@with-logic/elwood 0.1.2 → 0.2.0

package/prd/05-api/5.8-session-api.md

@@ -8,8 +8,8 @@ control surface (`sendMessage`, `sendPrompt`, `sendGuidance`, `sendKeys`, `resiz
 `cancelLoop`, `on`/`off`, `waitForStatus`, `waitForActivity`,
 `stop`/`kill`/`teardown`, and Claude's `login`). Every method is
 lazy-start-aware. The class is a thin wrapper over the same PTY-backed session the
-`start*` factories build — it adds no new lifecycle or persistence behavior and reads
-only public events. The `startClaude`/`startCodex` factories remain as the low-level
+`start*` factories build — it adds no new persistence behavior. Private submission
+and native-boundary evidence isolates collection without changing public hook payloads. The `startClaude`/`startCodex` factories remain as the low-level
 eager entry points but are DEPRECATED in favor of the class; they still return the
 same live session object (typed `ClaudeSessionApi`/`CodexSessionApi`) the class wraps.
 
@@ -34,6 +34,23 @@ with one another; control methods (`interrupt`, `sendKeys`, `createLoop`,
 `listLoops`, `cancelLoop`, `stop`, `kill`, …) go
 through immediately so an intervention reaches a running turn rather than queuing.
 
+**Image ownership.** Every image-bearing facade call snapshots bytes and absolute
+paths synchronously, before lazy startup or turn queueing, with the validation and
+200 MiB per-session clone ceiling from §5.3. That ceiling is ONE budget per
+session: the facade and the raw session it exposes through `session` reserve
+against the same 200 MiB, so mixing both surfaces cannot retain more than either
+alone. Raw facade submissions release their
+reservation when submission settles. Ergonomic `send`/`stream` turns retain their
+reservation until the real turn boundary, because acceptance recovery may replay
+the captured images. Consumer timeout or cancellation alone does not release it;
+closing or killing the session reaches the boundary. Pending copies and the serialized
+slot are released only after any cancelled acceptance-recovery submission finishes
+its initial or replay physical write and immediate cleanup; dialog-blocked draft cleanup remains
+owned by the input queue and must finish before a successor writes. Recovery stops when the consumer settles,
+on either success or failure. An earlier `ready` followed by replay `running` is not
+completion evidence for that replay; a failed consumer still waits for a new real
+`ready` or terminal boundary and the required transcript drain.
+
 **Turn boundary.** A "turn" begins when a `send`/`stream` submits its prompt and
 ends when its content is complete. A turn's assistant text is transcript-sourced
 (C-CLAUDE-15) and the transcript is written ASYNCHRONOUSLY, so the text can arrive
@@ -57,13 +74,27 @@ failure, not a quiet success). A terminal status ends the turn immediately (it i
 final). A turn may legitimately run for HOURS (running a test
 suite, polling a PR), so there is NO whole-turn timeout by default — a still-live turn
 is never failed by a clock; a caller may pass an OPT-IN `timeoutMs` whole-turn
-ceiling. The tight cap is `catchUpMs` (default 10000 ms), armed only ONCE `ready`
+ceiling, armed once at the first physical submitting Enter, without waiting for
+fresh-empty input confirmation. Both initial and replay ergonomic submissions retain
+input ownership until that confirmation or cancellation cleanup. The facade does not
+queue a whole-prompt replay while an awaited writer still owns native Enter recovery.
+A failure after Enter still waits for the real native boundary; a rejected submission
+that never reached Enter releases immediately. The tight cap is `catchUpMs` (default 10000 ms), armed only ONCE `ready`
 fires: the agent is done, so the transcript flush should be near-instant — if it
 stalls past `catchUpMs`, the turn rejects with `wait_timeout` rather than leaving the
 caller hanging. Turns
 are serialized: overlapping `send`/`stream` calls queue and run one at a time in call
 order, so a turn's activity never interleaves with another's. This serialization covers
-the ergonomic `send`/`stream` turns only. The raw turn-producing control methods
+the ergonomic `send`/`stream` turns and scheduled loop delivery: once its slot is
+reserved and the underlying session is available, an ergonomic turn holds due loop
+input until its real boundary,
+including acceptance recovery and post-failure transcript drain. A loop selected before that hold reserves its native boundary before preparation
+or physical submission; the caller waits for its completion and transcript drain
+BEFORE installing its collector. A loop merely queued behind the hold cannot
+prevent the caller's submission or recovery, or jump ahead of a successor caller
+whose serialized slot is already reserved. Startup persona input drains before
+caller collection by the same rule.
+The raw turn-producing control methods
 (`sendMessage`, `sendPrompt`, `sendGuidance`) submit immediately and are NOT part of
 the ergonomic turn queue, so calling one CONCURRENTLY with an in-flight `send`/`stream`
 turn is unsupported — its produced turn can interleave with the ergonomic turn's
@@ -79,8 +110,27 @@ reliable "turn done" signal: a real `ready` (a busy agent is `running`, not read
 terminal status, then a short transcript-drain settle. A hung agent holds the slot until
 `close()`/`kill()` forces a terminal status. The facade subscribes to `activity` BEFORE
 submitting so no early event of the turn is missed. Where the adapter tags activity with a
-`turnId` (Codex), the facade additionally binds collection to the first turn's id as a
-refinement; Claude transcript activity carries no `turnId`, so for Claude the
+`turnId` (Codex), the facade binds it only from an authenticated native
+`UserPromptSubmit` for its physically attempted submission. The adapter normalizes
+that acceptance and the submitted payload; prompt equality alone, replayed content,
+`running`, and a late `Stop` cannot establish identity. Before acceptance, tagged
+and untagged content cannot enter the collector. After acceptance, tagged content
+and the Stop completeness signal must match that identity; a prior Stop cannot
+replace its oracle. Untagged transcript records remain isolated by causal
+serialization and predecessor drain.
+A failed or interrupted consumer retains an unresolved attempted native boundary
+until trustworthy completion or terminal shutdown, rather than assigning the next
+unknown native generation to its successor. An earlier `ready` alone cannot
+complete a newly accepted generation. Completion can combine its own matching,
+unblocked Stop with a current positively empty, unblocked composer rendered from
+native output received after the owned Enter; a cached pre-Enter frame or a
+geometry-only change does not supply that evidence. Hookless completion may instead
+come from the existing classified native rendered end edge for the currently
+accepted generation, with post-Enter output progress and no input block. A raw
+`interrupt()` return or a generic status change is not that evidence.
+These rules also apply to headless CLI
+collection. They refine causal serialization rather than authenticate caller-owned
+configuration or unrelated host processes; Claude transcript activity carries no `turnId`, so for Claude the
 serialized-slot boundary is the sole isolation guarantee (which is why releasing the
 slot on the real agent boundary, not on consumer cancellation, is load-bearing).
 Because a turn has no default timeout, its buffered state is BOUNDED: the oracle
@@ -120,3 +170,5 @@ text-collection semantics are identical.
 **Teardown.** `close()` stops the underlying session (falling back to `kill` on a
 stop failure) and is a no-op if the session never started; it is the ergonomic
 counterpart to `stop`/`kill`/`teardown` and safe to call in a `finally`.
+
+Native question snapshots and answering are shared controls; see [§5.10](5.10-questions.md).

package/prd/05-api/5.9-loops.md

@@ -127,6 +127,14 @@ with no separate wall-clock delivery deadline. A candidate that settles before
 committing a turn releases the next due candidate immediately while readiness
 remains available.
 
+An ergonomic `send`/`stream` turn holds queued loop delivery once its serialized
+slot is reserved and the session is available, through its real boundary (§5.8),
+so a due loop cannot supply
+acceptance or completion evidence for a swallowed caller prompt. Caller controls
+and recovery submissions remain eligible ahead of held loops. Nested holds release
+independently; the final release resumes eligible due delivery, while shutdown or
+loop cancellation discards pending delivery under the existing rules.
+
 If the process stops or exits before a due prompt is submitted, its transient
 due state is discarded and its definition becomes `waiting` for resume. A live
 scheduling or submission failure emits a `failed` loop event and rearms the
@@ -141,7 +149,9 @@ If the loop already committed its prompt, cancellation does not interrupt that
 active agent turn. An unknown, expired, cancelled, or otherwise finished ID
 fails with `loop_not_found` and cannot affect another loop. `listLoops` and
 `cancelLoop` remain available on stopped or exited raw sessions; `createLoop`
-does not. The lazy wrappers apply the existing lazy-start behavior to all three
+does not. Once a successful same-process resume supersedes a raw session, its
+`createLoop` and `cancelLoop` reject with `session_not_running`; they cannot report
+a durable change that the successor did not receive. The lazy wrappers apply the existing lazy-start behavior to all three
 methods when no underlying session exists yet.
 
 The `loop` event is live-only and follows the union above. `created` carries a

package/prd/05-api/README.md

@@ -17,3 +17,5 @@ concepts in this section, including the stable `ElwoodErrorName` union.
 - [5.7 CodexSessionApi (the raw live session)](5.7-codex-session-api.md)
 - [5.8 The session API — `ClaudeSession` / `CodexSession`](5.8-session-api.md)
 - [5.9 Recurring session loops](5.9-loops.md)
+
+- [5.10 Native questions](5.10-questions.md)

package/prd/06-claude-hook-bridge.md

@@ -39,6 +39,17 @@ If a future Claude version adds events, the MVP may reject them as invalid hook
 input and fail open until first-class types are added. Elwood should add an
 unknown-but-safe event path before promising forward-compatible hook handling.
 
+`StopFailure` identifies a rejected Claude turn even when diagnostic fields drift.
+After validating the common hook envelope, ingress MUST admit missing or arbitrarily
+shaped `error`, `error_details`, and `last_assistant_message` fields. Their public
+TypeScript types are optional `unknown`; consumers must narrow them before use.
+Other event schemas retain their existing validation.
+
+Human-readable rejection diagnostics prefer a nonblank string `error_details`, then
+`Claude rejected the turn: <error>` for a nonblank string `error`, and otherwise
+`Claude rejected the turn.`. Each diagnostic field is bounded to 2,000 characters
+plus an ellipsis before interpolation. Assistant text is not a rejection reason.
+
 ### 6.2 Routing
 
 Each launched Claude process receives an Elwood session identifier in its
@@ -71,6 +82,31 @@ If a handler times out, throws, rejects, disconnects, or returns an invalid
 runtime value, Elwood returns no decision to Claude and emits `hookError` to the
 parent app.
 
+When a `Stop` result is finalized (normal completion, timeout, or other fail-open),
+its registered handler and hook-scoped observers of `hook`, `activity`,
+`hookError`/`hook_error`, and `hook_observer_failed` diagnostics lose authority
+in continuations that preserve their asynchronous execution context to admit new
+queue-backed input to that same live session. Promise continuations and async work
+created within the callback carry this boundary. Registering a callback on a
+pre-existing event source does not bind that source to the Stop context; input
+from its later independently dispatched callbacks is treated as unrelated caller
+input.
+Later `sendPrompt`, `sendMessage`, or `sendGuidance` calls from that context reject with
+`wait_timeout` before image capture, attachment, or queue admission, including the
+lazy session facade. The boundary identifies the live runtime instance, so another
+adapter or state directory may reuse the same Elwood ID without sharing authority.
+Already admitted input remains valid; the bridge does not wait for unawaited observers
+or timed-out user code. Unrelated caller contexts, other sessions, non-Stop hooks,
+raw keys, and independent non-turn controls are unaffected. Internal queue
+notifications, loop scheduling and settlement, and persistent transcript polling
+do not inherit this authority. This includes queue admission, cancellation, wakeup,
+dispatch, and settlement for non-turn controls such as compaction and model
+selection. A caller registering a Promise continuation on one of these controls
+inside Stop still carries the original Stop boundary; internal detachment does
+not renew that caller’s authority. Recognized malformed Stop bridge diagnostics
+use the same exact live-instance boundary and close when synchronous diagnostic
+delivery returns; asynchronous diagnostic continuations cannot admit late input.
+
 Fail-open does not mean silent. `hookError` must include:
 
 - `elwoodSessionId`
@@ -108,6 +144,38 @@ a `hookError`, matching the token-mismatch fail-open.
 
 ### 6.4 Typed hook responses
 
+Observational listener failures must not prevent Claude hook dispatch, replace a
+validated wire response or blocking decision, or skip readiness and Stop bookkeeping.
+Hook, activity, hook-error, transcript, and lifecycle notifications are isolated at
+the hook boundary. Each invocation emits at most one content-free
+`hook_observer_failed` warning (§5.7), identifying the first failed phase; warning
+observer failures are contained without recursive diagnostics (C-HOOK-22).
+Returned native observer Promises are observed through the captured intrinsic
+`Promise.prototype.then`, without awaiting them or reading an instance's own `then`.
+Their rejections are contained even after the hook reply completes when their
+constructor and `Symbol.species` support normal ECMAScript reaction attachment.
+Listeners run in the host process, not a sandbox: nonreturning synchronous listener
+code or Promise metadata can block the host. A constructor/species that prevents
+native attachment leaves its rejection handling with the caller. An attachment
+throw is reported as a notification failure, without caching an unattached Promise;
+a subsequent notification retries attachment. Elwood neither mutates caller Promise
+metadata nor opens a debugger session to bypass it. The first observed failure
+selects the diagnostic phase, and late failures do not emit additional warnings.
+Diagnostic retention is limited to the newest 1,024 pending observer registrations
+per session emitter. When this cap is exceeded, the oldest registration is detached
+from its invocation boundary; its eventual rejection is still consumed but no
+longer produces a diagnostic. Repeated returns of the same pending Promise share
+one rejection handler. Settled registrations are released immediately. Diagnostic
+warnings are frozen before delivery, and their activity projection is captured
+before any warning listener runs.
+Within a hook notification scope, synchronous listener failures are captured at
+each emission, so later derived status activity and committed transcript records
+are still delivered. Outside this scope, ordinary synchronous emission retains
+its existing throw-after-fan-out behavior. A hook-scoped ready-status listener
+failure reports `hook_observer_failed`; because the ready transition completes, it
+does not also report `initial_ready_fallback`. C-API-42 still applies to a transition
+that actually throws outside the notification boundary.
+
 Elwood MUST model Claude hook inputs and outputs as discriminated TypeScript
 unions.
 
@@ -118,6 +186,53 @@ unions.
 - Unknown future tools and MCP tools may use `Record<string, unknown>` or
   `unknown` with a safe raw tool name.
 - Hook bridge JSON must be runtime-validated before it reaches handlers.
+  The normalized, bridge-owned JSON event is deeply frozen before any observation
+  or handler dispatch. Hook observers and activity raw payloads cannot mutate
+  routing, tool inputs, response validation, or readiness/Stop bookkeeping.
+  Freezing introduces no additional input depth or size limit beyond the bridge
+  request contract.
+- A numeric field MUST be a finite number. `NaN` and `±Infinity` are rejected at
+  ingress and in `updatedInput` rewrites, because JSON has no encoding for them
+  and `JSON.stringify` would put a `null` on the wire where the CLI's schema
+  requires a number. This applies to EVERY tool: schema-less inputs (MCP, generic,
+  and future tools) have no field table, so the rule is enforced structurally over
+  the whole value, including nested records and arrays. Traversal allows at most
+  128 edges from the input root and 100,000 value visits, counting the root,
+  primitives, and every occurrence of a shared child. Ancestor cycles are invalid;
+  repeated children on separate paths are valid within these limits. Cyclic or
+  over-limit shapes fail validation without throwing. Invalid rewrites produce the
+  existing `invalid_response` hook error and a bridge response with no decision.
+  Structural values must consist of null, strings, booleans, finite numbers,
+  arrays, and plain records (including null-prototype records). Undefined values
+  retain JavaScript JSON omission/null semantics. Bigints, functions, symbols,
+  boxed primitives, proxies, custom prototypes, callable `toJSON` hooks, and
+  enumerable accessor properties are invalid. Other non-enumerable fields are
+  ignored; validation does not invoke getters or custom serializers. Each
+  child's budget is checked before reading its property descriptor. The complete
+  response envelope independently obeys the snapshot limits below.
+- Before result validation, Claude handler responses are copied into detached data.
+  Validation and wire serialization use that same snapshot, so later handler mutation
+  cannot replace a validated rewrite. Wire output and blocking decisions are captured
+  before result activity observers run. Only genuine Promises are awaited; direct
+  response-shaped thenables are validated as data without invoking `then`. Snapshotting reads only own enumerable data
+  properties, never invokes accessors or serializers, and rejects proxies, boxed
+  primitives, non-finite numbers, bigints, functions, symbols, custom prototypes,
+  and cycles. Null-prototype records are valid. Non-callable `toJSON` data fields
+  are ordinary data; callable or accessor-backed serializers are invalid even when
+  non-enumerable. Other non-enumerable properties are ignored as they are by JSON.
+  Undefined values and array holes retain JSON omission/null semantics. Responses
+  are limited to 128 edges on each root-to-leaf path (the root is depth zero) and
+  100,000 value visits, counting the root, undefined values, array holes, and
+  repeated occurrences of shared children. Invalid snapshots yield `invalid_response`
+  and no bridge decision (C-HOOK-21). Claude response wrappers across async dispatch
+  and the socket reply envelope do not inherit `then` or `toJSON` behavior.
+
+Task and plan inputs follow Claude's documented native field names: `TaskGet`
+uses `taskId`; `TaskOutput` uses `task_id`, `block`, and `timeout`; `TaskStop`
+accepts optional `task_id` and the deprecated `shell_id`. `CronDelete` uses `id`.
+`ExitPlanMode.allowedPrompts` contains `{ tool: "Bash", prompt: string }` objects,
+not strings. These shapes apply to both ingress and partial input rewrites.
+See the [Claude tool reference](https://code.claude.com/docs/en/agent-sdk/typescript#tool-input-types).
 
 Invalid states should be unrepresentable where TypeScript can enforce that. For
 example, a `Notification` handler should not be able to return a blocking

package/prd/07-claude-policy.md

@@ -13,3 +13,5 @@ complementary:
 `AskUserQuestion` is explicitly in scope. Elwood must type it and allow a
 `PreToolUse` handler to answer it programmatically by returning an allowed
 decision with updated input containing answers.
+
+Native unanswered `AskUserQuestion` dialogs also support the live question controls in §5.10. Caller hook decisions retain precedence; Elwood does not extend the hook deadline to await a host answer.

package/prd/07a-codex-hook-bridge.md

@@ -46,6 +46,31 @@ unions.
 - Observe-only or unsupported response states must be rejected by the type system
   and runtime validation. Parent handlers must return `undefined` for no
   decision; an empty object is invalid and must fail open with `hookError`.
+- Tool-keyed lookup, for both the exact tool name and the `unknown` fallback, MUST
+  consider only OWN properties of the handler map. A tool name that merely matches an
+  inherited member resolves to no handler, so a CLI-supplied name cannot reach a
+  function the caller never registered for it.
+
+The validated Codex hook event, including nested tool input, is frozen before
+parent observation or handler routing. A handler response is detached before
+validation, so later mutation of the handler-owned value cannot change it.
+Elwood fixes the validated wire reply and Stop blocking decision before result
+activity observers run. Observer mutation cannot change policy input, the native
+reply, or Stop readiness. Invalid response data fails open with `hookError`
+(C-HOOK-23).
+
+Observational hook, activity, hook-error, transcript, and lifecycle listener
+failures must not replace Codex hook decisions or skip turn bookkeeping. Each
+hook invocation reports at most one bounded, content-free `hook_observer_failed`
+warning for its first failed phase. Returned native observer Promise rejections
+are consumed without delaying the hook reply; warning delivery failures do not
+recurse (C-HOOK-22). The same boundary covers bridge error notifications.
+The one-shot initial-ready transition retains its separate C-API-42 fallback
+warning and queue-release guarantee for synchronous listener throws. Returned
+status/activity observer Promise rejections share the enclosing hook boundary
+when readiness fires within `SessionStart`; standalone resume-composer or deadline
+readiness instead reports `initial_ready_observer_failed`. Neither delays
+readiness or the hook reply.
 
 Decision note: Codex `PreToolUse` and `PermissionRequest` both produce
 event-specific JSON under `hookSpecificOutput`, but they do not use the same
@@ -74,3 +99,68 @@ Elwood must document this limitation and provide a live-only transcript
 observation event. The event may summarize transcript item kind, label, and text,
 and may include the raw item for immediate in-memory rendering. Elwood must not
 persist raw transcript items or derived prompt/tool content in Elwood state.
+
+Committed assistant commentary is normalized as `assistant_progress` under
+§5.4, separately from final `assistant_message` activity. The transcript summary
+uses `kind: "commentary"`, `label: "assistant"`, and readable `text` for the
+canonical response item, including array-form `output_text` content. Progress
+does not establish readiness or complete a caller's turn.
+
+The finalized-Stop input boundary in §6.3 also applies to Codex: late registered
+Stop-handler and hook-scoped observer continuations that preserve their async
+execution context cannot admit new queue-backed input to the same live runtime
+instance after the result is finalized.
+Independent callbacks dispatched by pre-existing event sources, internal queue
+and loop work, and persistent transcript polling remain outside that short-lived
+authority.
+
+### 7A.5 Native questions
+
+The shared question controls in §5.10 support current Codex `request_user_input`
+and `request_user_input_async` terminal editors. Committed function-call arguments
+provide complete metadata; a matching native editor or queued-question badge is
+required before publishing an actionable request. Rejected calls and historical
+transcript content never create requests. Mirrors retain the original identities.
+
+`request_user_input` publishes one grouped blocking request with ordered prompts,
+headers, choices and descriptions. The captured native tool requires nonempty
+choices, adds the real selectable `None of the above` option, and accepts optional
+notes alongside a selected choice. Elwood exposes that native option with its own
+opaque option ID; it may be chosen without notes. Text alone selects that native
+alternative and adds the text as notes. Elwood supports these pages through the native
+editor, preserving the group until the matching committed tool result confirms
+acceptance. Unsupported secret or changed layouts receive no speculative input.
+Every question must omit `isSecret` or set it to boolean `false`; `true` and
+malformed supplied values reject the complete native request before publication.
+
+Each asynchronous question is an independent queued request, with its own
+acceptance unit. Suggested choices use the first 32 native choices, then omit labels exceeding
+512 UTF-8 bytes without filling those gaps from later choices. Free text is
+available instead of a suggestion. Native question-bearing
+async messages remain question metadata even when their phase is `final_answer`;
+they never become final assistant activity. Answering opens the confirmed native
+editor and uses its question-answer route, preserving other pending questions.
+Ordinary composer submission must remain held because it clears queued questions.
+
+Committed native reply envelopes close matching queued requests as answered.
+Conclusive local removal closes them as unavailable when no answer is confirmed;
+live turn completion/interruption/failure also retires remaining requests. Badge
+redraws and countdowns do not invent an expiry deadline. Availability is live-only
+and independent of whether Codex continues working. A blocking modal contributes
+the existing blocked state; the queued editor does not manufacture a turn boundary.
+
+Question automation retains at most 256 pending native acceptance units and
+1 MiB of aggregate UTF-8 candidate metadata, including native identities and
+serialized question definitions. Each individual call is also limited to 256
+question definitions and 1 MiB of UTF-8 input metadata before normalization.
+Retired native identities are retained for replay suppression up to 4,096 keys
+and 1 MiB of UTF-8 key data. Exceeding any limit closes exposed requests as
+`unavailable`, clears retained candidate/identity state, and disables question
+automation for the remainder of that session; it never evicts a tombstone and
+then republishes an old request. Raw human input remains available. Ordinary
+input remains held for unknown native identities until explicit native turn end;
+raw human terminal input remains available. A matching supported editor can still
+publish recognized requests. One content-free `question_automation_disabled`
+warning and normalized warning activity diagnose budget disablement. Overflow does not
+invent an answer, expiry deadline, or turn boundary. Unchanged native redraws
+must not republish unchanged candidates or repeatedly copy the request registry.

package/prd/08-state.md

@@ -43,15 +43,53 @@ reused; the socket path is a per-launch runtime value, embedded only in the gene
 private bridge script and never in the session record, so a
 recorded socket path can never be trusted. `teardown` removes the whole socket
 home (every launch's socket) along with the session directory, so no per-launch
-socket can leak undiscoverably across restart/resume cycles. Because `teardown`
-removes the whole home, running two live sessions that share a full identity
-(`stateDir`, adapter, and session id) concurrently is UNSUPPORTED — they would
-also share the session directory, record file, and resume id, and one's teardown
-would remove the other's live socket. A given session identity has at most one
-live session at a time; a failed START (not a teardown) removes only its own
-socket file, so an overlapping failed launch never disturbs a live one. `stateDir`
+socket can leak undiscoverably across restart/resume cycles. Across separate Elwood
+processes, running two live sessions with the same full identity (`stateDir`,
+adapter, and session id) is unsupported: the processes share files and socket
+homes without a cross-process ownership protocol. Within one process, overlapping
+resume and cleanup follow the successor protocol below. A failed start removes
+only its own socket file, preserving any overlapping launch. `stateDir`
 length MUST NOT constrain whether a session can start.
 
+Within one Elwood process, a validated resume attempt revokes the prior launch's
+shared-state ownership before asynchronous preflight. A superseded launch may
+finish its own runtime cleanup, but cannot overwrite loop definitions or remove
+the shared session directory or socket home. Each loop persistence write and
+destructive path removal checks the current launch generation at the mutation itself,
+including after awaited shutdown work and on repeated shutdown calls. Until resume
+succeeds, the prior launch may continue ordinary loop and record persistence, but its shutdown
+cannot clear shared loops or files. Its `kill` or `teardown` still stops its own runtime,
+but waits for the pending reservation to settle before deciding shared cleanup: a
+committed successor keeps its state, while a failed successor permits the predecessor
+to finish the requested cleanup before its shutdown promise resolves. A pending
+successor does not activate loop timers. Successful activation rereads the latest
+durable loop definitions and revokes prior scheduling in the same synchronous commit,
+so a successful predecessor cancellation or creation is preserved. An activation
+read failure stops the built launch before ownership rolls back. If resume fails,
+ownership returns to the prior
+viable launch only when no newer reservation or launch has replaced that attempt.
+A failed overlapping launch therefore preserves the original live launch's cleanup
+and persistence behavior. This is an
+in-process successor guarantee, not cross-process launch serialization. Allowed root-owned filesystem
+aliases use one canonical, validated state identity for launch ownership, runtime
+paths, and socket homes; no-follow validation precedes canonicalization. Startup
+publication of session records is generation-owned. Bridge scripts and generated
+settings instead use fresh per-launch filenames permanently bound to that launch's
+PTY. Pending or committed successors never redirect a predecessor's hook policy. A failed
+attempt restores each prior file only while it still owns the reservation and the
+file still contains that attempt's exact published bytes. A newer predecessor
+record update or newer generation is preserved. If a predecessor updates a file
+between two pending-launch writes, that external version becomes the rollback
+baseline for the later write. Pending-launch hook record writes participate in the
+same transaction. Superseded or failed generations cannot publish metadata.
+A rollback failure is reported as
+`state_corrupt`, not as a successful restoration. Rollback attempts every independent
+file restoration, settles the failed reservation and restores the prior viable owner
+even when one restoration fails. Failed entries remain eligible for an exact-byte
+retry only while no newer generation has replaced that restored owner. Rollback
+unlinks are fsync-backed like other state changes. Identity-only CLI cleanup removes
+state only when no same-process live launch or pending reservation owns it.
+
 ### 8.2 Session record
 
 The schema-version-1 core session record persists only the minimum needed to
@@ -74,9 +112,10 @@ bridge scripts contain the fresh IPC token and socket path in owner-only files.
 Nothing else is persisted in the core record. In particular it MUST NOT persist session status,
 timestamps, warnings, terminal size, the hook bridge
 authentication token, the socket path, or any Elwood-owned runtime file paths.
-Status and warnings are live-only (§5.7). Runtime file paths are pure functions of
-the state directory, session id, and adapter, so they are DERIVED on demand rather
-than stored. The socket HOME is a deterministic function of that same identity (a
+Status and warnings are live-only (§5.7). Runtime artifacts use fresh launch
+identifiers beneath the validated session directory and are never read from a stored record. Their filenames remain fixed for
+the owning PTY's lifetime, including while a later launch is pending. The socket
+HOME is a deterministic function of that same identity (a
 bounded fingerprint, §8.1), so every launch resolves the same one without storing
 it. The bridge authentication token and the socket FILE inside that home are minted
 FRESH on every start and resume and never trusted from disk — a recorded token or
@@ -125,3 +164,5 @@ ordinary session record; a later resume has no loops.
 metadata, generated settings/config, bridge route records, sockets, and
 temporary files. It must not remove agent-owned global transcripts/auth state or
 project/user settings that Elwood did not create.
+
+Native question requests, opaque IDs and answers are live-only (§5.10); none is added to Elwood persistence.

package/prd/09-lifecycle.md

@@ -27,6 +27,13 @@
    session env.
 9. Return a `CodexSessionApi` object once the process and bridge are ready.
 
+Both adapters inspect received PTY output during the bounded startup health check,
+independently of terminal rendering. The collector retains at most the first
+64 KiB of UTF-8 output, ending on a complete code point. If a chunk exceeds the
+remaining budget, its remainder and all subsequent chunks are discarded; later
+output cannot fill a gap in that prefix. The collector releases its retained
+output after the check succeeds or fails.
+
 ### 9.2 Compatibility checks
 
 Elwood MUST check the installed Claude Code version during startup. The minimum
@@ -80,11 +87,48 @@ a second update. This mutual exclusion also applies across separate Elwood paren
 processes for the same macOS user and adapter: an atomic lease names the adapter in
 a stable per-account cache independent of `TMPDIR`; contenders wait without
 blocking the event loop, then invalidate their local caches and continue without
-running a duplicate update. The lease records the owner's process id and a unique
+running a duplicate update. Contender waiting is bounded to 60 seconds; an owner
+that has not finished by then causes the contender to skip its update and warn,
+without deleting the owner's lease. This warning uses `errorCode: "update_active"`
+and a canonical message explaining that the update was skipped because another
+updater is still active; no local update command ran, so it carries no exit status
+or stderr. The lease records the owner's process id and a unique
 generation. Cleanup removes only the generation it owns, a live owner is never
 evicted solely because the stale bound elapsed, and recovery of a dead owner's
 lease is itself serialized before removal, so neither cleanup nor concurrent stale
-recovery can evict a successor. Within one parent process, a FAILED shared update
+recovery can evict a successor. The lease is published atomically: a claimant writes
+its owner record inside a private staging directory and renames that directory into
+place, so a lease either does not exist or holds a complete owner record: no
+ownerless or partially written lease is ever published. A claimant interrupted
+before the rename leaves only its staging directory; one interrupted after it leaves
+a complete lease naming a dead owner, which ordinary stale recovery removes. Release is
+atomic in the same way: the owner renames its lease away and then deletes it, so a
+contender polling during release sees a whole lease or none, never an ownerless one
+it would recover as stale and follow with a duplicate update. A release that cannot rename
+at all still removes the lease where it stands rather than leaving it: its owner is alive,
+so a lease left behind would make every later updater on that host wait forever on a process
+that has already finished updating. Each lease holder removes
+a bounded number of that adapter's leftovers, of both kinds — staging left by an
+interrupted claimant and retired directories left by a release that renamed but did not
+delete — under one shared budget, so later holders finish whatever one holder leaves. An update whose aborted probe reports a process group it could not confirm gone
+(the typed update error's `cleanupProcessGroupId` detail) does not simply release its
+lease. Elwood observes that group for up to one additional second without signaling
+it; a group that exits within the window is not retained. A group still live is
+recorded on the lease as its only holder, so the lease outlives the parent process:
+contenders skip their update immediately with the `update_active` warning and a
+message saying another updater's process group has not exited, rather than waiting
+or starting a competing installer. Recovery removes this guard only after confirming
+every recorded group has exited; elapsed time or the parent's death alone is
+insufficient, and once the groups are gone the lease is recoverable whatever its age.
+If the group record cannot be written, the owner process keeps the obligation itself:
+it retries the record on an unreferenced timer and releases the lease as soon as the
+groups have exited, so a failed write never holds exclusion for the owner's lifetime.
+A lease directory that already exists, even one without an
+owner record, is a wait condition: it is recovered as stale rather than claimed
+over. An unreadable owner record still fails safe: it may belong
+to a live updater writing a record format this version cannot read, so it is never
+treated as dead. That is why a claim must not be able to publish one.
+Within one parent process, a FAILED shared update
 is likewise shared once — every concurrent caller observes the same failure,
 re-reads the installed version, and proceeds through the compatibility gate; the
 failure is never cached in a way that rejects those callers or poisons a later
@@ -98,7 +142,25 @@ failure.
 Each probe is bounded so a broken or hostile CLI on PATH cannot hang or flood
 the host: a probe that does not exit within a default timeout (15 seconds) or
 whose captured output exceeds a per-stream byte cap (1,000,000 bytes) is
-killed, and its captured output is truncated to the cap. Truncation happens on
+killed, and its captured output is truncated to the cap. Abort cleanup has an
+additional one-second bound: an aborted probe retries process-group termination,
+falls back to terminating the direct child once group signals have kept failing,
+and awaits exit within that window. A process-group id is signaled only while the
+probe's direct child (the group leader) is still unreaped, because only then is
+the number guaranteed not to have been reissued to an unrelated group; afterwards
+Elwood only observes the group until it exits and never signals the bare number.
+Cleanup that is confirmed within the window reports no cleanup error; the group is
+observed once more when the window ends, and the window is measured on a monotonic
+clock. Unconfirmed cleanup adds two details to the probe's typed error: the
+allowlisted `cleanupErrorCode`, and `cleanupProcessGroupId`, which is diagnostic
+only — the id may already have been reissued to an unrelated group, so a consumer
+must never signal it. Every
+unresolved aborted probe, including version
+and capability probes, remains owned by an asynchronous reaper while the parent
+is alive. Retries use an unreferenced timer, do not prolong host shutdown, and
+stop signaling after a successful group kill; ownership ends when the group is
+confirmed gone. A retained reaper holds process-liveness state only; the probe's
+captured output is released once its result is delivered. Truncation happens on
 a UTF-8 code-point boundary — an incomplete trailing sequence is dropped — so
 the decoded output re-encodes to at most the cap rather than growing via a
 replacement character. This applies to every
@@ -191,6 +253,20 @@ generated files, including loop definitions, unless kill or teardown is
 requested. Any unsubmitted due state is discarded. (Session status is live-only and is
 not written to the record, §8.2.)
 
+A resume started by an exit listener supersedes the old launch's shared-state
+ownership (§8.1). Deferred or repeated teardown of that old object still cleans its
+own resources, but cannot clear the successor's loops or remove its files/socket.
+
+Runtime cleanup first allows received terminal output to render, then disposes
+the renderer (C-LIFE-12). The drain covers output that arrives while it is in
+progress: it ends only when a whole settle pass completes with nothing new
+received from the PTY, and the entire drain shares one one-second budget. It does
+not delay the native process-exit notification, terminal status, or unconditional
+process-group reap; the final `terminal:data` tail may therefore arrive after
+`terminal:exit`. A stalled renderer, or a PTY that never goes quiet, is disposed
+when the budget expires. Explicit direct `terminal.dispose()` does not wait for
+pending output.
+
 Reaping the leader's process group is unconditional on every exit path
 (C-LIFE-10). On an unsolicited PTY exit the terminal status is submitted first,
 then the group is reaped in a `finally`, so transcript-drain, warning-emission, or

package/prd/10-errors.md

@@ -28,6 +28,7 @@ Initial required error names:
 | `resume_unavailable` | A resume request cannot be completed from available session metadata. |
 | `pty_start_failed` | PTY or shell startup failed. |
 | `hook_bridge_failed` | The hook bridge or IPC endpoint could not be initialized. |
+| `input_queue_full` | A live session control queue would exceed 1,024 outstanding operations or 8 MiB aggregate UTF-8 input text; no input or attachment is performed for the rejected operation. |
 | `session_not_running` | Operation requires a running process but the session is stopped. |
 | `termination_failed` | A stop/kill request did not observe process exit after escalation, or the PTY exited but its process group could not be confirmed reaped. |
 | `teardown_failed` | Elwood could not remove all owned session files. |
@@ -37,8 +38,8 @@ Initial required error names:
 | `login_failed` | The interactive `/login` re-authentication flow reported an explicit failure or an invalid authorization code. |
 | `login_timeout` | The interactive `/login` re-authentication flow did not report success before the timeout. |
 | `invalid_image` | An `images` input is not attachable: an unsupported/absent byte format, empty bytes, a path that is not a readable file, or a total image count/size beyond the documented limits (C-API-44). Raised before any partial input reaches the composer. |
-| `image_attach_failed` | An image could not be confirmed attached: the CLI's `[Image #N]` chip did not appear before the confirmation timeout, or the OS clipboard could not be read/written. No text is submitted afterward. (A session that TERMINATES mid-attach rejects with `session_not_running`, like any queued op.) (C-API-44/45/46) |
-| `wait_timeout` | A `waitForStatus`/`waitForActivity` call did not observe its condition before the timeout. |
+| `image_attach_failed` | An image could not be confirmed attached: the CLI's `[Image #N]` chip did not appear before the confirmation timeout, the OS clipboard could not be read/written, or terminal rendering permanently failed. No text is submitted afterward. (A session that TERMINATES mid-attach rejects with `session_not_running`, like any queued op.) (C-API-44/45/46) |
+| `wait_timeout` | A `waitForStatus`/`waitForActivity` call did not observe its condition before the timeout, the PTY rejected a staged-draft cleanup write before successor input, or raw input replaced an initial/replay ergonomic submission awaiting empty-input confirmation (§5.3). The same code rejects queue-backed input admitted from an expired Stop callback/observer context (§6.3), before terminal-state checks even after teardown. Cleanup failures retain the pending draft and use a bounded message without raw PTY diagnostics. |
 | `invalid_loop` | A loop request or recognized `/loop` command violates the documented shape, interval, or UTF-8 message bounds. |
 | `loop_limit_reached` | Creating a loop would exceed 50 unexpired definitions; existing loops are unchanged. |
 | `loop_not_found` | Cancellation targeted an unknown or already-finished loop ID. |
@@ -53,3 +54,9 @@ Startup errors MUST NOT swallow their underlying cause: `pty_start_failed`,
 message in `details.cause`, plus `errno`, `syscall`, and `path` fields when
 the underlying error exposes them, so consumers can diagnose environment
 failures without instrumenting Elwood internals.
+
+Native question controls add `question_not_found` (no current request with this live ID), `invalid_question_answer` (invalid complete answer batch or timeout option), and `question_answer_failed` (busy, revoked, unsupported or unacknowledged native input). Messages and details do not echo answer text.
+
+Native question answer failures may include only the fixed `details.category` values
+`frame_wait`, `adapter`, `terminal_write`, `native_acceptance`, or `aborted`
+(§5.10). Raw native exceptions and submitted answer values are never retained.