docs(lifecycle): define background ownership, isolation, cancellation, settlement, and delivery

Executive conclusion

OpenPI does not need one shared producer state machine or a second orchestration runtime.

Direct Subagent, Workflow, and Background Terminal deliberately have different owners, persistence, cancellation and recovery semantics. The missing artifact is a documentation contract that separates:

admission
→ execution and progress
→ cancellation / timeout
→ terminal snapshot
→ artifact commit
→ cleanup provenance
→ completion transport
→ model consumption
→ UI projection

A state in one plane must never be used as proof for another.

Five independent fixed-source workstreams completed without failure, followed by synthesis and an adversarial verification pass.

Baselines:

• OpenPI 2a69d3f32994da4123f1312b7fa84ef3d6119be1
• installed Pi @earendil-works/pi-coding-agent@0.84.3
• Codex a9e447a69dee4f2789dd8d8c776e314772c1f049
• Hermes cbd8de8ad64530be01efea23b7764d5c37c634ed
• Grok Build c2ad97f87aea4303b6000a2c22128bc91ee76c9b
• Gemini CLI 812f7a2bcf20b6e80e2e50c3c8fa8e26567bc1e8
• OpenCode 8615731d46153dd29b89e205fb55b2cc16205cb0
• Claude Code: official rolling documentation only; private runtime details remain unknown.

Runtime provenance

This is a fixed-source audit, not a diagnosis of the currently loaded runtime.

Verified while preparing this Issue:

source checkout: /Users/tushaokun/work/my-pi-setup
checkout HEAD:    2a69d3f32994da4123f1312b7fa84ef3d6119be1
checkout branch:  main
pi list source:   /Users/tushaokun/work/openpi-main-runtime
OpenPI sources:   exactly one

The source-audit checkout differs from the loaded OpenPI source. No statement below proves the behavior of a live TUI, provider request or installed extension instance without a separate reload/smoke chain.

Evidence contract: README — 开发运行时：区分 npm 与当前源码.

1. Vocabulary

Execution plane

• requested: caller expressed intent; no capacity or child exists yet.
• reserved/admitted: runtime capacity was synchronously claimed.
• queued: accepted but waiting for a semaphore/resource.
• starting: child/session/process creation or resource binding is incomplete.
• running: execution owner exists; does not imply model-visible progress.
• model progress: thinking/text/tool-call/assistant event visible through the Pi event seam.
• tool progress: a tool is executing or returned; not model completion.
• cancellation requested: abort intent was recorded; external effects may continue.
• aborting: owner is attempting cooperative cancellation/termination.
• terminal snapshot: process-local state guard selected one terminal classification.
• uncertain: terminal outcome or side effects cannot be proven.

Persistence and cleanup planes

• artifact committed: declared bytes are readable; independent from execution success.
• cleanup complete: owned resources were reclaimed with evidence.
• cleanup partial/unknown: timeout, owner loss or preservation policy prevented proof.
• owner lost: persisted state exists but the process/session/controller that could advance it is gone.

Delivery plane

• pending: a completion envelope awaits transport.
• held for inline: a live synchronous waiter currently owns delivery.
• transport accepted: pi.sendMessage/equivalent returned successfully.
• receipt persisted: sender durably recorded transport acceptance.
• consumed inline: synchronous tool caller received the result.
• model consumed: a later model invocation included the message; distinct and generally not proven by send acceptance.
• operator rendered: UI displayed a projection; not model consumption.

Identity

• run/child/process ID: execution identity within its owner.
• delivery ID: deduplication identity for completion transport.
• Session ID: Pi Session identity.
• generation/epoch: a fence that prevents late events from an earlier owner incarnation.

OpenPI does not currently have a general (sessionId, owner, epoch) fence across all producers. That is a proposed #160 vocabulary, not present fact.

2. Canonical ownership

Pi Session

Pi owns the parent Session lifetime, JSONL transcript, provider/model calls, extension hooks, session_start/session_shutdown, resume/fork/new behavior and message injection.

Direct Subagent manager/backend

The manager owns process-local child registry, pool slots, snapshot and delivery map. The Pi backend owns the in-process child AgentSession, event bridge and child resources.

Workflow coordinator/controller

Workflow owns run ID, sandbox, invocation ledger, controller/semaphore, child Sessions, artifacts, replay journal, terminal details and durable delivery state.

Background Terminal manager

The terminal manager owns child process/process-group identity, stdout/stderr capture, spill files, timeout, kill sequence, snapshot and process-local completion map.

UI

Footer, strip, dashboard, transcript viewport, status cards and spinners are projections only. They never own scheduling, terminalization, cleanup or consumption.

3. Direct Subagent contract

3.1 Admission and execution

Direct Subagent uses synchronous reservation before yielding:

• ordinary model children: maximum 4;
• by-the-way children: maximum 2;
• tracked entries: bounded separately.

The manager entry is represented as running before every startup substage is observable. There is no durable admitted, queued or starting record.

The backend creates an in-process Pi child Session with fresh resources/settings/extensions and a child-specific tool surface. Progress comes from assistant deltas, tool start/update/end, queue changes, message end and usage events.

Evidence:

• manager reservation and lifecycle
• Pi backend
• child-session policy.

3.2 Terminal classification

Backend outcomes are:

Completed(finalText)
Failed(errorText, partialText?)
Interrupted(partialText?)

The external snapshot collapses these to running | done | error; Interrupted is not independently represented as a top-level snapshot state.

The backend and manager both have settlement guards. These provide process-local idempotence for their own state transitions. They do not prove exactly-once provider execution, tool side effects, cleanup, or delivery.

Terminal evidence includes:

• Pi agent_settled and the final assistant stop reason;
• prompt rejection/provider error;
• unexpected backend event-stream end;
• first-response watchdog failure;
• explicit interruption.

3.3 Cancellation, timeout and late effects

Cancel marks delivery consumed, clears queued input and calls child abort. If cooperative abort exceeds the deadline, the manager records Interrupted and force-disposes the scope.

This is a bounded local settlement policy—not proof that every provider request, process, third-party extension or external side effect stopped at the same instant. Detached cleanup can continue after the snapshot is settled, and late effects remain possible when an owner does not cooperate.

Direct Subagent has a first-response watchdog. It does not provide a general watchdog for every later provider turn; lifecycle coverage belongs to #176 and the broader no-progress concern aligns with #171.

3.4 Delivery and restart

subagent_spawn is always detached. It immediately returns an ID. subagent_wait is an explicit synchronization/consumption tool; its interruption does not create durable execution recovery.

Automatic completion and explicit wait race through an in-memory pending map; the first successful consumer wins. A send failure can restore the batch while the process remains alive.

No stable durable receipt survives process/Session shutdown. A Pi child Session file may remain visible to /resume, but OpenPI does not reconstruct the manager entry, execution ownership or pending delivery from it.

Evidence: Direct result delivery.

4. Workflow contract

4.1 Separate intent, admission and execution

Workflow records three axes:

intent:     requested
admission:  pending → claimed | replayed | rejected
execution:  pending → running → settled | uncertain

A replayed invocation does not start a child. A rejected invocation did not execute. A persisted nonterminal invocation whose owner is lost becomes uncertain, not automatically failed, succeeded or retried.

The controller owns total-call budget, per-run concurrency, semaphore queue, abort propagation and bounded settlement.

Evidence:

• invocation ledger
• controller.

4.2 Startup and progress gaps

Workflow child Session creation and extension binding occur before the effective running-phase abort listener can interrupt them. A late aborted check prevents prompting once startup returns, but genuinely hung startup work can outlive the controller settlement deadline. #116 owns this gap.

The first-response watchdog covers initial assistant progress only. Later provider turns can remain without model-visible progress indefinitely; #171 owns the model-progress watchdog gap.

Do not describe either watchdog as a complete per-request deadline.

4.3 Cancellation and forced settlement

workflow_stop and Session shutdown abort the controller and child work. wait:true cancellation only releases the synchronous waiter; it does not own or cancel the run.

After a bounded shutdown barrier, Workflow may force-settle. This selects a conservative terminal record, but cannot prove all children stopped or all external effects ceased. Late tasks may still complete or produce effects; they must not be allowed to overwrite the selected terminal state.

Cleanup can continue after forced settlement. #114 documents a race where cleanup itself may execute while final cleanup provenance is skipped. Therefore “settled” must never imply “cleanup proven.”

4.4 Artifacts and terminal state

Workflow persists run artifacts and terminal details, but each file’s atomic replacement is not an atomic commit of the terminal artifact set. #110 owns that crash window.

A run’s terminal status, invocation records, artifact completeness, worktree cleanup and completion delivery are independent evidence planes.

Run-relative resultArtifact paths are provenance. Opaque resultRef values are stored in an in-memory same-run registry; persisting a ref string does not make it resolvable after restart.

4.5 Launch modes

Workflow alone has host-dependent default launch policy:

• interactive host with later-delivery support: detached by default;
• print/RPC/automation without reliable later delivery: inline by default;
• wait:true: explicit inline synchronization;
• deprecated compatibility aliases do not define the canonical contract.

#74 owns this product behavior. It must not be generalized to Direct Subagent or Background Terminal.

4.6 Durable delivery semantics

Workflow maintains stable per-run delivery identity and persists pending/held/accepted state. Restart converts a lost inline waiter to pending delivery and can retry.

Its at-least-once property means:

• if transport acceptance succeeds but receipt persistence fails, the same stable delivery ID may be transported again;
• duplicate transport is possible;
• consumer deduplication requires the stable ID;
• delivered in current state means synchronous pi.sendMessage returned and that outcome was recorded;
• it does not prove the provider saw the message, a model turn included it, the model attended to it, or a human rendered it.

#71 owns terminal persistence/delivery inconsistency; #160 owns any shared completion-inbox contract.

Evidence: Workflow result delivery.

5. Background Terminal contract

5.1 Admission and process ownership

Background Terminal always starts detached and has no generic synchronization wait equivalent to subagent_wait or Workflow wait:true. Status/watch tools observe bounded output and state; they do not take run ownership.

Admission uses synchronous reservation with a local maximum. The manager spawns a native child process, uses a POSIX process group where available, ignores stdin, and separately captures stdout/stderr.

5.2 Settlement and cancellation

The manager distinguishes successful zero exit, nonzero/spawn failure, killed and timed-out outcomes. It waits for stream/process close and spill flushing before normal settlement.

Cancellation attempts process-tree SIGTERM, then SIGKILL. Process groups improve descendant termination on supported platforms; they are not a filesystem, network, environment or container sandbox.

A state guard prevents duplicate process-local settlement. It cannot prove arbitrary grandchildren, remote work or side effects stopped.

5.3 Delivery and restart

Completion delivery uses a separate in-memory map. Idle completion can use followUp plus triggerTurn; a busy parent can receive nextTurn. Send failure restores the batch only while the process remains alive.

Session shutdown kills owned terminals, clears pending results and removes temporary spill state. Terminals and completion envelopes are not resumed after /new, /resume, /fork, /reload or process restart.

Evidence:

• Terminal manager
• Terminal result delivery.

6. Isolation and authority

Child Pi Session isolation

Children have independent model context and Pi Session identity. OpenPI package tools are fail-closed classified at the child boundary, role profiles can narrow capabilities, recursion is denied, and alternate-cwd Trust must resolve safely.

This is capability/context isolation, not operating-system isolation.

The fail-closed drift guard classifies OpenPI package-owned tools. It does not prove arbitrary third-party extensions safe merely because they are present in a child resource loader. Third-party extension permissions and side effects retain their own authority boundary.

Worktree isolation

A Git worktree isolates checkout/index/branch state. It does not isolate:

• process or user identity;
• environment variables or credentials;
• network;
• shared .git metadata;
• global package/cache/config state;
• dependencies outside the worktree;
• arbitrary absolute-path filesystem access.

Worktree cleanup is provenance-sensitive and fail-closed toward preserving uncertain/dirty state, but cleanup evidence remains separate from execution success.

Terminal isolation

A process group improves kill-tree behavior. It is not a sandbox, permission boundary or durable owner.

Authority invariant

Receiving a child ID, run ID, result ref, artifact path or completion envelope must never widen the receiving Session’s tools, Trust, filesystem access or provider credentials.

7. Session transitions and owner loss

Do not describe /new, /fork, /resume, /reload and process restart as one event.

• /new: starts a new parent Pi Session; old process-local producer ownership is shut down.
• /resume: hydrates Pi Session history into a fresh runtime; it does not rejoin old in-memory children or terminals.
• /fork: creates a new Pi Session branch/snapshot; it does not transfer live execution ownership.
• /reload: reloads extensions/resources in the current host lifecycle; package managers must dispose old owners and must not accept stale late events as new-run progress.
• process restart: removes every process-local owner.

Workflow can reconstruct same-Session persisted artifacts, classify stale running as uncertain, and restore pending delivery. It does not resume old child execution. Direct Subagent and Terminal do not have equivalent durable owner recovery.

A general epoch fence across producer types does not exist. #160 should define owner/session/generation only if implementation evidence proves it can prevent stale delivery without replacing producer identities.

8. Terminal, artifact, cleanup and delivery receipts

One boolean ok is insufficient. Documentation should keep at least:

executionStatus
executionOwnerLive
artifactStatus
cleanupStatus
deliveryTransportStatus
deliveryReceiptStatus
modelConsumptionStatus
operatorProjectionStatus

Examples:

• child completed, artifact failed, cleanup succeeded, delivery pending;
• Workflow forced-settled uncertain, cleanup still running, delivery accepted;
• Terminal timed out, kill attempted, process close unproven, partial spill retained;
• transport accepted, receipt write failed, duplicate delivery possible;
• UI rendered a completion that no later model request consumed.

“Exactly once” must be avoided unless its scope is explicit:

• process-local terminal-state guard: at-most-once state selection;
• Workflow transport: at-least-once with stable ID;
• Direct/Terminal pending maps: process-local first-consumer semantics;
• external side effects: not exactly once;
• model consumption: generally unknown.

9. Cross-system comparison

Codex

At a9e447a, Codex subagents are independent Threads/Sessions under one in-process AgentControl. Admission uses capacity/residency/spawn slots. Thread creation and first submitted turn are separate stages.

Status is derived from turn events. Interrupted is not necessarily a final closed Thread. wait timeout returns without cancelling the child. close is distinct from interrupt and flushes/materializes rollout before shutdown.

Completion watchers can inject a notification into the live parent. In the inspected source, a missing parent or ignored send failure does not have a Workflow-style durable completion outbox/receipt. Thread/rollout persistence can preserve conversation evidence without proving that a parent consumed completion.

Child Threads can inherit environment and execution policy and share the same filesystem/process authority; a Thread is not a filesystem sandbox.

Sources:

• Codex subagents documentation
• fixed multi-agent tools
• fixed Agent control.

Claude Code

Official rolling documentation establishes independent subagent context, configurable tools/permissions, background execution surfaces, Agent view, hooks/notifications, and worktree options.

It does not publish enough internal evidence to claim:

• exact admission/starting state;
• globally at-most-once terminalization;
• provider abort completion ordering;
• durable at-least-once completion delivery;
• consumer acknowledgement semantics;
• crash-atomic terminal/artifact/receipt commit;
• exact late-event fencing or retention implementation.

A product UI saying “completed” or a notification hook firing does not prove model consumption.

Sources:

• https://code.claude.com/docs/en/sub-agents
• https://code.claude.com/docs/en/agent-view
• https://code.claude.com/docs/en/hooks
• https://code.claude.com/docs/en/permissions

Hermes

Hermes documents richer asynchronous delegation states, including pending/starting/running, cancellation requested/cancelled and unknown. It also has durable database fields for result/delivery attempts/owner process.

However, important implementation modules referenced by the pinned checkout were absent from the inspected tree. The exact atomicity of delivery claims, late-event fencing and restart behavior therefore remains unknown rather than inferred from schema/docs.

Source: Hermes fixed tree.

Grok Build

Grok’s fixed source carries owner, parent Session/prompt and cancellation identity through child/workflow paths. Completion can be queued as a synthetic prompt and wake a parent, while cancellation barriers suppress stale wake after interruption. Persisted goal recovery resets in-flight activity because subagents do not survive restart.

The full task backend resides partly in an external dependency, so strict global at-most-once terminalization is not proven.

Source: Grok Build fixed tree.

Gemini CLI

The fixed Gemini source/docs establish subagents with independent context/tool configuration, recursion limits, headless result/exit-code surfaces and Session persistence. They do not establish a generic durable background completion inbox, exact cancellation/late-event ordering or cross-restart child execution recovery.

Source: Gemini CLI subagents.

OpenCode

OpenCode derives child permissions from parent restrictions, denies recursive task/todo behavior by default, and has durable Session parent/fork metadata. The fixed sparse source did not establish a universal background-job completion transport or its delivery guarantees.

Sources:

• child permission derivation
• Session state.

10. Relationship to existing Issues

This Issue owns documentation only:

• #159 owns package-wide admission leases/resource limits.
• #160 owns a thin completion inbox with owner routing, generation/epoch, deduplication receipt and wake policy.
• #71 owns Workflow terminal persistence/delivery inconsistency.
• #74 owns interactive Workflow detach/inline defaults.
• #116 owns unabortable Workflow child startup.
• #171 owns later-turn model no-progress watchdogs.
• #110 owns terminal artifact-set atomicity.
• #114 owns forced-settlement cleanup-provenance loss.
• #173 and #174 own Workflow/Subagent terminal UI projections.
• #176 owns Direct Subagent production-adapter lifecycle coverage.
• #193 owns Pi Session and Workflow replay semantics.

No producer lifecycle implementation moves into this Issue.

11. Minimal Pi-native recommendation

1. Publish this terminology and the three separate lifecycle tables.
2. Fix only through the existing owner Issues and owner modules.
3. Let runtime: 建立跨 Subagent、Workflow 与 Background Terminal 的总资源准入合同 #159 share admission facts without sharing execution state machines.
4. Let delivery: 统一后台完成事件的 owner 路由、epoch 与消费收据合同 #160 share envelope/receipt/wake invariants without owning producer terminal state.
5. Keep Workflow as the only durable run/outbox plane unless a concrete requirement proves otherwise.
6. Preserve Direct Subagent and Terminal’s simpler process-local lifecycle rather than adding durability by default.
7. Continue using Pi Session hooks and sendMessage; do not add a message broker.
8. Require every status/UI/test to name which plane it proves.

12. Non-goals

• No unified producer state machine.
• No second orchestration runtime, Agent OS, daemon or scheduler.
• No global job database.
• No durable Direct Subagent/Terminal execution resume.
• No exactly-once external side effects or delivery promise.
• No automatic retry of uncertain work.
• No epoch invented only in prompts or UI.
• No worktree represented as a sandbox.
• No child reference that widens authority.
• No forced foreground wait merely because a later step depends on a result.
• No polling loop as a substitute for event delivery.
• No inference of model consumption from transport or rendering.

13. Unknowns

• Whether the currently loaded runtime matches the fixed source behavior without reload/smoke verification.
• A general generation/epoch fence for Direct Subagent and Terminal; it does not currently exist.
• Whether all late provider/tool/extension side effects stop after force settlement.
• Exact child startup cancellation behavior when third-party resource hooks hang.
• Durable consumer acknowledgement beyond Workflow transport receipt.
• Crash atomicity across Workflow terminal state, artifacts and delivery receipt.
• Completion behavior when Pi host/provider shuts down between transport return and the next model turn.
• Third-party child extension capability classification and cleanup guarantees.
• Complete Windows process-tree termination behavior.
• Claude Code private delivery/receipt/restart semantics.
• Hermes missing implementation-module behavior at the pinned revision.
• Grok external task-backend terminalization.
• Gemini/OpenCode generic background completion delivery guarantees.

14. Acceptance criteria

• Documentation defines execution, persistence, cleanup, delivery, consumption and UI as separate planes.
• Direct Subagent, Workflow and Terminal each have their own exact state/lifecycle table.
• Direct Subagent and Terminal are documented as always detached; Workflow alone has host-dependent default inline/detached policy.
• subagent_wait, Workflow wait:true, workflow_stop and terminal status/watch are not conflated.
• Process-local state guards are not described as exactly-once execution, effects, cleanup or delivery.
• Startup cancellation and first-response/later-response watchdog gaps are documented under workflows: agent startup (session creation + extension binding) is not abortable #116/workflows: 后续模型回合可永久无进展，first-response watchdog 无法兜底 #171.
• Forced settlement is not proof that child work or external side effects stopped.
• Terminal status, artifact commit, cleanup provenance and delivery receipt are independently testable.
• Workflow delivered is defined as recorded synchronous transport acceptance—not model/human consumption.
• Workflow at-least-once transport and duplicate-delivery possibility are explicit.
• Direct/Terminal delivery maps are described as process-local and non-durable.
• Same-run in-memory resultRef is not described as restart-resolvable.
• /new, /resume, /fork, /reload and process restart are documented separately.
• Stale persisted Workflow running state restores as uncertain, never guessed success/failure.
• No general owner epoch is claimed to exist before delivery: 统一后台完成事件的 owner 路由、epoch 与消费收据合同 #160 implements and verifies one.
• Child Pi Session/tool isolation, worktree isolation and process-group behavior are not called OS sandboxes.
• OpenPI package-tool drift guard is not represented as third-party extension certification.
• IDs, artifact paths and completion envelopes never widen receiver authority.
• UI/model/operator projections are tested separately from canonical execution/delivery facts.
• Source checkout and pi list loaded runtime provenance are always separate.
• runtime: 建立跨 Subagent、Workflow 与 Background Terminal 的总资源准入合同 #159/delivery: 统一后台完成事件的 owner 路由、epoch 与消费收据合同 #160/Workflow：终态持久化失败与完成通知失败会留下不可恢复的不一致 #71/Workflow 默认应释放父 turn：与 Subagent 的后台生命周期合同对齐 #74/workflows: agent startup (session creation + extension binding) is not abortable #116/workflows: 后续模型回合可永久无进展，first-response watchdog 无法兜底 #171/workflows: terminal artifact set (result.json + workflow.json) is not committed atomically #110/workflows: forced settlement can skip persisting worktree cleanup metadata (provenance loss) #114/workflows: 精简完成态 UI，避免重复状态和诊断信息常驻 #173/subagents: 精简完成态主会话展示并隐藏 transport instruction #174/subagents: 为生产 Pi adapter 补齐生命周期集成覆盖 #176/docs(session): define lifecycle, recovery, replay, and side-effect boundaries #193 ownership remains intact.
• No shared producer machine, second runtime, global job store or message broker is introduced.