@with-logic/elwood 0.1.2 → 0.2.0

package/prd/12a-cli.md

@@ -86,10 +86,15 @@ launch, persona setup, and the user turn. Signal handlers are active before
 launch. The first `SIGINT` requests interruption and cleanup, a repeated
 `SIGINT` force-kills the process tree, and an interrupted invocation exits 130.
 
-A new invocation tears down its Elwood-owned state after every outcome; teardown
-does not undo workspace changes or remove history owned by the underlying agent.
-`--keep` instead preserves it after stop-or-kill cleanup and reports its session
-ID on stderr in text mode. A resume uses `--resume <id>` to load exactly the
+New and resumed headless runs preserve their Elwood-owned state after every
+outcome by default, after stop-or-kill cleanup. `--keep` explicitly selects this
+default. `--ephemeral` instead requests teardown for either a new or resumed
+run; it cannot be combined with `--keep`. Teardown does not undo workspace
+changes or remove history owned by the underlying agent. A preserved run reports
+its resumable session ID on stderr in text mode only when `--show-session-id`
+is supplied. By default, successful text output contains only the agent response;
+`elwood sessions` lists retained IDs. The flag affects only the text footer, not
+the `sessionId` field in JSON/JSONL, and emits nothing for ephemeral sessions. A resume uses `--resume <id>` to load exactly the
 stored adapter and cwd; it never falls back to a new conversation, and `--cwd`
 is therefore rejected with `--resume` rather than overriding the stored
 workspace. Explicit adapter conflicts are usage errors. Before launch, resumed state and its cwd MUST satisfy the private,
@@ -117,11 +122,13 @@ stacks, bridge credentials, and terminal escape sequences.
 
 Text is the default output. It writes the combined assistant response — every
 observed assistant text message in order, separated by one blank line — with one
-trailing newline when non-empty and zero bytes for an empty response. Concise,
-sanitized warnings are written to stderr by default for text and JSON runs;
-JSONL represents them only as ordered warning records to avoid duplicate
-diagnostics. `--verbose` adds concise elapsed-time phase, tool-name, and cleanup
-progress to stderr without replaying assistant or thinking text. `--debug` emits
+trailing newline when non-empty and zero bytes for an empty response. Live session
+warnings are quiet by default for text and JSON runs, including model probes.
+`--verbose` enables concise sanitized warnings and elapsed-time phase, tool-name,
+and cleanup progress on stderr without replaying assistant or thinking text.
+`--debug` also enables warnings. JSONL always represents warnings as ordered
+records without duplicating them on stderr. Fatal errors and `sessions` warnings
+about omitted unreadable records remain visible without verbosity. `--debug` emits
 full sanitized normalized event details to stderr and is intended for diagnosis
 rather than routine progress. `--stream` is text-only, emits assistant chunks once with one
 blank line between distinct messages, preserves partial output on failure, and
@@ -254,8 +261,11 @@ final nonzero result.
 While attached, Elwood temporarily puts terminal stdin into raw mode and
 discards ordinary keyboard, mouse, paste, and terminal-response bytes: v1 head
 mode is observational, not interactive. Every Ctrl-C byte follows the same
-first-interrupt/repeated-force-kill lifecycle as SIGINT. On every normal,
-failure, timeout, or interruption outcome, Elwood MUST remove its input and
+first-interrupt/repeated-force-kill lifecycle as SIGINT. The mirror MUST stay
+attached through session cleanup, so PTY output received before the run ended —
+including the tail that runtime cleanup drains (§9.4) — reaches the display
+rather than being discarded with a still-pending render batch. After cleanup, on
+every normal, failure, timeout, or interruption outcome, Elwood MUST remove its input and
 resize listeners, restore terminal stdin's prior raw/cooked mode, flush pending
 display writes, reset attributes, disable mouse and bracketed-paste modes, show
 the cursor, and leave the alternate screen before emitting the final stdout
@@ -298,8 +308,8 @@ nothing to stdout, one concise notice naming the state directory to stderr, and
 exits 0. JSON output is exactly one version-1 document
 `{ "schemaVersion": 1, "type": "sessions", "stateDir": "...", "sessions": [...] }`
 whose array may be empty. JSONL is not a listing protocol; selecting it from any
-source is a usage error that names the source. Any other run option or a
-positional word is a usage error.
+source is a usage error that names the source. Any other run option (including
+`--show-session-id`) or a positional word is a usage error.
 
 ### 12A.9 Interactive mode
 
@@ -337,7 +347,7 @@ the agent owns the resumed conversation, later `elwood resume <id>` runs see
 whatever the user said interactively.
 
 `--output json`, `--output jsonl`, `--stream`, `--verbose`, `--debug`, `--head`,
-`--timeout`, `--persona`, `--image`, `--keep`, `--ephemeral`, and `--resume`
+`--timeout`, `--persona`, `--image`, `--keep`, `--show-session-id`, `--ephemeral`, and `--resume`
 are usage errors with `interactive`, and more than one positional word is a usage
 error. A launch that cannot spawn fails with the adapter's not-found error code
 and status 1.
@@ -345,7 +355,7 @@ and status 1.
 ### 12A.10 Model listing
 
 `elwood models [options] [--output <text|json>]` briefly starts a headless
-session for the selected agent — honoring agent, workspace, model, reasoning
+session for each requested agent — honoring workspace, model, reasoning
 effort, timeout, trust, state directory, and adapter posture with normal
 precedence — waits for readiness, drives the agent's own model picker through
 the public `listModels` operation (which opens and cancels the picker and leaves
@@ -354,7 +364,30 @@ runs no persona turn, uses a fresh session identity under the effective state
 directory, and always tears that identity down, so no Elwood state remains
 afterward. Starting the agent is unavoidable and the help text says so.
 
-Text output is an aligned table with a header row: `*` in the first column marks
+Without an explicit `--agent`, the command MUST probe Claude and then Codex
+sequentially, regardless of `ELWOOD_AGENT` or a saved agent default. Each probe
+uses its own adapter settings; adapter-specific flags and environment posture
+settings apply only to their matching adapter. Shared settings apply to both.
+`--timeout` is one budget for the whole command, including settings resolution
+and preparation. Each probe receives only the remaining budget. Once exhausted,
+the next adapter MUST NOT start; available catalogs remain in the partial result. A failed or unavailable adapter MUST NOT
+hide the other adapter’s available models. SIGINT stops the command and MUST
+NOT launch the next adapter. Every started probe is cleaned up before the next.
+
+For combined listings, text includes an `AGENT` column and per-agent errors go
+to stderr. JSON is exactly one document
+`{ "schemaVersion": 1, "type": "models", "agents": [{ "agent": "...", "models": [...] }], "errors": [...] }`.
+`agents` contains successful catalogs (including empty catalogs), and `errors`
+contains the canonical version-1 error records with agent, error, duration, and
+cleanup fields. Both arrays retain probe order. Status is 0 only if both probes
+succeeded; otherwise interruption (130) takes precedence over timeout (124),
+usage errors (2), and other failures (1). Output-protocol errors and global
+config-file read, parse, or schema errors fail before any probe. Adapter-specific
+setting validation failures are recorded for that adapter and permit the other
+adapter to proceed. An explicit `--agent` preserves the single-agent output
+and error contract below. All model probes remain ephemeral.
+
+Single-agent text output is an aligned table with a header row: `*` in the first column marks
 the current model, followed by the id, label, `(default)` when the row is the
 adapter's default, and the description. JSON output is exactly one version-1
 document `{ "schemaVersion": 1, "type": "models", "agent": "...", "models": [...] }`
@@ -362,7 +395,7 @@ whose rows are the `AgentModelOption` objects. Every string is sanitized under
 §12A.3. Failures — timeout (124), interruption (130), blocked prompts, agent
 exit, and picker automation failures — use the existing stderr, error-document,
 and status conventions, and cleanup still runs exactly once. `--stream`,
-`--head`, `--persona`, `--image`, `--keep`, `--resume`, `--ephemeral`,
+`--head`, `--persona`, `--image`, `--keep`, `--show-session-id`, `--resume`, `--ephemeral`,
 positional words, and JSONL output are usage errors.
 
 Listing sessions resolves only state-directory and output settings. Adapter,

package/prd/13-latitude.md

@@ -10,3 +10,92 @@ above:
 - Whether the package runs on Node.js or another compatible JavaScript runtime, as long as the TypeScript API
   contract is met by supported hosts.
 - Internal storage filenames under `.elwood/`.
+
+The documentation site's sprite-load errors identify the failing relative asset
+path, bounded to 200 characters, and retain the underlying error as their cause.
+
+Sprite requests for the same metadata or atlas key share one fetch/decode operation.
+An explicit consumer may cancel without cancelling remaining consumers or silencing
+their automatic failure report. Only the final consumer cancels the underlying
+operation; an abandoned completion cannot publish into a successor request.
+Explicitly retained pages stay alive through delivery and cache eviction until their
+owner releases them, while current/outgoing pose owners remain protected.
+After successful complete animation preparation, the shared idle clip's two shipped
+pages remain leased for that sprite bank's lifetime, so later actions reuse them
+without repeated fetching or decoding. Failed or cancelled preparations do not
+establish this lease. The shared lease is capped at two pages: an idle manifest
+with more pages falls back to ordinary animation/cache ownership.
+The ordinary cache remains capped at four pages; rotation and action pages receive
+no bank-lifetime lease. Disposal releases the shared idle lease together with all
+other resource owners.
+
+Sprite decoder requests may carry an abort signal. Cancellation rejects the
+request promptly, skips requests that have not started decoding, and
+never falls back to another decoder. The internal worker protocol pairs decode
+request IDs with cancellation messages and completion acknowledgements. The page
+owns the waiting queue and sends one request at a time; aborting the active
+request does not release that physical slot until the worker replies. In-flight
+browser bitmap decoding cannot be interrupted; its eventual image is released,
+without terminating the worker or cancelling other requests. Settled requests remove their abort listeners.
+
+Automatic gesture and facing tasks may wait at most eight seconds before delivery.
+Once elapsed time exceeds eight seconds, the next simulation update cancels the
+task before checking asset readiness or silhouette fit. Assets becoming ready
+between updates cannot revive that expired task; delivery at exactly eight seconds
+remains eligible. This limit does not shorten an action already delivered.
+
+### 13.1 Landing-page explicit animation controls
+
+Landing gesture and front/back requests wait for every page of the requested clip,
+idle and rotation before delivering input. Pending explicit loading suppresses
+automatic actions. Requests are ineligible while dragging, holding movement,
+airborne, hanging, climbing, landing, settling, or committed to a pending jump or
+jump wind-up. Eligibility is checked before loading and again before delivery.
+
+A request accepted into an existing gesture's recovery queue retains its delivered
+pages until playback activation or replacement. Activation owns the requested clip
+before the opening turn paints. Held movement that clears the recovery queue also
+releases its delivered request. Reset, responsive reflow and supersession cancel
+pending/delivered work while preserving active/outgoing poses; reflow preserves
+held movement. Superseding a gesture/facing request preserves unrelated pending
+input such as a jump press. Workshop paths retain on-demand loading; automatic moments and facing follow
+§13.3, and suspended pickup follows §13.4.
+
+### 13.2 Landing-page initial animation readiness
+
+The landing page keeps its static fallback until every initial idle page is decoded
+and retained for playback. Initial preparation fetches idle only; rotation and other
+clips remain on demand. The live readiness callback and first painted handoff occur
+only after complete idle preparation. Input and visibility changes before readiness
+do not cancel initial preparation. Teardown cancels it and prevents a late handoff.
+An asset failure reports the existing contextual error and preserves the fallback;
+a later explicit boot attempt may retry. Idle pages remain available through cache
+eviction and later playback changes through the shared idle lease, with
+current/outgoing pose ownership preserved.
+
+### 13.3 Automatic gesture and facing readiness
+
+Automatic moments and facing actions wait for all requested, idle and rotation
+pages before delivering input. Their post-delivery clock starts only when complete
+preparation succeeds. The existing eight-second pre-delivery wait bounds loading;
+expiry cancels that task without reporting an asset failure. Geometry probes remain
+metadata-only and share existing loads. Publication requires the exact prepared
+candidate, or the same complete active owner with no newer candidate/delivery.
+Task replacement, manual takeover, reset/reflow and teardown release obsolete
+metadata/preparation consumers. Cancellation removes a matching queued delivery,
+but cannot release a newer manual request or active/current/outgoing playback.
+An automatic asset failure reports once. Failed requested or shared idle/rotation
+assets suppress later automatic attempts that need them, including other actions,
+until explicit preparation clears the relevant failure state. Unchanged paint ticks
+cannot retry or republish a failed or superseded task. Walking remains on demand.
+
+### 13.4 Landing-page pickup readiness
+
+Pickup takes pointer/keyboard control immediately while the current drawable clip
+continues playing. Suspended wriggle (or zero-gravity fallback) starts at time zero
+only after all its sheets and idle/rotation dependencies are ready and owned by
+that drag. Pointer movement preserves preparation. Drop, pause, reset, reflow and
+teardown cancel pending pickup; a late completion cannot start obsolete playback.
+Current/outgoing poses remain retained. Failure reports once for the current drag;
+movement and painting do not retry, but a new drag may retry. Falling and landing
+transitions retain their existing on-demand behavior.