@with-logic/elwood 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -4,14 +4,395 @@ All notable **consumer-facing** changes to Elwood are recorded here: new or
 changed public API, session/lifecycle behavior, activity/event shapes, and bug
 fixes a host application would notice. Internal refactors, test-only changes,
 and doc tweaks are omitted. The format follows
-[Keep a Changelog](https://keepachangelog.com); this project is pre-1.0, so
-everything lands under **Unreleased** until the first tagged release.
+[Keep a Changelog](https://keepachangelog.com). Changes accumulate under
+**Unreleased** and move into a versioned section for each release.
 
 Observable behavior is specified in `prd/`; the conformance criteria that
 back each entry are listed in `prd/14-conformance.md`.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-22
+
+- Codex question turns settle after native completion even when consecutive answer echoes contain caret-like multiline text.
+
+- Preserve overlapping Claude question requests across out-of-order hook outcomes;
+  require unambiguous native panel evidence before exposing answer authority.
+
+- Cancel question writes before physical dispatch when the operation aborts, including after its final frame guard.
+- Retain uncertain native answer reservations until both the physical write and correlated native ownership settle.
+- Preserve in-flight question request IDs through same-key metadata redraws so late native acceptance closes the original request.
+
+
+- Preserve the first question-observer failure diagnostic when pending listener
+  promises exceed the notification registration cap.
+
+- Keep native Claude questionnaires blocking when question text contains composer-like carets, fences, or navigation-footer copy.
+
+
+- Report contained question and companion activity listener failures once per
+  live session with a content-free `question_observer_failed` warning.
+
+- Expose live Claude and Codex questionnaires through typed `question` events,
+  structured normalized activity, `listQuestions()` and `answerQuestions()`;
+  submit grouped forms and independent queued answers while preserving running
+  turns, guarding native editors and verifying native acceptance. Budget
+  disablement emits a content-free `question_automation_disabled` warning.
+
+- Enforce the existing required payloads in transcript activity types: Codex progress carries text and its Codex/transcript identity, and Claude transcript projections retain their per-kind required fields.
+
+- Keep Codex turns running through native working pulses and hold input at blocking modal and queued question editors; recognize the captured Plan mode footer when verifying an empty composer.
+
+- Recognize Claude Code 2.1.305 question dialogs as blocking input and accept its captured manual-mode footer when verifying an empty composer.
+
+- Expose committed Codex commentary as readable `assistant_progress` activity, distinct from final answers; suppress non-final legacy mirrors so progress neither duplicates nor completes replies.
+
+- Expose Claude's advance login-renewal notices as `login_expiring` warnings and activities with `expiresInDays` and `/login`, including startup and resume, without interrupting the session.
+
+- Report a submission-specific `wait_timeout` when raw input replaces ergonomic input awaiting empty-composer confirmation, preserving model-picker diagnostics for picker operations.
+- Codex recovery now withholds retry Enter and empty-input acknowledgement when partial native approval rows remain above a retained composer.
+- Keep ergonomic response collection behind selected loop and persona completion; bind Codex transcript content and Stop completeness to the native acceptance of the caller's own submitted turn, including headless CLI sessions.
+
+- Prevent retained working and interrupt frames from releasing input physically submitted inside Stop callbacks; expired raw Stop input retains its timeout error after teardown.
+- Stop ergonomic turn recovery when its consumer settles, retaining captured images and the next turn’s slot until input cleanup and the current native boundary finish.
+
+- Retain staged text and images for initial and replay ergonomic submissions until fresh native empty-input evidence, preserving cancellation cleanup and the ordinary first-Enter send contract.
+
+- Preserve asynchronous hook decisions after the generated bridge child finishes sending its request, instead of closing the reply stream early.
+- Recover image-only and whitespace submissions only from a fresh live composer render after each Enter attempt; cached text or image drafts cannot trigger an extra Enter.
+
+- Preserve each observer registration’s async context when listeners reuse a pending Promise.
+
+- Require a current first-party banner for every automated Codex update-menu selection, withholding all bannerless choices while retaining the input hold; renumbered or removed safe options revoke the old retry, and a fresh bounded bannered block can recover from overflow.
+- Keep landing-page pickup responsive while preparing every suspended-animation sheet, cancelling obsolete pickup work on drop, reset or teardown.
+- Clear completed Codex trust gates when the native idle composer displays its warning-count footer, so queued input can reach readiness.
+
+- Bound each session’s queued input to 1,024 outstanding operations and 8 MiB of text; excess submissions reject with `input_queue_full` without writing to the terminal, and oversized personas reject before session startup.
+- Preserve Codex hook input, decisions, and turn bookkeeping when observers mutate, throw, or reject, with one bounded `hook_observer_failed` warning per hook and a distinct lifecycle warning for standalone initial-ready observer rejections.
+
+- Reject late queue-backed input from context-preserving continuations of completed or timed-out Stop callbacks and observers, so it cannot overtake a successor released by that Stop.
+
+- Keep a prompt submitted from a Stop callback running when the older Stop completes, without blocking immediate callback input.
+
+- Recover swallowed prompt Enters only from the live idle composer, without mistaking transcript text or working frames for staged input. Fresh empty input ends recovery; unverifiable frames get bounded observation retries.
+
+- Prepare complete automatic landing-page gestures and facing actions before playback, releasing obsolete task loads without interrupting manual input.
+- Discard expired automatic landing-page actions before readiness checks, preventing late assets from triggering an obsolete gesture or facing change.
+- Reuse decoded idle sheets across landing-page actions instead of repeatedly fetching and decoding them after playback changes.
+
+- Prepare and retain the complete initial idle animation before replacing the landing-page fallback.
+
+- Prepare complete landing-page gesture and facing animations before delivery, cancel obsolete requests, and avoid loading input that cannot play in the current state.
+
+- Stop background recovery Enter presses when the native composer is positively empty, even if submitted text remains in the transcript.
+
+- Avoid repeatedly scanning blocked turn input when model and login controls cross a queued backlog.
+
+- Stop background paste-recovery Enter presses after native submission activity, including while the first physical Enter is pending.
+
+- Require one current native update-option block before sending a skip key. Ambiguous repaints revoke the attempt; only fresh unambiguous banner evidence with a current safe choice can reauthorize it and renew its bounded CLI grace, including the same version pair.
+
+- Recognize Codex’s native ✨ update banner when its options are clipped, keeping the partial updater input-blocking.
+
+- Renew the CLI update grace period once for a changed Codex version banner, using generation-tagged attention without reporting a successful skip.
+
+- Treat a changed Codex update version banner as a new appearance, cancelling old retries and allowing a fresh bounded skip attempt.
+
+- Keep Codex update retries revoked after unknown or blank replacement frames until authoritative native composer clearance or fresh banner evidence appears; late writes cannot report an answer for a superseded dialog.
+- Hold scheduled loop delivery through ergonomic caller turns, preventing a due
+  loop from accepting or completing a caller prompt that needs recovery.
+
+- Recognize Claude 2.1.281's half-circle working title, keeping active turns and
+  trust holds from appearing idle while the input composer remains visible.
+
+- Keep startup persona responses out of ergonomic caller turns, including when
+  the persona and caller submit identical text or its transcript arrives after
+  readiness. Closing cancels waiting callers even if process shutdown fails.
+
+- Preserve cancellation when a queued submission's pending physical write later
+  succeeds, so the cancelled operation cannot report success. Commit successful
+  loop delivery before running observers can cancel it, preserving fired telemetry.
+
+- Stop delayed paste-recovery Enter keys after raw caller input takes ownership of
+  the draft, including direct terminal and xterm input.
+
+- Report an automated Codex update skip as answered only after verified native
+  composer clearance; completed writes without a reader or into replaced dialogs
+  settle quietly without false startup success.
+
+- Recognize Codex 0.156.1 capitalized model footers when confirming an empty
+  native composer, so cancelled draft cleanup can release queued successor input.
+
+- Recognize Codex 0.156.1 folder-access trust prompts, keeping queued input held
+  and approving only the known choice when `autotrust` is enabled.
+
+- Keep queued Codex input held when an update screen becomes an unknown or partial
+  dialog, until its live native composer returns; a stale visible cursor cannot
+  clear replacement text above the old composer. Specific trust rules retain their
+  diagnostic labels; other retained holds report `codex-unidentified-dialog`.
+
+- Retry an ignored Codex prompt Enter when the staged paste contains stripped
+  control characters, tabs, or carriage-return line breaks.
+
+- Preserve picker and cancelled-draft cleanup authority across automatic terminal
+  protocol replies and startup automation; actual caller input still revokes it.
+
+- Clear cancelled staged text and images before successor input, deferring cleanup
+  through dialogs. Failed cleanup holds the draft; raw input through `sendKeys`,
+  `terminal.sendInput`, or `xterm.input` revokes cleanup authority, and shutdown drops
+  deferred cleanup without waiting. A physical clear must be confirmed by a fresh
+  native empty composer before successor input; Claude recognizes both its native
+  idle screen and its post-picker composer.
+
+- Hold image paste keys until received terminal output has rendered and blocking
+  dialogs have cleared, then capture the chip count immediately before pasting.
+  Permanent render failures reject the attachment and release its clipboard lock;
+  session cancellation also prevents pending image input.
+
+- Cancel Codex update retry timers and pending automated keys when the session closes,
+  suppressing late startup success and write-failure warnings after disposal.
+
+- Release cancelled config-lock and clipboard-lock waiters immediately, including
+  captured session state, while active holders retain ownership through cleanup.
+
+- Select Codex update-skip choices only from a current validated first-party
+  banner and safe-option block, after the update action when present. Selection
+  uses the current numbering and never selects an update action whose label also
+  contains a skip phrase.
+
+- Keep an acquired Codex config or clipboard lock operation pending until its task
+  finishes cleanup when cancellation arrives; cancellable config-lock waiters still
+  cancel immediately. Codex model-switch deadlines also
+  cancel config-lock waits and release the waiting session input slot. A timeout
+  before successful `/model` dispatch never cancels a picker opened by someone else,
+  and the initial picker-screen wait honors the same operation deadline. Ordinary
+  queued text and images remain held through foreign picker repaints. Raw user
+  input revokes active picker navigation and cleanup, including config restoration
+  that could overwrite a human choice; uncertain changed defaults emit the existing
+  persistence warning.
+
+- Keep queued input suspended when a human dialog clears while the agent is still working,
+  including deferred startup readiness. A caller prompt held by the dialog reasserts running
+  when it submits, before a queued follow-up can dispatch. Blank or caret-only repaints
+  retain the hold until a verified idle composer, and resumed working clearance preserves
+  the next idle transition.
+
+- Refresh attention diagnostics when a blocked session switches to a differently
+  classified prompt, so consumers see the current human decision instead of a
+  stale update-prompt label. Repainting the same blocking rules stays quiet.
+- Keep a visible human prompt blocked through caller submissions and rendered turn
+  starts or endings, including late Stop hooks. Readiness resumes only after clearance.
+
+- Preserve live-loop cancellation notifications through delayed or retried kill and teardown cleanup. Previously, pausing the scheduler before clearing definitions could suppress these events.
+
+- Keep each live launch’s hook policy bound to its own bridge artifacts during resume. Pending resumes reconcile durable loops at activation; destructive predecessor shutdown joins the reservation outcome, and rollback attempts all files before reporting restoration failures.
+
+- Claude and Codex transcript and diagnostic listeners can stop a session without
+  moving pending activity past terminal exit, duplicating finalization, or signaling
+  an already-exited PTY while its final transcript records are being delivered.
+  An exit immediately after startup waits for already-scheduled warning delivery,
+  preserving both subscriber visibility and diagnostic-before-exit ordering.
+  A session resumed from an exit listener retains its files, socket, and loops when
+  the old launch finishes a deferred or repeated teardown, including through supported
+  state-path aliases. Failed launches restore their own published files, CLI cleanup
+  preserves newer owners, and superseded loop mutations reject instead of silently
+  reporting success.
+
+- Keep human-owned trust gates blocked through partial and unknown replacement
+  frames. Queued caller input resumes only after positive native clearance. Both
+  adapters withhold trust retries and human clearance while received output is
+  still rendering or the terminal has reported a render failure. Claude also waits
+  for its visible native input cursor after the final composer paint and retains
+  the hold while its native working title remains active.
+
+- Recognize Codex's native composer beneath numbered transcript output and with
+  its older model footer. A newly painted bare caret cannot borrow an earlier
+  composer's footer to release input held for a human dialog. Live clearance now
+  requires its visible input cursor after all received batches render; native approval
+  headers still override a stale visible cursor. Partial dialogs stay held while
+  ordinary transcript prose and numbered user prompts remain valid. Exact-shaped
+  native working rows remain conservatively held. Active work and incomplete
+  welcome-box fragments cannot release input.
+
+- Keep Codex transcript polling and activity delivery running after a public listener
+  throws, so later records (including turn failure evidence) still reach subscribers.
+  The content-free `transcript_listener_error` warning identifies the failed delivery
+  channel at most once per watcher, after synchronous transcript delivery;
+  `transcript_poll_stopped` remains reserved for actual reader failures.
+
+- Detect startup authentication errors from PTY bytes as soon as they arrive.
+  Slow or stalled terminal rendering no longer lets an already-received error
+  escape the bounded startup check in either adapter. Startup capture retains only
+  a complete UTF-8 prefix within 64 KiB, including for oversized raw chunks.
+
+- Reject hook rewrites with unsafe JSON values or accessors before serialization, and stop wide-value inspection at the validation budget.
+
+- Reject cyclic and excessively deep or wide schema-less hook inputs
+  and rewrites without throwing. Validation allows at most 128 edges of depth
+  and 100,000 value visits, counting repeated children on each path. Invalid rewrites
+  now report `invalid_response` and return no decision instead of reaching the JSON
+  serializer with an unserializable graph.
+- Reject `NaN` and `±Infinity` in numeric Claude hook fields, for every tool. Because
+  `JSON.stringify` encodes them as `null`, a hook handler that returned one in an
+  `updatedInput` rewrite used to send the CLI a `null` where its schema requires a
+  number. Concrete tool schemas enforce this per field; schema-less tools (MCP,
+  generic, future) enforce it structurally over the whole value, nested records and
+  arrays included. Such a rewrite is now an invalid result: the bridge fails open with
+  no decision and emits `hookError`.
+
+- Bind the Claude browser-tools decline to session disposal. After `stop()`,
+  `kill()`, or PTY exit the decline is no longer attempted, and one already in flight
+  settles as a cancellation, so a closed session no longer emits a late
+  `startup_prompt` / `startup_prompt_write_failed`. The keystroke itself is bound too:
+  the non-trust automation barrier waits for render settlement, and a write parked there
+  is interrupted immediately on disposal, releases its observation timer, and never
+  delivers a stale Escape to a dead PTY. Trust automation already had this lifetime.
+
+- Preserve Claude hook decisions and lifecycle progress when observational listeners
+  throw or return rejecting Promises, with one bounded `hook_observer_failed` warning
+  per affected invocation. Pending observers do not delay hook replies; diagnostic
+  retention is capped at 1,024 registrations per emitter. Promise constructor/species
+  metadata must permit native reaction attachment; attachment throws are reported
+  and remain retryable. Warning payloads are
+  frozen before delivery. Incoming
+  Claude hook events are deeply frozen before observation, and throwing observers
+  no longer truncate subsequent hook-scoped status or transcript notifications.
+
+- Snapshot Claude hook responses before validation so later mutations or custom accessors cannot replace validated rewrites on the wire. Capture wire output and blocking decisions before activity listeners run.
+
+- Preserve Claude `StopFailure` hooks with missing or changed diagnostic fields. Those
+  fields are now typed as optional `unknown`, matching ingress. Browser logs show a
+  bounded rejection reason instead of unrelated assistant text or a blank summary.
+
+- Route Codex tool-keyed hooks from own properties only. A `PreToolUse` map is a
+  plain object, so a tool name matching an inherited member (anything on
+  `Object.prototype`, or a key on a caller-supplied prototype) used to resolve to a
+  function the caller never registered for that tool and run it against the hook
+  event. Both the exact-name and `unknown` lookups now require an own property,
+  matching Claude routing.
+- Hold the cross-process update lease for an aborted updater's surviving process
+  group. An update probe that was aborted without confirming its process group had
+  exited used to release the lease anyway, so another Elwood host could start a
+  competing installer while the first updater's descendants were still running.
+- Bound the cleanup of an aborted version, capability, or update probe to one
+  extra second: retry process-group termination, fall back to the direct child,
+  and keep an unresolved group on an asynchronous reaper that never extends host
+  shutdown or retains captured output. A process group is signaled only while its
+  leader is unreaped, so a reissued group id is never killed. An update probe whose
+  group stays unconfirmed now reports that group in its typed error details.
+- Serialize `listModels`/`setModel` through the session input queue: a model
+  operation owns the queue until its picker flow settles, so overlapping model
+  calls, queued commands, and messages can no longer be typed into a picker while
+  the operation that opened it is running. `compact`'s delayed recovery Enter is
+  cancelled once a later operation takes the composer, rather than queued behind it.
+- A Codex `setModel` interrupted by session termination waits for the CLI process
+  to exit before restoring `config.toml`, bounded at five seconds so a process that
+  never reports an exit cannot hold the shared config lock. Session status alone
+  (`stopped`, `killed`, `torn_down`) no longer releases the restore, since teardown
+  records those even when its signal did not take. The wait now applies whether the
+  switch succeeded or failed: the question is whether the dying CLI can still write
+  `config.toml`, not whether Elwood's automation worked.
+- A Codex `setModel` still waiting for the process-wide `config.toml` lock rejects
+  with `session_not_running` as soon as its own session closes, instead of staying
+  pending until the session ahead of it finishes its transaction and exit wait. A
+  cancelled call never runs its switch when the lock frees.
+- Stop non-trust startup automation from writing into a trust gate that arrived while
+  the previous screen was still rendering. The Codex update skip (including its retries)
+  and the Claude browser-tools decline now observe all received PTY output and re-check
+  the settled frame before writing, the guarantee queued caller input already had. A
+  withheld write is silent and stays retryable; the trust responder is unaffected and
+  still answers trust gates itself.
+- Hold queued input on an unrecognized gate behind a recognized native header
+  prefix (`Do you`, `Is this`, `Trust the`, ... — PRD §5.4 lists them): a reworded
+  question with selectable options and a frame-ending native footer, and no
+  conversation above, now blocks for a human with the attention label
+  `<agent>-unknown_gate-prompt` under every `autotrust` value and is never answered
+  automatically; previously readiness could type the queued message and Enter
+  into it. Gates outside that grammar (other leading words, other footers) are
+  still not held. Dialogs that already block keep their existing labels.
+- Bound Codex in-TUI update skipping to one attempt per appearance of the update
+  screen: an exhausted retry no longer restarts on the next frame of the same
+  screen, and a stale attempt's late completion cannot start an overlapping retry
+  loop or report success or a write failure for the newer screen. A skip write
+  rejected after the update screen already cleared no longer fails a healthy
+  headless run as `blocked_prompt`. A reappearing update screen is still skipped again.
+- Emit the `attention` activity for a blocking prompt that painted while the
+  session was still `starting`. Such a session already became `blocked`, but
+  without the human-decision event, so a headless `elwood` run never reported
+  `blocked_prompt`.
+- A failed `listModels`/`setModel` now cancels the model dialog it left open
+  before releasing queued input, and holds queued messages, commands, and `/login`
+  while a dialog it could not cancel stays visible. Picker text quoted in a reply
+  is never cancelled, so cleanup cannot interrupt a running turn.
+- `setModel` no longer resolves on the partially painted frame that precedes
+  Claude's cache warning (it reported success without confirming the switch), and
+  queued input stays held while a Claude switch dialog is still painting.
+- Model-picker cleanup also covers a dialog that paints up to a second after the
+  failure (a late picker, Codex's reasoning level, Claude's cache warning). A model
+  operation now rejects without writing when model picker text is already visible.
+- `compact`'s recovery Enter can no longer be typed into a model picker opened by
+  a concurrent `listModels`/`setModel` (where Enter saves the highlighted model as
+  the default): it now waits for the picker operation to release the input queue.
+- Snapshot image bytes and relative paths when facade methods are called, including
+  turns queued behind another response or waiting for session startup. Facade copies
+  count against the same 200 MiB per-session ceiling as sends on the raw `session`.
+- Reject FIFO state/config files without hanging.
+- Runtime cleanup drains received terminal output before disposing the renderer —
+  for up to one second, including output that arrives while it drains — so the
+  final `terminal:data` tail is delivered (possibly after `terminal:exit`) instead
+  of dropped. `--head` now mirrors through cleanup, so the agent's final frames
+  (for example its last words before an unexpected exit) are no longer cut off.
+- Bind automatic trust approvals to the active dialog and revalidate every write,
+  preventing quoted transcript headers or unknown intervening titles from
+  authorizing unrelated permissions. Cancel stale trust attempts quietly while
+  keeping readiness and queued input gated until the native dialog clears. Retry
+  early numbered trust writes that the CLI has not yet consumed. Bound both
+  navigation styles to the session and current dialog generation; unsupported or
+  exhausted trust automation becomes a recoverable block after five seconds.
+  Image attachment is held by the same trust gate as text input.
+- Require a trust dialog's native explanatory copy before any automatic approval:
+  a bare allowlisted header with affirmative options is held, never typed into,
+  and becomes answerable only once its native body paints (recoverable `blocked`
+  after five seconds otherwise). Skill, plugin, and MCP gates are unchanged.
+- Release the cross-process update lease atomically. A second Elwood process polling
+  at the instant the owner released could recover the half-removed lease as stale
+  and run a duplicate `autoupdate` right after the first.
+- Publish the cross-process update lease atomically. An Elwood process killed
+  while claiming the lease could leave a partial owner record that made every
+  later `autoupdate` on that machine skip its update until the cache was removed
+  by hand.
+- Queued input now renders and observes all PTY output already received before
+  each write, so a trust or permission dialog that was received but not yet
+  rendered still holds the paste, its Enter, and recovery Enters. The compact
+  recovery Enter follows the same rule and is cancelled once a later queued
+  operation dispatches. On the terminal handle, `settled()` now also covers output
+  received while waiting (it still never rejects), and the new read-only
+  `renderFailed` property reports a failed render, after which queued input stays
+  withheld.
+- Keep text CLI output limited to agent responses by default. Use
+  `--show-session-id` to print the retained session ID on stderr, or find it
+  with `elwood sessions`. Session retention and JSON/JSONL records are unchanged.
+- Batch terminal rendering, improving throughput across parallel sessions:
+  adjacent PTY chunks share one render and one `terminal:data` event (at most
+  64 KiB, flushed within 4 ms), so event chunk boundaries and intermediate frames
+  are no longer guaranteed. Direct terminal disposal settles pending writes
+  immediately. Real PTY reads pause when unrendered output reaches 1 MiB and resume
+  below 512 KiB, so a runaway producer cannot grow the render backlog without bound;
+  a paused PTY resumes as soon as its child exits, so a draining backlog cannot
+  strand unread tail output.
+- Recognize only native Codex warning banners, keeping quoted private prompt text
+  out of warning events by requiring the current native welcome region.
+- Validate all concrete Claude tool input fields and typed hook fields, constrain
+  permission rewrites to tool-specific handlers, and accept nullable Codex descriptions.
+- Bound the wait for another Elwood process's `autoupdate` to 60 seconds. A
+  contender that is still waiting then skips its update and continues with the
+  installed CLI, reporting `agent_update_failed` with `errorCode: "update_active"`
+  instead of waiting indefinitely; the active owner's lease is never evicted.
+- Match Claude task identifiers and plan permission objects to the native hook
+  schemas so valid task and plan inputs reach their handlers.
+- Contain clipboard pipe failures during Codex image attachment, and retain the
+  clipboard lock until the restore process exits.
+
 ## [0.1.3] - 2026-09-14
 
 - Keep live session warnings quiet in text and JSON CLI output, including model

package/CONTRIBUTING.md

@@ -1,9 +1,14 @@
 # Contributing
 
-Thanks for helping with Elwood. This project is spec-first: `prd/` is the
-contract for observable behavior, and `CLAUDE.md` (also linked as `AGENTS.md`)
-is the implementation guide for anyone, human or AI, changing code. Read both
-before opening a pull request.
+Elwood is open source, but we do not accept outside pull requests. GitHub
+restricts PR creation to repository collaborators with write access or higher.
+You are welcome to use and fork Elwood under its MIT license, and to report
+security concerns through `SECURITY.md`. Issue creation is limited to repository
+collaborators.
+
+The instructions below are for maintainers. This project is spec-first:
+`prd/` is the contract for observable behavior, and `CLAUDE.md` (also linked as
+`AGENTS.md`) is the implementation guide. Read both before changing code.
 
 ## Requirements
 
@@ -60,6 +65,12 @@ directories automatically.
 
 ## Pull requests
 
+- Use branches in this repository. Fork PRs are not reviewed by automation.
+- After the first automatic review, post exactly `/review` as a new PR
+  comment to request another. Only current maintainers can trigger it.
+- The twelve-lens shared AI review can approve a completed review with no blocker or
+  major findings. Required CI checks and branch protections still apply; the
+  review workflow does not merge PRs. See [.github/PIPELINE.md](.github/PIPELINE.md).
 - Keep pull requests small and focused on one change.
 - Do not include secrets, access tokens, credentials, or private data in
   issues, tests, logs, screenshots, or fixtures.
@@ -88,17 +99,17 @@ like everything else but are excluded from the coverage gate.
 
 ## Repository map
 
-| Path | Purpose |
-|---|---|
-| `prd/` | Source of truth for behavior and conformance criteria (one file per section). |
-| `src/index.ts` | Public package exports. |
-| `src/core/` | Adapter-neutral session machinery: control queue, status detection, turns, loops, images, warnings. |
-| `src/runtime/` | Shared session base class, startup checks, teardown, and test seams. |
-| `src/claude/`, `src/codex/` | The two adapters: launch, hooks, transcripts, validation. |
-| `src/cli/` | The `elwood` executable. |
-| `src/state/` | Session records and private sidecar files. |
-| `src/bridge/` | Local hook bridge server and generated bridge script. |
-| `src/terminal/`, `src/pty/` | Headless xterm.js model and node-pty adapter. |
-| `dev/` | Local terminal and browser dev apps (not published, not coverage-gated). |
-| `tests/` | Unit, conformance, and e2e suites. |
-| `docs/` | Guides and the record of empirically learned CLI behavior. |
+| Path                        | Purpose                                                                                             |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| `prd/`                      | Source of truth for behavior and conformance criteria (one file per section).                       |
+| `src/index.ts`              | Public package exports.                                                                             |
+| `src/core/`                 | Adapter-neutral session machinery: control queue, status detection, turns, loops, images, warnings. |
+| `src/runtime/`              | Shared session base class, startup checks, teardown, and test seams.                                |
+| `src/claude/`, `src/codex/` | The two adapters: launch, hooks, transcripts, validation.                                           |
+| `src/cli/`                  | The `elwood` executable.                                                                            |
+| `src/state/`                | Session records and private sidecar files.                                                          |
+| `src/bridge/`               | Local hook bridge server and generated bridge script.                                               |
+| `src/terminal/`, `src/pty/` | Headless xterm.js model and node-pty adapter.                                                       |
+| `dev/`                      | Local terminal and browser dev apps (not published, not coverage-gated).                            |
+| `tests/`                    | Unit, conformance, and e2e suites.                                                                  |
+| `docs/`                     | Guides and the record of empirically learned CLI behavior.                                          |

package/README.md

@@ -22,11 +22,20 @@ elwood "Explain this project's architecture."
 ```ts
 import { ClaudeSession } from "@with-logic/elwood";
 
-const session = new ClaudeSession({ cwd: "/path/to/project" });
-console.log(await session.send("Explain this project."));
-await session.close();
+const session = new ClaudeSession({
+  cwd: "/path/to/project",
+  autotrust: true, // Approve allowlisted trust prompts for this known project.
+});
+try {
+  console.log(await session.send("Explain this project."));
+} finally {
+  await session.close();
+}
 ```
 
+Use `autotrust` only for workspaces and extensions you trust. Otherwise, run the
+agent directly in the same directory first and approve its trust prompts.
+
 ---
 
 ## Why Elwood
@@ -122,6 +131,7 @@ output protocols, head mode, and continuation.
 `elwoodSessionId`. `ClaudeSession` / `CodexSession` add `send`, `stream`, and
 `close` on top of the full control surface (`sendMessage`, `sendPrompt`,
 `sendGuidance`, `sendKeys`, `interrupt`, `compact`, `listModels`, `setModel`,
+`listQuestions`, `answerQuestions`,
 loops, `waitForStatus`, `stop`, `kill`, `teardown`). The eager `startClaude` /
 `startCodex` factories are deprecated but still available.
 
@@ -134,6 +144,18 @@ context; they fail open on error.
 assistant messages, reasoning, tool calls and results, web searches, hooks,
 warnings, and lifecycle. Most host UIs render this and nothing else.
 
+Codex commentary arrives as `assistant_progress` with normalized `text`; final
+replies remain `assistant_message`. Render progress while keeping the turn
+working. Progress is available through `on("activity", ...)`, and is excluded
+from ergonomic `send()` results and `stream()` text. See
+[Codex commentary](docs/codex/cli.md#commentary-and-final-replies) for the contract.
+
+**Agent questions.** Subscribe to `question` events or `question` activities to
+show native Claude and Codex questionnaires. `listQuestions()` returns available
+requests; `answerQuestions()` submits the user's choices or text through the
+native editor, including while `send()` is waiting. Queued Codex questions can
+remain available while the agent works. See [native questions](docs/questions.md).
+
 **Terminal stream.** `terminal:data` carries the raw PTY bytes so a host can
 mirror the agent in its own xterm. A late subscriber first receives up to
 128 KB of replayed history as one chunk. `sendKeys(Uint8Array)` forwards a
@@ -180,8 +202,9 @@ combined with `--stream`, `--verbose`, `--debug`, or `--output jsonl`.
 ### Continuation and cleanup
 
 New and resumed headless runs preserve Elwood state by default. A resumable
-session ID is reported on stderr for text output and in the terminal record for
-JSON and JSONL. `--keep` explicitly selects the default; use `--ephemeral` for
+session ID is included in the terminal record for JSON and JSONL. Text output
+prints only the agent response; use `--show-session-id` for an ID footer on
+stderr or `elwood sessions` to list retained sessions. `--keep` explicitly selects the default; use `--ephemeral` for
 one-off runs that should remove their Elwood state afterward:
 
 ```sh
@@ -418,7 +441,7 @@ session.on("activity", (event) => {
 | `hook` | Every parsed and validated adapter hook event. |
 | `hook:<Name>` | Hook-specific handler registration with typed response guidance. |
 | `hookError` | Handler timeout, thrown handler, invalid input, invalid response, or bridge error. Hooks fail open. |
-| `warning` | Non-fatal environment issue, such as an unparseable version or a failed autoupdate. |
+| `warning` | Non-fatal environment issue, such as an unparseable version, a failed autoupdate, or Claude's `login_expiring` notice with `expiresInDays` and `/login` ([renewal and recovery](docs/login-recovery.md)). |
 | `loop` | Redacted lifecycle for persisted recurring prompts. |
 | `terminal:data` | Raw PTY output for a visual terminal renderer. |
 | `terminal:exit` | PTY process exit, emitted exactly once. |
@@ -466,7 +489,9 @@ immediate; both are safe after the process has already exited.
   for the entire launched session even without autotrust. Codex update dialogs
   are skipped, and Claude browser-tools onboarding is dismissed. Other recognized
   dialogs leave the session `blocked` for a human; the CLI fails such runs as
-  `blocked_prompt`.
+  `blocked_prompt`. If safe trust automation cannot clear a gate within five
+  seconds, the library also leaves it `blocked`, retaining queued input. A later
+  supported layout can retry automatically; `sendKeys` permits manual recovery.
 - `--high-trust` (library `highTrust: true`) is the agent-neutral "never ask"
   switch: Claude `bypassPermissions`, or Codex `danger-full-access` with
   approval policy `never`. It removes the agent's own guardrails, so point it

package/dist/bridge/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/bridge/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAsB9D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,eAAe,CAAC,CAQjF;AAED,wBAAgB,UAAU,IAAI,mBAAmB,CAEhD"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/bridge/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAsB9D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,eAAe,CAAC,CAQjF;AAED,wBAAgB,UAAU,IAAI,mBAAmB,CAEhD"}

package/dist/bridge/parse.js

@@ -2,6 +2,7 @@
  * Bridge request parsing and fail-open result helpers.
  * Implements PRD §6.2 and §6.3.
  */
+import { inertRecord } from "../core/inert-record.js";
 export function parseBridgeMessage(data) {
     try {
         const parsed = JSON.parse(data);
@@ -40,6 +41,6 @@ export function hookEventNameFrom(input) {
         : "Unknown";
 }
 export function noDecision() {
-    return { exitCode: 0, stdout: "", stderr: "" };
+    return inertRecord({ exitCode: 0, stdout: "", stderr: "" });
 }
 //# sourceMappingURL=parse.js.map

package/dist/bridge/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/bridge/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAI7B,CAAC;QACF,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QACnE,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAO;gBACL,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,GAAG,CAAC,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ;oBAC5C,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE;oBAC7C,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,MAAM,GACV,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzD,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,OAAO,MAAM,CAAC,iBAAiB,CAAC,KAAK,QAAQ;QAClD,CAAC,CAAE,MAAM,CAAC,iBAAiB,CAAqC;QAChE,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACjD,CAAC"}
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/bridge/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AActD,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAI7B,CAAC;QACF,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QACnE,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAO;gBACL,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,GAAG,CAAC,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ;oBAC5C,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE;oBAC7C,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,MAAM,GACV,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzD,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,OAAO,MAAM,CAAC,iBAAiB,CAAC,KAAK,QAAQ;QAClD,CAAC,CAAE,MAAM,CAAC,iBAAiB,CAAqC;QAChE,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/bridge/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/bridge/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,iBAAiB,CAAC,KAAK,IAAI,CAAC;AACrF,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE7D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAG3C,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,kBAAkB,EAC/B,eAAe,CAAC,EAAE,MAAM;IAUpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwDtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAUb,YAAY;IAiB1B,OAAO,CAAC,WAAW;YAQL,MAAM;CA0BrB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/bridge/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,iBAAiB,CAAC,KAAK,IAAI,CAAC;AACrF,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE7D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAG3C,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,kBAAkB,EAC/B,eAAe,CAAC,EAAE,MAAM;IAUpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyDtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAUb,YAAY;IAiB1B,OAAO,CAAC,WAAW;YAQL,MAAM;CA0BrB"}

package/dist/bridge/server.js

@@ -4,6 +4,7 @@
  */
 import { existsSync, unlinkSync } from "node:fs";
 import { createServer } from "node:net";
+import { inertRecord } from "../core/inert-record.js";
 import { MAX_HOOK_REQUEST_BYTES } from "./limits.js";
 import { hookEventNameFrom, noDecision, parseBridgeMessage, parseHookInput } from "./parse.js";
 export class HookBridgeServer {
@@ -26,7 +27,8 @@ export class HookBridgeServer {
     async start() {
         if (existsSync(this.socketPath))
             unlinkSync(this.socketPath);
-        const server = createServer((socket) => {
+        // The child FIN ends its request, not its wait for our asynchronous reply.
+        const server = createServer({ allowHalfOpen: true }, (socket) => {
             this.sockets.add(socket);
             // Accumulate RAW bytes, not per-chunk strings: decoding each chunk on its own
             // would insert replacement chars whenever a multibyte code point straddles two
@@ -49,7 +51,9 @@ export class HookBridgeServer {
                 // stops reading and releases the FD instead of lingering half-open — a
                 // post-response client write can no longer reach a second dispatch.
                 const data = Buffer.concat(chunks).toString("utf8"); // decode once, whole
-                socket.end(JSON.stringify(result ?? (await this.handleSafely(data))), () => socket.destroy());
+                const { exitCode, stdout, stderr } = result ?? (await this.handleSafely(data));
+                const envelope = inertRecord({ exitCode, stdout, stderr });
+                socket.end(JSON.stringify(envelope), () => socket.destroy());
             };
             socket.on("data", (chunk) => {
                 // Count raw bytes and fail open the instant the request envelope crosses