Skip to content

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:

  1. Three independent read-only scouts propose exploration, synthesis, and challenge directions.
  2. One researcher selects the parent and experiment, verifies/restores candidate bytes, runs the experiment, and prepares a supported retained result with compact evidence.
  3. 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.