Execution and delivery details¶
How execution works explains graph execution.
Process cleanup¶
When a run closes, zeroshot atomically closes its execution activity; a late process cannot appear after the terminal result.
On Linux, each local command has a private supervisor that also owns descendants which detach with
setsid, change process group, or double-fork. It stops and reaps them when the command finishes,
the run cancels, or the controller dies. Workspace ownership remains held through cleanup, so a
successor cannot resume while that command's descendants can still write. This uses the kernel's
subreaper support and procfs; it needs no root access or cgroup setup. Windows uses Job Objects.
macOS retains process-group cleanup; descendants that detach can outlive the command there.
On Linux and macOS, SIGTERM requests a cooperative stop of a detached local controller. It
cancels owned work, confirms cleanup and records the existing force_stopped terminal result
before exiting. An already recorded terminal result is preserved, and a run that already
suspended stays suspended. The workspace and checkpoints
remain available for zeroshot resume; explicit zeroshot force-stop keeps its checkpoint
discard behavior. Closing the invoking terminal still leaves a detached run running.
The controller allows up to 30 seconds from its first termination request for shutdown, including
startup, cleanup and terminal persistence. Repeated signals do not extend that deadline. An earlier
OS grace deadline, SIGKILL, OOM or unavailable storage can prevent cleanup or a terminal record;
later recovery reports an unrecorded controller loss as runtime_lost.
On Windows, detached controllers retain their Ctrl-C and Ctrl-Break protections. They install no
handler for console close, logoff or system shutdown events, which can terminate them without
cleanup or a terminal record. Use zeroshot force-stop for a cooperative stop on Windows.
Peer-message delivery¶
Declared graph networks let authorized local agent executions
publish through zeroshot steer --network NAME. The host authenticates the execution capability,
checks its publisher permission and assigns the origin. Public execution labels do not authorize
a message. Receivers need membership in a selected network; repeated destinations or overlapping
memberships do not multiply delivery.
A peer message reaches a recipient through its next prompt or at its next tool call. Future recipients receive it once they start. Publication creates no execution and does not interrupt, restart or wake a recipient. It also keeps suspended runs suspended. The originating node instance never receives that message, while other mapped copies of its logical node remain eligible members.
Network messages default to once, with receipt tracking by recipient node instance across
retries, fresh conversations and successors. standing tracks each provider conversation; a
continued conversation retains messages kept in its saved session and a fresh conversation receives
them again. At a tool call a message arrives as a user message of its own on Claude Code, Copilot,
Pi and OpenCode and with the hook context on Codex; a conversation that holds a message is not
given it again in either mode. Both modes preserve sender exclusion. Human broadcast steering keeps its standing default
and instruction precedence. Peer messages remain attributed context under authored instructions.
The existing vector ledger owns messages and receipts. A tool-call receipt is recorded when the harness shows the message in the conversation, or on Codex when its hook has returned. Once prompt delivery records a receipt after successful provider completion. Standing prompt receipts are recorded at preparation and remain provisional until successful completion. Receipts do not prove model compliance. A missing acknowledgement leaves delivery pending and can cause a repeat.
Auto-research¶
auto-research runs ten iterations by default. Optional run input options.iterations selects a
positive count bound at admission, subject to the engine's general execution and loop budgets.
Each normal round has five model executions:
- Three independent read-only scouts propose exploration, synthesis, and challenge directions.
- One researcher selects the parent and experiment, verifies/restores candidate bytes, runs the experiment, and prepares a supported retained result with compact evidence.
- A fresh read-only reviewer accepts the proposed disposition, requests concrete corrections, or approves a justified early stop. A supported non-adoption can be accepted without replacing the incumbent. Plateau alone does not justify stopping before the requested count.
The scouts and researcher keep separate continuing sessions by default; the reviewer starts fresh. Required corrections return to the same researcher without repeating scouting or consuming another research round, then receive fresh review. This work/review cycle has a 64-pass safety limit. Routine file, tool, or archive errors can be repaired by the researcher. Missing optional historical archives and cosmetic bookkeeping issues are advisory when the current result and retained state are supported. Native reviewer outcomes establish approval; no separate file audit counter is required. There are no bootstrap, staging, finalization, or extra audit model passes.
Records live under .zeroshot/research at the shared workspace root, including for tasks in
subdirectories. The researcher keeps the charter, current summary, backlog, round evidence, and
restorable candidate source there. After two accepted non-adoptions, or diminishing returns across
max(1, ceil(iterationLimit / 10)) accepted rounds on one approach, it explicitly reconsiders a new
mechanism, an archived parent, and a discriminating measurement. These are reasoned alternatives,
not a mandatory parent switch or a fixed gain threshold.
The template supports local results and --push. With --push, the reviewer supplies title and
description and one trusted Git delivery node publishes each accepted round. Research agents never
use Git. Exhausted review, unrecovered execution errors, delivery errors, and delivery repair
requests stop the run explicitly; unreviewed work is never published. Existing saved profiles and
admitted runs keep their stored graph and runtime.
Delivery feedback¶
PR and merge delivery consider feedback by default. Use --no-pr-feedback to ignore PR discussion;
the git_delivery binding describes the runtime
setting.
Automatic repairs accept feedback only from current writers on the target repository. GitHub
confirms effective write or admin permission for issue comments, submitted reviews (including
unwritten change requests), inline comments and replies. GitLab confirms active Developer-or-higher
project membership, including inherited and invited membership, for discussion notes. The account
must be active. Enterprise Edition also requires active membership_state; awaiting membership is
ignored. Community Edition omits that field, so its response is accepted only after instance metadata
confirms the edition. Unknown or malformed membership status fails the feedback read. Permissions
are checked again on each inspection and bound to the author's stable numeric identity. Organization
association, PR authorship, requested-reviewer status and bot status grant no exception. Confirmed
read-only access or nonmembership is ignored and does not start another worker/reviewer round.
Failed or incomplete permission lookups stop delivery or use its existing retry handling.