@north-light/cli 0.0.0 → 0.3.414

package/dist/core/runtime/promote.d.ts

@@ -0,0 +1,76 @@
+import { type NodeMeta, type Mode, type Lifecycle } from '../canvas/index.js';
+export interface PromoteResult {
+    meta: NodeMeta;
+    roadmapWritten: boolean;
+    /** The node's roadmap document ref (`<node>/roadmap`), read with `crtr canvas read`. */
+    roadmapRef: string;
+    /** Absolute path to the node's goal doc (context/initial-prompt.md). */
+    goalPath: string;
+}
+/** Shared reshape machinery: rewrite kind and/or model tier — and, when the
+ *  caller supplies them, mode/lifecycle — by rebuilding the launch spec so the
+ *  change is durable across a future revive. MODE-PRESERVING by default (omit
+ *  `mode`/`lifecycle` and the node's own current values carry through) — this
+ *  is what a plain `crtr node yield --kind/--model` reshape rides, with no
+ *  mode flip and no roadmap seeding. `promote()` below is a thin wrapper that
+ *  also forces mode→orchestrator and seeds the roadmap. */
+type ReshapeOptions = {
+    kind?: string;
+    model?: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    profileId?: string | null;
+};
+/** Synchronous reshape for CLI callers outside the daemon. */
+export declare function reshapeNode(nodeId: string, opts?: ReshapeOptions, beforePersist?: () => void): NodeMeta;
+/** Daemon-safe reshape: network-backed config resolution happens off its event loop. */
+export declare function reshapeNodeAsync(nodeId: string, opts?: ReshapeOptions, beforePersist?: () => void): Promise<NodeMeta>;
+/** Promote a node to an orchestrator (mode→orchestrator), optionally
+ *  specializing its kind (e.g. a `general` worker becoming a
+ *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
+ *  re-promoting just rewrites the spec. Seeds a roadmap SCAFFOLD if absent (a
+ *  boss with no map is a failure mode) — no goal is forced here; authoring the
+ *  goal + roadmap is the node's next act. Pending context delivery is owned by
+ *  the broker provider gate, not this command. */
+export declare function promote(nodeId: string, opts?: {
+    kind?: string;
+    resident?: boolean;
+    model?: string;
+}): PromoteResult;
+/** Daemon-safe promotion variant; preserves the same validation/seed ordering. */
+export declare function promoteAsync(nodeId: string, opts?: {
+    kind?: string;
+    resident?: boolean;
+    model?: string;
+}): Promise<PromoteResult>;
+export interface YieldResult {
+    meta: NodeMeta;
+    /** True iff `promote:true` was passed — a plain yield never flips mode. */
+    promoted: boolean;
+    /** Always true on success — the node will refresh-revive on its next stop. */
+    willRefresh: boolean;
+}
+/** Request a refresh-yield: discard in-memory context and revive fresh, mode
+ *  and lifecycle UNCHANGED, against the roadmap if one exists else the
+ *  original goal (`buildReviveKickoff` falls back to it). A plain yield is
+ *  always mode-preserving — a base node comes back base, still working the
+ *  same task hands-on. Pass `promote:true` to ALSO become an orchestrator in
+ *  the same refresh (the one-step form of yield + promote), which rides the
+ *  same path `crtr node promote` would — mode flips to orchestrator and a
+ *  roadmap scaffold is seeded. Sets intent='refresh'; the stophook shuts the
+ *  process down on the next stop and the daemon revives it fresh. */
+export declare function requestYieldAsync(nodeId: string, opts?: {
+    kind?: string;
+    model?: string;
+    promote?: boolean;
+}, deps?: {
+    ensure?: () => void;
+}): Promise<YieldResult>;
+export declare function requestYield(nodeId: string, opts?: {
+    kind?: string;
+    model?: string;
+    promote?: boolean;
+}, deps?: {
+    ensure?: () => void;
+}): YieldResult;
+export {};

package/dist/core/runtime/promote.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var l=(n,e)=>g(n,"name",{value:e,configurable:!0});import{getNode as m,updateNode as x}from"../canvas/index.js";import{transition as E}from"./lifecycle.js";import{ensureDaemon as R}from"../../daemon/manage.js";import{buildLaunchSpec as $,buildLaunchSpecAsync as A}from"./launch.js";import{ensureRoadmap as u,hasRoadmap as f,roadmapRef as t}from"./roadmap.js";import{readGoal as c,goalPath as k}from"./kickoff.js";function h(n,e){const d=m(n);if(d===null)throw new Error(`unknown node: ${n}`);const i=e.kind??d.kind,o=e.mode??d.mode,r=e.lifecycle??d.lifecycle,a=e.profileId===void 0?d.profile_id??null:e.profileId;return{node:d,kind:i,mode:o,lifecycle:r,profileId:a,launchOpts:{lifecycle:r,hasManager:d.parent!==null,model:e.model??d.model_override??void 0,modelOverride:e.model!==void 0,modelIntent:e.model===void 0?d.launch?.modelIntent:void 0,modelExact:e.model===void 0?d.launch?.modelExact:void 0,cwd:d.cwd,profileId:a}}}l(h,"reshapeInputs");function w(n,e,d,i,o){o?.();const r=d.node.name===d.node.kind&&d.kind!==d.node.kind;return x(n,{kind:d.kind,mode:d.mode,lifecycle:d.lifecycle,profile_id:d.profileId,launch:i,...r?{name:d.kind}:{},...e.model!==void 0?{model_override:i?.model??e.model}:{}})}l(w,"persistReshape");function s(n,e={},d){const i=h(n,e);return w(n,e,i,$(i.kind,i.mode,i.launchOpts).launch,d)}l(s,"reshapeNode");async function y(n,e={},d){const i=h(n,e),{launch:o}=await A(i.kind,i.mode,i.launchOpts);return w(n,e,i,o,d)}l(y,"reshapeNodeAsync");function N(n,e={}){const d=m(n);if(d===null)throw new Error(`unknown node: ${n}`);let i=!1;return{meta:s(n,{...e.kind!==void 0?{kind:e.kind}:{},...e.model!==void 0?{model:e.model}:{},mode:"orchestrator",lifecycle:e.resident===!0?"resident":d.lifecycle},()=>{if(!f(n)){const r=c(n);i=u(n,r!==null&&r.trim()!==""?{goal:r.trim()}:{})}}),roadmapWritten:i,roadmapRef:t(n),goalPath:k(n)}}l(N,"promote");async function O(n,e={}){const d=m(n);if(d===null)throw new Error(`unknown node: ${n}`);let i=!1;return{meta:await y(n,{...e.kind!==void 0?{kind:e.kind}:{},...e.model!==void 0?{model:e.model}:{},mode:"orchestrator",lifecycle:e.resident===!0?"resident":d.lifecycle},()=>{if(!f(n)){const r=c(n);i=u(n,r!==null&&r.trim()!==""?{goal:r.trim()}:{})}}),roadmapWritten:i,roadmapRef:t(n),goalPath:k(n)}}l(O,"promoteAsync");async function Y(n,e={},d={}){if(m(n)===null)throw new Error(`unknown node: ${n}`);return e.promote===!0?await O(n,{...e.kind!==void 0?{kind:e.kind}:{},...e.model!==void 0?{model:e.model}:{}}):(e.kind!==void 0||e.model!==void 0)&&await y(n,{...e.kind!==void 0?{kind:e.kind}:{},...e.model!==void 0?{model:e.model}:{}}),{..._(n,{},d),promoted:e.promote===!0}}l(Y,"requestYieldAsync");function _(n,e={},d={}){const i=d.ensure??R;if(m(n)===null)throw new Error(`unknown node: ${n}`);const r=e.kind!==void 0||e.model!==void 0;let a=!1;return e.promote===!0?(N(n,{...e.kind!==void 0?{kind:e.kind}:{},...e.model!==void 0?{model:e.model}:{}}),a=!0):r&&s(n,{...e.kind!==void 0?{kind:e.kind}:{},...e.model!==void 0?{model:e.model}:{}}),i(),E(n,"yield"),{meta:m(n),promoted:a,willRefresh:!0}}l(_,"requestYield");export{N as promote,O as promoteAsync,_ as requestYield,Y as requestYieldAsync,s as reshapeNode,y as reshapeNodeAsync};

package/dist/core/runtime/prospective-inventory-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/runtime/prospective-inventory-cli.js

@@ -0,0 +1,3 @@
+var m=Object.defineProperty;var o=(e,t)=>m(e,"name",{value:t,configurable:!0});import{readFileSync as d,writeFileSync as u}from"node:fs";import{DefaultResourceLoader as f,ExtensionRunner as g,getAgentDir as l}from"@earendil-works/pi-coding-agent";import{gatewayCommandRows as w}from"./chat-inventory-rows.js";import{captureChatCapabilities as x,registrationChatSurface as y,templateChatSurface as h}from"./command-surface.js";function C(){const e=JSON.parse(d(0,"utf8"));if(typeof e!="object"||e===null)throw new Error("preflight input must be an object");const t=e.extensions;if(!Array.isArray(t)||!t.every(s=>typeof s=="string"))throw new Error("preflight input extensions must be strings");return{extensions:t}}o(C,"parseInput");async function S(){const{extensions:e}=C(),t=process.cwd(),s=new f({cwd:t,agentDir:l(),additionalExtensionPaths:e,noContextFiles:!0});await s.reload();const r=s.getExtensions(),i=s.getPrompts().prompts,a=new g(r.extensions,r.runtime,t,void 0,void 0).getRegisteredCommands();x({commands:a,templates:i});const p=[...a.map(n=>{const c=n.expansion;return{name:n.invocationName,description:n.description??"",source:"command",...c!==void 0?{expansion:c}:{},...y(n)}}),...i.map(n=>({name:n.name,description:n.description,source:"template",template:n.content,...h(n)}))];u(3,`${JSON.stringify({commands:w(p),memory_refs:[]})}
+`)}o(S,"main"),S().catch(e=>{process.stderr.write(`${e instanceof Error?e.stack??e.message:String(e)}
+`),process.exitCode=1});

package/dist/core/runtime/prospective-inventory.d.ts

@@ -0,0 +1,10 @@
+import type { ChatInventoryCommandDTO, ChatInventoryMemoryRefDTO } from '../../api/dto/chat-inventory.js';
+export interface ProspectiveInventoryRows {
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export declare function runProspectiveInventory(input: {
+    cwd: string;
+    profileId: string | null;
+    extensions: string[];
+}): Promise<ProspectiveInventoryRows>;

package/dist/core/runtime/prospective-inventory.js

@@ -0,0 +1,2 @@
+var w=Object.defineProperty;var p=(t,o)=>w(t,"name",{value:o,configurable:!0});import{spawn as v}from"node:child_process";import{dirname as g,join as I}from"node:path";import{fileURLToPath as _}from"node:url";import{chatInventoryCommandRows as R,chatInventoryMemoryRows as T}from"./chat-inventory-rows.js";import{FRONT_DOOR_ENV as O}from"./front-door-env.js";import{freshChildNodeExecPath as L}from"./branded-host.js";const P=15e3;function S(){return I(g(_(import.meta.url)),"prospective-inventory-cli.js")}p(S,"entryPath");function N(t){const o=JSON.parse(t.trim());if(typeof o!="object"||o===null)throw new Error("preflight output must be an object");const n=o;if(!Array.isArray(n.commands)||!Array.isArray(n.memory_refs))throw new Error("preflight output must contain command and memory-ref arrays");return{commands:R(n.commands),memory_refs:T(n.memory_refs)}}p(N,"parseDocument");async function F(t){const o=await L();return new Promise((n,s)=>{const f={...process.env,CRTR_PROFILE_ID:t.profileId??"",[O]:"1"};delete f.CRTR_NODE_ID;const r=v(o,[S()],{cwd:t.cwd,env:f,stdio:["pipe","pipe","pipe","pipe"]});let u="",l="",y="",i=!1;const a=setTimeout(()=>{i||(i=!0,r.kill("SIGKILL"),s(new Error("prospective inventory preflight timed out")))},P);a.unref?.(),r.stdout.setEncoding("utf8"),r.stderr.setEncoding("utf8");const m=r.stdio[3];if(m==null||!("setEncoding"in m)){clearTimeout(a),r.kill("SIGKILL"),s(new Error("prospective inventory preflight response channel unavailable"));return}m.setEncoding("utf8"),r.stdout.on("data",e=>{u+=e}),r.stderr.on("data",e=>{l+=e}),m.on("data",e=>{y+=e}),r.on("error",e=>{i||(i=!0,clearTimeout(a),s(e))}),r.on("close",(e,h)=>{if(i)return;i=!0,clearTimeout(a);const c=[l.trim(),u.trim()].filter(Boolean).join(`
+`);if(e!==0){s(new Error(`prospective inventory preflight exited ${e??h??"unknown"}${c===""?"":`: ${c}`}`));return}try{n(N(y))}catch(d){const E=d instanceof Error?d.message:String(d);s(new Error(`${E}${c===""?"":`: ${c}`}`))}}),r.stdin.end(JSON.stringify({extensions:t.extensions}))})}p(F,"runProspectiveInventory");export{F as runProspectiveInventory};

package/dist/core/runtime/provider-credential-gate.d.ts

@@ -0,0 +1,4 @@
+export declare const NO_PROVIDER_CREDENTIAL_MESSAGE = "crtr: no provider credential; run `crtr sys setup` to log in.";
+/** Check the setup catalog before a path creates a broker-backed node. */
+export declare function hasConfiguredProviderCredential(profileId?: string | null): Promise<boolean>;
+export declare function exitForMissingProviderCredential(): never;

package/dist/core/runtime/provider-credential-gate.js

@@ -0,0 +1,2 @@
+var m=Object.defineProperty;var o=(r,e)=>m(r,"name",{value:e,configurable:!0});import{ModelRegistry as p,ModelRuntime as a}from"@earendil-works/pi-coding-agent";import{join as n}from"node:path";import{PoolCredentialStore as c}from"../pool-credential-store.js";import{readProfileEnvVars as d}from"../profiles/env-store.js";import{hasProviderCredential as l}from"../provider-credential.js";import{piAgentDir as f}from"./package-health.js";import{secretsDir as u}from"../layout.js";import{PROVIDER_ENV_KEYS as E}from"./spawn-env.js";const v="crtr: no provider credential; run `crtr sys setup` to log in.";async function w(r=null){const e=d(r);if(Object.values(E).some(i=>(e[i]??process.env[i])?.trim()))return!0;const s=f(),t=await a.create({credentials:new c(n(u(),"auth.json")),modelsPath:n(s,"models.json")});return l(t,new p(t))}o(w,"hasConfiguredProviderCredential");function M(){process.stderr.write(`${v}
+`),process.exit(1)}o(M,"exitForMissingProviderCredential");export{v as NO_PROVIDER_CREDENTIAL_MESSAGE,M as exitForMissingProviderCredential,w as hasConfiguredProviderCredential};

package/dist/core/runtime/recap.d.ts

@@ -0,0 +1,3 @@
+/** Ask Pi for a concise briefing of `conversation`. Invokes `onRecap` with
+ *  the parsed string on success, or never on timeout, empty, or garbled output. */
+export declare function generateRecap(conversation: string, onRecap: (briefing: string) => void, liveModel?: string, roadmap?: string): void;

package/dist/core/runtime/recap.js

@@ -0,0 +1,27 @@
+var h=Object.defineProperty;var n=(t,e)=>h(t,"name",{value:e,configurable:!0});import{headlessText as l}from"./headless-pi.js";import{envRecapModelOverride as c}from"../../shared/env.js";const d=25e3,m="anthropic/claude-haiku-4-5",u=`You brief a developer returning to a paused coding-agent conversation. They run many agent sessions in parallel and have lost this one's thread: they no longer know what this conversation is about or what they originally asked for. The brief exists to solve exactly that \u2014 pinned above their input box, it must tell them at a glance what this conversation is FOR and where it actually stands. You are given the first and most recent messages of the literal user/agent back-and-forth (tool output omitted), and the agent's roadmap file when one exists.
+
+Output EXACTLY two plain-text lines, nothing else:
+Goal: <what was requested \u2014 the original ask / what this conversation is for>
+State: <catch-them-up: what is ACTUALLY going on right now>
+
+Both lines are extremely short \u2014 telegraphic fragments, roughly 8-15 words, no filler. The State line must NOT restate the most recent message \u2014 the last message is often mid-progress, a question, or noise; instead synthesize the real position: what has landed, what is in flight, and the live blocker or needed answer. If the agent is waiting on the developer, say exactly what for. Be concrete (real file names, branches, SHAs, error messages \u2014 one specific anchor beats abstractions). Never narrate turn by turn, hedge, or pad. If the conversation has barely started, still emit your best two lines.
+
+Examples of the shape (from other conversations):
+Goal: Validate + commit the Unit 3 attach-keybinding migration in this worktree.
+State: Done \u2014 17/17 tests green, committed and rebased onto main.
+
+Goal: Build the trimmed-v1 command-plugin seam (orchestrating phases).
+State: Phase 1 landed; waiting on the core-seam worker's final.
+
+Goal: Standing personal assistant \u2014 iMessage wakes, Reddit scans, small tasks.
+State: Idle \u2014 waiting on you: hook pick, map export, Omi timing.`;function p(t,e){return`${e!==void 0&&e.trim()!==""?`<roadmap>
+${e.trim()}
+</roadmap>
+
+`:""}<conversation>
+${t}
+</conversation>
+
+Write the two-line Goal:/State: briefing for the conversation above. Output JUST the two lines.`}n(p,"recapUserPrompt");function g(t){const e=c();return e!==void 0?e:t!==void 0&&t.trim()!==""?t.trim():m}n(g,"recapModel");function f(t){return t.split(`
+`).map(e=>e.replace(/\s+/g," ").trim()).filter(e=>e!=="").join(`
+`)}n(f,"parseRecap");function b(t,e,a,i){const o=(t??"").trim();o!==""&&l({systemPrompt:u,userPrompt:p(o,i),modelSpec:g(a),timeoutMs:d}).then(s=>{const r=f(s);if(r!=="")try{e(r)}catch{}}).catch(()=>{})}n(b,"generateRecap");export{b as generateRecap};

package/dist/core/runtime/recovery-hold.d.ts

@@ -0,0 +1,2 @@
+export declare function holdRecovery(nodeId: string): () => void;
+export declare function isRecoveryHeld(nodeId: string): boolean;

package/dist/core/runtime/recovery-hold.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(e,n)=>o(e,"name",{value:n,configurable:!0});const r=new Set;function d(e){return r.add(e),()=>{r.delete(e)}}t(d,"holdRecovery");function l(e){return r.has(e)}t(l,"isRecoveryHeld");export{d as holdRecovery,l as isRecoveryHeld};

package/dist/core/runtime/recycle.d.ts

@@ -0,0 +1,14 @@
+export interface RecycleResult {
+    /** True when the pane was recycled (a fresh root respawned in it). */
+    recycled: boolean;
+    /** True when a `final` report was pushed for the recycled node. */
+    finalized: boolean;
+    /** The fresh root node booted into the pane, or null on failure. */
+    newRoot: string | null;
+    /** Subscriber node ids that received the final report. */
+    delivered: string[];
+}
+/** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
+ *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
+ *  Best-effort; `recycled:false` when there is no pane to act on. */
+export declare function recycleNode(nodeId: string, callerPane?: string): Promise<RecycleResult>;

package/dist/core/runtime/recycle.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var r=(e,t)=>w(e,"name",{value:t,configurable:!0});import{abortExecution as y,beginExecution as _,getNode as s,setPresence as h,setFocusOccupant as v,fullName as R,recordExecutionPid as b,recordLaunch as E}from"../canvas/index.js";import{pushFinal as k}from"../feed/feed.js";import{newestReportBody as g}from"../feed/reports.js";import{spawnNode as x,rootOfSpine as S}from"./nodes.js";import{buildLaunchSpecAsync as T,buildPiArgv as B}from"./launch.js";import{focusOf as N,respawnPaneSync as O,setPaneOption as P}from"./placement.js";import{waitForBrokerViewSocket as C,viewerSplitEnv as D}from"./placement-tmux.js";import{headlessBrokerHost as u}from"./host.js";import{boundFleet as F}from"./fleet.js";import{transition as z}from"./lifecycle.js";import{ensureDaemon as A}from"../../daemon/manage.js";import{invokeBirthLifecycleHooks as L}from"./spawn.js";async function ne(e,t){const n=s(e);if(n===null)return{recycled:!1,finalized:!1,newRoot:null,delivered:[]};const o=t??process.env.TMUX_PANE;if(o===void 0||o==="")return{recycled:!1,finalized:!1,newRoot:null,delivered:[]};const f=N(e);try{A()}catch{}const{launch:m}=await T("general","base",{lifecycle:"resident",hasManager:!1,cwd:n.cwd,profileId:n.profile_id}),p=g(e)||`Closed via recycle \u2014 no final summary was authored by ${n.name}.`;let a=[],d=!1;const i=await x({kind:"general",mode:"base",lifecycle:"resident",cwd:n.cwd,name:"general",parent:null,replaces:e,profile_id:n.profile_id,launch:m,beforeCreate:r(async()=>{try{a=(await k(e,p)).deliveredTo,d=!0}catch{}},"beforeCreate")}),c=s(i.node_id);await L(c);const l=B(c);if(l.env={...l.env,CRTR_SUBTREE:S(i.node_id)},!await U(c,l))return{recycled:!1,finalized:d,newRoot:i.node_id,delivered:a};try{u.teardown(e)}catch{}try{h(e,{pane:null,window:null,tmux_session:null})}catch{}if(f!==null)try{v(f.focus_id,i.node_id)}catch{}return{recycled:M(c,o),finalized:d,newRoot:i.node_id,delivered:a}}r(ne,"recycleNode");async function U(e,t){const n=_(e.node_id,{daemonEpoch:F().epoch()});t.env={...t.env,CRTR_EXECUTION_ID:n};let o;try{if(o=await u.launch(e.node_id,t,{cwd:e.cwd,name:R(e),resuming:!1}),o.pid===null)throw new Error("broker host returned no pid");if(E(e.node_id,new Date().toISOString()),b(n,e.node_id,o.pid)==="shutdown")throw new Error("broker execution was superseded");if(await C(e.node_id,o.exited))return!0}catch{y(n,{reason:"launch_failed"})}try{H(e.node_id)}catch{}try{u.teardown(e.node_id)}catch{}return!1}r(U,"launchRecycledBroker");function H(e){const t=s(e);(t?.status==="active"||t?.status==="idle")&&z(e,"crash")}r(H,"transitionReplacementToDead");function M(e,t){try{P(t,"@crtr_node","")}catch{}return O({pane:t,cwd:e.cwd,env:D(),command:`crtr surface attach to ${e.node_id}`})}r(M,"respawnRecycledViewer");export{ne as recycleNode};

package/dist/core/runtime/reopen.d.ts

@@ -0,0 +1,38 @@
+/** Validate a target is NOT latched (the ordinary, non-reopen doorway). Reads
+ *  `final_report` fresh — never a caller-supplied snapshot. Throws
+ *  `node_finalized` when latched; otherwise a no-op (the common case). No
+ *  side effect either way. */
+export declare function assertNotFinalized(nodeId: string): void;
+/** Validate a target IS latched (the `--reopen` doorway) and return the exact
+ *  `final_report` value observed, so the caller can CAS-clear it later via
+ *  `commitReopen` — once every OTHER fallible precondition the requested
+ *  operation needs has already passed (e.g. `--fresh`'s recoverable-state
+ *  check). Throws `not_finalized` when the target has nothing to clear. Pure
+ *  read — never mutates. */
+export declare function assertFinalizedForReopen(nodeId: string): string;
+/** Clear `nodeId`'s finalization latch — retract-pointer-only (only
+ *  `final_report`/`finalized_at`; the report file and every delivered feed
+ *  event are untouched). CAS'd against `expectedFinalReport` (the value the
+ *  caller observed via `assertFinalizedForReopen`): if the row no longer
+ *  matches — a concurrent `--reopen` already cleared it, or (impossible
+ *  without a reopen in between, but defended anyway) a fresh final landed —
+ *  this throws `reopen_latch_changed` instead of silently clobbering a newer
+ *  canonical result. Callers MUST NOT proceed to revive/deliver when this
+ *  throws. */
+export declare function commitReopen(nodeId: string, expectedFinalReport: string): void;
+/** Commit the wider message-delivery reopen: make the node resident, then
+ * retract a final latch when one exists. Unlike the revive/fresh gate, an
+ * unlatched node is valid here — it still becomes resident. Writing lifecycle
+ * first leaves a failed latch CAS with the canonical-final pointer intact.
+ * Both writes finish before either delivery channel begins. */
+export declare function commitReopenResident(nodeId: string, expectedFinalReport?: string): string | null;
+/** Convenience wrapper for a doorway with NO intervening fallible step between
+ *  the gate check and the reopen clear (`node lifecycle revive` has nothing
+ *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,
+ *  clears in one call.
+ *
+ *  - `reopen` false + latched → throws `node_finalized`.
+ *  - `reopen` true + latched → makes the node resident and CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + not latched → throws `not_finalized`.
+ *  - `reopen` false + not latched → no-op (the common case). */
+export declare function assertReopenGate(nodeId: string, reopen: boolean): void;

package/dist/core/runtime/reopen.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var n=(e,t)=>s(e,"name",{value:t,configurable:!0});import{clearFinalReportIfMatches as l,getFinalReport as c,getNode as p,updateNode as u}from"../canvas/index.js";import{InputError as i}from"../io.js";import{transition as f}from"./lifecycle.js";import{noticeChangedWhileDone as h}from"./ledger.js";function o(e){return c(e)}n(o,"currentFinalReport");function m(e,t){throw new i({error:"node_finalized",message:`${e} already submitted its canonical final result (\`crtr canvas read ${e}/${t}\`) \u2014 reviving it now would hand it a mandate it can never finish, since a second \`push final\` always errors against an already-latched node.`,next:`Re-run this exact command with --reopen to clear ${e}'s spent latch and re-task it in place.`})}n(m,"throwNodeFinalized");function d(e){throw new i({error:"not_finalized",message:`${e} is not finalized \u2014 --reopen has nothing to clear.`,next:"Drop --reopen."})}n(d,"throwNotFinalized");function w(e){const t=o(e);t!==null&&m(e,t)}n(w,"assertNotFinalized");function g(e){const t=o(e);return t===null&&d(e),t}n(g,"assertFinalizedForReopen");function R(e,t){if(!l(e,t))throw new i({error:"reopen_latch_changed",message:`${e}'s finalization latch changed since it was last inspected \u2014 a concurrent --reopen (or a fresh push final) already moved it, so clearing it now would risk erasing a newer canonical result.`,next:"Re-run this exact command \u2014 it will re-inspect the current state before acting."})}n(R,"commitReopen");function x(e,t){const r=o(e);u(e,{lifecycle:"resident"});const a=p(e);return a!==null&&(a.status==="done"||a.status==="canceled"||a.status==="dead")&&(a.status==="done"&&a.last_settled_at!=null&&h(e,a.last_settled_at),f(e,"revive")),r!==null&&R(e,t??r),r}n(x,"commitReopenResident");function y(e,t){if(t){const r=g(e);x(e,r);return}w(e)}n(y,"assertReopenGate");export{g as assertFinalizedForReopen,w as assertNotFinalized,y as assertReopenGate,R as commitReopen,x as commitReopenResident};

package/dist/core/runtime/reset.d.ts

@@ -0,0 +1,68 @@
+import { headlessBrokerHost } from './host.js';
+import { respawnPaneSync } from './placement.js';
+/** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
+ *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+ *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
+ *  keep parent=rootId. No wipe. Returns the reaped ids.
+ *
+ *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
+ *  whether via `node lifecycle close` OR a root reset — did not finish its OWN work, so it
+ *  unifies on `canceled`; `done` is reserved for finish. Why marking is STILL
+ *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
+ *  general quit→done rule does NOT auto-resolve a force-killed descendant — we
+ *  mark it `canceled` here via the same `cancel` event the close cascade uses. */
+export declare function reapDescendants(rootId: string): string[];
+/** Injectable host/viewer seam, so the ordinary source test drives relaunchRoot's pure
+ *  DB transitions without a real broker or tmux. Each field defaults to its
+ *  production verb. */
+export interface RelaunchDeps {
+    /** Boot the new node's detached broker engine. Default: headlessBrokerHost.launch. */
+    launchBroker?: typeof headlessBrokerHost.launch;
+    /** Wait for the new broker's view.sock to accept. Default: waitForBrokerViewSocket. */
+    waitForViewSocket?: (nodeId: string, exited?: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>) => boolean | Promise<boolean>;
+    /** Re-exec the viewer pane onto the new node. Default: respawnPaneSync. */
+    respawnViewer?: typeof respawnPaneSync;
+    /** Tear down a broker after a failed replacement or a committed old-root replacement. */
+    teardownBroker?: typeof headlessBrokerHost.teardown;
+}
+export interface RelaunchRootResult {
+    /** The freshly-minted node now driving this pane. */
+    newNodeId: string;
+}
+/** Relaunch a ROOT on `/new`: park the old root `done` (kept as history) and
+ *  mint a fresh node id + broker in the same pane/cwd, re-pointing the viewer at
+ *  it. The new broker is booted FIRST and its pid confirmed BEFORE the old root
+ *  is touched, so any pre-commit failure leaves the old root fully intact and
+ *  live. Returns null when `oldId` is not a relaunchable root (unknown, a child,
+ *  or already parked), or when the new broker failed to launch. */
+export declare function relaunchRoot(oldId: string, deps?: RelaunchDeps): Promise<RelaunchRootResult | null>;
+export interface ResetRootResult {
+    /** Descendant node ids torn down. Always empty — a child `/new` reaps nothing. */
+    reaped: string[];
+    /** Direct subscriptions dropped. Always empty — a child `/new` detaches nothing. */
+    detached: string[];
+    /** Always false — a child `/new` is not a graph reset (roots route to relaunchRoot). */
+    reset: boolean;
+}
+/** Refresh a non-root child's pi session id on `/new`, so a later
+ *  `--session <id>` wakes the right conversation. A `/new` on a child is NOT a
+ *  graph reset — a root's `/new` is handled by relaunchRoot, never here; a root
+ *  that reaches this is a no-op. */
+export declare function resetRoot(nodeId: string, newSessionId?: string, newSessionFile?: string | null): ResetRootResult;
+export type HandleNewSessionPath = 'reset-child' | 'noop';
+export interface HandleNewSessionResult {
+    path: HandleNewSessionPath;
+}
+/** The child-side `/new` entry the stophook calls (the root side goes to
+ *  relaunchRoot directly). The broker already drove the engine-side new_session;
+ *  this only refreshes the child's session id on the SAME node id. */
+export declare function handleNewSession(nodeId: string, newSessionId: string, newSessionFile?: string | null): HandleNewSessionResult;
+/** Resolve a cleanly-exiting node to `done`. Returns true iff it transitioned.
+ *  Guard: only a real quit, and only a node still active|idle with no pending
+ *  intent — so it never clobbers a node already routed by agent_end to done
+ *  (push final), refresh (yield), or idle-release. Pure/DB-only (no pi/tmux) so
+ *  the guard is unit-testable without a live pi. */
+export declare function markCleanExitDone(nodeId: string, reason: unknown): boolean;

package/dist/core/runtime/reset.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var l=(e,t)=>S(e,"name",{value:t,configurable:!0});import{getNode as p,beginExecution as B,recordExecutionPid as N,abortExecution as k,bindSession as b,recordLaunch as g,fullName as x,liveExecutionForNode as F,closeFocusRow as R,view as O}from"../canvas/index.js";import{transition as a}from"./lifecycle.js";import{headlessBrokerHost as y,requestBrokerTeardown as V}from"./host.js";import{boundFleet as C}from"./fleet.js";import{tearDownNode as D,focusOf as P,registerViewerFocus as T,respawnPaneSync as I,windowOfPane as L,renameWindow as q}from"./placement.js";import{viewerSplitEnv as A,waitForBrokerViewSocket as H}from"./placement-tmux.js";import{buildLaunchSpecAsync as M,buildPiArgv as U}from"./launch.js";import{newNodeId as j,spawnNode as W,rootOfSpine as X}from"./nodes.js";import{appSpace as $}from"../layout.js";import{join as z}from"node:path";import{invokeBirthLifecycleHooks as G}from"./spawn.js";function J(e){const t=[];for(const r of O(e))try{a(r,"cancel",{reason:"closed"}),V(r),D(r),t.push(r)}catch{}return t}l(J,"reapDescendants");async function le(e,t={}){const r=t.launchBroker??y.launch,s=t.waitForViewSocket??H,m=t.respawnViewer??I,c=t.teardownBroker??y.teardown,o=p(e);if(o===null||o.parent!=null||o.status==="done")return null;const d=P(e),h=o.isolated?j():void 0,_=h?z($(o.grantee??"app:terminal").nodes,h):o.cwd,{launch:E}=await M(o.kind,"base",{lifecycle:"resident",hasManager:!1,model:o.model_override??void 0,modelIntent:o.launch?.modelIntent,modelExact:o.launch?.modelExact,cwd:_,profileId:o.profile_id}),n=await W({nodeId:h,kind:o.kind,mode:"base",lifecycle:"resident",cwd:_,name:o.kind,parent:null,replaces:e,profile_id:o.profile_id,launch:E,modelOverride:o.model_override??void 0});await G(n);const u=U(n,{});u.env={...u.env,CRTR_SUBTREE:X(n.node_id)};const f=B(n.node_id,{daemonEpoch:C().epoch()});u.env={...u.env,CRTR_EXECUTION_ID:f};let w;try{w=await r(n.node_id,u,{cwd:_,name:x(n),resuming:!1})}catch(i){throw k(f,{reason:"launch_failed"}),a(n.node_id,"crash"),i}if(w.pid==null)return k(f,{reason:"launch_failed"}),a(n.node_id,"crash"),null;if(g(n.node_id,new Date().toISOString()),N(f,n.node_id,w.pid)==="shutdown"){k(f,{reason:"superseded"});try{c(n.node_id)}catch{}return a(n.node_id,"crash"),null}let v=!1;try{v=await s(n.node_id,w.exited)}catch{}if(!v){const i=p(n.node_id);(i?.status==="active"||i?.status==="idle")&&a(n.node_id,"crash");try{c(n.node_id)}catch{}return null}if(J(e),a(e,"finish"),d?.pane!=null){R(d.focus_id),m({pane:d.pane,cwd:o.cwd,env:A(),command:`crtr surface attach to ${n.node_id}`});const i=L(d.pane);i!==null&&q(i,x(n)),T(n.node_id,d.pane,d.session,i)}return c(e),{newNodeId:n.node_id}}l(le,"relaunchRoot");function K(e,t,r){const s=p(e),m={reaped:[],detached:[],reset:!1};if(s===null||s.parent==null)return m;if(t!==void 0){const c=F(e);c!==null&&b(e,{executionId:c.executionId,sessionId:t,transcriptPath:r??null})}return m}l(K,"resetRoot");function se(e,t,r){return p(e)===null?{path:"noop"}:(K(e,t,r),{path:"reset-child"})}l(se,"handleNewSession");function ue(e,t){if(t!=="quit")return!1;const r=p(e);return r===null||r.status!=="active"&&r.status!=="idle"||r.intent!=null?!1:(a(e,"finish"),!0)}l(ue,"markCleanExitDone");export{se as handleNewSession,ue as markCleanExitDone,J as reapDescendants,le as relaunchRoot,K as resetRoot};

package/dist/core/runtime/resume-root.d.ts

@@ -0,0 +1,34 @@
+import type { NodeSummaryDTO } from '../../api/dto/nodes.js';
+/** Resolve a front-door resume: pick a target root (MRU or via picker), then
+ *  open this terminal to view it. On success it execs the viewer inline and
+ *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
+ *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
+ *  caller exits without surprise-booting). */
+export declare function resumeRoot(cwd: string, pick: boolean): Promise<'empty' | 'aborted'>;
+/** Match `idOrPrefix` against a node list: an exact id, else a unique id prefix.
+ *  The 8-character short id the pickers and Find node show is the canvas-install
+ *  stamp every node of this install shares, so a prefix is first narrowed to the
+ *  nodes that can be reopened; when several remain, the error lists them (with
+ *  full ids) instead of just refusing. `none` carries no message so the caller
+ *  can decide whether the token was an id at all (a plain word after `-r` may
+ *  be a prompt). */
+export declare function matchResumeTarget(all: readonly NodeSummaryDTO[], idOrPrefix: string): {
+    node: NodeSummaryDTO;
+} | {
+    error: string;
+} | {
+    none: true;
+};
+/** Message for an id that names no node. */
+export declare function noResumeTargetMessage(idOrPrefix: string): string;
+/** Resolve `crtr -r <node-id>` against the live canvas. Returns the node, the
+ *  message to show when it cannot be reopened, or `none` when nothing matches. */
+export declare function resolveResumeTarget(idOrPrefix: string): Promise<{
+    node: NodeSummaryDTO;
+} | {
+    error: string;
+} | {
+    none: true;
+}>;
+/** `crtr -r <node-id>`: make THIS terminal the writable viewer of one node. */
+export declare function resumeNodeById(nodeId: string): Promise<never>;

package/dist/core/runtime/resume-root.js

@@ -0,0 +1,11 @@
+var E=Object.defineProperty;var s=(t,n)=>E(t,"name",{value:n,configurable:!0});import{spawn as C}from"node:child_process";import{emitKeypressEvents as F}from"node:readline";import{readFileSync as I}from"node:fs";import{join as L}from"node:path";import{isPidAlive as j}from"../canvas/pid.js";import{contextDir as q}from"../canvas/paths.js";import{installTmuxBindings as B}from"./tmux-chrome.js";import{currentTmux as D,inTmux as S,viewerSplitEnv as W}from"./placement-tmux.js";import{cliClient as h}from"../../commands/api-client.js";import{stdoutColor as $}from"../output.js";import{printComeBackNote as H}from"./come-back-note.js";const g=$.dim,K=$.bold,y=$.cyan;async function Y(t){return(await h().listNodes()).filter(e=>e.parent===null&&e.kind!=="human"&&(e.status==="active"||e.status==="idle")&&e.cwd===t).sort((e,r)=>e.created<r.created?1:e.created>r.created?-1:0)}s(Y,"listResumableRoots");async function ht(t,n){const e=await Y(t);if(e.length===0)return"empty";let r;if(n&&e.length>1){if(r=await tt(e,t),r===null)return"aborted"}else r=e[0];return await v(r.node_id),"aborted"}s(ht,"resumeRoot");function G(t){return t.kind!=="human"&&(t.status==="active"||t.status==="idle")}s(G,"isResumable");function J(t,n){const e=t.filter(o=>o.node_id===n),r=e.length>0?e:t.filter(o=>o.node_id.startsWith(n));if(r.length===0)return{none:!0};const i=r.filter(G);if(i.length>1){const o=i.slice(0,8).map(m=>`  crtr -r ${m.node_id}   ${m.name}`),a=i.length>o.length?[`  \u2026 and ${i.length-o.length} more`]:[];return{error:[`${n} matches ${i.length} conversations \u2014 use the full id of one:`,...o,...a].join(`
+`)}}if(i.length===1)return{node:i[0]};if(r.length>1)return{error:`${n} matches ${r.length} nodes, none of them a running conversation. \`crtr -r\` lists the ones started in this directory.`};const c=r[0];return{error:`${c.node_id} is finished (${c.status}), so there is no running conversation to reopen. Read it with \`crtr node inspect transcript ${c.node_id}\`.`}}s(J,"matchResumeTarget");function pt(t){return`No conversation matches ${t}. \`crtr -r\` lists the ones started in this directory; \`crtr\` then Alt+C \u2192 Find node searches all of them.`}s(pt,"noResumeTargetMessage");async function gt(t){return J(await h().listNodes(),t)}s(gt,"resolveResumeTarget");async function wt(t){return v(t)}s(wt,"resumeNodeById");async function v(t){if(!S())throw new Error("crtr must be resumed from inside a tmux session \u2014 start tmux first (e.g. `tmux new -s work`), then run `crtr -c` there.");try{B()}catch{}const n=D();if(n!==null){try{const c=await h().focusOf(t);if(c!==null)try{await h().closeFocus(c.focus_id)}catch{}}catch{}try{await h().registerFocus({node_id:t,pane:n.pane,session:n.session,window:n.window})}catch{}}const e={...process.env,...W(),CRTR_ATTACH_WAIT_MS:"30000"},r=C("crtr",["surface","attach","to",t],{stdio:"inherit",env:e}),i=await new Promise(c=>{r.once("exit",o=>c(o??0)),r.once("error",()=>c(1))});await H(t,i),process.exit(i)}s(v,"attachInline");const U=y("\u25B8"),R=s(t=>t>0?`\x1B[${t}A\r`:"","cursorUp"),_="\x1B[0J",T=/\u001b\[[0-9;]*m/g;function z(t){const n=process.stdout.columns??80,e=t.split(`
+`),r=e.length-1;let i=0;for(let c=0;c<r;c++){const o=e[c].replace(T,"").length;n>0&&o>n&&(i+=Math.ceil(o/n)-1)}return r+i}s(z,"blockRows");function P(t,n){if(n<=0)return t;let e="",r=0;for(let i=0;i<t.length;){if(t[i]==="\x1B"){const c=/^\u001b\[[0-9;]*m/.exec(t.slice(i));if(c!==null){e+=c[0],i+=c[0].length;continue}}if(r>=n-1&&t.replace(T,"").length>n){e+="\u2026";break}e+=t[i],r++,i++}return e}s(P,"fitWidth");function Q(t){const n=j(t.pi_pid??null)?y("\u25CF live"):g("\u25CB dormant");let e=t.name;if(e===t.kind){const r=X(V(t.node_id));r!==""&&(e=r)}return`${e}  ${n}`}s(Q,"label");function V(t){try{return I(L(q(t),"initial-prompt.md"),"utf8")}catch{return null}}s(V,"readGoalBody");function X(t){if(t===null)return"";const n=t.split(`
+`).map(e=>e.trim()).find(e=>e!=="")??"";return n.length>72?n.slice(0,71)+"\u2026":n}s(X,"firstLine");function Z(t,n){const e=O(t.created),r=t.cwd===n?"":`  ${t.cwd}`;return`${e}${r}  ${t.node_id.slice(0,8)}`}s(Z,"detail");function O(t){const n=Date.now()-new Date(t).getTime();if(!Number.isFinite(n)||n<0)return"";const e=Math.floor(n/6e4);if(e<1)return"just now";if(e<60)return`${e}m ago`;const r=Math.floor(e/60);return r<24?`${r}h ago`:`${Math.floor(r/24)}d ago`}s(O,"ago");function tt(t,n){const e="Resume a session here",r=`${t.length} roots pinned to ${n}`;return new Promise(i=>{const c=process.stdout,o=process.stdin;let a=0,m=0;const x=s(()=>{const f=process.stdout.columns??80;let d=`
+  ${K(e)}
+  ${g(r)}
+
+`;return t.forEach((u,l)=>{const N=l===a?U:" ",M=l<9?et(`${l+1}`):"  ",A=`  ${N} ${M}  ${Q(u)}  ${g(Z(u,n))}`;d+=P(A,f)+`
+`}),d+=`
+  ${g("\u2191/\u2193 move  enter resume  q quit")}
+`,d},"render"),w=s(()=>{const f=x();c.write((m>0?R(m)+_:"")+f),m=z(f)},"draw");F(o);const k=o.isRaw??!1;o.isTTY&&o.setRawMode(!0),o.resume();const p=s(f=>{o.removeListener("keypress",b),o.isTTY&&o.setRawMode(k),o.pause(),c.write(R(m)+_),i(f)},"finish"),b=s((f,d)=>{const u=d.name??"";if(d.ctrl&&u==="c"&&(p(null),process.exit(130)),u==="q"||u==="escape")return p(null);if(u==="up"||u==="k")return a=(a-1+t.length)%t.length,w();if(u==="down"||u==="j")return a=(a+1)%t.length,w();if(u==="return"||u==="enter")return p(t[a]);const l=Number.parseInt(d.sequence??"",10);if(Number.isInteger(l)&&l>=1&&l<=Math.min(9,t.length))return a=l-1,p(t[a])},"onKey");o.on("keypress",b),w()})}s(tt,"pickRoot");function et(t){return y(t)}s(et,"key");export{J as matchResumeTarget,pt as noResumeTargetMessage,gt as resolveResumeTarget,wt as resumeNodeById,ht as resumeRoot};

package/dist/core/runtime/revive-all.d.ts

@@ -0,0 +1,57 @@
+import type { NodeMeta, NodeStatus } from '../canvas/types.js';
+/** Statuses a node lands in DELIBERATELY: a worker that finished its own work
+ *  (`done`) or a node a human closed/reaped (`canceled`). The daemon never
+ *  auto-revives these (see reapDeadResidue in crtrd.ts), and revive-all leaves
+ *  them alone too — resurrecting finished and closed conversations en masse would
+ *  flood the canvas with work nobody asked to reopen. `dead` is NOT here: a crash
+ *  is involuntary, so it is swept. (Silas, 2026-06-13: no opt-in to include these
+ *  — the exclusion is unconditional.) */
+export declare const TERMINAL_BY_CHOICE: readonly NodeStatus[];
+/** True when `meta` has no natural future cycle ahead of it. A frozen row is
+ *  excluded because its mark records a thaw cycle already owed. */
+export declare function hasNoNaturalCycle(meta: Pick<NodeMeta, 'status' | 'final_report' | 'frozen_at'>): boolean;
+/** True when `meta`'s engine is NOT running but it has a resumable saved session
+ *  — the precise "disconnected" predicate.
+ *
+ *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone does not resume — the broker preflight rejects
+ *    it — so such a node comes back fresh).
+ *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
+ *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
+ *  - unfrozen terminal-by-choice (`done`/`canceled`) is excluded.
+ *  - a node that already pushed its FINAL REPORT (`final_report` set) FINISHED
+ *    its own work — it is excluded regardless of status. A crash mid-reap can
+ *    leave it `dead` (not terminal-by-choice) with its report already committed;
+ *    resurrecting it as `active` strands it re-reviving forever and cannot
+ *    re-reap (the stuck-node incident). Mass revive must never resurrect
+ *    finished work; an explicit `node lifecycle revive <id>` still can.
+ *
+ *  Pure: the liveness probe is injected so scope is unit-testable without real
+ *  processes. */
+export declare function isDisconnected(meta: NodeMeta, isAlive: (pid: number | null | undefined) => boolean): boolean;
+/** Every disconnected node on the canvas — the set a revive-all WOULD relaunch.
+ *  This is the PREVIEW: it has no side effects, so the command can list the
+ *  candidates and gate on confirmation before any engine is launched. */
+export declare function listDisconnected(): NodeMeta[];
+export interface ReviveAllResult {
+    /** Node ids whose broker engine reviveAll relaunched (RESUME). */
+    revived: string[];
+    /** Per-node failures — reviveNode threw (its launch failed). One bad node
+     *  never aborts the sweep. */
+    failed: {
+        node_id: string;
+        error: string;
+    }[];
+    /** Node ids the cap turned away. They are not failures: each row is frozen
+     *  and the daemon's tick relaunches it as slots free. */
+    frozen: string[];
+}
+/** RESUME every disconnected node. reviveNode is the ONLY sanctioned launcher
+ *  and self-guards the double-spawn (a node whose broker pid is already live is a
+ *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
+ *  with resume:true. One failing node never aborts the sweep — its error is
+ *  collected and the rest proceed. */
+export declare function reviveAll(include?: (meta: NodeMeta) => boolean): Promise<ReviveAllResult>;

package/dist/core/runtime/revive-all.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var n=(e,r)=>t(e,"name",{value:r,configurable:!0});import{listNodes as s,getNode as u}from"../canvas/index.js";import{recordedPidLiveness as d}from"../canvas/pid.js";import{reviveNode as f}from"./revive.js";const l=["done","canceled"];function c(e){return e.frozen_at==null&&(e.final_report!=null||l.includes(e.status))}n(c,"hasNoNaturalCycle");function p(e,r){return!(e.kind==="human"||r(e.pi_pid)||e.pi_session_id==null&&e.pi_session_file==null||c(e))}n(p,"isDisconnected");function a(){const e=[];for(const r of s()){const o=u(r.node_id);o!==null&&p(o,i=>d(i,o.pi_pid_identity)==="alive")&&e.push(o)}return e}n(a,"listDisconnected");async function y(e=()=>!0){const r={revived:[],failed:[],frozen:[]};for(const o of a().filter(e))try{(await f(o.node_id,{resume:!0,recovery:!0,capacity:"freeze"})).outcome==="frozen"?r.frozen.push(o.node_id):r.revived.push(o.node_id)}catch(i){r.failed.push({node_id:o.node_id,error:i.message})}return r}n(y,"reviveAll");export{l as TERMINAL_BY_CHOICE,c as hasNoNaturalCycle,p as isDisconnected,a as listDisconnected,y as reviveAll};

package/dist/core/runtime/revive.d.ts

@@ -0,0 +1,105 @@
+import { type NodeMeta } from '../canvas/index.js';
+import type { WakeOrigin } from './bearings.js';
+/** A true session resume normally needs no prompt. A broker-certified runtime
+ * abort is the one exception: continue the persisted transcript with a factual
+ * warning rather than creating a fresh cycle. */
+export type ReviveWakeReason = WakeOrigin | 'runtime-restart-abort';
+import { headlessBrokerHost } from './host.js';
+/** Pick the `--session` source for a revive. Both resume=true (a true resume)
+ *  and resume=false (a refresh-yield) resume by the absolute session-file path
+ *  (immune to cwd; pi opens it directly) — but ONLY when that file actually
+ *  exists on disk. A node's `pi_session_file` can be recorded in meta with
+ *  nothing ever written there (e.g. its first-boot engine died before
+ *  session_start ever ran), and `headlessBrokerHost.launch`'s preflight
+ *  (host.ts) fatally rejects handing pi a `--session` for a missing path OR a
+ *  bare id — either would crash the revive and strand the node dead with
+ *  nothing to recover it. So when there is no real `.jsonl` to resume, this
+ *  selects NEITHER source regardless of `resume`: the caller then falls
+ *  through to a truly fresh (`--fresh`-equivalent) launch, which is always
+ *  safe. The only difference between the two `resume` values (when the file
+ *  DOES exist) is `newCycle`: resume=false additionally roots a fresh cycle
+ *  branch (`--crtr-new-cycle`) rather than continuing the existing leaf. Pure
+ *  so the decision is unit-testable without tmux or a real filesystem fixture
+ *  beyond a temp file. */
+export declare function resumeArgs(meta: NodeMeta, resume: boolean): {
+    resumeSessionPath?: string;
+    newCycle?: boolean;
+};
+/** Whether a fresh context window would have anything on disk to stand on: a
+ *  goal, a roadmap, or both. The negative is what makes a fresh cycle worse
+ *  than a resume — the new window would wake amnesiac, with no statement of
+ *  what it is for. Read by the parked-resident veto below and by the message
+ *  handler's explicit fresh-revive gate. */
+export declare function hasFreshGroundState(nodeId: string): boolean;
+export interface ReviveResult {
+    /** Always null — the broker engine is never placed in a tmux window. Kept on
+     *  the result for caller back-compat. */
+    window: string | null;
+    /** The node's last live LOCATION session, or null — the broker engine has no
+     *  tmux session of its own (it opens no viewer). Kept for caller back-compat. */
+    session: string | null;
+    /** True only for a TRUE resume — pi replays the saved conversation history
+     *  from its absolute session-file path. False for a fresh launch AND for an
+     *  in-place cycle (which also passes `--session <path>`, but to open a new
+     *  branch rather than replay the old one). */
+    resumed: boolean;
+    /** Launch handle for the detached broker, so callers can fail fast on its real
+     *  exit before the socket appears. */
+    launch?: Awaited<ReturnType<typeof headlessBrokerHost.launch>>;
+    /** Reads a fatal launch fault recorded by THIS revive attempt, scoped via
+     *  `beginBootFaultAttempt` at the exact clear-then-launch boundary below.
+     *  Present only when a fresh launch actually happened (absent on the
+     *  double-revive no-op, where nothing was cleared or relaunched). */
+    faultExplanation?: () => string | null;
+    /** What this call actually did. `already-live` means a broker was already
+     *  running for the node and nothing was launched; `frozen` means no slot was
+     *  free and the row is now waiting for one — the tick thaws it. */
+    outcome: ReviveOutcome;
+}
+export type ReviveOutcome = 'launched' | 'already-live' | 'frozen';
+export type AttachReviveDecision = {
+    parked: true;
+} | {
+    parked: false;
+    result: ReviveResult;
+};
+interface ReviveOptions {
+    resume: boolean;
+    capacity: ReviveCapacityPolicy;
+    wakeReason?: ReviveWakeReason;
+    recovery?: boolean;
+    /** Set only by {@link decideAttachRevive}: a viewer attach/focus launched
+     *  this broker so a person can look. Like `recovery`, it is NOT a wake. */
+    viewerAttach?: boolean;
+}
+/** What a caller wants when the broker cap is full. `freeze` suits a caller
+ *  whose reason to run survives waiting (durable mail, a cron sink, a recovery
+ *  respawn): the row is marked frozen and the tick relaunches it when a slot
+ *  frees. `refuse` suits a caller that must have a live broker NOW (an attach,
+ *  a bridge, a companion bind) and can only report the refusal. */
+export type ReviveCapacityPolicy = 'freeze' | 'refuse';
+/** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
+ *  meta. Opens no viewer (engine-only).
+ *
+ *  `recovery: true` marks a launch that only replaces a broker instance which
+ *  died or was torn down — the daemon's respawn after a broker exit, and the
+ *  `reviveAll` sweep over disconnected nodes. Nothing external arrived for the
+ *  node, so such a launch is NOT a wake and does not consume the node's armed
+ *  deadline (see the cancelCronsOnWake call below). A viewer attach (the
+ *  `viewerAttach` flag {@link decideAttachRevive} sets) is not a wake either.
+ *
+ *  Throws if the node does not exist. All other failures propagate as-is —
+ *  callers (daemon, command) decide how to handle.
+ */
+export declare function reviveNode(nodeId: string, opts: ReviveOptions): Promise<ReviveResult>;
+/** The attach-specific entry to the revive boundary. A focus viewer may decline
+ * to wake an exact parked resident while preserving the ordinary activating
+ * attach default. The fleet check and parked decision are synchronous with the
+ * launch below, so an already-running broker wins before dormancy is observed.
+ *
+ * Attaching only to look is not a wake: every launch through this entry is
+ * marked `viewerAttach`, so it leaves the node's armed `node wait deadline`
+ * cron in place. Anything the person types reaches the node as a message, and
+ * that delivery is the wake that consumes the deadline. */
+export declare function decideAttachRevive(nodeId: string, opts: Omit<ReviveOptions, 'viewerAttach'>, wakeParked: boolean): Promise<AttachReviveDecision>;
+export {};

package/dist/core/runtime/revive.js

@@ -0,0 +1,3 @@
+var V=Object.defineProperty;var s=(e,r)=>V(e,"name",{value:r,configurable:!0});import{existsSync as P}from"node:fs";import{conversationIdFromPath as _,conversationStore as h,ConversationNotFoundError as A}from"../conversation-store/index.js";import{isAbsolute as X}from"node:path";import{findNodeBySessionFile as Y,getNode as g,updateNode as y,beginExecution as q,recordExecutionPid as Q,abortExecution as b,endLiveExecution as Z,unbindSession as O,recordLaunch as I,setFrozen as ee,clearFrozen as re,fullName as D}from"../canvas/index.js";import{emitEvent as ie}from"../events/emit.js";import{cancelCronsOnWake as ne}from"../canvas/crons.js";import{isParked as oe,transition as R}from"./lifecycle.js";import{publishNotice as te}from"./close.js";import{InputError as E}from"../io.js";import{buildPiArgv as m}from"./launch.js";import{buildReviveKickoff as se,drainBearings as le,hasRetainedReports as ce,readGoal as S,readYieldMessage as ae,RUNTIME_RESTART_CONTINUATION as ue}from"./kickoff.js";import{readRoadmap as T}from"./roadmap.js";import{encodeKickoffOrigin as fe,KICKOFF_ORIGIN_ENV as he}from"./stamp/protocol.js";import{headlessBrokerHost as B}from"./host.js";import{boundFleet as z,brokerCapReached as de,brokerThresholdsForDaemon as U}from"./fleet.js";import{beginBootFaultAttempt as pe,clearFault as ve}from"../canvas/recovery.js";import{clearNodeLedger as H,forkNodeLedger as we,noticeChangedWhileDone as _e}from"./ledger.js";import{forkSourceNode as me,rootOfSpine as ke}from"./nodes.js";import{isReviewCompanionBound as ge}from"../review/companion.js";import{assertProfileActive as ye}from"../profiles/manifest.js";import{isPidAlive as be}from"../canvas/pid.js";import{crtrHome as Re,jobDir as Ee}from"../canvas/paths.js";import{contextDir as Se,ensureNodeDirs as xe,nodeAgentDir as $e}from"../canvas/node-agent-paths.js";import{discoverLifecycleHookRegistry as Ne}from"../command-hooks/discovery.js";import{invokeLifecycleHooks as Ce}from"../command-hooks/transport/exec-lifecycle.js";function Fe(e,r){const i=e.pi_session_file,n=i?_(i):null;if(n===null)return{};try{const t=h().header(n);return r?{resumeSessionPath:t.path}:{resumeSessionPath:t.path,newCycle:!0}}catch(t){if(t instanceof A)return{};throw t}}s(Fe,"resumeArgs");function K(e){const r=_(e);if(r===null)return!1;try{return h().header(r),!0}catch(i){if(i instanceof A)return!1;throw i}}s(K,"conversationExists");function Pe(e){const r=_(e);if(r===null)return!0;const i=h().header(r).header.cwd;return typeof i!="string"||P(i)}s(Pe,"sessionCwdExists");function Ae(e,r,i){const n=r.pi_session_file;if(!n||!K(n))return{};const t=Y(n);return t!==null&&t.node_id!==e&&be(t.pi_pid)?{}:Pe(n)?Fe(r,i):{}}s(Ae,"resumableSessionArgs");function Oe(e){return T(e)===null&&ae(e)===null&&!ce(e)}s(Oe,"isUnstartedBirth");function lr(e){const r=S(e);if(r!==null&&r.trim()!=="")return!0;const i=T(e);return i!==null&&i.trim()!==""}s(lr,"hasFreshGroundState");async function cr(e,r){const i=await L(e,r,!0);if(i.parked)throw new Error(`reviveNode: internal parked decision for activating revive ${e}`);return i.result}s(cr,"reviveNode");async function ar(e,r,i){return L(e,{...r,viewerAttach:!0},i)}s(ar,"decideAttachRevive");async function L(e,r,i){let n=g(e);if(n===null)throw new Error(`reviveNode: unknown node ${e}`);if(n=g(e)??n,n.run_id&&g(n.run_id)?.deleting_at)throw new Error("run is deleting");if(n.final_report!==null)throw new Error(`reviveNode: refusing to revive ${e} \u2014 its finalization latch is set (final_report=${n.final_report}). A final landed between the caller's reopen-gate check and this revive; re-run with --reopen if this retask is still wanted.`);ye(n.profile_id);const t=z();if(t.has(e))return R(e,n.intent==="refresh"?"refresh-launch":"revive"),{parked:!1,result:{window:null,session:n.tmux_session??null,resumed:!1,outcome:"already-live"}};if(t.isClaimed(e))return{parked:!1,result:{window:null,session:n.tmux_session??null,resumed:!1,outcome:"already-live"}};if(!i&&n.lifecycle==="resident"&&oe(n))return{parked:!0};if(!t.reserveSlot(e)){if(r.capacity==="refuse")throw de(U().automaticReviveCap,t.size());return n.frozen_at==null&&(ee(e,new Date().toISOString()),Z(e,{reason:"frozen"}),ie({level:"info",event:"broker.frozen",node_id:e,fields:{live_count:t.size(),hard_cap:U().automaticReviveCap}})),{parked:!1,result:{window:null,session:n.tmux_session??null,resumed:!1,outcome:"frozen"}}}try{return{parked:!1,result:await De(e,n,r)}}finally{t.releaseReservation(e)}}s(L,"decideRevive");async function De(e,r,i){if(!P(r.cwd)){const d=r.fork_from!=null?`Restore ${r.cwd}, then revive the fork normally with \`crtr node lifecycle revive ${e}\`.`:r.managed_worktree?.state==="open"?"Restore or reconcile the recorded checkout, then use the managed-worktree close or abandon recovery.":`Recreate ${r.cwd}, or repair it with \`crtr node config --cwd <path> --node ${e}\`; durable node work resumes in a fresh conversation. Then retry \`crtr node lifecycle revive ${e}\`.`;throw new E({error:"cwd_missing",message:`${e} cannot be revived \u2014 its recorded cwd no longer exists: ${r.cwd}`,next:d})}r.host_kind!=="broker"&&(y(e,{host_kind:"broker"}),r.host_kind="broker"),r.review_binding!=null&&!ge(e)&&(r.pi_session_id!=null||r.pi_session_file!=null)&&(O(e),r.pi_session_id=null,r.pi_session_file=null);const t=r.fork_from!=null&&r.pi_session_id==null,c=r.fork_source_file;if(t&&(typeof c!="string"||!X(c)))throw new E({error:"fork_source_invalid",message:`${e} cannot be revived \u2014 its resolved fork source file is missing or invalid.`,next:`Restore the node's fork source metadata, then retry \`crtr node lifecycle revive ${e}\`.`});const f=t&&typeof c=="string";if(f&&!K(c))throw new E({error:"fork_from_missing",message:`${e} cannot be revived \u2014 its fork source no longer exists: ${c}`,next:`Restore ${c}, or update the node's fork source, then retry \`crtr node lifecycle revive ${e}\`.`});const a=q(e,{daemonEpoch:z().epoch()});try{r.cycles=(r.cycles??0)+1,y(e,{cycles:r.cycles});const M=r.intent==="refresh"||r.cycle_pending===!0?!1:i.resume,p=f?{}:Ae(e,r,M),v=p.resumeSessionPath!==void 0,x=v&&p.newCycle===!0,k=v&&!x,$=!v&&(i.wakeReason===void 0||i.wakeReason==="runtime-restart-abort")&&Oe(e),G=f||$,N=r.cycle_pending===!0||x;y(e,{cycle_pending:N}),r.cycle_pending=N,!f&&!v&&(r.pi_session_id!=null||r.pi_session_file!=null)&&(O(e),r.pi_session_id=null,r.pi_session_file=null);let l,u=null;const C=s(()=>({type:"runtime",kind:"kickoff",...r.spawned_by!=null&&r.spawned_by!==""?{spawnedBy:r.spawned_by}:{}}),"birthOrigin");if(f){const o=S(e),F=_(c);if(F===null)throw new Error(`invalid fork source ${c}`);const J=h().header(h().fork(F,e)).path;l=m(r,{resumeSessionPath:J,...o!=null&&o!==""?{prompt:o}:{}}),o!=null&&o!==""&&(u=C()),we(e,me(c)?.node_id??null)}else if(k)l=m(r,{...p,...i.wakeReason==="runtime-restart-abort"?{prompt:ue}:{}}),i.wakeReason==="runtime-restart-abort"&&(u={type:"runtime",kind:"restart-continuation"});else if($){const o=S(e)?.trim();l=m(r,o!==void 0&&o!==""?{prompt:o}:{}),o!==void 0&&o!==""&&(u=C()),H(e)}else{const o=le(r,a);l=m(r,{...p,prompt:se(r,o,i.wakeReason==="runtime-restart-abort"?void 0:i.wakeReason)}),r.run_id&&o.unreadMessageIds?.length&&(l.env.CRTR_KICKOFF_MESSAGE_IDS=JSON.stringify(o.unreadMessageIds)),u=i.wakeReason!==void 0&&i.wakeReason!=="runtime-restart-abort"?{type:"runtime",kind:"wake",wake:i.wakeReason}:{type:"runtime",kind:"revive",cycle:r.cycles??0},H(e)}l.env={...l.env,CRTR_SUBTREE:ke(e)},u!==null&&(l.env[he]=fe(u)),r.status==="done"&&r.last_settled_at!=null&&_e(e,r.last_settled_at),R(e,r.intent==="refresh"?"refresh-launch":"revive"),ve(e,{preserveEpisode:!0});const j=pe(e);i.recovery!==!0&&i.viewerAttach!==!0&&ne(e),xe(e,r.grantee);const W=Ne(r.cwd,r.profile_id).plans.get("node:start")??[];await Ce(W,{node:{id:e,name:r.name,kind:r.kind,mode:r.mode,lifecycle:r.lifecycle,cwd:r.cwd,nodeDir:$e(e),contextDir:Se(e),jobDir:Ee(e)},runtime:{isBirth:G,canvasHome:Re(),profile:r.profile_id??null}}),l.env={...l.env,CRTR_EXECUTION_ID:a};let w;try{if(w=await B.launch(e,l,{cwd:r.cwd,name:D(r),resuming:k}),w.pid===null)throw new Error(`broker host returned no pid for ${e}`)}catch(o){try{R(e,"crash",{reason:"launch_failed",outcome:{detail:{schema:"crtr.node-outcome-detail/v1",message:o instanceof Error?o.message:String(o)}}}),te(e,"notice.crash",`Child crashed \u2014 ${D(r)} (${e}) failed to relaunch and is now dead: ${o.message}
+
+It stays dead until you revive it \u2014 \`crtr node lifecycle revive ${e}\`.`,{reason:"child-crashed",child:e})}catch{}throw b(a,{reason:"launch_failed"}),new Error(`[broker] refusing to revive ${e}: ${o.message}`)}if(I(e,new Date().toISOString()),Q(a,e,w.pid)==="shutdown")throw b(a,{reason:"superseded"}),B.teardown(e),new Error(`[broker] refusing to revive ${e}: execution was superseded during launch`);return re(e),{window:null,session:r.tmux_session??null,resumed:k,launch:w,faultExplanation:j.explanation,outcome:"launched"}}catch(d){throw b(a,{reason:"launch_failed"}),d}}s(De,"launchRevive");export{ar as decideAttachRevive,lr as hasFreshGroundState,Fe as resumeArgs,cr as reviveNode};

package/dist/core/runtime/roadmap.d.ts

@@ -0,0 +1,24 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare const ROADMAP_NAME = "roadmap";
+/** Fallback preview when the roadmap is seeded without a goal. */
+export declare const ROADMAP_PREVIEW = "To understand this node's long-term task and current plan, read this.";
+/** A roadmap's preview is its goal's first line; the fallback covers a goal-less seed. */
+export declare function roadmapPreview(goal?: string): string;
+/** How a node addresses its own roadmap in `crtr canvas read` / `crtr doc edit`. */
+export declare function roadmapRef(nodeId: string): string;
+export declare function hasRoadmap(nodeId: string): boolean;
+/** The roadmap's newest head body, or null when the node has none. */
+export declare function readRoadmap(nodeId: string): string | null;
+/** Seed a fresh, EXTREMELY BAREBONES roadmap document — the section skeleton
+ *  with one-line prompts — authored by the node. The owner fleshes it out as
+ *  its next act with `crtr doc edit roadmap`. Leaves an existing roadmap
+ *  untouched and returns null; otherwise returns the seeded body. */
+export declare function seedRoadmap(db: DatabaseSync, nodeId: string, opts?: {
+    goal?: string;
+    exitCriteria?: string;
+}): string | null;
+/** `seedRoadmap` in its own canvas write; true when it wrote one. */
+export declare function ensureRoadmap(nodeId: string, opts?: {
+    goal?: string;
+    exitCriteria?: string;
+}): boolean;