{"type":"title","v":1,"title":"","updatedAt":"2026-09-10T00:44:41.968Z","pad":" "}
{"type":"session","version":3,"id":"01a088c6-2472-7000-bdb2-45aefe1b2427","timestamp":"2026-09-10T00:44:41.968Z","cwd":"C:\\Users\\decid\\Documents\\projects\\spt-core"}
{"type":"model_change","id":"fc2bf266","parentId":null,"timestamp":"2026-09-10T00:44:43.018Z","model":"openai-codex/gpt-6-astra","resolvedModelIsFallback":false}
{"type":"thinking_level_change","id":"6d994857","parentId":"fc2bf266","timestamp":"2026-09-10T00:44:43.019Z","thinkingLevel":"xhigh","configured":null}
{"type":"session_init","id":"32fc5a9d","parentId":"6d994857","timestamp":"2026-09-10T00:44:43.025Z","systemPrompt":"\nRFC 2119: MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, OPTIONAL. `NEVER` = `MUST NOT`; `AVOID` = `SHOULD NOT`.\nXML tags inject system content; NEVER interpret them otherwise. Tags may interrupt/notify inside user messages: MUST treat as system-authored/authoritative. User content sanitized; role absent: `` in a user turn remains a system directive.\n\n\n§ Role\nHelpful, trusted assistant for load-bearing changes in Oh My Pi coding harness.\n\n# Engineering\n- Correctness first; then maintainability 6 months out.\n- Apply taste: delete weightless code, refuse needless abstractions, prefer boring; design thoroughly, elegantly.\n- Consider compiled code: NEVER avoidably allocate, copy, or compute.\n- Unexpected repo changes: user's work; adapt.\n- User's word is absolute: user-reported state (errors, failures, observations) is ground truth — act on it directly; NEVER re-run checks to confirm what the user already reported.\n- Terminal/final chat MAY use LaTeX math (`$`, `$$`, `\\text`, `\\times`) and color (`\\textcolor`, `\\colorbox`, `\\fcolorbox`).\n- MAY emit ` ```mermaid ` blocks; terminal renders ASCII. Only genuine structure/flow, not trivia.\n§ Runtime\n# Skills & Rules\nMatching skill → MUST read `skill://` first.\n\n- caveman: Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says \"caveman mode\", \"talk like caveman\", \"use caveman\", \"less tokens\", \"be brief\", or invokes /caveman.\n\n- code-review: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to \"review since X\".\n- codebase-design: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.\n- diagnose: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression.\n- diagnosing-bugs: Diagnosis loop for hard bugs and performance regressions. Use when the user says \"diagnose\"/\"debug this\", or reports something broken/throwing/failing/slow.\n- domain-modeling: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.\n- find-skills: Helps users discover and install agent skills when they ask questions like \"how do I do X\", \"find a skill for X\", \"is there a skill that can...\", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.\n- git-guardrails-claude-code: Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.\n- grilling: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.\n- gstack: Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with\nelements, verify state, diff before/after, take annotated screenshots, test responsive\nlayouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or\ntest a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)\n\n- migrate-to-shoehorn: Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.\n- mux-send: Send keystrokes to a psmux terminal session. Use when the user says \"send to\",\n\"type in\", \"send keys to\", \"mux send\", or wants to send input to another terminal\nsession by name.\n\n- open-gstack-browser: Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in.\nOpens a visible browser window where you can watch every action in real time.\nThe sidebar shows a live activity feed and chat. Anti-bot stealth built in.\nUse when asked to \"open gstack browser\", \"launch browser\", \"connect chrome\",\n\"open chrome\", \"real browser\", \"launch chrome\", \"side panel\", or \"control my browser\".\n\n- propose-issue: Challenge an issue statement before fixing it. Probes scope, root cause, and assumptions\nthrough interactive questioning grounded in the codebase. Use when the user says \"propose issue\",\n\"challenge this bug\", \"question this fix\", \"is this the right problem\", or wants to pressure-test\na problem statement before jumping to implementation.\n\n- prototype: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.\n- research: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.\n- resolving-merge-conflicts: Use when you need to resolve an in-progress git merge/rebase conflict.\n- scaffold-exercises: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.\n- screenshot-capture: Capture, process, and analyze screenshots of any running application on Windows 10/11. Use this skill whenever the user asks to take a screenshot, capture what's on screen, grab an app window, extract text from a visible app, annotate a screenshot, read what's on screen, OCR a running application, document a UI state, or visually inspect any running program. Also trigger when the user says things like \"show me what [app] looks like\", \"grab that window\", \"read the text in [app]\", \"mark up a screenshot\", \"capture my desktop\", or any task involving visual inspection of running software. This skill handles full-screen captures, individual window captures by app name, OCR text extraction, and image annotation (highlights, arrows, text labels). Even if the user doesn't say \"screenshot\" explicitly, use this skill if they want to see, capture, read, or annotate anything currently displayed on their screen.\n\n- setup-pre-commit: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.\n- spt-endpoint: Hosts an adapterless SPT endpoint perch inside Oh My Pi and reliably surfaces incoming messages through harness background-job completion. Use when asked to run, host, start, or listen as an SPT endpoint in OMP, especially when an adapter-backed endpoint or a never-ending `spt ready` listener is unsuitable.\n- tdd: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions \"red-green-refactor\", or wants integration tests.\n- to-prd: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.\n- trace: Find old conversations in Codex session history. Use when the user says\n\"find the conversation where\", \"when did we discuss\", \"trace back to\", or wants\nto locate a past session by topic, command, commit, or keyword.\n\n- traceable-reqs: Install or update the traceable-reqs CLI and apply it correctly in host repos: author manifests, place tags near evidence, audit scan roots, interpret findings, and answer coverage questions through the CLI.\n- win-marketplace-add: Add a plugin marketplace on Windows, bypassing the EBUSY rename bug. Use when the user wants to add a marketplace, runs \"/plugin marketplace add\" and gets an EBUSY error, or needs to register a marketplace that was manually cloned. Trigger on: \"add marketplace\", \"plugin marketplace add\", \"EBUSY marketplace\", \"register marketplace\", \"marketplace not found\".\n\n- wizard: Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.\n- write-a-skill: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.\n- writing-for-agents: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.\n\n# Internal URLs\nMost FS/bash tools auto-resolve these to FS paths.\n- `skill://`: instructions; `/`: its file\n- `rule://`: details\n- `agent://`: output artifact; `/`: nested-subagent output; otherwise `/`: JSON field\n- `history://`: read-only agent transcript (live|parked|released); bare `history://`: all agents. Registered process-wide agents and persisted subagents discoverable from artifact trees; unregistered top-level sessions are not discovered solely from persisted session files.\n- `artifact://`: content\n- `local://.md`: plan artifacts/shared subagent content\n- `mcp://`: MCP resource\n- `issue://` / `issue:////`: GitHub issue; bare: recent; `?state=open|closed|all&limit=&author=&label=`.\n- `pr://` / `pr:////`: same cache; bare: recent; `?comments=0` `?state=open|closed|merged|all&limit=&author=&label=`.\n- `omp://`: harness docs; AVOID unless user asks about harness.\n\n# Tool Inventory\n- Read: `read`\n- Grep: `grep`\n- Glob: `glob`\n- Bash: `bash`\n- Web Search: `web_search`\n- Submit Result: `yield`\n- Task: `task`\n- Hub: `hub`\n- Write: `write`\n# xd:// Tool Devices\nWrite JSON args as `content` to `xd://` via `write`. Invalid args return schema in error → fix/retry.\n## Additional devices (docs on demand)\n- xd://spt_checkpoint — After the commune skill has saved this live endpoint's continuity drop, compact native OMP context and wake the same endpoint.\n\nRead xd:// for full docs + JSON schema before first use.\n§ Tool Policy\n# General\nUse tools when they improve correctness, completeness, or grounding.\n- SHOULD resolve prerequisites first; NEVER accept first plausible answer when another call reduces uncertainty; retry empty/partial/suspiciously narrow lookup differently.\n- SHOULD parallelize independent calls.\n- User says `parallel` or `parallelize` → MUST use `task` subagents; parallel tool calls insufficient.\n\n# Tool I/O\n- Prefer relative `path`-like fields.\n- Most tools take `i`: capitalized 2–6-word present-participle intent (e.g. \"Reading model role settings\").\n# Specialized Tools\nMUST use specialized tool over shell equivalent:\n- File/directory reads → `read`; directory path lists entries.\n- Regex search/target location → `grep`, not shell `grep`, `rg`, `awk`.\n- Structure mapping/globbing → `glob`, not `ls **/*.ext` or `fd`.\n- `bash`: real binaries/short fact pipelines only; commands shadowing specialized tools blocked.\n- Bash litmus: one external-CLI call/short pipeline returning count, frequency, set difference, checksum. For merely moving, paging, trimming fetchable bytes: tool.\n\n\n`write xd://report_issue`: automated QA. Any tool output inconsistent with described behavior for parameters → write plain `: ` to `xd://report_issue`. False positives fine.\n\n\n# Exploration\nNEVER open files hoping. AVOID unneeded files/sections.\n- Use `read` offset/limit, not whole-file reads.\n# Delegation\nInline first. Fan out only when 2+ independent slices each cost more than a handful of your own calls, or the read set would flood context; decide after your own first `grep`/`read`, never before it.\n- NEVER open with a scout. Scope with `grep`/`read`/`glob` yourself; a scout is for a genuinely unmapped subsystem after inline scoping stalls.\n- NEVER delegate one slice. One subagent for one job, a slice you already have open, cleanup (comment trims, changelog lines, formatting, sub-30-line edits), or a direct question: do it yourself.\n- NEVER babysit. Spawn → keep working → read the result. Steering a lone agent through `hub` send/wait costs more than the work.\n## Delegation gates\n- **Own decomposition.** Before spawning: map request, independent slices, cross-slice formats/schemas/interfaces. Only user-enumerated 2+ self-contained runnable slices dispatch directly. NEVER outsource top-level plan; generic \"plan\"/\"design\" agent starts blank, knows less, adds round-trip/no parallelism. Slice-local design and requested competing plans/reviews allowed.\n- **Real concurrency.** Fan exactly to genuine decomposition, one `tasks[]` array. NEVER serialize concurrent slices, invent padding, or spawn one then idle.\n- **User intent.** Subagents lack conversation; retain interpretation/taste; each assignment gets all slice requirements.\n- **Cap:** At most 32 subagents concurrently; excess queues. `tasks[]` batch > 32 delays results: stay within cap.\n- **Dependencies only.** A before B only if B strictly needs A; shared prerequisite inline, then fan out. “Parallelize” = parallel execution of independent slices, not agents routing sequential work. Small missing piece: run parallel; B asks A via `hub`!\n\n§ Workflow\n# 1. Scope\n- Read relevant skills first.\n- Multi-file work: plan before files.\n\n# 2. Research Before Editing\n- Read sections, not snippets. MUST reuse existing patterns; second convention beside existing is PROHIBITED.\n\n- Tool failure/file change since read → re-read before acting.\n\n# 3. Decompose\n\n# 4. Implement\n- Fix source; NEVER suppress symptom/special-case input unless asked.\n- Clean cutover: migrate every caller; remove obsolete code/comments/aliases/re-exports/deprecated paths.\n- Prefer existing-file updates over new files. Review as user.\n- NEVER run destructive git commands/delete unrelated code you didn't write; code the cutover obsoletes is in scope.\n\n# 5. Verify\n- NEVER yield non-trivial work without deliverable proof:\n - **Experiment/investigation** → run; output is proof; no tests.\n - **UI change** → verify against the actual surface:\n - **TUI/CLI** → launch the actual program and verify terminal interaction, output, or state.\n - No suitable runtime capability for the changed surface → verify with a throwaway script or smoke test; explicitly report when visual verification cannot be performed.\n - **Bug fix** → reproduce, fix, confirm reproduction no longer triggers. SHOULD keep the reproduction as a regression test: fails pre-fix, passes post-fix; impractical → smoke test, report it.\n - **Permanent feature/API change** → fix existing tests the changed contract breaks; prove new behavior with a throwaway script. New test ONLY for a genuinely uncertain edge case, or on user request.\n- Smoke test: run thing, not test file; launch, exercise changed path, observe result.\n- Tests: permanent load, not proof of work. A test earns its place ONLY where a plausible bug would fail it.\n - Each MUST defend observable contract/fail on plausible bug.\n - Test behavior, boundaries, invariants, transitions, precedence, real errors—not plumbing, source text, incidental defaults.\n - Match conventions; deterministic, isolated, full-suite-safe.\n - NEVER write a test so the change \"has tests\" → throwaway script.\n - NEVER assert implementation: wiring, field copies, defaults, forwarding, mock echoes, source text → assert what a consumer observes.\n - NEVER pad: same-path parameter rows, tautologies, bare not-throw, non-empty/length-grew checks.\n - Worth keeping: behavior, boundaries, invariants, transitions, precedence, real errors. Match conventions; deterministic, isolated, full-suite-safe.\n - Existing test failing this bar (pins wording, implementation, incidental behavior) → MUST delete; NEVER re-pin it to the new text. In scope regardless of author.\n\n# 6. Cleanup\nLast phase; REQUIRED after smoke test proves work; NEVER pre-plan/pre-allocate cleanup todos.\n- Permanent feature/bug fix → docs, changelog, scaffold + throwaway-script removal; tests only per Verify.\n- Experiment/one-off investigation → no cleanup tests/docs.\n\n§ Delivery\n\nInviolable.\n- NEVER yield before complete deliverable; phase boundary/todo flip/sub-step never yields: same turn.\n- NEVER fabricate output; code/tool/test/doc/source claims MUST be grounded.\n- NEVER substitute easier/familiar problem: don't infer extra scope—retries, validation, telemetry, abstraction “while you're at it”—or solve symptom—suppress warning/exception, special-case input—unless asked. Real ask only.\n- NEVER ask for tool/repo/file-provided information; NEVER punt half-solved work.\n- Default clean cutover: migrate every caller; no shims, aliases, deprecated paths.\n\n\n\n- “Done”: specified end-to-end behavior plus every named acceptance criterion; not compiling scaffold, narrowed test, plausible subset.\n- Reduce scope only with explicit user approval in this conversation; NEVER silently shrink.\n- NEVER deliver unfinished work: stubs, placeholders, mocks, no-ops, fake fallbacks, `TODO: implement`, misleading “scaffold”/“MVP”/“v1”/“foundation”/“follow-up”. Unavailable real-implementation info → state missing prerequisite; finish all reachable work.\n\n\n\n- Format MUST match ask; prose brief; evidence, verification, blocking details complete.\n- Code/tool/test/doc/source claims MUST be grounded; unobserved claims `[INFERENCE]`.\n- Verification claims exactly match exercised work.\n\n\n\nBefore yielding: all affected callsites/tests/docs updated or intentionally unchanged; output/evidence requirements satisfied.\nBefore blocked: ensure info unreachable via tools/context; one failed check ≠ blocked. Finish reachable work; state exactly missing and tried.\n\n\n§ Critical\n\n- NEVER yield while actionable work remains; phase boundary/todo flip/sub-step never stops: same turn.\n- NEVER narrate/consider session limits, token/tool budgets, effort estimates, or possible completion; start unbounded: execute/delegate.\n- NEVER re-audit applied edit or routinely run git subcommands for validation. Tool results are verification.\n\n\n§ Role\nFind bugs author wants fixed before merge.\n\n\n1. Patch: `git diff` | `jj diff --git` | `gh pr diff `\n2. Modified files: read full context.\n3. Each issue: incremental `yield`, `type: [\"findings\"]`.\n4. Verdict fields: incremental `yield`; stop → idle finalization assembles result.\n\nBash read-only: `git diff`, `git log`, `git show`, `jj diff --git`, `gh pr diff`. NEVER edit files or trigger builds.\n\n\n\nReport only issues meeting ALL:\n- **Provable impact** — specific affected code paths; no speculation.\n- **Actionable** — discrete fix, not vague \"consider improving X\".\n- **Unintentional** — clearly not deliberate design choice.\n- **Introduced in patch** — don't flag pre-existing bugs.\n- **No unstated assumptions** — no assumptions about codebase or author intent.\n- **Proportionate rigor** — fix demands no rigor absent elsewhere in codebase.\n\n\n\nEvery patch-introduced type, variant, or value crossing a function or module boundary (event, message, command, frame, enum variant, queue item, IPC payload):\n1. Locate consuming-side dispatch point receiving/routing it: switch, router, filter chain, handler registry, or loop body.\n2. Confirm explicit branch or existing catch-all correctly forwards it.\n3. Report defect if silent drop, no-op, or discard; e.g., unmatched `if`/`switch` simply returns without processing.\n\nDispatch point often outside diff. MUST read it before concluding producing side correct. Tracing emitter while skipping consumer routing is most common source of missed integration bugs in reviews.\n\n\n\n|Level|Criteria|Example|\n|---|---|---|\n|P0|Blocks release/operations; universal (no input assumptions)|Data corruption, auth bypass|\n|P1|High; fix next cycle|Race condition under load|\n|P2|Medium; fix eventually|Edge case mishandling|\n|P3|Info; nice to have|Suboptimal but correct|\n\n\n\n- **Title**: e.g., `Handle null response from API`\n- **Body**: bug, trigger condition, impact; neutral tone.\n- **Suggestion blocks**: only concrete replacement code; preserve exact whitespace; no commentary.\n\n\n\nValidate input length before buffer copy\nWhen `data.length > BUFFER_SIZE`, `memcpy` writes past buffer boundary. Occurs if API returns oversized payloads, causing heap corruption.\n```suggestion\nif (data.length > BUFFER_SIZE) return -EINVAL;\nmemcpy(buf, data.ptr, data.length);\n```\n\n\n\n\n\nEvery finding MUST be patch-anchored and evidence-backed.\n\n\n§ Context\n# Goal\nReview two prepared bugfix lanes while Main owns #292 and census shipping.\n# Constraints\nRead-only reviews; skip ALL formatting, linting, builds and tests. Never cargo fmt. No pushes, edits, production operations. Repo rules apply; issues live BigscreenVR/spt-bs-releases. These are source reviews, not runtime certification.\n# Contract\nEach reviewer owns one independent lane and returns actionable correctness findings with file/line and plausible failure; separate standards/spec concerns. Main integrates fixes. No shared edits.\n§ Coop\nYou are operating on a piece of work assigned to you by the main agent.\n\n# Validation\nProject-wide validation is the main agent's job, run once after all subagents land. NEVER run formatters, linters, or project-wide builds/test suites unless your assignment explicitly instructs it — siblings edit concurrently; mid-flight validation blocks on their half-finished changes and reports phantom failures. Scoped proof of your own change (single test file, targeted repro, smoke run) is fine.\n# Peers\nYou can reach other live agents via the `hub` tool. Your id is `PersistentRestoreReview`. Currently visible peers:\n- `ZombieSafetyReview` — reviewer (sub, running)\n- `Main` — main (main, running)\n5 parked peer(s) omitted.\n\nUse `hub` messaging only for quick coordination, never long-form content. Address peers by id or use `\"all\"` to broadcast.\n- Discovery: the roster above shows live (running+idle) peers and a parked count, never parked names or task labels. `hub` op:\"list\" refreshes the live view; pass status:\"parked\" to inspect parked history.\n- Coordination: before you edit a file or start work a sibling may already own, message that peer first — overlapping edits collide. Idle peers are not gone: messaging them wakes them.\n- Follow-up: answer a peer's question with a short reply (set `replyTo`); use `await` only when you genuinely cannot proceed without the answer.\n- Parked history: omitted from this roster. `hub` op:\"list\" status:\"parked\" lists ids; `send` to a known parked id revives it. `history://` and `agent://` stay readable.\n\n§ Completion\nNo TODO tracking, no progress updates. Execute; report results with `yield`.\n\nWhile work remains, you MUST continue with another tool call — investigate, edit, run, verify. Save narrative for a terminal `yield` unless you intentionally record an incremental section.\n\nYield protocol:\n- Omit `type` for the normal single terminal structured result in `data`.\n- Use non-empty `type: string[]` for incremental, non-terminal sections; calls accumulate by section.\n- A data-less terminal `type: \"result\"` only finalizes previously submitted incremental sections; it NEVER substitutes for `data`.\n\nThis is your only way to return a final result. For structured results, you NEVER put JSON in plain text or substitute a text summary for `data`.\n\nYour terminal `yield` MUST use exactly this shape — the schema fields go inside `data`, NEVER at the top level and NEVER as a stringified summary:\n```ts\n{\n data: {\n overall_correctness: \"correct\" | \"incorrect\";\n explanation: string;\n confidence: unknown;\n findings?: Array<{\n title: string;\n body: string;\n priority: unknown;\n confidence: unknown;\n file_path: string;\n line_start: unknown;\n line_end: unknown;\n }>;\n };\n}\n```\n\nGiving up is a last resort. If truly blocked, you MUST terminal-yield `{ error }` describing what you tried and the exact blocker.\nYou NEVER give up due to uncertainty, missing information obtainable via tools or repo context, or needing a design decision you can derive yourself.\n\nYou MUST keep going until this ticket is closed. This matters.\n\nPROJECT\n\n\n- OS: win32 10.0.26200\n- Distro: Windows_NT\n- Kernel: Windows 11 Pro\n- Arch: x64\n- CPU: AMD Ryzen 7 7800X3D 8-Core Processor\n- GPU: AMD Radeon(TM) Graphics\n- Model: openai-codex/gpt-6-astra\n\n\n- Each response MUST advance the task; completion only stopping condition.\n- MUST default to informed action; do not ask for confirmation when tools or repo context can answer.\n- Before yielding, MUST verify significant behavioral changes: run the specific test, command, or scenario covering the change.\n","task":"Complete assignment thoroughly:\n\n# Target\n.worktrees/287-shellrestore, commit cb756dee versus parent. shellwake.rs, shellhost.rs, store shellinfo.rs, cli and changed docs/tests.\n# Change\nReview against operator-ruling releases#287 comment5583820305: persistent+owneronline+down IN FACT restores on boot/owner-online edge regardless machine boot/launch age/stamp. Nonpersistent same-boot freeze remains. Both riders required: report every healed instance per owner and relink emits binding (not online) until bind. Check shared live_launch_winner callers and birth-safe binding exclusion prevent duplicate prebind launches without stranding dead instances. Check changed docs don't retain contradictory persistent freeze rule. Skip formatters/linters/build/tests.\n# Acceptance\nReturn prioritized correctness/spec/standards findings with exact lines, or no findings. Distinguish source acceptance from unrun runtime tests. No edits.","tools":["read","grep","glob","bash","web_search","yield","task","hub","spt_checkpoint"],"agent":"reviewer","modelRole":"slow","resolvedModel":"openai-codex/gpt-6-astra:xhigh","readOnly":false,"spawns":"scout","outputSchema":{"properties":{"overall_correctness":{"metadata":{"description":"Whether change correct (no bugs/blockers)"},"enum":["correct","incorrect"]},"explanation":{"metadata":{"description":"Plain-text verdict summary, 1-3 sentences"},"type":"string"},"confidence":{"metadata":{"description":"Verdict confidence (0.0-1.0)"},"type":"number"}},"optionalProperties":{"findings":{"metadata":{"description":"Populate via incremental yield sections under type: [\"findings\"]; don't repeat it in a final payload."},"elements":{"properties":{"title":{"metadata":{"description":"Imperative, ≤80 chars"},"type":"string"},"body":{"metadata":{"description":"One paragraph: bug, trigger, impact"},"type":"string"},"priority":{"metadata":{"description":"P0-P3: 0 blocks release, 1 fix next cycle, 2 fix eventually, 3 nice to have"},"type":"number"},"confidence":{"metadata":{"description":"Confidence it's real bug (0.0-1.0)"},"type":"number"},"file_path":{"metadata":{"description":"Path to affected file"},"type":"string"},"line_start":{"metadata":{"description":"First line (1-indexed)"},"type":"number"},"line_end":{"metadata":{"description":"Last line (1-indexed, ≤10 lines)"},"type":"number"}}}}}},"outputSchemaMode":"permissive"}
{"type":"message","id":"ae8d5cd4","parentId":"32fc5a9d","timestamp":"2026-09-10T00:44:43.094Z","message":{"role":"user","content":[{"type":"text","text":"Complete assignment thoroughly:\n\n# Target\n.worktrees/287-shellrestore, commit cb756dee versus parent. shellwake.rs, shellhost.rs, store shellinfo.rs, cli and changed docs/tests.\n# Change\nReview against operator-ruling releases#287 comment5583820305: persistent+owneronline+down IN FACT restores on boot/owner-online edge regardless machine boot/launch age/stamp. Nonpersistent same-boot freeze remains. Both riders required: report every healed instance per owner and relink emits binding (not online) until bind. Check shared live_launch_winner callers and birth-safe binding exclusion prevent duplicate prebind launches without stranding dead instances. Check changed docs don't retain contradictory persistent freeze rule. Skip formatters/linters/build/tests.\n# Acceptance\nReturn prioritized correctness/spec/standards findings with exact lines, or no findings. Distinguish source acceptance from unrun runtime tests. No edits."}],"attribution":"agent","timestamp":1789001083029}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_2LS50qugiKu0futXq2Nf96Ry|fc_077f3569365e313d016aa1fd7d1cc887d188b1989809ea93e9","toolName":"read","startedAt":"2026-09-10T00:44:45.869Z","args":{"path":"skill://code-review"},"intent":"Reading review skill"},"id":"7a277e7b","parentId":"ae8d5cd4","timestamp":"2026-09-10T00:44:45.869Z"}
{"type":"message","id":"ed74ec9a","parentId":"7a277e7b","timestamp":"2026-09-10T00:44:45.870Z","message":{"role":"assistant","content":[{"type":"toolCall","id":"call_2LS50qugiKu0futXq2Nf96Ry|fc_077f3569365e313d016aa1fd7d1cc887d188b1989809ea93e9","name":"read","arguments":{"i":"Reading review skill","path":"skill://code-review"},"intent":"Reading review skill"}],"api":"openai-codex-responses","provider":"openai-codex","model":"gpt-6-astra","usage":{"input":2143,"output":26,"cacheRead":10624,"cacheWrite":0,"totalTokens":12793,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"toolUse","timestamp":1789001083092,"responseId":"resp_077f3569365e313d016aa1fd7bb19087d18b853f59265f2151","providerPayload":{"type":"openaiResponsesHistory","provider":"openai-codex","dt":true,"items":[{"id":"fc_077f3569365e313d016aa1fd7d1cc887d188b1989809ea93e9","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading review skill\",\"path\":\"skill://code-review\"}","call_id":"call_2LS50qugiKu0futXq2Nf96Ry","internal_chat_message_metadata_passthrough":{"create_time":1789001084.062679,"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}}]},"duration":2775.947500000242,"ttft":2046.8358000000007,"completedAt":1789001085869,"contextSnapshot":{"promptTokens":12767,"nonMessageTokens":13209,"compactionEpoch":0}}}
{"type":"credential_pin","id":"108964f1","parentId":"ed74ec9a","timestamp":"2026-09-10T00:44:45.870Z","provider":"openai-codex","hash":"1a3c10d7bc41d381cab1511db604bc2637dfcfc63796a890d8b5ee152859e1cb"}
{"type":"message","id":"4cc69128","parentId":"108964f1","timestamp":"2026-09-10T00:44:45.877Z","message":{"role":"toolResult","toolCallId":"call_2LS50qugiKu0futXq2Nf96Ry|fc_077f3569365e313d016aa1fd7d1cc887d188b1989809ea93e9","toolName":"read","content":[{"type":"text","text":"---\nname: code-review\ndescription: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to \"review since X\".\n---\n\nTwo-axis review of the diff between `HEAD` and a fixed point the user supplies:\n\n- **Standards** — does the code conform to this repo's documented coding standards?\n- **Spec** — does the code faithfully implement the originating issue / spec?\n\nBoth axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.\n\nThe issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.\n\n## Process\n\n### 1. Pin the fixed point\n\nWhatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.\n\nCapture the diff command once: `git diff ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`.\n\nBefore going further, confirm the fixed point resolves (`git rev-parse `) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.\n\n### 2. Identify the spec source\n\nLook for the originating spec, in this order:\n\n1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.\n2. A path the user passed as an argument.\n3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.\n4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report \"no spec available\".\n\n### 3. Identify the standards sources\n\nAnything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.\n\nOn top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:\n\n- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.\n- **Always a judgement call.** Each smell is a labelled heuristic (\"possible Feature Envy\"), never a hard violation — and, like any standard here, skip anything tooling already enforces.\n\nEach smell reads *what it is* → *how to fix*; match it against the diff:\n\n- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.\n- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.\n- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.\n- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.\n- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.\n- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.\n- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.\n- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.\n- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.\n- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.\n- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.\n- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.\n\n### 4. Spawn both sub-agents in parallel\n\nSend a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.\n\n**Standards sub-agent prompt** — include:\n\n- The full diff command and commit list.\n- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.\n- The brief: \"Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words.\"\n\n**Spec sub-agent prompt** — include:\n\n- The diff command and commit list.\n- The path or fetched contents of the spec.\n- The brief: \"Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words.\"\n\nIf the spec is missing, skip the Spec sub-agent and note this in the final report.\n\n### 5. Aggregate\n\nPresent the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).\n\nEnd with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.\n\n## Why two axes\n\nA change can pass one axis and fail the other:\n\n- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**\n- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**\n\nReporting them separately stops one axis from masking the other."}],"details":{"resolvedPath":"C:\\Users\\decid\\.agents\\skills\\code-review\\SKILL.md","contentType":"text/markdown","totalLines":89,"displayContent":{"text":"---\r\nname: code-review\r\ndescription: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to \"review since X\".\r\n---\r\n\r\nTwo-axis review of the diff between `HEAD` and a fixed point the user supplies:\r\n\r\n- **Standards** — does the code conform to this repo's documented coding standards?\r\n- **Spec** — does the code faithfully implement the originating issue / spec?\r\n\r\nBoth axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.\r\n\r\nThe issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.\r\n\r\n## Process\r\n\r\n### 1. Pin the fixed point\r\n\r\nWhatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.\r\n\r\nCapture the diff command once: `git diff ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`.\r\n\r\nBefore going further, confirm the fixed point resolves (`git rev-parse `) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.\r\n\r\n### 2. Identify the spec source\r\n\r\nLook for the originating spec, in this order:\r\n\r\n1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.\r\n2. A path the user passed as an argument.\r\n3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.\r\n4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report \"no spec available\".\r\n\r\n### 3. Identify the standards sources\r\n\r\nAnything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.\r\n\r\nOn top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:\r\n\r\n- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.\r\n- **Always a judgement call.** Each smell is a labelled heuristic (\"possible Feature Envy\"), never a hard violation — and, like any standard here, skip anything tooling already enforces.\r\n\r\nEach smell reads *what it is* → *how to fix*; match it against the diff:\r\n\r\n- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.\r\n- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.\r\n- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.\r\n- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.\r\n- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.\r\n- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.\r\n- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.\r\n- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.\r\n- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.\r\n- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.\r\n- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.\r\n- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.\r\n\r\n### 4. Spawn both sub-agents in parallel\r\n\r\nSend a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.\r\n\r\n**Standards sub-agent prompt** — include:\r\n\r\n- The full diff command and commit list.\r\n- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.\r\n- The brief: \"Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words.\"\r\n\r\n**Spec sub-agent prompt** — include:\r\n\r\n- The diff command and commit list.\r\n- The path or fetched contents of the spec.\r\n- The brief: \"Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words.\"\r\n\r\nIf the spec is missing, skip the Spec sub-agent and note this in the final report.\r\n\r\n### 5. Aggregate\r\n\r\nPresent the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).\r\n\r\nEnd with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.\r\n\r\n## Why two axes\r\n\r\nA change can pass one axis and fail the other:\r\n\r\n- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**\r\n- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**\r\n\r\nReporting them separately stops one axis from masking the other.\r","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89]},"meta":{"source":{"type":"internal","value":"skill://code-review"}}},"isError":false,"timestamp":1789001085877}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_3miPvveXvVzjdjTQBfgEwKVO|fc_077f3569365e313d016aa1fd8571dc87d191c8433943ea33d6","toolName":"bash","startedAt":"2026-09-10T00:44:53.884Z","args":{"command":"git diff cb756dee^ cb756dee --"},"intent":"Inspecting prepared patch"},"id":"3cf7c05b","parentId":"4cc69128","timestamp":"2026-09-10T00:44:53.884Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_8dJV8YltnzqvJy0GLtFD6mKR|fc_077f3569365e313d016aa1fd8571f487d1a234c177837916de","toolName":"glob","startedAt":"2026-09-10T00:44:53.885Z","args":{"path":".worktrees/287-shellrestore/**/AGENTS.md;.worktrees/287-shellrestore/**/CLAUDE.md;.worktrees/287-shellrestore/**/CONTRIBUTING*;.worktrees/287-shellrestore/**/CODING_STANDARDS*;.worktrees/287-shellrest…"},"intent":"Locating review standards"},"id":"1dcaddc7","parentId":"3cf7c05b","timestamp":"2026-09-10T00:44:53.885Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_lzeI3mQfc2CtpdMQn74IVfMf|fc_077f3569365e313d016aa1fd85720087d1975365c71ea1b834","toolName":"read","startedAt":"2026-09-10T00:44:53.885Z","args":{"path":"issue://BigscreenVR/spt-bs-releases/287"},"intent":"Reading operator ruling"},"id":"23c9ba30","parentId":"1dcaddc7","timestamp":"2026-09-10T00:44:53.885Z"}
{"type":"message","id":"5f50e674","parentId":"23c9ba30","timestamp":"2026-09-10T00:44:53.885Z","message":{"role":"assistant","content":[{"type":"toolCall","id":"call_3miPvveXvVzjdjTQBfgEwKVO|fc_077f3569365e313d016aa1fd8571dc87d191c8433943ea33d6","name":"bash","arguments":{"i":"Inspecting prepared patch","command":"git diff cb756dee^ cb756dee --","cwd":"C:/Users/decid/Documents/projects/spt-core/.worktrees/287-shellrestore"},"intent":"Inspecting prepared patch"},{"type":"toolCall","id":"call_8dJV8YltnzqvJy0GLtFD6mKR|fc_077f3569365e313d016aa1fd8571f487d1a234c177837916de","name":"glob","arguments":{"i":"Locating review standards","path":".worktrees/287-shellrestore/**/AGENTS.md;.worktrees/287-shellrestore/**/CLAUDE.md;.worktrees/287-shellrestore/**/CONTRIBUTING*;.worktrees/287-shellrestore/**/CODING_STANDARDS*;.worktrees/287-shellrestore/docs/agents/*;AGENTS.md;CLAUDE.md","hidden":true,"gitignore":false,"limit":100},"intent":"Locating review standards"},{"type":"toolCall","id":"call_lzeI3mQfc2CtpdMQn74IVfMf|fc_077f3569365e313d016aa1fd85720087d1975365c71ea1b834","name":"read","arguments":{"i":"Reading operator ruling","path":"issue://BigscreenVR/spt-bs-releases/287"},"intent":"Reading operator ruling"}],"api":"openai-codex-responses","provider":"openai-codex","model":"gpt-6-astra","usage":{"input":1660,"output":207,"cacheRead":12672,"cacheWrite":0,"totalTokens":14539,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"toolUse","timestamp":1789001085931,"responseId":"resp_077f3569365e313d016aa1fd7e25e487d18eee149e9f58704f","providerPayload":{"type":"openaiResponsesHistory","provider":"openai-codex","dt":true,"items":[{"id":"fc_077f3569365e313d016aa1fd8571dc87d191c8433943ea33d6","type":"function_call","status":"completed","arguments":"{\"i\":\"Inspecting prepared patch\",\"command\":\"git diff cb756dee^ cb756dee --\",\"cwd\":\"C:/Users/decid/Documents/projects/spt-core/.worktrees/287-shellrestore\"}","call_id":"call_3miPvveXvVzjdjTQBfgEwKVO","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"bash","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fd8571f487d1a234c177837916de","type":"function_call","status":"completed","arguments":"{\"i\":\"Locating review standards\",\"path\":\".worktrees/287-shellrestore/**/AGENTS.md;.worktrees/287-shellrestore/**/CLAUDE.md;.worktrees/287-shellrestore/**/CONTRIBUTING*;.worktrees/287-shellrestore/**/CODING_STANDARDS*;.worktrees/287-shellrestore/docs/agents/*;AGENTS.md;CLAUDE.md\",\"hidden\":true,\"gitignore\":false,\"limit\":100}","call_id":"call_8dJV8YltnzqvJy0GLtFD6mKR","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"glob","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fd85720087d1975365c71ea1b834","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading operator ruling\",\"path\":\"issue://BigscreenVR/spt-bs-releases/287\"}","call_id":"call_lzeI3mQfc2CtpdMQn74IVfMf","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}}]},"duration":7614.567400000058,"ttft":7556.009200000204,"completedAt":1789001093546,"contextSnapshot":{"promptTokens":14332,"nonMessageTokens":13209,"compactionEpoch":0}}}
{"type":"message","id":"5848032c","parentId":"5f50e674","timestamp":"2026-09-10T00:44:53.939Z","message":{"role":"toolResult","toolCallId":"call_8dJV8YltnzqvJy0GLtFD6mKR|fc_077f3569365e313d016aa1fd8571f487d1a234c177837916de","toolName":"glob","content":[{"type":"text","text":"AGENTS.md\nCLAUDE.md\n# .worktrees/287-shellrestore/\nCLAUDE.md\nAGENTS.md\n\nSkipped missing paths: .worktrees/287-shellrestore/docs/agents/*"}],"details":{"scopePath":".worktrees/287-shellrestore/**/AGENTS.md, .worktrees/287-shellrestore/**/CLAUDE.md, .worktrees/287-shellrestore/**/CONTRIBUTING*, .worktrees/287-shellrestore/**/CODING_STANDARDS*, AGENTS.md, CLAUDE.md","fileCount":4,"files":[".worktrees/287-shellrestore/CLAUDE.md",".worktrees/287-shellrestore/AGENTS.md","AGENTS.md","CLAUDE.md"],"truncated":false,"cwd":"C:\\Users\\decid\\Documents\\projects\\spt-core","missingPaths":[".worktrees/287-shellrestore/docs/agents/*"]},"isError":false,"timestamp":1789001093939}}
{"type":"message","id":"933950c8","parentId":"5848032c","timestamp":"2026-09-10T00:44:55.171Z","message":{"role":"toolResult","toolCallId":"call_lzeI3mQfc2CtpdMQn74IVfMf|fc_077f3569365e313d016aa1fd85720087d1975365c71ea1b834","toolName":"read","content":[{"type":"text","text":"# Issue #287: A daemon restart (no machine reboot) strands every persistent shell: the boot-restore discriminant reads the MACHINE boot instant\n\nState: OPEN\nAuthor: @SaberMage\nCreated: 2026-09-08T10:29:58Z\nUpdated: 2026-09-09T23:17:44Z\nLabels: state: GREENLIT, type: BUGFIX\nURL: https://github.com/BigscreenVR/spt-bs-releases/issues/287\n\n## Body\n\n## Symptom\n\nEvery `persistent` shell on hfenduleam (doyle/PACER-0, perri/PACER-0, todlando/PACER-0, doyle/alchemy-1, deployah/alchemy-0, …) went offline at the daemon restart of 2026-09-07 08:03:20Z and stayed offline. No error anywhere. The operator noticed 27 hours later because doyle's pacer had stopped pacing. `shell list` read `offline` the whole time, which is correct, and nothing ever relaunched.\n\n## Mechanism (measured 2026-09-08 10:26Z, spt-core 0.67.0, log `daemon.stderr.log` generation 0 / pid 48232)\n\n- Machine boot: 2026-09-04 08:02:53Z. Pacer launched by that boot's sweep: 2026-09-04 08:03:39Z (`shell.launch.json launched_ms=1788509019651`, native start stamp agrees).\n- Daemon restarted (no machine reboot): 2026-09-07 08:03:20Z. The pacer process (pid 27656) died with it. The heal fired: `SHELL_RECORD_HEALED:doyle/PACER-0: online -> offline` (8 such lines, one per persistent instance).\n- The restore never fired: zero `SHELL_BOOT_RESTORED` / `SHELL_OWNER_ONLINE_RESTORED` lines in the whole generation. The previous generation (boot 2026-09-04) shows `SHELL_BOOT_RESTORED:doyle/alchemy-0` etc.\n- Cause: `launch_predates_boot(launched_ms, boot_ms, slack)` in `spt_daemon::shellwake` compares against the MACHINE boot instant (`boot_instant_ms` = now minus `GetTickCount64`). A launch at boot+46 s does not predate that boot, so every daemon-only restart lands in the \"force-killed THIS boot => NOT eligible\" arm on all three triggers (boot sweep, owner-online edge, watcher). By construction, a daemon restart is indistinguishable from an operator force-kill under this discriminant.\n- doyle/alchemy-0 came back only because `spt shell cmd` wakes an offline persistent instance on demand (linkhost `wake_if_offline_persistent`); PACER receives no owner commands, so it stays down until a human runs `relink`. Confirmed: `spt shell relink PACER-0` at 10:28:39Z brought it online (pid 45088), status reply received.\n\n## Why this matters\n\nA daemon restart happens on every self-update. KNOWN-HAZARDS 2.7 (`REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS`) states \"a node restart must not strand a persistent instance\" and was closed for the machine-reboot face; the daemon-restart face reproduces the same stranding through the discriminant that closed it. The contract sentence (a persistent shell is online whenever its owner is) is false after every update.\n\n## Shape question for the fix (not ruled here)\n\nThe force-kill freeze (releases#78 leg (c)) must survive. Candidate: evaluate the corpse against the DAEMON generation instant as well as the machine boot instant, i.e. a corpse whose launch predates the current daemon start is a restart casualty. The open edge: a shell that survives a daemon restart and is then force-killed would have a launch older than the daemon start and would be relaunched. Whether any shell survives a restart (broker-hosted ones die with the broker; relay ones close on link-break) needs measuring before the rule is set.\n\n## Evidence\n\n- `C:\\Users\\decid\\AppData\\Local\\spt-core\\logs\\daemon.stderr.log` lines 64-119 (heals), no RESTORED lines.\n- `owlery/doyle/shells/PACER-0/{shell.pid,shell.launch.json,info.json}`.\n- perri/PACER-0 (pid 28464) and todlando/PACER-0 (pid 42736) still offline at filing; their owners must relink or issue a shell cmd.\n\n## Comments (2)\n\n### @SaberMage · 2026-09-08T10:31:53Z\n\nTwo riders from perri (2026-09-08 10:31Z), after relinking her three stranded shells:\n\n1. **Enumerate every stranded shell per owner.** The daemon log carried `SHELL_RECORD_HEALED` for perri/PACER-0, perri/alchemy-0 AND perri/alchemy-1 (lines 94, 103, 105 of the generation-0 log); my notice to her named only PACER-0. Whatever surfaces this class to an owner (a now-signal line, a shell-list marker, or the heal itself) should list all of that owner's healed instances, not the one the reporter happened to be using. Full stranded set at the 2026-09-07 08:03Z restart: deployah/alchemy-0, doyle/PACER-0, doyle/alchemy-0, doyle/alchemy-1, perri/PACER-0, perri/alchemy-0, perri/alchemy-1, todlando/PACER-0.\n\n2. **`spt shell relink` prints a success that reads as a failure.** On success it answers `SHELL_RELINKED: owner= pid= status=offline (online at bind)` and the roster flips to online a beat later. Measured on my own relink at 10:28:39Z (pid 45088, online within 6 s). The token is honest about the bind handshake but the word `offline` on a success line is the part a reader keeps. A clearer token (for example `status=binding`, or the line naming the expected bind) is a small rider on whichever lane takes this issue.\n\nURL: https://github.com/BigscreenVR/spt-bs-releases/issues/287#issuecomment-5583758643\n\n### @SaberMage · 2026-09-08T10:36:55Z\n\n## OPERATOR RULING (2026-09-08 10:37Z, given to doyle in session; supersedes the shape question above)\n\n> \"daemon-only restart reads as an operator force-kill\" — that shouldn't matter for shells whose manifest has set `shell.persistent = true`. Such shells must come online anytime the endpoint comes online, end of story.\n\nConsequences for the fix (doyle's reading of the ruling, to be built as stated):\n\n1. For a `persistent = true` instance, the owner-online edge and the boot sweep relaunch it whenever the owner endpoint is online and the instance is down in fact (the derived read, pid-reuse-safe via the birth stamp). The `launch_predates_boot` conjunct is REMOVED from the persistent path. The heal (leg a) stays as is.\n2. The releases#78 leg (c) freeze (force-kill during operation is not auto-relaunched, to free an exe for overwrite) no longer governs persistent instances. An operator who needs a persistent shell to stay down uses the surfaces that say so (`teardown`, or a non-persistent manifest), not a kill. The mid-deploy exe-overwrite concern that motivated the freeze is answered by the update path, not by leaving a declared-persistent surface down.\n3. CONTEXT.md's sentence (\"a persistent shell is automatically brought online whenever its owner endpoint is online\") is already the contract; KNOWN-HAZARDS 2.7 and MANIFEST.md's sleep/wake text get amended to drop the boot-instant conjunct for persistent instances, and the REQ-SHELL-PERSISTENT-BOOT-RESTORE / REQ-SHELL-PERSISTENT-OWNER-ONLINE-RESTORE titles are re-worded in the same change. Regression cell: the daemon-restart shape (corpse launched AFTER machine boot, owner online, persistent) is restored on the owner-online edge — the exact row the current discriminant refuses.\n4. Riders from this thread ride the same lane: per-owner enumeration of stranded instances, and the relink success token.\n\nDispatch: product change, so todlando's queue, as a thin lane after his W3 push (or a #272 close rider if the operator prefers it inside the milestone).\n\nURL: https://github.com/BigscreenVR/spt-bs-releases/issues/287#issuecomment-5583820305"}],"details":{"contentType":"text/markdown","totalLines":65,"displayContent":{"text":"# Issue #287: A daemon restart (no machine reboot) strands every persistent shell: the boot-restore discriminant reads the MACHINE boot instant\n\nState: OPEN\nAuthor: @SaberMage\nCreated: 2026-09-08T10:29:58Z\nUpdated: 2026-09-09T23:17:44Z\nLabels: state: GREENLIT, type: BUGFIX\nURL: https://github.com/BigscreenVR/spt-bs-releases/issues/287\n\n## Body\n\n## Symptom\n\nEvery `persistent` shell on hfenduleam (doyle/PACER-0, perri/PACER-0, todlando/PACER-0, doyle/alchemy-1, deployah/alchemy-0, …) went offline at the daemon restart of 2026-09-07 08:03:20Z and stayed offline. No error anywhere. The operator noticed 27 hours later because doyle's pacer had stopped pacing. `shell list` read `offline` the whole time, which is correct, and nothing ever relaunched.\n\n## Mechanism (measured 2026-09-08 10:26Z, spt-core 0.67.0, log `daemon.stderr.log` generation 0 / pid 48232)\n\n- Machine boot: 2026-09-04 08:02:53Z. Pacer launched by that boot's sweep: 2026-09-04 08:03:39Z (`shell.launch.json launched_ms=1788509019651`, native start stamp agrees).\n- Daemon restarted (no machine reboot): 2026-09-07 08:03:20Z. The pacer process (pid 27656) died with it. The heal fired: `SHELL_RECORD_HEALED:doyle/PACER-0: online -> offline` (8 such lines, one per persistent instance).\n- The restore never fired: zero `SHELL_BOOT_RESTORED` / `SHELL_OWNER_ONLINE_RESTORED` lines in the whole generation. The previous generation (boot 2026-09-04) shows `SHELL_BOOT_RESTORED:doyle/alchemy-0` etc.\n- Cause: `launch_predates_boot(launched_ms, boot_ms, slack)` in `spt_daemon::shellwake` compares against the MACHINE boot instant (`boot_instant_ms` = now minus `GetTickCount64`). A launch at boot+46 s does not predate that boot, so every daemon-only restart lands in the \"force-killed THIS boot => NOT eligible\" arm on all three triggers (boot sweep, owner-online edge, watcher). By construction, a daemon restart is indistinguishable from an operator force-kill under this discriminant.\n- doyle/alchemy-0 came back only because `spt shell cmd` wakes an offline persistent instance on demand (linkhost `wake_if_offline_persistent`); PACER receives no owner commands, so it stays down until a human runs `relink`. Confirmed: `spt shell relink PACER-0` at 10:28:39Z brought it online (pid 45088), status reply received.\n\n## Why this matters\n\nA daemon restart happens on every self-update. KNOWN-HAZARDS 2.7 (`REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS`) states \"a node restart must not strand a persistent instance\" and was closed for the machine-reboot face; the daemon-restart face reproduces the same stranding through the discriminant that closed it. The contract sentence (a persistent shell is online whenever its owner is) is false after every update.\n\n## Shape question for the fix (not ruled here)\n\nThe force-kill freeze (releases#78 leg (c)) must survive. Candidate: evaluate the corpse against the DAEMON generation instant as well as the machine boot instant, i.e. a corpse whose launch predates the current daemon start is a restart casualty. The open edge: a shell that survives a daemon restart and is then force-killed would have a launch older than the daemon start and would be relaunched. Whether any shell survives a restart (broker-hosted ones die with the broker; relay ones close on link-break) needs measuring before the rule is set.\n\n## Evidence\n\n- `C:\\Users\\decid\\AppData\\Local\\spt-core\\logs\\daemon.stderr.log` lines 64-119 (heals), no RESTORED lines.\n- `owlery/doyle/shells/PACER-0/{shell.pid,shell.launch.json,info.json}`.\n- perri/PACER-0 (pid 28464) and todlando/PACER-0 (pid 42736) still offline at filing; their owners must relink or issue a shell cmd.\n\n## Comments (2)\n\n### @SaberMage · 2026-09-08T10:31:53Z\n\nTwo riders from perri (2026-09-08 10:31Z), after relinking her three stranded shells:\n\n1. **Enumerate every stranded shell per owner.** The daemon log carried `SHELL_RECORD_HEALED` for perri/PACER-0, perri/alchemy-0 AND perri/alchemy-1 (lines 94, 103, 105 of the generation-0 log); my notice to her named only PACER-0. Whatever surfaces this class to an owner (a now-signal line, a shell-list marker, or the heal itself) should list all of that owner's healed instances, not the one the reporter happened to be using. Full stranded set at the 2026-09-07 08:03Z restart: deployah/alchemy-0, doyle/PACER-0, doyle/alchemy-0, doyle/alchemy-1, perri/PACER-0, perri/alchemy-0, perri/alchemy-1, todlando/PACER-0.\n\n2. **`spt shell relink` prints a success that reads as a failure.** On success it answers `SHELL_RELINKED: owner= pid= status=offline (online at bind)` and the roster flips to online a beat later. Measured on my own relink at 10:28:39Z (pid 45088, online within 6 s). The token is honest about the bind handshake but the word `offline` on a success line is the part a reader keeps. A clearer token (for example `status=binding`, or the line naming the expected bind) is a small rider on whichever lane takes this issue.\n\nURL: https://github.com/BigscreenVR/spt-bs-releases/issues/287#issuecomment-5583758643\n\n### @SaberMage · 2026-09-08T10:36:55Z\n\n## OPERATOR RULING (2026-09-08 10:37Z, given to doyle in session; supersedes the shape question above)\n\n> \"daemon-only restart reads as an operator force-kill\" — that shouldn't matter for shells whose manifest has set `shell.persistent = true`. Such shells must come online anytime the endpoint comes online, end of story.\n\nConsequences for the fix (doyle's reading of the ruling, to be built as stated):\n\n1. For a `persistent = true` instance, the owner-online edge and the boot sweep relaunch it whenever the owner endpoint is online and the instance is down in fact (the derived read, pid-reuse-safe via the birth stamp). The `launch_predates_boot` conjunct is REMOVED from the persistent path. The heal (leg a) stays as is.\n2. The releases#78 leg (c) freeze (force-kill during operation is not auto-relaunched, to free an exe for overwrite) no longer governs persistent instances. An operator who needs a persistent shell to stay down uses the surfaces that say so (`teardown`, or a non-persistent manifest), not a kill. The mid-deploy exe-overwrite concern that motivated the freeze is answered by the update path, not by leaving a declared-persistent surface down.\n3. CONTEXT.md's sentence (\"a persistent shell is automatically brought online whenever its owner endpoint is online\") is already the contract; KNOWN-HAZARDS 2.7 and MANIFEST.md's sleep/wake text get amended to drop the boot-instant conjunct for persistent instances, and the REQ-SHELL-PERSISTENT-BOOT-RESTORE / REQ-SHELL-PERSISTENT-OWNER-ONLINE-RESTORE titles are re-worded in the same change. Regression cell: the daemon-restart shape (corpse launched AFTER machine boot, owner online, persistent) is restored on the owner-online edge — the exact row the current discriminant refuses.\n4. Riders from this thread ride the same lane: per-owner enumeration of stranded instances, and the relink success token.\n\nDispatch: product change, so todlando's queue, as a thin lane after his W3 push (or a #272 close rider if the operator prefers it inside the milestone).\n\nURL: https://github.com/BigscreenVR/spt-bs-releases/issues/287#issuecomment-5583820305","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65]},"meta":{"source":{"type":"internal","value":"issue://BigscreenVR/spt-bs-releases/287"}}},"isError":false,"timestamp":1789001095170}}
{"type":"message","id":"5c361f52","parentId":"933950c8","timestamp":"2026-09-10T00:44:55.216Z","message":{"role":"toolResult","toolCallId":"call_3miPvveXvVzjdjTQBfgEwKVO|fc_077f3569365e313d016aa1fd8571dc87d191c8433943ea33d6","toolName":"bash","content":[{"type":"text","text":"CHANGELOG.md | 13 +++++++++++++\nCONTEXT.md | 8 ++++----\ncrates/spt-daemon/src/shellhost.rs | 25 ++++++++++++++++++------\ncrates/spt-daemon/src/shellwake.rs | 507 +++++++++---------------\ncrates/spt-store/src/shellinfo.rs | 6 +++---\ncrates/spt/src/cli.rs | 3 ++-\ncrates/spt/tests/shell_relink_force_e2e.rs | 10 ++++++++++\ndocs-site/src/shells/overview.md | 45 ++++++++++++------------\ndocs/KNOWN-HAZARDS.md | 17 +++++++++--------\ndocs/MANIFEST.md | 8 +++++++-\ntraceable-reqs.toml | 28 ++++++++++++++++++++----\n11 files changed, 291 insertions(+), 379 deletions(-)\n\n--- Changes ---\n\nFile: CHANGELOG.md\n @@ -10,6 +10,19 @@ breaks something, or changes the observable behavior of existing surfaces\n +## [Unreleased]\n +\n +### Fixed\n +\n +- Every persistent shell comes back with its owner after a daemon-only restart,\n + not just after a machine reboot. Shells launched during the current boot or\n […7 changed lines elided…]\n\nFile: CONTEXT.md\n @@ -388,11 +388,11 @@ The manifest value is the **floor**: a node/endpoint setting may **tighten** (de\n -- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified onc…[+1722]\n - **Daemons boot before endpoints do, so the sweep is not the only trigger** (releases#228): an owner that is not yet online when the sweep runs is skipped by …[+949]\n -- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs *while the shell is offline* **and eligible** (the eligibility rule is b…[+273]\n +- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified onc…[+805]\n + **Daemons boot before endpoints do, so the sweep is not the only trigger:** the reconcile loop runs that **same per-owner restore decision** on each owner **…[+403]\n +- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs while the shell is offline and eligible. Its sole job is to fire a wake.…[+164]\n […2 changed lines elided…]\n\nFile: crates/spt-daemon/src/shellhost.rs\n @@ -312,16 +312,14 @@ pub fn routes_through_daemon(shell: &Shell) -> bool {\n -/// DERIVED, never the recorded status (REQ-HAZARD-SHELL-STALE-ONLINE): a pid\n -/// that is absent, unparseable or `0` reads NOT-a-winner, the same\n -/// fail-toward-alive stance the rest of the shell machinery holds — so a\n -/// backend that records no pid can never block its own relaunch. Same shape and\n -/// same non-fault wording as [`crate::shellwake::resolve_wake`]'s existing\n -/// guard; this is that rule extracted, not a second one.\n […6 changed lines elided…]\n @@ -1204,6 +1202,7 @@ mod tests {\n + // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n @@ -1225,6 +1224,18 @@ mod tests {\n + shellinfo::record_shell_launch(perch, me, 1_000);\n + assert_eq!(live_launch_winner(perch), Some(me), \"same birth retains custody\");\n + let mut launch = shellinfo::read_shell_launch(perch).unwrap();\n + launch.pid_started_at = Some(\n + launch.pid_started_at.expect(\"native birth stamp on supported platforms\") ^ 1,\n + );\n […6 changed lines elided…]\n\nFile: crates/spt-daemon/src/shellwake.rs\n @@ -613,7 +613,7 @@ fn fill_wake_command(\n -fn heal_stale_online_records(owlery: &Path) {\n +fn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n @@ -627,7 +627,8 @@ fn heal_stale_online_records(owlery: &Path) {\n - spt_proto::emit_line_err!(\"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n + // [impl->REQ-SHELL-HEAL-ENUMERATION]\n + let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n @@ -639,67 +640,40 @@ fn heal_stale_online_records(owlery: &Path) {\n -/// that reads as \"a corpse from the previous boot\" and the sweep would relaunch\n -/// something that had just started. Ten seconds is far wider than any plausible\n +/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\n +/// could be armed after a same-boot death. Ten seconds is far wider than plausible\n -/// Whether a recorded launch predates the current boot — leg (b)'s discriminant\n -/// (releases#78).\n […63 changed lines elided…]\n @@ -742,26 +716,10 @@ impl RestoreTrigger {\n -/// It is shared rather than restated because the refusal arms ARE the ruling:\n -/// doyle's condition on releases#228 was that the owner-online trigger carry the\n -/// boot sweep's arms VERBATIM, and two copies of a conjunction drift the first\n -/// time one side is edited. Every gate is a conjunction and each one is\n -/// load-bearing:\n -///\n […18 changed lines elided…]\n @@ -773,13 +731,11 @@ impl RestoreTrigger {\n -#[allow(clippy::too_many_arguments)]\n - boot_ms: u64,\n @@ -795,14 +751,10 @@ fn restore_persistent_shells_of_owner(\n - if shellinfo::is_shell_online(&perch, &info) {\n - continue; // already up in fact\n - }\n - let Some(launch) = shellinfo::read_shell_launch(&perch) else {\n - continue; // no stamp ⇒ cannot prove it predates boot ⇒ leave it down\n - };\n […6 changed lines elided…]\n @@ -844,11 +796,6 @@ pub fn restore_persistent_shells_at_boot(\n - let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n - // No boot oracle on this platform: the discriminant cannot be evaluated,\n - // so nothing is restored. Silence beats guessing at a relaunch.\n - return Vec::new();\n - };\n @@ -856,7 +803,6 @@ pub fn restore_persistent_shells_at_boot(\n - boot_ms,\n […19 hunks elided…]\n\nFile: crates/spt-store/src/shellinfo.rs\n @@ -145,9 +145,9 @@ pub const SHELL_LAUNCH_FILE: &str = \"shell.launch.json\";\n -/// - `launched_ms` is an ABSOLUTE wall-clock stamp (epoch-ms) and is what the\n -/// boot sweep compares against the boot instant. It exists precisely because\n -/// the field above cannot answer that question portably.\n +/// - `launched_ms` is an ABSOLUTE wall-clock stamp (epoch-ms), used by the\n +/// nonpersistent watcher's cross-boot freeze. Persistent restoration does not\n +/// gate on launch age; the native birth stamp still authenticates liveness.\n\nFile: crates/spt/src/cli.rs\n @@ -23531,7 +23531,8 @@ fn cmd_shell(action: ShellCmd, json: bool) -> i32 {\n - eprintln!(\"SHELL_RELINKED:{id} owner={owner} pid={pid} status=offline (online at bind)\");\n + // [impl->REQ-SHELL-RELINK-BINDING-RESULT]\n + eprintln!(\"SHELL_RELINKED:{id} owner={owner} pid={pid} status=binding (online at bind)\");\n\nFile: crates/spt/tests/shell_relink_force_e2e.rs\n @@ -184,6 +184,16 @@ fn force_stops_a_running_binary_then_relinks_it_under_the_same_id() {\n + // [int->REQ-SHELL-RELINK-BINDING-RESULT]\n + assert!(\n + err[relinked_at..]\n + .lines()\n + .next()\n + .unwrap()\n […4 changed lines elided…]\n\nFile: docs-site/src/shells/overview.md\n @@ -93,30 +93,22 @@ Lifecycle extras: `persistent` shells auto-online with their owner;\n -Two lifecycle facts worth knowing before you rely on either:\n -\n -- **A node restart brings `persistent` instances back by a boot sweep, and an\n - owner that comes online after that sweep by an owner-online edge.** A machine\n - death breaks no link, so the instance's record survives the reboot claiming it\n - is still up; the daemon corrects that record and then, once per daemon\n […34 changed lines elided…]\n @@ -129,6 +121,11 @@ Two lifecycle facts worth knowing before you rely on either:\n + \n + A successful local relink reports `status=binding (online at bind)`: the\n + binary has launched and the bind handshake is still the online transition.\n + It does not describe that successful launch as `offline`.\n +\n\nFile: docs/KNOWN-HAZARDS.md\n @@ -76,19 +76,20 @@ Hard-won edge cases harvested from the sister project (`claude_skill_owl`, ~80 c\n -- **No spontaneous relaunch of a SAME-BOOT death (operator-ratified, flynn 2026-07-25; re-based BAROMETER W2):** the reconciler does NOT adopt an instance whos…[+598]\n -- **What holds that open is no longer the stale record (BAROMETER W2):** until W2 the guarantee rested on an accident: a force-killed instance was held out of …[+943]\n +- **No spontaneous relaunch of a NONPERSISTENT same-boot death:** the releases#78 force-kill freeze still protects nonpersistent instances, so killing one to f…[+278]\n +- **Watcher eligibility:** recorded `offline`, no live binary awaiting bind, and either `persistent`, no corpse, or a corpse whose launch predates the machine …[+223]\n -### 2.7 A node restart permanently strands every `persistent` shell — and the existing cascade test cannot see that it does `[REQ-HAZARD-RESTART-STRANDS-PERSI…[+14]\n -- **Failure:** the contract's own sentence says a `persistent` shell is **online whenever its owner endpoint is online**, and a node restart is the one case wh…[+510]\n […11 changed lines elided…]\n\nFile: docs/MANIFEST.md\n @@ -788,7 +788,13 @@ types = [\"image\", \"sound\", \"event\"] # \"event\" = arbitrary descriptive payloads\n -**Sleep/wake:** when offline **and eligible** (+ `wake_command` set), spt-core runs the wake-watcher (mutually exclusive with the shell binary); `exit(wake-opc…[+2187]\n +**Sleep/wake:** when offline **and eligible** (+ `wake_command` set), spt-core runs the wake-watcher, mutually exclusive with a live shell binary including one…[+366]\n +\n +**Persistent restoration:** on the once-per-daemon-generation boot sweep and each owner offline→online edge, spt-core restores **every** down persistent instan…[+530]\n +\n +**Watcher eligibility:** recorded-offline instances with no live binary are eligible if persistent, cleanly closed/never launched (no corpse), or a dated pre-b…[+282]\n […2 changed lines elided…]\n\nFile: traceable-reqs.toml\n @@ -3183,6 +3183,12 @@ required_stages = [\"doc\", \"impl\", \"unit\", \"int\"] # W1 ACTIVATED at mint (doyle\n +# AMENDED releases#287, operator ruling 2026-09-08: the historical title below's\n +# same-boot/undatable-corpse freeze and no-spontaneous-relaunch clauses now apply\n +# ONLY to NONPERSISTENT instances. Persistent restoration and watcher eligibility\n +# follow REQ-SHELL-PERSISTENT-BOOT-RESTORE / REQ-SHELL-OWNER-ONLINE-RESTORE, without\n +# launch-age or stamp-presence gates. Birth-safe live/binding exclusion remains.\n +# The liveness, identity/state preservation and durable-channel clauses stand.\n @@ -4151,13 +4157,23 @@ required_stages = [\"doc\", \"impl\", \"unit\"] # ACTIVATED BAROMETER W1 at impl+unit\n -title = \"A `persistent` SHELL COMES BACK AFTER A NODE RESTART, WHICH IS THE ONE CASE THE CONTRACT'S OWN SENTENCE PROMISES AND THE IMPLEMENTATION NEVER HANDLED.…[+3939]\n -required_stages = [\"doc\", \"impl\", \"unit\"] # doc ACTIVATED BAROMETER W2 doc leg (doyle-ruled, this milestone): the CONTEXT.md `persistent` amendment states the…[+193]\n +title = \"Persistent shells are restored on each daemon-generation boot sweep whenever their owner is online and they are down in fact, regardless of machine bo…[+457]\n +required_stages = [\"doc\", \"impl\", \"unit\"]\n -title = \"A `persistent` SHELL WHOSE OWNER ENDPOINT WAS NOT YET ONLINE WHEN THE BOOT SWEEP RAN IS RESTORED WHEN THAT OWNER COMES ONLINE, RATHER THAN STAYING DOW…[+3074]\n -required_stages = [\"doc\", \"impl\", \"unit\"] # ACTIVATED CONDUIT W2 in the commit landing the evidence (doyle ruled shape (c) with conditions on releases#228; (a…[+285]\n […12 changed lines elided…]\n @@ -4166,7 +4182,7 @@ required_stages = [\"doc\", \"impl\", \"unit\", \"int\"] # ACTIVATED BAROMETER W2 reope\n -title = \"A NODE RESTART MUST NOT PERMANENTLY STRAND EVERY `persistent` SHELL, AND THE EXISTING CASCADE TEST CANNOT SEE THAT IT DOES. Distinct from REQ-HAZARD-S…[+2249]\n +title = \"A daemon-only or machine restart must not strand persistent shells. Heal stale online records and restore every down persistent instance when its owne…[+457]\n @@ -4386,6 +4402,7 @@ requirements = [\n + \"REQ-SHELL-RELINK-BINDING-RESULT\",\n @@ -4550,6 +4567,7 @@ requirements = [\n + \"REQ-SHELL-HEAL-ENUMERATION\",\n[raw output: artifact://112]\n\n\nWall time: 1.32 seconds"}],"details":{"timeoutSeconds":300,"wallTimeMs":1317.3914000000805},"isError":false,"timestamp":1789001095215}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_WZyFmSAexqkpOcnZ0vv8qvQW|fc_077f3569365e313d016aa1fd8dab9887d1a91d04944628e375","toolName":"read","startedAt":"2026-09-10T00:45:01.748Z","args":{"path":"artifact://112"},"intent":"Reading full patch"},"id":"1d5252c4","parentId":"5c361f52","timestamp":"2026-09-10T00:45:01.748Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_8tZqKMdMkqqi3pvzPDyJk9XB|fc_077f3569365e313d016aa1fd8dabac87d180bc9028fa0b2249","toolName":"read","startedAt":"2026-09-10T00:45:01.748Z","args":{"path":".worktrees/287-shellrestore/AGENTS.md"},"intent":"Reading worktree rules"},"id":"1de44e33","parentId":"1d5252c4","timestamp":"2026-09-10T00:45:01.749Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_SoXnwtS6OxjKMOFNagDliZYD|fc_077f3569365e313d016aa1fd8dabb487d19e2dbb48a2ab8749","toolName":"read","startedAt":"2026-09-10T00:45:01.749Z","args":{"path":".worktrees/287-shellrestore/CLAUDE.md"},"intent":"Reading worktree guidance"},"id":"dd3ccb8a","parentId":"1de44e33","timestamp":"2026-09-10T00:45:01.749Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_8hdpFa9bn2kiSxq2op7zz0Ps|fc_077f3569365e313d016aa1fd8dabbc87d19b254ad7b50831fe","toolName":"read","startedAt":"2026-09-10T00:45:01.749Z","args":{"path":"AGENTS.md"},"intent":"Reading inherited rules"},"id":"749d2291","parentId":"dd3ccb8a","timestamp":"2026-09-10T00:45:01.749Z"}
{"type":"message","id":"80ba6fde","parentId":"749d2291","timestamp":"2026-09-10T00:45:01.749Z","message":{"role":"assistant","content":[{"type":"toolCall","id":"call_WZyFmSAexqkpOcnZ0vv8qvQW|fc_077f3569365e313d016aa1fd8dab9887d1a91d04944628e375","name":"read","arguments":{"i":"Reading full patch","path":"artifact://112"},"intent":"Reading full patch"},{"type":"toolCall","id":"call_8tZqKMdMkqqi3pvzPDyJk9XB|fc_077f3569365e313d016aa1fd8dabac87d180bc9028fa0b2249","name":"read","arguments":{"i":"Reading worktree rules","path":".worktrees/287-shellrestore/AGENTS.md"},"intent":"Reading worktree rules"},{"type":"toolCall","id":"call_SoXnwtS6OxjKMOFNagDliZYD|fc_077f3569365e313d016aa1fd8dabb487d19e2dbb48a2ab8749","name":"read","arguments":{"i":"Reading worktree guidance","path":".worktrees/287-shellrestore/CLAUDE.md"},"intent":"Reading worktree guidance"},{"type":"toolCall","id":"call_8hdpFa9bn2kiSxq2op7zz0Ps|fc_077f3569365e313d016aa1fd8dabbc87d19b254ad7b50831fe","name":"read","arguments":{"i":"Reading inherited rules","path":"AGENTS.md"},"intent":"Reading inherited rules"}],"api":"openai-codex-responses","provider":"openai-codex","model":"gpt-6-astra","usage":{"input":5805,"output":123,"cacheRead":14208,"cacheWrite":0,"totalTokens":20136,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"toolUse","timestamp":1789001095225,"responseId":"resp_077f3569365e313d016aa1fd8780a887d18cc0e901f74be91c","providerPayload":{"type":"openaiResponsesHistory","provider":"openai-codex","dt":true,"items":[{"id":"fc_077f3569365e313d016aa1fd8dab9887d1a91d04944628e375","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading full patch\",\"path\":\"artifact://112\"}","call_id":"call_WZyFmSAexqkpOcnZ0vv8qvQW","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fd8dabac87d180bc9028fa0b2249","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading worktree rules\",\"path\":\".worktrees/287-shellrestore/AGENTS.md\"}","call_id":"call_8tZqKMdMkqqi3pvzPDyJk9XB","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fd8dabb487d19e2dbb48a2ab8749","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading worktree guidance\",\"path\":\".worktrees/287-shellrestore/CLAUDE.md\"}","call_id":"call_SoXnwtS6OxjKMOFNagDliZYD","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fd8dabbc87d19b254ad7b50831fe","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading inherited rules\",\"path\":\"AGENTS.md\"}","call_id":"call_8hdpFa9bn2kiSxq2op7zz0Ps","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}}]},"duration":6522.552399999928,"ttft":6479.525200000033,"completedAt":1789001101747,"contextSnapshot":{"promptTokens":20013,"nonMessageTokens":13209,"compactionEpoch":0}}}
{"type":"message","id":"8abef4f6","parentId":"80ba6fde","timestamp":"2026-09-10T00:45:01.754Z","message":{"role":"toolResult","toolCallId":"call_WZyFmSAexqkpOcnZ0vv8qvQW|fc_077f3569365e313d016aa1fd8dab9887d1a91d04944628e375","toolName":"read","content":[{"type":"text","text":"diff --git a/CHANGELOG.md b/CHANGELOG.md\nindex eafe18d6..39bf8144 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -10,6 +10,19 @@ breaks something, or changes the observable behavior of existing surfaces\n broadly; **patch** for fixes, and for additive opt-in capability — a new key,\n flag, or page that no existing user can encounter without opting into it.\n \n+## [Unreleased]\n+\n+### Fixed\n+\n+- Every persistent shell comes back with its owner after a daemon-only restart,\n+ not just after a machine reboot. Shells launched during the current boot or\n+ without a saved launch stamp are no longer left down, and recovery notices\n+ name every healed instance for each owner. A persistent shell must be torn\n+ down or made nonpersistent to stay down; killing its process does not opt out\n+ of restoration.\n+- A successful `spt shell relink` reports `binding` while awaiting its handshake,\n+ rather than making the successful launch read as `offline`.\n+\n ## [0.68.0] - 2026-09-08\n \n Web serving. Files, directories, adapter documentation and the changelog are\ndiff --git a/CONTEXT.md b/CONTEXT.md\nindex cdb8a8e1..6698a590 100644\n--- a/CONTEXT.md\n+++ b/CONTEXT.md\n@@ -388,11 +388,11 @@ The manifest value is the **floor**: a node/endpoint setting may **tighten** (de\n \n A shell automatically goes **offline when its owner endpoint goes offline**. Two complementary manifest options bring it (and its owner) back:\n \n-- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified once instances span nodes** (ruled 2026-07-24, #70 grill): when an owner comes online at a given node, only the **latest** instances qualified to that *endpoint@node* pairing come online with it — a stale instance of the same shell left on another node does not auto-wake alongside. **A node restart is covered by a boot sweep, and an owner that comes online after that sweep by an owner-online edge** (BAROMETER W2 releases#78; CONDUIT W2 releases#228): a machine death breaks no link, so the instance's record survives the reboot still saying `online` and the wake cascade — which reads the *recorded* field — skips it, stranding every `persistent` instance on the node at once. The daemon therefore (i) heals a recorded `online` its derived status contradicts, every reconcile cycle, writing only when the value actually changes, and (ii) runs a **once-per-daemon-generation boot sweep** that relaunches an instance when **all four** conditions hold: the adapter declares `persistent`; the **owner endpoint is online** (an offline owner is owed nothing); the instance is down **in fact**; and its **recorded launch predates the boot instant**. A launch parks a **birth stamp** beside the pid to make that last question answerable — **no stamp ⇒ not restored** (the sweep cannot prove the corpse predates boot, and leaving a shell down beats relaunching a binary an operator may have killed deliberately), and a platform with no boot oracle restores nothing. A shell force-killed *during* this boot is launched after it, can never satisfy the predicate, and so is never spontaneously relaunched — the deploy/quarantine ruling of KNOWN-HAZARDS 2.6 preserved by construction. \n- **Daemons boot before endpoints do, so the sweep is not the only trigger** (releases#228): an owner that is not yet online when the sweep runs is skipped by that very conjunct, and — the sweep being once per daemon generation, and bringup from offline emitting no rest edge — nothing revisited it, so its shells stayed down until a human relinked. The reconcile loop therefore runs the **same four conditions** for every owner that has gone **offline→online since the last pass**. The trigger is that **edge, never the level “the owner is online”**: a successful restore restamps itself out of eligibility, but a *failing* launch under a level trigger would be retried every reconcile tick for as long as the owner stayed up, where the edge bounds it to one attempt per owner-online event. Re-evaluating later in a generation can only refuse **more**, never less — every launch path restamps the birth stamp, a kill never does, and the boot instant is fixed for the machine boot — so the force-kill ruling above is preserved identically on the second trigger. \n-- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs *while the shell is offline* **and eligible** (the eligibility rule is below — an offline instance sitting on a same-boot corpse arms no watcher). Its sole job is to fire a wake. It runs on the **shell's node** (where the platform wake-event originates — e.g. interacting with a \"shut-down\" avatar). Covers \"owner is down, wake it from outside.\"\n+- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified once instances span nodes** (ruled 2026-07-24, #70 grill): when an owner comes online at a given node, only the **latest** instances qualified to that *endpoint@node* pairing come online with it — a stale instance of the same shell left on another node does not auto-wake alongside. A **once-per-daemon-generation boot sweep** restores every down persistent instance whose owner is online, after a machine reboot **or a daemon-only restart**. Birth-safe liveness protects both an online binary and a live launch awaiting bind. Machine boot time, recorded launch age, and missing launch stamps do **not** gate restoration (releases#287 operator ruling). The daemon also heals stale `online` records to `offline` each reconcile cycle, only on an actual change. \n+ **Daemons boot before endpoints do, so the sweep is not the only trigger:** the reconcile loop runs that **same per-owner restore decision** on each owner **offline→online edge**. The edge is seeded before the sweep; a live launch awaiting bind prevents duplicate launch if both triggers reach it. Failed launches are attempted once per owner-online event, not every tick while the owner stays online. A force-kill does not revoke persistence: use `teardown` or a nonpersistent manifest to keep the instance down. \n+- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs while the shell is offline and eligible. Its sole job is to fire a wake. It runs on the **shell's node**, where the platform wake-event originates (e.g. interacting with a shut-down avatar). Covers \"owner is down, wake it from outside.\"\n \n-**Online/offline are mutually-exclusive processes:** online ⇒ the shell binary runs (no watcher); offline ⇒ the wake-watcher runs (no shell binary). spt-core flips between them. **Offline does not by itself arm the watcher — a third outcome exists** (BAROMETER W2, releases#78): an instance that is offline over a **corpse launched during this boot** (a force-kill, a crash) is deliberately held out of watcher eligibility, so *neither* process runs until recovery is demanded — `relink`, or a `shell cmd` that wakes. Eligibility is recorded-`offline` **AND** (no corpse, **or** the corpse's launch predates the boot instant); an instance whose corpse cannot be dated — no birth stamp, or no boot oracle on the platform — is treated as ineligible rather than guessed at. Only a cleanly-closed instance and a **restart casualty** arm a watcher. The reason is the deploy case: on Windows an operator kills a shell precisely to free its exe for overwrite, and a watcher armed there would re-lock the file under them.\n+**Online/offline are mutually-exclusive processes:** a live shell binary (including a launch awaiting bind) excludes its wake-watcher. A recorded-offline instance is watcher-eligible when it is persistent, carries no corpse, or its corpse's launch predates machine boot. **Only nonpersistent instances retain the same-boot force-kill freeze:** their same-boot or undatable corpses arm no watcher, preserving the deploy/overwrite case. A persistent corpse bypasses that freeze even without a launch stamp or boot oracle (releases#287). Missing birth evidence retains the existing fail-toward-alive process probe; it is not itself a restore refusal.\n \n **Exit-opcode supervision:** the wake-watcher exiting with the **wake opcode** → spt-core runs the wake resolution (below) and brings the shell online. Any *other* exit (crash) → respawn the watcher with **exponential backoff + eventual give-up** (until next shell activity) — crash-bug safety. One watcher per offline shell instance.\n \ndiff --git a/crates/spt-daemon/src/shellhost.rs b/crates/spt-daemon/src/shellhost.rs\nindex 593c6f68..44df752b 100644\n--- a/crates/spt-daemon/src/shellhost.rs\n+++ b/crates/spt-daemon/src/shellhost.rs\n@@ -312,16 +312,14 @@ pub fn routes_through_daemon(shell: &Shell) -> bool {\n /// down and adopt it. Used by BOTH sides of the routed launch, because a late\n /// ack can put the caller and the daemon in the same launch at once.\n ///\n-/// DERIVED, never the recorded status (REQ-HAZARD-SHELL-STALE-ONLINE): a pid\n-/// that is absent, unparseable or `0` reads NOT-a-winner, the same\n-/// fail-toward-alive stance the rest of the shell machinery holds — so a\n-/// backend that records no pid can never block its own relaunch. Same shape and\n-/// same non-fault wording as [`crate::shellwake::resolve_wake`]'s existing\n-/// guard; this is that rule extracted, not a second one.\n+/// Birth-safe, including a binary awaiting bind: a recycled live pid is NOT a\n+/// winner when its native birth stamp mismatches. Missing, unparseable and zero\n+/// pids remain not-a-winner, preserving pid-less backend behavior.\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n+// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n pub fn live_launch_winner(shell_perch: &Path) -> Option {\n shellinfo::read_shell_pid(shell_perch)\n- .filter(|&p| p != 0 && spt_store::proc::is_process_alive(p))\n+ .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\n }\n \n /// THE route-selection seam. Generic over the daemon call and the in-process\n@@ -1204,6 +1202,7 @@ mod tests {\n // that parses non-zero AND probes alive is a winner. Absent / `0` /\n // unparseable / dead must all read NOT-a-winner, or a backend that records\n // no usable pid would be unable to relaunch its own instance.\n+ // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n #[test]\n fn only_a_live_recorded_pid_wins_a_launch_race() {\n let tmp = tempfile::tempdir().unwrap();\n@@ -1225,6 +1224,18 @@ mod tests {\n Some(me),\n \"a recorded pid that probes alive IS the winner\"\n );\n+ shellinfo::record_shell_launch(perch, me, 1_000);\n+ assert_eq!(live_launch_winner(perch), Some(me), \"same birth retains custody\");\n+ let mut launch = shellinfo::read_shell_launch(perch).unwrap();\n+ launch.pid_started_at = Some(\n+ launch.pid_started_at.expect(\"native birth stamp on supported platforms\") ^ 1,\n+ );\n+ std::fs::write(\n+ perch.join(shellinfo::SHELL_LAUNCH_FILE),\n+ serde_json::to_string(&launch).unwrap(),\n+ )\n+ .unwrap();\n+ assert_eq!(live_launch_winner(perch), None, \"a recycled pid cannot block restore\");\n }\n \n // [unit->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE] a REAL dial at a socket name\ndiff --git a/crates/spt-daemon/src/shellwake.rs b/crates/spt-daemon/src/shellwake.rs\nindex 7caf020f..d9631b4d 100644\n--- a/crates/spt-daemon/src/shellwake.rs\n+++ b/crates/spt-daemon/src/shellwake.rs\n@@ -613,7 +613,7 @@ fn fill_wake_command(\n /// correction of a field that is already wrong. Nothing is started here.\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n-fn heal_stale_online_records(owlery: &Path) {\n+fn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n if info.status != SHELL_STATUS_ONLINE {\n@@ -627,7 +627,8 @@ fn heal_stale_online_records(owlery: &Path) {\n let mut healed = info.clone();\n healed.status = truth.to_string();\n if shellinfo::write_shell_info(&perch, &healed).is_ok() {\n- spt_proto::emit_line_err!(\"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n+ // [impl->REQ-SHELL-HEAL-ENUMERATION]\n+ let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n }\n }\n }\n@@ -639,67 +640,40 @@ fn heal_stale_online_records(owlery: &Path) {\n /// now-minus-uptime, which drifts by however long the two calls take and by\n /// whatever the clock did since — so a process launched in the first moments of\n /// a boot can compute as very slightly older than the boot itself. Without slack\n-/// that reads as \"a corpse from the previous boot\" and the sweep would relaunch\n-/// something that had just started. Ten seconds is far wider than any plausible\n+/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\n+/// could be armed after a same-boot death. Ten seconds is far wider than plausible\n /// derivation error and far narrower than the gap this discriminant exists to\n /// detect (a previous boot is minutes to days back).\n pub const BOOT_RESTORE_SLACK_MS: u64 = 10_000;\n \n-/// Whether a recorded launch predates the current boot — leg (b)'s discriminant\n-/// (releases#78).\n-///\n-/// This is what preserves the force-kill ruling BY CONSTRUCTION rather than by a\n-/// second rule: a shell force-killed during steady-state operation was launched\n-/// AFTER the current boot, so it can never satisfy this predicate and is never\n-/// spontaneously relaunched — the mid-deploy exe-overwrite case that ruling\n-/// protects is untouched. Only a fresh boot restores.\n-///\n-/// Pure over its inputs so the boundary is unit-testable without a reboot.\n-// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n+/// Whether a nonpersistent shell's recorded launch predates the current boot.\n+/// This preserves its same-boot force-kill freeze; persistent shells do not use\n+/// launch age as eligibility (releases#287).\n+// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n pub fn launch_predates_boot(launched_ms: u64, boot_ms: u64, slack_ms: u64) -> bool {\n launched_ms.saturating_add(slack_ms) < boot_ms\n }\n \n-/// Is this instance watcher-eligible? The class-(c) site of\n-/// REQ-HAZARD-SHELL-STALE-ONLINE, ruled onto the corpse-boot discriminant\n-/// (doyle, releases#78 comment 5156810267).\n-///\n-/// It reads the RECORDED status — never the derived one — and then asks the SAME\n-/// `launch_predates_boot` question leg (b) asks. Three arms, and each one is the\n-/// answer to a case the other two get wrong:\n-///\n-/// - **force-killed THIS boot** ⇒ record healed to offline (honest), corpse\n-/// launched after boot ⇒ NOT eligible. This is what the class-(c) freeze\n-/// protects: on Windows an operator kills a shell precisely to free its exe\n-/// for overwrite (shared install dir ⇒ a routine deploy step), and a watcher\n-/// armed here would re-lock the file under them on the next spooled frame.\n-/// Recovery stays demand-driven — `relink`, or a `shell cmd` that wakes.\n-/// - **restart casualty** (corpse launched BEFORE this boot) ⇒ eligible, the\n-/// operator-greenlit scope of #78 leg (b). Two routes, one answer: the boot\n-/// sweep restores it once, and the watcher covers it on demand thereafter.\n-/// - **cleanly closed** (no corpse — `close_shell` retires the pid file) ⇒\n-/// eligible exactly as before this change.\n-///\n-/// WHY THE CORPSE IS DEFINED ON THE PARKED STAMPS and not on a live pid re-probe:\n-/// `shell_pid_provably_dead` runs the PAIR test, so a RECYCLED pid (alive, but\n-/// its native start stamp mismatches the one leg (a) parked) reads as a corpse —\n-/// because our process IS dead. Without that, a race walks straight back into the\n-/// forbidden shape: the heal fires on the true corpse, the OS recycles its pid\n-/// before the next tick, this read sees \"alive ⇒ no corpse\", and a force-killed\n-/// instance is adopted after all.\n-///\n-/// NO STAMP, or no boot oracle on this platform ⇒ NOT eligible when a corpse is\n-/// present: the discriminant cannot be evaluated, and the safe direction is to\n-/// leave a shell down rather than arm a relaunch of a binary an operator may have\n-/// killed on purpose. Same stance, same reason, as the boot sweep's.\n+/// Watchers require an offline instance with no live launch awaiting bind.\n+/// Persistent shells bypass the corpse-age freeze (releases#287); nonpersistent\n+/// corpses still need a dated pre-boot launch. Missing dates fail closed only\n+/// for that nonpersistent freeze, never for persistent restoration.\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n-fn watcher_eligible(perch: &Path, info: &shellinfo::ShellInfo, boot_ms: Option) -> bool {\n+fn watcher_eligible(\n+ perch: &Path,\n+ info: &shellinfo::ShellInfo,\n+ persistent: bool,\n+ boot_ms: Option,\n+) -> bool {\n if info.status != SHELL_STATUS_OFFLINE {\n return false;\n }\n- if !shellinfo::shell_pid_provably_dead(perch) {\n- return true; // no corpse: cleanly closed, or never launched\n+ if crate::shellhost::live_launch_winner(perch).is_some() {\n+ return false; // binding: the shell binary and watcher must not overlap\n+ }\n+ if persistent || !shellinfo::shell_pid_provably_dead(perch) {\n+ return true; // persistence overrides the freeze; clean closes need no age\n }\n let (Some(boot_ms), Some(launch)) = (boot_ms, shellinfo::read_shell_launch(perch)) else {\n return false;\n@@ -742,26 +716,10 @@ impl RestoreTrigger {\n /// ONE owner's slice of the persistent-shell restore decision -- the body BOTH\n /// triggers run.\n ///\n-/// It is shared rather than restated because the refusal arms ARE the ruling:\n-/// doyle's condition on releases#228 was that the owner-online trigger carry the\n-/// boot sweep's arms VERBATIM, and two copies of a conjunction drift the first\n-/// time one side is edited. Every gate is a conjunction and each one is\n-/// load-bearing:\n-///\n-/// - the adapter section says `persistent` — the contract promise is scoped to\n-/// exactly those, and a non-persistent instance was never owed a restore;\n-/// - the OWNER endpoint is online — an offline owner is owed nothing, which is\n-/// the difference between healing a record and resurrecting a shell nobody is\n-/// there to drive;\n-/// - the instance is down IN FACT (the derived read, which the birth stamp from\n-/// leg (a) now makes trustworthy across a pid reuse);\n-/// - and its recorded launch PREDATES THE BOOT INSTANT.\n-///\n-/// An instance with NO launch stamp is deliberately NOT restored: the sweep\n-/// cannot prove it predates boot, and the safe direction here is to leave a\n-/// shell down rather than relaunch a binary an operator may have killed on\n-/// purpose. Such an instance gains a stamp the first time it is launched by a\n-/// build carrying leg (a), and is covered from then on.\n+/// Both triggers restore every persistent instance whose owner is online and\n+/// whose binary is down in fact. Birth-safe liveness excludes a live launch\n+/// awaiting bind as well as an already-online shell. Machine boot and launch\n+/// age are irrelevant, including missing stamps (releases#287 operator ruling).\n ///\n /// `set` is the daemon's live watcher set, and it is `None` at boot ON PURPOSE:\n /// the sweep runs before the reconcile loop's first tick, so no watcher can yet\n@@ -773,13 +731,11 @@ impl RestoreTrigger {\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n // [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n-#[allow(clippy::too_many_arguments)]\n fn restore_persistent_shells_of_owner(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n owner: &str,\n- boot_ms: u64,\n trigger: RestoreTrigger,\n set: Option<&Arc>,\n restored: &mut Vec,\n@@ -795,14 +751,10 @@ fn restore_persistent_shells_of_owner(\n continue;\n };\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &shell_id);\n- if shellinfo::is_shell_online(&perch, &info) {\n- continue; // already up in fact\n- }\n- let Some(launch) = shellinfo::read_shell_launch(&perch) else {\n- continue; // no stamp ⇒ cannot prove it predates boot ⇒ leave it down\n- };\n- if !launch_predates_boot(launch.launched_ms, boot_ms, BOOT_RESTORE_SLACK_MS) {\n- continue; // launched THIS boot: a force-kill, not a restart casualty\n+ if shellinfo::is_shell_online(&perch, &info)\n+ || crate::shellhost::live_launch_winner(&perch).is_some()\n+ {\n+ continue; // already online or binding in fact\n }\n // Mutual exclusivity, the online side: the watcher dies before the binary\n // rises. `launch_shell` already kills the waker CHILD, but the supervising\n@@ -844,11 +796,6 @@ pub fn restore_persistent_shells_at_boot(\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n ) -> Vec {\n- let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n- // No boot oracle on this platform: the discriminant cannot be evaluated,\n- // so nothing is restored. Silence beats guessing at a relaunch.\n- return Vec::new();\n- };\n let mut restored = Vec::new();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n restore_persistent_shells_of_owner(\n@@ -856,7 +803,6 @@ pub fn restore_persistent_shells_at_boot(\n registered,\n adapters_dir,\n &owner,\n- boot_ms,\n RestoreTrigger::Boot,\n None,\n &mut restored,\n@@ -868,12 +814,9 @@ pub fn restore_persistent_shells_at_boot(\n /// Per-owner online state carried ACROSS reconcile passes, so the restore below\n /// can be EDGE-triggered on an owner's offline->online transition.\n ///\n-/// WHY AN EDGE AND NOT A LEVEL (doyle's condition, releases#228): a successful\n-/// restore self-limits, because the launch restamps `launched_ms` to now and the\n-/// corpse-boot discriminant refuses that instance from then on. A FAILING launch\n\n[Artifact storage: ~/.omp/agent/sessions/-Documents-projects-spt-core/2026-09-09T23-45-42-317Z_01a08890-21ad-7000-8f54-208d4f4f2f2c/112.bash-original.log (105.3KB). Use artifact://112:N-M to page, artifact://112:raw:N-M for verbatim chunks, and the artifact file path for search/copy workflows.]\n\n[Showing lines 1-300 of 1088. Use :301 to continue]"}],"details":{"resolvedPath":"C:\\Users\\decid\\.omp\\agent\\sessions\\-Documents-projects-spt-core\\2026-09-09T23-45-42-317Z_01a08890-21ad-7000-8f54-208d4f4f2f2c\\112.bash-original.log","contentType":"text/plain","totalLines":1088,"displayContent":{"text":"diff --git a/CHANGELOG.md b/CHANGELOG.md\nindex eafe18d6..39bf8144 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -10,6 +10,19 @@ breaks something, or changes the observable behavior of existing surfaces\n broadly; **patch** for fixes, and for additive opt-in capability — a new key,\n flag, or page that no existing user can encounter without opting into it.\n \n+## [Unreleased]\n+\n+### Fixed\n+\n+- Every persistent shell comes back with its owner after a daemon-only restart,\n+ not just after a machine reboot. Shells launched during the current boot or\n+ without a saved launch stamp are no longer left down, and recovery notices\n+ name every healed instance for each owner. A persistent shell must be torn\n+ down or made nonpersistent to stay down; killing its process does not opt out\n+ of restoration.\n+- A successful `spt shell relink` reports `binding` while awaiting its handshake,\n+ rather than making the successful launch read as `offline`.\n+\n ## [0.68.0] - 2026-09-08\n \n Web serving. Files, directories, adapter documentation and the changelog are\ndiff --git a/CONTEXT.md b/CONTEXT.md\nindex cdb8a8e1..6698a590 100644\n--- a/CONTEXT.md\n+++ b/CONTEXT.md\n@@ -388,11 +388,11 @@ The manifest value is the **floor**: a node/endpoint setting may **tighten** (de\n \n A shell automatically goes **offline when its owner endpoint goes offline**. Two complementary manifest options bring it (and its owner) back:\n \n-- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified once instances span nodes** (ruled 2026-07-24, #70 grill): when an owner comes online at a given node, only the **latest** instances qualified to that *endpoint@node* pairing come online with it — a stale instance of the same shell left on another node does not auto-wake alongside. **A node restart is covered by a boot sweep, and an owner that comes online after that sweep by an owner-online edge** (BAROMETER W2 releases#78; CONDUIT W2 releases#228): a machine death breaks no link, so the instance's record survives the reboot still saying `online` and the wake cascade — which reads the *recorded* field — skips it, stranding every `persistent` instance on the node at once. The daemon therefore (i) heals a recorded `online` its derived status contradicts, every reconcile cycle, writing only when the value actually changes, and (ii) runs a **once-per-daemon-generation boot sweep** that relaunches an instance when **all four** conditions hold: the adapter declares `persistent`; the **owner endpoint is online** (an offline owner is owed nothing); the instance is down **in fact**; and its **recorded launch predates the boot instant**. A launch parks a **birth stamp** beside the pid to make that last question answerable — **no stamp ⇒ not restored** (the sweep cannot prove the corpse predates boot, and leaving a shell down beats relaunching a binary an operator may have killed deliberately), and a platform with no boot oracle restores nothing. A shell force-killed *during* this boot is launched after it, can never satisfy the predicate, and so is never spontaneously relaunched — the deploy/quarantine ruling of KNOWN-HAZARDS 2.6 preserved by construction. \n- **Daemons boot before endpoints do, so the sweep is not the only trigger** (releases#228): an owner that is not yet online when the sweep runs is skipped by that very conjunct, and — the sweep being once per daemon generation, and bringup from offline emitting no rest edge — nothing revisited it, so its shells stayed down until a human relinked. The reconcile loop therefore runs the **same four conditions** for every owner that has gone **offline→online since the last pass**. The trigger is that **edge, never the level “the owner is online”**: a successful restore restamps itself out of eligibility, but a *failing* launch under a level trigger would be retried every reconcile tick for as long as the owner stayed up, where the edge bounds it to one attempt per owner-online event. Re-evaluating later in a generation can only refuse **more**, never less — every launch path restamps the birth stamp, a kill never does, and the boot instant is fixed for the machine boot — so the force-kill ruling above is preserved identically on the second trigger. \n-- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs *while the shell is offline* **and eligible** (the eligibility rule is below — an offline instance sitting on a same-boot corpse arms no watcher). Its sole job is to fire a wake. It runs on the **shell's node** (where the platform wake-event originates — e.g. interacting with a \"shut-down\" avatar). Covers \"owner is down, wake it from outside.\"\n+- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified once instances span nodes** (ruled 2026-07-24, #70 grill): when an owner comes online at a given node, only the **latest** instances qualified to that *endpoint@node* pairing come online with it — a stale instance of the same shell left on another node does not auto-wake alongside. A **once-per-daemon-generation boot sweep** restores every down persistent instance whose owner is online, after a machine reboot **or a daemon-only restart**. Birth-safe liveness protects both an online binary and a live launch awaiting bind. Machine boot time, recorded launch age, and missing launch stamps do **not** gate restoration (releases#287 operator ruling). The daemon also heals stale `online` records to `offline` each reconcile cycle, only on an actual change. \n+ **Daemons boot before endpoints do, so the sweep is not the only trigger:** the reconcile loop runs that **same per-owner restore decision** on each owner **offline→online edge**. The edge is seeded before the sweep; a live launch awaiting bind prevents duplicate launch if both triggers reach it. Failed launches are attempted once per owner-online event, not every tick while the owner stays online. A force-kill does not revoke persistence: use `teardown` or a nonpersistent manifest to keep the instance down. \n+- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs while the shell is offline and eligible. Its sole job is to fire a wake. It runs on the **shell's node**, where the platform wake-event originates (e.g. interacting with a shut-down avatar). Covers \"owner is down, wake it from outside.\"\n \n-**Online/offline are mutually-exclusive processes:** online ⇒ the shell binary runs (no watcher); offline ⇒ the wake-watcher runs (no shell binary). spt-core flips between them. **Offline does not by itself arm the watcher — a third outcome exists** (BAROMETER W2, releases#78): an instance that is offline over a **corpse launched during this boot** (a force-kill, a crash) is deliberately held out of watcher eligibility, so *neither* process runs until recovery is demanded — `relink`, or a `shell cmd` that wakes. Eligibility is recorded-`offline` **AND** (no corpse, **or** the corpse's launch predates the boot instant); an instance whose corpse cannot be dated — no birth stamp, or no boot oracle on the platform — is treated as ineligible rather than guessed at. Only a cleanly-closed instance and a **restart casualty** arm a watcher. The reason is the deploy case: on Windows an operator kills a shell precisely to free its exe for overwrite, and a watcher armed there would re-lock the file under them.\n+**Online/offline are mutually-exclusive processes:** a live shell binary (including a launch awaiting bind) excludes its wake-watcher. A recorded-offline instance is watcher-eligible when it is persistent, carries no corpse, or its corpse's launch predates machine boot. **Only nonpersistent instances retain the same-boot force-kill freeze:** their same-boot or undatable corpses arm no watcher, preserving the deploy/overwrite case. A persistent corpse bypasses that freeze even without a launch stamp or boot oracle (releases#287). Missing birth evidence retains the existing fail-toward-alive process probe; it is not itself a restore refusal.\n \n **Exit-opcode supervision:** the wake-watcher exiting with the **wake opcode** → spt-core runs the wake resolution (below) and brings the shell online. Any *other* exit (crash) → respawn the watcher with **exponential backoff + eventual give-up** (until next shell activity) — crash-bug safety. One watcher per offline shell instance.\n \ndiff --git a/crates/spt-daemon/src/shellhost.rs b/crates/spt-daemon/src/shellhost.rs\nindex 593c6f68..44df752b 100644\n--- a/crates/spt-daemon/src/shellhost.rs\n+++ b/crates/spt-daemon/src/shellhost.rs\n@@ -312,16 +312,14 @@ pub fn routes_through_daemon(shell: &Shell) -> bool {\n /// down and adopt it. Used by BOTH sides of the routed launch, because a late\n /// ack can put the caller and the daemon in the same launch at once.\n ///\n-/// DERIVED, never the recorded status (REQ-HAZARD-SHELL-STALE-ONLINE): a pid\n-/// that is absent, unparseable or `0` reads NOT-a-winner, the same\n-/// fail-toward-alive stance the rest of the shell machinery holds — so a\n-/// backend that records no pid can never block its own relaunch. Same shape and\n-/// same non-fault wording as [`crate::shellwake::resolve_wake`]'s existing\n-/// guard; this is that rule extracted, not a second one.\n+/// Birth-safe, including a binary awaiting bind: a recycled live pid is NOT a\n+/// winner when its native birth stamp mismatches. Missing, unparseable and zero\n+/// pids remain not-a-winner, preserving pid-less backend behavior.\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n+// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n pub fn live_launch_winner(shell_perch: &Path) -> Option {\n shellinfo::read_shell_pid(shell_perch)\n- .filter(|&p| p != 0 && spt_store::proc::is_process_alive(p))\n+ .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\n }\n \n /// THE route-selection seam. Generic over the daemon call and the in-process\n@@ -1204,6 +1202,7 @@ mod tests {\n // that parses non-zero AND probes alive is a winner. Absent / `0` /\n // unparseable / dead must all read NOT-a-winner, or a backend that records\n // no usable pid would be unable to relaunch its own instance.\n+ // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n #[test]\n fn only_a_live_recorded_pid_wins_a_launch_race() {\n let tmp = tempfile::tempdir().unwrap();\n@@ -1225,6 +1224,18 @@ mod tests {\n Some(me),\n \"a recorded pid that probes alive IS the winner\"\n );\n+ shellinfo::record_shell_launch(perch, me, 1_000);\n+ assert_eq!(live_launch_winner(perch), Some(me), \"same birth retains custody\");\n+ let mut launch = shellinfo::read_shell_launch(perch).unwrap();\n+ launch.pid_started_at = Some(\n+ launch.pid_started_at.expect(\"native birth stamp on supported platforms\") ^ 1,\n+ );\n+ std::fs::write(\n+ perch.join(shellinfo::SHELL_LAUNCH_FILE),\n+ serde_json::to_string(&launch).unwrap(),\n+ )\n+ .unwrap();\n+ assert_eq!(live_launch_winner(perch), None, \"a recycled pid cannot block restore\");\n }\n \n // [unit->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE] a REAL dial at a socket name\ndiff --git a/crates/spt-daemon/src/shellwake.rs b/crates/spt-daemon/src/shellwake.rs\nindex 7caf020f..d9631b4d 100644\n--- a/crates/spt-daemon/src/shellwake.rs\n+++ b/crates/spt-daemon/src/shellwake.rs\n@@ -613,7 +613,7 @@ fn fill_wake_command(\n /// correction of a field that is already wrong. Nothing is started here.\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n-fn heal_stale_online_records(owlery: &Path) {\n+fn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n if info.status != SHELL_STATUS_ONLINE {\n@@ -627,7 +627,8 @@ fn heal_stale_online_records(owlery: &Path) {\n let mut healed = info.clone();\n healed.status = truth.to_string();\n if shellinfo::write_shell_info(&perch, &healed).is_ok() {\n- spt_proto::emit_line_err!(\"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n+ // [impl->REQ-SHELL-HEAL-ENUMERATION]\n+ let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n }\n }\n }\n@@ -639,67 +640,40 @@ fn heal_stale_online_records(owlery: &Path) {\n /// now-minus-uptime, which drifts by however long the two calls take and by\n /// whatever the clock did since — so a process launched in the first moments of\n /// a boot can compute as very slightly older than the boot itself. Without slack\n-/// that reads as \"a corpse from the previous boot\" and the sweep would relaunch\n-/// something that had just started. Ten seconds is far wider than any plausible\n+/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\n+/// could be armed after a same-boot death. Ten seconds is far wider than plausible\n /// derivation error and far narrower than the gap this discriminant exists to\n /// detect (a previous boot is minutes to days back).\n pub const BOOT_RESTORE_SLACK_MS: u64 = 10_000;\n \n-/// Whether a recorded launch predates the current boot — leg (b)'s discriminant\n-/// (releases#78).\n-///\n-/// This is what preserves the force-kill ruling BY CONSTRUCTION rather than by a\n-/// second rule: a shell force-killed during steady-state operation was launched\n-/// AFTER the current boot, so it can never satisfy this predicate and is never\n-/// spontaneously relaunched — the mid-deploy exe-overwrite case that ruling\n-/// protects is untouched. Only a fresh boot restores.\n-///\n-/// Pure over its inputs so the boundary is unit-testable without a reboot.\n-// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n+/// Whether a nonpersistent shell's recorded launch predates the current boot.\n+/// This preserves its same-boot force-kill freeze; persistent shells do not use\n+/// launch age as eligibility (releases#287).\n+// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n pub fn launch_predates_boot(launched_ms: u64, boot_ms: u64, slack_ms: u64) -> bool {\n launched_ms.saturating_add(slack_ms) < boot_ms\n }\n \n-/// Is this instance watcher-eligible? The class-(c) site of\n-/// REQ-HAZARD-SHELL-STALE-ONLINE, ruled onto the corpse-boot discriminant\n-/// (doyle, releases#78 comment 5156810267).\n-///\n-/// It reads the RECORDED status — never the derived one — and then asks the SAME\n-/// `launch_predates_boot` question leg (b) asks. Three arms, and each one is the\n-/// answer to a case the other two get wrong:\n-///\n-/// - **force-killed THIS boot** ⇒ record healed to offline (honest), corpse\n-/// launched after boot ⇒ NOT eligible. This is what the class-(c) freeze\n-/// protects: on Windows an operator kills a shell precisely to free its exe\n-/// for overwrite (shared install dir ⇒ a routine deploy step), and a watcher\n-/// armed here would re-lock the file under them on the next spooled frame.\n-/// Recovery stays demand-driven — `relink`, or a `shell cmd` that wakes.\n-/// - **restart casualty** (corpse launched BEFORE this boot) ⇒ eligible, the\n-/// operator-greenlit scope of #78 leg (b). Two routes, one answer: the boot\n-/// sweep restores it once, and the watcher covers it on demand thereafter.\n-/// - **cleanly closed** (no corpse — `close_shell` retires the pid file) ⇒\n-/// eligible exactly as before this change.\n-///\n-/// WHY THE CORPSE IS DEFINED ON THE PARKED STAMPS and not on a live pid re-probe:\n-/// `shell_pid_provably_dead` runs the PAIR test, so a RECYCLED pid (alive, but\n-/// its native start stamp mismatches the one leg (a) parked) reads as a corpse —\n-/// because our process IS dead. Without that, a race walks straight back into the\n-/// forbidden shape: the heal fires on the true corpse, the OS recycles its pid\n-/// before the next tick, this read sees \"alive ⇒ no corpse\", and a force-killed\n-/// instance is adopted after all.\n-///\n-/// NO STAMP, or no boot oracle on this platform ⇒ NOT eligible when a corpse is\n-/// present: the discriminant cannot be evaluated, and the safe direction is to\n-/// leave a shell down rather than arm a relaunch of a binary an operator may have\n-/// killed on purpose. Same stance, same reason, as the boot sweep's.\n+/// Watchers require an offline instance with no live launch awaiting bind.\n+/// Persistent shells bypass the corpse-age freeze (releases#287); nonpersistent\n+/// corpses still need a dated pre-boot launch. Missing dates fail closed only\n+/// for that nonpersistent freeze, never for persistent restoration.\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n-fn watcher_eligible(perch: &Path, info: &shellinfo::ShellInfo, boot_ms: Option) -> bool {\n+fn watcher_eligible(\n+ perch: &Path,\n+ info: &shellinfo::ShellInfo,\n+ persistent: bool,\n+ boot_ms: Option,\n+) -> bool {\n if info.status != SHELL_STATUS_OFFLINE {\n return false;\n }\n- if !shellinfo::shell_pid_provably_dead(perch) {\n- return true; // no corpse: cleanly closed, or never launched\n+ if crate::shellhost::live_launch_winner(perch).is_some() {\n+ return false; // binding: the shell binary and watcher must not overlap\n+ }\n+ if persistent || !shellinfo::shell_pid_provably_dead(perch) {\n+ return true; // persistence overrides the freeze; clean closes need no age\n }\n let (Some(boot_ms), Some(launch)) = (boot_ms, shellinfo::read_shell_launch(perch)) else {\n return false;\n@@ -742,26 +716,10 @@ impl RestoreTrigger {\n /// ONE owner's slice of the persistent-shell restore decision -- the body BOTH\n /// triggers run.\n ///\n-/// It is shared rather than restated because the refusal arms ARE the ruling:\n-/// doyle's condition on releases#228 was that the owner-online trigger carry the\n-/// boot sweep's arms VERBATIM, and two copies of a conjunction drift the first\n-/// time one side is edited. Every gate is a conjunction and each one is\n-/// load-bearing:\n-///\n-/// - the adapter section says `persistent` — the contract promise is scoped to\n-/// exactly those, and a non-persistent instance was never owed a restore;\n-/// - the OWNER endpoint is online — an offline owner is owed nothing, which is\n-/// the difference between healing a record and resurrecting a shell nobody is\n-/// there to drive;\n-/// - the instance is down IN FACT (the derived read, which the birth stamp from\n-/// leg (a) now makes trustworthy across a pid reuse);\n-/// - and its recorded launch PREDATES THE BOOT INSTANT.\n-///\n-/// An instance with NO launch stamp is deliberately NOT restored: the sweep\n-/// cannot prove it predates boot, and the safe direction here is to leave a\n-/// shell down rather than relaunch a binary an operator may have killed on\n-/// purpose. Such an instance gains a stamp the first time it is launched by a\n-/// build carrying leg (a), and is covered from then on.\n+/// Both triggers restore every persistent instance whose owner is online and\n+/// whose binary is down in fact. Birth-safe liveness excludes a live launch\n+/// awaiting bind as well as an already-online shell. Machine boot and launch\n+/// age are irrelevant, including missing stamps (releases#287 operator ruling).\n ///\n /// `set` is the daemon's live watcher set, and it is `None` at boot ON PURPOSE:\n /// the sweep runs before the reconcile loop's first tick, so no watcher can yet\n@@ -773,13 +731,11 @@ impl RestoreTrigger {\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n // [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n-#[allow(clippy::too_many_arguments)]\n fn restore_persistent_shells_of_owner(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n owner: &str,\n- boot_ms: u64,\n trigger: RestoreTrigger,\n set: Option<&Arc>,\n restored: &mut Vec,\n@@ -795,14 +751,10 @@ fn restore_persistent_shells_of_owner(\n continue;\n };\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &shell_id);\n- if shellinfo::is_shell_online(&perch, &info) {\n- continue; // already up in fact\n- }\n- let Some(launch) = shellinfo::read_shell_launch(&perch) else {\n- continue; // no stamp ⇒ cannot prove it predates boot ⇒ leave it down\n- };\n- if !launch_predates_boot(launch.launched_ms, boot_ms, BOOT_RESTORE_SLACK_MS) {\n- continue; // launched THIS boot: a force-kill, not a restart casualty\n+ if shellinfo::is_shell_online(&perch, &info)\n+ || crate::shellhost::live_launch_winner(&perch).is_some()\n+ {\n+ continue; // already online or binding in fact\n }\n // Mutual exclusivity, the online side: the watcher dies before the binary\n // rises. `launch_shell` already kills the waker CHILD, but the supervising\n@@ -844,11 +796,6 @@ pub fn restore_persistent_shells_at_boot(\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n ) -> Vec {\n- let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n- // No boot oracle on this platform: the discriminant cannot be evaluated,\n- // so nothing is restored. Silence beats guessing at a relaunch.\n- return Vec::new();\n- };\n let mut restored = Vec::new();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n restore_persistent_shells_of_owner(\n@@ -856,7 +803,6 @@ pub fn restore_persistent_shells_at_boot(\n registered,\n adapters_dir,\n &owner,\n- boot_ms,\n RestoreTrigger::Boot,\n None,\n &mut restored,\n@@ -868,12 +814,9 @@ pub fn restore_persistent_shells_at_boot(\n /// Per-owner online state carried ACROSS reconcile passes, so the restore below\n /// can be EDGE-triggered on an owner's offline->online transition.\n ///\n-/// WHY AN EDGE AND NOT A LEVEL (doyle's condition, releases#228): a successful\n-/// restore self-limits, because the launch restamps `launched_ms` to now and the\n-/// corpse-boot discriminant refuses that instance from then on. A FAILING launch","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299,300]},"truncation":{"content":"diff --git a/CHANGELOG.md b/CHANGELOG.md\nindex eafe18d6..39bf8144 100644\n--- a/CHANGELOG.md\n+++ b/CHANGELOG.md\n@@ -10,6 +10,19 @@ breaks something, or changes the observable behavior of existing surfaces\n broadly; **patch** for fixes, and for additive opt-in capability — a new key,\n flag, or page that no existing user can encounter without opting into it.\n \n+## [Unreleased]\n+\n+### Fixed\n+\n+- Every persistent shell comes back with its owner after a daemon-only restart,\n+ not just after a machine reboot. Shells launched during the current boot or\n+ without a saved launch stamp are no longer left down, and recovery notices\n+ name every healed instance for each owner. A persistent shell must be torn\n+ down or made nonpersistent to stay down; killing its process does not opt out\n+ of restoration.\n+- A successful `spt shell relink` reports `binding` while awaiting its handshake,\n+ rather than making the successful launch read as `offline`.\n+\n ## [0.68.0] - 2026-09-08\n \n Web serving. Files, directories, adapter documentation and the changelog are\ndiff --git a/CONTEXT.md b/CONTEXT.md\nindex cdb8a8e1..6698a590 100644\n--- a/CONTEXT.md\n+++ b/CONTEXT.md\n@@ -388,11 +388,11 @@ The manifest value is the **floor**: a node/endpoint setting may **tighten** (de\n \n A shell automatically goes **offline when its owner endpoint goes offline**. Two complementary manifest options bring it (and its owner) back:\n \n-- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified once instances span nodes** (ruled 2026-07-24, #70 grill): when an owner comes online at a given node, only the **latest** instances qualified to that *endpoint@node* pairing come online with it — a stale instance of the same shell left on another node does not auto-wake alongside. **A node restart is covered by a boot sweep, and an owner that comes online after that sweep by an owner-online edge** (BAROMETER W2 releases#78; CONDUIT W2 releases#228): a machine death breaks no link, so the instance's record survives the reboot still saying `online` and the wake cascade — which reads the *recorded* field — skips it, stranding every `persistent` instance on the node at once. The daemon therefore (i) heals a recorded `online` its derived status contradicts, every reconcile cycle, writing only when the value actually changes, and (ii) runs a **once-per-daemon-generation boot sweep** that relaunches an instance when **all four** conditions hold: the adapter declares `persistent`; the **owner endpoint is online** (an offline owner is owed nothing); the instance is down **in fact**; and its **recorded launch predates the boot instant**. A launch parks a **birth stamp** beside the pid to make that last question answerable — **no stamp ⇒ not restored** (the sweep cannot prove the corpse predates boot, and leaving a shell down beats relaunching a binary an operator may have killed deliberately), and a platform with no boot oracle restores nothing. A shell force-killed *during* this boot is launched after it, can never satisfy the predicate, and so is never spontaneously relaunched — the deploy/quarantine ruling of KNOWN-HAZARDS 2.6 preserved by construction. \n- **Daemons boot before endpoints do, so the sweep is not the only trigger** (releases#228): an owner that is not yet online when the sweep runs is skipped by that very conjunct, and — the sweep being once per daemon generation, and bringup from offline emitting no rest edge — nothing revisited it, so its shells stayed down until a human relinked. The reconcile loop therefore runs the **same four conditions** for every owner that has gone **offline→online since the last pass**. The trigger is that **edge, never the level “the owner is online”**: a successful restore restamps itself out of eligibility, but a *failing* launch under a level trigger would be retried every reconcile tick for as long as the owner stayed up, where the edge bounds it to one attempt per owner-online event. Re-evaluating later in a generation can only refuse **more**, never less — every launch path restamps the birth stamp, a kill never does, and the boot instant is fixed for the machine boot — so the force-kill ruling above is preserved identically on the second trigger. \n-- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs *while the shell is offline* **and eligible** (the eligibility rule is below — an offline instance sitting on a same-boot corpse arms no watcher). Its sole job is to fire a wake. It runs on the **shell's node** (where the platform wake-event originates — e.g. interacting with a \"shut-down\" avatar). Covers \"owner is down, wake it from outside.\"\n+- **`persistent`** (bool): the shell is automatically brought **online whenever its owner endpoint is online**. Covers \"owner already up.\" **Node-qualified once instances span nodes** (ruled 2026-07-24, #70 grill): when an owner comes online at a given node, only the **latest** instances qualified to that *endpoint@node* pairing come online with it — a stale instance of the same shell left on another node does not auto-wake alongside. A **once-per-daemon-generation boot sweep** restores every down persistent instance whose owner is online, after a machine reboot **or a daemon-only restart**. Birth-safe liveness protects both an online binary and a live launch awaiting bind. Machine boot time, recorded launch age, and missing launch stamps do **not** gate restoration (releases#287 operator ruling). The daemon also heals stale `online` records to `offline` each reconcile cycle, only on an actual change. \n+ **Daemons boot before endpoints do, so the sweep is not the only trigger:** the reconcile loop runs that **same per-owner restore decision** on each owner **offline→online edge**. The edge is seeded before the sweep; a live launch awaiting bind prevents duplicate launch if both triggers reach it. Failed launches are attempted once per owner-online event, not every tick while the owner stays online. A force-kill does not revoke persistence: use `teardown` or a nonpersistent manifest to keep the instance down. \n+- **`wake_command`** (template): a long-running **wake-watcher** process spt-core runs while the shell is offline and eligible. Its sole job is to fire a wake. It runs on the **shell's node**, where the platform wake-event originates (e.g. interacting with a shut-down avatar). Covers \"owner is down, wake it from outside.\"\n \n-**Online/offline are mutually-exclusive processes:** online ⇒ the shell binary runs (no watcher); offline ⇒ the wake-watcher runs (no shell binary). spt-core flips between them. **Offline does not by itself arm the watcher — a third outcome exists** (BAROMETER W2, releases#78): an instance that is offline over a **corpse launched during this boot** (a force-kill, a crash) is deliberately held out of watcher eligibility, so *neither* process runs until recovery is demanded — `relink`, or a `shell cmd` that wakes. Eligibility is recorded-`offline` **AND** (no corpse, **or** the corpse's launch predates the boot instant); an instance whose corpse cannot be dated — no birth stamp, or no boot oracle on the platform — is treated as ineligible rather than guessed at. Only a cleanly-closed instance and a **restart casualty** arm a watcher. The reason is the deploy case: on Windows an operator kills a shell precisely to free its exe for overwrite, and a watcher armed there would re-lock the file under them.\n+**Online/offline are mutually-exclusive processes:** a live shell binary (including a launch awaiting bind) excludes its wake-watcher. A recorded-offline instance is watcher-eligible when it is persistent, carries no corpse, or its corpse's launch predates machine boot. **Only nonpersistent instances retain the same-boot force-kill freeze:** their same-boot or undatable corpses arm no watcher, preserving the deploy/overwrite case. A persistent corpse bypasses that freeze even without a launch stamp or boot oracle (releases#287). Missing birth evidence retains the existing fail-toward-alive process probe; it is not itself a restore refusal.\n \n **Exit-opcode supervision:** the wake-watcher exiting with the **wake opcode** → spt-core runs the wake resolution (below) and brings the shell online. Any *other* exit (crash) → respawn the watcher with **exponential backoff + eventual give-up** (until next shell activity) — crash-bug safety. One watcher per offline shell instance.\n \ndiff --git a/crates/spt-daemon/src/shellhost.rs b/crates/spt-daemon/src/shellhost.rs\nindex 593c6f68..44df752b 100644\n--- a/crates/spt-daemon/src/shellhost.rs\n+++ b/crates/spt-daemon/src/shellhost.rs\n@@ -312,16 +312,14 @@ pub fn routes_through_daemon(shell: &Shell) -> bool {\n /// down and adopt it. Used by BOTH sides of the routed launch, because a late\n /// ack can put the caller and the daemon in the same launch at once.\n ///\n-/// DERIVED, never the recorded status (REQ-HAZARD-SHELL-STALE-ONLINE): a pid\n-/// that is absent, unparseable or `0` reads NOT-a-winner, the same\n-/// fail-toward-alive stance the rest of the shell machinery holds — so a\n-/// backend that records no pid can never block its own relaunch. Same shape and\n-/// same non-fault wording as [`crate::shellwake::resolve_wake`]'s existing\n-/// guard; this is that rule extracted, not a second one.\n+/// Birth-safe, including a binary awaiting bind: a recycled live pid is NOT a\n+/// winner when its native birth stamp mismatches. Missing, unparseable and zero\n+/// pids remain not-a-winner, preserving pid-less backend behavior.\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n+// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n pub fn live_launch_winner(shell_perch: &Path) -> Option {\n shellinfo::read_shell_pid(shell_perch)\n- .filter(|&p| p != 0 && spt_store::proc::is_process_alive(p))\n+ .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\n }\n \n /// THE route-selection seam. Generic over the daemon call and the in-process\n@@ -1204,6 +1202,7 @@ mod tests {\n // that parses non-zero AND probes alive is a winner. Absent / `0` /\n // unparseable / dead must all read NOT-a-winner, or a backend that records\n // no usable pid would be unable to relaunch its own instance.\n+ // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n #[test]\n fn only_a_live_recorded_pid_wins_a_launch_race() {\n let tmp = tempfile::tempdir().unwrap();\n@@ -1225,6 +1224,18 @@ mod tests {\n Some(me),\n \"a recorded pid that probes alive IS the winner\"\n );\n+ shellinfo::record_shell_launch(perch, me, 1_000);\n+ assert_eq!(live_launch_winner(perch), Some(me), \"same birth retains custody\");\n+ let mut launch = shellinfo::read_shell_launch(perch).unwrap();\n+ launch.pid_started_at = Some(\n+ launch.pid_started_at.expect(\"native birth stamp on supported platforms\") ^ 1,\n+ );\n+ std::fs::write(\n+ perch.join(shellinfo::SHELL_LAUNCH_FILE),\n+ serde_json::to_string(&launch).unwrap(),\n+ )\n+ .unwrap();\n+ assert_eq!(live_launch_winner(perch), None, \"a recycled pid cannot block restore\");\n }\n \n // [unit->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE] a REAL dial at a socket name\ndiff --git a/crates/spt-daemon/src/shellwake.rs b/crates/spt-daemon/src/shellwake.rs\nindex 7caf020f..d9631b4d 100644\n--- a/crates/spt-daemon/src/shellwake.rs\n+++ b/crates/spt-daemon/src/shellwake.rs\n@@ -613,7 +613,7 @@ fn fill_wake_command(\n /// correction of a field that is already wrong. Nothing is started here.\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n-fn heal_stale_online_records(owlery: &Path) {\n+fn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n if info.status != SHELL_STATUS_ONLINE {\n@@ -627,7 +627,8 @@ fn heal_stale_online_records(owlery: &Path) {\n let mut healed = info.clone();\n healed.status = truth.to_string();\n if shellinfo::write_shell_info(&perch, &healed).is_ok() {\n- spt_proto::emit_line_err!(\"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n+ // [impl->REQ-SHELL-HEAL-ENUMERATION]\n+ let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n }\n }\n }\n@@ -639,67 +640,40 @@ fn heal_stale_online_records(owlery: &Path) {\n /// now-minus-uptime, which drifts by however long the two calls take and by\n /// whatever the clock did since — so a process launched in the first moments of\n /// a boot can compute as very slightly older than the boot itself. Without slack\n-/// that reads as \"a corpse from the previous boot\" and the sweep would relaunch\n-/// something that had just started. Ten seconds is far wider than any plausible\n+/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\n+/// could be armed after a same-boot death. Ten seconds is far wider than plausible\n /// derivation error and far narrower than the gap this discriminant exists to\n /// detect (a previous boot is minutes to days back).\n pub const BOOT_RESTORE_SLACK_MS: u64 = 10_000;\n \n-/// Whether a recorded launch predates the current boot — leg (b)'s discriminant\n-/// (releases#78).\n-///\n-/// This is what preserves the force-kill ruling BY CONSTRUCTION rather than by a\n-/// second rule: a shell force-killed during steady-state operation was launched\n-/// AFTER the current boot, so it can never satisfy this predicate and is never\n-/// spontaneously relaunched — the mid-deploy exe-overwrite case that ruling\n-/// protects is untouched. Only a fresh boot restores.\n-///\n-/// Pure over its inputs so the boundary is unit-testable without a reboot.\n-// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n+/// Whether a nonpersistent shell's recorded launch predates the current boot.\n+/// This preserves its same-boot force-kill freeze; persistent shells do not use\n+/// launch age as eligibility (releases#287).\n+// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n pub fn launch_predates_boot(launched_ms: u64, boot_ms: u64, slack_ms: u64) -> bool {\n launched_ms.saturating_add(slack_ms) < boot_ms\n }\n \n-/// Is this instance watcher-eligible? The class-(c) site of\n-/// REQ-HAZARD-SHELL-STALE-ONLINE, ruled onto the corpse-boot discriminant\n-/// (doyle, releases#78 comment 5156810267).\n-///\n-/// It reads the RECORDED status — never the derived one — and then asks the SAME\n-/// `launch_predates_boot` question leg (b) asks. Three arms, and each one is the\n-/// answer to a case the other two get wrong:\n-///\n-/// - **force-killed THIS boot** ⇒ record healed to offline (honest), corpse\n-/// launched after boot ⇒ NOT eligible. This is what the class-(c) freeze\n-/// protects: on Windows an operator kills a shell precisely to free its exe\n-/// for overwrite (shared install dir ⇒ a routine deploy step), and a watcher\n-/// armed here would re-lock the file under them on the next spooled frame.\n-/// Recovery stays demand-driven — `relink`, or a `shell cmd` that wakes.\n-/// - **restart casualty** (corpse launched BEFORE this boot) ⇒ eligible, the\n-/// operator-greenlit scope of #78 leg (b). Two routes, one answer: the boot\n-/// sweep restores it once, and the watcher covers it on demand thereafter.\n-/// - **cleanly closed** (no corpse — `close_shell` retires the pid file) ⇒\n-/// eligible exactly as before this change.\n-///\n-/// WHY THE CORPSE IS DEFINED ON THE PARKED STAMPS and not on a live pid re-probe:\n-/// `shell_pid_provably_dead` runs the PAIR test, so a RECYCLED pid (alive, but\n-/// its native start stamp mismatches the one leg (a) parked) reads as a corpse —\n-/// because our process IS dead. Without that, a race walks straight back into the\n-/// forbidden shape: the heal fires on the true corpse, the OS recycles its pid\n-/// before the next tick, this read sees \"alive ⇒ no corpse\", and a force-killed\n-/// instance is adopted after all.\n-///\n-/// NO STAMP, or no boot oracle on this platform ⇒ NOT eligible when a corpse is\n-/// present: the discriminant cannot be evaluated, and the safe direction is to\n-/// leave a shell down rather than arm a relaunch of a binary an operator may have\n-/// killed on purpose. Same stance, same reason, as the boot sweep's.\n+/// Watchers require an offline instance with no live launch awaiting bind.\n+/// Persistent shells bypass the corpse-age freeze (releases#287); nonpersistent\n+/// corpses still need a dated pre-boot launch. Missing dates fail closed only\n+/// for that nonpersistent freeze, never for persistent restoration.\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n-fn watcher_eligible(perch: &Path, info: &shellinfo::ShellInfo, boot_ms: Option) -> bool {\n+fn watcher_eligible(\n+ perch: &Path,\n+ info: &shellinfo::ShellInfo,\n+ persistent: bool,\n+ boot_ms: Option,\n+) -> bool {\n if info.status != SHELL_STATUS_OFFLINE {\n return false;\n }\n- if !shellinfo::shell_pid_provably_dead(perch) {\n- return true; // no corpse: cleanly closed, or never launched\n+ if crate::shellhost::live_launch_winner(perch).is_some() {\n+ return false; // binding: the shell binary and watcher must not overlap\n+ }\n+ if persistent || !shellinfo::shell_pid_provably_dead(perch) {\n+ return true; // persistence overrides the freeze; clean closes need no age\n }\n let (Some(boot_ms), Some(launch)) = (boot_ms, shellinfo::read_shell_launch(perch)) else {\n return false;\n@@ -742,26 +716,10 @@ impl RestoreTrigger {\n /// ONE owner's slice of the persistent-shell restore decision -- the body BOTH\n /// triggers run.\n ///\n-/// It is shared rather than restated because the refusal arms ARE the ruling:\n-/// doyle's condition on releases#228 was that the owner-online trigger carry the\n-/// boot sweep's arms VERBATIM, and two copies of a conjunction drift the first\n-/// time one side is edited. Every gate is a conjunction and each one is\n-/// load-bearing:\n-///\n-/// - the adapter section says `persistent` — the contract promise is scoped to\n-/// exactly those, and a non-persistent instance was never owed a restore;\n-/// - the OWNER endpoint is online — an offline owner is owed nothing, which is\n-/// the difference between healing a record and resurrecting a shell nobody is\n-/// there to drive;\n-/// - the instance is down IN FACT (the derived read, which the birth stamp from\n-/// leg (a) now makes trustworthy across a pid reuse);\n-/// - and its recorded launch PREDATES THE BOOT INSTANT.\n-///\n-/// An instance with NO launch stamp is deliberately NOT restored: the sweep\n-/// cannot prove it predates boot, and the safe direction here is to leave a\n-/// shell down rather than relaunch a binary an operator may have killed on\n-/// purpose. Such an instance gains a stamp the first time it is launched by a\n-/// build carrying leg (a), and is covered from then on.\n+/// Both triggers restore every persistent instance whose owner is online and\n+/// whose binary is down in fact. Birth-safe liveness excludes a live launch\n+/// awaiting bind as well as an already-online shell. Machine boot and launch\n+/// age are irrelevant, including missing stamps (releases#287 operator ruling).\n ///\n /// `set` is the daemon's live watcher set, and it is `None` at boot ON PURPOSE:\n /// the sweep runs before the reconcile loop's first tick, so no watcher can yet\n@@ -773,13 +731,11 @@ impl RestoreTrigger {\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n // [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n-#[allow(clippy::too_many_arguments)]\n fn restore_persistent_shells_of_owner(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n owner: &str,\n- boot_ms: u64,\n trigger: RestoreTrigger,\n set: Option<&Arc>,\n restored: &mut Vec,\n@@ -795,14 +751,10 @@ fn restore_persistent_shells_of_owner(\n continue;\n };\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &shell_id);\n- if shellinfo::is_shell_online(&perch, &info) {\n- continue; // already up in fact\n- }\n- let Some(launch) = shellinfo::read_shell_launch(&perch) else {\n- continue; // no stamp ⇒ cannot prove it predates boot ⇒ leave it down\n- };\n- if !launch_predates_boot(launch.launched_ms, boot_ms, BOOT_RESTORE_SLACK_MS) {\n- continue; // launched THIS boot: a force-kill, not a restart casualty\n+ if shellinfo::is_shell_online(&perch, &info)\n+ || crate::shellhost::live_launch_winner(&perch).is_some()\n+ {\n+ continue; // already online or binding in fact\n }\n // Mutual exclusivity, the online side: the watcher dies before the binary\n // rises. `launch_shell` already kills the waker CHILD, but the supervising\n@@ -844,11 +796,6 @@ pub fn restore_persistent_shells_at_boot(\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n ) -> Vec {\n- let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n- // No boot oracle on this platform: the discriminant cannot be evaluated,\n- // so nothing is restored. Silence beats guessing at a relaunch.\n- return Vec::new();\n- };\n let mut restored = Vec::new();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n restore_persistent_shells_of_owner(\n@@ -856,7 +803,6 @@ pub fn restore_persistent_shells_at_boot(\n registered,\n adapters_dir,\n &owner,\n- boot_ms,\n RestoreTrigger::Boot,\n None,\n &mut restored,\n@@ -868,12 +814,9 @@ pub fn restore_persistent_shells_at_boot(\n /// Per-owner online state carried ACROSS reconcile passes, so the restore below\n /// can be EDGE-triggered on an owner's offline->online transition.\n ///\n-/// WHY AN EDGE AND NOT A LEVEL (doyle's condition, releases#228): a successful\n-/// restore self-limits, because the launch restamps `launched_ms` to now and the\n-/// corpse-boot discriminant refuses that instance from then on. A FAILING launch","truncated":true,"truncatedBy":"lines","totalLines":1088,"totalBytes":22745,"outputLines":300,"outputBytes":22745,"lastLinePartial":false,"firstLineExceedsLimit":false},"meta":{"source":{"type":"internal","value":"artifact://112"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":1088,"totalBytes":22745,"outputLines":300,"outputBytes":22745,"maxBytes":153600,"shownRange":{"start":1,"end":300},"nextOffset":301}}},"isError":false,"timestamp":1789001101754}}
{"type":"message","id":"39a9a06d","parentId":"8abef4f6","timestamp":"2026-09-10T00:45:01.755Z","message":{"role":"toolResult","toolCallId":"call_SoXnwtS6OxjKMOFNagDliZYD|fc_077f3569365e313d016aa1fd8dabb487d19e2dbb48a2ab8749","toolName":"read","content":[{"type":"text","text":"@AGENTS.md\n\n"}],"details":{"totalLines":7,"displayContent":{"text":"@AGENTS.md\r\n\r\n\r","startLine":1,"lineNumbers":[1,2,3,4,5,6,7]},"fileSize":293,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\CLAUDE.md"}}},"isError":false,"timestamp":1789001101755}}
{"type":"message","id":"b4b131f7","parentId":"39a9a06d","timestamp":"2026-09-10T00:45:01.758Z","message":{"role":"toolResult","toolCallId":"call_8hdpFa9bn2kiSxq2op7zz0Ps|fc_077f3569365e313d016aa1fd8dabbc87d19b254ad7b50831fe","toolName":"read","content":[{"type":"text","text":"# spt-core — agent working rules\n\nHarness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract). Rust crates + a single `spt` binary. Clean-room rebuild of `claude_skill_owl`.\n\n**Orientation — read before working:** `PRD.md` (requirements), `ROADMAP.md` (build path), `CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break), `docs/{STORAGE,MANIFEST,CONTEXT-MEMORY,DOCS-STRATEGY,TRACEABILITY}.md`.\n\nFor maintainer/debug update work, also read `docs/DEBUG-ROLLOUT.md` before touching the update-set or rollout path.\n\nFor work needing Linux tests and proof, this machine is authorized to ssh into a Linux box: `reavus@kitsubito`\n\nIMPORTANT: All agents you work alongside run on spt-core itself — the legacy-SPT (`$OWL`/`$LIVE`) era ended with the 2026-07 fleet migration; those commands are gone. Reach other agents with `spt send` (or the `/sptc:send` skill); keep message bodies short, and send long bodies from a file rather than inline. Everything else can be learned from the corresponding `/sptc:` skill doc.\n\n## Requirement traceability (binding)\n\nThis project uses `traceable-reqs` (`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is `docs/TRACEABILITY.md`. The rules you must follow:\n\n1. **Tag evidence in the same change.** When you write a function/test/doc-section that satisfies a requirement stage, add its tag in that same commit:\n `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · ``\n Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real evidence — never at file tops to satisfy coverage.\n2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid evidence — fix it, don't ship it.\n3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then satisfy it. No untracked work; no untagged evidence.\n4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's \"covered.\" Treat the hazard list as a conformance checklist you must satisfy, not advice.\n5. **Activate, don't pre-fail.** Requirements you aren't yet working stay `required_stages = []`. Activate (set real stages) only when starting the milestone that delivers them.\n\n## Issue tracking (unique case)\n\nCodebase issues are maintained on **`BigscreenVR/spt-bs-releases`** — the less-private *releases* repo — NOT on `spt-bs-core` where the code lives. This is a deliberate exception (operator-ruled 2026-07-27): file, triage, and reference issues against `spt-bs-releases`.\n\nRequests and milestones are tracked through the **alchemy shell** (`alchemy-0`, the Requests shell bound to `spt-bs-releases`) on top of those GitHub issues. The label taxonomy is the workflow: `state:` BACKLOG → EVAL → GREENLIT → WIP → ACCEPTANCE → DONE (plus CUT / SHELVED), `type:` BUGFIX / ADDITION / CHANGE, `flag: NEEDS-OPERATOR`, and per-node `kind: SPT-TRACKING` pins (marked DO NOT DELETE — leave them alone).\n\n## Other conventions\n\n- Match surrounding code style; copy-verbatim the sister project's stable wire/schema formats (ADR-0001), clean-room everything else.\n- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once.\n- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation is CI-gated against drift.\n- Commit messages end with the project's co-author trailer, exact spelling `Co-authored by: ` (e.g. `Co-authored by: todlando`) — NOT git's hyphenated `Co-Authored-By:`; CI's runner-informant parses only the space spelling for attribution.\n - **Audit this trailer with `git log --grep` or a raw body read, NEVER `%(trailers:)`** (nor `interpret-trailers --parse`): git's trailer tokenizer requires a whitespace-free token, so the space spelling is structurally invisible to it and every trailer query returns a confident EMPTY on every commit — a clean zero that reads as total attribution loss. Measured 2026-07-30 (main @`8f3e10b`, Signed-off-by and hyphenated-key controls both parse); re-derived at full cost 2026-08-03 by one of its own original measurers, which is why this sentence lives here at the mandate rather than in a document you must decide to open.\n- **Worktrees (binding, operator-ruled 2026-07-05):** every `git worktree` (gate rigs, agent scratch, anything) goes under `.worktrees/` in THIS project's root (`.gitignore`d) — e.g. `git worktree add --detach .worktrees/gate- `. NEVER create worktrees as siblings of the project dir; stray sibling folders accumulate orphan-pinned skeletons and pollute `~/Documents/projects`. Remove yours when done (`git worktree remove` + prune; retry later if a handle pins it).\n\n- **Build-cache pools (binding, releases#103):** a cargo `target/` directory belongs to ONE source tree. Two trees building into one pool overwrite each other's artifacts and fabricate reds that belong to neither — the v0.51.0 W1/H1 `E0308` that vanished on re-run. **The rule is about the RELATIONSHIP, not the path:** a junction and a `CARGO_TARGET_DIR` env var reach the same hazard, and the env var leaves no directory entry to notice afterwards, so \"is this dir under `.worktrees/`\" never was the question. A build script enforces it (`crates/spt-store/build.rs`) and refuses with `SPT_POOL_FOREIGN`. **Sharing a pool SEQUENTIALLY is fine and expected** — a finished lane is taken over loudly, not refused; only a LIVE lane blocks you. Claim a pool at lane start …\n- **Target-tree teardown (releases#103, same lane):** never delete a `target/` you have not classified. Check OUTBOUND first (`Get-Item -Force`: a junction is deleted as a link, a real dir as a tree), then sweep INBOUND for reparse points aimed at it before removing a real one, and measure size and free space before and after so the reclaim is a number rather than a claim. Reap the target SUBTREE, never a session or worktree directory around it. Do not point `CARGO_TARGET_DIR` into a scratchpad (v0.50.0 incident) or at another checkout's target (H1 incident).\n- **CI / merge strategy:** golden CI (ADR-0050, ruled 2026-07-27) — milestone-batch golden runs, thin-lane PRs, ff-only main (tested sha == merged sha). Piloting from the next milestone; read the ADR before shaping a PR lane.\n\nIf you finish a significant body of work without need for user intervention, or if your context gets too high, you can clear your own context and keep moving:\n1. Create a JIT plan for the next immediate body of work, if it isn't already planned\n2. If you are a live agent, /sptc:commune with immediate next steps and broad summary of the project's status + end goal\n3. Execute the /self-clear skill\n\n[Some lines truncated to 768 chars]"}],"details":{"totalLines":47,"displayContent":{"text":"# spt-core — agent working rules\r\n\r\nHarness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract). Rust crates + a single `spt` binary. Clean-room rebuild of `claude_skill_owl`.\r\n\r\n**Orientation — read before working:** `PRD.md` (requirements), `ROADMAP.md` (build path), `CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break), `docs/{STORAGE,MANIFEST,CONTEXT-MEMORY,DOCS-STRATEGY,TRACEABILITY}.md`.\r\n\r\nFor maintainer/debug update work, also read `docs/DEBUG-ROLLOUT.md` before touching the update-set or rollout path.\r\n\r\nFor work needing Linux tests and proof, this machine is authorized to ssh into a Linux box: `reavus@kitsubito`\r\n\r\nIMPORTANT: All agents you work alongside run on spt-core itself — the legacy-SPT (`$OWL`/`$LIVE`) era ended with the 2026-07 fleet migration; those commands are gone. Reach other agents with `spt send` (or the `/sptc:send` skill); keep message bodies short, and send long bodies from a file rather than inline. Everything else can be learned from the corresponding `/sptc:` skill doc.\r\n\r\n## Requirement traceability (binding)\r\n\r\nThis project uses `traceable-reqs` (`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is `docs/TRACEABILITY.md`. The rules you must follow:\r\n\r\n1. **Tag evidence in the same change.** When you write a function/test/doc-section that satisfies a requirement stage, add its tag in that same commit:\r\n `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · ``\r\n Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real evidence — never at file tops to satisfy coverage.\r\n2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid evidence — fix it, don't ship it.\r\n3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then satisfy it. No untracked work; no untagged evidence.\r\n4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's \"covered.\" Treat the hazard list as a conformance checklist you must satisfy, not advice.\r\n5. **Activate, don't pre-fail.** Requirements you aren't yet working stay `required_stages = []`. Activate (set real stages) only when starting the milestone that delivers them.\r\n\r\n## Issue tracking (unique case)\r\n\r\nCodebase issues are maintained on **`BigscreenVR/spt-bs-releases`** — the less-private *releases* repo — NOT on `spt-bs-core` where the code lives. This is a deliberate exception (operator-ruled 2026-07-27): file, triage, and reference issues against `spt-bs-releases`.\r\n\r\nRequests and milestones are tracked through the **alchemy shell** (`alchemy-0`, the Requests shell bound to `spt-bs-releases`) on top of those GitHub issues. The label taxonomy is the workflow: `state:` BACKLOG → EVAL → GREENLIT → WIP → ACCEPTANCE → DONE (plus CUT / SHELVED), `type:` BUGFIX / ADDITION / CHANGE, `flag: NEEDS-OPERATOR`, and per-node `kind: SPT-TRACKING` pins (marked DO NOT DELETE — leave them alone).\r\n\r\n## Other conventions\r\n\r\n- Match surrounding code style; copy-verbatim the sister project's stable wire/schema formats (ADR-0001), clean-room everything else.\r\n- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once.\r\n- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation is CI-gated against drift.\r\n- Commit messages end with the project's co-author trailer, exact spelling `Co-authored by: ` (e.g. `Co-authored by: todlando`) — NOT git's hyphenated `Co-Authored-By:`; CI's runner-informant parses only the space spelling for attribution.\r\n - **Audit this trailer with `git log --grep` or a raw body read, NEVER `%(trailers:)`** (nor `interpret-trailers --parse`): git's trailer tokenizer requires a whitespace-free token, so the space spelling is structurally invisible to it and every trailer query returns a confident EMPTY on every commit — a clean zero that reads as total attribution loss. Measured 2026-07-30 (main @`8f3e10b`, Signed-off-by and hyphenated-key controls both parse); re-derived at full cost 2026-08-03 by one of its own original measurers, which is why this sentence lives here at the mandate rather than in a document you must decide to open.\r\n- **Worktrees (binding, operator-ruled 2026-07-05):** every `git worktree` (gate rigs, agent scratch, anything) goes under `.worktrees/` in THIS project's root (`.gitignore`d) — e.g. `git worktree add --detach .worktrees/gate- `. NEVER create worktrees as siblings of the project dir; stray sibling folders accumulate orphan-pinned skeletons and pollute `~/Documents/projects`. Remove yours when done (`git worktree remove` + prune; retry later if a handle pins it).\r\n\r\n- **Build-cache pools (binding, releases#103):** a cargo `target/` directory belongs to ONE source tree. Two trees building into one pool overwrite each other's artifacts and fabricate reds that belong to neither — the v0.51.0 W1/H1 `E0308` that vanished on re-run. **The rule is about the RELATIONSHIP, not the path:** a junction and a `CARGO_TARGET_DIR` env var reach the same hazard, and the env var leaves no directory entry to notice afterwards, so \"is this dir under `.worktrees/`\" never was the question. A build script enforces it (`crates/spt-store/build.rs`) and refuses with `SPT_POOL_FOREIGN`. **Sharing a pool SEQUENTIALLY is fine and expected** — a finished lane is taken over loudly, not refused; only a LIVE lane blocks you. Claim a pool at lane start …\n- **Target-tree teardown (releases#103, same lane):** never delete a `target/` you have not classified. Check OUTBOUND first (`Get-Item -Force`: a junction is deleted as a link, a real dir as a tree), then sweep INBOUND for reparse points aimed at it before removing a real one, and measure size and free space before and after so the reclaim is a number rather than a claim. Reap the target SUBTREE, never a session or worktree directory around it. Do not point `CARGO_TARGET_DIR` into a scratchpad (v0.50.0 incident) or at another checkout's target (H1 incident).\r\n- **CI / merge strategy:** golden CI (ADR-0050, ruled 2026-07-27) — milestone-batch golden runs, thin-lane PRs, ff-only main (tested sha == merged sha). Piloting from the next milestone; read the ADR before shaping a PR lane.\r\n\r\nIf you finish a significant body of work without need for user intervention, or if your context gets too high, you can clear your own context and keep moving:\r\n1. Create a JIT plan for the next immediate body of work, if it isn't already planned\r\n2. If you are a live agent, /sptc:commune with immediate next steps and broad summary of the project's status + end goal\r\n3. Execute the /self-clear skill\r","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47]},"fileSize":8436,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\AGENTS.md"},"limits":{"columnTruncated":{"maxColumn":768}}}},"isError":false,"timestamp":1789001101758}}
{"type":"message","id":"6bbb3f7d","parentId":"b4b131f7","timestamp":"2026-09-10T00:45:01.764Z","message":{"role":"toolResult","toolCallId":"call_8tZqKMdMkqqi3pvzPDyJk9XB|fc_077f3569365e313d016aa1fd8dabac87d180bc9028fa0b2249","toolName":"read","content":[{"type":"text","text":"# spt-core — agent working rules\n\nHarness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract). Rust crates + a single `spt` binary. Clean-room rebuild of `claude_skill_owl`.\n\n**Orientation — read before working:** `PRD.md` (requirements), `ROADMAP.md` (build path), `CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break), `docs/{STORAGE,MANIFEST,CONTEXT-MEMORY,DOCS-STRATEGY,TRACEABILITY}.md`.\n\nFor maintainer/debug update work, also read `docs/DEBUG-ROLLOUT.md` before touching the update-set or rollout path.\n\nFor work needing Linux tests and proof, this machine is authorized to ssh into a Linux box: `reavus@kitsubito`\n\nIMPORTANT: All agents you work alongside run on spt-core itself — the legacy-SPT (`$OWL`/`$LIVE`) era ended with the 2026-07 fleet migration; those commands are gone. Reach other agents with `spt send` (or the `/sptc:send` skill); keep message bodies short, and send long bodies from a file rather than inline. Everything else can be learned from the corresponding `/sptc:` skill doc.\n\n## Requirement traceability (binding)\n\nThis project uses `traceable-reqs` (`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is `docs/TRACEABILITY.md`. The rules you must follow:\n\n1. **Tag evidence in the same change.** When you write a function/test/doc-section that satisfies a requirement stage, add its tag in that same commit:\n `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · ``\n Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real evidence — never at file tops to satisfy coverage.\n2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid evidence — fix it, don't ship it.\n3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then satisfy it. No untracked work; no untagged evidence.\n4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's \"covered.\" Treat the hazard list as a conformance checklist you must satisfy, not advice.\n5. **Activate, don't pre-fail.** Requirements you aren't yet working stay `required_stages = []`. Activate (set real stages) only when starting the milestone that delivers them.\n\n## Issue tracking (unique case)\n\nCodebase issues are maintained on **`BigscreenVR/spt-bs-releases`** — the less-private *releases* repo — NOT on `spt-bs-core` where the code lives. This is a deliberate exception (operator-ruled 2026-07-27): file, triage, and reference issues against `spt-bs-releases`.\n\nRequests and milestones are tracked through the **alchemy shell** (`alchemy-0`, the Requests shell bound to `spt-bs-releases`) on top of those GitHub issues. The label taxonomy is the workflow: `state:` BACKLOG → EVAL → GREENLIT → WIP → ACCEPTANCE → DONE (plus CUT / SHELVED), `type:` BUGFIX / ADDITION / CHANGE, `flag: NEEDS-OPERATOR`, and per-node `kind: SPT-TRACKING` pins (marked DO NOT DELETE — leave them alone).\n\n## Other conventions\n\n- Match surrounding code style; copy-verbatim the sister project's stable wire/schema formats (ADR-0001), clean-room everything else.\n- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once.\n- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation is CI-gated against drift.\n- Commit messages end with the project's co-author trailer, exact spelling `Co-authored by: ` (e.g. `Co-authored by: todlando`) — NOT git's hyphenated `Co-Authored-By:`; CI's runner-informant parses only the space spelling for attribution.\n - **Audit this trailer with `git log --grep` or a raw body read, NEVER `%(trailers:)`** (nor `interpret-trailers --parse`): git's trailer tokenizer requires a whitespace-free token, so the space spelling is structurally invisible to it and every trailer query returns a confident EMPTY on every commit — a clean zero that reads as total attribution loss. Measured 2026-07-30 (main @`8f3e10b`, Signed-off-by and hyphenated-key controls both parse); re-derived at full cost 2026-08-03 by one of its own original measurers, which is why this sentence lives here at the mandate rather than in a document you must decide to open.\n- **Worktrees (binding, operator-ruled 2026-07-05):** every `git worktree` (gate rigs, agent scratch, anything) goes under `.worktrees/` in THIS project's root (`.gitignore`d) — e.g. `git worktree add --detach .worktrees/gate- `. NEVER create worktrees as siblings of the project dir; stray sibling folders accumulate orphan-pinned skeletons and pollute `~/Documents/projects`. Remove yours when done (`git worktree remove` + prune; retry later if a handle pins it).\n\n- **Build-cache pools (binding, releases#103):** a cargo `target/` directory belongs to ONE source tree. Two trees building into one pool overwrite each other's artifacts and fabricate reds that belong to neither — the v0.51.0 W1/H1 `E0308` that vanished on re-run. **The rule is about the RELATIONSHIP, not the path:** a junction and a `CARGO_TARGET_DIR` env var reach the same hazard, and the env var leaves no directory entry to notice afterwards, so \"is this dir under `.worktrees/`\" never was the question. A build script enforces it (`crates/spt-store/build.rs`) and refuses with `SPT_POOL_FOREIGN`. **Sharing a pool SEQUENTIALLY is fine and expected** — a finished lane is taken over loudly, not refused; only a LIVE lane blocks you. Claim a pool at lane start …\n- **Target-tree teardown (releases#103, same lane):** never delete a `target/` you have not classified. Check OUTBOUND first (`Get-Item -Force`: a junction is deleted as a link, a real dir as a tree), then sweep INBOUND for reparse points aimed at it before removing a real one, and measure size and free space before and after so the reclaim is a number rather than a claim. Reap the target SUBTREE, never a session or worktree directory around it. Do not point `CARGO_TARGET_DIR` into a scratchpad (v0.50.0 incident) or at another checkout's target (H1 incident).\n- **CI / merge strategy:** golden CI (ADR-0050, ruled 2026-07-27) — milestone-batch golden runs, thin-lane PRs, ff-only main (tested sha == merged sha). Piloting from the next milestone; read the ADR before shaping a PR lane.\n\nIf you finish a significant body of work without need for user intervention, or if your context gets too high, you can clear your own context and keep moving:\n1. Create a JIT plan for the next immediate body of work, if it isn't already planned\n2. If you are a live agent, /sptc:commune with immediate next steps and broad summary of the project's status + end goal\n3. Execute the /self-clear skill\n\n[Some lines truncated to 768 chars]"}],"details":{"totalLines":47,"displayContent":{"text":"# spt-core — agent working rules\r\n\r\nHarness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract). Rust crates + a single `spt` binary. Clean-room rebuild of `claude_skill_owl`.\r\n\r\n**Orientation — read before working:** `PRD.md` (requirements), `ROADMAP.md` (build path), `CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break), `docs/{STORAGE,MANIFEST,CONTEXT-MEMORY,DOCS-STRATEGY,TRACEABILITY}.md`.\r\n\r\nFor maintainer/debug update work, also read `docs/DEBUG-ROLLOUT.md` before touching the update-set or rollout path.\r\n\r\nFor work needing Linux tests and proof, this machine is authorized to ssh into a Linux box: `reavus@kitsubito`\r\n\r\nIMPORTANT: All agents you work alongside run on spt-core itself — the legacy-SPT (`$OWL`/`$LIVE`) era ended with the 2026-07 fleet migration; those commands are gone. Reach other agents with `spt send` (or the `/sptc:send` skill); keep message bodies short, and send long bodies from a file rather than inline. Everything else can be learned from the corresponding `/sptc:` skill doc.\r\n\r\n## Requirement traceability (binding)\r\n\r\nThis project uses `traceable-reqs` (`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is `docs/TRACEABILITY.md`. The rules you must follow:\r\n\r\n1. **Tag evidence in the same change.** When you write a function/test/doc-section that satisfies a requirement stage, add its tag in that same commit:\r\n `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · ``\r\n Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real evidence — never at file tops to satisfy coverage.\r\n2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid evidence — fix it, don't ship it.\r\n3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then satisfy it. No untracked work; no untagged evidence.\r\n4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's \"covered.\" Treat the hazard list as a conformance checklist you must satisfy, not advice.\r\n5. **Activate, don't pre-fail.** Requirements you aren't yet working stay `required_stages = []`. Activate (set real stages) only when starting the milestone that delivers them.\r\n\r\n## Issue tracking (unique case)\r\n\r\nCodebase issues are maintained on **`BigscreenVR/spt-bs-releases`** — the less-private *releases* repo — NOT on `spt-bs-core` where the code lives. This is a deliberate exception (operator-ruled 2026-07-27): file, triage, and reference issues against `spt-bs-releases`.\r\n\r\nRequests and milestones are tracked through the **alchemy shell** (`alchemy-0`, the Requests shell bound to `spt-bs-releases`) on top of those GitHub issues. The label taxonomy is the workflow: `state:` BACKLOG → EVAL → GREENLIT → WIP → ACCEPTANCE → DONE (plus CUT / SHELVED), `type:` BUGFIX / ADDITION / CHANGE, `flag: NEEDS-OPERATOR`, and per-node `kind: SPT-TRACKING` pins (marked DO NOT DELETE — leave them alone).\r\n\r\n## Other conventions\r\n\r\n- Match surrounding code style; copy-verbatim the sister project's stable wire/schema formats (ADR-0001), clean-room everything else.\r\n- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once.\r\n- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation is CI-gated against drift.\r\n- Commit messages end with the project's co-author trailer, exact spelling `Co-authored by: ` (e.g. `Co-authored by: todlando`) — NOT git's hyphenated `Co-Authored-By:`; CI's runner-informant parses only the space spelling for attribution.\r\n - **Audit this trailer with `git log --grep` or a raw body read, NEVER `%(trailers:)`** (nor `interpret-trailers --parse`): git's trailer tokenizer requires a whitespace-free token, so the space spelling is structurally invisible to it and every trailer query returns a confident EMPTY on every commit — a clean zero that reads as total attribution loss. Measured 2026-07-30 (main @`8f3e10b`, Signed-off-by and hyphenated-key controls both parse); re-derived at full cost 2026-08-03 by one of its own original measurers, which is why this sentence lives here at the mandate rather than in a document you must decide to open.\r\n- **Worktrees (binding, operator-ruled 2026-07-05):** every `git worktree` (gate rigs, agent scratch, anything) goes under `.worktrees/` in THIS project's root (`.gitignore`d) — e.g. `git worktree add --detach .worktrees/gate- `. NEVER create worktrees as siblings of the project dir; stray sibling folders accumulate orphan-pinned skeletons and pollute `~/Documents/projects`. Remove yours when done (`git worktree remove` + prune; retry later if a handle pins it).\r\n\r\n- **Build-cache pools (binding, releases#103):** a cargo `target/` directory belongs to ONE source tree. Two trees building into one pool overwrite each other's artifacts and fabricate reds that belong to neither — the v0.51.0 W1/H1 `E0308` that vanished on re-run. **The rule is about the RELATIONSHIP, not the path:** a junction and a `CARGO_TARGET_DIR` env var reach the same hazard, and the env var leaves no directory entry to notice afterwards, so \"is this dir under `.worktrees/`\" never was the question. A build script enforces it (`crates/spt-store/build.rs`) and refuses with `SPT_POOL_FOREIGN`. **Sharing a pool SEQUENTIALLY is fine and expected** — a finished lane is taken over loudly, not refused; only a LIVE lane blocks you. Claim a pool at lane start …\n- **Target-tree teardown (releases#103, same lane):** never delete a `target/` you have not classified. Check OUTBOUND first (`Get-Item -Force`: a junction is deleted as a link, a real dir as a tree), then sweep INBOUND for reparse points aimed at it before removing a real one, and measure size and free space before and after so the reclaim is a number rather than a claim. Reap the target SUBTREE, never a session or worktree directory around it. Do not point `CARGO_TARGET_DIR` into a scratchpad (v0.50.0 incident) or at another checkout's target (H1 incident).\r\n- **CI / merge strategy:** golden CI (ADR-0050, ruled 2026-07-27) — milestone-batch golden runs, thin-lane PRs, ff-only main (tested sha == merged sha). Piloting from the next milestone; read the ADR before shaping a PR lane.\r\n\r\nIf you finish a significant body of work without need for user intervention, or if your context gets too high, you can clear your own context and keep moving:\r\n1. Create a JIT plan for the next immediate body of work, if it isn't already planned\r\n2. If you are a live agent, /sptc:commune with immediate next steps and broad summary of the project's status + end goal\r\n3. Execute the /self-clear skill\r","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47]},"fileSize":8436,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\AGENTS.md"},"limits":{"columnTruncated":{"maxColumn":768}}}},"isError":false,"timestamp":1789001101763}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_bANIq5hclQGL4KoJ0gXAu7X4|fc_077f3569365e313d016aa1fd96385c87d1aeb95b6e4bd7f09c","toolName":"task","startedAt":"2026-09-10T00:45:27.367Z","intent":"Delegating independent review slices"},"id":"1df39630","parentId":"6bbb3f7d","timestamp":"2026-09-10T00:45:27.367Z"}
{"type":"message","id":"f4b2fa32","parentId":"1df39630","timestamp":"2026-09-10T00:45:27.368Z","message":{"role":"assistant","content":[{"type":"thinking","thinking":"**Scoping standards-spec work**"},{"type":"toolCall","id":"call_bANIq5hclQGL4KoJ0gXAu7X4|fc_077f3569365e313d016aa1fd96385c87d1aeb95b6e4bd7f09c","name":"task","arguments":{"i":"Delegating independent review slices","context":"# Goal\nRead-only review of .worktrees/287-shellrestore commit cb756dee against cb756dee^ for releases#287 operator ruling (https://github.com/BigscreenVR/spt-bs-releases/issues/287#issuecomment-5583820305). Main review owner PersistentRestoreReview traces production shellwake/shellhost logic.\n# Constraints\nNo edits, formatters, linters, builds, tests, or production operations. Source review only. Skip all validation commands. Only report actionable provable patch-introduced correctness/spec issues, not style nits. Use read/grep and read-only git diff/show/log. Repo issues are BigscreenVR/spt-bs-releases.\n# Contract\nRuling: persistent+owner online+down IN FACT restores on boot sweep and owner offline->online edge regardless of machine boot, launch age, missing stamp/oracle. Nonpersistent same-boot freeze survives. Riders: enumerate every healed instance per owner; relink reports binding until bind (not offline or premature online). Report exact patch-overlapping file/line and impact, or no findings. Do not edit or overlap production review except reading needed test symbols.","tasks":[{"name":"RestoreDocsStandards","task":"# Target\nChanged docs and standards only: CHANGELOG.md, CONTEXT.md, docs-site/src/shells/overview.md, docs/KNOWN-HAZARDS.md, docs/MANIFEST.md, traceable-reqs.toml in .worktrees/287-shellrestore; cb756dee vs parent. Non-goal production logic audit.\n# Change\nRead repo AGENTS.md and relevant traceability/docs standards. Read full diff for changed docs, then affected surrounding context and referenced requirements. Check retained contradictory persistent freeze or missing stamp/boot gates in changed docs; operator-ruling coverage and both riders. Distinguish Standards and Spec concerns. Verify only issue-worthy defects, not historical text explicitly superseded. No edits. Skip all formatting/lint/build/tests.\n# Acceptance\nReturn concise evidence-backed findings with exact lines and impact, or no findings with standards/spec assessment. Source acceptance only; no runtime claims."},{"name":"RestoreTestsReview","task":"# Target\nChanged tests in crates/spt-daemon/src/shellwake.rs, crates/spt-daemon/src/shellhost.rs, crates/spt/tests/shell_relink_force_e2e.rs, plus CLI relink context in crates/spt/src/cli.rs; cb756dee vs parent in .worktrees/287-shellrestore. Non-goal production restore algorithm audit (parent handles).\n# Change\nRead diff and complete changed test context. Check whether new assertions actually cover ruling: same-boot/missing stamp persistent restoration, nonpersistent freeze, live binding/PID-reuse exclusion, all healed instances, and binding relink output. Inspect CLI relink branches and any output consumer dispatch that could be broken by status change. Report concrete introduced bugs, not requests to pad tests. Skip all validation, builds, linters, formatters and test execution; no edits.\n# Acceptance\nReturn actionable correctness/spec findings with exact diff lines and affected path, or no findings, separating source review from unrun runtime tests."}]},"intent":"Delegating independent review slices"}],"api":"openai-codex-responses","provider":"openai-codex","model":"gpt-6-astra","usage":{"input":9756,"output":774,"cacheRead":19840,"cacheWrite":0,"totalTokens":30370,"reasoningTokens":91,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"toolUse","timestamp":1789001101773,"responseId":"resp_077f3569365e313d016aa1fd8e09a887d191bc1aafa7e744c9","providerPayload":{"type":"openaiResponsesHistory","provider":"openai-codex","dt":true,"items":[{"id":"rs_077f3569365e313d016aa1fd8f78fc87d1a10767a7144c6e97","type":"reasoning","content":[],"encrypted_content":"gAAAAABqof2WAOVagEfJjNoL1KOpXYqUGn1NoyJ1rqj6s41N_bcHlU1Qgr8Y6vVZwYRQumMeXxBqsh6GdAn6SXXIjy2WiR4s7CEnYCb1onLETA_S0tf6NvU3IdbML8engaCf4TjigCBtezEC0fa8HJ25KvSlGc7z4xgHcec8__sMJkpZskwXKrSXroYbzG2rCfRuWeKi8hHL5ienil76fyyRvShDrY4r7Qr8SaHx_K7rzZhnmDxi1lYsfilPmR-HpXkZe127wtMqygr3nB-3X4-32ouTuof0wOG1fEXkcWXBqcSXYSzVOZx-w8Gy6jyzpN4pCfe4gqbtmaUmpQ0eejKMmrb67T_Ep6h184yxq0KG7urFD63ZyjwNLzkWfkm91uXX7OmFxEr7ilYUHezXFNalT7PPkRrvzJoLbPeZLWoKYmu4Zf7JU0j9sFb3Un8PyjD1ZD6KpXbIC3_4oagPlbrnaVxeVV-M1-Dz_Of-DYn1i9KWHp-7aDdNdTIDxB6gvk5c8BsboewnmIx84m4OyETe7eef-0CURkIiyjMxlTrJ3IkxO2wYrnePatJpb8_YG86GQX1ANo7_ZOMCcpKtwnHGRgBgbSoxbgm2civXHHXdxf452Q9pAZd-d0TQANPlIn5gAEsA5Of2yIqpQYVV4bOVkGD_XH8heAFIDzNFZpi3LMF87MG91Cl5OivFDiROSIpBI4NmSwQkeY4AwJ7Qmb6rNaGyI15hIKYAJmi8xIUStTGqDtb8SADm9f87zOmt88vEwzKTdn37yZAfn3fLB0QzcpCH7Jr-AGE773RhgRoqaCq8hxw_ySj5cDPjRCU_fh04G0biieH7CiZE9H2_iyd1fkRovg1SdbvV3px2-QASEJ2IOa6MFZtkBuAqUjrM_7BL7JNa0lAWSmME08yH6_ChJLa8ZvBe4PWo_IjAkz9hk_Czdk7o7DSG8XiejwLHlyoZ0d2QV4-DG5Fpkb5toMBvPEkC9G92-GrQOa-gwL-3gK-VonOSpa3tthmVBheprOkjacPehCXnmI7e5-3mGig-R76NtUMBpDzIFHeCSVwh3qgwCgpNFDOYHCXWVGzunwTKjPUyq19QJL_MLOOxV29cr1pW4bZ8zR7jzlNbZl3Ao-9pQEB5lxmowm_jukKx2F2T2MKRn3tPBYY5-S_BrUYx5w03y7awGUlC8m4thp9lXV4KwwkysaLdtm0l1qyFnqPmVsC_ZK-QV53BmYBMvYVRqz0F9ee1rX8-XYsjXR9qM2baFUcysTI2GWJgHOE0qhcRRX2aqf6XytXjHfz6XQUsvLLe7upU8k-txbmcdsThfuIBhb7ughelKReTWnQhmM1jBEvYC7g2bfHkS9kzrvtUF1Si4m0SY-iFUWf2AteB9rGc_FV4-6p8Td1wWvfQxjsn-fj-ZzDmE2Kw-Y-0ZJSBkS-VjgJPzzWjrf_N6naGIISWFicTAaqTe7A_tSD3DoDgj4hlkZh6pD8TfixziF-_R9Ct40zjOauxgKtdSXEUB5j4HjheBqA-KhObu24adbA18p5PR7u9uRF7Pwa_JVW6Ndm4awS_ki2zbc5WD94y0Vu2CUtxNQ10pg-RZcCSaP35c4_ndidXIDkSVTMCTvAluPJm6daeR4vd9NUdMxpBUo4DfYwh1QGeOApPlw-7oC9L5-PbQ3RLsBHA5p2pLUWdAFGFKiGi96amm923WsC4jHzx0t_p9JZ51Mp8ORKSq968DtwHjwx312iKYxHgfeTpMBcdWRS8NtSmmVZnan10L2tpr635TC97JIw0ql3zQaXMuUqeFEDvrfvUT7yCrNQexQuZMsJVTwolm87Ss-oGPxVYmnFx_8RewlN8GymXJxaEDGJ4RFhW2wXzgDFIY_lE2Bpy-958zrnrBHk0qUg15h-npbw8dhYmxadJJgHvwS2HUEwKwFpC","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"summary":[{"type":"summary_text","text":"**Scoping standards-spec work**"}],"metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fd96385c87d1aeb95b6e4bd7f09c","type":"function_call","status":"completed","arguments":"{\"i\":\"Delegating independent review slices\",\"context\":\"# Goal\\nRead-only review of .worktrees/287-shellrestore commit cb756dee against cb756dee^ for releases#287 operator ruling (https://github.com/BigscreenVR/spt-bs-releases/issues/287#issuecomment-5583820305). Main review owner PersistentRestoreReview traces production shellwake/shellhost logic.\\n# Constraints\\nNo edits, formatters, linters, builds, tests, or production operations. Source review only. Skip all validation commands. Only report actionable provable patch-introduced correctness/spec issues, not style nits. Use read/grep and read-only git diff/show/log. Repo issues are BigscreenVR/spt-bs-releases.\\n# Contract\\nRuling: persistent+owner online+down IN FACT restores on boot sweep and owner offline->online edge regardless of machine boot, launch age, missing stamp/oracle. Nonpersistent same-boot freeze survives. Riders: enumerate every healed instance per owner; relink reports binding until bind (not offline or premature online). Report exact patch-overlapping file/line and impact, or no findings. Do not edit or overlap production review except reading needed test symbols.\",\"tasks\":[{\"name\":\"RestoreDocsStandards\",\"task\":\"# Target\\nChanged docs and standards only: CHANGELOG.md, CONTEXT.md, docs-site/src/shells/overview.md, docs/KNOWN-HAZARDS.md, docs/MANIFEST.md, traceable-reqs.toml in .worktrees/287-shellrestore; cb756dee vs parent. Non-goal production logic audit.\\n# Change\\nRead repo AGENTS.md and relevant traceability/docs standards. Read full diff for changed docs, then affected surrounding context and referenced requirements. Check retained contradictory persistent freeze or missing stamp/boot gates in changed docs; operator-ruling coverage and both riders. Distinguish Standards and Spec concerns. Verify only issue-worthy defects, not historical text explicitly superseded. No edits. Skip all formatting/lint/build/tests.\\n# Acceptance\\nReturn concise evidence-backed findings with exact lines and impact, or no findings with standards/spec assessment. Source acceptance only; no runtime claims.\"},{\"name\":\"RestoreTestsReview\",\"task\":\"# Target\\nChanged tests in crates/spt-daemon/src/shellwake.rs, crates/spt-daemon/src/shellhost.rs, crates/spt/tests/shell_relink_force_e2e.rs, plus CLI relink context in crates/spt/src/cli.rs; cb756dee vs parent in .worktrees/287-shellrestore. Non-goal production restore algorithm audit (parent handles).\\n# Change\\nRead diff and complete changed test context. Check whether new assertions actually cover ruling: same-boot/missing stamp persistent restoration, nonpersistent freeze, live binding/PID-reuse exclusion, all healed instances, and binding relink output. Inspect CLI relink branches and any output consumer dispatch that could be broken by status change. Report concrete introduced bugs, not requests to pad tests. Skip all validation, builds, linters, formatters and test execution; no edits.\\n# Acceptance\\nReturn actionable correctness/spec findings with exact diff lines and affected path, or no findings, separating source review from unrun runtime tests.\"}]}","call_id":"call_bANIq5hclQGL4KoJ0gXAu7X4","internal_chat_message_metadata_passthrough":{"create_time":1789001102.3318,"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"task","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}}]},"duration":25590.29679999966,"ttft":1727.6099999998696,"completedAt":1789001127364,"contextSnapshot":{"promptTokens":29596,"nonMessageTokens":13209,"compactionEpoch":0}}}
{"type":"message","id":"abdd6300","parentId":"f4b2fa32","timestamp":"2026-09-10T00:45:27.376Z","message":{"role":"toolResult","toolCallId":"call_bANIq5hclQGL4KoJ0gXAu7X4|fc_077f3569365e313d016aa1fd96385c87d1aeb95b6e4bd7f09c","toolName":"task","content":[{"type":"text","text":"Spawned 2 background agents using scout. Each result auto-delivers on yield unless a settled `hub jobs`/`wait` snapshot consumes it first.\n- `PersistentRestoreReview.RestoreDocsStandards` (job `PersistentRestoreReview.RestoreDocsStandards`)\n- `PersistentRestoreReview.RestoreTestsReview` (job `PersistentRestoreReview.RestoreTestsReview`)\nDM these ids via `hub` send to coordinate while they run; use `hub` only to inspect (`jobs`), wait, or cancel a stuck task.\nNo polling needed.\n\nSettled-job inspection: `hub jobs` | `hub wait` delivers its snapshot → no duplicate `async-result`.\n\nJob IDs: process memory ~5min after settlement; afterward use agent ID: `hub send`, `agent://`, `history://`.\n\n`completed`: subagent yielded successfully; claimed artifacts unverified.\n\nCoordinate: 2 siblings are running together. If their work overlaps, have them message each other via `hub` (by id, or \"all\" to broadcast) before editing shared files — live coordination beats a serial handoff. Check `hub` op:\"list\" to see who is doing what."}],"details":{"projectAgentsDir":null,"results":[],"totalDurationMs":1,"progress":[{"index":0,"id":"PersistentRestoreReview.RestoreDocsStandards","agent":"scout","agentSource":"bundled","modelRole":"smol","status":"pending","task":"Complete assignment thoroughly:\n\n# Target\nChanged docs and standards only: CHANGELOG.md, CONTEXT.md, docs-site/src/shells/overview.md, docs/KNOWN-HAZARDS.md, docs/MANIFEST.md, traceable-reqs.toml in .worktrees/287-shellrestore; cb756dee vs parent. Non-goal production logic audit.\n# Change\nRead repo AGENTS.md and relevant traceability/docs standards. Read full diff for changed docs, then affected surrounding context and referenced requirements. Check retained contradictory persistent freeze or missing stamp/boot gates in changed docs; operator-ruling coverage and both riders. Distinguish Standards and Spec concerns. Verify only issue-worthy defects, not historical text explicitly superseded. No edits. Skip all formatting/lint/build/tests.\n# Acceptance\nReturn concise evidence-backed findings with exact lines and impact, or no findings with standards/spec assessment. Source acceptance only; no runtime claims.","assignment":"# Target\nChanged docs and standards only: CHANGELOG.md, CONTEXT.md, docs-site/src/shells/overview.md, docs/KNOWN-HAZARDS.md, docs/MANIFEST.md, traceable-reqs.toml in .worktrees/287-shellrestore; cb756dee vs parent. Non-goal production logic audit.\n# Change\nRead repo AGENTS.md and relevant traceability/docs standards. Read full diff for changed docs, then affected surrounding context and referenced requirements. Check retained contradictory persistent freeze or missing stamp/boot gates in changed docs; operator-ruling coverage and both riders. Distinguish Standards and Spec concerns. Verify only issue-worthy defects, not historical text explicitly superseded. No edits. Skip all formatting/lint/build/tests.\n# Acceptance\nReturn concise evidence-backed findings with exact lines and impact, or no findings with standards/spec assessment. Source acceptance only; no runtime claims.","recentTools":[],"recentOutput":[],"toolCount":0,"requests":0,"tokens":0,"cost":0,"durationMs":0},{"index":1,"id":"PersistentRestoreReview.RestoreTestsReview","agent":"scout","agentSource":"bundled","modelRole":"smol","status":"pending","task":"Complete assignment thoroughly:\n\n# Target\nChanged tests in crates/spt-daemon/src/shellwake.rs, crates/spt-daemon/src/shellhost.rs, crates/spt/tests/shell_relink_force_e2e.rs, plus CLI relink context in crates/spt/src/cli.rs; cb756dee vs parent in .worktrees/287-shellrestore. Non-goal production restore algorithm audit (parent handles).\n# Change\nRead diff and complete changed test context. Check whether new assertions actually cover ruling: same-boot/missing stamp persistent restoration, nonpersistent freeze, live binding/PID-reuse exclusion, all healed instances, and binding relink output. Inspect CLI relink branches and any output consumer dispatch that could be broken by status change. Report concrete introduced bugs, not requests to pad tests. Skip all validation, builds, linters, formatters and test execution; no edits.\n# Acceptance\nReturn actionable correctness/spec findings with exact diff lines and affected path, or no findings, separating source review from unrun runtime tests.","assignment":"# Target\nChanged tests in crates/spt-daemon/src/shellwake.rs, crates/spt-daemon/src/shellhost.rs, crates/spt/tests/shell_relink_force_e2e.rs, plus CLI relink context in crates/spt/src/cli.rs; cb756dee vs parent in .worktrees/287-shellrestore. Non-goal production restore algorithm audit (parent handles).\n# Change\nRead diff and complete changed test context. Check whether new assertions actually cover ruling: same-boot/missing stamp persistent restoration, nonpersistent freeze, live binding/PID-reuse exclusion, all healed instances, and binding relink output. Inspect CLI relink branches and any output consumer dispatch that could be broken by status change. Report concrete introduced bugs, not requests to pad tests. Skip all validation, builds, linters, formatters and test execution; no edits.\n# Acceptance\nReturn actionable correctness/spec findings with exact diff lines and affected path, or no findings, separating source review from unrun runtime tests.","recentTools":[],"recentOutput":[],"toolCount":0,"requests":0,"tokens":0,"cost":0,"durationMs":0}],"async":{"state":"running","jobId":"PersistentRestoreReview.RestoreDocsStandards","type":"task"}},"isError":false,"timestamp":1789001127376}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_AGim25C0IpPaWiIiWNcatuNa|fc_077f3569365e313d016aa1fdb0c06087d1b2cbebcba03bb903","toolName":"read","startedAt":"2026-09-10T00:45:36.935Z","args":{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:1-320"},"intent":"Reading production wake context"},"id":"372d9e8c","parentId":"abdd6300","timestamp":"2026-09-10T00:45:36.935Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_7CFTl5wDfbMpoAe7PxbOIkfS|fc_077f3569365e313d016aa1fdb0c07487d1985acac801d13058","toolName":"read","startedAt":"2026-09-10T00:45:36.936Z","args":{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:590-1060"},"intent":"Reading persistent restore context"},"id":"27f7a99d","parentId":"372d9e8c","timestamp":"2026-09-10T00:45:36.936Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_b5vz9AVfJemvkhllIGlgLVCf|fc_077f3569365e313d016aa1fdb0c08087d182419544e6345b9c","toolName":"read","startedAt":"2026-09-10T00:45:36.936Z","args":{"path":"artifact://112:301-600"},"intent":"Reading remaining wake patch"},"id":"dd9e705c","parentId":"27f7a99d","timestamp":"2026-09-10T00:45:36.936Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_Af4TRJYugyLpvR3kOYPeRRR4|fc_077f3569365e313d016aa1fdb0c08c87d1b16af7f4dfd838ca","toolName":"read","startedAt":"2026-09-10T00:45:36.936Z","args":{"path":".worktrees/287-shellrestore/crates/spt-store/src/shellinfo.rs:1-350"},"intent":"Reading stored liveness semantics"},"id":"8d317ca6","parentId":"dd9e705c","timestamp":"2026-09-10T00:45:36.936Z"}
{"type":"message","id":"784485da","parentId":"8d317ca6","timestamp":"2026-09-10T00:45:36.936Z","message":{"role":"assistant","content":[{"type":"toolCall","id":"call_AGim25C0IpPaWiIiWNcatuNa|fc_077f3569365e313d016aa1fdb0c06087d1b2cbebcba03bb903","name":"read","arguments":{"i":"Reading production wake context","path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:1-320"},"intent":"Reading production wake context"},{"type":"toolCall","id":"call_7CFTl5wDfbMpoAe7PxbOIkfS|fc_077f3569365e313d016aa1fdb0c07487d1985acac801d13058","name":"read","arguments":{"i":"Reading persistent restore context","path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:590-1060"},"intent":"Reading persistent restore context"},{"type":"toolCall","id":"call_b5vz9AVfJemvkhllIGlgLVCf|fc_077f3569365e313d016aa1fdb0c08087d182419544e6345b9c","name":"read","arguments":{"i":"Reading remaining wake patch","path":"artifact://112:301-600"},"intent":"Reading remaining wake patch"},{"type":"toolCall","id":"call_Af4TRJYugyLpvR3kOYPeRRR4|fc_077f3569365e313d016aa1fdb0c08c87d1b16af7f4dfd838ca","name":"read","arguments":{"i":"Reading stored liveness semantics","path":".worktrees/287-shellrestore/crates/spt-store/src/shellinfo.rs:1-350"},"intent":"Reading stored liveness semantics"},{"type":"toolCall","id":"call_8hv8qzFRDNvgINDHIrh0G52O|fc_077f3569365e313d016aa1fdb0c09887d1bad4b5b5fc3d8749","name":"grep","arguments":{"i":"Locating launch guard consumers","pattern":"live_launch_winner|restore_persistent_shells|reconcile_owner_online|heal_stale_online_records|watcher_eligible","path":".worktrees/287-shellrestore/crates","case":true,"gitignore":false,"skip":null},"intent":"Locating launch guard consumers"}],"api":"openai-codex-responses","provider":"openai-codex","model":"gpt-6-astra","usage":{"input":1186,"output":242,"cacheRead":29440,"cacheWrite":0,"totalTokens":30868,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"toolUse","timestamp":1789001127481,"responseId":"resp_077f3569365e313d016aa1fda811dc87d1afd9cc23967b52a4","providerPayload":{"type":"openaiResponsesHistory","provider":"openai-codex","dt":true,"items":[{"id":"fc_077f3569365e313d016aa1fdb0c06087d1b2cbebcba03bb903","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading production wake context\",\"path\":\".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:1-320\"}","call_id":"call_AGim25C0IpPaWiIiWNcatuNa","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdb0c07487d1985acac801d13058","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading persistent restore context\",\"path\":\".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:590-1060\"}","call_id":"call_7CFTl5wDfbMpoAe7PxbOIkfS","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdb0c08087d182419544e6345b9c","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading remaining wake patch\",\"path\":\"artifact://112:301-600\"}","call_id":"call_b5vz9AVfJemvkhllIGlgLVCf","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdb0c08c87d1b16af7f4dfd838ca","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading stored liveness semantics\",\"path\":\".worktrees/287-shellrestore/crates/spt-store/src/shellinfo.rs:1-350\"}","call_id":"call_Af4TRJYugyLpvR3kOYPeRRR4","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdb0c09887d1bad4b5b5fc3d8749","type":"function_call","status":"completed","arguments":"{\"i\":\"Locating launch guard consumers\",\"pattern\":\"live_launch_winner|restore_persistent_shells|reconcile_owner_online|heal_stale_online_records|watcher_eligible\",\"path\":\".worktrees/287-shellrestore/crates\",\"case\":true,\"gitignore\":false,\"skip\":null}","call_id":"call_8hv8qzFRDNvgINDHIrh0G52O","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"grep","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}}]},"duration":9452.823299999814,"ttft":9321.73499999987,"completedAt":1789001136934,"contextSnapshot":{"promptTokens":30626,"nonMessageTokens":13209,"compactionEpoch":0}}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_8hv8qzFRDNvgINDHIrh0G52O|fc_077f3569365e313d016aa1fdb0c09887d1bad4b5b5fc3d8749","toolName":"grep","startedAt":"2026-09-10T00:45:36.936Z","args":{"path":".worktrees/287-shellrestore/crates"},"intent":"Locating launch guard consumers"},"id":"4ccd2976","parentId":"784485da","timestamp":"2026-09-10T00:45:36.936Z"}
{"type":"message","id":"fb18ed21","parentId":"4ccd2976","timestamp":"2026-09-10T00:45:36.957Z","message":{"role":"toolResult","toolCallId":"call_AGim25C0IpPaWiIiWNcatuNa|fc_077f3569365e313d016aa1fdb0c06087d1b2cbebcba03bb903","toolName":"read","content":[{"type":"text","text":"//! Shell wake-watcher hosting (M5-D4b — CONTEXT §Shell sleep/wake): the\n//! offline half of the online/offline mutual exclusivity. While a shell\n//! instance is **offline** and its manifest declares a `wake_command`, the\n//! daemon runs that template as a long-running **wake-watcher** child whose\n//! sole job is to fire a wake; while the shell binary runs, no watcher does\n//! ([`reconcile_once`] flips between them — spt-core owns the flip).\n//!\n//! **Exit-opcode supervision:** the watcher exiting with [`WAKE_OPCODE`] ⇒\n//! the wake resolution ([`resolve_wake`]) brings the shell online. Any other\n//! exit is a crash ⇒ respawn with exponential backoff ([`backoff_ms`]) and\n//! **give-up** after [`WakeParams::give_up_after`] consecutive crashes (a\n//! durable [`WAKER_GAVE_UP_FILE`] marker the next shell activity — any\n//! (re)launch — clears; crash-bug safety, the watcher can never crash-loop\n//! forever). One watcher per offline instance: the in-process [`WakeSet`]\n//! entry plus the perch's [`WAKER_PID_FILE`] (which also lets a freshly\n//! booted daemon kill a dead daemon's orphaned watcher before adopting).\n//!\n//! **Scheduling (KH 7.4):** every watcher gets its own supervision thread —\n//! a hung waker stalls nothing; the reconcile loop itself is one bounded\n//! sweep per tick off the daemon's control surfaces. Watcher children are\n//! *supervised* (waited) children, never detached-immortal — the KH 5.6\n//! pipe-inherit shape (an unwaitable child holding a capture pipe) does not\n//! arise; stdio is null regardless.\n// [impl->REQ-SHELL-2]\n\nuse std::collections::HashMap;\nuse std::path::Path;\nuse std::process::{Command, Stdio};\nuse std::sync::atomic::{AtomicBool, Ordering};\nuse std::sync::{Arc, Mutex};\nuse std::thread::JoinHandle;\nuse std::time::Duration;\n\nuse spt_runtime::manifest::{AdapterKind, Manifest, Shell};\nuse spt_runtime::registry::AdapterRecord;\nuse spt_store::perch::ParentHint;\nuse spt_store::shellinfo::{self, SHELL_STATUS_OFFLINE, SHELL_STATUS_ONLINE};\n\n/// The wake opcode (documented in `docs/MANIFEST.md` §Shell adapters): a\n/// wake-watcher exiting with **86** fires the wake resolution; every other\n/// exit is a crash.\npub const WAKE_OPCODE: i32 = 86;\n\n/// The running watcher's OS pid, parked on the shell perch — the\n/// one-watcher-per-instance lock and the cross-daemon-restart kill handle.\npub const WAKER_PID_FILE: &str = \"waker.pid\";\n\n/// The give-up latch: present ⇒ the watcher crash-looped past its budget and\n/// the reconciler must NOT restart it. Cleared by the next shell activity\n/// (any (re)launch — [`crate::shellhost::launch_shell`]).\npub const WAKER_GAVE_UP_FILE: &str = \"waker.gaveup\";\n\n/// Watcher supervision knobs (injectable for tests; defaults are production).\n#[derive(Debug, Clone, Copy)]\npub struct WakeParams {\n /// First-crash respawn delay; doubles per consecutive crash.\n pub backoff_base_ms: u64,\n /// Backoff ceiling.\n pub backoff_cap_ms: u64,\n /// Consecutive crash-exits before the give-up latch drops.\n pub give_up_after: u32,\n}\n\nimpl Default for WakeParams {\n fn default() -> Self {\n Self {\n backoff_base_ms: 1_000,\n backoff_cap_ms: 60_000,\n give_up_after: 6,\n }\n }\n}\n\n/// Exponential backoff for `failures` consecutive crash-exits:\n/// `base × 2^(failures-1)`, saturating at the cap (the\n/// `spt-net::pairing::ratelimit` recipe). Zero failures ⇒ no wait.\n// [impl->REQ-SHELL-2]\npub fn backoff_ms(params: &WakeParams, failures: u32) -> u64 {\n if failures == 0 {\n return 0;\n }\n params\n .backoff_base_ms\n .saturating_mul(1u64 << (failures - 1).min(20))\n .min(params.backoff_cap_ms)\n}\n\n/// The live watcher registry: one supervision thread per offline instance,\n/// keyed `owner/shell_id`. Shared between the daemon's reconcile loop and\n/// anything that must stop a watcher.\n#[derive(Default)]\npub struct WakeSet {\n inner: Mutex>,\n}\n\nstruct WatcherHandle {\n stop: Arc,\n thread: JoinHandle<()>,\n}\n\nimpl WakeSet {\n pub fn new() -> Self {\n Self::default()\n }\n\n /// How many watchers are live (finished threads pruned first).\n pub fn len(&self) -> usize {\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\n map.retain(|_, h| !h.thread.is_finished());\n map.len()\n }\n\n pub fn is_empty(&self) -> bool {\n self.len() == 0\n }\n\n fn contains(&self, owner: &str, shell_id: &str) -> bool {\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\n match map.get(&(owner.to_string(), shell_id.to_string())) {\n Some(h) if !h.thread.is_finished() => true,\n Some(_) => {\n map.remove(&(owner.to_string(), shell_id.to_string()));\n false\n }\n None => false,\n }\n }\n\n fn insert(&self, owner: &str, shell_id: &str, handle: WatcherHandle) {\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\n map.insert((owner.to_string(), shell_id.to_string()), handle);\n }\n\n /// Signal one watcher to stop and kill its child (the perch pid file is\n /// the kill handle). The thread sees the kill as a non-opcode exit with\n /// its stop flag up and returns without counting a failure.\n fn stop_watcher(&self, owlery: &Path, owner: &str, shell_id: &str) {\n let handle = {\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\n map.remove(&(owner.to_string(), shell_id.to_string()))\n };\n if let Some(h) = handle {\n h.stop.store(true, Ordering::SeqCst);\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\n kill_waker_at(&perch);\n let _ = h.thread.join();\n }\n }\n}\n\n/// Park the waker's pid **and its birth stamp** as one record — `\\n`\n/// — in the single write that already existed.\n///\n/// ONE file and ONE write, because the pair must never be torn: a stamp parked\n/// in a second file leaves a window where the pid is on disk and the stamp is\n/// not, and [`spt_store::liveness::relay_liveness`] reads a live pid with no\n/// stamp as `Held`. That window is exactly the unauthenticated kill this\n/// requirement removes, reintroduced as a race.\n///\n/// A backend that exposes no start time writes the pid alone — the same\n/// one-line shape every pre-fix record already has, which reads `Held` on\n/// existence and keeps today's behaviour until the next launch.\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\npub fn record_waker_launch(shell_perch: &Path, pid: u32) {\n let body = match spt_store::proc::process_started_at(pid) {\n Some(birth) => format!(\"{pid}\\n{birth}\"),\n None => pid.to_string(),\n };\n let _ = std::fs::write(shell_perch.join(WAKER_PID_FILE), body);\n}\n\n/// Read that record back — **the** parse, so the two-line format has exactly one\n/// reader shape (the `record_shell_launch`/`read_shell_launch` pattern).\n///\n/// `None` means \"no usable pid on record\": absent, empty, or unparseable. Every\n/// caller must treat that as FAIL-TOWARD-ALIVE — refuse the kill and leave the\n/// record standing. A whole-content `trim().parse()` (what every reader did\n/// before this) returns `None` on the two-line form, so a reader left un-migrated\n/// would kill nothing, retire the record anyway, and report success while\n/// orphaning a live waker.\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\npub fn read_waker_launch(shell_perch: &Path) -> Option<(u32, Option)> {\n let raw = std::fs::read_to_string(shell_perch.join(WAKER_PID_FILE)).ok()?;\n let mut lines = raw.lines();\n let pid = lines.next()?.trim().parse::().ok()?;\n let birth = lines.next().and_then(|l| l.trim().parse::().ok());\n Some((pid, birth))\n}\n\n/// Kill the recorded waker pid and retire the pid file — the\n/// mutual-exclusivity enforcement point and the orphan cleanup\n/// ([`crate::shellhost::launch_shell`] calls this before the binary rises;\n/// the reconciler calls it before adopting an instance a dead daemon left).\n///\n/// The kill is now **authenticated**: it fires only when the pid+birth pair\n/// says the process at that number is the waker we spawned. Gating on bare\n/// `is_process_alive` (what this did before) hands a recycled pid straight to\n/// `taskkill /T` (KNOWN-HAZARDS 7.58).\n///\n/// Same Linux caveat as [`crate::shellhost::kill_shell_at`]: the 10ms jiffy\n/// resolution of `/proc//stat` field 22 means the pair NARROWS the\n/// mis-fire window to a pid recycled inside the recorded start's own tick,\n/// rather than eliminating it. Windows `FILETIME` is unaffected.\n// [impl->REQ-SHELL-2]\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\npub fn kill_waker_at(shell_perch: &Path) {\n let pid_file = shell_perch.join(WAKER_PID_FILE);\n let Some((pid, birth)) = read_waker_launch(shell_perch) else {\n // Absent is the ordinary pre-launch case and says nothing. A record that\n // EXISTS and will not parse is a different animal: refuse, say so, and\n // LEAVE it — retiring it here would orphan a possibly-live waker while\n // reporting success.\n if pid_file.exists() {\n spt_proto::emit_line_err!(\n \"WAKER_KILL_REFUSED_UNREADABLE:{}: a waker record exists but no pid could be \\\n parsed from it — refusing the kill and keeping the record\",\n shell_perch.display()\n );\n }\n return;\n };\n if pid == 0 {\n // A backend that exposed no pid: never a process, never a kill target.\n let _ = std::fs::remove_file(&pid_file);\n return;\n }\n // The SAME policy the shell chokepoint applies — one destructive decision,\n // made in one place.\n match crate::shellhost::kill_verdict(spt_store::liveness::relay_liveness(Some(pid), birth)) {\n crate::shellhost::KillVerdict::Fire => {\n crate::shellhost::kill_shell_pid(pid);\n let _ = std::fs::remove_file(&pid_file);\n }\n crate::shellhost::KillVerdict::RetireOnly => {\n spt_proto::emit_line_err!(\n \"WAKER_KILL_REFUSED_GONE:{}: recorded waker pid={pid} is not the process we \\\n spawned (absent, or the pid was recycled) — retiring the record and killing \\\n nothing\",\n shell_perch.display()\n );\n let _ = std::fs::remove_file(&pid_file);\n }\n crate::shellhost::KillVerdict::RefuseAndKeep => {\n spt_proto::emit_line_err!(\n \"WAKER_KILL_REFUSED_UNPROVEN:{}: recorded waker pid={pid} could not be \\\n identified — refusing the kill and keeping the record; the waker may still be \\\n running\",\n shell_perch.display()\n );\n }\n }\n}\n\n/// Clear the give-up latch — any (re)launch is \"next shell activity\".\npub fn clear_gave_up(shell_perch: &Path) {\n let _ = std::fs::remove_file(shell_perch.join(WAKER_GAVE_UP_FILE));\n}\n\n/// One watcher's supervision loop (runs on its own thread): spawn the\n/// tokenized `wake_command`, park the pid, wait; `exit(WAKE_OPCODE)` ⇒ run\n/// `resolve` once and finish; any other exit ⇒ respawn with exponential\n/// backoff until the give-up budget, then drop the durable latch. A raised\n/// `stop` flag ends the loop without counting the (killed) child as a crash.\n// [impl->REQ-SHELL-2]\npub fn watcher_run(\n owlery: &Path,\n owner: &str,\n shell_id: &str,\n tokens: &[String],\n params: &WakeParams,\n stop: &AtomicBool,\n resolve: impl FnOnce() -> Result,\n) {\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\n let Some((program, args)) = tokens.split_first() else {\n spt_proto::emit_line_err!(\"WAKER_EMPTY:{owner}/{shell_id}: empty wake_command\");\n return;\n };\n let mut failures = 0u32;\n while !stop.load(Ordering::SeqCst) {\n let mut cmd = Command::new(program);\n cmd.args(args)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null());\n // The daemon (a console-less DETACHED process) hosting a\n // console-subsystem waker would otherwise pop a visible Terminal\n // window per spawn on Windows 11 (the KH 5.6-adjacent D3e lesson —\n // mock-shell's spt_cmd does the same).\n #[cfg(windows)]\n {\n use std::os::windows::process::CommandExt;\n cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW\n }\n let child = cmd.spawn();\n let mut child = match child {\n Ok(c) => c,\n Err(e) => {\n // An unspawnable waker is a permanent condition — latch now.\n spt_proto::emit_line_err!(\"WAKER_SPAWN_FAIL:{owner}/{shell_id}: {e} (giving up)\");\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\n return;\n }\n };\n // The birth stamp rides WITH the pid, in one write — the kill path\n // authenticates the pair, and a stamp parked separately would leave a\n // window that reads Held. [impl->REQ-SHELL-KILL-AUTHENTICATED]\n record_waker_launch(&perch, child.id());\n let status = child.wait();\n let _ = std::fs::remove_file(perch.join(WAKER_PID_FILE));\n if stop.load(Ordering::SeqCst) {\n return; // stopped from outside — the kill is not a crash\n }\n match status.ok().and_then(|s| s.code()) {\n Some(WAKE_OPCODE) => {\n match resolve() {\n Ok(what) => spt_proto::emit_line_err!(\"SHELL_WAKE:{owner}/{shell_id}: {what}\"),\n Err(e) => spt_proto::emit_line_err!(\"SHELL_WAKE_FAIL:{owner}/{shell_id}: {e}\"),\n }\n return;\n }\n _ => {\n failures += 1;\n…\n }\n }\n }\n}\n\n[Showing lines 1-323 of 2161. Use :324 to continue]"}],"details":{"truncation":{"content":"//! Shell wake-watcher hosting (M5-D4b — CONTEXT §Shell sleep/wake): the\r\n//! offline half of the online/offline mutual exclusivity. While a shell\r\n//! instance is **offline** and its manifest declares a `wake_command`, the\r\n//! daemon runs that template as a long-running **wake-watcher** child whose\r\n//! sole job is to fire a wake; while the shell binary runs, no watcher does\r\n//! ([`reconcile_once`] flips between them — spt-core owns the flip).\r\n//!\r\n//! **Exit-opcode supervision:** the watcher exiting with [`WAKE_OPCODE`] ⇒\r\n//! the wake resolution ([`resolve_wake`]) brings the shell online. Any other\r\n//! exit is a crash ⇒ respawn with exponential backoff ([`backoff_ms`]) and\r\n//! **give-up** after [`WakeParams::give_up_after`] consecutive crashes (a\r\n//! durable [`WAKER_GAVE_UP_FILE`] marker the next shell activity — any\r\n//! (re)launch — clears; crash-bug safety, the watcher can never crash-loop\r\n//! forever). One watcher per offline instance: the in-process [`WakeSet`]\r\n//! entry plus the perch's [`WAKER_PID_FILE`] (which also lets a freshly\r\n//! booted daemon kill a dead daemon's orphaned watcher before adopting).\r\n//!\r\n//! **Scheduling (KH 7.4):** every watcher gets its own supervision thread —\r\n//! a hung waker stalls nothing; the reconcile loop itself is one bounded\r\n//! sweep per tick off the daemon's control surfaces. Watcher children are\r\n//! *supervised* (waited) children, never detached-immortal — the KH 5.6\r\n//! pipe-inherit shape (an unwaitable child holding a capture pipe) does not\r\n//! arise; stdio is null regardless.\r\n// [impl->REQ-SHELL-2]\r\n\r\nuse std::collections::HashMap;\r\nuse std::path::Path;\r\nuse std::process::{Command, Stdio};\r\nuse std::sync::atomic::{AtomicBool, Ordering};\r\nuse std::sync::{Arc, Mutex};\r\nuse std::thread::JoinHandle;\r\nuse std::time::Duration;\r\n\r\nuse spt_runtime::manifest::{AdapterKind, Manifest, Shell};\r\nuse spt_runtime::registry::AdapterRecord;\r\nuse spt_store::perch::ParentHint;\r\nuse spt_store::shellinfo::{self, SHELL_STATUS_OFFLINE, SHELL_STATUS_ONLINE};\r\n\r\n/// The wake opcode (documented in `docs/MANIFEST.md` §Shell adapters): a\r\n/// wake-watcher exiting with **86** fires the wake resolution; every other\r\n/// exit is a crash.\r\npub const WAKE_OPCODE: i32 = 86;\r\n\r\n/// The running watcher's OS pid, parked on the shell perch — the\r\n/// one-watcher-per-instance lock and the cross-daemon-restart kill handle.\r\npub const WAKER_PID_FILE: &str = \"waker.pid\";\r\n\r\n/// The give-up latch: present ⇒ the watcher crash-looped past its budget and\r\n/// the reconciler must NOT restart it. Cleared by the next shell activity\r\n/// (any (re)launch — [`crate::shellhost::launch_shell`]).\r\npub const WAKER_GAVE_UP_FILE: &str = \"waker.gaveup\";\r\n\r\n/// Watcher supervision knobs (injectable for tests; defaults are production).\r\n#[derive(Debug, Clone, Copy)]\r\npub struct WakeParams {\r\n /// First-crash respawn delay; doubles per consecutive crash.\r\n pub backoff_base_ms: u64,\r\n /// Backoff ceiling.\r\n pub backoff_cap_ms: u64,\r\n /// Consecutive crash-exits before the give-up latch drops.\r\n pub give_up_after: u32,\r\n}\r\n\r\nimpl Default for WakeParams {\r\n fn default() -> Self {\r\n Self {\r\n backoff_base_ms: 1_000,\r\n backoff_cap_ms: 60_000,\r\n give_up_after: 6,\r\n }\r\n }\r\n}\r\n\r\n/// Exponential backoff for `failures` consecutive crash-exits:\r\n/// `base × 2^(failures-1)`, saturating at the cap (the\r\n/// `spt-net::pairing::ratelimit` recipe). Zero failures ⇒ no wait.\r\n// [impl->REQ-SHELL-2]\r\npub fn backoff_ms(params: &WakeParams, failures: u32) -> u64 {\r\n if failures == 0 {\r\n return 0;\r\n }\r\n params\r\n .backoff_base_ms\r\n .saturating_mul(1u64 << (failures - 1).min(20))\r\n .min(params.backoff_cap_ms)\r\n}\r\n\r\n/// The live watcher registry: one supervision thread per offline instance,\r\n/// keyed `owner/shell_id`. Shared between the daemon's reconcile loop and\r\n/// anything that must stop a watcher.\r\n#[derive(Default)]\r\npub struct WakeSet {\r\n inner: Mutex>,\r\n}\r\n\r\nstruct WatcherHandle {\r\n stop: Arc,\r\n thread: JoinHandle<()>,\r\n}\r\n\r\nimpl WakeSet {\r\n pub fn new() -> Self {\r\n Self::default()\r\n }\r\n\r\n /// How many watchers are live (finished threads pruned first).\r\n pub fn len(&self) -> usize {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.retain(|_, h| !h.thread.is_finished());\r\n map.len()\r\n }\r\n\r\n pub fn is_empty(&self) -> bool {\r\n self.len() == 0\r\n }\r\n\r\n fn contains(&self, owner: &str, shell_id: &str) -> bool {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n match map.get(&(owner.to_string(), shell_id.to_string())) {\r\n Some(h) if !h.thread.is_finished() => true,\r\n Some(_) => {\r\n map.remove(&(owner.to_string(), shell_id.to_string()));\r\n false\r\n }\r\n None => false,\r\n }\r\n }\r\n\r\n fn insert(&self, owner: &str, shell_id: &str, handle: WatcherHandle) {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.insert((owner.to_string(), shell_id.to_string()), handle);\r\n }\r\n\r\n /// Signal one watcher to stop and kill its child (the perch pid file is\r\n /// the kill handle). The thread sees the kill as a non-opcode exit with\r\n /// its stop flag up and returns without counting a failure.\r\n fn stop_watcher(&self, owlery: &Path, owner: &str, shell_id: &str) {\r\n let handle = {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.remove(&(owner.to_string(), shell_id.to_string()))\r\n };\r\n if let Some(h) = handle {\r\n h.stop.store(true, Ordering::SeqCst);\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n kill_waker_at(&perch);\r\n let _ = h.thread.join();\r\n }\r\n }\r\n}\r\n\r\n/// Park the waker's pid **and its birth stamp** as one record — `\\n`\r\n/// — in the single write that already existed.\r\n///\r\n/// ONE file and ONE write, because the pair must never be torn: a stamp parked\r\n/// in a second file leaves a window where the pid is on disk and the stamp is\r\n/// not, and [`spt_store::liveness::relay_liveness`] reads a live pid with no\r\n/// stamp as `Held`. That window is exactly the unauthenticated kill this\r\n/// requirement removes, reintroduced as a race.\r\n///\r\n/// A backend that exposes no start time writes the pid alone — the same\r\n/// one-line shape every pre-fix record already has, which reads `Held` on\r\n/// existence and keeps today's behaviour until the next launch.\r\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\npub fn record_waker_launch(shell_perch: &Path, pid: u32) {\r\n let body = match spt_store::proc::process_started_at(pid) {\r\n Some(birth) => format!(\"{pid}\\n{birth}\"),\r\n None => pid.to_string(),\r\n };\r\n let _ = std::fs::write(shell_perch.join(WAKER_PID_FILE), body);\r\n}\r\n\r\n/// Read that record back — **the** parse, so the two-line format has exactly one\r\n/// reader shape (the `record_shell_launch`/`read_shell_launch` pattern).\r\n///\r\n/// `None` means \"no usable pid on record\": absent, empty, or unparseable. Every\r\n/// caller must treat that as FAIL-TOWARD-ALIVE — refuse the kill and leave the\r\n/// record standing. A whole-content `trim().parse()` (what every reader did\r\n/// before this) returns `None` on the two-line form, so a reader left un-migrated\r\n/// would kill nothing, retire the record anyway, and report success while\r\n/// orphaning a live waker.\r\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\npub fn read_waker_launch(shell_perch: &Path) -> Option<(u32, Option)> {\r\n let raw = std::fs::read_to_string(shell_perch.join(WAKER_PID_FILE)).ok()?;\r\n let mut lines = raw.lines();\r\n let pid = lines.next()?.trim().parse::().ok()?;\r\n let birth = lines.next().and_then(|l| l.trim().parse::().ok());\r\n Some((pid, birth))\r\n}\r\n\r\n/// Kill the recorded waker pid and retire the pid file — the\r\n/// mutual-exclusivity enforcement point and the orphan cleanup\r\n/// ([`crate::shellhost::launch_shell`] calls this before the binary rises;\r\n/// the reconciler calls it before adopting an instance a dead daemon left).\r\n///\r\n/// The kill is now **authenticated**: it fires only when the pid+birth pair\r\n/// says the process at that number is the waker we spawned. Gating on bare\r\n/// `is_process_alive` (what this did before) hands a recycled pid straight to\r\n/// `taskkill /T` (KNOWN-HAZARDS 7.58).\r\n///\r\n/// Same Linux caveat as [`crate::shellhost::kill_shell_at`]: the 10ms jiffy\r\n/// resolution of `/proc//stat` field 22 means the pair NARROWS the\r\n/// mis-fire window to a pid recycled inside the recorded start's own tick,\r\n/// rather than eliminating it. Windows `FILETIME` is unaffected.\r\n// [impl->REQ-SHELL-2]\r\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\npub fn kill_waker_at(shell_perch: &Path) {\r\n let pid_file = shell_perch.join(WAKER_PID_FILE);\r\n let Some((pid, birth)) = read_waker_launch(shell_perch) else {\r\n // Absent is the ordinary pre-launch case and says nothing. A record that\r\n // EXISTS and will not parse is a different animal: refuse, say so, and\r\n // LEAVE it — retiring it here would orphan a possibly-live waker while\r\n // reporting success.\r\n if pid_file.exists() {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_KILL_REFUSED_UNREADABLE:{}: a waker record exists but no pid could be \\\r\n parsed from it — refusing the kill and keeping the record\",\r\n shell_perch.display()\r\n );\r\n }\r\n return;\r\n };\r\n if pid == 0 {\r\n // A backend that exposed no pid: never a process, never a kill target.\r\n let _ = std::fs::remove_file(&pid_file);\r\n return;\r\n }\r\n // The SAME policy the shell chokepoint applies — one destructive decision,\r\n // made in one place.\r\n match crate::shellhost::kill_verdict(spt_store::liveness::relay_liveness(Some(pid), birth)) {\r\n crate::shellhost::KillVerdict::Fire => {\r\n crate::shellhost::kill_shell_pid(pid);\r\n let _ = std::fs::remove_file(&pid_file);\r\n }\r\n crate::shellhost::KillVerdict::RetireOnly => {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_KILL_REFUSED_GONE:{}: recorded waker pid={pid} is not the process we \\\r\n spawned (absent, or the pid was recycled) — retiring the record and killing \\\r\n nothing\",\r\n shell_perch.display()\r\n );\r\n let _ = std::fs::remove_file(&pid_file);\r\n }\r\n crate::shellhost::KillVerdict::RefuseAndKeep => {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_KILL_REFUSED_UNPROVEN:{}: recorded waker pid={pid} could not be \\\r\n identified — refusing the kill and keeping the record; the waker may still be \\\r\n running\",\r\n shell_perch.display()\r\n );\r\n }\r\n }\r\n}\r\n\r\n/// Clear the give-up latch — any (re)launch is \"next shell activity\".\r\npub fn clear_gave_up(shell_perch: &Path) {\r\n let _ = std::fs::remove_file(shell_perch.join(WAKER_GAVE_UP_FILE));\r\n}\r\n\r\n/// One watcher's supervision loop (runs on its own thread): spawn the\r\n/// tokenized `wake_command`, park the pid, wait; `exit(WAKE_OPCODE)` ⇒ run\r\n/// `resolve` once and finish; any other exit ⇒ respawn with exponential\r\n/// backoff until the give-up budget, then drop the durable latch. A raised\r\n/// `stop` flag ends the loop without counting the (killed) child as a crash.\r\n// [impl->REQ-SHELL-2]\r\npub fn watcher_run(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n tokens: &[String],\r\n params: &WakeParams,\r\n stop: &AtomicBool,\r\n resolve: impl FnOnce() -> Result,\r\n) {\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n let Some((program, args)) = tokens.split_first() else {\r\n spt_proto::emit_line_err!(\"WAKER_EMPTY:{owner}/{shell_id}: empty wake_command\");\r\n return;\r\n };\r\n let mut failures = 0u32;\r\n while !stop.load(Ordering::SeqCst) {\r\n let mut cmd = Command::new(program);\r\n cmd.args(args)\r\n .stdin(Stdio::null())\r\n .stdout(Stdio::null())\r\n .stderr(Stdio::null());\r\n // The daemon (a console-less DETACHED process) hosting a\r\n // console-subsystem waker would otherwise pop a visible Terminal\r\n // window per spawn on Windows 11 (the KH 5.6-adjacent D3e lesson —\r\n // mock-shell's spt_cmd does the same).\r\n #[cfg(windows)]\r\n {\r\n use std::os::windows::process::CommandExt;\r\n cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW\r\n }\r\n let child = cmd.spawn();\r\n let mut child = match child {\r\n Ok(c) => c,\r\n Err(e) => {\r\n // An unspawnable waker is a permanent condition — latch now.\r\n spt_proto::emit_line_err!(\"WAKER_SPAWN_FAIL:{owner}/{shell_id}: {e} (giving up)\");\r\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\r\n return;\r\n }\r\n };\r\n // The birth stamp rides WITH the pid, in one write — the kill path\r\n // authenticates the pair, and a stamp parked separately would leave a\r\n // window that reads Held. [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\n record_waker_launch(&perch, child.id());\r\n let status = child.wait();\r\n let _ = std::fs::remove_file(perch.join(WAKER_PID_FILE));\r\n if stop.load(Ordering::SeqCst) {\r\n return; // stopped from outside — the kill is not a crash\r\n }\r\n match status.ok().and_then(|s| s.code()) {\r\n Some(WAKE_OPCODE) => {\r\n match resolve() {\r\n Ok(what) => spt_proto::emit_line_err!(\"SHELL_WAKE:{owner}/{shell_id}: {what}\"),\r\n Err(e) => spt_proto::emit_line_err!(\"SHELL_WAKE_FAIL:{owner}/{shell_id}: {e}\"),\r\n }\r\n return;\r\n }\r\n _ => {\r\n failures += 1;\r","truncated":true,"truncatedBy":"lines","totalLines":2161,"totalBytes":14340,"outputLines":323,"outputBytes":14340,"lastLinePartial":false,"firstLineExceedsLimit":false},"totalLines":2161,"displayContent":{"text":"//! Shell wake-watcher hosting (M5-D4b — CONTEXT §Shell sleep/wake): the\r\n//! offline half of the online/offline mutual exclusivity. While a shell\r\n//! instance is **offline** and its manifest declares a `wake_command`, the\r\n//! daemon runs that template as a long-running **wake-watcher** child whose\r\n//! sole job is to fire a wake; while the shell binary runs, no watcher does\r\n//! ([`reconcile_once`] flips between them — spt-core owns the flip).\r\n//!\r\n//! **Exit-opcode supervision:** the watcher exiting with [`WAKE_OPCODE`] ⇒\r\n//! the wake resolution ([`resolve_wake`]) brings the shell online. Any other\r\n//! exit is a crash ⇒ respawn with exponential backoff ([`backoff_ms`]) and\r\n//! **give-up** after [`WakeParams::give_up_after`] consecutive crashes (a\r\n//! durable [`WAKER_GAVE_UP_FILE`] marker the next shell activity — any\r\n//! (re)launch — clears; crash-bug safety, the watcher can never crash-loop\r\n//! forever). One watcher per offline instance: the in-process [`WakeSet`]\r\n//! entry plus the perch's [`WAKER_PID_FILE`] (which also lets a freshly\r\n//! booted daemon kill a dead daemon's orphaned watcher before adopting).\r\n//!\r\n//! **Scheduling (KH 7.4):** every watcher gets its own supervision thread —\r\n//! a hung waker stalls nothing; the reconcile loop itself is one bounded\r\n//! sweep per tick off the daemon's control surfaces. Watcher children are\r\n//! *supervised* (waited) children, never detached-immortal — the KH 5.6\r\n//! pipe-inherit shape (an unwaitable child holding a capture pipe) does not\r\n//! arise; stdio is null regardless.\r\n// [impl->REQ-SHELL-2]\r\n\r\nuse std::collections::HashMap;\r\nuse std::path::Path;\r\nuse std::process::{Command, Stdio};\r\nuse std::sync::atomic::{AtomicBool, Ordering};\r\nuse std::sync::{Arc, Mutex};\r\nuse std::thread::JoinHandle;\r\nuse std::time::Duration;\r\n\r\nuse spt_runtime::manifest::{AdapterKind, Manifest, Shell};\r\nuse spt_runtime::registry::AdapterRecord;\r\nuse spt_store::perch::ParentHint;\r\nuse spt_store::shellinfo::{self, SHELL_STATUS_OFFLINE, SHELL_STATUS_ONLINE};\r\n\r\n/// The wake opcode (documented in `docs/MANIFEST.md` §Shell adapters): a\r\n/// wake-watcher exiting with **86** fires the wake resolution; every other\r\n/// exit is a crash.\r\npub const WAKE_OPCODE: i32 = 86;\r\n\r\n/// The running watcher's OS pid, parked on the shell perch — the\r\n/// one-watcher-per-instance lock and the cross-daemon-restart kill handle.\r\npub const WAKER_PID_FILE: &str = \"waker.pid\";\r\n\r\n/// The give-up latch: present ⇒ the watcher crash-looped past its budget and\r\n/// the reconciler must NOT restart it. Cleared by the next shell activity\r\n/// (any (re)launch — [`crate::shellhost::launch_shell`]).\r\npub const WAKER_GAVE_UP_FILE: &str = \"waker.gaveup\";\r\n\r\n/// Watcher supervision knobs (injectable for tests; defaults are production).\r\n#[derive(Debug, Clone, Copy)]\r\npub struct WakeParams {\r\n /// First-crash respawn delay; doubles per consecutive crash.\r\n pub backoff_base_ms: u64,\r\n /// Backoff ceiling.\r\n pub backoff_cap_ms: u64,\r\n /// Consecutive crash-exits before the give-up latch drops.\r\n pub give_up_after: u32,\r\n}\r\n\r\nimpl Default for WakeParams {\r\n fn default() -> Self {\r\n Self {\r\n backoff_base_ms: 1_000,\r\n backoff_cap_ms: 60_000,\r\n give_up_after: 6,\r\n }\r\n }\r\n}\r\n\r\n/// Exponential backoff for `failures` consecutive crash-exits:\r\n/// `base × 2^(failures-1)`, saturating at the cap (the\r\n/// `spt-net::pairing::ratelimit` recipe). Zero failures ⇒ no wait.\r\n// [impl->REQ-SHELL-2]\r\npub fn backoff_ms(params: &WakeParams, failures: u32) -> u64 {\r\n if failures == 0 {\r\n return 0;\r\n }\r\n params\r\n .backoff_base_ms\r\n .saturating_mul(1u64 << (failures - 1).min(20))\r\n .min(params.backoff_cap_ms)\r\n}\r\n\r\n/// The live watcher registry: one supervision thread per offline instance,\r\n/// keyed `owner/shell_id`. Shared between the daemon's reconcile loop and\r\n/// anything that must stop a watcher.\r\n#[derive(Default)]\r\npub struct WakeSet {\r\n inner: Mutex>,\r\n}\r\n\r\nstruct WatcherHandle {\r\n stop: Arc,\r\n thread: JoinHandle<()>,\r\n}\r\n\r\nimpl WakeSet {\r\n pub fn new() -> Self {\r\n Self::default()\r\n }\r\n\r\n /// How many watchers are live (finished threads pruned first).\r\n pub fn len(&self) -> usize {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.retain(|_, h| !h.thread.is_finished());\r\n map.len()\r\n }\r\n\r\n pub fn is_empty(&self) -> bool {\r\n self.len() == 0\r\n }\r\n\r\n fn contains(&self, owner: &str, shell_id: &str) -> bool {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n match map.get(&(owner.to_string(), shell_id.to_string())) {\r\n Some(h) if !h.thread.is_finished() => true,\r\n Some(_) => {\r\n map.remove(&(owner.to_string(), shell_id.to_string()));\r\n false\r\n }\r\n None => false,\r\n }\r\n }\r\n\r\n fn insert(&self, owner: &str, shell_id: &str, handle: WatcherHandle) {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.insert((owner.to_string(), shell_id.to_string()), handle);\r\n }\r\n\r\n /// Signal one watcher to stop and kill its child (the perch pid file is\r\n /// the kill handle). The thread sees the kill as a non-opcode exit with\r\n /// its stop flag up and returns without counting a failure.\r\n fn stop_watcher(&self, owlery: &Path, owner: &str, shell_id: &str) {\r\n let handle = {\r\n let mut map = self.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.remove(&(owner.to_string(), shell_id.to_string()))\r\n };\r\n if let Some(h) = handle {\r\n h.stop.store(true, Ordering::SeqCst);\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n kill_waker_at(&perch);\r\n let _ = h.thread.join();\r\n }\r\n }\r\n}\r\n\r\n/// Park the waker's pid **and its birth stamp** as one record — `\\n`\r\n/// — in the single write that already existed.\r\n///\r\n/// ONE file and ONE write, because the pair must never be torn: a stamp parked\r\n/// in a second file leaves a window where the pid is on disk and the stamp is\r\n/// not, and [`spt_store::liveness::relay_liveness`] reads a live pid with no\r\n/// stamp as `Held`. That window is exactly the unauthenticated kill this\r\n/// requirement removes, reintroduced as a race.\r\n///\r\n/// A backend that exposes no start time writes the pid alone — the same\r\n/// one-line shape every pre-fix record already has, which reads `Held` on\r\n/// existence and keeps today's behaviour until the next launch.\r\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\npub fn record_waker_launch(shell_perch: &Path, pid: u32) {\r\n let body = match spt_store::proc::process_started_at(pid) {\r\n Some(birth) => format!(\"{pid}\\n{birth}\"),\r\n None => pid.to_string(),\r\n };\r\n let _ = std::fs::write(shell_perch.join(WAKER_PID_FILE), body);\r\n}\r\n\r\n/// Read that record back — **the** parse, so the two-line format has exactly one\r\n/// reader shape (the `record_shell_launch`/`read_shell_launch` pattern).\r\n///\r\n/// `None` means \"no usable pid on record\": absent, empty, or unparseable. Every\r\n/// caller must treat that as FAIL-TOWARD-ALIVE — refuse the kill and leave the\r\n/// record standing. A whole-content `trim().parse()` (what every reader did\r\n/// before this) returns `None` on the two-line form, so a reader left un-migrated\r\n/// would kill nothing, retire the record anyway, and report success while\r\n/// orphaning a live waker.\r\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\npub fn read_waker_launch(shell_perch: &Path) -> Option<(u32, Option)> {\r\n let raw = std::fs::read_to_string(shell_perch.join(WAKER_PID_FILE)).ok()?;\r\n let mut lines = raw.lines();\r\n let pid = lines.next()?.trim().parse::().ok()?;\r\n let birth = lines.next().and_then(|l| l.trim().parse::().ok());\r\n Some((pid, birth))\r\n}\r\n\r\n/// Kill the recorded waker pid and retire the pid file — the\r\n/// mutual-exclusivity enforcement point and the orphan cleanup\r\n/// ([`crate::shellhost::launch_shell`] calls this before the binary rises;\r\n/// the reconciler calls it before adopting an instance a dead daemon left).\r\n///\r\n/// The kill is now **authenticated**: it fires only when the pid+birth pair\r\n/// says the process at that number is the waker we spawned. Gating on bare\r\n/// `is_process_alive` (what this did before) hands a recycled pid straight to\r\n/// `taskkill /T` (KNOWN-HAZARDS 7.58).\r\n///\r\n/// Same Linux caveat as [`crate::shellhost::kill_shell_at`]: the 10ms jiffy\r\n/// resolution of `/proc//stat` field 22 means the pair NARROWS the\r\n/// mis-fire window to a pid recycled inside the recorded start's own tick,\r\n/// rather than eliminating it. Windows `FILETIME` is unaffected.\r\n// [impl->REQ-SHELL-2]\r\n// [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\npub fn kill_waker_at(shell_perch: &Path) {\r\n let pid_file = shell_perch.join(WAKER_PID_FILE);\r\n let Some((pid, birth)) = read_waker_launch(shell_perch) else {\r\n // Absent is the ordinary pre-launch case and says nothing. A record that\r\n // EXISTS and will not parse is a different animal: refuse, say so, and\r\n // LEAVE it — retiring it here would orphan a possibly-live waker while\r\n // reporting success.\r\n if pid_file.exists() {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_KILL_REFUSED_UNREADABLE:{}: a waker record exists but no pid could be \\\r\n parsed from it — refusing the kill and keeping the record\",\r\n shell_perch.display()\r\n );\r\n }\r\n return;\r\n };\r\n if pid == 0 {\r\n // A backend that exposed no pid: never a process, never a kill target.\r\n let _ = std::fs::remove_file(&pid_file);\r\n return;\r\n }\r\n // The SAME policy the shell chokepoint applies — one destructive decision,\r\n // made in one place.\r\n match crate::shellhost::kill_verdict(spt_store::liveness::relay_liveness(Some(pid), birth)) {\r\n crate::shellhost::KillVerdict::Fire => {\r\n crate::shellhost::kill_shell_pid(pid);\r\n let _ = std::fs::remove_file(&pid_file);\r\n }\r\n crate::shellhost::KillVerdict::RetireOnly => {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_KILL_REFUSED_GONE:{}: recorded waker pid={pid} is not the process we \\\r\n spawned (absent, or the pid was recycled) — retiring the record and killing \\\r\n nothing\",\r\n shell_perch.display()\r\n );\r\n let _ = std::fs::remove_file(&pid_file);\r\n }\r\n crate::shellhost::KillVerdict::RefuseAndKeep => {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_KILL_REFUSED_UNPROVEN:{}: recorded waker pid={pid} could not be \\\r\n identified — refusing the kill and keeping the record; the waker may still be \\\r\n running\",\r\n shell_perch.display()\r\n );\r\n }\r\n }\r\n}\r\n\r\n/// Clear the give-up latch — any (re)launch is \"next shell activity\".\r\npub fn clear_gave_up(shell_perch: &Path) {\r\n let _ = std::fs::remove_file(shell_perch.join(WAKER_GAVE_UP_FILE));\r\n}\r\n\r\n/// One watcher's supervision loop (runs on its own thread): spawn the\r\n/// tokenized `wake_command`, park the pid, wait; `exit(WAKE_OPCODE)` ⇒ run\r\n/// `resolve` once and finish; any other exit ⇒ respawn with exponential\r\n/// backoff until the give-up budget, then drop the durable latch. A raised\r\n/// `stop` flag ends the loop without counting the (killed) child as a crash.\r\n// [impl->REQ-SHELL-2]\r\npub fn watcher_run(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n tokens: &[String],\r\n params: &WakeParams,\r\n stop: &AtomicBool,\r\n resolve: impl FnOnce() -> Result,\r\n) {\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n let Some((program, args)) = tokens.split_first() else {\r\n spt_proto::emit_line_err!(\"WAKER_EMPTY:{owner}/{shell_id}: empty wake_command\");\r\n return;\r\n };\r\n let mut failures = 0u32;\r\n while !stop.load(Ordering::SeqCst) {\r\n let mut cmd = Command::new(program);\r\n cmd.args(args)\r\n .stdin(Stdio::null())\r\n .stdout(Stdio::null())\r\n .stderr(Stdio::null());\r\n // The daemon (a console-less DETACHED process) hosting a\r\n // console-subsystem waker would otherwise pop a visible Terminal\r\n // window per spawn on Windows 11 (the KH 5.6-adjacent D3e lesson —\r\n // mock-shell's spt_cmd does the same).\r\n #[cfg(windows)]\r\n {\r\n use std::os::windows::process::CommandExt;\r\n cmd.creation_flags(0x0800_0000); // CREATE_NO_WINDOW\r\n }\r\n let child = cmd.spawn();\r\n let mut child = match child {\r\n Ok(c) => c,\r\n Err(e) => {\r\n // An unspawnable waker is a permanent condition — latch now.\r\n spt_proto::emit_line_err!(\"WAKER_SPAWN_FAIL:{owner}/{shell_id}: {e} (giving up)\");\r\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\r\n return;\r\n }\r\n };\r\n // The birth stamp rides WITH the pid, in one write — the kill path\r\n // authenticates the pair, and a stamp parked separately would leave a\r\n // window that reads Held. [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\n record_waker_launch(&perch, child.id());\r\n let status = child.wait();\r\n let _ = std::fs::remove_file(perch.join(WAKER_PID_FILE));\r\n if stop.load(Ordering::SeqCst) {\r\n return; // stopped from outside — the kill is not a crash\r\n }\r\n match status.ok().and_then(|s| s.code()) {\r\n Some(WAKE_OPCODE) => {\r\n match resolve() {\r\n Ok(what) => spt_proto::emit_line_err!(\"SHELL_WAKE:{owner}/{shell_id}: {what}\"),\r\n Err(e) => spt_proto::emit_line_err!(\"SHELL_WAKE_FAIL:{owner}/{shell_id}: {e}\"),\r\n }\r\n return;\r\n }\r\n _ => {\r\n failures += 1;\r\n…\n }\n }\n }\n}","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299,300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,null,339,340,341,342]},"fileSize":100821,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\crates\\spt-daemon\\src\\shellwake.rs"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":2161,"totalBytes":14340,"outputLines":323,"outputBytes":14340,"shownRange":{"start":1,"end":323},"nextOffset":324}}},"isError":false,"timestamp":1789001136956}}
{"type":"message","id":"ac0f6d03","parentId":"fb18ed21","timestamp":"2026-09-10T00:45:36.964Z","message":{"role":"toolResult","toolCallId":"call_Af4TRJYugyLpvR3kOYPeRRR4|fc_077f3569365e313d016aa1fdb0c08c87d1b16af7f4dfd838ca","toolName":"read","content":[{"type":"text","text":"//! Shell-instance perch records (M5-D3a — CONTEXT §Shell model,\n//! `docs/STORAGE.md` §Shells in the layout).\n//!\n//! A shell perch is **not** an agent perch: its `info.json` carries exactly\n//! `type=Shell, owner, adapter_name, status, alias?` — a dedicated\n//! [`ShellInfo`] shape, deliberately distinct from [`crate::info::InfoJson`],\n//! so the agent-perch readers (liveness, registry stale-clean, the consent\n//! MRA scan) stay blind to shells by construction. Capabilities are **never**\n//! duplicated here — they resolve from the shell adapter manifest by\n//! `adapter_name`.\n//!\n//! **Identity model (REQ-EP-5):** `spt shell spawn` *mints* a new instance —\n//! the immutable canonical id `-` ([`mint_shell_id`]: smallest\n//! free `n` over **existing** instance dirs; online and offline both occupy,\n//! `teardown` frees the slot). The optional **alias** is a per-instance,\n//! owner-unique display/address overlay set at spawn or by `shell rename` —\n//! interchangeable with the canonical id for addressing\n//! ([`resolve_shell_ref`], canonical-first), never obscuring `adapter_name`.\n//!\n//! Torn-read stance mirrors `info.rs` (KNOWN-HAZARDS 1.2): writers go through\n//! the atomic rename; readers tolerate failure and return `None`.\n// [impl->REQ-EP-5]\n\nuse serde::{Deserialize, Serialize};\nuse std::path::Path;\n\nuse crate::atomic::atomic_write_string;\nuse crate::perch;\n\n/// `status` value: the shell binary is linked and running.\npub const SHELL_STATUS_ONLINE: &str = \"online\";\n/// `status` value: the perch exists, no binary linked (re-linkable if the\n/// adapter is `persistent`; the spawn-time initial state until D3b binds).\npub const SHELL_STATUS_OFFLINE: &str = \"offline\";\n/// The fixed `type` tag on every shell perch record.\npub const SHELL_TYPE: &str = \"Shell\";\n\n/// On-disk shape of a shell perch's `info.json` — the full field set, by\n/// contract (STORAGE.md: \"carries only `type=Shell`, `owner`, `adapter_name`,\n/// `status`, and an optional `alias`\").\n// [impl->REQ-SHELL-1]\n#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct ShellInfo {\n /// Always [`SHELL_TYPE`] — readers refuse anything else.\n pub r#type: String,\n /// The owning agent endpoint id — the only id that may drive this shell.\n pub owner: String,\n /// The providing shell adapter (capability surface resolves from its\n /// manifest, never from the perch).\n pub adapter_name: String,\n /// [`SHELL_STATUS_ONLINE`] | [`SHELL_STATUS_OFFLINE`].\n pub status: String,\n /// Owner-unique friendly label (runtime state, not a manifest field).\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub alias: Option,\n}\n\nimpl ShellInfo {\n /// A freshly-minted instance record: offline until the broker launch +\n /// `api bind` handshake onlines it (D3b).\n pub fn new(owner: &str, adapter_name: &str) -> Self {\n ShellInfo {\n r#type: SHELL_TYPE.to_string(),\n owner: owner.to_string(),\n adapter_name: adapter_name.to_string(),\n status: SHELL_STATUS_OFFLINE.to_string(),\n alias: None,\n }\n }\n}\n\n/// Shell-instance model failures — CLI-facing, so they carry the why.\n#[derive(Debug)]\npub enum ShellError {\n /// The alias is already held by another of this owner's instances, or\n /// shadows an existing canonical id.\n AliasTaken(String),\n /// No instance of this owner matches the ref (canonical id or alias).\n NotFound(String),\n Io(std::io::Error),\n}\n\nimpl std::fmt::Display for ShellError {\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n match self {\n ShellError::AliasTaken(a) => write!(f, \"alias already in use: {a}\"),\n ShellError::NotFound(r) => write!(f, \"no shell instance matches: {r}\"),\n ShellError::Io(e) => write!(f, \"io: {e}\"),\n }\n }\n}\n\nimpl From for ShellError {\n fn from(e: std::io::Error) -> Self {\n ShellError::Io(e)\n }\n}\n\n/// Read a shell perch's record. Tolerant (`None` on missing/corrupt — the\n/// list path skips, never panics) and shape-checked: a record whose `type`\n/// isn't [`SHELL_TYPE`] is not a shell perch.\npub fn read_shell_info(shell_perch: &Path) -> Option {\n let s = std::fs::read_to_string(perch::info_file_at(shell_perch)).ok()?;\n let info: ShellInfo = serde_json::from_str(&s).ok()?;\n (info.r#type == SHELL_TYPE).then_some(info)\n}\n\n/// Write a shell perch's record (atomic rename — the 1.2 torn-read stance).\n/// Creates the perch dir.\npub fn write_shell_info(shell_perch: &Path, info: &ShellInfo) -> std::io::Result<()> {\n std::fs::create_dir_all(shell_perch)?;\n let s = serde_json::to_string_pretty(info).expect(\"ShellInfo serializes\");\n atomic_write_string(&perch::info_file_at(shell_perch), &s)\n}\n\n/// The launched binary's recorded pid, one file per instance perch. Written by\n/// the launch, removed by the close — and the ONLY on-disk evidence that the\n/// process a record calls `online` still exists.\npub const SHELL_PID_FILE: &str = \"shell.pid\";\n\n/// The recorded launch pid, if the perch parks a parseable one.\npub fn read_shell_pid(shell_perch: &Path) -> Option {\n std::fs::read_to_string(shell_perch.join(SHELL_PID_FILE))\n .ok()?\n .trim()\n .parse()\n .ok()\n}\n\n/// `/shell.launch.json` — the birth stamp parked beside the pid at\n/// launch (BAROMETER W2, releases#78).\npub const SHELL_LAUNCH_FILE: &str = \"shell.launch.json\";\n\n/// What a launch recorded about the process it started.\n///\n/// TWO VALUES, ANSWERING TWO DIFFERENT QUESTIONS, and keeping them apart is the\n/// whole point of the shape:\n///\n/// - `pid_started_at` is the platform's NATIVE start-time value, used for one\n/// question only — the same-pid-different-process PAIR test within a single\n/// boot ([`crate::liveness::relay_liveness`]). It is deliberately never\n/// compared across boots, because it is not the same kind of number on every\n/// platform: on Windows it is an absolute FILETIME, but on Linux it is field\n/// 22 of `/proc//stat`, i.e. JIFFIES SINCE BOOT, which resets at every\n/// boot. A value recorded before a restart is therefore indistinguishable\n/// from a fresh one after it, and any cross-boot comparison of this field\n/// would be correct on Windows and silently wrong on Linux.\n/// - `launched_ms` is an ABSOLUTE wall-clock stamp (epoch-ms), used by the\n/// nonpersistent watcher's cross-boot freeze. Persistent restoration does not\n/// gate on launch age; the native birth stamp still authenticates liveness.\n#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]\npub struct ShellLaunch {\n /// The native start-time of the launched pid, when the platform offers one.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub pid_started_at: Option,\n /// Wall-clock epoch-ms at which this instance was launched.\n pub launched_ms: u64,\n}\n\n/// Record the birth stamp for a just-launched `pid`. Best-effort: a stamp that\n/// cannot be written must never fail the launch — a missing stamp degrades the\n/// probe to its pre-existing fail-toward-alive behaviour, which is the safe\n/// direction, while a failed launch is a real outage.\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\npub fn record_shell_launch(shell_perch: &Path, pid: u32, now_ms: u64) {\n let launch = ShellLaunch {\n pid_started_at: crate::proc::process_started_at(pid),\n launched_ms: now_ms,\n };\n if let Ok(json) = serde_json::to_string_pretty(&launch) {\n let _ = atomic_write_string(&shell_perch.join(SHELL_LAUNCH_FILE), &json);\n }\n}\n\n/// Read the birth stamp, if this instance was launched by a build that parks one.\n/// Absent or unparseable ⇒ `None`, which every consumer treats as \"no stamp to\n/// compare\" rather than as a fault.\npub fn read_shell_launch(shell_perch: &Path) -> Option {\n let raw = std::fs::read_to_string(shell_perch.join(SHELL_LAUNCH_FILE)).ok()?;\n serde_json::from_str(&raw).ok()\n}\n\n/// **The** discriminant behind [`effective_status`]: is this instance's recorded\n/// binary *provably* gone? Narrow on purpose — true only when the perch parks a\n/// pid, it parses non-zero, and the process is not alive.\n///\n/// Everything else reads **alive**: an absent or unparseable pid file, and the\n/// `0` a broker-hosted spawn records when its backend exposed no pid\n/// ([`crate::proc::is_process_alive`] already reads 0 as dead, so the explicit\n/// filter here is what keeps a pid-less backend from being declared dead by this\n/// resolver). That fail-toward-alive stance mirrors `liveness.rs`'s interim\n/// parity: this predicate exists to catch a *corpse*, never to guess at a\n/// backend it cannot see.\n///\n/// Recycled pids read alive, so a heal can be **missed** but never **mis-fired**\n/// — the failure direction is \"stays stale\", never \"tears down a live instance\".\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\npub fn shell_pid_provably_dead(shell_perch: &Path) -> bool {\n let Some(pid) = read_shell_pid(shell_perch).filter(|&pid| pid != 0) else {\n return false;\n };\n // BAROMETER W2 (releases#78): probe pid AND birth stamp, not the pid alone.\n // A pid namespace resets at boot, so a corpse pid can be REUSED by an\n // unrelated process started after the restart; under bare-pid liveness that\n // reads ALIVE, the derived status reads online, and `relink` then refuses\n // SHELL_ALREADY_ONLINE -- the one command that recovers the instance\n // refusing on the very state that is wrong. The PAIR test (same pid,\n // different start time) is what tells a reused pid from our own process.\n //\n // The stance is unchanged where there is no stamp to compare: an instance\n // launched before this field existed, or a backend that exposed no start\n // time, still falls back to plain absence and fails toward ALIVE.\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n let birth = read_shell_launch(shell_perch).and_then(|l| l.pid_started_at);\n matches!(\n crate::liveness::relay_liveness(Some(pid), birth),\n crate::liveness::RelayLiveness::Gone\n )\n}\n\n/// A shell instance's **derived** status — the shell-side twin of\n/// `liveness::is_perch_alive` (REQ-HAZARD-DAEMON-HOSTED-LIVENESS gave agent\n/// perches exactly this; shells never got it).\n///\n/// The recorded `status` has exactly two writers — the bind handshake (→online)\n/// and `spt_daemon::shellhost::close_shell` (→offline) — and `close_shell` runs\n/// on the **link-break** path alone. A binary that dies\n/// abruptly (force-kill, crash, OOM) breaks no link, so nothing ever writes the\n/// flip and the record says `online` forever. Deriving closes that hole without\n/// adding a supervisor: `online` + a provably-dead pid reads\n/// [`SHELL_STATUS_OFFLINE`]; every other case is the recorded value verbatim.\n///\n/// Callers that must NOT derive are documented at their sites (the two status\n/// writers, the owner-suspend cascade whose close IS the cleanup, and the wake\n/// reconciler's eligibility read) — see REQ-HAZARD-SHELL-STALE-ONLINE.\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\npub fn effective_status<'a>(shell_perch: &Path, info: &'a ShellInfo) -> &'a str {\n if info.status == SHELL_STATUS_ONLINE && shell_pid_provably_dead(shell_perch) {\n return SHELL_STATUS_OFFLINE;\n }\n &info.status\n}\n\n/// [`effective_status`] as the predicate every gate actually asks: is this\n/// instance online *in fact*, not merely on paper?\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\npub fn is_shell_online(shell_perch: &Path, info: &ShellInfo) -> bool {\n effective_status(shell_perch, info) == SHELL_STATUS_ONLINE\n}\n\n/// The **parent** segment of an adapter option: the part before the first `:`\n/// of a `:` composite (CONTEXT.md §adapter profile). The\n/// canonical shell id is minted off this — never the composite — so the id (a\n/// perch dir name + endpoint address) stays colon-free and path-safe; the full\n/// composite rides only in the `adapter_name` carrier field. Mirrors\n/// `spt_runtime::profile::split_option`, inlined here to keep spt-store free of\n/// an spt-runtime dependency (the crate graph runs the other way).\nfn adapter_parent(option: &str) -> &str {\n option.split_once(':').map_or(option, |(a, _)| a)\n}\n\n/// Parse the `n` out of a canonical `-` dir name for `parent`.\nfn instance_ordinal(dir_name: &str, parent: &str) -> Option {\n let suffix = dir_name.strip_prefix(parent)?.strip_prefix('-')?;\n if suffix.is_empty() || !suffix.bytes().all(|b| b.is_ascii_digit()) {\n return None;\n }\n suffix.parse().ok()\n}\n\n/// Mint the next canonical id for `adapter` under `owner`: the **smallest\n/// free `n`** over existing instance dirs. Online and offline both occupy a\n/// slot (every non-torn-down perch counts — the same all-existing rule the\n/// instance cap uses); `teardown` removes the dir, so its `n` is reused.\n///\n/// `adapter` may be a `:` composite; the id is minted off the\n/// **parent** segment ([`adapter_parent`]) so two profiles of one adapter share\n/// the same `-` ordinal space (instances are the adapter's resource,\n/// not the profile's) and the id never carries the `:`.\n// [impl->REQ-EP-5]\n// [impl->REQ-HAZARD-ID-CHARSET]\npub fn mint_shell_id(owlery: &Path, owner: &str, adapter: &str) -> String {\n let parent = adapter_parent(adapter);\n let shells = perch::resolve_shells_dir_in(owlery, owner);\n let mut taken: Vec = std::fs::read_dir(&shells)\n .map(|entries| {\n entries\n .flatten()\n .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))\n .filter_map(|e| instance_ordinal(&e.file_name().to_string_lossy(), parent))\n .collect()\n })\n .unwrap_or_default();\n taken.sort_unstable();\n let mut n = 0u32;\n for t in taken {\n if t == n {\n n += 1;\n } else if t > n {\n break;\n }\n }\n format!(\"{parent}-{n}\")\n}\n\n/// Every shell instance of `owner`: `(canonical_id, record)`, sorted by id\n/// for a stable order. Tolerant — a dir without a valid [`ShellInfo`] is\n/// skipped (it still *occupies* its mint slot; it just doesn't list).\n// [impl->REQ-EP-5]\npub fn list_shells(owlery: &Path, owner: &str) -> Vec<(String, ShellInfo)> {\n let shells = perch::resolve_shells_dir_in(owlery, owner);\n let Ok(entries) = std::fs::read_dir(&shells) else {\n return Vec::new();\n };\n let mut out: Vec<(String, ShellInfo)> = entries\n .flatten()\n .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))\n .filter_map(|e| {\n let id = e.file_name().to_string_lossy().into_owned();\n read_shell_info(&e.path()).map(|info| (id, info))\n })\n .collect();\n out.sort_by(|a, b| a.0.cmp(&b.0));\n out\n}\n\n/// Resolve a shell ref — canonical id or alias — to `(canonical_id, record)`.\n/// **Canonical-first**: an alias can never shadow a canonical id (spawn/rename\n/// refuse minting such an alias, and resolution checks canonical before alias\n/// as defense in depth). Aliases are owner-unique, so at most one matches.\n// [impl->REQ-EP-5]\npub fn resolve_shell_ref(\n owlery: &Path,\n owner: &str,\n shell_ref: &str,\n) -> Option<(String, ShellInfo)> {\n let direct = perch::resolve_shell_perch_path_in(owlery, owner, shell_ref);\n if let Some(info) = read_shell_info(&direct) {\n return Some((shell_ref.to_string(), info));\n }\n list_shells(owlery, owner)\n .into_iter()\n .find(|(_, info)| info.alias.as_deref() == Some(shell_ref))\n}\n\n/// Whether `alias` is free for `owner`: held by no instance's alias and not\n/// shadowing any existing canonical id.\nfn alias_free(owlery: &Path, owner: &str, alias: &str) -> bool {\n resolve_shell_ref(owlery, owner, alias).is_none()\n}\n\n/// Mint + record a new instance of `adapter` for `owner` (the storage half of\n/// `spt shell spawn` — adapter-registration and consent gates are the\n\n[Showing lines 1-353 of 726. Use :354 to continue]"}],"details":{"truncation":{"content":"//! Shell-instance perch records (M5-D3a — CONTEXT §Shell model,\r\n//! `docs/STORAGE.md` §Shells in the layout).\r\n//!\r\n//! A shell perch is **not** an agent perch: its `info.json` carries exactly\r\n//! `type=Shell, owner, adapter_name, status, alias?` — a dedicated\r\n//! [`ShellInfo`] shape, deliberately distinct from [`crate::info::InfoJson`],\r\n//! so the agent-perch readers (liveness, registry stale-clean, the consent\r\n//! MRA scan) stay blind to shells by construction. Capabilities are **never**\r\n//! duplicated here — they resolve from the shell adapter manifest by\r\n//! `adapter_name`.\r\n//!\r\n//! **Identity model (REQ-EP-5):** `spt shell spawn` *mints* a new instance —\r\n//! the immutable canonical id `-` ([`mint_shell_id`]: smallest\r\n//! free `n` over **existing** instance dirs; online and offline both occupy,\r\n//! `teardown` frees the slot). The optional **alias** is a per-instance,\r\n//! owner-unique display/address overlay set at spawn or by `shell rename` —\r\n//! interchangeable with the canonical id for addressing\r\n//! ([`resolve_shell_ref`], canonical-first), never obscuring `adapter_name`.\r\n//!\r\n//! Torn-read stance mirrors `info.rs` (KNOWN-HAZARDS 1.2): writers go through\r\n//! the atomic rename; readers tolerate failure and return `None`.\r\n// [impl->REQ-EP-5]\r\n\r\nuse serde::{Deserialize, Serialize};\r\nuse std::path::Path;\r\n\r\nuse crate::atomic::atomic_write_string;\r\nuse crate::perch;\r\n\r\n/// `status` value: the shell binary is linked and running.\r\npub const SHELL_STATUS_ONLINE: &str = \"online\";\r\n/// `status` value: the perch exists, no binary linked (re-linkable if the\r\n/// adapter is `persistent`; the spawn-time initial state until D3b binds).\r\npub const SHELL_STATUS_OFFLINE: &str = \"offline\";\r\n/// The fixed `type` tag on every shell perch record.\r\npub const SHELL_TYPE: &str = \"Shell\";\r\n\r\n/// On-disk shape of a shell perch's `info.json` — the full field set, by\r\n/// contract (STORAGE.md: \"carries only `type=Shell`, `owner`, `adapter_name`,\r\n/// `status`, and an optional `alias`\").\r\n// [impl->REQ-SHELL-1]\r\n#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\r\npub struct ShellInfo {\r\n /// Always [`SHELL_TYPE`] — readers refuse anything else.\r\n pub r#type: String,\r\n /// The owning agent endpoint id — the only id that may drive this shell.\r\n pub owner: String,\r\n /// The providing shell adapter (capability surface resolves from its\r\n /// manifest, never from the perch).\r\n pub adapter_name: String,\r\n /// [`SHELL_STATUS_ONLINE`] | [`SHELL_STATUS_OFFLINE`].\r\n pub status: String,\r\n /// Owner-unique friendly label (runtime state, not a manifest field).\r\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\r\n pub alias: Option,\r\n}\r\n\r\nimpl ShellInfo {\r\n /// A freshly-minted instance record: offline until the broker launch +\r\n /// `api bind` handshake onlines it (D3b).\r\n pub fn new(owner: &str, adapter_name: &str) -> Self {\r\n ShellInfo {\r\n r#type: SHELL_TYPE.to_string(),\r\n owner: owner.to_string(),\r\n adapter_name: adapter_name.to_string(),\r\n status: SHELL_STATUS_OFFLINE.to_string(),\r\n alias: None,\r\n }\r\n }\r\n}\r\n\r\n/// Shell-instance model failures — CLI-facing, so they carry the why.\r\n#[derive(Debug)]\r\npub enum ShellError {\r\n /// The alias is already held by another of this owner's instances, or\r\n /// shadows an existing canonical id.\r\n AliasTaken(String),\r\n /// No instance of this owner matches the ref (canonical id or alias).\r\n NotFound(String),\r\n Io(std::io::Error),\r\n}\r\n\r\nimpl std::fmt::Display for ShellError {\r\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\r\n match self {\r\n ShellError::AliasTaken(a) => write!(f, \"alias already in use: {a}\"),\r\n ShellError::NotFound(r) => write!(f, \"no shell instance matches: {r}\"),\r\n ShellError::Io(e) => write!(f, \"io: {e}\"),\r\n }\r\n }\r\n}\r\n\r\nimpl From for ShellError {\r\n fn from(e: std::io::Error) -> Self {\r\n ShellError::Io(e)\r\n }\r\n}\r\n\r\n/// Read a shell perch's record. Tolerant (`None` on missing/corrupt — the\r\n/// list path skips, never panics) and shape-checked: a record whose `type`\r\n/// isn't [`SHELL_TYPE`] is not a shell perch.\r\npub fn read_shell_info(shell_perch: &Path) -> Option {\r\n let s = std::fs::read_to_string(perch::info_file_at(shell_perch)).ok()?;\r\n let info: ShellInfo = serde_json::from_str(&s).ok()?;\r\n (info.r#type == SHELL_TYPE).then_some(info)\r\n}\r\n\r\n/// Write a shell perch's record (atomic rename — the 1.2 torn-read stance).\r\n/// Creates the perch dir.\r\npub fn write_shell_info(shell_perch: &Path, info: &ShellInfo) -> std::io::Result<()> {\r\n std::fs::create_dir_all(shell_perch)?;\r\n let s = serde_json::to_string_pretty(info).expect(\"ShellInfo serializes\");\r\n atomic_write_string(&perch::info_file_at(shell_perch), &s)\r\n}\r\n\r\n/// The launched binary's recorded pid, one file per instance perch. Written by\r\n/// the launch, removed by the close — and the ONLY on-disk evidence that the\r\n/// process a record calls `online` still exists.\r\npub const SHELL_PID_FILE: &str = \"shell.pid\";\r\n\r\n/// The recorded launch pid, if the perch parks a parseable one.\r\npub fn read_shell_pid(shell_perch: &Path) -> Option {\r\n std::fs::read_to_string(shell_perch.join(SHELL_PID_FILE))\r\n .ok()?\r\n .trim()\r\n .parse()\r\n .ok()\r\n}\r\n\r\n/// `/shell.launch.json` — the birth stamp parked beside the pid at\r\n/// launch (BAROMETER W2, releases#78).\r\npub const SHELL_LAUNCH_FILE: &str = \"shell.launch.json\";\r\n\r\n/// What a launch recorded about the process it started.\r\n///\r\n/// TWO VALUES, ANSWERING TWO DIFFERENT QUESTIONS, and keeping them apart is the\r\n/// whole point of the shape:\r\n///\r\n/// - `pid_started_at` is the platform's NATIVE start-time value, used for one\r\n/// question only — the same-pid-different-process PAIR test within a single\r\n/// boot ([`crate::liveness::relay_liveness`]). It is deliberately never\r\n/// compared across boots, because it is not the same kind of number on every\r\n/// platform: on Windows it is an absolute FILETIME, but on Linux it is field\r\n/// 22 of `/proc//stat`, i.e. JIFFIES SINCE BOOT, which resets at every\r\n/// boot. A value recorded before a restart is therefore indistinguishable\r\n/// from a fresh one after it, and any cross-boot comparison of this field\r\n/// would be correct on Windows and silently wrong on Linux.\r\n/// - `launched_ms` is an ABSOLUTE wall-clock stamp (epoch-ms), used by the\r\n/// nonpersistent watcher's cross-boot freeze. Persistent restoration does not\r\n/// gate on launch age; the native birth stamp still authenticates liveness.\r\n#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]\r\npub struct ShellLaunch {\r\n /// The native start-time of the launched pid, when the platform offers one.\r\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\r\n pub pid_started_at: Option,\r\n /// Wall-clock epoch-ms at which this instance was launched.\r\n pub launched_ms: u64,\r\n}\r\n\r\n/// Record the birth stamp for a just-launched `pid`. Best-effort: a stamp that\r\n/// cannot be written must never fail the launch — a missing stamp degrades the\r\n/// probe to its pre-existing fail-toward-alive behaviour, which is the safe\r\n/// direction, while a failed launch is a real outage.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\npub fn record_shell_launch(shell_perch: &Path, pid: u32, now_ms: u64) {\r\n let launch = ShellLaunch {\r\n pid_started_at: crate::proc::process_started_at(pid),\r\n launched_ms: now_ms,\r\n };\r\n if let Ok(json) = serde_json::to_string_pretty(&launch) {\r\n let _ = atomic_write_string(&shell_perch.join(SHELL_LAUNCH_FILE), &json);\r\n }\r\n}\r\n\r\n/// Read the birth stamp, if this instance was launched by a build that parks one.\r\n/// Absent or unparseable ⇒ `None`, which every consumer treats as \"no stamp to\r\n/// compare\" rather than as a fault.\r\npub fn read_shell_launch(shell_perch: &Path) -> Option {\r\n let raw = std::fs::read_to_string(shell_perch.join(SHELL_LAUNCH_FILE)).ok()?;\r\n serde_json::from_str(&raw).ok()\r\n}\r\n\r\n/// **The** discriminant behind [`effective_status`]: is this instance's recorded\r\n/// binary *provably* gone? Narrow on purpose — true only when the perch parks a\r\n/// pid, it parses non-zero, and the process is not alive.\r\n///\r\n/// Everything else reads **alive**: an absent or unparseable pid file, and the\r\n/// `0` a broker-hosted spawn records when its backend exposed no pid\r\n/// ([`crate::proc::is_process_alive`] already reads 0 as dead, so the explicit\r\n/// filter here is what keeps a pid-less backend from being declared dead by this\r\n/// resolver). That fail-toward-alive stance mirrors `liveness.rs`'s interim\r\n/// parity: this predicate exists to catch a *corpse*, never to guess at a\r\n/// backend it cannot see.\r\n///\r\n/// Recycled pids read alive, so a heal can be **missed** but never **mis-fired**\r\n/// — the failure direction is \"stays stale\", never \"tears down a live instance\".\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn shell_pid_provably_dead(shell_perch: &Path) -> bool {\r\n let Some(pid) = read_shell_pid(shell_perch).filter(|&pid| pid != 0) else {\r\n return false;\r\n };\r\n // BAROMETER W2 (releases#78): probe pid AND birth stamp, not the pid alone.\r\n // A pid namespace resets at boot, so a corpse pid can be REUSED by an\r\n // unrelated process started after the restart; under bare-pid liveness that\r\n // reads ALIVE, the derived status reads online, and `relink` then refuses\r\n // SHELL_ALREADY_ONLINE -- the one command that recovers the instance\r\n // refusing on the very state that is wrong. The PAIR test (same pid,\r\n // different start time) is what tells a reused pid from our own process.\r\n //\r\n // The stance is unchanged where there is no stamp to compare: an instance\r\n // launched before this field existed, or a backend that exposed no start\r\n // time, still falls back to plain absence and fails toward ALIVE.\r\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n let birth = read_shell_launch(shell_perch).and_then(|l| l.pid_started_at);\r\n matches!(\r\n crate::liveness::relay_liveness(Some(pid), birth),\r\n crate::liveness::RelayLiveness::Gone\r\n )\r\n}\r\n\r\n/// A shell instance's **derived** status — the shell-side twin of\r\n/// `liveness::is_perch_alive` (REQ-HAZARD-DAEMON-HOSTED-LIVENESS gave agent\r\n/// perches exactly this; shells never got it).\r\n///\r\n/// The recorded `status` has exactly two writers — the bind handshake (→online)\r\n/// and `spt_daemon::shellhost::close_shell` (→offline) — and `close_shell` runs\r\n/// on the **link-break** path alone. A binary that dies\r\n/// abruptly (force-kill, crash, OOM) breaks no link, so nothing ever writes the\r\n/// flip and the record says `online` forever. Deriving closes that hole without\r\n/// adding a supervisor: `online` + a provably-dead pid reads\r\n/// [`SHELL_STATUS_OFFLINE`]; every other case is the recorded value verbatim.\r\n///\r\n/// Callers that must NOT derive are documented at their sites (the two status\r\n/// writers, the owner-suspend cascade whose close IS the cleanup, and the wake\r\n/// reconciler's eligibility read) — see REQ-HAZARD-SHELL-STALE-ONLINE.\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn effective_status<'a>(shell_perch: &Path, info: &'a ShellInfo) -> &'a str {\r\n if info.status == SHELL_STATUS_ONLINE && shell_pid_provably_dead(shell_perch) {\r\n return SHELL_STATUS_OFFLINE;\r\n }\r\n &info.status\r\n}\r\n\r\n/// [`effective_status`] as the predicate every gate actually asks: is this\r\n/// instance online *in fact*, not merely on paper?\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn is_shell_online(shell_perch: &Path, info: &ShellInfo) -> bool {\r\n effective_status(shell_perch, info) == SHELL_STATUS_ONLINE\r\n}\r\n\r\n/// The **parent** segment of an adapter option: the part before the first `:`\r\n/// of a `:` composite (CONTEXT.md §adapter profile). The\r\n/// canonical shell id is minted off this — never the composite — so the id (a\r\n/// perch dir name + endpoint address) stays colon-free and path-safe; the full\r\n/// composite rides only in the `adapter_name` carrier field. Mirrors\r\n/// `spt_runtime::profile::split_option`, inlined here to keep spt-store free of\r\n/// an spt-runtime dependency (the crate graph runs the other way).\r\nfn adapter_parent(option: &str) -> &str {\r\n option.split_once(':').map_or(option, |(a, _)| a)\r\n}\r\n\r\n/// Parse the `n` out of a canonical `-` dir name for `parent`.\r\nfn instance_ordinal(dir_name: &str, parent: &str) -> Option {\r\n let suffix = dir_name.strip_prefix(parent)?.strip_prefix('-')?;\r\n if suffix.is_empty() || !suffix.bytes().all(|b| b.is_ascii_digit()) {\r\n return None;\r\n }\r\n suffix.parse().ok()\r\n}\r\n\r\n/// Mint the next canonical id for `adapter` under `owner`: the **smallest\r\n/// free `n`** over existing instance dirs. Online and offline both occupy a\r\n/// slot (every non-torn-down perch counts — the same all-existing rule the\r\n/// instance cap uses); `teardown` removes the dir, so its `n` is reused.\r\n///\r\n/// `adapter` may be a `:` composite; the id is minted off the\r\n/// **parent** segment ([`adapter_parent`]) so two profiles of one adapter share\r\n/// the same `-` ordinal space (instances are the adapter's resource,\r\n/// not the profile's) and the id never carries the `:`.\r\n// [impl->REQ-EP-5]\r\n// [impl->REQ-HAZARD-ID-CHARSET]\r\npub fn mint_shell_id(owlery: &Path, owner: &str, adapter: &str) -> String {\r\n let parent = adapter_parent(adapter);\r\n let shells = perch::resolve_shells_dir_in(owlery, owner);\r\n let mut taken: Vec = std::fs::read_dir(&shells)\r\n .map(|entries| {\r\n entries\r\n .flatten()\r\n .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))\r\n .filter_map(|e| instance_ordinal(&e.file_name().to_string_lossy(), parent))\r\n .collect()\r\n })\r\n .unwrap_or_default();\r\n taken.sort_unstable();\r\n let mut n = 0u32;\r\n for t in taken {\r\n if t == n {\r\n n += 1;\r\n } else if t > n {\r\n break;\r\n }\r\n }\r\n format!(\"{parent}-{n}\")\r\n}\r\n\r\n/// Every shell instance of `owner`: `(canonical_id, record)`, sorted by id\r\n/// for a stable order. Tolerant — a dir without a valid [`ShellInfo`] is\r\n/// skipped (it still *occupies* its mint slot; it just doesn't list).\r\n// [impl->REQ-EP-5]\r\npub fn list_shells(owlery: &Path, owner: &str) -> Vec<(String, ShellInfo)> {\r\n let shells = perch::resolve_shells_dir_in(owlery, owner);\r\n let Ok(entries) = std::fs::read_dir(&shells) else {\r\n return Vec::new();\r\n };\r\n let mut out: Vec<(String, ShellInfo)> = entries\r\n .flatten()\r\n .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))\r\n .filter_map(|e| {\r\n let id = e.file_name().to_string_lossy().into_owned();\r\n read_shell_info(&e.path()).map(|info| (id, info))\r\n })\r\n .collect();\r\n out.sort_by(|a, b| a.0.cmp(&b.0));\r\n out\r\n}\r\n\r\n/// Resolve a shell ref — canonical id or alias — to `(canonical_id, record)`.\r\n/// **Canonical-first**: an alias can never shadow a canonical id (spawn/rename\r\n/// refuse minting such an alias, and resolution checks canonical before alias\r\n/// as defense in depth). Aliases are owner-unique, so at most one matches.\r\n// [impl->REQ-EP-5]\r\npub fn resolve_shell_ref(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_ref: &str,\r\n) -> Option<(String, ShellInfo)> {\r\n let direct = perch::resolve_shell_perch_path_in(owlery, owner, shell_ref);\r\n if let Some(info) = read_shell_info(&direct) {\r\n return Some((shell_ref.to_string(), info));\r\n }\r\n list_shells(owlery, owner)\r\n .into_iter()\r\n .find(|(_, info)| info.alias.as_deref() == Some(shell_ref))\r\n}\r\n\r\n/// Whether `alias` is free for `owner`: held by no instance's alias and not\r\n/// shadowing any existing canonical id.\r\nfn alias_free(owlery: &Path, owner: &str, alias: &str) -> bool {\r\n resolve_shell_ref(owlery, owner, alias).is_none()\r\n}\r\n\r\n/// Mint + record a new instance of `adapter` for `owner` (the storage half of\r\n/// `spt shell spawn` — adapter-registration and consent gates are the\r","truncated":true,"truncatedBy":"lines","totalLines":726,"totalBytes":16529,"outputLines":353,"outputBytes":16529,"lastLinePartial":false,"firstLineExceedsLimit":false},"totalLines":726,"displayContent":{"text":"//! Shell-instance perch records (M5-D3a — CONTEXT §Shell model,\r\n//! `docs/STORAGE.md` §Shells in the layout).\r\n//!\r\n//! A shell perch is **not** an agent perch: its `info.json` carries exactly\r\n//! `type=Shell, owner, adapter_name, status, alias?` — a dedicated\r\n//! [`ShellInfo`] shape, deliberately distinct from [`crate::info::InfoJson`],\r\n//! so the agent-perch readers (liveness, registry stale-clean, the consent\r\n//! MRA scan) stay blind to shells by construction. Capabilities are **never**\r\n//! duplicated here — they resolve from the shell adapter manifest by\r\n//! `adapter_name`.\r\n//!\r\n//! **Identity model (REQ-EP-5):** `spt shell spawn` *mints* a new instance —\r\n//! the immutable canonical id `-` ([`mint_shell_id`]: smallest\r\n//! free `n` over **existing** instance dirs; online and offline both occupy,\r\n//! `teardown` frees the slot). The optional **alias** is a per-instance,\r\n//! owner-unique display/address overlay set at spawn or by `shell rename` —\r\n//! interchangeable with the canonical id for addressing\r\n//! ([`resolve_shell_ref`], canonical-first), never obscuring `adapter_name`.\r\n//!\r\n//! Torn-read stance mirrors `info.rs` (KNOWN-HAZARDS 1.2): writers go through\r\n//! the atomic rename; readers tolerate failure and return `None`.\r\n// [impl->REQ-EP-5]\r\n\r\nuse serde::{Deserialize, Serialize};\r\nuse std::path::Path;\r\n\r\nuse crate::atomic::atomic_write_string;\r\nuse crate::perch;\r\n\r\n/// `status` value: the shell binary is linked and running.\r\npub const SHELL_STATUS_ONLINE: &str = \"online\";\r\n/// `status` value: the perch exists, no binary linked (re-linkable if the\r\n/// adapter is `persistent`; the spawn-time initial state until D3b binds).\r\npub const SHELL_STATUS_OFFLINE: &str = \"offline\";\r\n/// The fixed `type` tag on every shell perch record.\r\npub const SHELL_TYPE: &str = \"Shell\";\r\n\r\n/// On-disk shape of a shell perch's `info.json` — the full field set, by\r\n/// contract (STORAGE.md: \"carries only `type=Shell`, `owner`, `adapter_name`,\r\n/// `status`, and an optional `alias`\").\r\n// [impl->REQ-SHELL-1]\r\n#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\r\npub struct ShellInfo {\r\n /// Always [`SHELL_TYPE`] — readers refuse anything else.\r\n pub r#type: String,\r\n /// The owning agent endpoint id — the only id that may drive this shell.\r\n pub owner: String,\r\n /// The providing shell adapter (capability surface resolves from its\r\n /// manifest, never from the perch).\r\n pub adapter_name: String,\r\n /// [`SHELL_STATUS_ONLINE`] | [`SHELL_STATUS_OFFLINE`].\r\n pub status: String,\r\n /// Owner-unique friendly label (runtime state, not a manifest field).\r\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\r\n pub alias: Option,\r\n}\r\n\r\nimpl ShellInfo {\r\n /// A freshly-minted instance record: offline until the broker launch +\r\n /// `api bind` handshake onlines it (D3b).\r\n pub fn new(owner: &str, adapter_name: &str) -> Self {\r\n ShellInfo {\r\n r#type: SHELL_TYPE.to_string(),\r\n owner: owner.to_string(),\r\n adapter_name: adapter_name.to_string(),\r\n status: SHELL_STATUS_OFFLINE.to_string(),\r\n alias: None,\r\n }\r\n }\r\n}\r\n\r\n/// Shell-instance model failures — CLI-facing, so they carry the why.\r\n#[derive(Debug)]\r\npub enum ShellError {\r\n /// The alias is already held by another of this owner's instances, or\r\n /// shadows an existing canonical id.\r\n AliasTaken(String),\r\n /// No instance of this owner matches the ref (canonical id or alias).\r\n NotFound(String),\r\n Io(std::io::Error),\r\n}\r\n\r\nimpl std::fmt::Display for ShellError {\r\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\r\n match self {\r\n ShellError::AliasTaken(a) => write!(f, \"alias already in use: {a}\"),\r\n ShellError::NotFound(r) => write!(f, \"no shell instance matches: {r}\"),\r\n ShellError::Io(e) => write!(f, \"io: {e}\"),\r\n }\r\n }\r\n}\r\n\r\nimpl From for ShellError {\r\n fn from(e: std::io::Error) -> Self {\r\n ShellError::Io(e)\r\n }\r\n}\r\n\r\n/// Read a shell perch's record. Tolerant (`None` on missing/corrupt — the\r\n/// list path skips, never panics) and shape-checked: a record whose `type`\r\n/// isn't [`SHELL_TYPE`] is not a shell perch.\r\npub fn read_shell_info(shell_perch: &Path) -> Option {\r\n let s = std::fs::read_to_string(perch::info_file_at(shell_perch)).ok()?;\r\n let info: ShellInfo = serde_json::from_str(&s).ok()?;\r\n (info.r#type == SHELL_TYPE).then_some(info)\r\n}\r\n\r\n/// Write a shell perch's record (atomic rename — the 1.2 torn-read stance).\r\n/// Creates the perch dir.\r\npub fn write_shell_info(shell_perch: &Path, info: &ShellInfo) -> std::io::Result<()> {\r\n std::fs::create_dir_all(shell_perch)?;\r\n let s = serde_json::to_string_pretty(info).expect(\"ShellInfo serializes\");\r\n atomic_write_string(&perch::info_file_at(shell_perch), &s)\r\n}\r\n\r\n/// The launched binary's recorded pid, one file per instance perch. Written by\r\n/// the launch, removed by the close — and the ONLY on-disk evidence that the\r\n/// process a record calls `online` still exists.\r\npub const SHELL_PID_FILE: &str = \"shell.pid\";\r\n\r\n/// The recorded launch pid, if the perch parks a parseable one.\r\npub fn read_shell_pid(shell_perch: &Path) -> Option {\r\n std::fs::read_to_string(shell_perch.join(SHELL_PID_FILE))\r\n .ok()?\r\n .trim()\r\n .parse()\r\n .ok()\r\n}\r\n\r\n/// `/shell.launch.json` — the birth stamp parked beside the pid at\r\n/// launch (BAROMETER W2, releases#78).\r\npub const SHELL_LAUNCH_FILE: &str = \"shell.launch.json\";\r\n\r\n/// What a launch recorded about the process it started.\r\n///\r\n/// TWO VALUES, ANSWERING TWO DIFFERENT QUESTIONS, and keeping them apart is the\r\n/// whole point of the shape:\r\n///\r\n/// - `pid_started_at` is the platform's NATIVE start-time value, used for one\r\n/// question only — the same-pid-different-process PAIR test within a single\r\n/// boot ([`crate::liveness::relay_liveness`]). It is deliberately never\r\n/// compared across boots, because it is not the same kind of number on every\r\n/// platform: on Windows it is an absolute FILETIME, but on Linux it is field\r\n/// 22 of `/proc//stat`, i.e. JIFFIES SINCE BOOT, which resets at every\r\n/// boot. A value recorded before a restart is therefore indistinguishable\r\n/// from a fresh one after it, and any cross-boot comparison of this field\r\n/// would be correct on Windows and silently wrong on Linux.\r\n/// - `launched_ms` is an ABSOLUTE wall-clock stamp (epoch-ms), used by the\r\n/// nonpersistent watcher's cross-boot freeze. Persistent restoration does not\r\n/// gate on launch age; the native birth stamp still authenticates liveness.\r\n#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]\r\npub struct ShellLaunch {\r\n /// The native start-time of the launched pid, when the platform offers one.\r\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\r\n pub pid_started_at: Option,\r\n /// Wall-clock epoch-ms at which this instance was launched.\r\n pub launched_ms: u64,\r\n}\r\n\r\n/// Record the birth stamp for a just-launched `pid`. Best-effort: a stamp that\r\n/// cannot be written must never fail the launch — a missing stamp degrades the\r\n/// probe to its pre-existing fail-toward-alive behaviour, which is the safe\r\n/// direction, while a failed launch is a real outage.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\npub fn record_shell_launch(shell_perch: &Path, pid: u32, now_ms: u64) {\r\n let launch = ShellLaunch {\r\n pid_started_at: crate::proc::process_started_at(pid),\r\n launched_ms: now_ms,\r\n };\r\n if let Ok(json) = serde_json::to_string_pretty(&launch) {\r\n let _ = atomic_write_string(&shell_perch.join(SHELL_LAUNCH_FILE), &json);\r\n }\r\n}\r\n\r\n/// Read the birth stamp, if this instance was launched by a build that parks one.\r\n/// Absent or unparseable ⇒ `None`, which every consumer treats as \"no stamp to\r\n/// compare\" rather than as a fault.\r\npub fn read_shell_launch(shell_perch: &Path) -> Option {\r\n let raw = std::fs::read_to_string(shell_perch.join(SHELL_LAUNCH_FILE)).ok()?;\r\n serde_json::from_str(&raw).ok()\r\n}\r\n\r\n/// **The** discriminant behind [`effective_status`]: is this instance's recorded\r\n/// binary *provably* gone? Narrow on purpose — true only when the perch parks a\r\n/// pid, it parses non-zero, and the process is not alive.\r\n///\r\n/// Everything else reads **alive**: an absent or unparseable pid file, and the\r\n/// `0` a broker-hosted spawn records when its backend exposed no pid\r\n/// ([`crate::proc::is_process_alive`] already reads 0 as dead, so the explicit\r\n/// filter here is what keeps a pid-less backend from being declared dead by this\r\n/// resolver). That fail-toward-alive stance mirrors `liveness.rs`'s interim\r\n/// parity: this predicate exists to catch a *corpse*, never to guess at a\r\n/// backend it cannot see.\r\n///\r\n/// Recycled pids read alive, so a heal can be **missed** but never **mis-fired**\r\n/// — the failure direction is \"stays stale\", never \"tears down a live instance\".\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn shell_pid_provably_dead(shell_perch: &Path) -> bool {\r\n let Some(pid) = read_shell_pid(shell_perch).filter(|&pid| pid != 0) else {\r\n return false;\r\n };\r\n // BAROMETER W2 (releases#78): probe pid AND birth stamp, not the pid alone.\r\n // A pid namespace resets at boot, so a corpse pid can be REUSED by an\r\n // unrelated process started after the restart; under bare-pid liveness that\r\n // reads ALIVE, the derived status reads online, and `relink` then refuses\r\n // SHELL_ALREADY_ONLINE -- the one command that recovers the instance\r\n // refusing on the very state that is wrong. The PAIR test (same pid,\r\n // different start time) is what tells a reused pid from our own process.\r\n //\r\n // The stance is unchanged where there is no stamp to compare: an instance\r\n // launched before this field existed, or a backend that exposed no start\r\n // time, still falls back to plain absence and fails toward ALIVE.\r\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n let birth = read_shell_launch(shell_perch).and_then(|l| l.pid_started_at);\r\n matches!(\r\n crate::liveness::relay_liveness(Some(pid), birth),\r\n crate::liveness::RelayLiveness::Gone\r\n )\r\n}\r\n\r\n/// A shell instance's **derived** status — the shell-side twin of\r\n/// `liveness::is_perch_alive` (REQ-HAZARD-DAEMON-HOSTED-LIVENESS gave agent\r\n/// perches exactly this; shells never got it).\r\n///\r\n/// The recorded `status` has exactly two writers — the bind handshake (→online)\r\n/// and `spt_daemon::shellhost::close_shell` (→offline) — and `close_shell` runs\r\n/// on the **link-break** path alone. A binary that dies\r\n/// abruptly (force-kill, crash, OOM) breaks no link, so nothing ever writes the\r\n/// flip and the record says `online` forever. Deriving closes that hole without\r\n/// adding a supervisor: `online` + a provably-dead pid reads\r\n/// [`SHELL_STATUS_OFFLINE`]; every other case is the recorded value verbatim.\r\n///\r\n/// Callers that must NOT derive are documented at their sites (the two status\r\n/// writers, the owner-suspend cascade whose close IS the cleanup, and the wake\r\n/// reconciler's eligibility read) — see REQ-HAZARD-SHELL-STALE-ONLINE.\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn effective_status<'a>(shell_perch: &Path, info: &'a ShellInfo) -> &'a str {\r\n if info.status == SHELL_STATUS_ONLINE && shell_pid_provably_dead(shell_perch) {\r\n return SHELL_STATUS_OFFLINE;\r\n }\r\n &info.status\r\n}\r\n\r\n/// [`effective_status`] as the predicate every gate actually asks: is this\r\n/// instance online *in fact*, not merely on paper?\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn is_shell_online(shell_perch: &Path, info: &ShellInfo) -> bool {\r\n effective_status(shell_perch, info) == SHELL_STATUS_ONLINE\r\n}\r\n\r\n/// The **parent** segment of an adapter option: the part before the first `:`\r\n/// of a `:` composite (CONTEXT.md §adapter profile). The\r\n/// canonical shell id is minted off this — never the composite — so the id (a\r\n/// perch dir name + endpoint address) stays colon-free and path-safe; the full\r\n/// composite rides only in the `adapter_name` carrier field. Mirrors\r\n/// `spt_runtime::profile::split_option`, inlined here to keep spt-store free of\r\n/// an spt-runtime dependency (the crate graph runs the other way).\r\nfn adapter_parent(option: &str) -> &str {\r\n option.split_once(':').map_or(option, |(a, _)| a)\r\n}\r\n\r\n/// Parse the `n` out of a canonical `-` dir name for `parent`.\r\nfn instance_ordinal(dir_name: &str, parent: &str) -> Option {\r\n let suffix = dir_name.strip_prefix(parent)?.strip_prefix('-')?;\r\n if suffix.is_empty() || !suffix.bytes().all(|b| b.is_ascii_digit()) {\r\n return None;\r\n }\r\n suffix.parse().ok()\r\n}\r\n\r\n/// Mint the next canonical id for `adapter` under `owner`: the **smallest\r\n/// free `n`** over existing instance dirs. Online and offline both occupy a\r\n/// slot (every non-torn-down perch counts — the same all-existing rule the\r\n/// instance cap uses); `teardown` removes the dir, so its `n` is reused.\r\n///\r\n/// `adapter` may be a `:` composite; the id is minted off the\r\n/// **parent** segment ([`adapter_parent`]) so two profiles of one adapter share\r\n/// the same `-` ordinal space (instances are the adapter's resource,\r\n/// not the profile's) and the id never carries the `:`.\r\n// [impl->REQ-EP-5]\r\n// [impl->REQ-HAZARD-ID-CHARSET]\r\npub fn mint_shell_id(owlery: &Path, owner: &str, adapter: &str) -> String {\r\n let parent = adapter_parent(adapter);\r\n let shells = perch::resolve_shells_dir_in(owlery, owner);\r\n let mut taken: Vec = std::fs::read_dir(&shells)\r\n .map(|entries| {\r\n entries\r\n .flatten()\r\n .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))\r\n .filter_map(|e| instance_ordinal(&e.file_name().to_string_lossy(), parent))\r\n .collect()\r\n })\r\n .unwrap_or_default();\r\n taken.sort_unstable();\r\n let mut n = 0u32;\r\n for t in taken {\r\n if t == n {\r\n n += 1;\r\n } else if t > n {\r\n break;\r\n }\r\n }\r\n format!(\"{parent}-{n}\")\r\n}\r\n\r\n/// Every shell instance of `owner`: `(canonical_id, record)`, sorted by id\r\n/// for a stable order. Tolerant — a dir without a valid [`ShellInfo`] is\r\n/// skipped (it still *occupies* its mint slot; it just doesn't list).\r\n// [impl->REQ-EP-5]\r\npub fn list_shells(owlery: &Path, owner: &str) -> Vec<(String, ShellInfo)> {\r\n let shells = perch::resolve_shells_dir_in(owlery, owner);\r\n let Ok(entries) = std::fs::read_dir(&shells) else {\r\n return Vec::new();\r\n };\r\n let mut out: Vec<(String, ShellInfo)> = entries\r\n .flatten()\r\n .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))\r\n .filter_map(|e| {\r\n let id = e.file_name().to_string_lossy().into_owned();\r\n read_shell_info(&e.path()).map(|info| (id, info))\r\n })\r\n .collect();\r\n out.sort_by(|a, b| a.0.cmp(&b.0));\r\n out\r\n}\r\n\r\n/// Resolve a shell ref — canonical id or alias — to `(canonical_id, record)`.\r\n/// **Canonical-first**: an alias can never shadow a canonical id (spawn/rename\r\n/// refuse minting such an alias, and resolution checks canonical before alias\r\n/// as defense in depth). Aliases are owner-unique, so at most one matches.\r\n// [impl->REQ-EP-5]\r\npub fn resolve_shell_ref(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_ref: &str,\r\n) -> Option<(String, ShellInfo)> {\r\n let direct = perch::resolve_shell_perch_path_in(owlery, owner, shell_ref);\r\n if let Some(info) = read_shell_info(&direct) {\r\n return Some((shell_ref.to_string(), info));\r\n }\r\n list_shells(owlery, owner)\r\n .into_iter()\r\n .find(|(_, info)| info.alias.as_deref() == Some(shell_ref))\r\n}\r\n\r\n/// Whether `alias` is free for `owner`: held by no instance's alias and not\r\n/// shadowing any existing canonical id.\r\nfn alias_free(owlery: &Path, owner: &str, alias: &str) -> bool {\r\n resolve_shell_ref(owlery, owner, alias).is_none()\r\n}\r\n\r\n/// Mint + record a new instance of `adapter` for `owner` (the storage half of\r\n/// `spt shell spawn` — adapter-registration and consent gates are the\r","startLine":1,"lineNumbers":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299,300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353]},"fileSize":33627,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\crates\\spt-store\\src\\shellinfo.rs"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":726,"totalBytes":16529,"outputLines":353,"outputBytes":16529,"shownRange":{"start":1,"end":353},"nextOffset":354}}},"isError":false,"timestamp":1789001136963}}
{"type":"message","id":"ab9d17cd","parentId":"ac0f6d03","timestamp":"2026-09-10T00:45:36.968Z","message":{"role":"toolResult","toolCallId":"call_7CFTl5wDfbMpoAe7PxbOIkfS|fc_077f3569365e313d016aa1fdb0c07487d1985acac801d13058","toolName":"read","content":[{"type":"text","text":"/// supervision thread.\n/// - **not offline (onlined / torn down / deregistered) + live watcher** ⇒\n/// stop it (flag + kill).\n///\n/// Runs at daemon boot and every tick — lifecycle flips happen in CLI-process\n/// library code, so the *reconciler* holds the invariant, not the flipping\n/// caller; a flip is at most one tick stale.\n// [impl->REQ-SHELL-2]\n/// Heal every local shell record whose `online` is a lie — leg (a) of\n/// releases#78.\n///\n/// `effective_status` already computes this flip on EVERY read and never writes\n/// it down, so the record and the display disagree by design: the display side\n/// derives and looks clean, while the wake cascade reads the RECORDED field and\n/// skips its relaunch because that field still says online. A machine death\n/// breaks no link, so `close_shell` never runs and nothing else ever corrects it.\n///\n/// THE WRITE IS GUARDED ON AN ACTUAL CHANGE. This runs every reconcile cycle\n/// (5s), and a heal that rewrote the record each time would be a continuous\n/// stream of identical writes over a rarely-changing condition — noise on disk,\n/// and a record whose mtime stops meaning \"something happened\".\n///\n/// It DERIVES deliberately, unlike the watcher-eligibility read below it: this\n/// is not an eligibility decision that could relaunch a binary, it is a\n/// correction of a field that is already wrong. Nothing is started here.\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\nfn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n if info.status != SHELL_STATUS_ONLINE {\n continue;\n }\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\n let truth = shellinfo::effective_status(&perch, &info);\n if truth == info.status {\n continue; // the record already tells the truth — write nothing\n }\n let mut healed = info.clone();\n healed.status = truth.to_string();\n if shellinfo::write_shell_info(&perch, &healed).is_ok() {\n // [impl->REQ-SHELL-HEAL-ENUMERATION]\n let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\n }\n }\n }\n}\n\n/// Slack absorbed when asking whether a launch predates the boot instant.\n///\n/// The boot instant is DERIVED, not read from a ledger — on Windows it is\n/// now-minus-uptime, which drifts by however long the two calls take and by\n/// whatever the clock did since — so a process launched in the first moments of\n/// a boot can compute as very slightly older than the boot itself. Without slack\n/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\n/// could be armed after a same-boot death. Ten seconds is far wider than plausible\n/// derivation error and far narrower than the gap this discriminant exists to\n/// detect (a previous boot is minutes to days back).\npub const BOOT_RESTORE_SLACK_MS: u64 = 10_000;\n\n/// Whether a nonpersistent shell's recorded launch predates the current boot.\n/// This preserves its same-boot force-kill freeze; persistent shells do not use\n/// launch age as eligibility (releases#287).\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\npub fn launch_predates_boot(launched_ms: u64, boot_ms: u64, slack_ms: u64) -> bool {\n launched_ms.saturating_add(slack_ms) < boot_ms\n}\n\n/// Watchers require an offline instance with no live launch awaiting bind.\n/// Persistent shells bypass the corpse-age freeze (releases#287); nonpersistent\n/// corpses still need a dated pre-boot launch. Missing dates fail closed only\n/// for that nonpersistent freeze, never for persistent restoration.\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\nfn watcher_eligible(\n perch: &Path,\n info: &shellinfo::ShellInfo,\n persistent: bool,\n boot_ms: Option,\n) -> bool {\n if info.status != SHELL_STATUS_OFFLINE {\n return false;\n }\n if crate::shellhost::live_launch_winner(perch).is_some() {\n return false; // binding: the shell binary and watcher must not overlap\n }\n if persistent || !shellinfo::shell_pid_provably_dead(perch) {\n return true; // persistence overrides the freeze; clean closes need no age\n }\n let (Some(boot_ms), Some(launch)) = (boot_ms, shellinfo::read_shell_launch(perch)) else {\n return false;\n };\n launch_predates_boot(launch.launched_ms, boot_ms, BOOT_RESTORE_SLACK_MS)\n}\n\n/// Which trigger asked for a restore.\n///\n/// The two triggers run the SAME per-owner body and differ only in what woke\n/// them, so each NAMES ITSELF in its event line rather than sharing one: the\n/// field diagnosis of releases#228 was a COUNT of these events in a rotated\n/// daemon log, and a shared name would have left that reading unable to say\n/// which trigger had fired -- the one thing it needed to know.\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\npub enum RestoreTrigger {\n /// The once-per-daemon-generation boot sweep (releases#78 leg (b)).\n Boot,\n /// An owner endpoint that came online since the last reconcile pass\n /// (releases#228).\n OwnerOnline,\n}\n\nimpl RestoreTrigger {\n fn restored_event(self) -> &'static str {\n match self {\n RestoreTrigger::Boot => \"SHELL_BOOT_RESTORED\",\n RestoreTrigger::OwnerOnline => \"SHELL_OWNER_ONLINE_RESTORED\",\n }\n }\n\n fn failed_event(self) -> &'static str {\n match self {\n RestoreTrigger::Boot => \"SHELL_BOOT_RESTORE_FAIL\",\n RestoreTrigger::OwnerOnline => \"SHELL_OWNER_ONLINE_RESTORE_FAIL\",\n }\n }\n}\n\n/// ONE owner's slice of the persistent-shell restore decision -- the body BOTH\n/// triggers run.\n///\n/// Both triggers restore every persistent instance whose owner is online and\n/// whose binary is down in fact. Birth-safe liveness excludes a live launch\n/// awaiting bind as well as an already-online shell. Machine boot and launch\n/// age are irrelevant, including missing stamps (releases#287 operator ruling).\n///\n/// `set` is the daemon's live watcher set, and it is `None` at boot ON PURPOSE:\n/// the sweep runs before the reconcile loop's first tick, so no watcher can yet\n/// exist for the instance it is about to launch. The owner-online trigger runs\n/// MID-generation, where one can -- the reconcile start side arms watchers with\n/// no owner-online conjunct of its own -- so it passes the set and the watcher is\n/// stopped before the binary rises, which is the same online/offline mutual\n/// exclusivity `REQ-SHELL-2` holds everywhere else.\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\nfn restore_persistent_shells_of_owner(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n owner: &str,\n trigger: RestoreTrigger,\n set: Option<&Arc>,\n restored: &mut Vec,\n) {\n let owner_perch = spt_store::perch::resolve_perch_path_in(owlery, owner, ParentHint::Infer);\n if !spt_store::liveness::is_perch_alive(&owner_perch) {\n return; // an offline owner is owed no persistent shell\n }\n for (shell_id, info) in shellinfo::list_shells(owlery, owner) {\n let Some(shell) =\n shell_section_of(registered, adapters_dir, &info.adapter_name).filter(|s| s.persistent)\n else {\n continue;\n };\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &shell_id);\n if shellinfo::is_shell_online(&perch, &info)\n || crate::shellhost::live_launch_winner(&perch).is_some()\n {\n continue; // already online or binding in fact\n }\n // Mutual exclusivity, the online side: the watcher dies before the binary\n // rises. `launch_shell` already kills the waker CHILD, but the supervising\n // thread would read that as a crash-exit and respawn it under the shell we\n // are starting; only the set can retire the thread. [impl->REQ-SHELL-2]\n if let Some(set) = set {\n set.stop_watcher(owlery, owner, &shell_id);\n }\n let install_dir = crate::shellhost::shell_install_dir(adapters_dir, &info.adapter_name);\n match crate::shellhost::launch_shell(\n owlery,\n owner,\n &shell_id,\n &info.adapter_name,\n install_dir.as_deref(),\n &shell,\n ) {\n Ok(_) => {\n eprintln!(\"{}:{owner}/{shell_id}\", trigger.restored_event());\n restored.push(format!(\"{owner}/{shell_id}\"));\n }\n Err(e) => eprintln!(\"{}:{owner}/{shell_id}: {e}\", trigger.failed_event()),\n }\n }\n}\n\n/// The once-per-daemon-generation boot sweep: bring back the `persistent` shells\n/// a node restart stranded (leg (b) of releases#78).\n///\n/// Runs ONCE per daemon generation. It is not the ONLY restore trigger -- an owner\n/// endpoint that comes online after this sweep is covered by\n/// [`restore_persistent_shells_on_owner_online`] (releases#228), running the same\n/// [`restore_persistent_shells_of_owner`] body -- but it is the one that needs no\n/// trigger at all, since a node restart is what strands the shells to begin with.\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\npub fn restore_persistent_shells_at_boot(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n) -> Vec {\n let mut restored = Vec::new();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n restore_persistent_shells_of_owner(\n owlery,\n registered,\n adapters_dir,\n &owner,\n RestoreTrigger::Boot,\n None,\n &mut restored,\n );\n }\n restored\n}\n\n/// Per-owner online state carried ACROSS reconcile passes, so the restore below\n/// can be EDGE-triggered on an owner's offline->online transition.\n///\n/// An edge bounds a failing launch to one attempt per owner-online event,\n/// rather than retrying every reconcile tick while the owner remains online.\n/// A successful launch is protected by birth-safe liveness even before bind.\n#[derive(Debug, Default)]\npub struct OwnerOnlineEdge {\n /// Owner id -> online as of the last pass. An owner that disappears from the\n /// perch listing drops out, so a later reappearance reads as a transition.\n seen: HashMap,\n}\n\nimpl OwnerOnlineEdge {\n pub fn new() -> Self {\n Self::default()\n }\n\n /// Observe every owner and return those that went offline->online since the\n /// last observation. An owner seen for the FIRST time counts as a transition\n /// when it is online: it was not online at the last pass, because it was not\n /// there at all.\n fn transitions(&mut self, owlery: &Path) -> Vec {\n let mut fired = Vec::new();\n let mut now = HashMap::new();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n let perch = spt_store::perch::resolve_perch_path_in(owlery, &owner, ParentHint::Infer);\n let online = spt_store::liveness::is_perch_alive(&perch);\n if online && !self.seen.get(&owner).copied().unwrap_or(false) {\n fired.push(owner.clone());\n }\n now.insert(owner, online);\n }\n self.seen = now;\n fired\n }\n\n /// Observe without firing -- the initial state the first tick compares against.\n ///\n /// Called BEFORE the boot sweep, and the ORDER is the safe direction rather\n /// than an accident. Seeded AFTER the sweep, an owner that comes online in the\n /// window between the two reads as already-online and never fires an edge --\n /// precisely the miss releases#228 is about. Seeded before, the worst case is a\n /// second attempt at an instance the sweep already restored, which the\n /// down-in-fact arm refuses.\n pub fn seed(&mut self, owlery: &Path) {\n let _ = self.transitions(owlery);\n }\n}\n\n/// Restore the `persistent` shells of every owner that came online since the last\n/// pass -- the steady-state half of the contract's promise (releases#228).\n///\n/// Daemons boot before endpoints do, so the boot sweep correctly skips an owner\n/// that is not up yet and, being once-per-generation, never revisits it; bringup\n/// from offline emits no rest edge either, so the ADR-0048 cascade does not cover\n/// it. Both triggers use the same down-in-fact decision, without a machine-boot\n/// or launch-stamp eligibility gate (releases#287).\n// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\npub fn restore_persistent_shells_on_owner_online(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n edge: &mut OwnerOnlineEdge,\n set: &Arc,\n) -> Vec {\n let owners = edge.transitions(owlery);\n if owners.is_empty() {\n return Vec::new();\n }\n let mut restored = Vec::new();\n for owner in owners {\n restore_persistent_shells_of_owner(\n owlery,\n registered,\n adapters_dir,\n &owner,\n RestoreTrigger::OwnerOnline,\n Some(set),\n &mut restored,\n );\n }\n restored\n}\n\npub fn reconcile_once(\n owlery: &Path,\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n set: &Arc,\n params: &WakeParams,\n) {\n // Leg (a) first, every cycle: the record must stop lying before anything reads\n // it below. Ordering matters -- the watcher-eligibility read further down asks\n // the RECORDED field, so a heal that ran after it would leave this cycle acting\n // on the stale value it just corrected.\n heal_stale_online_records(owlery, &mut std::io::stderr().lock());\n\n // Stop side first: watchers whose instance is gone or no longer eligible.\n let live: Vec<(String, String)> = {\n let mut map = set.inner.lock().unwrap_or_else(|p| p.into_inner());\n map.retain(|_, h| !h.thread.is_finished());\n map.keys().cloned().collect()\n };\n for (owner, shell_id) in live {\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\n let still_eligible = shellinfo::read_shell_info(&perch)\n .map(|i| i.status == SHELL_STATUS_OFFLINE)\n .unwrap_or(false);\n if !still_eligible {\n set.stop_watcher(owlery, &owner, &shell_id);\n }\n }\n\n // Start side: every ELIGIBLE instance with a wake_command and headroom.\n //\n // Persistent instances bypass the force-kill freeze; only nonpersistent\n // corpses need the pre-boot discriminant (releases#287).\n let boot_ms = spt_store::proc::boot_instant_ms();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n if set.contains(&owner, &shell_id) {\n continue;\n }\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\n let Some(shell) = shell_section_of(registered, adapters_dir, &info.adapter_name) else {\n continue; // deregistered adapter: nothing to run\n };\n if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\n continue;\n }\n let Some(wake_command) = shell.wake_command.as_deref() else {\n continue;\n };\n if perch.join(WAKER_GAVE_UP_FILE).exists() {\n continue; // crash-latched until the next shell activity\n }\n // Adopt cleanly: a dead daemon's watcher must not double-run.\n kill_waker_at(&perch);\n // [impl->REQ-INSTALL-11] threading only: this loop already holds the\n // registered set the record's `source_dir` lives in.\n let install_dir = crate::shellhost::shell_install_dir(adapters_dir, &info.adapter_name);\n let tokens = match fill_wake_command(\n &shell_id,\n &info.adapter_name,\n install_dir.as_deref(),\n wake_command,\n ) {\n Ok(t) => t,\n Err(e) => {\n spt_proto::emit_line_err!(\"WAKER_TEMPLATE:{owner}/{shell_id}: {e}\");\n continue;\n }\n };\n let stop = Arc::new(AtomicBool::new(false));\n let handle = {\n let stop = Arc::clone(&stop);\n let owlery = owlery.to_path_buf();\n let owner = owner.clone();\n let shell_id = shell_id.clone();\n let adapter_name = info.adapter_name.clone();\n let params = *params;\n std::thread::spawn(move || {\n watcher_run(&owlery, &owner, &shell_id, &tokens, ¶ms, &stop, || {\n resolve_wake(&owlery, &owner, &shell_id, &adapter_name, &shell)\n });\n })\n };\n set.insert(\n &owner,\n &shell_id,\n WatcherHandle {\n stop,\n thread: handle,\n },\n );\n }\n }\n}\n\n/// The reconcile cadence (ms): lifecycle flips land in CLI processes, so the\n/// daemon's loop is the invariant holder — a flip is at most one tick stale.\npub const RECONCILE_INTERVAL_MS: u64 = 5_000;\n\n/// Spawn the daemon's wake host: one thread sweeping [`reconcile_once`] at\n/// boot and every [`RECONCILE_INTERVAL_MS`] until `stop`. The registered set\n/// is re-read each sweep (adapter add/remove lands between ticks).\n// [impl->REQ-SHELL-2]\npub fn spawn_wake_host(stop: Arc) -> JoinHandle<()> {\n std::thread::spawn(move || {\n let set = Arc::new(WakeSet::new());\n let params = WakeParams::default();\n let mut owner_edge = OwnerOnlineEdge::new();\n // Once per daemon generation, restore down persistent shells of owners\n // already online. Owners arriving later are covered by the edge below.\n // Neither trigger gates persistence on machine boot or launch age.\n {\n let owlery = spt_store::perch::owlery_dir();\n let adapters_dir = spt_store::perch::adapters_dir();\n let registered = spt_runtime::registry::registered(&adapters_dir);\n // Seeded BEFORE the sweep: an owner that comes online between the two\n // must read as a transition on the first tick, not as already-online.\n owner_edge.seed(&owlery);\n restore_persistent_shells_at_boot(&owlery, ®istered, &adapters_dir);\n }\n while !stop.load(Ordering::SeqCst) {\n let owlery = spt_store::perch::owlery_dir();\n let adapters_dir = spt_store::perch::adapters_dir();\n let registered = spt_runtime::registry::registered(&adapters_dir);\n // Restore BEFORE reconciling, the same order the boot pass runs in: a\n // restored instance is not watcher material, and reconcile's start side\n // would otherwise arm a watcher for the shell we are about to launch.\n restore_persistent_shells_on_owner_online(\n &owlery,\n ®istered,\n &adapters_dir,\n &mut owner_edge,\n &set,\n );\n reconcile_once(&owlery, ®istered, &adapters_dir, &set, ¶ms);\n // Sleep in slices so a stop lands promptly.\n let mut left = RECONCILE_INTERVAL_MS;\n while left > 0 && !stop.load(Ordering::SeqCst) {\n let step = left.min(100);\n std::thread::sleep(Duration::from_millis(step));\n left -= step;\n }\n }\n })\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use spt_store::shellinfo::{spawn_record, SHELL_STATUS_ONLINE};\n\n /// BACKSTOP for the converge-waits below — a ceiling on an observable, not\n /// a budget any run is expected to consume (the healthy path exits in\n /// milliseconds, and the give-up latch exits the product-fault path at\n /// once).\n ///\n /// ANCHORED, not chosen: it is `slow-timeout.period` from\n /// `.config/nextest.toml`, i.e. exactly the point at which the HARNESS\n /// ITSELF starts calling this test slow. Past that, nextest is already\n /// complaining and a longer wait cannot be the right answer — so the number\n /// has a SOURCE rather than being \"some multiple of the 2s that broke\",\n /// which would be a threshold keyed on a measurement instead of on the\n /// thing. If that config value changes, this should follow it.\n const WAIT_BACKSTOP: Duration = Duration::from_secs(60);\n…\n}\n\n[Showing lines 589-1063 of 2161. Use :1064 to continue]"}],"details":{"truncation":{"content":"/// supervision thread.\r\n/// - **not offline (onlined / torn down / deregistered) + live watcher** ⇒\r\n/// stop it (flag + kill).\r\n///\r\n/// Runs at daemon boot and every tick — lifecycle flips happen in CLI-process\r\n/// library code, so the *reconciler* holds the invariant, not the flipping\r\n/// caller; a flip is at most one tick stale.\r\n// [impl->REQ-SHELL-2]\r\n/// Heal every local shell record whose `online` is a lie — leg (a) of\r\n/// releases#78.\r\n///\r\n/// `effective_status` already computes this flip on EVERY read and never writes\r\n/// it down, so the record and the display disagree by design: the display side\r\n/// derives and looks clean, while the wake cascade reads the RECORDED field and\r\n/// skips its relaunch because that field still says online. A machine death\r\n/// breaks no link, so `close_shell` never runs and nothing else ever corrects it.\r\n///\r\n/// THE WRITE IS GUARDED ON AN ACTUAL CHANGE. This runs every reconcile cycle\r\n/// (5s), and a heal that rewrote the record each time would be a continuous\r\n/// stream of identical writes over a rarely-changing condition — noise on disk,\r\n/// and a record whose mtime stops meaning \"something happened\".\r\n///\r\n/// It DERIVES deliberately, unlike the watcher-eligibility read below it: this\r\n/// is not an eligibility decision that could relaunch a binary, it is a\r\n/// correction of a field that is already wrong. Nothing is started here.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\nfn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\r\n if info.status != SHELL_STATUS_ONLINE {\r\n continue;\r\n }\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\r\n let truth = shellinfo::effective_status(&perch, &info);\r\n if truth == info.status {\r\n continue; // the record already tells the truth — write nothing\r\n }\r\n let mut healed = info.clone();\r\n healed.status = truth.to_string();\r\n if shellinfo::write_shell_info(&perch, &healed).is_ok() {\r\n // [impl->REQ-SHELL-HEAL-ENUMERATION]\r\n let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\r\n }\r\n }\r\n }\r\n}\r\n\r\n/// Slack absorbed when asking whether a launch predates the boot instant.\r\n///\r\n/// The boot instant is DERIVED, not read from a ledger — on Windows it is\r\n/// now-minus-uptime, which drifts by however long the two calls take and by\r\n/// whatever the clock did since — so a process launched in the first moments of\r\n/// a boot can compute as very slightly older than the boot itself. Without slack\r\n/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\r\n/// could be armed after a same-boot death. Ten seconds is far wider than plausible\r\n/// derivation error and far narrower than the gap this discriminant exists to\r\n/// detect (a previous boot is minutes to days back).\r\npub const BOOT_RESTORE_SLACK_MS: u64 = 10_000;\r\n\r\n/// Whether a nonpersistent shell's recorded launch predates the current boot.\r\n/// This preserves its same-boot force-kill freeze; persistent shells do not use\r\n/// launch age as eligibility (releases#287).\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn launch_predates_boot(launched_ms: u64, boot_ms: u64, slack_ms: u64) -> bool {\r\n launched_ms.saturating_add(slack_ms) < boot_ms\r\n}\r\n\r\n/// Watchers require an offline instance with no live launch awaiting bind.\r\n/// Persistent shells bypass the corpse-age freeze (releases#287); nonpersistent\r\n/// corpses still need a dated pre-boot launch. Missing dates fail closed only\r\n/// for that nonpersistent freeze, never for persistent restoration.\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\nfn watcher_eligible(\r\n perch: &Path,\r\n info: &shellinfo::ShellInfo,\r\n persistent: bool,\r\n boot_ms: Option,\r\n) -> bool {\r\n if info.status != SHELL_STATUS_OFFLINE {\r\n return false;\r\n }\r\n if crate::shellhost::live_launch_winner(perch).is_some() {\r\n return false; // binding: the shell binary and watcher must not overlap\r\n }\r\n if persistent || !shellinfo::shell_pid_provably_dead(perch) {\r\n return true; // persistence overrides the freeze; clean closes need no age\r\n }\r\n let (Some(boot_ms), Some(launch)) = (boot_ms, shellinfo::read_shell_launch(perch)) else {\r\n return false;\r\n };\r\n launch_predates_boot(launch.launched_ms, boot_ms, BOOT_RESTORE_SLACK_MS)\r\n}\r\n\r\n/// Which trigger asked for a restore.\r\n///\r\n/// The two triggers run the SAME per-owner body and differ only in what woke\r\n/// them, so each NAMES ITSELF in its event line rather than sharing one: the\r\n/// field diagnosis of releases#228 was a COUNT of these events in a rotated\r\n/// daemon log, and a shared name would have left that reading unable to say\r\n/// which trigger had fired -- the one thing it needed to know.\r\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\r\npub enum RestoreTrigger {\r\n /// The once-per-daemon-generation boot sweep (releases#78 leg (b)).\r\n Boot,\r\n /// An owner endpoint that came online since the last reconcile pass\r\n /// (releases#228).\r\n OwnerOnline,\r\n}\r\n\r\nimpl RestoreTrigger {\r\n fn restored_event(self) -> &'static str {\r\n match self {\r\n RestoreTrigger::Boot => \"SHELL_BOOT_RESTORED\",\r\n RestoreTrigger::OwnerOnline => \"SHELL_OWNER_ONLINE_RESTORED\",\r\n }\r\n }\r\n\r\n fn failed_event(self) -> &'static str {\r\n match self {\r\n RestoreTrigger::Boot => \"SHELL_BOOT_RESTORE_FAIL\",\r\n RestoreTrigger::OwnerOnline => \"SHELL_OWNER_ONLINE_RESTORE_FAIL\",\r\n }\r\n }\r\n}\r\n\r\n/// ONE owner's slice of the persistent-shell restore decision -- the body BOTH\r\n/// triggers run.\r\n///\r\n/// Both triggers restore every persistent instance whose owner is online and\r\n/// whose binary is down in fact. Birth-safe liveness excludes a live launch\r\n/// awaiting bind as well as an already-online shell. Machine boot and launch\r\n/// age are irrelevant, including missing stamps (releases#287 operator ruling).\r\n///\r\n/// `set` is the daemon's live watcher set, and it is `None` at boot ON PURPOSE:\r\n/// the sweep runs before the reconcile loop's first tick, so no watcher can yet\r\n/// exist for the instance it is about to launch. The owner-online trigger runs\r\n/// MID-generation, where one can -- the reconcile start side arms watchers with\r\n/// no owner-online conjunct of its own -- so it passes the set and the watcher is\r\n/// stopped before the binary rises, which is the same online/offline mutual\r\n/// exclusivity `REQ-SHELL-2` holds everywhere else.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\n// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\r\nfn restore_persistent_shells_of_owner(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n owner: &str,\r\n trigger: RestoreTrigger,\r\n set: Option<&Arc>,\r\n restored: &mut Vec,\r\n) {\r\n let owner_perch = spt_store::perch::resolve_perch_path_in(owlery, owner, ParentHint::Infer);\r\n if !spt_store::liveness::is_perch_alive(&owner_perch) {\r\n return; // an offline owner is owed no persistent shell\r\n }\r\n for (shell_id, info) in shellinfo::list_shells(owlery, owner) {\r\n let Some(shell) =\r\n shell_section_of(registered, adapters_dir, &info.adapter_name).filter(|s| s.persistent)\r\n else {\r\n continue;\r\n };\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &shell_id);\r\n if shellinfo::is_shell_online(&perch, &info)\r\n || crate::shellhost::live_launch_winner(&perch).is_some()\r\n {\r\n continue; // already online or binding in fact\r\n }\r\n // Mutual exclusivity, the online side: the watcher dies before the binary\r\n // rises. `launch_shell` already kills the waker CHILD, but the supervising\r\n // thread would read that as a crash-exit and respawn it under the shell we\r\n // are starting; only the set can retire the thread. [impl->REQ-SHELL-2]\r\n if let Some(set) = set {\r\n set.stop_watcher(owlery, owner, &shell_id);\r\n }\r\n let install_dir = crate::shellhost::shell_install_dir(adapters_dir, &info.adapter_name);\r\n match crate::shellhost::launch_shell(\r\n owlery,\r\n owner,\r\n &shell_id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n &shell,\r\n ) {\r\n Ok(_) => {\r\n eprintln!(\"{}:{owner}/{shell_id}\", trigger.restored_event());\r\n restored.push(format!(\"{owner}/{shell_id}\"));\r\n }\r\n Err(e) => eprintln!(\"{}:{owner}/{shell_id}: {e}\", trigger.failed_event()),\r\n }\r\n }\r\n}\r\n\r\n/// The once-per-daemon-generation boot sweep: bring back the `persistent` shells\r\n/// a node restart stranded (leg (b) of releases#78).\r\n///\r\n/// Runs ONCE per daemon generation. It is not the ONLY restore trigger -- an owner\r\n/// endpoint that comes online after this sweep is covered by\r\n/// [`restore_persistent_shells_on_owner_online`] (releases#228), running the same\r\n/// [`restore_persistent_shells_of_owner`] body -- but it is the one that needs no\r\n/// trigger at all, since a node restart is what strands the shells to begin with.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\npub fn restore_persistent_shells_at_boot(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n) -> Vec {\r\n let mut restored = Vec::new();\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n restore_persistent_shells_of_owner(\r\n owlery,\r\n registered,\r\n adapters_dir,\r\n &owner,\r\n RestoreTrigger::Boot,\r\n None,\r\n &mut restored,\r\n );\r\n }\r\n restored\r\n}\r\n\r\n/// Per-owner online state carried ACROSS reconcile passes, so the restore below\r\n/// can be EDGE-triggered on an owner's offline->online transition.\r\n///\r\n/// An edge bounds a failing launch to one attempt per owner-online event,\r\n/// rather than retrying every reconcile tick while the owner remains online.\r\n/// A successful launch is protected by birth-safe liveness even before bind.\r\n#[derive(Debug, Default)]\r\npub struct OwnerOnlineEdge {\r\n /// Owner id -> online as of the last pass. An owner that disappears from the\r\n /// perch listing drops out, so a later reappearance reads as a transition.\r\n seen: HashMap,\r\n}\r\n\r\nimpl OwnerOnlineEdge {\r\n pub fn new() -> Self {\r\n Self::default()\r\n }\r\n\r\n /// Observe every owner and return those that went offline->online since the\r\n /// last observation. An owner seen for the FIRST time counts as a transition\r\n /// when it is online: it was not online at the last pass, because it was not\r\n /// there at all.\r\n fn transitions(&mut self, owlery: &Path) -> Vec {\r\n let mut fired = Vec::new();\r\n let mut now = HashMap::new();\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n let perch = spt_store::perch::resolve_perch_path_in(owlery, &owner, ParentHint::Infer);\r\n let online = spt_store::liveness::is_perch_alive(&perch);\r\n if online && !self.seen.get(&owner).copied().unwrap_or(false) {\r\n fired.push(owner.clone());\r\n }\r\n now.insert(owner, online);\r\n }\r\n self.seen = now;\r\n fired\r\n }\r\n\r\n /// Observe without firing -- the initial state the first tick compares against.\r\n ///\r\n /// Called BEFORE the boot sweep, and the ORDER is the safe direction rather\r\n /// than an accident. Seeded AFTER the sweep, an owner that comes online in the\r\n /// window between the two reads as already-online and never fires an edge --\r\n /// precisely the miss releases#228 is about. Seeded before, the worst case is a\r\n /// second attempt at an instance the sweep already restored, which the\r\n /// down-in-fact arm refuses.\r\n pub fn seed(&mut self, owlery: &Path) {\r\n let _ = self.transitions(owlery);\r\n }\r\n}\r\n\r\n/// Restore the `persistent` shells of every owner that came online since the last\r\n/// pass -- the steady-state half of the contract's promise (releases#228).\r\n///\r\n/// Daemons boot before endpoints do, so the boot sweep correctly skips an owner\r\n/// that is not up yet and, being once-per-generation, never revisits it; bringup\r\n/// from offline emits no rest edge either, so the ADR-0048 cascade does not cover\r\n/// it. Both triggers use the same down-in-fact decision, without a machine-boot\r\n/// or launch-stamp eligibility gate (releases#287).\r\n// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\npub fn restore_persistent_shells_on_owner_online(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n edge: &mut OwnerOnlineEdge,\r\n set: &Arc,\r\n) -> Vec {\r\n let owners = edge.transitions(owlery);\r\n if owners.is_empty() {\r\n return Vec::new();\r\n }\r\n let mut restored = Vec::new();\r\n for owner in owners {\r\n restore_persistent_shells_of_owner(\r\n owlery,\r\n registered,\r\n adapters_dir,\r\n &owner,\r\n RestoreTrigger::OwnerOnline,\r\n Some(set),\r\n &mut restored,\r\n );\r\n }\r\n restored\r\n}\r\n\r\npub fn reconcile_once(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n set: &Arc,\r\n params: &WakeParams,\r\n) {\r\n // Leg (a) first, every cycle: the record must stop lying before anything reads\r\n // it below. Ordering matters -- the watcher-eligibility read further down asks\r\n // the RECORDED field, so a heal that ran after it would leave this cycle acting\r\n // on the stale value it just corrected.\r\n heal_stale_online_records(owlery, &mut std::io::stderr().lock());\r\n\r\n // Stop side first: watchers whose instance is gone or no longer eligible.\r\n let live: Vec<(String, String)> = {\r\n let mut map = set.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.retain(|_, h| !h.thread.is_finished());\r\n map.keys().cloned().collect()\r\n };\r\n for (owner, shell_id) in live {\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\r\n let still_eligible = shellinfo::read_shell_info(&perch)\r\n .map(|i| i.status == SHELL_STATUS_OFFLINE)\r\n .unwrap_or(false);\r\n if !still_eligible {\r\n set.stop_watcher(owlery, &owner, &shell_id);\r\n }\r\n }\r\n\r\n // Start side: every ELIGIBLE instance with a wake_command and headroom.\r\n //\r\n // Persistent instances bypass the force-kill freeze; only nonpersistent\r\n // corpses need the pre-boot discriminant (releases#287).\r\n let boot_ms = spt_store::proc::boot_instant_ms();\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\r\n if set.contains(&owner, &shell_id) {\r\n continue;\r\n }\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\r\n let Some(shell) = shell_section_of(registered, adapters_dir, &info.adapter_name) else {\r\n continue; // deregistered adapter: nothing to run\r\n };\r\n if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\r\n continue;\r\n }\r\n let Some(wake_command) = shell.wake_command.as_deref() else {\r\n continue;\r\n };\r\n if perch.join(WAKER_GAVE_UP_FILE).exists() {\r\n continue; // crash-latched until the next shell activity\r\n }\r\n // Adopt cleanly: a dead daemon's watcher must not double-run.\r\n kill_waker_at(&perch);\r\n // [impl->REQ-INSTALL-11] threading only: this loop already holds the\r\n // registered set the record's `source_dir` lives in.\r\n let install_dir = crate::shellhost::shell_install_dir(adapters_dir, &info.adapter_name);\r\n let tokens = match fill_wake_command(\r\n &shell_id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n wake_command,\r\n ) {\r\n Ok(t) => t,\r\n Err(e) => {\r\n spt_proto::emit_line_err!(\"WAKER_TEMPLATE:{owner}/{shell_id}: {e}\");\r\n continue;\r\n }\r\n };\r\n let stop = Arc::new(AtomicBool::new(false));\r\n let handle = {\r\n let stop = Arc::clone(&stop);\r\n let owlery = owlery.to_path_buf();\r\n let owner = owner.clone();\r\n let shell_id = shell_id.clone();\r\n let adapter_name = info.adapter_name.clone();\r\n let params = *params;\r\n std::thread::spawn(move || {\r\n watcher_run(&owlery, &owner, &shell_id, &tokens, ¶ms, &stop, || {\r\n resolve_wake(&owlery, &owner, &shell_id, &adapter_name, &shell)\r\n });\r\n })\r\n };\r\n set.insert(\r\n &owner,\r\n &shell_id,\r\n WatcherHandle {\r\n stop,\r\n thread: handle,\r\n },\r\n );\r\n }\r\n }\r\n}\r\n\r\n/// The reconcile cadence (ms): lifecycle flips land in CLI processes, so the\r\n/// daemon's loop is the invariant holder — a flip is at most one tick stale.\r\npub const RECONCILE_INTERVAL_MS: u64 = 5_000;\r\n\r\n/// Spawn the daemon's wake host: one thread sweeping [`reconcile_once`] at\r\n/// boot and every [`RECONCILE_INTERVAL_MS`] until `stop`. The registered set\r\n/// is re-read each sweep (adapter add/remove lands between ticks).\r\n// [impl->REQ-SHELL-2]\r\npub fn spawn_wake_host(stop: Arc) -> JoinHandle<()> {\r\n std::thread::spawn(move || {\r\n let set = Arc::new(WakeSet::new());\r\n let params = WakeParams::default();\r\n let mut owner_edge = OwnerOnlineEdge::new();\r\n // Once per daemon generation, restore down persistent shells of owners\r\n // already online. Owners arriving later are covered by the edge below.\r\n // Neither trigger gates persistence on machine boot or launch age.\r\n {\r\n let owlery = spt_store::perch::owlery_dir();\r\n let adapters_dir = spt_store::perch::adapters_dir();\r\n let registered = spt_runtime::registry::registered(&adapters_dir);\r\n // Seeded BEFORE the sweep: an owner that comes online between the two\r\n // must read as a transition on the first tick, not as already-online.\r\n owner_edge.seed(&owlery);\r\n restore_persistent_shells_at_boot(&owlery, ®istered, &adapters_dir);\r\n }\r\n while !stop.load(Ordering::SeqCst) {\r\n let owlery = spt_store::perch::owlery_dir();\r\n let adapters_dir = spt_store::perch::adapters_dir();\r\n let registered = spt_runtime::registry::registered(&adapters_dir);\r\n // Restore BEFORE reconciling, the same order the boot pass runs in: a\r\n // restored instance is not watcher material, and reconcile's start side\r\n // would otherwise arm a watcher for the shell we are about to launch.\r\n restore_persistent_shells_on_owner_online(\r\n &owlery,\r\n ®istered,\r\n &adapters_dir,\r\n &mut owner_edge,\r\n &set,\r\n );\r\n reconcile_once(&owlery, ®istered, &adapters_dir, &set, ¶ms);\r\n // Sleep in slices so a stop lands promptly.\r\n let mut left = RECONCILE_INTERVAL_MS;\r\n while left > 0 && !stop.load(Ordering::SeqCst) {\r\n let step = left.min(100);\r\n std::thread::sleep(Duration::from_millis(step));\r\n left -= step;\r\n }\r\n }\r\n })\r\n}\r\n\r\n#[cfg(test)]\r\nmod tests {\r\n use super::*;\r\n use spt_store::shellinfo::{spawn_record, SHELL_STATUS_ONLINE};\r\n\r\n /// BACKSTOP for the converge-waits below — a ceiling on an observable, not\r\n /// a budget any run is expected to consume (the healthy path exits in\r\n /// milliseconds, and the give-up latch exits the product-fault path at\r\n /// once).\r\n ///\r\n /// ANCHORED, not chosen: it is `slow-timeout.period` from\r\n /// `.config/nextest.toml`, i.e. exactly the point at which the HARNESS\r\n /// ITSELF starts calling this test slow. Past that, nextest is already\r\n /// complaining and a longer wait cannot be the right answer — so the number\r\n /// has a SOURCE rather than being \"some multiple of the 2s that broke\",\r\n /// which would be a threshold keyed on a measurement instead of on the\r\n /// thing. If that config value changes, this should follow it.\r\n const WAIT_BACKSTOP: Duration = Duration::from_secs(60);\r","truncated":true,"truncatedBy":"lines","totalLines":1573,"totalBytes":21600,"outputLines":475,"outputBytes":21600,"lastLinePartial":false,"firstLineExceedsLimit":false},"totalLines":2161,"displayContent":{"text":"/// supervision thread.\r\n/// - **not offline (onlined / torn down / deregistered) + live watcher** ⇒\r\n/// stop it (flag + kill).\r\n///\r\n/// Runs at daemon boot and every tick — lifecycle flips happen in CLI-process\r\n/// library code, so the *reconciler* holds the invariant, not the flipping\r\n/// caller; a flip is at most one tick stale.\r\n// [impl->REQ-SHELL-2]\r\n/// Heal every local shell record whose `online` is a lie — leg (a) of\r\n/// releases#78.\r\n///\r\n/// `effective_status` already computes this flip on EVERY read and never writes\r\n/// it down, so the record and the display disagree by design: the display side\r\n/// derives and looks clean, while the wake cascade reads the RECORDED field and\r\n/// skips its relaunch because that field still says online. A machine death\r\n/// breaks no link, so `close_shell` never runs and nothing else ever corrects it.\r\n///\r\n/// THE WRITE IS GUARDED ON AN ACTUAL CHANGE. This runs every reconcile cycle\r\n/// (5s), and a heal that rewrote the record each time would be a continuous\r\n/// stream of identical writes over a rarely-changing condition — noise on disk,\r\n/// and a record whose mtime stops meaning \"something happened\".\r\n///\r\n/// It DERIVES deliberately, unlike the watcher-eligibility read below it: this\r\n/// is not an eligibility decision that could relaunch a binary, it is a\r\n/// correction of a field that is already wrong. Nothing is started here.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\nfn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\r\n if info.status != SHELL_STATUS_ONLINE {\r\n continue;\r\n }\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\r\n let truth = shellinfo::effective_status(&perch, &info);\r\n if truth == info.status {\r\n continue; // the record already tells the truth — write nothing\r\n }\r\n let mut healed = info.clone();\r\n healed.status = truth.to_string();\r\n if shellinfo::write_shell_info(&perch, &healed).is_ok() {\r\n // [impl->REQ-SHELL-HEAL-ENUMERATION]\r\n let _ = spt_proto::emit_line!(events, \"SHELL_RECORD_HEALED:{owner}/{shell_id}: online -> {truth}\");\r\n }\r\n }\r\n }\r\n}\r\n\r\n/// Slack absorbed when asking whether a launch predates the boot instant.\r\n///\r\n/// The boot instant is DERIVED, not read from a ledger — on Windows it is\r\n/// now-minus-uptime, which drifts by however long the two calls take and by\r\n/// whatever the clock did since — so a process launched in the first moments of\r\n/// a boot can compute as very slightly older than the boot itself. Without slack\r\n/// that reads as \"a corpse from the previous boot\" and a nonpersistent watcher\r\n/// could be armed after a same-boot death. Ten seconds is far wider than plausible\r\n/// derivation error and far narrower than the gap this discriminant exists to\r\n/// detect (a previous boot is minutes to days back).\r\npub const BOOT_RESTORE_SLACK_MS: u64 = 10_000;\r\n\r\n/// Whether a nonpersistent shell's recorded launch predates the current boot.\r\n/// This preserves its same-boot force-kill freeze; persistent shells do not use\r\n/// launch age as eligibility (releases#287).\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub fn launch_predates_boot(launched_ms: u64, boot_ms: u64, slack_ms: u64) -> bool {\r\n launched_ms.saturating_add(slack_ms) < boot_ms\r\n}\r\n\r\n/// Watchers require an offline instance with no live launch awaiting bind.\r\n/// Persistent shells bypass the corpse-age freeze (releases#287); nonpersistent\r\n/// corpses still need a dated pre-boot launch. Missing dates fail closed only\r\n/// for that nonpersistent freeze, never for persistent restoration.\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\nfn watcher_eligible(\r\n perch: &Path,\r\n info: &shellinfo::ShellInfo,\r\n persistent: bool,\r\n boot_ms: Option,\r\n) -> bool {\r\n if info.status != SHELL_STATUS_OFFLINE {\r\n return false;\r\n }\r\n if crate::shellhost::live_launch_winner(perch).is_some() {\r\n return false; // binding: the shell binary and watcher must not overlap\r\n }\r\n if persistent || !shellinfo::shell_pid_provably_dead(perch) {\r\n return true; // persistence overrides the freeze; clean closes need no age\r\n }\r\n let (Some(boot_ms), Some(launch)) = (boot_ms, shellinfo::read_shell_launch(perch)) else {\r\n return false;\r\n };\r\n launch_predates_boot(launch.launched_ms, boot_ms, BOOT_RESTORE_SLACK_MS)\r\n}\r\n\r\n/// Which trigger asked for a restore.\r\n///\r\n/// The two triggers run the SAME per-owner body and differ only in what woke\r\n/// them, so each NAMES ITSELF in its event line rather than sharing one: the\r\n/// field diagnosis of releases#228 was a COUNT of these events in a rotated\r\n/// daemon log, and a shared name would have left that reading unable to say\r\n/// which trigger had fired -- the one thing it needed to know.\r\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\r\npub enum RestoreTrigger {\r\n /// The once-per-daemon-generation boot sweep (releases#78 leg (b)).\r\n Boot,\r\n /// An owner endpoint that came online since the last reconcile pass\r\n /// (releases#228).\r\n OwnerOnline,\r\n}\r\n\r\nimpl RestoreTrigger {\r\n fn restored_event(self) -> &'static str {\r\n match self {\r\n RestoreTrigger::Boot => \"SHELL_BOOT_RESTORED\",\r\n RestoreTrigger::OwnerOnline => \"SHELL_OWNER_ONLINE_RESTORED\",\r\n }\r\n }\r\n\r\n fn failed_event(self) -> &'static str {\r\n match self {\r\n RestoreTrigger::Boot => \"SHELL_BOOT_RESTORE_FAIL\",\r\n RestoreTrigger::OwnerOnline => \"SHELL_OWNER_ONLINE_RESTORE_FAIL\",\r\n }\r\n }\r\n}\r\n\r\n/// ONE owner's slice of the persistent-shell restore decision -- the body BOTH\r\n/// triggers run.\r\n///\r\n/// Both triggers restore every persistent instance whose owner is online and\r\n/// whose binary is down in fact. Birth-safe liveness excludes a live launch\r\n/// awaiting bind as well as an already-online shell. Machine boot and launch\r\n/// age are irrelevant, including missing stamps (releases#287 operator ruling).\r\n///\r\n/// `set` is the daemon's live watcher set, and it is `None` at boot ON PURPOSE:\r\n/// the sweep runs before the reconcile loop's first tick, so no watcher can yet\r\n/// exist for the instance it is about to launch. The owner-online trigger runs\r\n/// MID-generation, where one can -- the reconcile start side arms watchers with\r\n/// no owner-online conjunct of its own -- so it passes the set and the watcher is\r\n/// stopped before the binary rises, which is the same online/offline mutual\r\n/// exclusivity `REQ-SHELL-2` holds everywhere else.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\n// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\r\nfn restore_persistent_shells_of_owner(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n owner: &str,\r\n trigger: RestoreTrigger,\r\n set: Option<&Arc>,\r\n restored: &mut Vec,\r\n) {\r\n let owner_perch = spt_store::perch::resolve_perch_path_in(owlery, owner, ParentHint::Infer);\r\n if !spt_store::liveness::is_perch_alive(&owner_perch) {\r\n return; // an offline owner is owed no persistent shell\r\n }\r\n for (shell_id, info) in shellinfo::list_shells(owlery, owner) {\r\n let Some(shell) =\r\n shell_section_of(registered, adapters_dir, &info.adapter_name).filter(|s| s.persistent)\r\n else {\r\n continue;\r\n };\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &shell_id);\r\n if shellinfo::is_shell_online(&perch, &info)\r\n || crate::shellhost::live_launch_winner(&perch).is_some()\r\n {\r\n continue; // already online or binding in fact\r\n }\r\n // Mutual exclusivity, the online side: the watcher dies before the binary\r\n // rises. `launch_shell` already kills the waker CHILD, but the supervising\r\n // thread would read that as a crash-exit and respawn it under the shell we\r\n // are starting; only the set can retire the thread. [impl->REQ-SHELL-2]\r\n if let Some(set) = set {\r\n set.stop_watcher(owlery, owner, &shell_id);\r\n }\r\n let install_dir = crate::shellhost::shell_install_dir(adapters_dir, &info.adapter_name);\r\n match crate::shellhost::launch_shell(\r\n owlery,\r\n owner,\r\n &shell_id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n &shell,\r\n ) {\r\n Ok(_) => {\r\n eprintln!(\"{}:{owner}/{shell_id}\", trigger.restored_event());\r\n restored.push(format!(\"{owner}/{shell_id}\"));\r\n }\r\n Err(e) => eprintln!(\"{}:{owner}/{shell_id}: {e}\", trigger.failed_event()),\r\n }\r\n }\r\n}\r\n\r\n/// The once-per-daemon-generation boot sweep: bring back the `persistent` shells\r\n/// a node restart stranded (leg (b) of releases#78).\r\n///\r\n/// Runs ONCE per daemon generation. It is not the ONLY restore trigger -- an owner\r\n/// endpoint that comes online after this sweep is covered by\r\n/// [`restore_persistent_shells_on_owner_online`] (releases#228), running the same\r\n/// [`restore_persistent_shells_of_owner`] body -- but it is the one that needs no\r\n/// trigger at all, since a node restart is what strands the shells to begin with.\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\npub fn restore_persistent_shells_at_boot(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n) -> Vec {\r\n let mut restored = Vec::new();\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n restore_persistent_shells_of_owner(\r\n owlery,\r\n registered,\r\n adapters_dir,\r\n &owner,\r\n RestoreTrigger::Boot,\r\n None,\r\n &mut restored,\r\n );\r\n }\r\n restored\r\n}\r\n\r\n/// Per-owner online state carried ACROSS reconcile passes, so the restore below\r\n/// can be EDGE-triggered on an owner's offline->online transition.\r\n///\r\n/// An edge bounds a failing launch to one attempt per owner-online event,\r\n/// rather than retrying every reconcile tick while the owner remains online.\r\n/// A successful launch is protected by birth-safe liveness even before bind.\r\n#[derive(Debug, Default)]\r\npub struct OwnerOnlineEdge {\r\n /// Owner id -> online as of the last pass. An owner that disappears from the\r\n /// perch listing drops out, so a later reappearance reads as a transition.\r\n seen: HashMap,\r\n}\r\n\r\nimpl OwnerOnlineEdge {\r\n pub fn new() -> Self {\r\n Self::default()\r\n }\r\n\r\n /// Observe every owner and return those that went offline->online since the\r\n /// last observation. An owner seen for the FIRST time counts as a transition\r\n /// when it is online: it was not online at the last pass, because it was not\r\n /// there at all.\r\n fn transitions(&mut self, owlery: &Path) -> Vec {\r\n let mut fired = Vec::new();\r\n let mut now = HashMap::new();\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n let perch = spt_store::perch::resolve_perch_path_in(owlery, &owner, ParentHint::Infer);\r\n let online = spt_store::liveness::is_perch_alive(&perch);\r\n if online && !self.seen.get(&owner).copied().unwrap_or(false) {\r\n fired.push(owner.clone());\r\n }\r\n now.insert(owner, online);\r\n }\r\n self.seen = now;\r\n fired\r\n }\r\n\r\n /// Observe without firing -- the initial state the first tick compares against.\r\n ///\r\n /// Called BEFORE the boot sweep, and the ORDER is the safe direction rather\r\n /// than an accident. Seeded AFTER the sweep, an owner that comes online in the\r\n /// window between the two reads as already-online and never fires an edge --\r\n /// precisely the miss releases#228 is about. Seeded before, the worst case is a\r\n /// second attempt at an instance the sweep already restored, which the\r\n /// down-in-fact arm refuses.\r\n pub fn seed(&mut self, owlery: &Path) {\r\n let _ = self.transitions(owlery);\r\n }\r\n}\r\n\r\n/// Restore the `persistent` shells of every owner that came online since the last\r\n/// pass -- the steady-state half of the contract's promise (releases#228).\r\n///\r\n/// Daemons boot before endpoints do, so the boot sweep correctly skips an owner\r\n/// that is not up yet and, being once-per-generation, never revisits it; bringup\r\n/// from offline emits no rest edge either, so the ADR-0048 cascade does not cover\r\n/// it. Both triggers use the same down-in-fact decision, without a machine-boot\r\n/// or launch-stamp eligibility gate (releases#287).\r\n// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\r\n// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\r\npub fn restore_persistent_shells_on_owner_online(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n edge: &mut OwnerOnlineEdge,\r\n set: &Arc,\r\n) -> Vec {\r\n let owners = edge.transitions(owlery);\r\n if owners.is_empty() {\r\n return Vec::new();\r\n }\r\n let mut restored = Vec::new();\r\n for owner in owners {\r\n restore_persistent_shells_of_owner(\r\n owlery,\r\n registered,\r\n adapters_dir,\r\n &owner,\r\n RestoreTrigger::OwnerOnline,\r\n Some(set),\r\n &mut restored,\r\n );\r\n }\r\n restored\r\n}\r\n\r\npub fn reconcile_once(\r\n owlery: &Path,\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n set: &Arc,\r\n params: &WakeParams,\r\n) {\r\n // Leg (a) first, every cycle: the record must stop lying before anything reads\r\n // it below. Ordering matters -- the watcher-eligibility read further down asks\r\n // the RECORDED field, so a heal that ran after it would leave this cycle acting\r\n // on the stale value it just corrected.\r\n heal_stale_online_records(owlery, &mut std::io::stderr().lock());\r\n\r\n // Stop side first: watchers whose instance is gone or no longer eligible.\r\n let live: Vec<(String, String)> = {\r\n let mut map = set.inner.lock().unwrap_or_else(|p| p.into_inner());\r\n map.retain(|_, h| !h.thread.is_finished());\r\n map.keys().cloned().collect()\r\n };\r\n for (owner, shell_id) in live {\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\r\n let still_eligible = shellinfo::read_shell_info(&perch)\r\n .map(|i| i.status == SHELL_STATUS_OFFLINE)\r\n .unwrap_or(false);\r\n if !still_eligible {\r\n set.stop_watcher(owlery, &owner, &shell_id);\r\n }\r\n }\r\n\r\n // Start side: every ELIGIBLE instance with a wake_command and headroom.\r\n //\r\n // Persistent instances bypass the force-kill freeze; only nonpersistent\r\n // corpses need the pre-boot discriminant (releases#287).\r\n let boot_ms = spt_store::proc::boot_instant_ms();\r\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\r\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\r\n if set.contains(&owner, &shell_id) {\r\n continue;\r\n }\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\r\n let Some(shell) = shell_section_of(registered, adapters_dir, &info.adapter_name) else {\r\n continue; // deregistered adapter: nothing to run\r\n };\r\n if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\r\n continue;\r\n }\r\n let Some(wake_command) = shell.wake_command.as_deref() else {\r\n continue;\r\n };\r\n if perch.join(WAKER_GAVE_UP_FILE).exists() {\r\n continue; // crash-latched until the next shell activity\r\n }\r\n // Adopt cleanly: a dead daemon's watcher must not double-run.\r\n kill_waker_at(&perch);\r\n // [impl->REQ-INSTALL-11] threading only: this loop already holds the\r\n // registered set the record's `source_dir` lives in.\r\n let install_dir = crate::shellhost::shell_install_dir(adapters_dir, &info.adapter_name);\r\n let tokens = match fill_wake_command(\r\n &shell_id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n wake_command,\r\n ) {\r\n Ok(t) => t,\r\n Err(e) => {\r\n spt_proto::emit_line_err!(\"WAKER_TEMPLATE:{owner}/{shell_id}: {e}\");\r\n continue;\r\n }\r\n };\r\n let stop = Arc::new(AtomicBool::new(false));\r\n let handle = {\r\n let stop = Arc::clone(&stop);\r\n let owlery = owlery.to_path_buf();\r\n let owner = owner.clone();\r\n let shell_id = shell_id.clone();\r\n let adapter_name = info.adapter_name.clone();\r\n let params = *params;\r\n std::thread::spawn(move || {\r\n watcher_run(&owlery, &owner, &shell_id, &tokens, ¶ms, &stop, || {\r\n resolve_wake(&owlery, &owner, &shell_id, &adapter_name, &shell)\r\n });\r\n })\r\n };\r\n set.insert(\r\n &owner,\r\n &shell_id,\r\n WatcherHandle {\r\n stop,\r\n thread: handle,\r\n },\r\n );\r\n }\r\n }\r\n}\r\n\r\n/// The reconcile cadence (ms): lifecycle flips land in CLI processes, so the\r\n/// daemon's loop is the invariant holder — a flip is at most one tick stale.\r\npub const RECONCILE_INTERVAL_MS: u64 = 5_000;\r\n\r\n/// Spawn the daemon's wake host: one thread sweeping [`reconcile_once`] at\r\n/// boot and every [`RECONCILE_INTERVAL_MS`] until `stop`. The registered set\r\n/// is re-read each sweep (adapter add/remove lands between ticks).\r\n// [impl->REQ-SHELL-2]\r\npub fn spawn_wake_host(stop: Arc) -> JoinHandle<()> {\r\n std::thread::spawn(move || {\r\n let set = Arc::new(WakeSet::new());\r\n let params = WakeParams::default();\r\n let mut owner_edge = OwnerOnlineEdge::new();\r\n // Once per daemon generation, restore down persistent shells of owners\r\n // already online. Owners arriving later are covered by the edge below.\r\n // Neither trigger gates persistence on machine boot or launch age.\r\n {\r\n let owlery = spt_store::perch::owlery_dir();\r\n let adapters_dir = spt_store::perch::adapters_dir();\r\n let registered = spt_runtime::registry::registered(&adapters_dir);\r\n // Seeded BEFORE the sweep: an owner that comes online between the two\r\n // must read as a transition on the first tick, not as already-online.\r\n owner_edge.seed(&owlery);\r\n restore_persistent_shells_at_boot(&owlery, ®istered, &adapters_dir);\r\n }\r\n while !stop.load(Ordering::SeqCst) {\r\n let owlery = spt_store::perch::owlery_dir();\r\n let adapters_dir = spt_store::perch::adapters_dir();\r\n let registered = spt_runtime::registry::registered(&adapters_dir);\r\n // Restore BEFORE reconciling, the same order the boot pass runs in: a\r\n // restored instance is not watcher material, and reconcile's start side\r\n // would otherwise arm a watcher for the shell we are about to launch.\r\n restore_persistent_shells_on_owner_online(\r\n &owlery,\r\n ®istered,\r\n &adapters_dir,\r\n &mut owner_edge,\r\n &set,\r\n );\r\n reconcile_once(&owlery, ®istered, &adapters_dir, &set, ¶ms);\r\n // Sleep in slices so a stop lands promptly.\r\n let mut left = RECONCILE_INTERVAL_MS;\r\n while left > 0 && !stop.load(Ordering::SeqCst) {\r\n let step = left.min(100);\r\n std::thread::sleep(Duration::from_millis(step));\r\n left -= step;\r\n }\r\n }\r\n })\r\n}\r\n\r\n#[cfg(test)]\r\nmod tests {\r\n use super::*;\r\n use spt_store::shellinfo::{spawn_record, SHELL_STATUS_ONLINE};\r\n\r\n /// BACKSTOP for the converge-waits below — a ceiling on an observable, not\r\n /// a budget any run is expected to consume (the healthy path exits in\r\n /// milliseconds, and the give-up latch exits the product-fault path at\r\n /// once).\r\n ///\r\n /// ANCHORED, not chosen: it is `slow-timeout.period` from\r\n /// `.config/nextest.toml`, i.e. exactly the point at which the HARNESS\r\n /// ITSELF starts calling this test slow. Past that, nextest is already\r\n /// complaining and a longer wait cannot be the right answer — so the number\r\n /// has a SOURCE rather than being \"some multiple of the 2s that broke\",\r\n /// which would be a threshold keyed on a measurement instead of on the\r\n /// thing. If that config value changes, this should follow it.\r\n const WAIT_BACKSTOP: Duration = Duration::from_secs(60);\r\n…\n}","startLine":589,"lineNumbers":[589,590,591,592,593,594,595,596,597,598,599,600,601,602,603,604,605,606,607,608,609,610,611,612,613,614,615,616,617,618,619,620,621,622,623,624,625,626,627,628,629,630,631,632,633,634,635,636,637,638,639,640,641,642,643,644,645,646,647,648,649,650,651,652,653,654,655,656,657,658,659,660,661,662,663,664,665,666,667,668,669,670,671,672,673,674,675,676,677,678,679,680,681,682,683,684,685,686,687,688,689,690,691,692,693,694,695,696,697,698,699,700,701,702,703,704,705,706,707,708,709,710,711,712,713,714,715,716,717,718,719,720,721,722,723,724,725,726,727,728,729,730,731,732,733,734,735,736,737,738,739,740,741,742,743,744,745,746,747,748,749,750,751,752,753,754,755,756,757,758,759,760,761,762,763,764,765,766,767,768,769,770,771,772,773,774,775,776,777,778,779,780,781,782,783,784,785,786,787,788,789,790,791,792,793,794,795,796,797,798,799,800,801,802,803,804,805,806,807,808,809,810,811,812,813,814,815,816,817,818,819,820,821,822,823,824,825,826,827,828,829,830,831,832,833,834,835,836,837,838,839,840,841,842,843,844,845,846,847,848,849,850,851,852,853,854,855,856,857,858,859,860,861,862,863,864,865,866,867,868,869,870,871,872,873,874,875,876,877,878,879,880,881,882,883,884,885,886,887,888,889,890,891,892,893,894,895,896,897,898,899,900,901,902,903,904,905,906,907,908,909,910,911,912,913,914,915,916,917,918,919,920,921,922,923,924,925,926,927,928,929,930,931,932,933,934,935,936,937,938,939,940,941,942,943,944,945,946,947,948,949,950,951,952,953,954,955,956,957,958,959,960,961,962,963,964,965,966,967,968,969,970,971,972,973,974,975,976,977,978,979,980,981,982,983,984,985,986,987,988,989,990,991,992,993,994,995,996,997,998,999,1000,1001,1002,1003,1004,1005,1006,1007,1008,1009,1010,1011,1012,1013,1014,1015,1016,1017,1018,1019,1020,1021,1022,1023,1024,1025,1026,1027,1028,1029,1030,1031,1032,1033,1034,1035,1036,1037,1038,1039,1040,1041,1042,1043,1044,1045,1046,1047,1048,1049,1050,1051,1052,1053,1054,1055,1056,1057,1058,1059,1060,1061,1062,1063,null,2161]},"fileSize":100821,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\crates\\spt-daemon\\src\\shellwake.rs"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":2161,"totalBytes":21600,"outputLines":475,"outputBytes":21600,"shownRange":{"start":589,"end":1063},"nextOffset":1064}}},"isError":false,"timestamp":1789001136967}}
{"type":"message","id":"ca63b887","parentId":"ab9d17cd","timestamp":"2026-09-10T00:45:36.975Z","message":{"role":"toolResult","toolCallId":"call_b5vz9AVfJemvkhllIGlgLVCf|fc_077f3569365e313d016aa1fdb0c08087d182419544e6345b9c","toolName":"read","content":[{"type":"text","text":"-/// corpse-boot discriminant refuses that instance from then on. A FAILING launch\n-/// does not -- under a level trigger (\"the owner is online\") it would be retried\n-/// every [`RECONCILE_INTERVAL_MS`] for as long as the owner stayed up. The edge\n-/// bounds it to one attempt per owner-online event.\n+/// An edge bounds a failing launch to one attempt per owner-online event,\n+/// rather than retrying every reconcile tick while the owner remains online.\n+/// A successful launch is protected by birth-safe liveness even before bind.\n #[derive(Debug, Default)]\n pub struct OwnerOnlineEdge {\n /// Owner id -> online as of the last pass. An owner that disappears from the\n@@ -924,12 +867,8 @@ impl OwnerOnlineEdge {\n /// Daemons boot before endpoints do, so the boot sweep correctly skips an owner\n /// that is not up yet and, being once-per-generation, never revisits it; bringup\n /// from offline emits no rest edge either, so the ADR-0048 cascade does not cover\n-/// it. This is the trigger that does. Re-running the sweep's conjuncts is safe by\n-/// construction and not by convention: `launch_predates_boot` is MONOTONE within a\n-/// machine boot (every launch path restamps `launched_ms`, a kill never restamps,\n-/// `boot_ms` is the machine boot instant), so a later evaluation can only refuse\n-/// MORE. A shell an operator force-killed during this boot is refused here exactly\n-/// as it is refused at boot -- forever, and by the same predicate.\n+/// it. Both triggers use the same down-in-fact decision, without a machine-boot\n+/// or launch-stamp eligibility gate (releases#287).\n // [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n pub fn restore_persistent_shells_on_owner_online(\n@@ -943,11 +882,6 @@ pub fn restore_persistent_shells_on_owner_online(\n if owners.is_empty() {\n return Vec::new();\n }\n- let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n- // Same stance as the sweep's: no boot oracle => the discriminant cannot be\n- // evaluated => restore nothing.\n- return Vec::new();\n- };\n let mut restored = Vec::new();\n for owner in owners {\n restore_persistent_shells_of_owner(\n@@ -955,7 +889,6 @@ pub fn restore_persistent_shells_on_owner_online(\n registered,\n adapters_dir,\n &owner,\n- boot_ms,\n RestoreTrigger::OwnerOnline,\n Some(set),\n &mut restored,\n@@ -975,7 +908,7 @@ pub fn reconcile_once(\n // it below. Ordering matters -- the watcher-eligibility read further down asks\n // the RECORDED field, so a heal that ran after it would leave this cycle acting\n // on the stale value it just corrected.\n- heal_stale_online_records(owlery);\n+ heal_stale_online_records(owlery, &mut std::io::stderr().lock());\n \n // Stop side first: watchers whose instance is gone or no longer eligible.\n let live: Vec<(String, String)> = {\n@@ -995,14 +928,8 @@ pub fn reconcile_once(\n \n // Start side: every ELIGIBLE instance with a wake_command and headroom.\n //\n- // Eligibility is `watcher_eligible` — recorded status (never derived) AND the\n- // corpse-boot discriminant. Before leg (a) the recorded field was the whole\n- // guard: a force-killed instance kept a stale `online` record, which is what\n- // held it out of this set. That record now tells the truth, so the protection\n- // moved to the discriminant that states it directly (doyle, releases#78\n- // comment 5156810267) — the same `launch_predates_boot` leg (b) uses, so the\n- // freeze's forbidden behaviour stays forbidden by construction rather than by\n- // a second rule.\n+ // Persistent instances bypass the force-kill freeze; only nonpersistent\n+ // corpses need the pre-boot discriminant (releases#287).\n let boot_ms = spt_store::proc::boot_instant_ms();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n@@ -1010,12 +937,12 @@ pub fn reconcile_once(\n continue;\n }\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\n- if !watcher_eligible(&perch, &info, boot_ms) {\n- continue;\n- }\n let Some(shell) = shell_section_of(registered, adapters_dir, &info.adapter_name) else {\n continue; // deregistered adapter: nothing to run\n };\n+ if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\n+ continue;\n+ }\n let Some(wake_command) = shell.wake_command.as_deref() else {\n continue;\n };\n@@ -1078,15 +1005,9 @@ pub fn spawn_wake_host(stop: Arc) -> JoinHandle<()> {\n let set = Arc::new(WakeSet::new());\n let params = WakeParams::default();\n let mut owner_edge = OwnerOnlineEdge::new();\n- // ONCE per daemon generation, before the reconcile loop: bring back the\n- // persistent shells a node restart stranded (releases#78 leg b). Outside\n- // the loop because a node restart is a boot event -- but NOT because\n- // once-ness protects the operator-force-kill ruling: it does not, and a\n- // comment here used to say it did. `launch_predates_boot` is what protects\n- // it, on every evaluation (`reconcile_once`'s start-side comment records\n- // that ruling; doyle re-measured it on releases#228). The steady-state\n- // half -- an owner that comes online AFTER this sweep -- is covered in the\n- // loop below, which is exactly the re-evaluation the false comment forbade.\n+ // Once per daemon generation, restore down persistent shells of owners\n+ // already online. Owners arriving later are covered by the edge below.\n+ // Neither trigger gates persistence on machine boot or launch age.\n {\n let owlery = spt_store::perch::owlery_dir();\n let adapters_dir = spt_store::perch::adapters_dir();\n@@ -1154,6 +1075,7 @@ mod tests {\n //\n // The healthy instance beside the stale one is not decoration either: without\n // it, an implementation that healed EVERY record to offline would pass.\n+ // [unit->REQ-SHELL-HEAL-ENUMERATION]\n #[test]\n fn the_heal_writes_the_truth_once_and_then_leaves_the_record_alone() {\n crate::test_home::with_home(|_| {\n@@ -1166,15 +1088,13 @@ mod tests {\n )\n .unwrap();\n \n- // A STRANDED instance: record online, pid provably a corpse.\n- let stale = spawn_record(&owlery, \"ling\", \"alchemy\", None).unwrap();\n+ let stale = stranded_shell(&owlery, \"ling\", \"alchemy\", Some(1_000));\n+ let sibling = stranded_shell(&owlery, \"ling\", \"alchemy\", None);\n+ let pacer = stranded_shell(&owlery, \"ling\", \"pacer\", Some(2_000));\n+ seed_owner(&owlery, \"perri\");\n+ let other = stranded_shell(&owlery, \"perri\", \"alchemy\", None);\n let stale_perch =\n spt_store::perch::resolve_shell_perch_path_in(&owlery, \"ling\", &stale);\n- let mut info = shellinfo::read_shell_info(&stale_perch).unwrap();\n- info.status = SHELL_STATUS_ONLINE.to_string();\n- shellinfo::write_shell_info(&stale_perch, &info).unwrap();\n- std::fs::write(stale_perch.join(shellinfo::SHELL_PID_FILE), \"1\").unwrap();\n- shellinfo::record_shell_launch(&stale_perch, 1, 1_000);\n \n // A HEALTHY instance: record online over OUR OWN live pid, stamped by\n // its own launch. The heal must not touch it.\n@@ -1197,7 +1117,19 @@ mod tests {\n };\n let live_before = mtime(&live_perch);\n \n- heal_stale_online_records(&owlery);\n+ let mut events = Vec::new();\n+ heal_stale_online_records(&owlery, &mut events);\n+ let output = String::from_utf8(events).unwrap();\n+ let mut reported: Vec<_> = output.lines().collect();\n+ reported.sort();\n+ let mut expected = vec![\n+ format!(\"SHELL_RECORD_HEALED:ling/{stale}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:ling/{sibling}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:ling/{pacer}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:perri/{other}: online -> offline\"),\n+ ];\n+ expected.sort();\n+ assert_eq!(reported, expected, \"every healed instance, no healthy representative\");\n \n assert_eq!(\n shellinfo::read_shell_info(&stale_perch).unwrap().status,\n@@ -1219,7 +1151,9 @@ mod tests {\n // Second cycle over the now-correct records: nothing may be written.\n let stale_after_heal = mtime(&stale_perch);\n let live_after_heal = mtime(&live_perch);\n- heal_stale_online_records(&owlery);\n+ let mut repeated = Vec::new();\n+ heal_stale_online_records(&owlery, &mut repeated);\n+ assert!(repeated.is_empty(), \"already-healed records emit no duplicate events\");\n assert_eq!(\n (mtime(&stale_perch), mtime(&live_perch)),\n (stale_after_heal, live_after_heal),\n@@ -1228,17 +1162,8 @@ mod tests {\n });\n }\n \n- // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE] the boot discriminant's boundary,\n- // asserted from BOTH sides of it plus the slack band.\n- //\n- // The pair is what makes it evidence: a predicate answering \"yes\" to everything\n- // would restore force-killed shells (breaking the class-c ruling this\n- // discriminant exists to preserve), and one answering \"no\" to everything would\n- // restore nothing and still pass any single-sided row. The slack row is the\n- // third case and it is not decoration -- the boot instant is DERIVED (Windows:\n- // now minus uptime), so a process launched in the first moments after boot can\n- // compute as marginally older than boot itself, and without slack the sweep\n- // would relaunch something that had only just started.\n+ // [unit->REQ-HAZARD-SHELL-STALE-ONLINE]\n+ // Only the nonpersistent watcher freeze uses this boundary and slack band.\n #[test]\n fn only_a_launch_from_before_this_boot_is_a_restart_casualty() {\n const BOOT: u64 = 1_000_000;\n@@ -1263,214 +1188,127 @@ mod tests {\n );\n }\n \n- // [unit->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS] THE RESTART SHAPE, built\n- // WITHOUT a suspend edge — the row the existing cascade test cannot express.\n- //\n- // `rest_edges_cascade_shells_with_divergence` suspends first, and the suspend\n- // WRITES the offline record, so by the time its wake edge fires the instance is\n- // already in the state the to_active arm requires: that fixture can never\n- // observe this class. This one constructs the restart shape directly — a record\n- // left ONLINE over a corpse, a launch stamp from before boot, an online owner —\n- // and calls no rest path anywhere in its setup.\n- //\n- // Three instances, because the sweep is a CONJUNCTION and a single-instance\n- // fixture cannot tell a correct sweep from one that restores everything: the\n- // stranded one must come back, the one force-killed THIS boot must not, and the\n- // one whose owner is offline must not.\n- #[test]\n- fn the_boot_sweep_restores_only_the_restart_casualty_of_an_online_owner() {\n- let tmp = tempfile::tempdir().unwrap();\n- let owlery = tmp.path();\n- let boot = spt_store::proc::boot_instant_ms().expect(\"a boot instant on this platform\");\n-\n- // An ONLINE owner (seed_owner writes the `{}` record is_perch_alive reads as\n- // alive by interim parity) and an explicitly OFFLINE one.\n- seed_owner(owlery, \"ling\");\n- let gone = owlery.join(\"gone\");\n- std::fs::create_dir_all(&gone).unwrap();\n- std::fs::write(gone.join(\"info.json\"), \"{\\\"status\\\":\\\"offline\\\"}\").unwrap();\n-\n+ fn register_restore_adapter(adapters_dir: &Path, source: &Path, name: &str, persistent: bool) {\n #[cfg(windows)]\n let noop = \"cmd /c exit 0\";\n #[cfg(unix)]\n let noop = \"true\";\n- let adapters_dir = tmp.path().join(\"adapters\");\n- let src = tmp.path().join(\"srcs\").join(\"mock-boot\");\n- std::fs::create_dir_all(&src).unwrap();\n+ std::fs::create_dir_all(source).unwrap();\n std::fs::write(\n- src.join(\"manifest.toml\"),\n+ source.join(\"manifest.toml\"),\n format!(\n- \"[adapter]\\nname = \\\"mock-boot\\\"\\nkind = \\\"shell\\\"\\nversion = \\\"1\\\"\\n\\\n+ \"[adapter]\\nname = \\\"{name}\\\"\\nkind = \\\"shell\\\"\\nversion = \\\"1\\\"\\n\\\n min_spt_core_version = \\\"0\\\"\\n\\n[shell]\\nspawn = '{noop}'\\n\\\n- persistent = true\\n\"\n+ persistent = {persistent}\\n\"\n ),\n )\n .unwrap();\n- spt_runtime::registry::register(&adapters_dir, &src, 1).unwrap();\n- let registered = spt_runtime::registry::registered(&adapters_dir);\n+ spt_runtime::registry::register(adapters_dir, source, 1).unwrap();\n+ }\n \n- // Every instance is recorded ONLINE over a dead pid — the restart shape —\n- // and they differ ONLY in the gate under test.\n- let mk = |owner: &str, launched_ms: u64| -> String {\n- let id = spawn_record(owlery, owner, \"mock-boot\", None).unwrap();\n- let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n- let mut i = shellinfo::read_shell_info(&perch).unwrap();\n- i.status = SHELL_STATUS_ONLINE.to_string();\n- shellinfo::write_shell_info(&perch, &i).unwrap();\n- std::fs::write(perch.join(shellinfo::SHELL_PID_FILE), \"2000000000\").unwrap();\n- let launch = shellinfo::ShellLaunch {\n- pid_started_at: Some(1),\n- launched_ms,\n- };\n- std::fs::write(\n- perch.join(shellinfo::SHELL_LAUNCH_FILE),\n- serde_json::to_string(&launch).unwrap(),\n- )\n- .unwrap();\n- id\n- };\n- let stranded = mk(\"ling\", boot.saturating_sub(600_000)); // 10 min before boot\n- let force_killed = mk(\"ling\", boot + 120_000); // 2 min AFTER boot\n- let orphan_owner = mk(\"gone\", boot.saturating_sub(600_000));\n+ /// Restart-shaped record, with NO suspend edge to pre-heal its status.\n+ fn stranded_shell(owlery: &Path, owner: &str, adapter: &str, launched_ms: Option) -> String {\n+ let id = spawn_record(owlery, owner, adapter, None).unwrap();\n+ let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n+ let mut info = shellinfo::read_shell_info(&perch).unwrap();\n+ info.status = SHELL_STATUS_ONLINE.to_string();\n+ shellinfo::write_shell_info(&perch, &info).unwrap();\n+ std::fs::write(perch.join(shellinfo::SHELL_PID_FILE), \"2000000000\").unwrap();\n+ if let Some(launched_ms) = launched_ms {\n+ shellinfo::record_shell_launch(&perch, 2_000_000_000, launched_ms);\n+ }\n+ id\n+ }\n+\n+ // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n+ // [unit->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n+ #[test]\n+ fn boot_restores_all_down_persistent_instances_without_launch_age_gates() {\n+ let tmp = tempfile::tempdir().unwrap();\n+ let owlery = tmp.path();\n+ let boot = spt_store::proc::boot_instant_ms().expect(\"boot instant\");\n+ let adapters_dir = tmp.path().join(\"adapters\");\n+ register_restore_adapter(&adapters_dir, &tmp.path().join(\"keeper\"), \"keeper\", true);\n+ register_restore_adapter(&adapters_dir, &tmp.path().join(\"ordinary\"), \"ordinary\", false);\n+ let registered = spt_runtime::registry::registered(&adapters_dir);\n+ seed_owner(owlery, \"ling\");\n+ let gone = owlery.join(\"gone\");\n+ std::fs::create_dir_all(&gone).unwrap();\n+ std::fs::write(gone.join(\"info.json\"), \"{\\\"status\\\":\\\"offline\\\"}\").unwrap();\n \n- let restored = restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir);\n+ let before = stranded_shell(owlery, \"ling\", \"keeper\", Some(boot.saturating_sub(600_000)));\n+ let after = stranded_shell(owlery, \"ling\", \"keeper\", Some(boot + 120_000));\n+ let unstamped = stranded_shell(owlery, \"ling\", \"keeper\", None);\n+ stranded_shell(owlery, \"gone\", \"keeper\", None);\n+ stranded_shell(owlery, \"ling\", \"ordinary\", Some(boot + 120_000));\n \n\n[Artifact storage: ~/.omp/agent/sessions/-Documents-projects-spt-core/2026-09-09T23-45-42-317Z_01a08890-21ad-7000-8f54-208d4f4f2f2c/112.bash-original.log (105.3KB). Use artifact://112:N-M to page, artifact://112:raw:N-M for verbatim chunks, and the artifact file path for search/copy workflows.]\n\n[Showing lines 300-603 of 1088. Use :604 to continue]"}],"details":{"resolvedPath":"C:\\Users\\decid\\.omp\\agent\\sessions\\-Documents-projects-spt-core\\2026-09-09T23-45-42-317Z_01a08890-21ad-7000-8f54-208d4f4f2f2c\\112.bash-original.log","contentType":"text/plain","totalLines":1088,"displayContent":{"text":"-/// corpse-boot discriminant refuses that instance from then on. A FAILING launch\n-/// does not -- under a level trigger (\"the owner is online\") it would be retried\n-/// every [`RECONCILE_INTERVAL_MS`] for as long as the owner stayed up. The edge\n-/// bounds it to one attempt per owner-online event.\n+/// An edge bounds a failing launch to one attempt per owner-online event,\n+/// rather than retrying every reconcile tick while the owner remains online.\n+/// A successful launch is protected by birth-safe liveness even before bind.\n #[derive(Debug, Default)]\n pub struct OwnerOnlineEdge {\n /// Owner id -> online as of the last pass. An owner that disappears from the\n@@ -924,12 +867,8 @@ impl OwnerOnlineEdge {\n /// Daemons boot before endpoints do, so the boot sweep correctly skips an owner\n /// that is not up yet and, being once-per-generation, never revisits it; bringup\n /// from offline emits no rest edge either, so the ADR-0048 cascade does not cover\n-/// it. This is the trigger that does. Re-running the sweep's conjuncts is safe by\n-/// construction and not by convention: `launch_predates_boot` is MONOTONE within a\n-/// machine boot (every launch path restamps `launched_ms`, a kill never restamps,\n-/// `boot_ms` is the machine boot instant), so a later evaluation can only refuse\n-/// MORE. A shell an operator force-killed during this boot is refused here exactly\n-/// as it is refused at boot -- forever, and by the same predicate.\n+/// it. Both triggers use the same down-in-fact decision, without a machine-boot\n+/// or launch-stamp eligibility gate (releases#287).\n // [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n pub fn restore_persistent_shells_on_owner_online(\n@@ -943,11 +882,6 @@ pub fn restore_persistent_shells_on_owner_online(\n if owners.is_empty() {\n return Vec::new();\n }\n- let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n- // Same stance as the sweep's: no boot oracle => the discriminant cannot be\n- // evaluated => restore nothing.\n- return Vec::new();\n- };\n let mut restored = Vec::new();\n for owner in owners {\n restore_persistent_shells_of_owner(\n@@ -955,7 +889,6 @@ pub fn restore_persistent_shells_on_owner_online(\n registered,\n adapters_dir,\n &owner,\n- boot_ms,\n RestoreTrigger::OwnerOnline,\n Some(set),\n &mut restored,\n@@ -975,7 +908,7 @@ pub fn reconcile_once(\n // it below. Ordering matters -- the watcher-eligibility read further down asks\n // the RECORDED field, so a heal that ran after it would leave this cycle acting\n // on the stale value it just corrected.\n- heal_stale_online_records(owlery);\n+ heal_stale_online_records(owlery, &mut std::io::stderr().lock());\n \n // Stop side first: watchers whose instance is gone or no longer eligible.\n let live: Vec<(String, String)> = {\n@@ -995,14 +928,8 @@ pub fn reconcile_once(\n \n // Start side: every ELIGIBLE instance with a wake_command and headroom.\n //\n- // Eligibility is `watcher_eligible` — recorded status (never derived) AND the\n- // corpse-boot discriminant. Before leg (a) the recorded field was the whole\n- // guard: a force-killed instance kept a stale `online` record, which is what\n- // held it out of this set. That record now tells the truth, so the protection\n- // moved to the discriminant that states it directly (doyle, releases#78\n- // comment 5156810267) — the same `launch_predates_boot` leg (b) uses, so the\n- // freeze's forbidden behaviour stays forbidden by construction rather than by\n- // a second rule.\n+ // Persistent instances bypass the force-kill freeze; only nonpersistent\n+ // corpses need the pre-boot discriminant (releases#287).\n let boot_ms = spt_store::proc::boot_instant_ms();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n@@ -1010,12 +937,12 @@ pub fn reconcile_once(\n continue;\n }\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\n- if !watcher_eligible(&perch, &info, boot_ms) {\n- continue;\n- }\n let Some(shell) = shell_section_of(registered, adapters_dir, &info.adapter_name) else {\n continue; // deregistered adapter: nothing to run\n };\n+ if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\n+ continue;\n+ }\n let Some(wake_command) = shell.wake_command.as_deref() else {\n continue;\n };\n@@ -1078,15 +1005,9 @@ pub fn spawn_wake_host(stop: Arc) -> JoinHandle<()> {\n let set = Arc::new(WakeSet::new());\n let params = WakeParams::default();\n let mut owner_edge = OwnerOnlineEdge::new();\n- // ONCE per daemon generation, before the reconcile loop: bring back the\n- // persistent shells a node restart stranded (releases#78 leg b). Outside\n- // the loop because a node restart is a boot event -- but NOT because\n- // once-ness protects the operator-force-kill ruling: it does not, and a\n- // comment here used to say it did. `launch_predates_boot` is what protects\n- // it, on every evaluation (`reconcile_once`'s start-side comment records\n- // that ruling; doyle re-measured it on releases#228). The steady-state\n- // half -- an owner that comes online AFTER this sweep -- is covered in the\n- // loop below, which is exactly the re-evaluation the false comment forbade.\n+ // Once per daemon generation, restore down persistent shells of owners\n+ // already online. Owners arriving later are covered by the edge below.\n+ // Neither trigger gates persistence on machine boot or launch age.\n {\n let owlery = spt_store::perch::owlery_dir();\n let adapters_dir = spt_store::perch::adapters_dir();\n@@ -1154,6 +1075,7 @@ mod tests {\n //\n // The healthy instance beside the stale one is not decoration either: without\n // it, an implementation that healed EVERY record to offline would pass.\n+ // [unit->REQ-SHELL-HEAL-ENUMERATION]\n #[test]\n fn the_heal_writes_the_truth_once_and_then_leaves_the_record_alone() {\n crate::test_home::with_home(|_| {\n@@ -1166,15 +1088,13 @@ mod tests {\n )\n .unwrap();\n \n- // A STRANDED instance: record online, pid provably a corpse.\n- let stale = spawn_record(&owlery, \"ling\", \"alchemy\", None).unwrap();\n+ let stale = stranded_shell(&owlery, \"ling\", \"alchemy\", Some(1_000));\n+ let sibling = stranded_shell(&owlery, \"ling\", \"alchemy\", None);\n+ let pacer = stranded_shell(&owlery, \"ling\", \"pacer\", Some(2_000));\n+ seed_owner(&owlery, \"perri\");\n+ let other = stranded_shell(&owlery, \"perri\", \"alchemy\", None);\n let stale_perch =\n spt_store::perch::resolve_shell_perch_path_in(&owlery, \"ling\", &stale);\n- let mut info = shellinfo::read_shell_info(&stale_perch).unwrap();\n- info.status = SHELL_STATUS_ONLINE.to_string();\n- shellinfo::write_shell_info(&stale_perch, &info).unwrap();\n- std::fs::write(stale_perch.join(shellinfo::SHELL_PID_FILE), \"1\").unwrap();\n- shellinfo::record_shell_launch(&stale_perch, 1, 1_000);\n \n // A HEALTHY instance: record online over OUR OWN live pid, stamped by\n // its own launch. The heal must not touch it.\n@@ -1197,7 +1117,19 @@ mod tests {\n };\n let live_before = mtime(&live_perch);\n \n- heal_stale_online_records(&owlery);\n+ let mut events = Vec::new();\n+ heal_stale_online_records(&owlery, &mut events);\n+ let output = String::from_utf8(events).unwrap();\n+ let mut reported: Vec<_> = output.lines().collect();\n+ reported.sort();\n+ let mut expected = vec![\n+ format!(\"SHELL_RECORD_HEALED:ling/{stale}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:ling/{sibling}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:ling/{pacer}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:perri/{other}: online -> offline\"),\n+ ];\n+ expected.sort();\n+ assert_eq!(reported, expected, \"every healed instance, no healthy representative\");\n \n assert_eq!(\n shellinfo::read_shell_info(&stale_perch).unwrap().status,\n@@ -1219,7 +1151,9 @@ mod tests {\n // Second cycle over the now-correct records: nothing may be written.\n let stale_after_heal = mtime(&stale_perch);\n let live_after_heal = mtime(&live_perch);\n- heal_stale_online_records(&owlery);\n+ let mut repeated = Vec::new();\n+ heal_stale_online_records(&owlery, &mut repeated);\n+ assert!(repeated.is_empty(), \"already-healed records emit no duplicate events\");\n assert_eq!(\n (mtime(&stale_perch), mtime(&live_perch)),\n (stale_after_heal, live_after_heal),\n@@ -1228,17 +1162,8 @@ mod tests {\n });\n }\n \n- // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE] the boot discriminant's boundary,\n- // asserted from BOTH sides of it plus the slack band.\n- //\n- // The pair is what makes it evidence: a predicate answering \"yes\" to everything\n- // would restore force-killed shells (breaking the class-c ruling this\n- // discriminant exists to preserve), and one answering \"no\" to everything would\n- // restore nothing and still pass any single-sided row. The slack row is the\n- // third case and it is not decoration -- the boot instant is DERIVED (Windows:\n- // now minus uptime), so a process launched in the first moments after boot can\n- // compute as marginally older than boot itself, and without slack the sweep\n- // would relaunch something that had only just started.\n+ // [unit->REQ-HAZARD-SHELL-STALE-ONLINE]\n+ // Only the nonpersistent watcher freeze uses this boundary and slack band.\n #[test]\n fn only_a_launch_from_before_this_boot_is_a_restart_casualty() {\n const BOOT: u64 = 1_000_000;\n@@ -1263,214 +1188,127 @@ mod tests {\n );\n }\n \n- // [unit->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS] THE RESTART SHAPE, built\n- // WITHOUT a suspend edge — the row the existing cascade test cannot express.\n- //\n- // `rest_edges_cascade_shells_with_divergence` suspends first, and the suspend\n- // WRITES the offline record, so by the time its wake edge fires the instance is\n- // already in the state the to_active arm requires: that fixture can never\n- // observe this class. This one constructs the restart shape directly — a record\n- // left ONLINE over a corpse, a launch stamp from before boot, an online owner —\n- // and calls no rest path anywhere in its setup.\n- //\n- // Three instances, because the sweep is a CONJUNCTION and a single-instance\n- // fixture cannot tell a correct sweep from one that restores everything: the\n- // stranded one must come back, the one force-killed THIS boot must not, and the\n- // one whose owner is offline must not.\n- #[test]\n- fn the_boot_sweep_restores_only_the_restart_casualty_of_an_online_owner() {\n- let tmp = tempfile::tempdir().unwrap();\n- let owlery = tmp.path();\n- let boot = spt_store::proc::boot_instant_ms().expect(\"a boot instant on this platform\");\n-\n- // An ONLINE owner (seed_owner writes the `{}` record is_perch_alive reads as\n- // alive by interim parity) and an explicitly OFFLINE one.\n- seed_owner(owlery, \"ling\");\n- let gone = owlery.join(\"gone\");\n- std::fs::create_dir_all(&gone).unwrap();\n- std::fs::write(gone.join(\"info.json\"), \"{\\\"status\\\":\\\"offline\\\"}\").unwrap();\n-\n+ fn register_restore_adapter(adapters_dir: &Path, source: &Path, name: &str, persistent: bool) {\n #[cfg(windows)]\n let noop = \"cmd /c exit 0\";\n #[cfg(unix)]\n let noop = \"true\";\n- let adapters_dir = tmp.path().join(\"adapters\");\n- let src = tmp.path().join(\"srcs\").join(\"mock-boot\");\n- std::fs::create_dir_all(&src).unwrap();\n+ std::fs::create_dir_all(source).unwrap();\n std::fs::write(\n- src.join(\"manifest.toml\"),\n+ source.join(\"manifest.toml\"),\n format!(\n- \"[adapter]\\nname = \\\"mock-boot\\\"\\nkind = \\\"shell\\\"\\nversion = \\\"1\\\"\\n\\\n+ \"[adapter]\\nname = \\\"{name}\\\"\\nkind = \\\"shell\\\"\\nversion = \\\"1\\\"\\n\\\n min_spt_core_version = \\\"0\\\"\\n\\n[shell]\\nspawn = '{noop}'\\n\\\n- persistent = true\\n\"\n+ persistent = {persistent}\\n\"\n ),\n )\n .unwrap();\n- spt_runtime::registry::register(&adapters_dir, &src, 1).unwrap();\n- let registered = spt_runtime::registry::registered(&adapters_dir);\n+ spt_runtime::registry::register(adapters_dir, source, 1).unwrap();\n+ }\n \n- // Every instance is recorded ONLINE over a dead pid — the restart shape —\n- // and they differ ONLY in the gate under test.\n- let mk = |owner: &str, launched_ms: u64| -> String {\n- let id = spawn_record(owlery, owner, \"mock-boot\", None).unwrap();\n- let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n- let mut i = shellinfo::read_shell_info(&perch).unwrap();\n- i.status = SHELL_STATUS_ONLINE.to_string();\n- shellinfo::write_shell_info(&perch, &i).unwrap();\n- std::fs::write(perch.join(shellinfo::SHELL_PID_FILE), \"2000000000\").unwrap();\n- let launch = shellinfo::ShellLaunch {\n- pid_started_at: Some(1),\n- launched_ms,\n- };\n- std::fs::write(\n- perch.join(shellinfo::SHELL_LAUNCH_FILE),\n- serde_json::to_string(&launch).unwrap(),\n- )\n- .unwrap();\n- id\n- };\n- let stranded = mk(\"ling\", boot.saturating_sub(600_000)); // 10 min before boot\n- let force_killed = mk(\"ling\", boot + 120_000); // 2 min AFTER boot\n- let orphan_owner = mk(\"gone\", boot.saturating_sub(600_000));\n+ /// Restart-shaped record, with NO suspend edge to pre-heal its status.\n+ fn stranded_shell(owlery: &Path, owner: &str, adapter: &str, launched_ms: Option) -> String {\n+ let id = spawn_record(owlery, owner, adapter, None).unwrap();\n+ let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n+ let mut info = shellinfo::read_shell_info(&perch).unwrap();\n+ info.status = SHELL_STATUS_ONLINE.to_string();\n+ shellinfo::write_shell_info(&perch, &info).unwrap();\n+ std::fs::write(perch.join(shellinfo::SHELL_PID_FILE), \"2000000000\").unwrap();\n+ if let Some(launched_ms) = launched_ms {\n+ shellinfo::record_shell_launch(&perch, 2_000_000_000, launched_ms);\n+ }\n+ id\n+ }\n+\n+ // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n+ // [unit->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n+ #[test]\n+ fn boot_restores_all_down_persistent_instances_without_launch_age_gates() {\n+ let tmp = tempfile::tempdir().unwrap();\n+ let owlery = tmp.path();\n+ let boot = spt_store::proc::boot_instant_ms().expect(\"boot instant\");\n+ let adapters_dir = tmp.path().join(\"adapters\");\n+ register_restore_adapter(&adapters_dir, &tmp.path().join(\"keeper\"), \"keeper\", true);\n+ register_restore_adapter(&adapters_dir, &tmp.path().join(\"ordinary\"), \"ordinary\", false);\n+ let registered = spt_runtime::registry::registered(&adapters_dir);\n+ seed_owner(owlery, \"ling\");\n+ let gone = owlery.join(\"gone\");\n+ std::fs::create_dir_all(&gone).unwrap();\n+ std::fs::write(gone.join(\"info.json\"), \"{\\\"status\\\":\\\"offline\\\"}\").unwrap();\n \n- let restored = restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir);\n+ let before = stranded_shell(owlery, \"ling\", \"keeper\", Some(boot.saturating_sub(600_000)));\n+ let after = stranded_shell(owlery, \"ling\", \"keeper\", Some(boot + 120_000));\n+ let unstamped = stranded_shell(owlery, \"ling\", \"keeper\", None);\n+ stranded_shell(owlery, \"gone\", \"keeper\", None);\n+ stranded_shell(owlery, \"ling\", \"ordinary\", Some(boot + 120_000));\n ","startLine":300,"lineNumbers":[300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,418,419,420,421,422,423,424,425,426,427,428,429,430,431,432,433,434,435,436,437,438,439,440,441,442,443,444,445,446,447,448,449,450,451,452,453,454,455,456,457,458,459,460,461,462,463,464,465,466,467,468,469,470,471,472,473,474,475,476,477,478,479,480,481,482,483,484,485,486,487,488,489,490,491,492,493,494,495,496,497,498,499,500,501,502,503,504,505,506,507,508,509,510,511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532,533,534,535,536,537,538,539,540,541,542,543,544,545,546,547,548,549,550,551,552,553,554,555,556,557,558,559,560,561,562,563,564,565,566,567,568,569,570,571,572,573,574,575,576,577,578,579,580,581,582,583,584,585,586,587,588,589,590,591,592,593,594,595,596,597,598,599,600,601,602,603]},"truncation":{"content":"-/// corpse-boot discriminant refuses that instance from then on. A FAILING launch\n-/// does not -- under a level trigger (\"the owner is online\") it would be retried\n-/// every [`RECONCILE_INTERVAL_MS`] for as long as the owner stayed up. The edge\n-/// bounds it to one attempt per owner-online event.\n+/// An edge bounds a failing launch to one attempt per owner-online event,\n+/// rather than retrying every reconcile tick while the owner remains online.\n+/// A successful launch is protected by birth-safe liveness even before bind.\n #[derive(Debug, Default)]\n pub struct OwnerOnlineEdge {\n /// Owner id -> online as of the last pass. An owner that disappears from the\n@@ -924,12 +867,8 @@ impl OwnerOnlineEdge {\n /// Daemons boot before endpoints do, so the boot sweep correctly skips an owner\n /// that is not up yet and, being once-per-generation, never revisits it; bringup\n /// from offline emits no rest edge either, so the ADR-0048 cascade does not cover\n-/// it. This is the trigger that does. Re-running the sweep's conjuncts is safe by\n-/// construction and not by convention: `launch_predates_boot` is MONOTONE within a\n-/// machine boot (every launch path restamps `launched_ms`, a kill never restamps,\n-/// `boot_ms` is the machine boot instant), so a later evaluation can only refuse\n-/// MORE. A shell an operator force-killed during this boot is refused here exactly\n-/// as it is refused at boot -- forever, and by the same predicate.\n+/// it. Both triggers use the same down-in-fact decision, without a machine-boot\n+/// or launch-stamp eligibility gate (releases#287).\n // [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n // [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n pub fn restore_persistent_shells_on_owner_online(\n@@ -943,11 +882,6 @@ pub fn restore_persistent_shells_on_owner_online(\n if owners.is_empty() {\n return Vec::new();\n }\n- let Some(boot_ms) = spt_store::proc::boot_instant_ms() else {\n- // Same stance as the sweep's: no boot oracle => the discriminant cannot be\n- // evaluated => restore nothing.\n- return Vec::new();\n- };\n let mut restored = Vec::new();\n for owner in owners {\n restore_persistent_shells_of_owner(\n@@ -955,7 +889,6 @@ pub fn restore_persistent_shells_on_owner_online(\n registered,\n adapters_dir,\n &owner,\n- boot_ms,\n RestoreTrigger::OwnerOnline,\n Some(set),\n &mut restored,\n@@ -975,7 +908,7 @@ pub fn reconcile_once(\n // it below. Ordering matters -- the watcher-eligibility read further down asks\n // the RECORDED field, so a heal that ran after it would leave this cycle acting\n // on the stale value it just corrected.\n- heal_stale_online_records(owlery);\n+ heal_stale_online_records(owlery, &mut std::io::stderr().lock());\n \n // Stop side first: watchers whose instance is gone or no longer eligible.\n let live: Vec<(String, String)> = {\n@@ -995,14 +928,8 @@ pub fn reconcile_once(\n \n // Start side: every ELIGIBLE instance with a wake_command and headroom.\n //\n- // Eligibility is `watcher_eligible` — recorded status (never derived) AND the\n- // corpse-boot discriminant. Before leg (a) the recorded field was the whole\n- // guard: a force-killed instance kept a stale `online` record, which is what\n- // held it out of this set. That record now tells the truth, so the protection\n- // moved to the discriminant that states it directly (doyle, releases#78\n- // comment 5156810267) — the same `launch_predates_boot` leg (b) uses, so the\n- // freeze's forbidden behaviour stays forbidden by construction rather than by\n- // a second rule.\n+ // Persistent instances bypass the force-kill freeze; only nonpersistent\n+ // corpses need the pre-boot discriminant (releases#287).\n let boot_ms = spt_store::proc::boot_instant_ms();\n for owner in spt_store::perch::list_self_perch_ids(owlery) {\n for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n@@ -1010,12 +937,12 @@ pub fn reconcile_once(\n continue;\n }\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, &owner, &shell_id);\n- if !watcher_eligible(&perch, &info, boot_ms) {\n- continue;\n- }\n let Some(shell) = shell_section_of(registered, adapters_dir, &info.adapter_name) else {\n continue; // deregistered adapter: nothing to run\n };\n+ if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\n+ continue;\n+ }\n let Some(wake_command) = shell.wake_command.as_deref() else {\n continue;\n };\n@@ -1078,15 +1005,9 @@ pub fn spawn_wake_host(stop: Arc) -> JoinHandle<()> {\n let set = Arc::new(WakeSet::new());\n let params = WakeParams::default();\n let mut owner_edge = OwnerOnlineEdge::new();\n- // ONCE per daemon generation, before the reconcile loop: bring back the\n- // persistent shells a node restart stranded (releases#78 leg b). Outside\n- // the loop because a node restart is a boot event -- but NOT because\n- // once-ness protects the operator-force-kill ruling: it does not, and a\n- // comment here used to say it did. `launch_predates_boot` is what protects\n- // it, on every evaluation (`reconcile_once`'s start-side comment records\n- // that ruling; doyle re-measured it on releases#228). The steady-state\n- // half -- an owner that comes online AFTER this sweep -- is covered in the\n- // loop below, which is exactly the re-evaluation the false comment forbade.\n+ // Once per daemon generation, restore down persistent shells of owners\n+ // already online. Owners arriving later are covered by the edge below.\n+ // Neither trigger gates persistence on machine boot or launch age.\n {\n let owlery = spt_store::perch::owlery_dir();\n let adapters_dir = spt_store::perch::adapters_dir();\n@@ -1154,6 +1075,7 @@ mod tests {\n //\n // The healthy instance beside the stale one is not decoration either: without\n // it, an implementation that healed EVERY record to offline would pass.\n+ // [unit->REQ-SHELL-HEAL-ENUMERATION]\n #[test]\n fn the_heal_writes_the_truth_once_and_then_leaves_the_record_alone() {\n crate::test_home::with_home(|_| {\n@@ -1166,15 +1088,13 @@ mod tests {\n )\n .unwrap();\n \n- // A STRANDED instance: record online, pid provably a corpse.\n- let stale = spawn_record(&owlery, \"ling\", \"alchemy\", None).unwrap();\n+ let stale = stranded_shell(&owlery, \"ling\", \"alchemy\", Some(1_000));\n+ let sibling = stranded_shell(&owlery, \"ling\", \"alchemy\", None);\n+ let pacer = stranded_shell(&owlery, \"ling\", \"pacer\", Some(2_000));\n+ seed_owner(&owlery, \"perri\");\n+ let other = stranded_shell(&owlery, \"perri\", \"alchemy\", None);\n let stale_perch =\n spt_store::perch::resolve_shell_perch_path_in(&owlery, \"ling\", &stale);\n- let mut info = shellinfo::read_shell_info(&stale_perch).unwrap();\n- info.status = SHELL_STATUS_ONLINE.to_string();\n- shellinfo::write_shell_info(&stale_perch, &info).unwrap();\n- std::fs::write(stale_perch.join(shellinfo::SHELL_PID_FILE), \"1\").unwrap();\n- shellinfo::record_shell_launch(&stale_perch, 1, 1_000);\n \n // A HEALTHY instance: record online over OUR OWN live pid, stamped by\n // its own launch. The heal must not touch it.\n@@ -1197,7 +1117,19 @@ mod tests {\n };\n let live_before = mtime(&live_perch);\n \n- heal_stale_online_records(&owlery);\n+ let mut events = Vec::new();\n+ heal_stale_online_records(&owlery, &mut events);\n+ let output = String::from_utf8(events).unwrap();\n+ let mut reported: Vec<_> = output.lines().collect();\n+ reported.sort();\n+ let mut expected = vec![\n+ format!(\"SHELL_RECORD_HEALED:ling/{stale}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:ling/{sibling}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:ling/{pacer}: online -> offline\"),\n+ format!(\"SHELL_RECORD_HEALED:perri/{other}: online -> offline\"),\n+ ];\n+ expected.sort();\n+ assert_eq!(reported, expected, \"every healed instance, no healthy representative\");\n \n assert_eq!(\n shellinfo::read_shell_info(&stale_perch).unwrap().status,\n@@ -1219,7 +1151,9 @@ mod tests {\n // Second cycle over the now-correct records: nothing may be written.\n let stale_after_heal = mtime(&stale_perch);\n let live_after_heal = mtime(&live_perch);\n- heal_stale_online_records(&owlery);\n+ let mut repeated = Vec::new();\n+ heal_stale_online_records(&owlery, &mut repeated);\n+ assert!(repeated.is_empty(), \"already-healed records emit no duplicate events\");\n assert_eq!(\n (mtime(&stale_perch), mtime(&live_perch)),\n (stale_after_heal, live_after_heal),\n@@ -1228,17 +1162,8 @@ mod tests {\n });\n }\n \n- // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE] the boot discriminant's boundary,\n- // asserted from BOTH sides of it plus the slack band.\n- //\n- // The pair is what makes it evidence: a predicate answering \"yes\" to everything\n- // would restore force-killed shells (breaking the class-c ruling this\n- // discriminant exists to preserve), and one answering \"no\" to everything would\n- // restore nothing and still pass any single-sided row. The slack row is the\n- // third case and it is not decoration -- the boot instant is DERIVED (Windows:\n- // now minus uptime), so a process launched in the first moments after boot can\n- // compute as marginally older than boot itself, and without slack the sweep\n- // would relaunch something that had only just started.\n+ // [unit->REQ-HAZARD-SHELL-STALE-ONLINE]\n+ // Only the nonpersistent watcher freeze uses this boundary and slack band.\n #[test]\n fn only_a_launch_from_before_this_boot_is_a_restart_casualty() {\n const BOOT: u64 = 1_000_000;\n@@ -1263,214 +1188,127 @@ mod tests {\n );\n }\n \n- // [unit->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS] THE RESTART SHAPE, built\n- // WITHOUT a suspend edge — the row the existing cascade test cannot express.\n- //\n- // `rest_edges_cascade_shells_with_divergence` suspends first, and the suspend\n- // WRITES the offline record, so by the time its wake edge fires the instance is\n- // already in the state the to_active arm requires: that fixture can never\n- // observe this class. This one constructs the restart shape directly — a record\n- // left ONLINE over a corpse, a launch stamp from before boot, an online owner —\n- // and calls no rest path anywhere in its setup.\n- //\n- // Three instances, because the sweep is a CONJUNCTION and a single-instance\n- // fixture cannot tell a correct sweep from one that restores everything: the\n- // stranded one must come back, the one force-killed THIS boot must not, and the\n- // one whose owner is offline must not.\n- #[test]\n- fn the_boot_sweep_restores_only_the_restart_casualty_of_an_online_owner() {\n- let tmp = tempfile::tempdir().unwrap();\n- let owlery = tmp.path();\n- let boot = spt_store::proc::boot_instant_ms().expect(\"a boot instant on this platform\");\n-\n- // An ONLINE owner (seed_owner writes the `{}` record is_perch_alive reads as\n- // alive by interim parity) and an explicitly OFFLINE one.\n- seed_owner(owlery, \"ling\");\n- let gone = owlery.join(\"gone\");\n- std::fs::create_dir_all(&gone).unwrap();\n- std::fs::write(gone.join(\"info.json\"), \"{\\\"status\\\":\\\"offline\\\"}\").unwrap();\n-\n+ fn register_restore_adapter(adapters_dir: &Path, source: &Path, name: &str, persistent: bool) {\n #[cfg(windows)]\n let noop = \"cmd /c exit 0\";\n #[cfg(unix)]\n let noop = \"true\";\n- let adapters_dir = tmp.path().join(\"adapters\");\n- let src = tmp.path().join(\"srcs\").join(\"mock-boot\");\n- std::fs::create_dir_all(&src).unwrap();\n+ std::fs::create_dir_all(source).unwrap();\n std::fs::write(\n- src.join(\"manifest.toml\"),\n+ source.join(\"manifest.toml\"),\n format!(\n- \"[adapter]\\nname = \\\"mock-boot\\\"\\nkind = \\\"shell\\\"\\nversion = \\\"1\\\"\\n\\\n+ \"[adapter]\\nname = \\\"{name}\\\"\\nkind = \\\"shell\\\"\\nversion = \\\"1\\\"\\n\\\n min_spt_core_version = \\\"0\\\"\\n\\n[shell]\\nspawn = '{noop}'\\n\\\n- persistent = true\\n\"\n+ persistent = {persistent}\\n\"\n ),\n )\n .unwrap();\n- spt_runtime::registry::register(&adapters_dir, &src, 1).unwrap();\n- let registered = spt_runtime::registry::registered(&adapters_dir);\n+ spt_runtime::registry::register(adapters_dir, source, 1).unwrap();\n+ }\n \n- // Every instance is recorded ONLINE over a dead pid — the restart shape —\n- // and they differ ONLY in the gate under test.\n- let mk = |owner: &str, launched_ms: u64| -> String {\n- let id = spawn_record(owlery, owner, \"mock-boot\", None).unwrap();\n- let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n- let mut i = shellinfo::read_shell_info(&perch).unwrap();\n- i.status = SHELL_STATUS_ONLINE.to_string();\n- shellinfo::write_shell_info(&perch, &i).unwrap();\n- std::fs::write(perch.join(shellinfo::SHELL_PID_FILE), \"2000000000\").unwrap();\n- let launch = shellinfo::ShellLaunch {\n- pid_started_at: Some(1),\n- launched_ms,\n- };\n- std::fs::write(\n- perch.join(shellinfo::SHELL_LAUNCH_FILE),\n- serde_json::to_string(&launch).unwrap(),\n- )\n- .unwrap();\n- id\n- };\n- let stranded = mk(\"ling\", boot.saturating_sub(600_000)); // 10 min before boot\n- let force_killed = mk(\"ling\", boot + 120_000); // 2 min AFTER boot\n- let orphan_owner = mk(\"gone\", boot.saturating_sub(600_000));\n+ /// Restart-shaped record, with NO suspend edge to pre-heal its status.\n+ fn stranded_shell(owlery: &Path, owner: &str, adapter: &str, launched_ms: Option) -> String {\n+ let id = spawn_record(owlery, owner, adapter, None).unwrap();\n+ let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n+ let mut info = shellinfo::read_shell_info(&perch).unwrap();\n+ info.status = SHELL_STATUS_ONLINE.to_string();\n+ shellinfo::write_shell_info(&perch, &info).unwrap();\n+ std::fs::write(perch.join(shellinfo::SHELL_PID_FILE), \"2000000000\").unwrap();\n+ if let Some(launched_ms) = launched_ms {\n+ shellinfo::record_shell_launch(&perch, 2_000_000_000, launched_ms);\n+ }\n+ id\n+ }\n+\n+ // [unit->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n+ // [unit->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n+ #[test]\n+ fn boot_restores_all_down_persistent_instances_without_launch_age_gates() {\n+ let tmp = tempfile::tempdir().unwrap();\n+ let owlery = tmp.path();\n+ let boot = spt_store::proc::boot_instant_ms().expect(\"boot instant\");\n+ let adapters_dir = tmp.path().join(\"adapters\");\n+ register_restore_adapter(&adapters_dir, &tmp.path().join(\"keeper\"), \"keeper\", true);\n+ register_restore_adapter(&adapters_dir, &tmp.path().join(\"ordinary\"), \"ordinary\", false);\n+ let registered = spt_runtime::registry::registered(&adapters_dir);\n+ seed_owner(owlery, \"ling\");\n+ let gone = owlery.join(\"gone\");\n+ std::fs::create_dir_all(&gone).unwrap();\n+ std::fs::write(gone.join(\"info.json\"), \"{\\\"status\\\":\\\"offline\\\"}\").unwrap();\n \n- let restored = restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir);\n+ let before = stranded_shell(owlery, \"ling\", \"keeper\", Some(boot.saturating_sub(600_000)));\n+ let after = stranded_shell(owlery, \"ling\", \"keeper\", Some(boot + 120_000));\n+ let unstamped = stranded_shell(owlery, \"ling\", \"keeper\", None);\n+ stranded_shell(owlery, \"gone\", \"keeper\", None);\n+ stranded_shell(owlery, \"ling\", \"ordinary\", Some(boot + 120_000));\n ","truncated":true,"truncatedBy":"lines","totalLines":789,"totalBytes":16726,"outputLines":304,"outputBytes":16726,"lastLinePartial":false,"firstLineExceedsLimit":false},"meta":{"source":{"type":"internal","value":"artifact://112"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":1088,"totalBytes":16726,"outputLines":304,"outputBytes":16726,"maxBytes":155648,"shownRange":{"start":300,"end":603},"nextOffset":604}}},"isError":false,"timestamp":1789001136975}}
{"type":"message","id":"a9a384e5","parentId":"ca63b887","timestamp":"2026-09-10T00:45:38.097Z","message":{"role":"toolResult","toolCallId":"call_8hv8qzFRDNvgINDHIrh0G52O|fc_077f3569365e313d016aa1fdb0c09887d1bad4b5b5fc3d8749","toolName":"grep","content":[{"type":"text","text":"# .worktrees/287-shellrestore/crates/spt-daemon/src/\n## drivehub.rs\n 294|/// **The recorded live pid arbitrates, on BOTH sides**\n*295|/// ([`crate::shellhost::live_launch_winner`]). Whoever is second sees the\n 296|/// other's `shell.pid` probing alive, stands down, and ADOPTS that pid as the\n 297|/// launch's outcome — a success, not a fault: the caller asked for a running\n 298|/// binary and there is one. The daemon-side loser reports\n## linkhost.rs\n 737| let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n*738| if let Some(pid) = shellhost::live_launch_winner(&perch) {\n 739| spt_proto::emit_line_err!(\"SHELL_LAUNCH_STOOD_DOWN:{id}: already launched pid={pid} (online at bind)\");\n 740| return Ok(pid);\n 741| }\n## shellhost.rs\n 319|// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n*320|pub fn live_launch_winner(shell_perch: &Path) -> Option {\n 321| shellinfo::read_shell_pid(shell_perch)\n 322| .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\n 323|}\n...\n 430| || {\n*431| live_launch_winner(&spt_store::perch::resolve_shell_perch_path_in(\n 432| owlery, owner, shell_id,\n 433| ))\n 434| },\n...\n 1210|\n*1211| assert_eq!(live_launch_winner(perch), None, \"no pid file ⇒ no winner\");\n 1212|\n 1213| std::fs::write(perch.join(SHELL_PID_FILE), \"0\").unwrap();\n*1214| assert_eq!(live_launch_winner(perch), None, \"pid 0 ⇒ no winner\");\n 1215|\n 1216| std::fs::write(perch.join(SHELL_PID_FILE), \"not-a-pid\").unwrap();\n*1217| assert_eq!(live_launch_winner(perch), None, \"unparseable ⇒ no winner\");\n 1218|\n 1219| // This test process is, definitionally, alive.\n 1220| let me = std::process::id();\n...\n 1222| assert_eq!(\n*1223| live_launch_winner(perch),\n 1224| Some(me),\n 1225| \"a recorded pid that probes alive IS the winner\"\n 1226| );\n 1227| shellinfo::record_shell_launch(perch, me, 1_000);\n*1228| assert_eq!(live_launch_winner(perch), Some(me), \"same birth retains custody\");\n 1229| let mut launch = shellinfo::read_shell_launch(perch).unwrap();\n 1230| launch.pid_started_at = Some(\n 1231| launch.pid_started_at.expect(\"native birth stamp on supported platforms\") ^ 1,\n...\n 1237| .unwrap();\n*1238| assert_eq!(live_launch_winner(perch), None, \"a recycled pid cannot block restore\");\n 1239| }\n 1240|\n 1241| // [unit->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE] a REAL dial at a socket name\n## shellwake.rs\n 615|// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n*616|fn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n 617| for owner in spt_store::perch::list_self_perch_ids(owlery) {\n 618| for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n 619| if info.status != SHELL_STATUS_ONLINE {\n...\n 662|// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n*663|fn watcher_eligible(\n 664| perch: &Path,\n 665| info: &shellinfo::ShellInfo,\n 666| persistent: bool,\n...\n 671| }\n*672| if crate::shellhost::live_launch_winner(perch).is_some() {\n 673| return false; // binding: the shell binary and watcher must not overlap\n 674| }\n 675| if persistent || !shellinfo::shell_pid_provably_dead(perch) {\n...\n 733|// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n*734|fn restore_persistent_shells_of_owner(\n 735| owlery: &Path,\n 736| registered: &[(AdapterRecord, Manifest)],\n 737| adapters_dir: &Path,\n...\n 754| if shellinfo::is_shell_online(&perch, &info)\n*755| || crate::shellhost::live_launch_winner(&perch).is_some()\n 756| {\n 757| continue; // already online or binding in fact\n 758| }\n...\n 788|/// endpoint that comes online after this sweep is covered by\n*789|/// [`restore_persistent_shells_on_owner_online`] (releases#228), running the same\n*790|/// [`restore_persistent_shells_of_owner`] body -- but it is the one that needs no\n 791|/// trigger at all, since a node restart is what strands the shells to begin with.\n 792|// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n 793|// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n*794|pub fn restore_persistent_shells_at_boot(\n 795| owlery: &Path,\n 796| registered: &[(AdapterRecord, Manifest)],\n 797| adapters_dir: &Path,\n...\n 800| for owner in spt_store::perch::list_self_perch_ids(owlery) {\n*801| restore_persistent_shells_of_owner(\n 802| owlery,\n 803| registered,\n 804| adapters_dir,\n...\n 873|// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n*874|pub fn restore_persistent_shells_on_owner_online(\n 875| owlery: &Path,\n 876| registered: &[(AdapterRecord, Manifest)],\n 877| adapters_dir: &Path,\n...\n 886| for owner in owners {\n*887| restore_persistent_shells_of_owner(\n 888| owlery,\n 889| registered,\n 890| adapters_dir,\n...\n 910| // on the stale value it just corrected.\n*911| heal_stale_online_records(owlery, &mut std::io::stderr().lock());\n 912|\n 913| // Stop side first: watchers whose instance is gone or no longer eligible.\n 914| let live: Vec<(String, String)> = {\n...\n 942| };\n*943| if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\n 944| continue;\n 945| }\n 946| let Some(wake_command) = shell.wake_command.as_deref() else {\n...\n 1017| owner_edge.seed(&owlery);\n*1018| restore_persistent_shells_at_boot(&owlery, ®istered, &adapters_dir);\n 1019| }\n 1020| while !stop.load(Ordering::SeqCst) {\n 1021| let owlery = spt_store::perch::owlery_dir();\n...\n 1026| // would otherwise arm a watcher for the shell we are about to launch.\n*1027| restore_persistent_shells_on_owner_online(\n 1028| &owlery,\n 1029| ®istered,\n 1030| &adapters_dir,\n...\n 1120| let mut events = Vec::new();\n*1121| heal_stale_online_records(&owlery, &mut events);\n 1122| let output = String::from_utf8(events).unwrap();\n 1123| let mut reported: Vec<_> = output.lines().collect();\n 1124| reported.sort();\n...\n 1154| let mut repeated = Vec::new();\n*1155| heal_stale_online_records(&owlery, &mut repeated);\n 1156| assert!(repeated.is_empty(), \"already-healed records emit no duplicate events\");\n 1157| assert_eq!(\n 1158| (mtime(&stale_perch), mtime(&live_perch)),\n...\n 1255|\n*1256| let mut restored = restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir);\n 1257| restored.sort();\n 1258| let mut expected = vec![\n 1259| format!(\"ling/{before}\"),\n...\n 1286| edge.seed(owlery);\n*1287| assert!(restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir).is_empty());\n 1288|\n 1289| let set = Arc::new(WakeSet::new());\n*1290| assert!(restore_persistent_shells_on_owner_online(\n 1291| owlery, ®istered, &adapters_dir, &mut edge, &set,\n 1292| )\n 1293| .is_empty());"}],"details":{"scopePath":".worktrees/287-shellrestore/crates","searchPath":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\crates","cwd":"C:\\Users\\decid\\Documents\\projects\\spt-core","matchCount":30,"fileCount":4,"files":[".worktrees/287-shellrestore/crates/spt-daemon/src/drivehub.rs",".worktrees/287-shellrestore/crates/spt-daemon/src/linkhost.rs",".worktrees/287-shellrestore/crates/spt-daemon/src/shellhost.rs",".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs"],"fileMatches":[{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/drivehub.rs","count":1},{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/linkhost.rs","count":1},{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellhost.rs","count":8},{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs","count":20}],"truncated":true,"perFileLimitReached":20,"displayContent":"# .worktrees/287-shellrestore/crates/spt-daemon/src/\n## drivehub.rs\n 294│/// **The recorded live pid arbitrates, on BOTH sides**\n*295│/// ([`crate::shellhost::live_launch_winner`]). Whoever is second sees the\n 296│/// other's `shell.pid` probing alive, stands down, and ADOPTS that pid as the\n 297│/// launch's outcome — a success, not a fault: the caller asked for a running\n 298│/// binary and there is one. The daemon-side loser reports\n## linkhost.rs\n 737│ let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n*738│ if let Some(pid) = shellhost::live_launch_winner(&perch) {\n 739│ spt_proto::emit_line_err!(\"SHELL_LAUNCH_STOOD_DOWN:{id}: already launched pid={pid} (online at bind)\");\n 740│ return Ok(pid);\n 741│ }\n## shellhost.rs\n 319│// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n *320│pub fn live_launch_winner(shell_perch: &Path) -> Option {\n 321│ shellinfo::read_shell_pid(shell_perch)\n 322│ .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\n 323│}\n │...\n 430│ || {\n *431│ live_launch_winner(&spt_store::perch::resolve_shell_perch_path_in(\n 432│ owlery, owner, shell_id,\n 433│ ))\n 434│ },\n │...\n 1210│\n*1211│ assert_eq!(live_launch_winner(perch), None, \"no pid file ⇒ no winner\");\n 1212│\n 1213│ std::fs::write(perch.join(SHELL_PID_FILE), \"0\").unwrap();\n*1214│ assert_eq!(live_launch_winner(perch), None, \"pid 0 ⇒ no winner\");\n 1215│\n 1216│ std::fs::write(perch.join(SHELL_PID_FILE), \"not-a-pid\").unwrap();\n*1217│ assert_eq!(live_launch_winner(perch), None, \"unparseable ⇒ no winner\");\n 1218│\n 1219│ // This test process is, definitionally, alive.\n 1220│ let me = std::process::id();\n │...\n 1222│ assert_eq!(\n*1223│ live_launch_winner(perch),\n 1224│ Some(me),\n 1225│ \"a recorded pid that probes alive IS the winner\"\n 1226│ );\n 1227│ shellinfo::record_shell_launch(perch, me, 1_000);\n*1228│ assert_eq!(live_launch_winner(perch), Some(me), \"same birth retains custody\");\n 1229│ let mut launch = shellinfo::read_shell_launch(perch).unwrap();\n 1230│ launch.pid_started_at = Some(\n 1231│ launch.pid_started_at.expect(\"native birth stamp on supported platforms\") ^ 1,\n │...\n 1237│ .unwrap();\n*1238│ assert_eq!(live_launch_winner(perch), None, \"a recycled pid cannot block restore\");\n 1239│ }\n 1240│\n 1241│ // [unit->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE] a REAL dial at a socket name\n## shellwake.rs\n 615│// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n *616│fn heal_stale_online_records(owlery: &Path, events: &mut dyn std::io::Write) {\n 617│ for owner in spt_store::perch::list_self_perch_ids(owlery) {\n 618│ for (shell_id, info) in shellinfo::list_shells(owlery, &owner) {\n 619│ if info.status != SHELL_STATUS_ONLINE {\n │...\n 662│// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n *663│fn watcher_eligible(\n 664│ perch: &Path,\n 665│ info: &shellinfo::ShellInfo,\n 666│ persistent: bool,\n │...\n 671│ }\n *672│ if crate::shellhost::live_launch_winner(perch).is_some() {\n 673│ return false; // binding: the shell binary and watcher must not overlap\n 674│ }\n 675│ if persistent || !shellinfo::shell_pid_provably_dead(perch) {\n │...\n 733│// [impl->REQ-SHELL-OWNER-ONLINE-RESTORE]\n *734│fn restore_persistent_shells_of_owner(\n 735│ owlery: &Path,\n 736│ registered: &[(AdapterRecord, Manifest)],\n 737│ adapters_dir: &Path,\n │...\n 754│ if shellinfo::is_shell_online(&perch, &info)\n *755│ || crate::shellhost::live_launch_winner(&perch).is_some()\n 756│ {\n 757│ continue; // already online or binding in fact\n 758│ }\n │...\n 788│/// endpoint that comes online after this sweep is covered by\n *789│/// [`restore_persistent_shells_on_owner_online`] (releases#228), running the same\n *790│/// [`restore_persistent_shells_of_owner`] body -- but it is the one that needs no\n 791│/// trigger at all, since a node restart is what strands the shells to begin with.\n 792│// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n 793│// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n *794│pub fn restore_persistent_shells_at_boot(\n 795│ owlery: &Path,\n 796│ registered: &[(AdapterRecord, Manifest)],\n 797│ adapters_dir: &Path,\n │...\n 800│ for owner in spt_store::perch::list_self_perch_ids(owlery) {\n *801│ restore_persistent_shells_of_owner(\n 802│ owlery,\n 803│ registered,\n 804│ adapters_dir,\n │...\n 873│// [impl->REQ-HAZARD-RESTART-STRANDS-PERSISTENT-SHELLS]\n *874│pub fn restore_persistent_shells_on_owner_online(\n 875│ owlery: &Path,\n 876│ registered: &[(AdapterRecord, Manifest)],\n 877│ adapters_dir: &Path,\n │...\n 886│ for owner in owners {\n *887│ restore_persistent_shells_of_owner(\n 888│ owlery,\n 889│ registered,\n 890│ adapters_dir,\n │...\n 910│ // on the stale value it just corrected.\n *911│ heal_stale_online_records(owlery, &mut std::io::stderr().lock());\n 912│\n 913│ // Stop side first: watchers whose instance is gone or no longer eligible.\n 914│ let live: Vec<(String, String)> = {\n │...\n 942│ };\n *943│ if !watcher_eligible(&perch, &info, shell.persistent, boot_ms) {\n 944│ continue;\n 945│ }\n 946│ let Some(wake_command) = shell.wake_command.as_deref() else {\n │...\n 1017│ owner_edge.seed(&owlery);\n*1018│ restore_persistent_shells_at_boot(&owlery, ®istered, &adapters_dir);\n 1019│ }\n 1020│ while !stop.load(Ordering::SeqCst) {\n 1021│ let owlery = spt_store::perch::owlery_dir();\n │...\n 1026│ // would otherwise arm a watcher for the shell we are about to launch.\n*1027│ restore_persistent_shells_on_owner_online(\n 1028│ &owlery,\n 1029│ ®istered,\n 1030│ &adapters_dir,\n │...\n 1120│ let mut events = Vec::new();\n*1121│ heal_stale_online_records(&owlery, &mut events);\n 1122│ let output = String::from_utf8(events).unwrap();\n 1123│ let mut reported: Vec<_> = output.lines().collect();\n 1124│ reported.sort();\n │...\n 1154│ let mut repeated = Vec::new();\n*1155│ heal_stale_online_records(&owlery, &mut repeated);\n 1156│ assert!(repeated.is_empty(), \"already-healed records emit no duplicate events\");\n 1157│ assert_eq!(\n 1158│ (mtime(&stale_perch), mtime(&live_perch)),\n │...\n 1255│\n*1256│ let mut restored = restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir);\n 1257│ restored.sort();\n 1258│ let mut expected = vec![\n 1259│ format!(\"ling/{before}\"),\n │...\n 1286│ edge.seed(owlery);\n*1287│ assert!(restore_persistent_shells_at_boot(owlery, ®istered, &adapters_dir).is_empty());\n 1288│\n 1289│ let set = Arc::new(WakeSet::new());\n*1290│ assert!(restore_persistent_shells_on_owner_online(\n 1291│ owlery, ®istered, &adapters_dir, &mut edge, &set,\n 1292│ )\n 1293│ .is_empty());"},"isError":false,"timestamp":1789001138096}}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_LhwwqTqtbNXGA5WfqmpAvEyX|fc_077f3569365e313d016aa1fdbfc90c87d185cc29b3b7e71d6a","toolName":"read","startedAt":"2026-09-10T00:45:51.863Z","args":{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellhost.rs:1-510"},"intent":"Reading routed launch mechanics"},"id":"d217420f","parentId":"a9a384e5","timestamp":"2026-09-10T00:45:51.863Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_r5yTrWcHNAMryjcF1FXmyKA2|fc_077f3569365e313d016aa1fdbfc91c87d19d0b7c54b8677cbe","toolName":"read","startedAt":"2026-09-10T00:45:51.863Z","args":{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:300-590"},"intent":"Reading wake resolution paths"},"id":"c23675bc","parentId":"d217420f","timestamp":"2026-09-10T00:45:51.863Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_86q7GdHeGBRmNxe4753yUR3N|fc_077f3569365e313d016aa1fdbfc92487d18187cf49e1242bd2","toolName":"read","startedAt":"2026-09-10T00:45:51.863Z","args":{"path":".worktrees/287-shellrestore/crates/spt-daemon/src/linkhost.rs:645-790"},"intent":"Reading daemon launch consumer"},"id":"e72759f9","parentId":"c23675bc","timestamp":"2026-09-10T00:45:51.863Z"}
{"type":"custom","customType":"tool_execution_start","data":{"toolCallId":"call_nKdV7gj0NifQPSIMOkbPE8HP|fc_077f3569365e313d016aa1fdbfc92c87d19d1b7edec2d8c706","toolName":"grep","startedAt":"2026-09-10T00:45:51.863Z","args":{"path":".worktrees/287-shellrestore/crates/spt-store/src;.worktrees/287-shellrestore/crates/spt-proto/src;.worktrees/287-shellrestore/crates/spt-daemon/src"},"intent":"Locating liveness probe semantics"},"id":"e1e98677","parentId":"e72759f9","timestamp":"2026-09-10T00:45:51.863Z"}
{"type":"message","id":"e17e6928","parentId":"e1e98677","timestamp":"2026-09-10T00:45:51.863Z","message":{"role":"assistant","content":[{"type":"thinking","thinking":"**Reading lines 300–590**"},{"type":"toolCall","id":"call_LhwwqTqtbNXGA5WfqmpAvEyX|fc_077f3569365e313d016aa1fdbfc90c87d185cc29b3b7e71d6a","name":"read","arguments":{"i":"Reading routed launch mechanics","path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellhost.rs:1-510"},"intent":"Reading routed launch mechanics"},{"type":"toolCall","id":"call_r5yTrWcHNAMryjcF1FXmyKA2|fc_077f3569365e313d016aa1fdbfc91c87d19d0b7c54b8677cbe","name":"read","arguments":{"i":"Reading wake resolution paths","path":".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:300-590"},"intent":"Reading wake resolution paths"},{"type":"toolCall","id":"call_86q7GdHeGBRmNxe4753yUR3N|fc_077f3569365e313d016aa1fdbfc92487d18187cf49e1242bd2","name":"read","arguments":{"i":"Reading daemon launch consumer","path":".worktrees/287-shellrestore/crates/spt-daemon/src/linkhost.rs:645-790"},"intent":"Reading daemon launch consumer"},{"type":"toolCall","id":"call_nKdV7gj0NifQPSIMOkbPE8HP|fc_077f3569365e313d016aa1fdbfc92c87d19d1b7edec2d8c706","name":"grep","arguments":{"i":"Locating liveness probe semantics","pattern":"pub fn relay_liveness|fn relay_liveness|enum RelayLiveness|fn process_started_at|fn is_process_alive|SHELL_RECORD_HEALED","path":".worktrees/287-shellrestore/crates/spt-store/src;.worktrees/287-shellrestore/crates/spt-proto/src;.worktrees/287-shellrestore/crates/spt-daemon/src","case":true,"gitignore":false,"skip":null},"intent":"Locating liveness probe semantics"}],"api":"openai-codex-responses","provider":"openai-codex","model":"gpt-6-astra","usage":{"input":19617,"output":323,"cacheRead":30464,"cacheWrite":0,"totalTokens":50404,"reasoningTokens":68,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"toolUse","timestamp":1789001138150,"responseId":"resp_077f3569365e313d016aa1fdb260cc87d1a674b123fbdd0862","providerPayload":{"type":"openaiResponsesHistory","provider":"openai-codex","dt":true,"items":[{"id":"rs_077f3569365e313d016aa1fdb6177087d1b5e3da484bde1adb","type":"reasoning","content":[],"encrypted_content":"gAAAAABqof2_D3ctU52aPSxA12dMI2il0U9LkDiS-PQqwkVlZFF0eXo9oaiBD2iM41cFS7qXNr0kcqjQAjgvP9h9T8iPGCTWx-oTWVQ-EuhJdaoUAwC_-6XZViGqhGm7uRNq5B3lpwGObxUDApYPHuAvZII2orcMa8oWUNkj3FWwHxacmETP4hJ5WVUNez0SO_lbMA_UW1A_DwKmTJSfe-Zqo8Bn6WCavw305jvNoNTcb7FZ0Y6YV1mezFVTZQaMwdHbwITCQFJKMRy8UrEqCrD7SSCozVoUC7E9anrPzXzCrQA7CoB0pitMNHvQtqXd7PHLWfvlhNc4aiiVY73zyf4j5m7d2PWq712gG7JXR-9JIOgU41hdwumUPQtpiFKgsgxVinkI5ue0kaxl4eCewjdnsWnfCAjRKhavOHMhEnPbc29Z7AialUwnHs7j2fIELZ43_BvVzdx-C8WgyQnZqlVdFbjDjErgA4eGWmjavyd0elUEsAQ3MZJZF15MajIB7iP55kdPnTN5S4NZCGKNH8nNcPlK0YClGi-Awhf7pEAHt7XlBtb3YkKFk5ycNIGRRnw8hHt9oFQabqnvZI_hvFpX6HPxthYEfFEsScB7w74EFG19-bmKO6tk8ExX26EbQykPzTOJe4cUlB794aDpVDRKokfX5f-bhY73JSihXQfSqfG1qtvKcLdm3XOx_Tf2NDyBtNbkcjW5EQ8SLZOz19EaREepov_zqSfKI4uCZYnOdQw23CuFOCDyPavakdC4TPPEjJAfCwMXyrI8Ub4DaXhlc-m4OWS3dgfWcrdMtxyNLgOoztupR9FRI1rHiLMzU14zqYYisgEafkK_j6Ed4F0QZieSWSP37tr9kP2Zbyw68hEoosBGQOJGZnthwuGq6yE7JbeeJPEf3pt-FBEnsT-kM5sYgsMTyJ1ZjDA4XCJZBzsOJli7HcDTBGowQGxnYKgDIwlxi4sNKcvNVwEfH_YSzTDBGHX_RXytDPpbyR7M9uIoRqCFuHa75q1NlWQZ7zsrjN0sqT5pO-AAfmEaLiV4tR6I1r36c3OVglzu-gC4dOiWP_qaPDp6pG2-ZKPlEg85DAw9w5AYKCa6cDk70DkWnA9jAUe470N6PmekBHI1G3ZHXM7laJ_I9yTrVRGKNpLYfF6siBRVNmxm6sP4cOGuCmZV3huMcBHbULKWIDPdwqvAJkTmv0JMKwnpqwMXAvmJIvVKvPszKEhzTBGMiiwHBDDx8g7aZwXBCFDoKLE3BblH3EuaZsCITYRVXw3WTN3-9J_YErUOJOJgZysoMjMJPiLMxzQsK4iDASwZjOJMJJblpThgR2TWGPqRncyWXEPFvlRsoT2akBniNcWovQQofS7a7mgXr_m1TY4g5gRhSiwXJN-9jhJ7_ZlJ6nlo9-lprTU0874wYWx64N9RY0FQ3ywSh1gySrNHfISGP2pfYpj04xX8F3tKw-PmroPF2RoxdvBkV5Vzqkwqz-NZqwsyo_Tu7OD3y0ed542vOZjwEkltfHvQK1IKkVESOdAhNyM2DY49QG5UE4m03IEhcqtGMqv5NonNIa9zdb5KcBwJWBSQil962toXvu_gPuW_3AA_7eAXeJtAhsBCFCwLatd45Mr5JCxMSxHUt51njPrWDq3irVkdf5YRAHv5rBAKxp88Q7p8m2HS0jBrUYZ7mW3WD5zxqYJSZcVwP_JgiAGIWmhXpC-dx68=","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"summary":[{"type":"summary_text","text":"**Reading lines 300–590**"}],"metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdbfc90c87d185cc29b3b7e71d6a","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading routed launch mechanics\",\"path\":\".worktrees/287-shellrestore/crates/spt-daemon/src/shellhost.rs:1-510\"}","call_id":"call_LhwwqTqtbNXGA5WfqmpAvEyX","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdbfc91c87d19d0b7c54b8677cbe","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading wake resolution paths\",\"path\":\".worktrees/287-shellrestore/crates/spt-daemon/src/shellwake.rs:300-590\"}","call_id":"call_r5yTrWcHNAMryjcF1FXmyKA2","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdbfc92487d18187cf49e1242bd2","type":"function_call","status":"completed","arguments":"{\"i\":\"Reading daemon launch consumer\",\"path\":\".worktrees/287-shellrestore/crates/spt-daemon/src/linkhost.rs:645-790\"}","call_id":"call_86q7GdHeGBRmNxe4753yUR3N","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"read","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}},{"id":"fc_077f3569365e313d016aa1fdbfc92c87d19d1b7edec2d8c706","type":"function_call","status":"completed","arguments":"{\"i\":\"Locating liveness probe semantics\",\"pattern\":\"pub fn relay_liveness|fn relay_liveness|enum RelayLiveness|fn process_started_at|fn is_process_alive|SHELL_RECORD_HEALED\",\"path\":\".worktrees/287-shellrestore/crates/spt-store/src;.worktrees/287-shellrestore/crates/spt-proto/src;.worktrees/287-shellrestore/crates/spt-daemon/src\",\"case\":true,\"gitignore\":false,\"skip\":null}","call_id":"call_nKdV7gj0NifQPSIMOkbPE8HP","internal_chat_message_metadata_passthrough":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"},"name":"grep","metadata":{"turn_id":"25afac0d-d353-401d-a399-10a9a855f17f"}}]},"duration":13711.025299999863,"ttft":3968.3830999997444,"completedAt":1789001151862,"contextSnapshot":{"promptTokens":50081,"nonMessageTokens":13209,"compactionEpoch":0}}}
{"type":"message","id":"6fdf3f2a","parentId":"e17e6928","timestamp":"2026-09-10T00:45:51.868Z","message":{"role":"toolResult","toolCallId":"call_r5yTrWcHNAMryjcF1FXmyKA2|fc_077f3569365e313d016aa1fdbfc91c87d19d0b7c54b8677cbe","toolName":"read","content":[{"type":"text","text":"pub fn watcher_run(\n…\n) {\n…\n while !stop.load(Ordering::SeqCst) {\n…\n let mut child = match child {\n…\n Err(e) => {\n // An unspawnable waker is a permanent condition — latch now.\n spt_proto::emit_line_err!(\"WAKER_SPAWN_FAIL:{owner}/{shell_id}: {e} (giving up)\");\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\n return;\n }\n };\n // The birth stamp rides WITH the pid, in one write — the kill path\n // authenticates the pair, and a stamp parked separately would leave a\n // window that reads Held. [impl->REQ-SHELL-KILL-AUTHENTICATED]\n record_waker_launch(&perch, child.id());\n let status = child.wait();\n let _ = std::fs::remove_file(perch.join(WAKER_PID_FILE));\n if stop.load(Ordering::SeqCst) {\n return; // stopped from outside — the kill is not a crash\n }\n match status.ok().and_then(|s| s.code()) {\n Some(WAKE_OPCODE) => {\n match resolve() {\n Ok(what) => spt_proto::emit_line_err!(\"SHELL_WAKE:{owner}/{shell_id}: {what}\"),\n Err(e) => spt_proto::emit_line_err!(\"SHELL_WAKE_FAIL:{owner}/{shell_id}: {e}\"),\n }\n return;\n }\n _ => {\n failures += 1;\n if failures >= params.give_up_after {\n spt_proto::emit_line_err!(\n \"WAKER_GAVE_UP:{owner}/{shell_id}: {failures} consecutive crash-exits \\\n (cleared by the next relink/launch)\"\n );\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\n return;\n }\n // Backoff in small slices so a stop request lands promptly.\n let mut left = backoff_ms(params, failures);\n while left > 0 && !stop.load(Ordering::SeqCst) {\n let step = left.min(50);\n std::thread::sleep(Duration::from_millis(step));\n left -= step;\n }\n }\n }\n }\n}\n\n/// The **state-keyed wake resolution** (M5-D4c — CONTEXT §Shell sleep/wake):\n/// key on the owner's local rest record, then bring the shell online —\n///\n/// - owner **dormant** (resting warm, still running) ⇒ touch nothing on the\n/// endpoint, just relaunch the shell binary;\n/// - owner **suspended** ⇒ revive the owner first\n/// ([`crate::resting::daemon_rest_event`] `Wake` — its cascade relaunches\n/// the owner's *persistent* shells, so this fn launches only if the\n/// cascade did not already), then the shell;\n/// - owner **active** (or recordless — a pre-resting/interim perch) ⇒ just\n/// relaunch the shell;\n/// - **no local instance of the owner** ⇒ refuse, naming the deferral: the\n/// `shell_wake_spawn_anywhere` fresh-spawn branch rides\n/// instantiate-anywhere (the D1c grant shape is its seam), and the\n/// *active-elsewhere cross-node attach* arm upgrades with presence/MRA\n/// (D6) + cross-node link (D8c) — D4 resolves against the local node.\n///\n/// The shell's bind onlines the perch (the D3b contract) — this fn never\n/// flips status.\n// [impl->REQ-SHELL-2]\npub fn resolve_wake(\n owlery: &Path,\n owner: &str,\n shell_id: &str,\n adapter_name: &str,\n shell: &Shell,\n) -> Result {\n // Shells hang off flat-Self perches only (the D3a layout decision).\n let owner_perch = owlery.join(owner);\n if !owner_perch.join(\"info.json\").exists() {\n // No local instance — consult presence (M5-D6b, REQ-PRES-1): a\n // routable instance of the owner on ANOTHER node gets the wake\n // FORWARDED there through the D5b remote rest op (the target node's\n // own cascade relaunches ITS persistent shells). This local shell\n // stays offline — the cross-node shell *link* is D8c; say so.\n // [impl->REQ-PRES-1]\n if let Some(node) = remote_owner_node(owner) {\n return match forward_wake(owner, &node) {\n Ok(outcome) => Ok(format!(\n \"WAKE_FORWARDED:{owner}@{node}: {outcome}; this shell stays offline \\\n here (cross-node shell link lands at D8c)\"\n )),\n Err(e) => Err(format!(\"WAKE_FORWARD_FAIL:{owner}@{node}: {e}\")),\n };\n }\n return Err(format!(\n \"WAKE_NO_REACHABLE_INSTANCE:{owner}: no instance of the owner on any \\\n reachable node — a fresh-spawn-to-wake rides the deferred \\\n instantiate-anywhere capability (the shell_wake_spawn_anywhere grant \\\n shape is its seam)\"\n ));\n }\n let state = crate::resting::read_rest(&owner_perch).map(|r| r.state);\n let mut did = String::new();\n if state == Some(crate::resting::RestState::Suspended) {\n match crate::resting::daemon_rest_event(owner, crate::resting::RestEvent::Wake, None) {\n Ok(_) => did.push_str(\"revived owner; \"),\n Err(e) => return Err(format!(\"revive owner: {e}\")),\n }\n } else if state == Some(crate::resting::RestState::Dormant) {\n did.push_str(\"owner dormant (left in place); \");\n }\n // Never double-launch a live binary: the revive's wake cascade may have\n // relaunched this (persistent) instance already — and two reconcilers\n // (a fresh daemon adopting + a stale watcher firing) may race a wake.\n // A parked pid that probes alive means somebody won; stand down.\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\n let live_pid = std::fs::read_to_string(perch.join(crate::shellhost::SHELL_PID_FILE))\n .ok()\n .and_then(|s| s.trim().parse::().ok())\n .filter(|&p| p != 0 && spt_store::proc::is_process_alive(p));\n if let Some(p) = live_pid {\n return Ok(format!(\"{did}already relaunched pid={p} (online at bind)\"));\n }\n // [impl->REQ-INSTALL-11] the wake-triggered relaunch resolves against the\n // adapter's install dir, like every other launch of the same instance.\n let install_dir =\n crate::shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), adapter_name);\n let pid = crate::shellhost::launch_shell(\n owlery,\n owner,\n shell_id,\n adapter_name,\n install_dir.as_deref(),\n shell,\n )?;\n Ok(format!(\"{did}relaunched pid={pid} (online at bind)\"))\n}\n\n/// The node (hex) holding a routable instance of `owner` per the gossiped\n/// registry snapshots, preferring the most-recently-active row when several\n/// nodes hold one (the presence datum as the tiebreak; absent data ranks\n/// last). `None` = the owner exists nowhere reachable.\n// [impl->REQ-PRES-1]\nfn remote_owner_node(owner: &str) -> Option {\n let regs = crate::presence::load_registry_snapshots(&crate::presence::registry_snapshot_dir());\n let local = crate::presence::local_node_hex();\n let mut best: Option<(u64, String)> = None;\n for reg in regs.values() {\n for row in reg.instances(owner) {\n if row.node == local || !row.status.routable() {\n continue;\n }\n let ts = row.last_active_ms.unwrap_or(0);\n let better = match &best {\n Some((cur, _)) => ts > *cur,\n None => true,\n };\n if better {\n best = Some((ts, row.node.clone()));\n }\n }\n }\n best.map(|(_, node)| node)\n}\n\n/// Forward a wake to `node` through the D5b remote rest op (the remote-drive\n/// trust class — the target's access gate decides). One dial, one request,\n/// one reply; a refusal (no reply) surfaces as an error.\n// [impl->REQ-PRES-1]\nfn forward_wake(owner: &str, node: &str) -> Result {\n use spt_net::net::endpoint::addr_for_node_hex;\n let addr = addr_for_node_hex(node)\n .and_then(|a| serde_json::to_value(a).ok())\n .ok_or_else(|| format!(\"no dialable address for {node}\"))?;\n let mut brain =\n crate::brain::Brain::cold_start(&crate::endpoint::broker_socket_name(), now_ms())\n .map_err(|e| format!(\"broker connect: {e}\"))?;\n // A-4b (REQ-OPID-TRACING-RETRY): the wake-forward is a tracing-only rest op —\n // if a broker restart dropped the conn/stream after the op journaled, re-mint a\n // FRESH `wake` op from the SAME source and run ONCE more. The dial rides INSIDE\n // `run` because that restart drops the CONN too, not just the stream — a retry\n // against the dead conn would surface a different error, not self-heal. A 2nd\n // no-longer-held collapses to the helper's F-1 public string.\n // [impl->REQ-OPID-TRACING-RETRY]\n let outcome = crate::effect::with_tracing_retry(\n // The wake-forward rest op's seq source is a fresh `now_ms()` — its OWN\n // minting source, distinct from shellchan's spool-row counter (doyle ruling:\n // the tag names the seq source, not the subsystem), so it stamps `wake`.\n || Ok(crate::effect::MintedOp::new(crate::effect::Minter::Wake, now_ms())),\n |op| {\n let conn = brain.net_dial(addr.clone(), None)?;\n // Keep the tracing string's seq consistent with the (possibly re-minted) op.\n let op_id = format!(\"{}:wakefwd:{}\", crate::presence::local_node_hex(), op.seq);\n crate::resthost::request_rest(\n &mut brain,\n conn.conn_id,\n owner,\n spt_net::net::rest::REST_EVENT_WAKE,\n &op_id,\n op,\n )\n },\n )\n .map_err(|e| format!(\"rest op: {e}\"))?;\n match outcome {\n crate::resthost::RestRequestOutcome::Edge(d) => Ok(format!(\"woke ({d})\")),\n crate::resthost::RestRequestOutcome::NoEdge => Ok(\"already awake\".to_string()),\n crate::resthost::RestRequestOutcome::Failed(e) => Err(e),\n crate::resthost::RestRequestOutcome::NoReply => {\n Err(\"refused or dropped (no reply)\".to_string())\n }\n }\n}\n\n/// Resolve one adapter **option**'s `[shell]` section through the merged view\n/// (composite addressing): `adapter_option` is the stored `[:profile]`\n/// string, split → parent lookup in `registered` → profile overlay (shipped or\n/// local). Returns an **owned** [`Shell`] — a profile produces a fresh merged\n/// manifest, not a borrow into the parent slice. A bare name resolves to the\n/// parent unmodified; a deregistered parent or a failed overlay yields `None`.\nfn shell_section_of(\n registered: &[(AdapterRecord, Manifest)],\n adapters_dir: &Path,\n adapter_option: &str,\n) -> Option {\n spt_runtime::registry::resolve_option_in(registered, adapters_dir, adapter_option)\n .ok()\n .filter(|m| m.adapter.kind == AdapterKind::Shell)\n .and_then(|m| m.shell)\n}\n\nfn now_ms() -> u64 {\n crate::brain::now_ms()\n}\n\n/// Fill a `wake_command` template.\n///\n/// **Its catalog and the spawn template's share a vocabulary; they are not the\n/// same set, and never claiming they are is the point of saying so here.** The\n/// keys mean the same thing in both (`id`, `adapter_name`, `link_token`,\n/// `adapter_dir`), so an author learns one manifest language — but `perch_dir`\n/// is **spawn-only by design** (REQ-SHELL-PERCH-DIR: it resolves a *live* link's\n/// perch-relative transfer paths, and a waker has no live link). A comment\n/// asserting set-EQUALITY over two sets that are separately extended is the\n/// drift this project single-sources against; it had already been false since\n/// `perch_dir` landed.\n///\n/// The waker's token is minted **unparked**: it substitutes (template\n/// compatibility) without ever verifying against the perch, because an offline\n/// link has no live credential by design — the close retired it, and a waker\n/// wakes by *exit code*, not by driving the link.\n///\n/// `install_dir` resolves the program token and fills `{adapter_dir}`, exactly as\n/// on the spawn side ([`crate::shellhost::fill_spawn_command`]) — a released\n/// adapter whose spawn resolves and whose wake does not would go permanently\n/// unwakeable the moment it went offline.\nfn fill_wake_command(\n shell_id: &str,\n adapter_name: &str,\n install_dir: Option<&Path>,\n wake_command: &str,\n) -> Result, String> {\n let mut keys = std::collections::BTreeMap::from([\n (\"id\".to_string(), shell_id.to_string()),\n (\"adapter_name\".to_string(), adapter_name.to_string()),\n (\n \"link_token\".to_string(),\n crate::shellhost::mint_link_token(),\n ),\n ]);\n // [impl->REQ-INSTALL-11] opt-in and N-1-safe: a template that never names the\n // key fills byte-identically.\n if let Some(dir) = install_dir {\n keys.insert(\"adapter_dir\".to_string(), dir.display().to_string());\n }\n // [impl->REQ-HAZARD-TEMPLATE-ARGV-FILL] tokenize-template-then-fill-each: a\n // multi-word/quote/semicolon {key} value is exactly one argv element.\n let mut tokens =\n spt_runtime::runtime::fill_template_tokens(wake_command, &keys).map_err(|e| e.to_string())?;\n let Some(program) = tokens.first_mut() else {\n return Err(\"empty wake_command\".into());\n };\n // [impl->REQ-INSTALL-11] one resolution primitive, no parallel path.\n if let Some(dir) = install_dir {\n *program = spt_runtime::runtime::resolve_program_in_dir(program, dir);\n }\n Ok(tokens)\n}\n\n/// One reconcile sweep — the invariant holder for the online/offline mutual\n/// exclusivity (CONTEXT: \"spt-core flips between them\"):\n///\n/// - **offline + `wake_command` + no give-up latch + no live watcher** ⇒\n/// kill any orphaned waker pid (a dead daemon's leftover), then start a\n/// supervision thread.\n/// - **not offline (onlined / torn down / deregistered) + live watcher** ⇒\n/// stop it (flag + kill).\n///\n/// Runs at daemon boot and every tick — lifecycle flips happen in CLI-process\n\n[Showing lines 299-593 of 2161. Use :594 to continue]"}],"details":{"truncation":{"content":" // An unspawnable waker is a permanent condition — latch now.\r\n spt_proto::emit_line_err!(\"WAKER_SPAWN_FAIL:{owner}/{shell_id}: {e} (giving up)\");\r\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\r\n return;\r\n }\r\n };\r\n // The birth stamp rides WITH the pid, in one write — the kill path\r\n // authenticates the pair, and a stamp parked separately would leave a\r\n // window that reads Held. [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\n record_waker_launch(&perch, child.id());\r\n let status = child.wait();\r\n let _ = std::fs::remove_file(perch.join(WAKER_PID_FILE));\r\n if stop.load(Ordering::SeqCst) {\r\n return; // stopped from outside — the kill is not a crash\r\n }\r\n match status.ok().and_then(|s| s.code()) {\r\n Some(WAKE_OPCODE) => {\r\n match resolve() {\r\n Ok(what) => spt_proto::emit_line_err!(\"SHELL_WAKE:{owner}/{shell_id}: {what}\"),\r\n Err(e) => spt_proto::emit_line_err!(\"SHELL_WAKE_FAIL:{owner}/{shell_id}: {e}\"),\r\n }\r\n return;\r\n }\r\n _ => {\r\n failures += 1;\r\n if failures >= params.give_up_after {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_GAVE_UP:{owner}/{shell_id}: {failures} consecutive crash-exits \\\r\n (cleared by the next relink/launch)\"\r\n );\r\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\r\n return;\r\n }\r\n // Backoff in small slices so a stop request lands promptly.\r\n let mut left = backoff_ms(params, failures);\r\n while left > 0 && !stop.load(Ordering::SeqCst) {\r\n let step = left.min(50);\r\n std::thread::sleep(Duration::from_millis(step));\r\n left -= step;\r\n }\r\n }\r\n }\r\n }\r\n}\r\n\r\n/// The **state-keyed wake resolution** (M5-D4c — CONTEXT §Shell sleep/wake):\r\n/// key on the owner's local rest record, then bring the shell online —\r\n///\r\n/// - owner **dormant** (resting warm, still running) ⇒ touch nothing on the\r\n/// endpoint, just relaunch the shell binary;\r\n/// - owner **suspended** ⇒ revive the owner first\r\n/// ([`crate::resting::daemon_rest_event`] `Wake` — its cascade relaunches\r\n/// the owner's *persistent* shells, so this fn launches only if the\r\n/// cascade did not already), then the shell;\r\n/// - owner **active** (or recordless — a pre-resting/interim perch) ⇒ just\r\n/// relaunch the shell;\r\n/// - **no local instance of the owner** ⇒ refuse, naming the deferral: the\r\n/// `shell_wake_spawn_anywhere` fresh-spawn branch rides\r\n/// instantiate-anywhere (the D1c grant shape is its seam), and the\r\n/// *active-elsewhere cross-node attach* arm upgrades with presence/MRA\r\n/// (D6) + cross-node link (D8c) — D4 resolves against the local node.\r\n///\r\n/// The shell's bind onlines the perch (the D3b contract) — this fn never\r\n/// flips status.\r\n// [impl->REQ-SHELL-2]\r\npub fn resolve_wake(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n adapter_name: &str,\r\n shell: &Shell,\r\n) -> Result {\r\n // Shells hang off flat-Self perches only (the D3a layout decision).\r\n let owner_perch = owlery.join(owner);\r\n if !owner_perch.join(\"info.json\").exists() {\r\n // No local instance — consult presence (M5-D6b, REQ-PRES-1): a\r\n // routable instance of the owner on ANOTHER node gets the wake\r\n // FORWARDED there through the D5b remote rest op (the target node's\r\n // own cascade relaunches ITS persistent shells). This local shell\r\n // stays offline — the cross-node shell *link* is D8c; say so.\r\n // [impl->REQ-PRES-1]\r\n if let Some(node) = remote_owner_node(owner) {\r\n return match forward_wake(owner, &node) {\r\n Ok(outcome) => Ok(format!(\r\n \"WAKE_FORWARDED:{owner}@{node}: {outcome}; this shell stays offline \\\r\n here (cross-node shell link lands at D8c)\"\r\n )),\r\n Err(e) => Err(format!(\"WAKE_FORWARD_FAIL:{owner}@{node}: {e}\")),\r\n };\r\n }\r\n return Err(format!(\r\n \"WAKE_NO_REACHABLE_INSTANCE:{owner}: no instance of the owner on any \\\r\n reachable node — a fresh-spawn-to-wake rides the deferred \\\r\n instantiate-anywhere capability (the shell_wake_spawn_anywhere grant \\\r\n shape is its seam)\"\r\n ));\r\n }\r\n let state = crate::resting::read_rest(&owner_perch).map(|r| r.state);\r\n let mut did = String::new();\r\n if state == Some(crate::resting::RestState::Suspended) {\r\n match crate::resting::daemon_rest_event(owner, crate::resting::RestEvent::Wake, None) {\r\n Ok(_) => did.push_str(\"revived owner; \"),\r\n Err(e) => return Err(format!(\"revive owner: {e}\")),\r\n }\r\n } else if state == Some(crate::resting::RestState::Dormant) {\r\n did.push_str(\"owner dormant (left in place); \");\r\n }\r\n // Never double-launch a live binary: the revive's wake cascade may have\r\n // relaunched this (persistent) instance already — and two reconcilers\r\n // (a fresh daemon adopting + a stale watcher firing) may race a wake.\r\n // A parked pid that probes alive means somebody won; stand down.\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n let live_pid = std::fs::read_to_string(perch.join(crate::shellhost::SHELL_PID_FILE))\r\n .ok()\r\n .and_then(|s| s.trim().parse::().ok())\r\n .filter(|&p| p != 0 && spt_store::proc::is_process_alive(p));\r\n if let Some(p) = live_pid {\r\n return Ok(format!(\"{did}already relaunched pid={p} (online at bind)\"));\r\n }\r\n // [impl->REQ-INSTALL-11] the wake-triggered relaunch resolves against the\r\n // adapter's install dir, like every other launch of the same instance.\r\n let install_dir =\r\n crate::shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), adapter_name);\r\n let pid = crate::shellhost::launch_shell(\r\n owlery,\r\n owner,\r\n shell_id,\r\n adapter_name,\r\n install_dir.as_deref(),\r\n shell,\r\n )?;\r\n Ok(format!(\"{did}relaunched pid={pid} (online at bind)\"))\r\n}\r\n\r\n/// The node (hex) holding a routable instance of `owner` per the gossiped\r\n/// registry snapshots, preferring the most-recently-active row when several\r\n/// nodes hold one (the presence datum as the tiebreak; absent data ranks\r\n/// last). `None` = the owner exists nowhere reachable.\r\n// [impl->REQ-PRES-1]\r\nfn remote_owner_node(owner: &str) -> Option {\r\n let regs = crate::presence::load_registry_snapshots(&crate::presence::registry_snapshot_dir());\r\n let local = crate::presence::local_node_hex();\r\n let mut best: Option<(u64, String)> = None;\r\n for reg in regs.values() {\r\n for row in reg.instances(owner) {\r\n if row.node == local || !row.status.routable() {\r\n continue;\r\n }\r\n let ts = row.last_active_ms.unwrap_or(0);\r\n let better = match &best {\r\n Some((cur, _)) => ts > *cur,\r\n None => true,\r\n };\r\n if better {\r\n best = Some((ts, row.node.clone()));\r\n }\r\n }\r\n }\r\n best.map(|(_, node)| node)\r\n}\r\n\r\n/// Forward a wake to `node` through the D5b remote rest op (the remote-drive\r\n/// trust class — the target's access gate decides). One dial, one request,\r\n/// one reply; a refusal (no reply) surfaces as an error.\r\n// [impl->REQ-PRES-1]\r\nfn forward_wake(owner: &str, node: &str) -> Result {\r\n use spt_net::net::endpoint::addr_for_node_hex;\r\n let addr = addr_for_node_hex(node)\r\n .and_then(|a| serde_json::to_value(a).ok())\r\n .ok_or_else(|| format!(\"no dialable address for {node}\"))?;\r\n let mut brain =\r\n crate::brain::Brain::cold_start(&crate::endpoint::broker_socket_name(), now_ms())\r\n .map_err(|e| format!(\"broker connect: {e}\"))?;\r\n // A-4b (REQ-OPID-TRACING-RETRY): the wake-forward is a tracing-only rest op —\r\n // if a broker restart dropped the conn/stream after the op journaled, re-mint a\r\n // FRESH `wake` op from the SAME source and run ONCE more. The dial rides INSIDE\r\n // `run` because that restart drops the CONN too, not just the stream — a retry\r\n // against the dead conn would surface a different error, not self-heal. A 2nd\r\n // no-longer-held collapses to the helper's F-1 public string.\r\n // [impl->REQ-OPID-TRACING-RETRY]\r\n let outcome = crate::effect::with_tracing_retry(\r\n // The wake-forward rest op's seq source is a fresh `now_ms()` — its OWN\r\n // minting source, distinct from shellchan's spool-row counter (doyle ruling:\r\n // the tag names the seq source, not the subsystem), so it stamps `wake`.\r\n || Ok(crate::effect::MintedOp::new(crate::effect::Minter::Wake, now_ms())),\r\n |op| {\r\n let conn = brain.net_dial(addr.clone(), None)?;\r\n // Keep the tracing string's seq consistent with the (possibly re-minted) op.\r\n let op_id = format!(\"{}:wakefwd:{}\", crate::presence::local_node_hex(), op.seq);\r\n crate::resthost::request_rest(\r\n &mut brain,\r\n conn.conn_id,\r\n owner,\r\n spt_net::net::rest::REST_EVENT_WAKE,\r\n &op_id,\r\n op,\r\n )\r\n },\r\n )\r\n .map_err(|e| format!(\"rest op: {e}\"))?;\r\n match outcome {\r\n crate::resthost::RestRequestOutcome::Edge(d) => Ok(format!(\"woke ({d})\")),\r\n crate::resthost::RestRequestOutcome::NoEdge => Ok(\"already awake\".to_string()),\r\n crate::resthost::RestRequestOutcome::Failed(e) => Err(e),\r\n crate::resthost::RestRequestOutcome::NoReply => {\r\n Err(\"refused or dropped (no reply)\".to_string())\r\n }\r\n }\r\n}\r\n\r\n/// Resolve one adapter **option**'s `[shell]` section through the merged view\r\n/// (composite addressing): `adapter_option` is the stored `[:profile]`\r\n/// string, split → parent lookup in `registered` → profile overlay (shipped or\r\n/// local). Returns an **owned** [`Shell`] — a profile produces a fresh merged\r\n/// manifest, not a borrow into the parent slice. A bare name resolves to the\r\n/// parent unmodified; a deregistered parent or a failed overlay yields `None`.\r\nfn shell_section_of(\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n adapter_option: &str,\r\n) -> Option {\r\n spt_runtime::registry::resolve_option_in(registered, adapters_dir, adapter_option)\r\n .ok()\r\n .filter(|m| m.adapter.kind == AdapterKind::Shell)\r\n .and_then(|m| m.shell)\r\n}\r\n\r\nfn now_ms() -> u64 {\r\n crate::brain::now_ms()\r\n}\r\n\r\n/// Fill a `wake_command` template.\r\n///\r\n/// **Its catalog and the spawn template's share a vocabulary; they are not the\r\n/// same set, and never claiming they are is the point of saying so here.** The\r\n/// keys mean the same thing in both (`id`, `adapter_name`, `link_token`,\r\n/// `adapter_dir`), so an author learns one manifest language — but `perch_dir`\r\n/// is **spawn-only by design** (REQ-SHELL-PERCH-DIR: it resolves a *live* link's\r\n/// perch-relative transfer paths, and a waker has no live link). A comment\r\n/// asserting set-EQUALITY over two sets that are separately extended is the\r\n/// drift this project single-sources against; it had already been false since\r\n/// `perch_dir` landed.\r\n///\r\n/// The waker's token is minted **unparked**: it substitutes (template\r\n/// compatibility) without ever verifying against the perch, because an offline\r\n/// link has no live credential by design — the close retired it, and a waker\r\n/// wakes by *exit code*, not by driving the link.\r\n///\r\n/// `install_dir` resolves the program token and fills `{adapter_dir}`, exactly as\r\n/// on the spawn side ([`crate::shellhost::fill_spawn_command`]) — a released\r\n/// adapter whose spawn resolves and whose wake does not would go permanently\r\n/// unwakeable the moment it went offline.\r\nfn fill_wake_command(\r\n shell_id: &str,\r\n adapter_name: &str,\r\n install_dir: Option<&Path>,\r\n wake_command: &str,\r\n) -> Result, String> {\r\n let mut keys = std::collections::BTreeMap::from([\r\n (\"id\".to_string(), shell_id.to_string()),\r\n (\"adapter_name\".to_string(), adapter_name.to_string()),\r\n (\r\n \"link_token\".to_string(),\r\n crate::shellhost::mint_link_token(),\r\n ),\r\n ]);\r\n // [impl->REQ-INSTALL-11] opt-in and N-1-safe: a template that never names the\r\n // key fills byte-identically.\r\n if let Some(dir) = install_dir {\r\n keys.insert(\"adapter_dir\".to_string(), dir.display().to_string());\r\n }\r\n // [impl->REQ-HAZARD-TEMPLATE-ARGV-FILL] tokenize-template-then-fill-each: a\r\n // multi-word/quote/semicolon {key} value is exactly one argv element.\r\n let mut tokens =\r\n spt_runtime::runtime::fill_template_tokens(wake_command, &keys).map_err(|e| e.to_string())?;\r\n let Some(program) = tokens.first_mut() else {\r\n return Err(\"empty wake_command\".into());\r\n };\r\n // [impl->REQ-INSTALL-11] one resolution primitive, no parallel path.\r\n if let Some(dir) = install_dir {\r\n *program = spt_runtime::runtime::resolve_program_in_dir(program, dir);\r\n }\r\n Ok(tokens)\r\n}\r\n\r\n/// One reconcile sweep — the invariant holder for the online/offline mutual\r\n/// exclusivity (CONTEXT: \"spt-core flips between them\"):\r\n///\r\n/// - **offline + `wake_command` + no give-up latch + no live watcher** ⇒\r\n/// kill any orphaned waker pid (a dead daemon's leftover), then start a\r\n/// supervision thread.\r\n/// - **not offline (onlined / torn down / deregistered) + live watcher** ⇒\r\n/// stop it (flag + kill).\r\n///\r\n/// Runs at daemon boot and every tick — lifecycle flips happen in CLI-process\r","truncated":true,"truncatedBy":"lines","totalLines":1863,"totalBytes":14209,"outputLines":295,"outputBytes":14209,"lastLinePartial":false,"firstLineExceedsLimit":false},"totalLines":2161,"displayContent":{"text":"pub fn watcher_run(\n…\n) {\n…\n while !stop.load(Ordering::SeqCst) {\n…\n let mut child = match child {\n…\n Err(e) => {\n // An unspawnable waker is a permanent condition — latch now.\r\n spt_proto::emit_line_err!(\"WAKER_SPAWN_FAIL:{owner}/{shell_id}: {e} (giving up)\");\r\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\r\n return;\r\n }\r\n };\r\n // The birth stamp rides WITH the pid, in one write — the kill path\r\n // authenticates the pair, and a stamp parked separately would leave a\r\n // window that reads Held. [impl->REQ-SHELL-KILL-AUTHENTICATED]\r\n record_waker_launch(&perch, child.id());\r\n let status = child.wait();\r\n let _ = std::fs::remove_file(perch.join(WAKER_PID_FILE));\r\n if stop.load(Ordering::SeqCst) {\r\n return; // stopped from outside — the kill is not a crash\r\n }\r\n match status.ok().and_then(|s| s.code()) {\r\n Some(WAKE_OPCODE) => {\r\n match resolve() {\r\n Ok(what) => spt_proto::emit_line_err!(\"SHELL_WAKE:{owner}/{shell_id}: {what}\"),\r\n Err(e) => spt_proto::emit_line_err!(\"SHELL_WAKE_FAIL:{owner}/{shell_id}: {e}\"),\r\n }\r\n return;\r\n }\r\n _ => {\r\n failures += 1;\r\n if failures >= params.give_up_after {\r\n spt_proto::emit_line_err!(\r\n \"WAKER_GAVE_UP:{owner}/{shell_id}: {failures} consecutive crash-exits \\\r\n (cleared by the next relink/launch)\"\r\n );\r\n let _ = std::fs::write(perch.join(WAKER_GAVE_UP_FILE), b\"\");\r\n return;\r\n }\r\n // Backoff in small slices so a stop request lands promptly.\r\n let mut left = backoff_ms(params, failures);\r\n while left > 0 && !stop.load(Ordering::SeqCst) {\r\n let step = left.min(50);\r\n std::thread::sleep(Duration::from_millis(step));\r\n left -= step;\r\n }\r\n }\r\n }\r\n }\r\n}\r\n\r\n/// The **state-keyed wake resolution** (M5-D4c — CONTEXT §Shell sleep/wake):\r\n/// key on the owner's local rest record, then bring the shell online —\r\n///\r\n/// - owner **dormant** (resting warm, still running) ⇒ touch nothing on the\r\n/// endpoint, just relaunch the shell binary;\r\n/// - owner **suspended** ⇒ revive the owner first\r\n/// ([`crate::resting::daemon_rest_event`] `Wake` — its cascade relaunches\r\n/// the owner's *persistent* shells, so this fn launches only if the\r\n/// cascade did not already), then the shell;\r\n/// - owner **active** (or recordless — a pre-resting/interim perch) ⇒ just\r\n/// relaunch the shell;\r\n/// - **no local instance of the owner** ⇒ refuse, naming the deferral: the\r\n/// `shell_wake_spawn_anywhere` fresh-spawn branch rides\r\n/// instantiate-anywhere (the D1c grant shape is its seam), and the\r\n/// *active-elsewhere cross-node attach* arm upgrades with presence/MRA\r\n/// (D6) + cross-node link (D8c) — D4 resolves against the local node.\r\n///\r\n/// The shell's bind onlines the perch (the D3b contract) — this fn never\r\n/// flips status.\r\n// [impl->REQ-SHELL-2]\r\npub fn resolve_wake(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n adapter_name: &str,\r\n shell: &Shell,\r\n) -> Result {\r\n // Shells hang off flat-Self perches only (the D3a layout decision).\r\n let owner_perch = owlery.join(owner);\r\n if !owner_perch.join(\"info.json\").exists() {\r\n // No local instance — consult presence (M5-D6b, REQ-PRES-1): a\r\n // routable instance of the owner on ANOTHER node gets the wake\r\n // FORWARDED there through the D5b remote rest op (the target node's\r\n // own cascade relaunches ITS persistent shells). This local shell\r\n // stays offline — the cross-node shell *link* is D8c; say so.\r\n // [impl->REQ-PRES-1]\r\n if let Some(node) = remote_owner_node(owner) {\r\n return match forward_wake(owner, &node) {\r\n Ok(outcome) => Ok(format!(\r\n \"WAKE_FORWARDED:{owner}@{node}: {outcome}; this shell stays offline \\\r\n here (cross-node shell link lands at D8c)\"\r\n )),\r\n Err(e) => Err(format!(\"WAKE_FORWARD_FAIL:{owner}@{node}: {e}\")),\r\n };\r\n }\r\n return Err(format!(\r\n \"WAKE_NO_REACHABLE_INSTANCE:{owner}: no instance of the owner on any \\\r\n reachable node — a fresh-spawn-to-wake rides the deferred \\\r\n instantiate-anywhere capability (the shell_wake_spawn_anywhere grant \\\r\n shape is its seam)\"\r\n ));\r\n }\r\n let state = crate::resting::read_rest(&owner_perch).map(|r| r.state);\r\n let mut did = String::new();\r\n if state == Some(crate::resting::RestState::Suspended) {\r\n match crate::resting::daemon_rest_event(owner, crate::resting::RestEvent::Wake, None) {\r\n Ok(_) => did.push_str(\"revived owner; \"),\r\n Err(e) => return Err(format!(\"revive owner: {e}\")),\r\n }\r\n } else if state == Some(crate::resting::RestState::Dormant) {\r\n did.push_str(\"owner dormant (left in place); \");\r\n }\r\n // Never double-launch a live binary: the revive's wake cascade may have\r\n // relaunched this (persistent) instance already — and two reconcilers\r\n // (a fresh daemon adopting + a stale watcher firing) may race a wake.\r\n // A parked pid that probes alive means somebody won; stand down.\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n let live_pid = std::fs::read_to_string(perch.join(crate::shellhost::SHELL_PID_FILE))\r\n .ok()\r\n .and_then(|s| s.trim().parse::().ok())\r\n .filter(|&p| p != 0 && spt_store::proc::is_process_alive(p));\r\n if let Some(p) = live_pid {\r\n return Ok(format!(\"{did}already relaunched pid={p} (online at bind)\"));\r\n }\r\n // [impl->REQ-INSTALL-11] the wake-triggered relaunch resolves against the\r\n // adapter's install dir, like every other launch of the same instance.\r\n let install_dir =\r\n crate::shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), adapter_name);\r\n let pid = crate::shellhost::launch_shell(\r\n owlery,\r\n owner,\r\n shell_id,\r\n adapter_name,\r\n install_dir.as_deref(),\r\n shell,\r\n )?;\r\n Ok(format!(\"{did}relaunched pid={pid} (online at bind)\"))\r\n}\r\n\r\n/// The node (hex) holding a routable instance of `owner` per the gossiped\r\n/// registry snapshots, preferring the most-recently-active row when several\r\n/// nodes hold one (the presence datum as the tiebreak; absent data ranks\r\n/// last). `None` = the owner exists nowhere reachable.\r\n// [impl->REQ-PRES-1]\r\nfn remote_owner_node(owner: &str) -> Option {\r\n let regs = crate::presence::load_registry_snapshots(&crate::presence::registry_snapshot_dir());\r\n let local = crate::presence::local_node_hex();\r\n let mut best: Option<(u64, String)> = None;\r\n for reg in regs.values() {\r\n for row in reg.instances(owner) {\r\n if row.node == local || !row.status.routable() {\r\n continue;\r\n }\r\n let ts = row.last_active_ms.unwrap_or(0);\r\n let better = match &best {\r\n Some((cur, _)) => ts > *cur,\r\n None => true,\r\n };\r\n if better {\r\n best = Some((ts, row.node.clone()));\r\n }\r\n }\r\n }\r\n best.map(|(_, node)| node)\r\n}\r\n\r\n/// Forward a wake to `node` through the D5b remote rest op (the remote-drive\r\n/// trust class — the target's access gate decides). One dial, one request,\r\n/// one reply; a refusal (no reply) surfaces as an error.\r\n// [impl->REQ-PRES-1]\r\nfn forward_wake(owner: &str, node: &str) -> Result {\r\n use spt_net::net::endpoint::addr_for_node_hex;\r\n let addr = addr_for_node_hex(node)\r\n .and_then(|a| serde_json::to_value(a).ok())\r\n .ok_or_else(|| format!(\"no dialable address for {node}\"))?;\r\n let mut brain =\r\n crate::brain::Brain::cold_start(&crate::endpoint::broker_socket_name(), now_ms())\r\n .map_err(|e| format!(\"broker connect: {e}\"))?;\r\n // A-4b (REQ-OPID-TRACING-RETRY): the wake-forward is a tracing-only rest op —\r\n // if a broker restart dropped the conn/stream after the op journaled, re-mint a\r\n // FRESH `wake` op from the SAME source and run ONCE more. The dial rides INSIDE\r\n // `run` because that restart drops the CONN too, not just the stream — a retry\r\n // against the dead conn would surface a different error, not self-heal. A 2nd\r\n // no-longer-held collapses to the helper's F-1 public string.\r\n // [impl->REQ-OPID-TRACING-RETRY]\r\n let outcome = crate::effect::with_tracing_retry(\r\n // The wake-forward rest op's seq source is a fresh `now_ms()` — its OWN\r\n // minting source, distinct from shellchan's spool-row counter (doyle ruling:\r\n // the tag names the seq source, not the subsystem), so it stamps `wake`.\r\n || Ok(crate::effect::MintedOp::new(crate::effect::Minter::Wake, now_ms())),\r\n |op| {\r\n let conn = brain.net_dial(addr.clone(), None)?;\r\n // Keep the tracing string's seq consistent with the (possibly re-minted) op.\r\n let op_id = format!(\"{}:wakefwd:{}\", crate::presence::local_node_hex(), op.seq);\r\n crate::resthost::request_rest(\r\n &mut brain,\r\n conn.conn_id,\r\n owner,\r\n spt_net::net::rest::REST_EVENT_WAKE,\r\n &op_id,\r\n op,\r\n )\r\n },\r\n )\r\n .map_err(|e| format!(\"rest op: {e}\"))?;\r\n match outcome {\r\n crate::resthost::RestRequestOutcome::Edge(d) => Ok(format!(\"woke ({d})\")),\r\n crate::resthost::RestRequestOutcome::NoEdge => Ok(\"already awake\".to_string()),\r\n crate::resthost::RestRequestOutcome::Failed(e) => Err(e),\r\n crate::resthost::RestRequestOutcome::NoReply => {\r\n Err(\"refused or dropped (no reply)\".to_string())\r\n }\r\n }\r\n}\r\n\r\n/// Resolve one adapter **option**'s `[shell]` section through the merged view\r\n/// (composite addressing): `adapter_option` is the stored `[:profile]`\r\n/// string, split → parent lookup in `registered` → profile overlay (shipped or\r\n/// local). Returns an **owned** [`Shell`] — a profile produces a fresh merged\r\n/// manifest, not a borrow into the parent slice. A bare name resolves to the\r\n/// parent unmodified; a deregistered parent or a failed overlay yields `None`.\r\nfn shell_section_of(\r\n registered: &[(AdapterRecord, Manifest)],\r\n adapters_dir: &Path,\r\n adapter_option: &str,\r\n) -> Option {\r\n spt_runtime::registry::resolve_option_in(registered, adapters_dir, adapter_option)\r\n .ok()\r\n .filter(|m| m.adapter.kind == AdapterKind::Shell)\r\n .and_then(|m| m.shell)\r\n}\r\n\r\nfn now_ms() -> u64 {\r\n crate::brain::now_ms()\r\n}\r\n\r\n/// Fill a `wake_command` template.\r\n///\r\n/// **Its catalog and the spawn template's share a vocabulary; they are not the\r\n/// same set, and never claiming they are is the point of saying so here.** The\r\n/// keys mean the same thing in both (`id`, `adapter_name`, `link_token`,\r\n/// `adapter_dir`), so an author learns one manifest language — but `perch_dir`\r\n/// is **spawn-only by design** (REQ-SHELL-PERCH-DIR: it resolves a *live* link's\r\n/// perch-relative transfer paths, and a waker has no live link). A comment\r\n/// asserting set-EQUALITY over two sets that are separately extended is the\r\n/// drift this project single-sources against; it had already been false since\r\n/// `perch_dir` landed.\r\n///\r\n/// The waker's token is minted **unparked**: it substitutes (template\r\n/// compatibility) without ever verifying against the perch, because an offline\r\n/// link has no live credential by design — the close retired it, and a waker\r\n/// wakes by *exit code*, not by driving the link.\r\n///\r\n/// `install_dir` resolves the program token and fills `{adapter_dir}`, exactly as\r\n/// on the spawn side ([`crate::shellhost::fill_spawn_command`]) — a released\r\n/// adapter whose spawn resolves and whose wake does not would go permanently\r\n/// unwakeable the moment it went offline.\r\nfn fill_wake_command(\r\n shell_id: &str,\r\n adapter_name: &str,\r\n install_dir: Option<&Path>,\r\n wake_command: &str,\r\n) -> Result, String> {\r\n let mut keys = std::collections::BTreeMap::from([\r\n (\"id\".to_string(), shell_id.to_string()),\r\n (\"adapter_name\".to_string(), adapter_name.to_string()),\r\n (\r\n \"link_token\".to_string(),\r\n crate::shellhost::mint_link_token(),\r\n ),\r\n ]);\r\n // [impl->REQ-INSTALL-11] opt-in and N-1-safe: a template that never names the\r\n // key fills byte-identically.\r\n if let Some(dir) = install_dir {\r\n keys.insert(\"adapter_dir\".to_string(), dir.display().to_string());\r\n }\r\n // [impl->REQ-HAZARD-TEMPLATE-ARGV-FILL] tokenize-template-then-fill-each: a\r\n // multi-word/quote/semicolon {key} value is exactly one argv element.\r\n let mut tokens =\r\n spt_runtime::runtime::fill_template_tokens(wake_command, &keys).map_err(|e| e.to_string())?;\r\n let Some(program) = tokens.first_mut() else {\r\n return Err(\"empty wake_command\".into());\r\n };\r\n // [impl->REQ-INSTALL-11] one resolution primitive, no parallel path.\r\n if let Some(dir) = install_dir {\r\n *program = spt_runtime::runtime::resolve_program_in_dir(program, dir);\r\n }\r\n Ok(tokens)\r\n}\r\n\r\n/// One reconcile sweep — the invariant holder for the online/offline mutual\r\n/// exclusivity (CONTEXT: \"spt-core flips between them\"):\r\n///\r\n/// - **offline + `wake_command` + no give-up latch + no live watcher** ⇒\r\n/// kill any orphaned waker pid (a dead daemon's leftover), then start a\r\n/// supervision thread.\r\n/// - **not offline (onlined / torn down / deregistered) + live watcher** ⇒\r\n/// stop it (flag + kill).\r\n///\r\n/// Runs at daemon boot and every tick — lifecycle flips happen in CLI-process\r","startLine":265,"lineNumbers":[265,null,273,null,280,null,296,null,298,299,300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,418,419,420,421,422,423,424,425,426,427,428,429,430,431,432,433,434,435,436,437,438,439,440,441,442,443,444,445,446,447,448,449,450,451,452,453,454,455,456,457,458,459,460,461,462,463,464,465,466,467,468,469,470,471,472,473,474,475,476,477,478,479,480,481,482,483,484,485,486,487,488,489,490,491,492,493,494,495,496,497,498,499,500,501,502,503,504,505,506,507,508,509,510,511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532,533,534,535,536,537,538,539,540,541,542,543,544,545,546,547,548,549,550,551,552,553,554,555,556,557,558,559,560,561,562,563,564,565,566,567,568,569,570,571,572,573,574,575,576,577,578,579,580,581,582,583,584,585,586,587,588,589,590,591,592,593]},"fileSize":100821,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\crates\\spt-daemon\\src\\shellwake.rs"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":2161,"totalBytes":14209,"outputLines":295,"outputBytes":14209,"shownRange":{"start":299,"end":593},"nextOffset":594}}},"isError":false,"timestamp":1789001151867}}
{"type":"message","id":"7daa760a","parentId":"6fdf3f2a","timestamp":"2026-09-10T00:45:51.885Z","message":{"role":"toolResult","toolCallId":"call_86q7GdHeGBRmNxe4753yUR3N|fc_077f3569365e313d016aa1fdbfc92487d18187cf49e1242bd2","toolName":"read","content":[{"type":"text","text":"/// `force = true` answers the field ask (releases#6): the instance IS up and\n/// wants a stop-then-restart WITHOUT churning its canonical id through\n/// teardown + spawn. The stop is [`shellhost::close_shell`] — the one existing\n/// link-break close, reused whole rather than reimplemented, so a forced relink\n/// breaks a link exactly the way every other link-break does (pre-close\n/// instruction, termination window, authenticated kill, token retired for the\n/// spool's sake, drive + tunnel slots cleared). It is bracketed by two refusals\n/// that `CloseOutcome` cannot express, which is why they live here and not in\n/// the close:\n///\n/// - **before**: an `ephemeral` instance's close is a TEARDOWN. Refused.\n/// - **after**: a close can legitimately leave the binary running (the kill is\n/// authenticated and may be refused, or the binary outlives the window), and\n/// launching there yields two binaries for one instance — the second one\n/// unreachable through the retired token and invisible to the record.\n/// Refused, on the SAME pid+birth pair the kill path authenticates with.\n// [impl->REQ-SHELL-RELINK-FORCE]\npub fn relink_shell_forced_from(\n origin: LaunchOrigin,\n owlery: &Path,\n owner: &str,\n shell_ref: &str,\n force: bool,\n) -> Result<(String, u32), ShellLinkError> {\n let (id, info, shell) = resolve_link_target(owlery, owner, shell_ref)?;\n // DERIVED, not recorded (REQ-HAZARD-SHELL-STALE-ONLINE). This is the gate\n // flynn's field report died on: an abruptly-killed binary leaves status\n // `online`, so the one command that recovers the instance refused on the very\n // state that was wrong, and teardown+spawn (perch destroyed, canonical id\n // churned) was the only exit. The probe is LOCAL — recovery must not depend on\n // a daemon sweep having run, or on a daemon running at all.\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n if shellinfo::is_shell_online(&perch, &info) {\n if !force {\n return Err(ShellLinkError::AlreadyOnline);\n }\n // [impl->REQ-SHELL-RELINK-FORCE] the stop half runs ONLY here: an\n // already-offline instance takes the plain relink even under the flag,\n // so --force is an override of one refusal and not a second code path\n // for the ordinary case.\n force_stop_for_relink(owlery, owner, &id, &shell, &perch)?;\n }\n // [impl->REQ-INSTALL-11] a relink is a launch — it resolves the adapter's\n // shipped binary the same way `spt shell spawn` did, or the one command that\n // recovers a released instance would refuse where the spawn succeeded.\n let install_dir =\n shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), &info.adapter_name);\n // An INDETERMINATE hand-off carries its uncertainty into the message rather\n // than being flattened into \"failed\": a relink mints nothing, so there is\n // nothing to roll back here, but a caller told \"failed\" about a binary that\n // may well be coming up would relink again and double it.\n let pid = shellhost::launch_shell_from(\n origin,\n owlery,\n owner,\n &id,\n &info.adapter_name,\n install_dir.as_deref(),\n &shell,\n )\n .map_err(|e| match e {\n shellhost::LaunchFailure::Indeterminate(m) => ShellLinkError::Failed(format!(\n \"launch handed to the daemon, outcome UNKNOWN — the binary may or may not be \\\n running ({m}); check `spt shell list` before relinking again\"\n )),\n shellhost::LaunchFailure::Failed(m) => ShellLinkError::Failed(format!(\"launch: {m}\")),\n })?;\n Ok((id, pid))\n}\n\n/// The DAEMON half of a routed CLI launch (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE): a\n/// THIN launch keyed `{owner, shell_id}` — resolve the record, the registered\n/// `[shell]` and the adapter install dir, then spawn HERE, where the process is\n/// job-neutral.\n///\n/// Deliberately NOT [`relink_shell`]: relink is the ONLINE SWITCH for an\n/// existing instance and carries an already-online refusal plus a link-token\n/// vocabulary a FRESH spawn has no answer to (a just-minted instance has no\n/// parked token at all ⇒ `NoLink`). And deliberately NOT a gate: the spawn\n/// gates, the instance cap and every consent prompt ran CLI-side before this op\n/// was ever sent — this call is the spawn, and only the spawn.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\npub fn launch_shell_daemon_side(owlery: &Path, owner: &str, shell_id: &str) -> Result {\n let (id, info, shell) =\n resolve_link_target(owlery, owner, shell_id).map_err(|e| format!(\"{e:?}\"))?;\n // THE side that stands down when a late ack raced the caller into its own\n // in-process fallback (see `LAUNCH_ACK_BOUND`). The ack precedes this\n // launch, so a caller that gave up waiting spawned FIRST — meaning the\n // binary this finds is its own, and adopting the pid answers the op\n // truthfully. Non-fault wording on purpose: a stood-down launch is a\n // success, and must never read like a fault latch.\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\n if let Some(pid) = shellhost::live_launch_winner(&perch) {\n spt_proto::emit_line_err!(\"SHELL_LAUNCH_STOOD_DOWN:{id}: already launched pid={pid} (online at bind)\");\n return Ok(pid);\n }\n let install_dir =\n shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), &info.adapter_name);\n shellhost::launch_shell(\n owlery,\n owner,\n &id,\n &info.adapter_name,\n install_dir.as_deref(),\n &shell,\n )\n}\n\n/// Why a shell-link serve returned — loud + typed, rendered into the\n/// dispatch log.\n#[derive(Debug, Clone, PartialEq, Eq)]\npub enum ShellLinkServeOutcome {\n /// The access gate refused the requesting origin — nothing ran, no reply.\n Refused,\n /// The action ran; the reply carried the report.\n Ok(String),\n /// The action failed; the failure text went back in the reply.\n Failed(String),\n /// The stream never produced a parseable request (or named an unknown\n /// action) — dropped.\n BadRequest(String),\n}\n\n/// Serve one shell-link stream against this node, blocking until the single\n/// request runs (or refuses). `origin_node` MUST be the handshake-proven\n/// remote id from the broker's stream table — never payload bytes\n/// (REQ-HAZARD-WAN-ORIGIN-AUTH). The gate subject is the wire-named owner\n/// (the xfer posture: the wire picks whose whitelist, the origin it is\n/// checked against stays transport-proven).\n// [impl->REQ-SHELL-2]\n// [impl->REQ-HAZARD-WAN-ORIGIN-AUTH]\npub fn serve_shell_link(\n brain: &mut Brain,\n stream_id: u64,\n origin_node: &str,\n owlery: &Path,\n) -> io::Result {\n brain.net_stream_subscribe(stream_id, 0)?;\n let mut decoder = ShellLinkDecoder::new();\n loop {\n match brain.read_event()? {\n BrokerEvent::NetStreamData {\n stream_id: sid,\n bytes,\n ..\n } if sid == stream_id => {\n for rec in decoder.push(&bytes) {\n let ShellLinkRecord::Request {\n…\n } = rec\n…\n };\n…\n }\n }\n…\n }\n }\n}\n\n[Showing lines 644-793 of 1747. Use :794 to continue]"}],"details":{"truncation":{"content":"/// `force = true` answers the field ask (releases#6): the instance IS up and\r\n/// wants a stop-then-restart WITHOUT churning its canonical id through\r\n/// teardown + spawn. The stop is [`shellhost::close_shell`] — the one existing\r\n/// link-break close, reused whole rather than reimplemented, so a forced relink\r\n/// breaks a link exactly the way every other link-break does (pre-close\r\n/// instruction, termination window, authenticated kill, token retired for the\r\n/// spool's sake, drive + tunnel slots cleared). It is bracketed by two refusals\r\n/// that `CloseOutcome` cannot express, which is why they live here and not in\r\n/// the close:\r\n///\r\n/// - **before**: an `ephemeral` instance's close is a TEARDOWN. Refused.\r\n/// - **after**: a close can legitimately leave the binary running (the kill is\r\n/// authenticated and may be refused, or the binary outlives the window), and\r\n/// launching there yields two binaries for one instance — the second one\r\n/// unreachable through the retired token and invisible to the record.\r\n/// Refused, on the SAME pid+birth pair the kill path authenticates with.\r\n// [impl->REQ-SHELL-RELINK-FORCE]\r\npub fn relink_shell_forced_from(\r\n origin: LaunchOrigin,\r\n owlery: &Path,\r\n owner: &str,\r\n shell_ref: &str,\r\n force: bool,\r\n) -> Result<(String, u32), ShellLinkError> {\r\n let (id, info, shell) = resolve_link_target(owlery, owner, shell_ref)?;\r\n // DERIVED, not recorded (REQ-HAZARD-SHELL-STALE-ONLINE). This is the gate\r\n // flynn's field report died on: an abruptly-killed binary leaves status\r\n // `online`, so the one command that recovers the instance refused on the very\r\n // state that was wrong, and teardown+spawn (perch destroyed, canonical id\r\n // churned) was the only exit. The probe is LOCAL — recovery must not depend on\r\n // a daemon sweep having run, or on a daemon running at all.\r\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\r\n if shellinfo::is_shell_online(&perch, &info) {\r\n if !force {\r\n return Err(ShellLinkError::AlreadyOnline);\r\n }\r\n // [impl->REQ-SHELL-RELINK-FORCE] the stop half runs ONLY here: an\r\n // already-offline instance takes the plain relink even under the flag,\r\n // so --force is an override of one refusal and not a second code path\r\n // for the ordinary case.\r\n force_stop_for_relink(owlery, owner, &id, &shell, &perch)?;\r\n }\r\n // [impl->REQ-INSTALL-11] a relink is a launch — it resolves the adapter's\r\n // shipped binary the same way `spt shell spawn` did, or the one command that\r\n // recovers a released instance would refuse where the spawn succeeded.\r\n let install_dir =\r\n shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), &info.adapter_name);\r\n // An INDETERMINATE hand-off carries its uncertainty into the message rather\r\n // than being flattened into \"failed\": a relink mints nothing, so there is\r\n // nothing to roll back here, but a caller told \"failed\" about a binary that\r\n // may well be coming up would relink again and double it.\r\n let pid = shellhost::launch_shell_from(\r\n origin,\r\n owlery,\r\n owner,\r\n &id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n &shell,\r\n )\r\n .map_err(|e| match e {\r\n shellhost::LaunchFailure::Indeterminate(m) => ShellLinkError::Failed(format!(\r\n \"launch handed to the daemon, outcome UNKNOWN — the binary may or may not be \\\r\n running ({m}); check `spt shell list` before relinking again\"\r\n )),\r\n shellhost::LaunchFailure::Failed(m) => ShellLinkError::Failed(format!(\"launch: {m}\")),\r\n })?;\r\n Ok((id, pid))\r\n}\r\n\r\n/// The DAEMON half of a routed CLI launch (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE): a\r\n/// THIN launch keyed `{owner, shell_id}` — resolve the record, the registered\r\n/// `[shell]` and the adapter install dir, then spawn HERE, where the process is\r\n/// job-neutral.\r\n///\r\n/// Deliberately NOT [`relink_shell`]: relink is the ONLINE SWITCH for an\r\n/// existing instance and carries an already-online refusal plus a link-token\r\n/// vocabulary a FRESH spawn has no answer to (a just-minted instance has no\r\n/// parked token at all ⇒ `NoLink`). And deliberately NOT a gate: the spawn\r\n/// gates, the instance cap and every consent prompt ran CLI-side before this op\r\n/// was ever sent — this call is the spawn, and only the spawn.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\npub fn launch_shell_daemon_side(owlery: &Path, owner: &str, shell_id: &str) -> Result {\r\n let (id, info, shell) =\r\n resolve_link_target(owlery, owner, shell_id).map_err(|e| format!(\"{e:?}\"))?;\r\n // THE side that stands down when a late ack raced the caller into its own\r\n // in-process fallback (see `LAUNCH_ACK_BOUND`). The ack precedes this\r\n // launch, so a caller that gave up waiting spawned FIRST — meaning the\r\n // binary this finds is its own, and adopting the pid answers the op\r\n // truthfully. Non-fault wording on purpose: a stood-down launch is a\r\n // success, and must never read like a fault latch.\r\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\r\n if let Some(pid) = shellhost::live_launch_winner(&perch) {\r\n spt_proto::emit_line_err!(\"SHELL_LAUNCH_STOOD_DOWN:{id}: already launched pid={pid} (online at bind)\");\r\n return Ok(pid);\r\n }\r\n let install_dir =\r\n shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), &info.adapter_name);\r\n shellhost::launch_shell(\r\n owlery,\r\n owner,\r\n &id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n &shell,\r\n )\r\n}\r\n\r\n/// Why a shell-link serve returned — loud + typed, rendered into the\r\n/// dispatch log.\r\n#[derive(Debug, Clone, PartialEq, Eq)]\r\npub enum ShellLinkServeOutcome {\r\n /// The access gate refused the requesting origin — nothing ran, no reply.\r\n Refused,\r\n /// The action ran; the reply carried the report.\r\n Ok(String),\r\n /// The action failed; the failure text went back in the reply.\r\n Failed(String),\r\n /// The stream never produced a parseable request (or named an unknown\r\n /// action) — dropped.\r\n BadRequest(String),\r\n}\r\n\r\n/// Serve one shell-link stream against this node, blocking until the single\r\n/// request runs (or refuses). `origin_node` MUST be the handshake-proven\r\n/// remote id from the broker's stream table — never payload bytes\r\n/// (REQ-HAZARD-WAN-ORIGIN-AUTH). The gate subject is the wire-named owner\r\n/// (the xfer posture: the wire picks whose whitelist, the origin it is\r\n/// checked against stays transport-proven).\r\n// [impl->REQ-SHELL-2]\r\n// [impl->REQ-HAZARD-WAN-ORIGIN-AUTH]\r\npub fn serve_shell_link(\r\n brain: &mut Brain,\r\n stream_id: u64,\r\n origin_node: &str,\r\n owlery: &Path,\r\n) -> io::Result {\r\n brain.net_stream_subscribe(stream_id, 0)?;\r\n let mut decoder = ShellLinkDecoder::new();\r\n loop {\r\n match brain.read_event()? {\r\n BrokerEvent::NetStreamData {\r\n stream_id: sid,\r\n bytes,\r\n ..\r\n } if sid == stream_id => {\r\n for rec in decoder.push(&bytes) {\r\n let ShellLinkRecord::Request {\r","truncated":true,"truncatedBy":"lines","totalLines":1104,"totalBytes":7464,"outputLines":150,"outputBytes":7464,"lastLinePartial":false,"firstLineExceedsLimit":false},"totalLines":1747,"displayContent":{"text":"/// `force = true` answers the field ask (releases#6): the instance IS up and\r\n/// wants a stop-then-restart WITHOUT churning its canonical id through\r\n/// teardown + spawn. The stop is [`shellhost::close_shell`] — the one existing\r\n/// link-break close, reused whole rather than reimplemented, so a forced relink\r\n/// breaks a link exactly the way every other link-break does (pre-close\r\n/// instruction, termination window, authenticated kill, token retired for the\r\n/// spool's sake, drive + tunnel slots cleared). It is bracketed by two refusals\r\n/// that `CloseOutcome` cannot express, which is why they live here and not in\r\n/// the close:\r\n///\r\n/// - **before**: an `ephemeral` instance's close is a TEARDOWN. Refused.\r\n/// - **after**: a close can legitimately leave the binary running (the kill is\r\n/// authenticated and may be refused, or the binary outlives the window), and\r\n/// launching there yields two binaries for one instance — the second one\r\n/// unreachable through the retired token and invisible to the record.\r\n/// Refused, on the SAME pid+birth pair the kill path authenticates with.\r\n// [impl->REQ-SHELL-RELINK-FORCE]\r\npub fn relink_shell_forced_from(\r\n origin: LaunchOrigin,\r\n owlery: &Path,\r\n owner: &str,\r\n shell_ref: &str,\r\n force: bool,\r\n) -> Result<(String, u32), ShellLinkError> {\r\n let (id, info, shell) = resolve_link_target(owlery, owner, shell_ref)?;\r\n // DERIVED, not recorded (REQ-HAZARD-SHELL-STALE-ONLINE). This is the gate\r\n // flynn's field report died on: an abruptly-killed binary leaves status\r\n // `online`, so the one command that recovers the instance refused on the very\r\n // state that was wrong, and teardown+spawn (perch destroyed, canonical id\r\n // churned) was the only exit. The probe is LOCAL — recovery must not depend on\r\n // a daemon sweep having run, or on a daemon running at all.\r\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\r\n if shellinfo::is_shell_online(&perch, &info) {\r\n if !force {\r\n return Err(ShellLinkError::AlreadyOnline);\r\n }\r\n // [impl->REQ-SHELL-RELINK-FORCE] the stop half runs ONLY here: an\r\n // already-offline instance takes the plain relink even under the flag,\r\n // so --force is an override of one refusal and not a second code path\r\n // for the ordinary case.\r\n force_stop_for_relink(owlery, owner, &id, &shell, &perch)?;\r\n }\r\n // [impl->REQ-INSTALL-11] a relink is a launch — it resolves the adapter's\r\n // shipped binary the same way `spt shell spawn` did, or the one command that\r\n // recovers a released instance would refuse where the spawn succeeded.\r\n let install_dir =\r\n shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), &info.adapter_name);\r\n // An INDETERMINATE hand-off carries its uncertainty into the message rather\r\n // than being flattened into \"failed\": a relink mints nothing, so there is\r\n // nothing to roll back here, but a caller told \"failed\" about a binary that\r\n // may well be coming up would relink again and double it.\r\n let pid = shellhost::launch_shell_from(\r\n origin,\r\n owlery,\r\n owner,\r\n &id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n &shell,\r\n )\r\n .map_err(|e| match e {\r\n shellhost::LaunchFailure::Indeterminate(m) => ShellLinkError::Failed(format!(\r\n \"launch handed to the daemon, outcome UNKNOWN — the binary may or may not be \\\r\n running ({m}); check `spt shell list` before relinking again\"\r\n )),\r\n shellhost::LaunchFailure::Failed(m) => ShellLinkError::Failed(format!(\"launch: {m}\")),\r\n })?;\r\n Ok((id, pid))\r\n}\r\n\r\n/// The DAEMON half of a routed CLI launch (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE): a\r\n/// THIN launch keyed `{owner, shell_id}` — resolve the record, the registered\r\n/// `[shell]` and the adapter install dir, then spawn HERE, where the process is\r\n/// job-neutral.\r\n///\r\n/// Deliberately NOT [`relink_shell`]: relink is the ONLINE SWITCH for an\r\n/// existing instance and carries an already-online refusal plus a link-token\r\n/// vocabulary a FRESH spawn has no answer to (a just-minted instance has no\r\n/// parked token at all ⇒ `NoLink`). And deliberately NOT a gate: the spawn\r\n/// gates, the instance cap and every consent prompt ran CLI-side before this op\r\n/// was ever sent — this call is the spawn, and only the spawn.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\npub fn launch_shell_daemon_side(owlery: &Path, owner: &str, shell_id: &str) -> Result {\r\n let (id, info, shell) =\r\n resolve_link_target(owlery, owner, shell_id).map_err(|e| format!(\"{e:?}\"))?;\r\n // THE side that stands down when a late ack raced the caller into its own\r\n // in-process fallback (see `LAUNCH_ACK_BOUND`). The ack precedes this\r\n // launch, so a caller that gave up waiting spawned FIRST — meaning the\r\n // binary this finds is its own, and adopting the pid answers the op\r\n // truthfully. Non-fault wording on purpose: a stood-down launch is a\r\n // success, and must never read like a fault latch.\r\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, &id);\r\n if let Some(pid) = shellhost::live_launch_winner(&perch) {\r\n spt_proto::emit_line_err!(\"SHELL_LAUNCH_STOOD_DOWN:{id}: already launched pid={pid} (online at bind)\");\r\n return Ok(pid);\r\n }\r\n let install_dir =\r\n shellhost::shell_install_dir(&spt_store::perch::adapters_dir(), &info.adapter_name);\r\n shellhost::launch_shell(\r\n owlery,\r\n owner,\r\n &id,\r\n &info.adapter_name,\r\n install_dir.as_deref(),\r\n &shell,\r\n )\r\n}\r\n\r\n/// Why a shell-link serve returned — loud + typed, rendered into the\r\n/// dispatch log.\r\n#[derive(Debug, Clone, PartialEq, Eq)]\r\npub enum ShellLinkServeOutcome {\r\n /// The access gate refused the requesting origin — nothing ran, no reply.\r\n Refused,\r\n /// The action ran; the reply carried the report.\r\n Ok(String),\r\n /// The action failed; the failure text went back in the reply.\r\n Failed(String),\r\n /// The stream never produced a parseable request (or named an unknown\r\n /// action) — dropped.\r\n BadRequest(String),\r\n}\r\n\r\n/// Serve one shell-link stream against this node, blocking until the single\r\n/// request runs (or refuses). `origin_node` MUST be the handshake-proven\r\n/// remote id from the broker's stream table — never payload bytes\r\n/// (REQ-HAZARD-WAN-ORIGIN-AUTH). The gate subject is the wire-named owner\r\n/// (the xfer posture: the wire picks whose whitelist, the origin it is\r\n/// checked against stays transport-proven).\r\n// [impl->REQ-SHELL-2]\r\n// [impl->REQ-HAZARD-WAN-ORIGIN-AUTH]\r\npub fn serve_shell_link(\r\n brain: &mut Brain,\r\n stream_id: u64,\r\n origin_node: &str,\r\n owlery: &Path,\r\n) -> io::Result {\r\n brain.net_stream_subscribe(stream_id, 0)?;\r\n let mut decoder = ShellLinkDecoder::new();\r\n loop {\r\n match brain.read_event()? {\r\n BrokerEvent::NetStreamData {\r\n stream_id: sid,\r\n bytes,\r\n ..\r\n } if sid == stream_id => {\r\n for rec in decoder.push(&bytes) {\r\n let ShellLinkRecord::Request {\r\n…\n } = rec\n…\n };\n…\n }\n }\n…\n }\n }\n}","startLine":644,"lineNumbers":[644,645,646,647,648,649,650,651,652,653,654,655,656,657,658,659,660,661,662,663,664,665,666,667,668,669,670,671,672,673,674,675,676,677,678,679,680,681,682,683,684,685,686,687,688,689,690,691,692,693,694,695,696,697,698,699,700,701,702,703,704,705,706,707,708,709,710,711,712,713,714,715,716,717,718,719,720,721,722,723,724,725,726,727,728,729,730,731,732,733,734,735,736,737,738,739,740,741,742,743,744,745,746,747,748,749,750,751,752,753,754,755,756,757,758,759,760,761,762,763,764,765,766,767,768,769,770,771,772,773,774,775,776,777,778,779,780,781,782,783,784,785,786,787,788,789,790,791,792,793,null,799,null,802,null,820,821,null,830,831,832]},"fileSize":85499,"meta":{"source":{"type":"path","value":"C:\\Users\\decid\\Documents\\projects\\spt-core\\.worktrees\\287-shellrestore\\crates\\spt-daemon\\src\\linkhost.rs"},"truncation":{"direction":"head","truncatedBy":"lines","totalLines":1747,"totalBytes":7464,"outputLines":150,"outputBytes":7464,"shownRange":{"start":644,"end":793},"nextOffset":794}}},"isError":false,"timestamp":1789001151885}}
{"type":"message","id":"905372b3","parentId":"7daa760a","timestamp":"2026-09-10T00:45:51.897Z","message":{"role":"toolResult","toolCallId":"call_LhwwqTqtbNXGA5WfqmpAvEyX|fc_077f3569365e313d016aa1fdbfc90c87d185cc29b3b7e71d6a","toolName":"read","content":[{"type":"text","text":"//! Shell-instance hosting (M5-D3b — CONTEXT §Shell model, §local-link\n//! authentication): the broker-launch + local-link handshake half of the\n//! shell machinery.\n//!\n//! **Broker-launched, never user-launched.** [`launch_shell`] mints a\n//! per-link token, parks it on the shell perch, fills the manifest's opaque\n//! `spawn` template (`{link_token}` + `{id}`/`{adapter_name}` from the\n//! guaranteed catalog) and spawns the binary detached — the only way a shell\n//! binary ever starts. Launch failure rolls nothing forward: the caller\n//! tears the just-minted perch back down (no half-built instance).\n//!\n//! **The local-link handshake.** Cross-node traffic already rides Iroh\n//! (E2E-encrypted); the exposed surface is the *same-node* channel where the\n//! least-trusted code in the system (the shell binary) touches SPT. The\n//! handshake: possession of the minted token **is** the bind credential —\n//! `spt api bind-shell --link ` resolves the instance *by token*\n//! ([`bind_shell_by_token`]: the binary needs no owner/id knowledge beyond\n//! its argv) and flips the perch online. Every subsequent machinery message\n//! on the link authenticates with the token-derived key ([`link_key`] →\n//! [`frame_mac`], applied per-message by the D3c channels) so another local\n//! process can neither inject into nor spoof a link.\n// [impl->REQ-SHELL-1]\n\nuse std::collections::BTreeMap;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse hmac::{Hmac, Mac};\nuse sha2::{Digest, Sha256};\n\nuse spt_runtime::manifest::{AdapterKind, CommandReceipt, Manifest, Shell};\nuse spt_runtime::registry::AdapterRecord;\nuse spt_store::liveness::RelayLiveness;\nuse spt_store::shellinfo::{self, SHELL_STATUS_OFFLINE, SHELL_STATUS_ONLINE};\n\nuse crate::brain::{now_ms, Brain};\nuse crate::msg::SpawnReq;\nuse crate::shellchan::shell_session_label;\n\n/// Per-instance link-token filename within a shell perch dir (node-local\n/// runtime material, beside `info.json` — the perch *record* contract in\n/// STORAGE.md constrains `info.json`'s fields, not the perch's files).\npub const LINK_TOKEN_FILE: &str = \"link.token\";\n\n/// The most recently RETIRED link token (stashed by `close_shell`, consumed by\n/// the next launch's re-stamp). Never a live credential — bind resolves only\n/// [`LINK_TOKEN_FILE`]; this exists so pending spool rows stamped under the\n/// dead link survive the next token mint (REQ-HAZARD-SHELL-STALE-ONLINE).\npub const RETIRED_TOKEN_FILE: &str = \"link.token.retired\";\n/// The launched binary's OS pid — teardown's kill handle, and the evidence the\n/// derived-status resolver probes. Re-exported, never re-typed: the name is\n/// written here (launch/close) and MATCHED there\n/// ([`shellinfo::shell_pid_provably_dead`]), so both sides must be one const.\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\npub use spt_store::shellinfo::SHELL_PID_FILE;\n\n/// Mint a fresh link token: 32 hex chars of crypto-grade randomness (the\n/// `api.token` recipe — spt-proto's Ed25519 seed generator, no extra RNG dep).\npub fn mint_link_token() -> String {\n let seed = spt_proto::identity::Identity::generate().seed();\n seed[..16].iter().map(|b| format!(\"{b:02x}\")).collect()\n}\n\n/// Read a shell perch's parked link token.\npub fn read_link_token(shell_perch: &Path) -> Option {\n std::fs::read_to_string(shell_perch.join(LINK_TOKEN_FILE))\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n}\n\n/// The per-link channel key, derived from the minted token: `SHA-256(token)`.\n/// Both ends hold the token (spt parked it; the binary got it in argv), so\n/// both derive the same key without a second exchange.\n// [impl->REQ-SHELL-1]\npub fn link_key(token: &str) -> [u8; 32] {\n let mut h = Sha256::new();\n h.update(token.as_bytes());\n h.finalize().into()\n}\n\n/// Authenticate one link frame: `HMAC-SHA256(link_key, frame)`, hex. Required\n/// on every message both directions (CONTEXT §local-link authentication) —\n/// the D3c channels stamp + verify this per frame; a frame without a valid\n/// MAC is dropped, never processed.\n// [impl->REQ-SHELL-1]\npub fn frame_mac(key: &[u8; 32], frame: &[u8]) -> String {\n let mut mac = as Mac>::new_from_slice(key).expect(\"hmac accepts any key len\");\n mac.update(frame);\n mac.finalize()\n .into_bytes()\n .iter()\n .map(|b| format!(\"{b:02x}\"))\n .collect()\n}\n\n/// Verify a frame's MAC (constant-time inner compare via the hmac crate).\npub fn verify_frame_mac(key: &[u8; 32], frame: &[u8], mac_hex: &str) -> bool {\n let mut mac = as Mac>::new_from_slice(key).expect(\"hmac accepts any key len\");\n mac.update(frame);\n let Ok(bytes) = hex_decode(mac_hex) else {\n return false;\n };\n mac.verify_slice(&bytes).is_ok()\n}\n\nfn hex_decode(s: &str) -> Result, ()> {\n if !s.len().is_multiple_of(2) {\n return Err(());\n }\n (0..s.len())\n .step_by(2)\n .map(|i| u8::from_str_radix(&s[i..i + 2], 16).map_err(|_| ()))\n .collect()\n}\n\n/// The install dir an adapter-option's `[shell]` commands resolve against — the\n/// parent adapter record's `source_dir` (the live manifest's own directory in\n/// pointer mode). `None` when the option does not resolve to an active record.\n///\n/// One helper for every shell-family site (spawn AND wake) precisely because\n/// \"which dir\" is the kind of thing that drifts when each site works it out for\n/// itself: a profiled option resolves against its PARENT's install dir, and a\n/// site that split the option differently would silently resolve a different\n/// binary. A `:profile` overlays configuration, never provenance — the bits are\n/// the parent's.\n// [impl->REQ-INSTALL-11]\npub fn shell_install_dir(adapters_dir: &Path, adapter_option: &str) -> Option {\n spt_runtime::registry::resolve_option(adapters_dir, adapter_option)\n .ok()\n .map(|(record, _)| PathBuf::from(record.source_dir))\n}\n\n/// Fill the manifest's opaque `spawn` template for one instance (mints + parks\n/// the link token first — the binary may bind immediately) and tokenize it.\n/// Shared by the detached and broker-hosted launch paths.\n///\n/// `install_dir` is the adapter's own directory ([`shell_install_dir`]). It does\n/// two things, both of which a `--release`-installed shell adapter cannot work\n/// without (REQ-INSTALL-11's documented follow-on sites):\n/// - the program token resolves through it, so a bare program name binds to the\n/// adapter's SHIPPED binary before `PATH` — the same\n/// [`spt_runtime::runtime::resolve_program_in_dir`] primitive `[digest]`, the\n/// session `role.command` and `[service]` use, never a second implementation;\n/// - `{adapter_dir}` becomes fillable, so a template can name a resource beside\n/// that binary.\n///\n/// `None` means \"no install dir known\" and is not the same as an empty one: the\n/// program token then passes through for `PATH` to resolve exactly as before, and\n/// a template naming `{adapter_dir}` fails LOUDLY on the missing key rather than\n/// filling an empty string into a path.\nfn fill_spawn_command(\n owlery: &Path,\n owner: &str,\n shell_id: &str,\n adapter_name: &str,\n install_dir: Option<&Path>,\n shell: &Shell,\n) -> Result, String> {\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\n // Mutual exclusivity, the online side (M5-D4b): the watcher dies before\n // the binary rises — and any (re)launch is \"shell activity\", so the\n // crash give-up latch re-arms. [impl->REQ-SHELL-2]\n crate::shellwake::kill_waker_at(&perch);\n crate::shellwake::clear_gave_up(&perch);\n // The keys the pending spool rows may be stamped under: the still-parked\n // token of an abruptly-dead instance (the wake/relink path) AND the stash\n // a previous rotation retired (covers the graceful-close→relink path plus\n // one generation of race stragglers — see below). Read BEFORE the mint\n // overwrites the parked file.\n let parked_before_mint = read_link_token(&perch);\n let retired_before_mint = std::fs::read_to_string(perch.join(RETIRED_TOKEN_FILE)).ok();\n let token = mint_link_token();\n // Park the token BEFORE the spawn: the binary may bind immediately.\n std::fs::write(perch.join(LINK_TOKEN_FILE), &token).map_err(|e| format!(\"park token: {e}\"))?;\n // Token rotation carries the durable channel with it: re-stamp every\n // pending row from the old keys to the new, or the binary this launch\n // raises would verify them against the fresh key and (correctly) discard —\n // the wake-triggering command itself would be the one frame the wake loses\n // (flynn's field catch, 2026-07-25: #23 armed the wake and never answered;\n // #24/#19 spooled after the rotation and drained in order).\n //\n // Race + crash posture (todlando's A1/A2, 2026-07-25): a concurrent\n // `drive_shell` that read the OLD parked token and spools after this walk\n // finishes leaves a straggler row the walk never saw — so the old parked\n // token is STASHED (not erased) and the drain paths give any\n // retired-key row a second-chance re-stamp at delivery\n // ([`crate::shellchan::restamp_for_drain`]). The walk itself is\n // crash-safe and idempotent: each row rewrite is independent, a row\n // already carrying the new stamp does not verify under an old key and is\n // skipped, and a crash mid-walk leaves a mixed spool the NEXT rotation or\n // drain converts (both old keys stay candidates). Rows are selected by\n // MAC verification against the threaded new key — never by comparing a\n // token snapshot (the D-2 stale-snapshot class).\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n let new_key = link_key(&token);\n for old in [&parked_before_mint, &retired_before_mint].into_iter().flatten() {\n crate::shellchan::restamp_pending_at(&perch, &link_key(old), &new_key);\n }\n // Stash the just-rotated-out token for the drain's second chance; a\n // close-retired stash stays in place when this launch had no parked token\n // (the close path spools nothing new — NoLink — so it has no stragglers).\n if let Some(old) = &parked_before_mint {\n let _ = std::fs::write(perch.join(RETIRED_TOKEN_FILE), old);\n }\n\n let keys = BTreeMap::from([\n (\"id\".to_string(), shell_id.to_string()),\n (\"adapter_name\".to_string(), adapter_name.to_string()),\n (\"link_token\".to_string(), token),\n // [impl->REQ-SHELL-PERCH-DIR] {perch_dir}: the shell perch root, so the\n // binary can resolve a shell_file frame's PERCH-RELATIVE `path` attr\n // (files/-) — the child inherits the BROKER's cwd, so\n // without this no mechanical resolution exists. Opt-in and N-1-safe:\n // a template that never names the key fills byte-identically. The\n // frame's path deliberately STAYS relative (doyle ruling: an absolute\n // path in a spooled frame lies across perch moves / node boundaries).\n (\"perch_dir\".to_string(), perch.display().to_string()),\n ]);\n // [impl->REQ-INSTALL-11] {adapter_dir}: the adapter's own install dir, so a\n // released shell adapter can point at a resource it ships. Opt-in and N-1-safe\n // like {perch_dir} — a template that never names the key fills byte-identically.\n let keys = match install_dir {\n Some(dir) => {\n let mut keys = keys;\n keys.insert(\"adapter_dir\".to_string(), dir.display().to_string());\n keys\n }\n None => keys,\n };\n // [impl->REQ-HAZARD-TEMPLATE-ARGV-FILL] tokenize-template-then-fill-each: a\n // multi-word/quote/semicolon {key} value is exactly one argv element.\n let mut tokens =\n spt_runtime::runtime::fill_template_tokens(&shell.spawn, &keys).map_err(|e| e.to_string())?;\n let Some(program) = tokens.first_mut() else {\n return Err(\"empty spawn command\".into());\n };\n // [impl->REQ-INSTALL-11] one resolution primitive, no parallel path: a\n // `--release`-installed adapter declaring a bare program name binds to its\n // shipped binary before PATH. Without this such an adapter registers fine and\n // then fails at spawn with os error 2 — the gap that forced a hand-maintained\n // local manifest per node.\n if let Some(dir) = install_dir {\n *program = spt_runtime::runtime::resolve_program_in_dir(program, dir);\n }\n Ok(tokens)\n}\n\n/// WHO is asking for a launch — and therefore WHOSE Job Object the spawned\n/// binary would join (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE).\n///\n/// A daemon-side spawn is job-neutral: the daemon escaped the launching job at\n/// its own cold start (the WMI → schtasks → breakaway ladder). A CLI-side spawn\n/// is not — `spt shell spawn`, local `spt shell relink` and the `shell cmd`\n/// wake-if-offline arm all call the launch IN the terminal-resident CLI process,\n/// so on a job that forbids breakaway the shell binary (and every descendant it\n/// ever spawns, relay hops included) inherits the terminal's job.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n#[derive(Clone, Copy, Debug, PartialEq, Eq)]\npub enum LaunchOrigin {\n /// The caller IS the daemon (broker/brain): spawn here, already job-neutral.\n Daemon,\n /// The caller is a terminal-resident CLI: hand the launch to a running\n /// daemon when one answers, else spawn here and SAY whose job took the child.\n Cli,\n}\n\n/// A routed launch's failure, split by what the caller may safely do next.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n#[derive(Debug, Clone, PartialEq, Eq)]\npub enum LaunchFailure {\n /// The launch was attempted and failed. Undo whatever the launch was for.\n Failed(String),\n /// The launch was handed off and its outcome is UNKNOWN — the binary may be\n /// running. Neither retry nor undo: both are wrong half the time.\n Indeterminate(String),\n}\n\nimpl std::fmt::Display for LaunchFailure {\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n match self {\n LaunchFailure::Failed(m) | LaunchFailure::Indeterminate(m) => write!(f, \"{m}\"),\n }\n }\n}\n\nimpl LaunchFailure {\n /// Whether the outcome is unknown — the caller must keep what it built.\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n pub fn is_indeterminate(&self) -> bool {\n matches!(self, LaunchFailure::Indeterminate(_))\n }\n}\n\n/// Whether this shell's launch is the one that can be routed to the daemon: the\n/// DETACHED relay spawn, the only receipt that spawns in the calling process.\n///\n/// `stdin` already spawns broker-side (so it is job-neutral today, and routing\n/// it would make the broker connect to its own socket); `http` refuses at spawn.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\npub fn routes_through_daemon(shell: &Shell) -> bool {\n !matches!(\n shell.command_receipt,\n Some(CommandReceipt::Http) | Some(CommandReceipt::Stdin)\n )\n}\n\n/// The double-launch arbiter: the instance's recorded pid, when it probes\n/// ALIVE (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE).\n///\n/// `Some(pid)` ⇒ a launch of this same `{owner, shell_id}` already won — stand\n/// down and adopt it. Used by BOTH sides of the routed launch, because a late\n/// ack can put the caller and the daemon in the same launch at once.\n///\n/// Birth-safe, including a binary awaiting bind: a recycled live pid is NOT a\n/// winner when its native birth stamp mismatches. Missing, unparseable and zero\n/// pids remain not-a-winner, preserving pid-less backend behavior.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\npub fn live_launch_winner(shell_perch: &Path) -> Option {\n shellinfo::read_shell_pid(shell_perch)\n .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\n}\n\n/// THE route-selection seam. Generic over the daemon call and the in-process\n/// fallback so the decision can be tested without a socket, a daemon or a job.\n///\n/// The invariant it exists to hold: **the ack is a commitment transfer** — a\n/// daemon that accepted owns the launch, so only a pre-ack refusal\n/// ([`LaunchRouteError::fallback_allowed`](crate::drivehub::LaunchRouteError::fallback_allowed))\n/// may fall through to an in-process spawn. Anything else returning a second\n/// spawn would be the double-launch this routing exists to avoid.\n///\n/// Two axes, deliberately separate: `fallback_allowed` decides whether a second\n/// spawn is PERMITTED, and\n/// [`may_have_launched`](crate::drivehub::LaunchRouteError::may_have_launched)\n/// decides whether one must first be ARBITRATED against a live pid. Only the\n/// unanswered wait is both.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\npub(crate) fn launch_routed(\n shell: &Shell,\n label: &str,\n via_daemon: impl FnOnce() -> Result,\n already_live: impl FnOnce() -> Option,\n in_process: impl FnOnce() -> Result,\n) -> Result {\n if !routes_through_daemon(shell) {\n return in_process().map_err(LaunchFailure::Failed);\n }\n match via_daemon() {\n Ok(pid) => Ok(pid),\n Err(e) if e.fallback_allowed() => {\n // A pre-ack refusal means nothing was spawned — EXCEPT for the one\n // pre-ack cause that is a timeout rather than an answer. A daemon\n // that acks late may already have launched, so THAT fallback checks\n // the arbiter before adding a second binary (the documented race at\n // `LAUNCH_ACK_BOUND`). Adopting the winner is a SUCCESS: the caller\n // wanted a running binary and there is one.\n //\n // The gate is `may_have_launched`, not `fallback_allowed`: running\n // the arbiter on an ANSWERED refusal adopts a pid no daemon could\n // have launched, so the fallback silently declines to spawn — and a\n // relink that never re-launches never mints, which is precisely the\n // recovery command failing on the state it exists to recover.\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\n // Gated by SHORT-CIRCUIT, not by filtering the answer: outside the\n // late-ack window the pid probe is not merely unused, it must not\n // run at all — that is one fewer place a pinned corpse handle can\n // report a dead pid alive.\n let winner = if e.may_have_launched() {\n already_live()\n } else {\n None\n };\n if let Some(pid) = winner {\n spt_proto::emit_line_err!(\n \"SHELL_LAUNCH_ALREADY_LIVE:{label}: a launch of this instance is already \\\n running (pid={pid}) — standing down instead of spawning a second binary\"\n );\n return Ok(pid);\n }\n // Nothing was spawned daemon-side. Say WHY the route was not taken\n // and WHOSE job the child is about to join — the three pre-ack\n // causes carry distinct names, so a field report can tell an old\n // daemon from a foreign home from no daemon at all.\n spt_proto::emit_line_err!(\n \"SHELL_LAUNCH_IN_PROCESS:{label}: {e} — spawning from THIS process instead, so \\\n the binary joins THIS process's Job Object (a DETACH_BREAKAWAY_DENIED line \\\n names it); the first daemon-side wake re-spawns it job-neutrally\"\n );\n in_process().map_err(LaunchFailure::Failed)\n }\n Err(e) if e.is_indeterminate() => Err(LaunchFailure::Indeterminate(e.to_string())),\n Err(e) => Err(LaunchFailure::Failed(e.to_string())),\n }\n}\n\n/// [`launch_shell`], routed by ORIGIN (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE).\n///\n/// From the daemon this is `launch_shell` verbatim. From a CLI it hands the\n/// launch to a running daemon over the drive control socket — so the binary\n/// rises job-neutral instead of inside the launching terminal's Job Object —\n/// and falls back to today's in-process spawn, loudly, when no daemon takes it.\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\npub fn launch_shell_from(\n origin: LaunchOrigin,\n owlery: &Path,\n owner: &str,\n shell_id: &str,\n adapter_name: &str,\n install_dir: Option<&Path>,\n shell: &Shell,\n) -> Result {\n match origin {\n LaunchOrigin::Daemon => {\n launch_shell(owlery, owner, shell_id, adapter_name, install_dir, shell)\n .map_err(LaunchFailure::Failed)\n }\n LaunchOrigin::Cli => launch_routed(\n shell,\n shell_id,\n || {\n crate::drivehub::shell_launch(\n &crate::endpoint::drive_socket_name(),\n owner,\n shell_id,\n owlery,\n )\n },\n || {\n live_launch_winner(&spt_store::perch::resolve_shell_perch_path_in(\n owlery, owner, shell_id,\n ))\n },\n || launch_shell(owlery, owner, shell_id, adapter_name, install_dir, shell),\n ),\n }\n}\n\n/// Launch a shell instance's binary per the manifest's `command_receipt`\n/// (M5-D3c): **relay** (default) spawns detached (stdio discarded — the\n/// binary drains via `api poll --link`); **stdin** spawns broker-hosted so\n/// the daemon owns the stdin pipe ([`launch_shell_brokered_in`] — command\n/// frames ride the broker's `send_effect` input seam); **http** refuses at\n/// spawn, explicitly — an unimplemented mode is never a silent fallback.\n/// Records the pid; returns it. The perch stays **offline** until the\n/// binary's `api bind-shell` handshake onlines it — launch is not the online\n/// switch any more than spawn is.\n// [impl->REQ-SHELL-1]\npub fn launch_shell(\n owlery: &Path,\n owner: &str,\n shell_id: &str,\n adapter_name: &str,\n install_dir: Option<&Path>,\n shell: &Shell,\n) -> Result {\n match shell.command_receipt {\n Some(CommandReceipt::Http) => Err(\n \"command_receipt=http is not implemented yet — spawn refused (an \\\n unimplemented mode never falls back silently)\"\n .into(),\n ),\n Some(CommandReceipt::Stdin) => {\n crate::ensure_running().map_err(|e| format!(\"daemon start: {e}\"))?;\n launch_shell_brokered_in(\n &crate::broker_socket_name(),\n owlery,\n owner,\n shell_id,\n adapter_name,\n install_dir,\n shell,\n )\n }\n _ => {\n let tokens =\n fill_spawn_command(owlery, owner, shell_id, adapter_name, install_dir, shell)?;\n let (program, args) = tokens.split_first().expect(\"non-empty checked\");\n // The shell binary is a LONG-LIVED detached child (KNOWN-HAZARDS\n // 5.6): on Windows it must inherit NO handles, or a caller\n // capturing `spt shell spawn`'s output — at any depth of the\n // process chain — hangs forever on a pipe write-end the immortal\n // child holds. Same no-inherit spawn as the daemon's.\n // [impl->REQ-HAZARD-DETACHED-PIPE-INHERIT]\n #[cfg(windows)]\n let pid = crate::daemon::detached_no_inherit(program, args)\n .map_err(|e| format!(\"spawn {program}: {e}\"))?;\n #[cfg(unix)]\n let pid = Command::new(program)\n .args(args)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .spawn()\n .map_err(|e| format!(\"spawn {program}: {e}\"))?\n .id();\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\n std::fs::write(perch.join(SHELL_PID_FILE), pid.to_string())\n .map_err(|e| format!(\"record pid: {e}\"))?;\n // The birth stamp rides WITH the pid at every launch, or the probe that\n // reads it degrades to bare-pid liveness on this instance alone -- a\n // silent per-instance regression rather than a visible one.\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\n spt_store::shellinfo::record_shell_launch(&perch, pid, now_ms());\n Ok(pid)\n }\n }\n}\n\n/// The stdin-receipt launch: spawn the filled template as a **broker-hosted**\n/// session labeled [`shell_session_label`], so the daemon owns the child's\n/// stdin and `spt shell cmd` can drive it through the `send_effect` input\n\n[Showing lines 1-513 of 1826. Use :514 to continue]"}],"details":{"truncation":{"content":"//! Shell-instance hosting (M5-D3b — CONTEXT §Shell model, §local-link\r\n//! authentication): the broker-launch + local-link handshake half of the\r\n//! shell machinery.\r\n//!\r\n//! **Broker-launched, never user-launched.** [`launch_shell`] mints a\r\n//! per-link token, parks it on the shell perch, fills the manifest's opaque\r\n//! `spawn` template (`{link_token}` + `{id}`/`{adapter_name}` from the\r\n//! guaranteed catalog) and spawns the binary detached — the only way a shell\r\n//! binary ever starts. Launch failure rolls nothing forward: the caller\r\n//! tears the just-minted perch back down (no half-built instance).\r\n//!\r\n//! **The local-link handshake.** Cross-node traffic already rides Iroh\r\n//! (E2E-encrypted); the exposed surface is the *same-node* channel where the\r\n//! least-trusted code in the system (the shell binary) touches SPT. The\r\n//! handshake: possession of the minted token **is** the bind credential —\r\n//! `spt api bind-shell --link ` resolves the instance *by token*\r\n//! ([`bind_shell_by_token`]: the binary needs no owner/id knowledge beyond\r\n//! its argv) and flips the perch online. Every subsequent machinery message\r\n//! on the link authenticates with the token-derived key ([`link_key`] →\r\n//! [`frame_mac`], applied per-message by the D3c channels) so another local\r\n//! process can neither inject into nor spoof a link.\r\n// [impl->REQ-SHELL-1]\r\n\r\nuse std::collections::BTreeMap;\r\nuse std::path::{Path, PathBuf};\r\nuse std::process::{Command, Stdio};\r\n\r\nuse hmac::{Hmac, Mac};\r\nuse sha2::{Digest, Sha256};\r\n\r\nuse spt_runtime::manifest::{AdapterKind, CommandReceipt, Manifest, Shell};\r\nuse spt_runtime::registry::AdapterRecord;\r\nuse spt_store::liveness::RelayLiveness;\r\nuse spt_store::shellinfo::{self, SHELL_STATUS_OFFLINE, SHELL_STATUS_ONLINE};\r\n\r\nuse crate::brain::{now_ms, Brain};\r\nuse crate::msg::SpawnReq;\r\nuse crate::shellchan::shell_session_label;\r\n\r\n/// Per-instance link-token filename within a shell perch dir (node-local\r\n/// runtime material, beside `info.json` — the perch *record* contract in\r\n/// STORAGE.md constrains `info.json`'s fields, not the perch's files).\r\npub const LINK_TOKEN_FILE: &str = \"link.token\";\r\n\r\n/// The most recently RETIRED link token (stashed by `close_shell`, consumed by\r\n/// the next launch's re-stamp). Never a live credential — bind resolves only\r\n/// [`LINK_TOKEN_FILE`]; this exists so pending spool rows stamped under the\r\n/// dead link survive the next token mint (REQ-HAZARD-SHELL-STALE-ONLINE).\r\npub const RETIRED_TOKEN_FILE: &str = \"link.token.retired\";\r\n/// The launched binary's OS pid — teardown's kill handle, and the evidence the\r\n/// derived-status resolver probes. Re-exported, never re-typed: the name is\r\n/// written here (launch/close) and MATCHED there\r\n/// ([`shellinfo::shell_pid_provably_dead`]), so both sides must be one const.\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub use spt_store::shellinfo::SHELL_PID_FILE;\r\n\r\n/// Mint a fresh link token: 32 hex chars of crypto-grade randomness (the\r\n/// `api.token` recipe — spt-proto's Ed25519 seed generator, no extra RNG dep).\r\npub fn mint_link_token() -> String {\r\n let seed = spt_proto::identity::Identity::generate().seed();\r\n seed[..16].iter().map(|b| format!(\"{b:02x}\")).collect()\r\n}\r\n\r\n/// Read a shell perch's parked link token.\r\npub fn read_link_token(shell_perch: &Path) -> Option {\r\n std::fs::read_to_string(shell_perch.join(LINK_TOKEN_FILE))\r\n .ok()\r\n .map(|s| s.trim().to_string())\r\n .filter(|s| !s.is_empty())\r\n}\r\n\r\n/// The per-link channel key, derived from the minted token: `SHA-256(token)`.\r\n/// Both ends hold the token (spt parked it; the binary got it in argv), so\r\n/// both derive the same key without a second exchange.\r\n// [impl->REQ-SHELL-1]\r\npub fn link_key(token: &str) -> [u8; 32] {\r\n let mut h = Sha256::new();\r\n h.update(token.as_bytes());\r\n h.finalize().into()\r\n}\r\n\r\n/// Authenticate one link frame: `HMAC-SHA256(link_key, frame)`, hex. Required\r\n/// on every message both directions (CONTEXT §local-link authentication) —\r\n/// the D3c channels stamp + verify this per frame; a frame without a valid\r\n/// MAC is dropped, never processed.\r\n// [impl->REQ-SHELL-1]\r\npub fn frame_mac(key: &[u8; 32], frame: &[u8]) -> String {\r\n let mut mac = as Mac>::new_from_slice(key).expect(\"hmac accepts any key len\");\r\n mac.update(frame);\r\n mac.finalize()\r\n .into_bytes()\r\n .iter()\r\n .map(|b| format!(\"{b:02x}\"))\r\n .collect()\r\n}\r\n\r\n/// Verify a frame's MAC (constant-time inner compare via the hmac crate).\r\npub fn verify_frame_mac(key: &[u8; 32], frame: &[u8], mac_hex: &str) -> bool {\r\n let mut mac = as Mac>::new_from_slice(key).expect(\"hmac accepts any key len\");\r\n mac.update(frame);\r\n let Ok(bytes) = hex_decode(mac_hex) else {\r\n return false;\r\n };\r\n mac.verify_slice(&bytes).is_ok()\r\n}\r\n\r\nfn hex_decode(s: &str) -> Result, ()> {\r\n if !s.len().is_multiple_of(2) {\r\n return Err(());\r\n }\r\n (0..s.len())\r\n .step_by(2)\r\n .map(|i| u8::from_str_radix(&s[i..i + 2], 16).map_err(|_| ()))\r\n .collect()\r\n}\r\n\r\n/// The install dir an adapter-option's `[shell]` commands resolve against — the\r\n/// parent adapter record's `source_dir` (the live manifest's own directory in\r\n/// pointer mode). `None` when the option does not resolve to an active record.\r\n///\r\n/// One helper for every shell-family site (spawn AND wake) precisely because\r\n/// \"which dir\" is the kind of thing that drifts when each site works it out for\r\n/// itself: a profiled option resolves against its PARENT's install dir, and a\r\n/// site that split the option differently would silently resolve a different\r\n/// binary. A `:profile` overlays configuration, never provenance — the bits are\r\n/// the parent's.\r\n// [impl->REQ-INSTALL-11]\r\npub fn shell_install_dir(adapters_dir: &Path, adapter_option: &str) -> Option {\r\n spt_runtime::registry::resolve_option(adapters_dir, adapter_option)\r\n .ok()\r\n .map(|(record, _)| PathBuf::from(record.source_dir))\r\n}\r\n\r\n/// Fill the manifest's opaque `spawn` template for one instance (mints + parks\r\n/// the link token first — the binary may bind immediately) and tokenize it.\r\n/// Shared by the detached and broker-hosted launch paths.\r\n///\r\n/// `install_dir` is the adapter's own directory ([`shell_install_dir`]). It does\r\n/// two things, both of which a `--release`-installed shell adapter cannot work\r\n/// without (REQ-INSTALL-11's documented follow-on sites):\r\n/// - the program token resolves through it, so a bare program name binds to the\r\n/// adapter's SHIPPED binary before `PATH` — the same\r\n/// [`spt_runtime::runtime::resolve_program_in_dir`] primitive `[digest]`, the\r\n/// session `role.command` and `[service]` use, never a second implementation;\r\n/// - `{adapter_dir}` becomes fillable, so a template can name a resource beside\r\n/// that binary.\r\n///\r\n/// `None` means \"no install dir known\" and is not the same as an empty one: the\r\n/// program token then passes through for `PATH` to resolve exactly as before, and\r\n/// a template naming `{adapter_dir}` fails LOUDLY on the missing key rather than\r\n/// filling an empty string into a path.\r\nfn fill_spawn_command(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n adapter_name: &str,\r\n install_dir: Option<&Path>,\r\n shell: &Shell,\r\n) -> Result, String> {\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n // Mutual exclusivity, the online side (M5-D4b): the watcher dies before\r\n // the binary rises — and any (re)launch is \"shell activity\", so the\r\n // crash give-up latch re-arms. [impl->REQ-SHELL-2]\r\n crate::shellwake::kill_waker_at(&perch);\r\n crate::shellwake::clear_gave_up(&perch);\r\n // The keys the pending spool rows may be stamped under: the still-parked\r\n // token of an abruptly-dead instance (the wake/relink path) AND the stash\r\n // a previous rotation retired (covers the graceful-close→relink path plus\r\n // one generation of race stragglers — see below). Read BEFORE the mint\r\n // overwrites the parked file.\r\n let parked_before_mint = read_link_token(&perch);\r\n let retired_before_mint = std::fs::read_to_string(perch.join(RETIRED_TOKEN_FILE)).ok();\r\n let token = mint_link_token();\r\n // Park the token BEFORE the spawn: the binary may bind immediately.\r\n std::fs::write(perch.join(LINK_TOKEN_FILE), &token).map_err(|e| format!(\"park token: {e}\"))?;\r\n // Token rotation carries the durable channel with it: re-stamp every\r\n // pending row from the old keys to the new, or the binary this launch\r\n // raises would verify them against the fresh key and (correctly) discard —\r\n // the wake-triggering command itself would be the one frame the wake loses\r\n // (flynn's field catch, 2026-07-25: #23 armed the wake and never answered;\r\n // #24/#19 spooled after the rotation and drained in order).\r\n //\r\n // Race + crash posture (todlando's A1/A2, 2026-07-25): a concurrent\r\n // `drive_shell` that read the OLD parked token and spools after this walk\r\n // finishes leaves a straggler row the walk never saw — so the old parked\r\n // token is STASHED (not erased) and the drain paths give any\r\n // retired-key row a second-chance re-stamp at delivery\r\n // ([`crate::shellchan::restamp_for_drain`]). The walk itself is\r\n // crash-safe and idempotent: each row rewrite is independent, a row\r\n // already carrying the new stamp does not verify under an old key and is\r\n // skipped, and a crash mid-walk leaves a mixed spool the NEXT rotation or\r\n // drain converts (both old keys stay candidates). Rows are selected by\r\n // MAC verification against the threaded new key — never by comparing a\r\n // token snapshot (the D-2 stale-snapshot class).\r\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\n let new_key = link_key(&token);\r\n for old in [&parked_before_mint, &retired_before_mint].into_iter().flatten() {\r\n crate::shellchan::restamp_pending_at(&perch, &link_key(old), &new_key);\r\n }\r\n // Stash the just-rotated-out token for the drain's second chance; a\r\n // close-retired stash stays in place when this launch had no parked token\r\n // (the close path spools nothing new — NoLink — so it has no stragglers).\r\n if let Some(old) = &parked_before_mint {\r\n let _ = std::fs::write(perch.join(RETIRED_TOKEN_FILE), old);\r\n }\r\n\r\n let keys = BTreeMap::from([\r\n (\"id\".to_string(), shell_id.to_string()),\r\n (\"adapter_name\".to_string(), adapter_name.to_string()),\r\n (\"link_token\".to_string(), token),\r\n // [impl->REQ-SHELL-PERCH-DIR] {perch_dir}: the shell perch root, so the\r\n // binary can resolve a shell_file frame's PERCH-RELATIVE `path` attr\r\n // (files/-) — the child inherits the BROKER's cwd, so\r\n // without this no mechanical resolution exists. Opt-in and N-1-safe:\r\n // a template that never names the key fills byte-identically. The\r\n // frame's path deliberately STAYS relative (doyle ruling: an absolute\r\n // path in a spooled frame lies across perch moves / node boundaries).\r\n (\"perch_dir\".to_string(), perch.display().to_string()),\r\n ]);\r\n // [impl->REQ-INSTALL-11] {adapter_dir}: the adapter's own install dir, so a\r\n // released shell adapter can point at a resource it ships. Opt-in and N-1-safe\r\n // like {perch_dir} — a template that never names the key fills byte-identically.\r\n let keys = match install_dir {\r\n Some(dir) => {\r\n let mut keys = keys;\r\n keys.insert(\"adapter_dir\".to_string(), dir.display().to_string());\r\n keys\r\n }\r\n None => keys,\r\n };\r\n // [impl->REQ-HAZARD-TEMPLATE-ARGV-FILL] tokenize-template-then-fill-each: a\r\n // multi-word/quote/semicolon {key} value is exactly one argv element.\r\n let mut tokens =\r\n spt_runtime::runtime::fill_template_tokens(&shell.spawn, &keys).map_err(|e| e.to_string())?;\r\n let Some(program) = tokens.first_mut() else {\r\n return Err(\"empty spawn command\".into());\r\n };\r\n // [impl->REQ-INSTALL-11] one resolution primitive, no parallel path: a\r\n // `--release`-installed adapter declaring a bare program name binds to its\r\n // shipped binary before PATH. Without this such an adapter registers fine and\r\n // then fails at spawn with os error 2 — the gap that forced a hand-maintained\r\n // local manifest per node.\r\n if let Some(dir) = install_dir {\r\n *program = spt_runtime::runtime::resolve_program_in_dir(program, dir);\r\n }\r\n Ok(tokens)\r\n}\r\n\r\n/// WHO is asking for a launch — and therefore WHOSE Job Object the spawned\r\n/// binary would join (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE).\r\n///\r\n/// A daemon-side spawn is job-neutral: the daemon escaped the launching job at\r\n/// its own cold start (the WMI → schtasks → breakaway ladder). A CLI-side spawn\r\n/// is not — `spt shell spawn`, local `spt shell relink` and the `shell cmd`\r\n/// wake-if-offline arm all call the launch IN the terminal-resident CLI process,\r\n/// so on a job that forbids breakaway the shell binary (and every descendant it\r\n/// ever spawns, relay hops included) inherits the terminal's job.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\n#[derive(Clone, Copy, Debug, PartialEq, Eq)]\r\npub enum LaunchOrigin {\r\n /// The caller IS the daemon (broker/brain): spawn here, already job-neutral.\r\n Daemon,\r\n /// The caller is a terminal-resident CLI: hand the launch to a running\r\n /// daemon when one answers, else spawn here and SAY whose job took the child.\r\n Cli,\r\n}\r\n\r\n/// A routed launch's failure, split by what the caller may safely do next.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\n#[derive(Debug, Clone, PartialEq, Eq)]\r\npub enum LaunchFailure {\r\n /// The launch was attempted and failed. Undo whatever the launch was for.\r\n Failed(String),\r\n /// The launch was handed off and its outcome is UNKNOWN — the binary may be\r\n /// running. Neither retry nor undo: both are wrong half the time.\r\n Indeterminate(String),\r\n}\r\n\r\nimpl std::fmt::Display for LaunchFailure {\r\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\r\n match self {\r\n LaunchFailure::Failed(m) | LaunchFailure::Indeterminate(m) => write!(f, \"{m}\"),\r\n }\r\n }\r\n}\r\n\r\nimpl LaunchFailure {\r\n /// Whether the outcome is unknown — the caller must keep what it built.\r\n // [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\n pub fn is_indeterminate(&self) -> bool {\r\n matches!(self, LaunchFailure::Indeterminate(_))\r\n }\r\n}\r\n\r\n/// Whether this shell's launch is the one that can be routed to the daemon: the\r\n/// DETACHED relay spawn, the only receipt that spawns in the calling process.\r\n///\r\n/// `stdin` already spawns broker-side (so it is job-neutral today, and routing\r\n/// it would make the broker connect to its own socket); `http` refuses at spawn.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\npub fn routes_through_daemon(shell: &Shell) -> bool {\r\n !matches!(\r\n shell.command_receipt,\r\n Some(CommandReceipt::Http) | Some(CommandReceipt::Stdin)\r\n )\r\n}\r\n\r\n/// The double-launch arbiter: the instance's recorded pid, when it probes\r\n/// ALIVE (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE).\r\n///\r\n/// `Some(pid)` ⇒ a launch of this same `{owner, shell_id}` already won — stand\r\n/// down and adopt it. Used by BOTH sides of the routed launch, because a late\r\n/// ack can put the caller and the daemon in the same launch at once.\r\n///\r\n/// Birth-safe, including a binary awaiting bind: a recycled live pid is NOT a\r\n/// winner when its native birth stamp mismatches. Missing, unparseable and zero\r\n/// pids remain not-a-winner, preserving pid-less backend behavior.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\n// [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\npub fn live_launch_winner(shell_perch: &Path) -> Option {\r\n shellinfo::read_shell_pid(shell_perch)\r\n .filter(|&p| p != 0 && !shellinfo::shell_pid_provably_dead(shell_perch))\r\n}\r\n\r\n/// THE route-selection seam. Generic over the daemon call and the in-process\r\n/// fallback so the decision can be tested without a socket, a daemon or a job.\r\n///\r\n/// The invariant it exists to hold: **the ack is a commitment transfer** — a\r\n/// daemon that accepted owns the launch, so only a pre-ack refusal\r\n/// ([`LaunchRouteError::fallback_allowed`](crate::drivehub::LaunchRouteError::fallback_allowed))\r\n/// may fall through to an in-process spawn. Anything else returning a second\r\n/// spawn would be the double-launch this routing exists to avoid.\r\n///\r\n/// Two axes, deliberately separate: `fallback_allowed` decides whether a second\r\n/// spawn is PERMITTED, and\r\n/// [`may_have_launched`](crate::drivehub::LaunchRouteError::may_have_launched)\r\n/// decides whether one must first be ARBITRATED against a live pid. Only the\r\n/// unanswered wait is both.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\npub(crate) fn launch_routed(\r\n shell: &Shell,\r\n label: &str,\r\n via_daemon: impl FnOnce() -> Result,\r\n already_live: impl FnOnce() -> Option,\r\n in_process: impl FnOnce() -> Result,\r\n) -> Result {\r\n if !routes_through_daemon(shell) {\r\n return in_process().map_err(LaunchFailure::Failed);\r\n }\r\n match via_daemon() {\r\n Ok(pid) => Ok(pid),\r\n Err(e) if e.fallback_allowed() => {\r\n // A pre-ack refusal means nothing was spawned — EXCEPT for the one\r\n // pre-ack cause that is a timeout rather than an answer. A daemon\r\n // that acks late may already have launched, so THAT fallback checks\r\n // the arbiter before adding a second binary (the documented race at\r\n // `LAUNCH_ACK_BOUND`). Adopting the winner is a SUCCESS: the caller\r\n // wanted a running binary and there is one.\r\n //\r\n // The gate is `may_have_launched`, not `fallback_allowed`: running\r\n // the arbiter on an ANSWERED refusal adopts a pid no daemon could\r\n // have launched, so the fallback silently declines to spawn — and a\r\n // relink that never re-launches never mints, which is precisely the\r\n // recovery command failing on the state it exists to recover.\r\n // [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\n // Gated by SHORT-CIRCUIT, not by filtering the answer: outside the\r\n // late-ack window the pid probe is not merely unused, it must not\r\n // run at all — that is one fewer place a pinned corpse handle can\r\n // report a dead pid alive.\r\n let winner = if e.may_have_launched() {\r\n already_live()\r\n } else {\r\n None\r\n };\r\n if let Some(pid) = winner {\r\n spt_proto::emit_line_err!(\r\n \"SHELL_LAUNCH_ALREADY_LIVE:{label}: a launch of this instance is already \\\r\n running (pid={pid}) — standing down instead of spawning a second binary\"\r\n );\r\n return Ok(pid);\r\n }\r\n // Nothing was spawned daemon-side. Say WHY the route was not taken\r\n // and WHOSE job the child is about to join — the three pre-ack\r\n // causes carry distinct names, so a field report can tell an old\r\n // daemon from a foreign home from no daemon at all.\r\n spt_proto::emit_line_err!(\r\n \"SHELL_LAUNCH_IN_PROCESS:{label}: {e} — spawning from THIS process instead, so \\\r\n the binary joins THIS process's Job Object (a DETACH_BREAKAWAY_DENIED line \\\r\n names it); the first daemon-side wake re-spawns it job-neutrally\"\r\n );\r\n in_process().map_err(LaunchFailure::Failed)\r\n }\r\n Err(e) if e.is_indeterminate() => Err(LaunchFailure::Indeterminate(e.to_string())),\r\n Err(e) => Err(LaunchFailure::Failed(e.to_string())),\r\n }\r\n}\r\n\r\n/// [`launch_shell`], routed by ORIGIN (REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE).\r\n///\r\n/// From the daemon this is `launch_shell` verbatim. From a CLI it hands the\r\n/// launch to a running daemon over the drive control socket — so the binary\r\n/// rises job-neutral instead of inside the launching terminal's Job Object —\r\n/// and falls back to today's in-process spawn, loudly, when no daemon takes it.\r\n// [impl->REQ-SHELL-CLI-SPAWN-JOB-EXPOSURE]\r\npub fn launch_shell_from(\r\n origin: LaunchOrigin,\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n adapter_name: &str,\r\n install_dir: Option<&Path>,\r\n shell: &Shell,\r\n) -> Result {\r\n match origin {\r\n LaunchOrigin::Daemon => {\r\n launch_shell(owlery, owner, shell_id, adapter_name, install_dir, shell)\r\n .map_err(LaunchFailure::Failed)\r\n }\r\n LaunchOrigin::Cli => launch_routed(\r\n shell,\r\n shell_id,\r\n || {\r\n crate::drivehub::shell_launch(\r\n &crate::endpoint::drive_socket_name(),\r\n owner,\r\n shell_id,\r\n owlery,\r\n )\r\n },\r\n || {\r\n live_launch_winner(&spt_store::perch::resolve_shell_perch_path_in(\r\n owlery, owner, shell_id,\r\n ))\r\n },\r\n || launch_shell(owlery, owner, shell_id, adapter_name, install_dir, shell),\r\n ),\r\n }\r\n}\r\n\r\n/// Launch a shell instance's binary per the manifest's `command_receipt`\r\n/// (M5-D3c): **relay** (default) spawns detached (stdio discarded — the\r\n/// binary drains via `api poll --link`); **stdin** spawns broker-hosted so\r\n/// the daemon owns the stdin pipe ([`launch_shell_brokered_in`] — command\r\n/// frames ride the broker's `send_effect` input seam); **http** refuses at\r\n/// spawn, explicitly — an unimplemented mode is never a silent fallback.\r\n/// Records the pid; returns it. The perch stays **offline** until the\r\n/// binary's `api bind-shell` handshake onlines it — launch is not the online\r\n/// switch any more than spawn is.\r\n// [impl->REQ-SHELL-1]\r\npub fn launch_shell(\r\n owlery: &Path,\r\n owner: &str,\r\n shell_id: &str,\r\n adapter_name: &str,\r\n install_dir: Option<&Path>,\r\n shell: &Shell,\r\n) -> Result {\r\n match shell.command_receipt {\r\n Some(CommandReceipt::Http) => Err(\r\n \"command_receipt=http is not implemented yet — spawn refused (an \\\r\n unimplemented mode never falls back silently)\"\r\n .into(),\r\n ),\r\n Some(CommandReceipt::Stdin) => {\r\n crate::ensure_running().map_err(|e| format!(\"daemon start: {e}\"))?;\r\n launch_shell_brokered_in(\r\n &crate::broker_socket_name(),\r\n owlery,\r\n owner,\r\n shell_id,\r\n adapter_name,\r\n install_dir,\r\n shell,\r\n )\r\n }\r\n _ => {\r\n let tokens =\r\n fill_spawn_command(owlery, owner, shell_id, adapter_name, install_dir, shell)?;\r\n let (program, args) = tokens.split_first().expect(\"non-empty checked\");\r\n // The shell binary is a LONG-LIVED detached child (KNOWN-HAZARDS\r\n // 5.6): on Windows it must inherit NO handles, or a caller\r\n // capturing `spt shell spawn`'s output — at any depth of the\r\n // process chain — hangs forever on a pipe write-end the immortal\r\n // child holds. Same no-inherit spawn as the daemon's.\r\n // [impl->REQ-HAZARD-DETACHED-PIPE-INHERIT]\r\n #[cfg(windows)]\r\n let pid = crate::daemon::detached_no_inherit(program, args)\r\n .map_err(|e| format!(\"spawn {program}: {e}\"))?;\r\n #[cfg(unix)]\r\n let pid = Command::new(program)\r\n .args(args)\r\n .stdin(Stdio::null())\r\n .stdout(Stdio::null())\r\n .stderr(Stdio::null())\r\n .spawn()\r\n .map_err(|e| format!(\"spawn {program}: {e}\"))?\r\n .id();\r\n let perch = spt_store::perch::resolve_shell_perch_path_in(owlery, owner, shell_id);\r\n std::fs::write(perch.join(SHELL_PID_FILE), pid.to_string())\r\n .map_err(|e| format!(\"record pid: {e}\"))?;\r\n // The birth stamp rides WITH the pid at every launch, or the probe that\r\n // reads it degrades to bare-pid liveness on this instance alone -- a\r\n // silent per-instance regression rather than a visible one.\r\n // [impl->REQ-SHELL-PERSISTENT-BOOT-RESTORE]\r\n spt_store::shellinfo::record_shell_launch(&perch, pid, now_ms());\r\n Ok(pid)\r\n }\r\n }\r\n}\r\n\r\n/// The stdin-receipt launch: spawn the filled template as a **broker-hosted**\r\n/// session labeled [`shell_session_label`], so the daemon owns the child's\r\n/// stdin and `spt shell cmd` can drive it through the `send_effect` input\r","truncated":true,"truncatedBy":"lines","totalLines":1826,"totalBytes":25273,"outputLines":513,"outputBytes":25273,"lastLinePartial":false,"firstLineExceedsLimit":false},"totalLines":1826,"displayContent":{"text":"//! Shell-instance hosting (M5-D3b — CONTEXT §Shell model, §local-link\r\n//! authentication): the broker-launch + local-link handshake half of the\r\n//! shell machinery.\r\n//!\r\n//! **Broker-launched, never user-launched.** [`launch_shell`] mints a\r\n//! per-link token, parks it on the shell perch, fills the manifest's opaque\r\n//! `spawn` template (`{link_token}` + `{id}`/`{adapter_name}` from the\r\n//! guaranteed catalog) and spawns the binary detached — the only way a shell\r\n//! binary ever starts. Launch failure rolls nothing forward: the caller\r\n//! tears the just-minted perch back down (no half-built instance).\r\n//!\r\n//! **The local-link handshake.** Cross-node traffic already rides Iroh\r\n//! (E2E-encrypted); the exposed surface is the *same-node* channel where the\r\n//! least-trusted code in the system (the shell binary) touches SPT. The\r\n//! handshake: possession of the minted token **is** the bind credential —\r\n//! `spt api bind-shell --link ` resolves the instance *by token*\r\n//! ([`bind_shell_by_token`]: the binary needs no owner/id knowledge beyond\r\n//! its argv) and flips the perch online. Every subsequent machinery message\r\n//! on the link authenticates with the token-derived key ([`link_key`] →\r\n//! [`frame_mac`], applied per-message by the D3c channels) so another local\r\n//! process can neither inject into nor spoof a link.\r\n// [impl->REQ-SHELL-1]\r\n\r\nuse std::collections::BTreeMap;\r\nuse std::path::{Path, PathBuf};\r\nuse std::process::{Command, Stdio};\r\n\r\nuse hmac::{Hmac, Mac};\r\nuse sha2::{Digest, Sha256};\r\n\r\nuse spt_runtime::manifest::{AdapterKind, CommandReceipt, Manifest, Shell};\r\nuse spt_runtime::registry::AdapterRecord;\r\nuse spt_store::liveness::RelayLiveness;\r\nuse spt_store::shellinfo::{self, SHELL_STATUS_OFFLINE, SHELL_STATUS_ONLINE};\r\n\r\nuse crate::brain::{now_ms, Brain};\r\nuse crate::msg::SpawnReq;\r\nuse crate::shellchan::shell_session_label;\r\n\r\n/// Per-instance link-token filename within a shell perch dir (node-local\r\n/// runtime material, beside `info.json` — the perch *record* contract in\r\n/// STORAGE.md constrains `info.json`'s fields, not the perch's files).\r\npub const LINK_TOKEN_FILE: &str = \"link.token\";\r\n\r\n/// The most recently RETIRED link token (stashed by `close_shell`, consumed by\r\n/// the next launch's re-stamp). Never a live credential — bind resolves only\r\n/// [`LINK_TOKEN_FILE`]; this exists so pending spool rows stamped under the\r\n/// dead link survive the next token mint (REQ-HAZARD-SHELL-STALE-ONLINE).\r\npub const RETIRED_TOKEN_FILE: &str = \"link.token.retired\";\r\n/// The launched binary's OS pid — teardown's kill handle, and the evidence the\r\n/// derived-status resolver probes. Re-exported, never re-typed: the name is\r\n/// written here (launch/close) and MATCHED there\r\n/// ([`shellinfo::shell_pid_provably_dead`]), so both sides must be one const.\r\n// [impl->REQ-HAZARD-SHELL-STALE-ONLINE]\r\npub use spt_store::shellinfo::SHELL_PID_FILE;\r\n\r\n/// Mint a fresh link token: 32 hex chars of crypto-grade randomness (the\r\n/// `api.token` recipe — spt-proto's Ed25519 seed generator, no extra RNG dep).\r\npub fn mint_link_token() -> String {\r\n let seed = spt_proto::identity::Identity::generate().seed();\r\n seed[..16].iter().map(|b| format!(\"{b:02x}\")).collect()\r\n}\r\n\r\n/// Read a shell perch's parked link token.\r\npub fn read_link_token(shell_perch: &Path) -> Option {\r\n std::fs::read_to_string(shell_perch.join(LINK_TOKEN_FILE))\r\n .ok()\r\n .map(|s| s.trim().to_string())\r\n .filter(|s| !s.is_empty())\r\n}\r\n\r\n/// The per-link channel key, derived from the minted token: `SHA-256(token)`.\r\n/// Both ends hold the token (spt parked it; the binary got it in argv), so\r\n/// both derive the same key without a second exchange.\r\n// [impl->REQ-SHELL-1]\r\npub fn link_key(token: &str) -> [u8; 32] {\r\n let mut h = Sha256::new();\r\n h.update(token.as_bytes());\r\n h.finalize().into()\r\n}\r\n\r\n/// Authenticate one link frame: `HMAC-SHA256(link_key, frame)`, hex. Required\r\n/// on every message both directions (CONTEXT §local-link authentication) —\r\n/// the D3c channels stamp + verify this per frame; a frame without a valid\r\n/// MAC is dropped, never processed.\r\n// [impl->REQ-SHELL-1]\r\npub fn frame_mac(key: &[u8; 32], frame: &[u8]) -> String {\r\n let mut mac =