@with-logic/elwood 0.1.1 → 0.1.2

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

@@ -0,0 +1,170 @@
+## 5.9 Recurring session loops
+
+Elwood, not either wrapped CLI, owns recurring prompt scheduling. Claude and
+Codex expose the same typed operations on their raw session APIs, the common
+`ElwoodAgentSession` surface, and the lazy session classes. No operation forwards
+an adapter-native scheduling command.
+
+```ts
+type ElwoodLoopRequest =
+  | {
+      readonly mode: "fixed";
+      readonly intervalMs: number;
+      readonly message: string;
+    }
+  | {
+      readonly mode: "idle";
+      readonly message: string;
+    };
+
+type ElwoodLoopState = "waiting" | "scheduled" | "due" | "submitted";
+
+interface ElwoodLoopSnapshot {
+  readonly id: string;
+  readonly message: string;
+  readonly mode: "fixed" | "idle";
+  readonly intervalMs?: number;
+  readonly jitterMs: number;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  readonly state: ElwoodLoopState;
+  readonly nextDueAt?: number;
+}
+
+type ElwoodLoopEventSnapshot = Omit<ElwoodLoopSnapshot, "message">;
+
+type ElwoodLoopEvent =
+  | {
+      readonly kind: "created";
+      readonly loopId: string;
+      readonly at: number;
+      readonly snapshot: ElwoodLoopEventSnapshot;
+    }
+  | {
+      readonly kind: "fired";
+      readonly loopId: string;
+      readonly scheduledDueAt: number;
+      readonly submittedAt: number;
+      readonly snapshot: ElwoodLoopEventSnapshot & { readonly state: "submitted" };
+    }
+  | {
+      readonly kind: "cancelled";
+      readonly loopId: string;
+      readonly at: number;
+      readonly reason: "caller" | "kill" | "teardown";
+    }
+  | {
+      readonly kind: "expired";
+      readonly loopId: string;
+      readonly at: number;
+    }
+  | {
+      readonly kind: "failed";
+      readonly loopId: string;
+      readonly at: number;
+      readonly phase: "persistence" | "scheduling" | "submission";
+      readonly snapshot?: ElwoodLoopEventSnapshot;
+      readonly code: "loop_persistence_failed" | "loop_submission_failed";
+      readonly message: string;
+    };
+
+declare function parseLoopCommand(command: string): ElwoodLoopRequest | undefined;
+```
+
+All `at`, `createdAt`, `expiresAt`, `nextDueAt`, `scheduledDueAt`, and
+`submittedAt` values are Unix epoch milliseconds. `intervalMs` and `jitterMs`
+are integer milliseconds. `intervalMs` is present only for fixed loops, and
+`nextDueAt` is present only while a live loop is `scheduled`. `listLoops()`
+returns immutable snapshots ordered by `createdAt`, then `id`.
+
+Creation is always explicit. `parseLoopCommand` is a package-root helper for
+callers that choose slash-command UX; it does not schedule anything. It returns
+`undefined` when the input is not an exact `/loop` command. After `/loop`, it
+treats the first whitespace-delimited token as an interval only when the token
+is a positive integer followed by exactly `s`, `m`, `h`, or `d`; it converts
+that token to `intervalMs` and uses the remaining text as the message. Otherwise
+the entire remainder is an idle-loop message. A recognized command with an
+empty or over-limit message, a fixed interval outside the allowed range, or a
+numeric conversion that is not a safe integer fails with `invalid_loop`.
+`sendMessage` and `sendPrompt` never call this parser: `/loop ...` sent through
+either method remains an ordinary literal message.
+
+`createLoop` accepts the same readonly discriminated request. Messages must
+contain between 1 and 65,536 UTF-8 bytes. A fixed `intervalMs` must be an integer
+of at least 60,000 and less than 604,800,000 (seven days). Each session may have
+at most 50 unexpired loop definitions; the fifty-first creation fails with
+`loop_limit_reached` and leaves every existing loop unchanged. Invalid request
+shapes or values fail with `invalid_loop`. Creation requires a live session;
+the lazy classes start under their existing lazy-start contract before creating
+a loop.
+
+Every loop expires exactly seven wall-clock days after its original creation,
+including time when no process is running. A fixed interval close to that
+horizon can therefore expire without submitting once. Each loop receives a
+stable, delay-only jitter offset derived from its ID at creation:
+`0..min(10% of the cadence interval, 30,000 ms)`. For an idle loop the cadence
+interval is the fixed five-minute idle threshold. The offset is never negative,
+so a loop cannot fire earlier than its requested cadence. The exact offset is
+persisted and is authoritative after restore; resume does not re-derive it.
+
+A fixed loop first becomes due one full `intervalMs + jitterMs` after creation.
+After it submits, its next clock begins at the actual submission time, not the
+old phase. An idle loop becomes due after five continuous minutes without
+non-loop session activity, plus its jitter. Any non-loop activity resets every
+idle loop. A loop-generated turn rearms only its originating idle loop, from the
+`ready` transition that completes that turn; it does not reset or restrict peer
+idle loops.
+
+Due work uses the ordinary readiness-safe message path. It observes the current
+session permissions and every blocking-dialog gate at submission time, including
+the effective posture of a resumed session rather than the posture that existed
+when the loop was created. A due loop waits while the session is running,
+blocked, or otherwise unable to accept a message, then submits at most once on a
+ready transition. Missed occurrences never accumulate. Due loops submit
+serially, one committed turn per ready transition, ordered by due time and then
+stable `id`; latency may grow with the number of due loops and agent turn time,
+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.
+
+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
+loop from a fresh cadence unless the session has become non-live, in which case
+the persisted definition waits for resume. Expiry observed before submission
+wins over a pending due state. Live expiry emits `expired`; resume and loop
+management on a stopped or exited session silently prune expired definitions
+before returning.
+
+`cancelLoop` removes one known definition and prevents every future submission.
+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
+methods when no underlying session exists yet.
+
+The `loop` event is live-only and follows the union above. `created` carries a
+redacted snapshot and event time. `fired` carries a redacted `submitted`
+snapshot, scheduled due time, and actual submission time. `cancelled` carries
+only ID, time, and `caller | kill | teardown` reason. `expired` carries only ID
+and time. `failed` carries ID, time, phase, a stable code, a bounded safe message,
+and a redacted snapshot only while the loop remains active. Neither a loop event
+nor an error detail may contain the stored prompt or serialized request; a loop
+is identified only by ID.
+
+`stop`, unexpected agent exit, and parent-process failure preserve definitions
+for resume. A successful `kill` permanently clears every loop definition and
+emits `cancelled` with reason `kill` for live definitions; `teardown` removes the
+sidecar with all other Elwood-owned session state and uses reason `teardown` for
+live definitions. An already-submitted turn is not interrupted merely because
+its originating definition is removed. Resume silently removes definitions that
+expired during downtime, preserves each surviving ID and jitter, discards all
+missed runs, and starts every surviving fixed or idle clock fresh from restored
+session readiness. No catch-up delivery or prior timer phase is restored.
+
+Stable failures are `invalid_loop`, `loop_limit_reached`, `loop_not_found`,
+`loop_persistence_failed`, and `loop_submission_failed`. Write-side persistence
+failures use `loop_persistence_failed`; live scheduling and scheduled-message
+submission failures use `loop_submission_failed` plus the event phase that
+distinguishes them. Sidecar read/ownership/mode failures use `state_corrupt`.

package/prd/05-api/README.md

@@ -0,0 +1,19 @@
+## 5. Public TypeScript API
+
+The package MUST expose its public API from the package root and SHOULD define an
+explicit package `exports` map so consumers do not depend on internal module
+paths. The exact public type names can evolve, but the MVP must expose the
+concepts in this section, including the stable `ElwoodErrorName` union.
+
+
+### Sections
+
+- [5.1 Starting Claude](5.1-starting-claude.md)
+- [5.2 Resuming Claude](5.2-resuming-claude.md)
+- [5.3 ClaudeSessionApi (the raw live session)](5.3-claude-session-api.md)
+- [5.4 Events](5.4-events.md)
+- [5.5 Starting Codex](5.5-starting-codex.md)
+- [5.6 Resuming Codex](5.6-resuming-codex.md)
+- [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)

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

@@ -0,0 +1,164 @@
+## 6. Claude Hook Bridge
+
+### 6.1 Required hook coverage
+
+Elwood MUST configure a hook bridge for every Claude Code hook event supported
+by the installed Claude Code version, including at minimum:
+
+- `SessionStart`
+- `Setup`
+- `InstructionsLoaded`
+- `UserPromptSubmit`
+- `UserPromptExpansion`
+- `PreToolUse`
+- `PermissionRequest`
+- `PostToolUse`
+- `PostToolUseFailure`
+- `PostToolBatch`
+- `PermissionDenied`
+- `Notification`
+- `SubagentStart`
+- `SubagentStop`
+- `TaskCreated`
+- `TaskCompleted`
+- `Stop`
+- `StopFailure`
+- `TeammateIdle`
+- `ConfigChange`
+- `CwdChanged`
+- `FileChanged`
+- `WorktreeCreate`
+- `WorktreeRemove`
+- `PreCompact`
+- `PostCompact`
+- `SessionEnd`
+- `Elicitation`
+- `ElicitationResult`
+
+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.
+
+### 6.2 Routing
+
+Each launched Claude process receives an Elwood session identifier in its
+environment as `ELWOOD_SESSION_ID`. The hook bridge reads that identifier and
+uses it to route hook invocations to the owning Elwood runtime over local IPC.
+
+The IPC transport is an implementation detail, but it MUST be local-only and
+session-scoped. A Unix domain socket is the preferred initial design on macOS.
+The bridge must authenticate or validate that it is talking to the expected
+local Elwood runtime, for example through an unguessable per-session token stored
+in the generated settings/environment.
+Bridge request framing must wait for a complete request before dispatching. A
+partial JSON chunk must not be interpreted as a complete hook invocation, and a
+malformed complete request must fail open with a typed hook error.
+A request with a missing or mismatched session token must also fail open without
+dispatching to parent handlers. Token mismatches are treated as unauthenticated
+local IPC noise, not as hook handler failures.
+
+### 6.3 Fail-open behavior
+
+The hook bridge is fail-open by default.
+
+If no parent handler is registered for a hook event, Elwood returns the same
+observable result Claude would receive if no hook existed.
+
+If the bridge cannot identify a hook event name from malformed input, Elwood
+emits `hookError.hookEventName: "Unknown"` and fails open.
+
+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.
+
+Fail-open does not mean silent. `hookError` must include:
+
+- `elwoodSessionId`
+- hook event name
+- error category
+- timeout duration when applicable (only for a genuine timeout, never for a
+  handler that throws or rejects)
+- a diagnostic message
+
+It must not persist the full hook payload by default.
+
+Elwood's `hookTimeoutMs` is the deadline that decides a handler timeout. The
+per-hook `timeout` written into the generated Claude settings (the CLI's own
+kill switch for the hook process) is `ceil(hookTimeoutMs / 1000) + 5` seconds:
+the CLI's clock starts when it spawns the hook process, before the bridge has
+connected and Elwood's deadline has started, so an equal value would let the CLI
+kill the hook just before Elwood's fail-open "no decision" reply arrived. The
+margin keeps Elwood the party that times out, so the parent always observes its
+typed `hookError` rather than an opaque CLI-side hook failure.
+
+The bridge caps the size of a single hook request at 8 MiB (8,388,608 bytes). The
+cap is measured on the SAME thing in both places: the encoded wire envelope (the
+`{token, elwoodSessionId, input}` JSON plus its framing newline), counted in the
+child bridge script before it connects and in the parent IPC server as bytes
+arrive — so an escape-heavy input whose JSON encoding expands past the ceiling is
+rejected identically by both, never accepted by the child only to be dropped by
+the server. The child additionally bounds raw stdin buffering at the same ceiling
+as an OOM guard (the wrapped envelope can only be larger, so raw input past the cap
+can never yield a valid request). The cap is enforced before any authentication or
+parsing. A request whose encoded envelope exceeds the cap fails open immediately:
+the child bridge script emits no decision and exits, and the parent server responds
+with no decision and closes the connection without dispatching to any parent
+handler. An oversized request is unauthenticated local IPC noise and does not emit
+a `hookError`, matching the token-mismatch fail-open.
+
+### 6.4 Typed hook responses
+
+Elwood MUST model Claude hook inputs and outputs as discriminated TypeScript
+unions.
+
+- `hook_event_name` narrows the event payload.
+- For tool events, `tool_name` narrows `tool_input` and response shape.
+- Known Claude built-in tools must be typed as strongly as Claude's documented
+  schemas allow.
+- 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.
+
+Invalid states should be unrepresentable where TypeScript can enforce that. For
+example, a `Notification` handler should not be able to return a blocking
+decision, while a `PreToolUse` handler can return `allow`, `deny`, `ask`,
+`defer`, `updatedInput`, and/or `additionalContext` according to Claude's rules.
+`PreToolUse` may also return `additionalContext` without a permission decision.
+Typed `updatedInput` rewrites MUST be authored through a tool-keyed handler such
+as `PreToolUse.Bash` or `PreToolUse.AskUserQuestion`, so the returned input
+rewrite is checked against that exact tool's input type. The event-name
+`PreToolUse(event)` handler form may return permission decisions or context, but
+must not expose `updatedInput`. Elwood must also validate returned
+`updatedInput` against the actual tool input shape for known tools before
+serializing it.
+
+Claude hook response support also includes:
+
+- `PermissionRequest` may return `allow` or `deny`, optional `updatedInput`,
+  `updatedPermissions`, `message`, or `interrupt`.
+  Typed `updatedInput` rewrites follow the same tool-keyed handler rule as
+  `PreToolUse`.
+- `PermissionDenied` may return `{ retry: true }`.
+- context hooks such as `SessionStart`, `Setup`, and `SubagentStart` may return
+  `additionalContext`, `initialUserMessage`, or `watchPaths`.
+- `PostToolUse` may return `additionalContext`, `updatedToolOutput`, or
+  `updatedMCPToolOutput`, or block with a reason. Every field is optional, so
+  an empty object is a valid no-op result (as it is for the context hooks).
+- `WorktreeCreate` may return `{ worktreePath: string }`.
+- `TeammateIdle`, `TaskCreated`, and `TaskCompleted` may return
+  `{ continue: false, stopReason? }`.
+
+### 6.5 Readiness
+
+The `Stop` hook is the canonical signal that a Claude turn completed and the
+session is ready for the next prompt. If a `Stop` handler blocks stopping and
+returns feedback to Claude, Elwood must not mark the session ready.
+
+The headless terminal screen model may be used for startup automation,
+environment warnings, diagnostics, or UI hints. On a **cold start** it is not the
+source of truth for readiness — a rendered composer there is only a placeholder
+and the hook/deadline path decides readiness. **On resume this is relaxed** (see
+§5.3 and C-API-28): because the input loop is already live, the first rendered,
+quiet, non-blocking composer frame is an accepted readiness source, racing the
+readiness hook and the deadline. A blocking dialog on that frame does not mark
+ready.

package/prd/07-claude-policy.md

@@ -0,0 +1,15 @@
+## 7. Claude Tool And Permission Policy
+
+`startClaude` MUST accept options for Claude launch policy, including permission
+mode and allowed/disallowed tools. Elwood translates these options to Claude
+Code-supported CLI flags or generated settings.
+
+Hook handlers remain the mechanism for dynamic policy. The two approaches are
+complementary:
+
+- launch policy narrows Claude's baseline capability;
+- hooks observe and control individual lifecycle events and tool calls.
+
+`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.

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

@@ -0,0 +1,76 @@
+## 7A. Codex Hook Bridge And Policy
+
+### 7A.1 Required hook coverage
+
+Elwood MUST configure a hook bridge for every documented Codex hook event,
+including at minimum:
+
+- `SessionStart`
+- `SubagentStart`
+- `PreToolUse`
+- `PermissionRequest`
+- `PostToolUse`
+- `PreCompact`
+- `PostCompact`
+- `UserPromptSubmit`
+- `SubagentStop`
+- `Stop`
+
+### 7A.2 Typed hook responses
+
+Elwood MUST model Codex hook inputs and outputs as discriminated TypeScript
+unions.
+
+- `hook_event_name` narrows the event payload.
+- For tool events, `tool_name` narrows known tool inputs for `Bash` and
+  `apply_patch`; MCP tools use their raw `mcp__*` names, and other future raw
+  Codex tool names are normalized to `unknown:<raw-name>` before dispatch so
+  known-tool narrowing remains reliable while preserving a safe generic input
+  path.
+- `PreToolUse` may deny, allow, allow a rewritten input, or add context
+  according to Codex's current supported response shapes. Typed `updatedInput`
+  rewrites MUST be authored through a tool-keyed handler such as
+  `PreToolUse.Bash` or `PreToolUse.apply_patch`; the event-name
+  `PreToolUse(event)` handler form may return permission decisions or context,
+  but must not expose `updatedInput`.
+- `PermissionRequest` may allow or deny only. Future-only fields such as
+  updated input, updated permissions, and interrupts must be unrepresentable.
+  Serialized output must put `behavior` and optional `message` inside the
+  event-specific `decision` object with `hookEventName`.
+- `Stop` and `SubagentStop` may block completion with a continuation reason and
+  optional additional context, or return `continue: false` with a stop reason
+  and optional additional context.
+- `PostToolUse`, `UserPromptSubmit`, `SubagentStart`, `PreCompact`, and
+  `PostCompact` are observe-only in Elwood's Codex API until Codex documents a
+  stable response contract for those hooks.
+- 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`.
+
+Decision note: Codex `PreToolUse` and `PermissionRequest` both produce
+event-specific JSON under `hookSpecificOutput`, but they do not use the same
+inner shape. `PreToolUse` uses fields such as `permissionDecision` directly
+beside `hookEventName`; `PermissionRequest` nests `{ behavior, message? }` under
+`decision`. Elwood mirrors the current Codex hook protocol instead of normalizing
+these shapes on the wire.
+
+### 7A.3 Readiness
+
+For Codex, `Stop` is the canonical signal that a turn completed. If a `Stop`
+handler returns a continuation/blocking decision, Elwood must not mark the
+session ready. Before an unblocked Codex `Stop` marks the session ready, Elwood
+should read the committed live transcript data with one bounded per-pass scan
+(the same bounded read the poll timer performs, never the terminal-drain budget
+reserved for PTY exit) so parent applications receive transcript-derived turn
+activity before the ready transition whenever Codex has already written it.
+
+### 7A.4 Non-Hook Transcript Activity
+
+Current Codex hooks do not cover every TUI-visible activity. Reasoning/status
+updates and non-shell/non-MCP tools such as web search can appear in Codex's TUI
+and transcript without triggering `PreToolUse` or `PostToolUse`.
+
+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.

package/prd/08-state.md

@@ -0,0 +1,127 @@
+## 8. State And Persistence
+
+### 8.1 State directory
+
+By default, Elwood stores session metadata under:
+
+```text
+<cwd>/.elwood/
+```
+
+Callers may override this with `stateDir`. Relative `stateDir` values MUST be
+resolved to absolute paths before state is written or read, so equivalent path
+spellings address the same session store. When Elwood initializes the default
+project-local state directory, it should create `.elwood/.gitignore` when that
+file does not already exist. Elwood MUST NOT overwrite an existing gitignore
+file and MUST NOT create gitignore files in caller-provided custom state
+directories unless a future explicit option asks it to.
+The default `.elwood/` directory and generated `.elwood/.gitignore` should be
+readable by normal local tooling, while session-specific subdirectories remain
+private.
+
+Before creating or changing state, Elwood MUST reject a symlink at the state
+root, sessions directory, or session directory, and reject user-owned symlink
+ancestors that redirect those paths. System-owned path aliases (such as macOS
+`/tmp`) remain supported. Directory permission changes and generated-file writes
+MUST use no-follow descriptors and verify ownership/type before changing them.
+Unsafe state paths fail as `state_corrupt` before touching the linked target.
+These checks protect against planted checkout paths; they do not isolate a
+hostile process already running as the same OS user.
+
+The hook bridge's Unix domain socket MUST NOT live under `stateDir`. Socket
+paths are capped near 104 bytes on macOS (`sockaddr_un.sun_path`), so a socket
+inside a caller-structured `stateDir` breaks any parent app with nested state
+layouts. Instead, each session has a STABLE Elwood-owned private (0700) socket
+home directory under the OS temp dir, named by a bounded, collision-resistant
+fingerprint of the session's full identity — its `stateDir`, adapter, and session
+id — so every start/resume of that session resolves the SAME home even after a
+parent restart (the record persists nothing about it), while two sessions that
+share an explicit session id in different state dirs get DISTINCT homes and can
+never sweep each other's live socket. Each
+launch binds a FRESH socket FILE inside that home, so a stale socket is never
+reused; the socket path is a per-launch runtime value, embedded only in the generated
+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`
+length MUST NOT constrain whether a session can start.
+
+### 8.2 Session record
+
+The schema-version-1 core session record persists only the minimum needed to
+resume or tear down a session after
+the parent app restarts. The persisted record is deliberately small: everything a
+running session needs beyond it is regenerated at each start/resume. Runtime
+bridge scripts contain the fresh IPC token and socket path in owner-only files. The persisted fields are exactly:
+
+- schema version;
+- `elwoodSessionId`;
+- adapter kind (`claude` or `codex`);
+- original `cwd`;
+- per-adapter resume state: the CLI's own internal conversation id needed to
+  resume, and the resolved launch posture (the privilege and tool-policy options
+  the session was launched with — `permissionMode`, `allowedTools`,
+  `disallowedTools`, `tools` for Claude; `sandbox`, `approvalPolicy` for Codex),
+  so resume re-derives its launch configuration and cannot silently loosen
+  privileges.
+
+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
+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
+socket path is never read back.
+
+Elwood-generated session directories MUST be private to the current user
+(`0700`), and generated settings, bridge scripts, and session records MUST be
+written as private files (`0600`) because they can contain local IPC credentials.
+State writes MUST be rename-atomic and fsync-backed where the platform supports
+it. Crash recovery is a product requirement.
+Session records are not intended to be portable across unrelated state
+directories. Session IDs are opaque path components: absolute paths, path
+separators, and traversal segments are invalid.
+
+Loop definitions are stored separately so existing schema-version-1 session
+records remain backward-readable. A versioned loop sidecar under the same
+owner-only session directory contains exactly each validated loop's stable ID,
+mode, message, fixed interval when applicable, stable jitter, creation time, and
+expiration time; it contains no timer, due state, submission state, or prior
+phase. An absent sidecar means that the session has no loops. The sidecar uses
+rename-atomic, fsync-backed writes under the same crash-recovery rules and MUST
+be mode `0600`. On every read Elwood rejects malformed data, a sidecar not owned
+by the current user, or any group/world permission bits as `state_corrupt`; it
+must never restore or execute those definitions.
+
+### 8.3 What must not be persisted by default
+
+Elwood MUST NOT persist raw PTY input/output, ordinary prompts, terminal
+transcripts, hook payloads, hook responses, or conversation content by default.
+The exact prompt in a caller-created loop is an explicit, narrow exception: it
+is durable automation state in the loop sidecar, not an observed chat transcript.
+
+Hook events are live-only by default. Terminal data is live-only by default.
+
+Parent applications may implement their own logging outside Elwood, but Elwood's
+core state must not become a transcript store.
+
+### 8.4 Cleanup
+
+Runtime files needed for resume/debugging are kept by default after `stop`.
+Loop definitions are likewise kept after `stop`, unexpected exit, or process
+failure. `kill` permanently removes all loop definitions while preserving the
+ordinary session record; a later resume has no loops.
+
+`teardown` removes all Elwood-owned traces for that session, including session
+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.