@north-light/cli 0.0.0 → 0.3.414

package/dist/core/runtime/roadmap.js

@@ -0,0 +1,15 @@
+var l=Object.defineProperty;var r=(e,t)=>l(e,"name",{value:t,configurable:!0});import{openDb as u,withCanvasWrite as d}from"../canvas/db.js";import{get as s}from"../graph/bodies.js";import{heads as p,writeDocument as c}from"../graph/documents.js";import{getById as m,liveDocumentNamed as f,nodeObject as h}from"../graph/objects.js";import{readerForNode as g}from"../graph/reader.js";const i="roadmap",w="To understand this node's long-term task and current plan, read this.";function x(e){return e?.split(`
+`).map(n=>n.trim()).find(n=>n!=="")??w}r(x,"roadmapPreview");function O(e){return`${e}/${i}`}r(O,"roadmapRef");function a(e,t){const n=m(e,t);return n===null||n.type!=="node"?null:f(e,n.rowid,i)}r(a,"roadmapObject");function P(e){return a(u(),e)!==null}r(P,"hasRoadmap");function W(e){const t=u(),n=a(t,e);if(n===null)return null;const o=p(t,n)[0];if(o===void 0)return null;try{return s(o.body_hash)}catch{return null}}r(W,"readRoadmap");function y(e){return`# Roadmap
+
+## Goal
+${e.goal?.trim()||"(the goal you now own)"}
+
+## Exit criteria
+${e.exitCriteria?.trim()||'(what "done" looks like)'}
+
+## Where things stand
+(present state at your level: settled, in flight, remaining)
+
+## Working set
+(links to the documents the work depends on now, one per line)
+`}r(y,"scaffold");function R(e,t,n={}){if(a(e,t)!==null)return null;const o=y(n);return c(e,g(e,t,()=>[]),{owner:h(e,t),name:i,kind:"knowledge",preview:x(n.goal),privacy:"public",rules:[{on:"boot",deliver:"content"}]},o),o}r(R,"seedRoadmap");function $(e,t={}){return d(n=>R(n,e,t)!==null)}r($,"ensureRoadmap");export{i as ROADMAP_NAME,w as ROADMAP_PREVIEW,$ as ensureRoadmap,P as hasRoadmap,W as readRoadmap,x as roadmapPreview,O as roadmapRef,R as seedRoadmap};

package/dist/core/runtime/run-command.d.ts

@@ -0,0 +1,36 @@
+export interface RunCommandOnceOptions {
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    headBytes: number;
+}
+export interface RunCommandOnceResult {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stdoutTruncated: boolean;
+    stderr: string;
+    stderrTruncated: boolean;
+    timedOut: boolean;
+    durationMs: number;
+    stdoutSha256: string;
+    processError: Error | null;
+}
+export interface RunningCommand {
+    pid: number | null;
+    completion: Promise<RunCommandOnceResult>;
+    terminate(): void;
+}
+/** App commands use the broker's mount compiler and the root launcher on Linux.
+ * The Mac runs through the existing direct-spawn implementation. */
+export declare function runAppCommand(options: RunCommandOnceOptions & {
+    nodeId?: string;
+    app: string;
+    isolated?: boolean;
+}): Promise<RunningCommand>;
+/** Start one admitted-PATH bash command in its own process group. The returned
+ * handle exposes the pid immediately for callers that must record ownership
+ * before waiting for completion; `completion` resolves after the process group
+ * has stopped, including timeout teardown. */
+export declare function runCommandOnce({ command, cwd, env, timeoutMs, headBytes }: RunCommandOnceOptions): RunningCommand;

package/dist/core/runtime/run-command.js

@@ -0,0 +1 @@
+var H=Object.defineProperty;var a=(e,s)=>H(e,"name",{value:s,configurable:!0});import{spawn as b}from"node:child_process";import{createHash as k}from"node:crypto";import{captureTeardownSnapshot as R,isAnyPidAlive as x,killProcessTreePids as I}from"../canvas/pid.js";import{CRON_DEATH_POLL_MS as B,CRON_KILL_GRACE_MS as G,newHeadCapture as L}from"../../daemon/cron/capture.js";import{resolveAdmittedHostCommand as M}from"./spawn-env.js";import{appProcessSandboxed as K,launchAppProcess as N}from"../spaces/process.js";async function V(e){if(!K()){if(e.isolated)throw new Error("isolated cron requires the root launcher");return q(e)}const s=Date.now(),n=await N({nodeId:e.nodeId,app:e.app,isolated:e.isolated,command:[M("bash",e.env,e.cwd),"-c",e.command],cwd:e.cwd,env:e.env,stdoutBytes:e.headBytes,stderrBytes:e.headBytes});let f=!1,o;const p=a(()=>{n.stop().catch(t=>{console.error(`app command ${n.pid} could not be stopped:`,t)})},"terminate");o=setTimeout(()=>{f=!0,p()},e.timeoutMs),o.unref?.();const i=n.completion.then(t=>({exitCode:t.exitCode,signal:t.signal,stdout:t.stdout,stderr:t.stderr,stdoutTruncated:t.stdoutTruncated,stderrTruncated:t.stderrTruncated,stdoutSha256:t.stdoutSha256,timedOut:f,durationMs:Date.now()-s,processError:null})).finally(()=>{o&&clearTimeout(o)});return{pid:n.pid,completion:i,terminate:p}}a(V,"runAppCommand");function q({command:e,cwd:s,env:n,timeoutMs:f,headBytes:o}){const p=Date.now(),i=b(M("bash",n,s),["-c",e],{cwd:s,env:n,detached:!0,stdio:["ignore","pipe","pipe"]}),t=i.pid??null,h=L(o),T=L(o),P=k("sha256");i.stdout?.on("data",d=>{P.update(d),h.take(d)}),i.stderr?.on("data",d=>T.take(d));let g=!1,w=null,l,v=null,c=!1,y=!1,u,m,C,r,D;const O=new Promise(d=>{D=d}),S=a(()=>{c||l===void 0||(c=!0,u!==void 0&&clearTimeout(u),m!==void 0&&clearTimeout(m),C!==void 0&&clearTimeout(C),D({exitCode:l,signal:v,stdout:h.decode(),stdoutTruncated:h.truncated(),stderr:T.decode(),stderrTruncated:T.truncated(),timedOut:g,durationMs:Date.now()-p,stdoutSha256:P.digest("hex"),processError:w}))},"finish"),A=a(()=>{if(r===void 0||!x(r.tree)){S();return}C=setTimeout(A,B)},"awaitTeardownDeath"),E=a(()=>{t===null||c||(r??=R(t,null),I(r.tree,"SIGTERM",r.identities),m===void 0&&(m=setTimeout(()=>{x(r.tree)&&I(r.tree,"SIGKILL",r.identities),y=!0,l!==void 0&&A()},G),m.unref?.()))},"terminate");return i.on("error",d=>{w===null&&(w=d),t===null&&(l=null,S())}),i.on("close",(d,_)=>{if(!c){if(l=d,v=_,u!==void 0&&clearTimeout(u),r!==void 0&&x(r.tree)){y&&A();return}S()}}),t!==null&&(u=setTimeout(()=>{c||(g=!0,E())},f),u.unref?.()),{pid:t,completion:O,terminate:E}}a(q,"runCommandOnce");export{V as runAppCommand,q as runCommandOnce};

package/dist/core/runtime/session-branch.d.ts

@@ -0,0 +1,7 @@
+export interface HumanForkCoordinates {
+    sourceFile: string;
+    sourceSessionId: string;
+    leafId: string;
+}
+/** Fork the captured root-to-leaf branch without opening or mutating its live source. */
+export declare function materializeSessionBranch(coordinates: HumanForkCoordinates): string;

package/dist/core/runtime/session-branch.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var s=(e,r)=>n(e,"name",{value:r,configurable:!0});import{conversationIdFromPath as i,conversationStore as t}from"../conversation-store/index.js";function c(e){if(e.sourceSessionId===""||e.leafId==="")throw new Error("session branch coordinates require source session and leaf ids");const r=i(e.sourceFile);if(r===null||r!==e.sourceSessionId)throw new Error("source session id does not match captured coordinates");const o=t();if(o.header(r).header.id!==e.sourceSessionId)throw new Error("source session id does not match captured coordinates");return o.header(o.fork(r,void 0,e.leafId)).path}s(c,"materializeSessionBranch");export{c as materializeSessionBranch};

package/dist/core/runtime/session-cycles.d.ts

@@ -0,0 +1,45 @@
+import { type SessionEntry } from '@earendil-works/pi-coding-agent';
+import type { BrokerSnapshot } from './broker-protocol.js';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export declare const CRTR_CYCLE_CUSTOM_TYPE = "crtr-cycle";
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export declare const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = "crtr-cycle-divider";
+type SnapshotMessage = BrokerSnapshot['messages'][number];
+/** One reconstructed message and the durable session entry that produced it. */
+export type IdentifiedMessage = {
+    id: string;
+    message: SnapshotMessage;
+};
+/** The structural slice of pi's SessionManager cycle rendering needs. The
+ *  broker's fake-engine test fixture implements only `buildSessionContext`, so
+ *  the tree accessors are optional — absent ⇒ single-cycle behavior. */
+export interface CycleSessionManagerLike {
+    buildSessionContext(): {
+        messages: SnapshotMessage[];
+    };
+    getEntries?(): SessionEntry[];
+    /** Walk from `fromId` (default: the current leaf) to its root; returns the
+     *  path root-first. */
+    getBranch?(fromId?: string): SessionEntry[];
+}
+/** True when an assistant turn ended because its own abort fired — an ESC, a
+ *  critical-tier interrupt, or the self-abort a refresh-yield performs. */
+export declare function endedByAbort(message: {
+    stopReason?: string;
+    errorMessage?: string;
+}): boolean;
+/** A refresh-yield deliberately aborts its own turn before the next cycle is
+ * rooted. Preserve that assistant message (including tool calls and prose), but
+ * omit the failure annotation: the cycle divider is the truthful visible seam. */
+export declare function withoutYieldAbort(message: SnapshotMessage): SnapshotMessage;
+/** The full multi-cycle message history for display: prior cycles (oldest
+ *  first, each closed by a divider), then the live cycle's context. Falls back
+ *  to plain `buildSessionContext()` when the session has no cycle markers, when
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export declare function cycleAwareMessages(sm: CycleSessionManagerLike): IdentifiedMessage[] | undefined;
+export {};

package/dist/core/runtime/session-cycles.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var i=(e,t)=>y(e,"name",{value:t,configurable:!0});import{buildContextEntries as b,sessionEntryToContextMessages as R}from"@earendil-works/pi-coding-agent";const T="crtr-cycle",g="crtr-cycle-divider";function C(e,t){const n=e!==void 0?`cycle ${e}`:"new cycle";return{role:"custom",customType:g,content:`yielded \u2014 ${n} begins with a fresh context window`,display:!0,timestamp:new Date(t).getTime()}}i(C,"cycleDivider");const M=/\b(?:request|operation) was aborted\b|\bthe user aborted\b/i;function h(e){return e.stopReason==="aborted"?!0:e.stopReason==="error"&&M.test(e.errorMessage??"")}i(h,"endedByAbort");function m(e){if(e.role!=="assistant"||!h(e))return e;const{stopReason:t,errorMessage:n,...o}=e;return o}i(m,"withoutYieldAbort");function p(e,t,n){return b(e,t,n).flatMap(o=>R(o).map(s=>({id:o.id,message:s})))}i(p,"identifiedContextMessages");function x(e){const t=e.at(-1);return t===void 0?e:[...e.slice(0,-1),{...t,message:m(t.message)}]}i(x,"priorCycleMessages");function w(e){if(typeof e.getEntries!="function"||typeof e.getBranch!="function")return;const t=e.getEntries(),n=new Map(t.map(r=>[r.id,r])),o=e.getBranch(),s=p(t,o.at(-1)?.id??null,n),u=t.filter(r=>r.type==="custom"&&r.customType===T);if(u.length===0)return s;const l=o[0]?.id,f=u.findIndex(r=>r.id===l);if(f===-1)return s;const c=[];for(let r=0;r<=f;r++){const a=u[r],d=a.data?.fromLeaf;typeof d=="string"&&d!==""&&c.push(...x(p(t,d,n))),c.push({id:`${a.id}~divider`,message:C(a.data?.cycle,a.timestamp)})}return c.push(...s),c}i(w,"cycleAwareMessages");export{T as CRTR_CYCLE_CUSTOM_TYPE,g as CRTR_CYCLE_DIVIDER_CUSTOM_TYPE,w as cycleAwareMessages,h as endedByAbort,m as withoutYieldAbort};

package/dist/core/runtime/session-list-cache.d.ts

@@ -0,0 +1,37 @@
+import type { WireSessionInfo } from './broker-protocol.js';
+export declare function compactSessionSearchText(text: string): string;
+/** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
+ *  per broker; the file is shared across brokers (last-writer-wins via atomic
+ *  rename — a lost update just costs one file's rebuild next open, never
+ *  corruption). */
+export declare class SessionListCache {
+    private readonly cacheFile;
+    private cache;
+    /** Share concurrent scans for the same cwd. */
+    private inflightDir;
+    private loadPromise;
+    private buildChain;
+    private persisting;
+    private persistAgain;
+    private persistTimer;
+    constructor(cacheFile: string);
+    /** Sessions in the picker's current cwd. */
+    listDir(cwd: string): Promise<WireSessionInfo[]>;
+    private buildDir;
+    /** Sessions across every cwd (`all` scope). */
+    listAll(): Promise<WireSessionInfo[]>;
+    /** Serialize cwd and all-scope cache mutations. */
+    private build;
+    private buildLocked;
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
+    private ensureLoaded;
+    private loadFromDisk;
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    private schedulePersist;
+    /** Atomic write (temp + rename) so a concurrent reader never sees a partial
+     *  file. Coalesces overlapping writes into one trailing flush. */
+    private persist;
+}

package/dist/core/runtime/session-list-cache.js

@@ -0,0 +1 @@
+var T=Object.defineProperty;var c=(t,e)=>T(t,"name",{value:e,configurable:!0});import{readFile as D,rename as N,unlink as C,writeFile as A}from"node:fs/promises";import{resolve as M}from"node:path";import{conversationStore as p,ConversationNotFoundError as F}from"../conversation-store/index.js";const S=1024;function E(t){if(t.length<=S)return t;const e=S/2;return`${t.slice(0,e)} \u2026 ${t.slice(-e)}`}c(E,"compactSessionSearchText");const w=1,P=2e3;function g(t){return typeof t=="number"&&Number.isFinite(t)&&t>=0}c(g,"isFiniteNonNeg");function b(t){return t===void 0||typeof t=="string"}c(b,"isOptionalString");function x(t){if(typeof t!="object"||t===null)return!1;const e=t;return typeof e.path=="string"&&typeof e.id=="string"&&typeof e.cwd=="string"&&typeof e.created=="string"&&typeof e.modified=="string"&&g(e.messageCount)&&typeof e.firstMessage=="string"&&typeof e.allMessagesText=="string"&&b(e.name)&&b(e.parentSessionPath)}c(x,"isValidWireInfo");function O(t){if(typeof t!="object"||t===null)return!1;const e=t;return g(e.mtimeMs)&&g(e.size)&&x(e.info)}c(O,"isValidEntry");function _(t){const e=t.content;return typeof e=="string"?e:Array.isArray(e)?e.filter(i=>i.type==="text").map(i=>i.text).join(" "):""}c(_,"extractTextContent");function k(t){const e=t.message;if(!e||!("content"in e))return;const i=e.role;if(i!=="user"&&i!=="assistant")return;const s=e.timestamp;if(typeof s=="number")return s;const n=new Date(t.timestamp).getTime();return Number.isNaN(n)?void 0:n}c(k,"messageActivityTime");function v(t){try{const e=t.header;let i=0,s="";const n=[];let a,h;for(const f of p().read(t.conversation_id).entries){if(f.type==="session_info"&&(a=f.name?.trim()||void 0),f.type!=="message")continue;i++;const y=k(f);typeof y=="number"&&(h=Math.max(h??0,y));const u=f.message;if(!u||!("content"in u))continue;const m=u.role;if(m!=="user"&&m!=="assistant")continue;const d=_(u);d&&(n.push(d),!s&&m==="user"&&(s=d))}const r=typeof e.cwd=="string"?e.cwd:"",o=typeof e.timestamp=="string"?new Date(e.timestamp).getTime():NaN,l=typeof h=="number"&&h>0?new Date(h):Number.isNaN(o)?new Date(t.mtime):new Date(o);return{path:t.path,id:e.id,cwd:r,name:a,parentSessionPath:e.parentSession,created:new Date(e.timestamp).toISOString(),modified:l.toISOString(),messageCount:i,firstMessage:s||"(no messages)",allMessagesText:E(n.join(" "))}}catch(e){if(e instanceof F)return null;throw e}}c(v,"buildWireSessionInfo");class H{static{c(this,"SessionListCache")}cacheFile;cache=new Map;inflightDir=new Map;loadPromise=null;buildChain=Promise.resolve();persisting=!1;persistAgain=!1;persistTimer=null;constructor(e){this.cacheFile=e}listDir(e){const i=M(e),s=this.inflightDir.get(i);if(s)return s;const n=Promise.resolve().then(()=>this.buildDir(i));this.inflightDir.set(i,n);const a=c(()=>{this.inflightDir.get(i)===n&&this.inflightDir.delete(i)},"clear");return n.then(a,a),n}buildDir(e){const i=p().list().filter(s=>s.header.cwd===e);return this.build(i,s=>this.cache.get(s)?.info.cwd===e)}async listAll(){return this.build(p().list(),()=>!0)}build(e,i){const s=this.buildChain.then(()=>this.buildLocked(e,i));return this.buildChain=s.then(()=>{},()=>{}),s}async buildLocked(e,i){await this.ensureLoaded();const s=new Set(e.map(({path:r})=>r));let n=!1;for(const r of this.cache.keys())!s.has(r)&&i(r)&&(this.cache.delete(r),n=!0);const a=new Array(e.length);for(const[r,o]of e.entries()){const l=this.cache.get(o.path);if(l&&l.mtimeMs===o.mtime&&l.size===o.size){a[r]=l.info;continue}const f=v(o);if(n=!0,!f){this.cache.delete(o.path);continue}this.cache.set(o.path,{mtimeMs:o.mtime,size:o.size,info:f}),a[r]=f}n&&this.schedulePersist();const h=a.filter(r=>r!==void 0);return h.sort((r,o)=>new Date(o.modified).getTime()-new Date(r.modified).getTime()),h}ensureLoaded(){return this.loadPromise||(this.loadPromise=this.loadFromDisk()),this.loadPromise}async loadFromDisk(){try{const e=JSON.parse(await D(this.cacheFile,"utf8"));if(e?.version!==w||typeof e.entries!="object")return;for(const[i,s]of Object.entries(e.entries)){if(!O(s)){this.cache.clear();return}this.cache.set(i,s)}}catch{this.cache.clear()}}schedulePersist(){this.persistTimer||(this.persistTimer=setTimeout(()=>{this.persistTimer=null,this.persist()},P),this.persistTimer.unref?.())}async persist(){if(this.persisting){this.persistAgain=!0;return}this.persisting=!0;const e=`${this.cacheFile}.${process.pid}.tmp`;try{const i={};for(const[n,a]of this.cache)i[n]=a;await A(e,JSON.stringify({version:w,entries:i})),await N(e,this.cacheFile)}catch{await C(e).catch(()=>{})}finally{this.persisting=!1,this.persistAgain&&(this.persistAgain=!1,this.persist())}}}export{H as SessionListCache,E as compactSessionSearchText};

package/dist/core/runtime/session-visibility.d.ts

@@ -0,0 +1,37 @@
+import type { WireSessionTreeNode } from './broker-protocol.js';
+import type { IdentifiedMessage } from './session-cycles.js';
+import { type MessageVisibility } from './stamp/protocol.js';
+import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { REVIEW_BOUNDARY_CUSTOM_TYPE };
+export type ProjectedMessage = IdentifiedMessage & {
+    visibility: MessageVisibility;
+};
+/** True when an entry is a durable review boundary, optionally for one review. */
+export declare function isReviewBoundary(entry: unknown, reviewId?: string): boolean;
+/**
+ * Project identified snapshot messages for transcript presentation.
+ *
+ * Every retained message carries its durable visibility classification. A
+ * companion then passes its binding's review id so its slice starts at ITS OWN
+ * boundary marker: a node forked from another companion inherits that
+ * companion's earlier marker, and slicing at the first marker of any review
+ * would reveal the origin companion's transcript.
+ */
+export declare function projectTranscript(messages: IdentifiedMessage[], opts: {
+    boundaryReviewId: string | undefined;
+    sessionEntries?: readonly unknown[];
+}): ProjectedMessage[];
+/**
+ * Project a session tree to the review companion's visible transcript boundary.
+ *
+ * Pre-boundary ancestors are omitted rather than retained as empty structural
+ * shells, making each durable boundary a root in the returned forest. Once a
+ * boundary is crossed, its complete descendant subtree remains navigable. An
+ * absent boundary produces an empty tree, so picker previews never disclose an
+ * inherited entry before a mutation guard can reject its selection.
+ *
+ * `boundaryReviewId` selects only this binding's marker as a root, so a
+ * companion forked from another companion never navigates into the inherited
+ * subtree rooted at the origin's earlier marker.
+ */
+export declare function boundaryRootedTree(tree: readonly WireSessionTreeNode[], boundaryReviewId?: string): WireSessionTreeNode[];

package/dist/core/runtime/session-visibility.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var o=(n,r)=>l(n,"name",{value:r,configurable:!0});import{readStamps as p,STAMP_SCHEMA_VERSION as f}from"./stamp/protocol.js";import{REVIEW_BOUNDARY_CUSTOM_TYPE as a}from"../../shared/generated-context.js";function c(n,r){if(n===null||typeof n!="object")return!1;const t=n;return(t.role==="custom"||t.type==="custom_message")&&t.customType===a&&(r===void 0||t.details?.reviewId===r)}o(c,"isReviewBoundary");function d(n){return{role:"custom",customType:a,content:"Earlier conversation with the origin is not shown.",display:!0,timestamp:n??Date.now()}}o(d,"syntheticBoundary");function y(n,r){const t=new Map;for(const e of p(r??[])){if(e.kind!=="message"||e.v!==f)continue;const i=e.payload;typeof i.msgTs=="number"&&t.set(i.msgTs,i.visibility==="internal")}let s="visible";return n.map(e=>{const{message:i}=e;return i.role==="user"&&(s=typeof i.timestamp=="number"&&t.get(i.timestamp)===!0?"internal":"visible"),{...e,visibility:s}})}o(y,"classifyMessages");function T(n,r){const t=y(n,r.sessionEntries),s=t.findIndex(({message:m})=>c(m,r.boundaryReviewId));if(s!==-1)return t.slice(s);if(r.boundaryReviewId===void 0)return t;const[e,...i]=t,u={id:"~boundary",message:d(e?.message.timestamp),visibility:"visible"};return e?.message.role==="compactionSummary"?[u,...i]:[u]}o(T,"projectTranscript");function h(n,r){const t=o(e=>({...e,children:e.children.map(t)}),"retainSubtree"),s=o(e=>c(e.entry,r)?[t(e)]:e.children.flatMap(s),"project");return n.flatMap(s)}o(h,"boundaryRootedTree");export{a as REVIEW_BOUNDARY_CUSTOM_TYPE,h as boundaryRootedTree,c as isReviewBoundary,T as projectTranscript};

package/dist/core/runtime/setup-marker.d.ts

@@ -0,0 +1,8 @@
+export declare function setupCompleted(): boolean;
+/** Record a finished setup run. A first setup leaves the tutorial offer
+ *  pending; a re-run keeps whatever the earlier marker said about it. */
+export declare function recordSetupCompleted(outcome: 'completed' | 'skipped'): Promise<void>;
+/** True while setup has run but no root has booted since. */
+export declare function tourOfferPending(): Promise<boolean>;
+/** The root that carries the offer is booting; never offer it again. */
+export declare function markTourOffered(): Promise<void>;

package/dist/core/runtime/setup-marker.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var t=(r,o)=>s(r,"name",{value:o,configurable:!0});import{existsSync as a}from"node:fs";import{join as f}from"node:path";import{runtimeRoot as c}from"../layout.js";function e(){return f(c(),"setup-completed.json")}t(e,"markerPath");function O(){return a(e())}t(O,"setupCompleted");async function x(r){const[{atomicWriteJson:o,readJsonOrNull:n},{crtrVersion:u}]=await Promise.all([import("../fs-utils.js"),import("../../shared/crtr-version.js")]),i=n(e());o(e(),{packageVersion:u(),completedAt:new Date().toISOString(),outcome:r,tourOffered:i===null?!1:i.tourOffered!==!1})}t(x,"recordSetupCompleted");async function J(){const{readJsonOrNull:r}=await import("../fs-utils.js");return r(e())?.tourOffered===!1}t(J,"tourOfferPending");async function w(){const{atomicWriteJson:r,readJsonOrNull:o}=await import("../fs-utils.js"),n=o(e());n!==null&&r(e(),{...n,tourOffered:!0})}t(w,"markTourOffered");export{w as markTourOffered,x as recordSetupCompleted,O as setupCompleted,J as tourOfferPending};

package/dist/core/runtime/shell-expansion.d.ts

@@ -0,0 +1,32 @@
+export declare const DEFAULT_SHELL_TIMEOUT_MS = 120000;
+/** Runs one command and returns the text that replaces it in the body. A runner
+ * never throws: a failure is reported inline so the surrounding document still
+ * reaches the model. */
+export type ShellRunner = (cmd: string) => Promise<string>;
+/** True when `body` carries at least one shell construct. Lets a caller skip an
+ * async execution pass (and its cwd/timeout plumbing) for the common inert
+ * document. */
+export declare function hasShellBlocks(body: string): boolean;
+/** Cap runaway command output before it becomes model context. */
+export declare function truncateShellOutput(content: string): string;
+/** Merge a completed command's streams the way the model should read them. */
+export declare function formatShellResult(result: {
+    code: number | null;
+    killed?: boolean;
+    stdout?: string;
+    stderr?: string;
+    timeoutMs: number;
+}): string;
+/** The runner for processes with no pi engine — every CLI leaf. */
+export declare function makeNodeShellRunner(opts: {
+    cwd: string;
+    timeoutMs?: number;
+}): ShellRunner;
+/** Replace every shell construct in `body` with its output.
+ *
+ * Fenced blocks resolve first behind sentinels so an inline pattern inside a
+ * block's own text is never executed a second time; inline forms resolve
+ * against the masked text; sentinels are then restored. Commands run in
+ * document order, exactly once per call — a document read twice runs its
+ * commands twice, which is the intended "once per invocation" contract. */
+export declare function expandShellBlocks(body: string, run: ShellRunner): Promise<string>;

package/dist/core/runtime/shell-expansion.js

@@ -0,0 +1,9 @@
+var S=Object.defineProperty;var l=(e,t)=>S(e,"name",{value:t,configurable:!0});import{execFile as E}from"node:child_process";const a="!`([^`\\n]+)`",h="```!\\n([\\s\\S]*?)\\n```",_=l(()=>new RegExp(a,"g"),"inlineRe"),w=l(()=>new RegExp(h,"g"),"blockRe"),L=12e4,f=2e3,d=5e4;function B(e){return new RegExp(a).test(e)||new RegExp(h).test(e)}l(B,"hasShellBlocks");function x(e){const t=e.split(`
+`);return t.length>f?`${t.slice(0,f).join(`
+`)}
+[truncated: hit ${f} lines]`:Buffer.byteLength(e,"utf8")>d?`${Buffer.from(e,"utf8").subarray(0,d).toString("utf8")}
+[truncated: hit ${d} bytes]`:e}l(x,"truncateShellOutput");function $(e){if(e.killed===!0)return`[Shell error: timed out after ${Math.max(1,Math.round(e.timeoutMs/1e3))}s]`;if(e.code!==0)return`[Shell error: exit code ${e.code}]
+${x(e.stderr??"")}`;let t=e.stdout??"";if(e.stderr!==void 0&&e.stderr!==""){const i=t.length===0||t.endsWith(`
+`)?"":`
+`;t=`${t}${i}[stderr]
+${e.stderr}`}return x(t)}l($,"formatShellResult");function M(e){const t=e.timeoutMs??L,[i,s]=process.platform==="win32"?["powershell.exe","-Command"]:["sh","-c"];return o=>new Promise(u=>{E(i,[s,o],{cwd:e.cwd,timeout:t,maxBuffer:d*4,encoding:"utf8"},(n,r,m)=>{const c=n,p=c!==null&&(c.killed===!0||c.signal!==void 0&&c.signal!==null),g=c===null?0:typeof c.code=="number"?c.code:1;u($({code:g,killed:p,stdout:r,stderr:m,timeoutMs:t}))})})}l(M,"makeNodeShellRunner");async function O(e,t){const i=[];let s="",o=0;for(const n of e.matchAll(w())){const r=n.index??0;s+=e.slice(o,r)+`\0B${i.length}\0`,i.push(await t(n[1]??"")),o=r+n[0].length}s+=e.slice(o);let u="";o=0;for(const n of s.matchAll(_())){const r=n.index??0;u+=s.slice(o,r)+await t(n[1]??""),o=r+n[0].length}return u+=s.slice(o),u.replace(/\x00B(\d+)\x00/g,(n,r)=>i[parseInt(r,10)]??"")}l(O,"expandShellBlocks");export{L as DEFAULT_SHELL_TIMEOUT_MS,O as expandShellBlocks,$ as formatShellResult,B as hasShellBlocks,M as makeNodeShellRunner,x as truncateShellOutput};

package/dist/core/runtime/situational-context.d.ts

@@ -0,0 +1,19 @@
+/** The `customType` stamped on the hidden custom message the inbox watcher
+ *  sends for an existing node's situational-context update. */
+export { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../shared/generated-context.js';
+/** Render prose supplied through a `situational_context` string entry point
+ *  (`crtr node message --situational-context`, the node-create seed) as the
+ *  card the sidecar stores. Card-supplying callers pass their own rendered
+ *  envelope to `appendSituationalContext` instead. Blank prose renders as ''
+ *  so the sidecar write stays a no-op rather than storing an empty card. */
+export declare function formatSituationalProse(prose: string): string;
+/** Upsert the node's current situational context (replace, not append) — the
+ *  one sanctioned writer for the sidecar, taking an ALREADY-RENDERED envelope.
+ *  No-op for blank text, so a caller can pass through an optional/empty value
+ *  with no guard at the call site. */
+export declare function appendSituationalContext(nodeId: string, text: string): void;
+/** The node's stored situational card, verbatim, or null when none is set.
+ *  The ONE read of the sidecar. A sidecar written before the card cut holds
+ *  bare prose; that single legacy branch lives here alone and self-clears on
+ *  the next situation change. */
+export declare function situationalContextEnvelope(nodeId: string): string | null;

package/dist/core/runtime/situational-context.js

@@ -0,0 +1,2 @@
+var a=Object.defineProperty;var n=(t,r)=>a(t,"name",{value:r,configurable:!0});import{mkdirSync as u}from"node:fs";import{readTextBeneathIfExists as l,writeFileBeneath as m}from"../spaces/open-beneath.js";import{situationalContextPath as e,nodeRunDir as o}from"../canvas/paths.js";import{formatCard as f,parseCard as c}from"../../shared/generated-context.js";import{SITUATIONAL_CONTEXT_CUSTOM_TYPE as P}from"../../shared/generated-context.js";function p(t){return t.trim()===""?"":f("situational",{},t)}n(p,"formatSituationalProse");function d(t,r){const i=r.trim();i!==""&&(u(o(t),{recursive:!0}),m(o(t),e(t),i+`
+`,{atomic:!0}))}n(d,"appendSituationalContext");function x(t){const r=l(o(t),e(t))?.trim()??"";return r!==""?r:null}n(x,"readSituationalContext");function h(t){const r=x(t);return r===null?null:c({content:r})===null?p(r):r}n(h,"situationalContextEnvelope");export{P as SITUATIONAL_CONTEXT_CUSTOM_TYPE,d as appendSituationalContext,p as formatSituationalProse,h as situationalContextEnvelope};

package/dist/core/runtime/situational-live.d.ts

@@ -0,0 +1,9 @@
+/** Write `text` (prose) to the node's sidecar and, when its broker is live,
+ *  deliver the stored card into the running session for the NEXT turn.
+ *
+ *  Rejects when a live broker cannot be reached or refuses the frame — the
+ *  caller decides what that means. For a warm claim it is fatal (a node holding
+ *  the wrong situation is worse than a slow one), the same call the model swap
+ *  makes. A DORMANT node needs no delivery at all: its next revive renders the
+ *  sidecar into the kickoff. */
+export declare function setSituationalContextLive(nodeId: string, text: string): Promise<void>;

package/dist/core/runtime/situational-live.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(t,e)=>i(t,"name",{value:e,configurable:!0});import{getNode as r}from"../canvas/index.js";import{deliverCustomMessageLive as a}from"./deliver-live.js";import{appendSituationalContext as l,formatSituationalProse as u,situationalContextEnvelope as s,SITUATIONAL_CONTEXT_CUSTOM_TYPE as m}from"./situational-context.js";async function C(t,e){if(l(t,u(e)),r(t)===null)throw new Error(`setSituationalContextLive: unknown node ${t}`);const o=s(t);o!==null&&await a(t,{customType:m,content:o,deliverAs:"nextTurn"})}n(C,"setSituationalContextLive");export{C as setSituationalContextLive};

package/dist/core/runtime/spawn-env.d.ts

@@ -0,0 +1,54 @@
+import type { PiInvocation } from './invocation.js';
+import type { ModelProvider } from '../../types.js';
+/** The unshimmed PATH admitted from the host. Broker and cron shells resolve
+ *  crouter-owned executables from this value, while commands those shells run
+ *  still receive the shim-prepended PATH. */
+export declare const ADMITTED_HOST_PATH_ENV = "CRTR_ADMITTED_HOST_PATH";
+/** Resolve a regular executable against a shell PATH without executing it.
+ *  The result is absolute, or null when no PATH entry supplies the command. */
+export declare function resolvePathExecutable(name: string, env: NodeJS.ProcessEnv, cwd: string): string | null;
+export declare function resolveAdmittedHostCommand(name: string, env: NodeJS.ProcessEnv, cwd: string): string;
+/** Vendor keys stay with the daemon, even when an explicit profile or host
+ *  allowlist names one of them. The front-door credential check uses this map. */
+export declare const PROVIDER_ENV_KEYS: Record<ModelProvider, string>;
+/** Sources A–C: the operational base shared by the broker boundary (this
+ *  module's `buildBrokerEnv`) and cron executor — the single shared definition
+ *  of "non-secret host state the runtime exposes to any spawned shell." Does not include
+ *  `inv.env`/`FRONT_DOOR_ENV` (source D), which is broker-specific. */
+export declare function buildOperationalEnvBase(opts: {
+    /** The TARGET node's cwd — never the calling/daemon process's own ambient
+     *  `process.cwd()`. Threaded into `readMergedLaunchConfig` so source C
+     *  (`spawnEnv.allow`) resolves from the TARGET's own project-scope config,
+     *  not whichever cwd happened to launch the process that builds this env. */
+    targetCwd: string;
+    /** The TARGET node's profile id — never the calling process's own ambient
+     *  `CRTR_PROFILE_ID`. `null`/`''` for no profile. */
+    targetProfileId: string | null;
+    host?: NodeJS.ProcessEnv;
+    /** App runs do not inherit the owner project's explicit host-env allowlist. */
+    skipSpawnAllow?: boolean;
+}): NodeJS.ProcessEnv;
+/** Source F — the TARGET profile's manifest `metadata`, each entry surfaced
+ *  as `CRTR_PROFILE_META_<KEY>` (key uppercased, every non-alphanumeric run
+ *  → `_`). Identity facts rather than secrets — unlike the env store these
+ *  are readable back (`profile show`, ProfileDTO). Read straight off the
+ *  manifest at every launch; never throws (a bad profile id yields `{}`). */
+export declare function profileMetadataEnv(profileId: string | null): NodeJS.ProcessEnv;
+/** The one authoritative broker child env: sources A–C (the operational
+ *  base, resolved from the TARGET node's own cwd/profile — `inv.env`'s
+ *  `CRTR_NODE_CWD`/`CRTR_PROFILE_ID`, never this process's ambient
+ *  `process.cwd()`/`CRTR_PROFILE_ID`, which may be a launcher's or the
+ *  daemon's own and belong to an unrelated scope), E — the TARGET profile's
+ *  own `profile env` store (`readProfileEnvVars`, `core/profiles/env-store.ts`)
+ *  read directly off disk only when the profile belongs to the launched app, regardless of the host env or any
+ *  `spawnEnv.allow` entry (setting a value there IS the consent to cross this
+ *  boundary), F — the TARGET profile's manifest metadata as
+ *  `CRTR_PROFILE_META_*` (`profileMetadataEnv` above), plus D — the trusted,
+ *  crtr-constructed `inv.env` overlay and the
+ *  fork-bomb recursion guard `FRONT_DOOR_ENV=1`. D is layered last so crtr's
+ *  own constructed env always wins a name collision with a stored profile
+ *  value. Every broker launch (front-door root, managed child, `--root`,
+ *  every revive/daemon relaunch) funnels through `headlessBrokerHost.launch()`,
+ *  which calls this. */
+export declare function buildAppProcessEnv(targetCwd: string, targetProfileId: string | null, app: string): NodeJS.ProcessEnv;
+export declare function buildBrokerEnv(inv: PiInvocation): NodeJS.ProcessEnv;

package/dist/core/runtime/spawn-env.js

@@ -0,0 +1 @@
+var E=Object.defineProperty;var c=(t,e)=>E(t,"name",{value:e,configurable:!0});import{statSync as _}from"node:fs";import{SANDBOX_RUNTIME_HOME as R}from"../spaces/runtime-home.js";import{appProcessHome as p,appSpace as d,layoutRoot as T,runtimeRoot as m}from"../layout.js";import{delimiter as O,join as A,resolve as P}from"node:path";import{readMergedLaunchConfig as H}from"../config.js";import{readProfileEnvVars as M}from"../profiles/env-store.js";import{readAppEnvVars as N}from"../profiles/app-env-store.js";import{loadProfileManifest as h,metadataEnvName as I,readProfileMetadata as C}from"../profiles/manifest.js";import{binShimDirFor as w}from"./bin-contributions.js";import{FRONT_DOOR_ENV as v}from"./front-door-env.js";const D=new Set(["HOME","PATH","SHELL","USER","LOGNAME","TMPDIR","TERM","TERMINFO","COLORTERM","LANG","LANGUAGE","TZ","NO_PROXY","no_proxy","SSH_AUTH_SOCK","CRTR_BASH_VALVE_MS"]),S=["LC_","XDG_","PI_"],l="CRTR_ADMITTED_HOST_PATH";function y(t,e,o){const r=e.PATH;if(r===void 0||r==="")return null;for(const s of r.split(O)){const i=P(o,s===""?".":s,t);try{const n=_(i);if(n.isFile()&&(n.mode&73)!==0)return i}catch{}}return null}c(y,"resolvePathExecutable");function q(t,e,o){const r=e[l]??e.PATH;if(r===void 0||r==="")throw new Error(`cannot resolve crouter-owned ${t}: the admitted host PATH is empty`);const s=y(t,{PATH:r},o);if(s!==null)return s;throw new Error(`cannot resolve crouter-owned ${t} from the admitted host PATH`)}c(q,"resolveAdmittedHostCommand");const x=["HTTP_PROXY","HTTPS_PROXY","http_proxy","https_proxy"],u={anthropic:"ANTHROPIC_API_KEY",openai:"OPENAI_API_KEY"};function L(t){let e;try{e=new URL(t)}catch{return!1}return!(e.protocol!=="http:"&&e.protocol!=="https:"||e.hostname===""||e.username!==""||e.password!=="")}c(L,"isCredentialFreeProxyValue");function b(t,e){if(!e.includes("*"))return t===e;const o=e.split("*").map(r=>r.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")).join(".*");return new RegExp(`^${o}$`).test(t)}c(b,"matchesAllowPattern");function G(t){const e=t.host??process.env,o={};for(const[n,a]of Object.entries(e))a!==void 0&&(D.has(n)||S.some(f=>n.startsWith(f)))&&(o[n]=a);o.PWD=t.targetCwd;for(const n of x){const a=e[n];a!==void 0&&L(a)&&(o[n]=a)}const r=t.skipSpawnAllow?[]:H(t.targetCwd,t.targetProfileId).spawnEnv.allow;if(r.length>0)for(const[n,a]of Object.entries(e))a!==void 0&&r.some(f=>b(n,f))&&(o[n]=a);const s=e[l]??o.PATH;s!==void 0&&s!==""&&(o[l]=s);const i=w(t.targetCwd,t.targetProfileId);if(i!==null){const n=o.PATH;o.PATH=n===void 0||n===""?i:`${i}:${n}`}return o}c(G,"buildOperationalEnvBase");function V(t){const e={};for(const[o,r]of Object.entries(C(t)))e[I(o)]=r;return e}c(V,"profileMetadataEnv");function g(t,e,o){const r=e===null?null:h(e).manifest,s=r!==null&&(r.grantee??"app:terminal")===o,i=G({targetCwd:t,targetProfileId:e,skipSpawnAllow:o!=="app:terminal"}),n={...i,...N(o),...r===null?{}:V(e),...s?M(e):{},HOME:p(o),PI_CODING_AGENT_DIR:A(d(o).home,".pi","agent"),[l]:i[l],...process.platform==="linux"?{CRTR_RUNTIME_HOME:R}:{CRTR_HOME:T(),CRTR_RUNTIME_HOME:process.env.CRTR_RUNTIME_HOME??m()}};for(const a of Object.values(u))delete n[a];return n}c(g,"buildAppProcessEnv");function z(t){const e=t.env.CRTR_NODE_CWD??process.cwd(),o=t.env.CRTR_PROFILE_ID||null,r=t.env.CRTR_GRANTEE??"app:terminal",s=g(e,o,r),i={...s,...t.env,HOME:s.HOME,PI_CODING_AGENT_DIR:s.PI_CODING_AGENT_DIR,[l]:s[l],CRTR_RUNTIME_HOME:s.CRTR_RUNTIME_HOME,[v]:"1"};for(const n of Object.values(u))delete i[n];return i}c(z,"buildBrokerEnv");export{l as ADMITTED_HOST_PATH_ENV,u as PROVIDER_ENV_KEYS,g as buildAppProcessEnv,z as buildBrokerEnv,G as buildOperationalEnvBase,V as profileMetadataEnv,q as resolveAdmittedHostCommand,y as resolvePathExecutable};

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

@@ -0,0 +1,155 @@
+import { type SpawnNodeOpts } from './nodes.js';
+import { type WakeOrigin } from './bearings.js';
+import { type NodeMeta, type Mode, type Lifecycle, type OutcomeDeliveryBinding, type ReviewBinding } from '../canvas/index.js';
+import { type ModelRegistryLike, type ModelRequest } from '../model-routes.js';
+export interface SpawnChildOpts {
+    kind: string;
+    mode?: Mode;
+    cwd: string;
+    name?: string;
+    /** Caller-supplied description preserved against automatic naming. */
+    description?: string;
+    prompt: string;
+    /** Override the parent (defaults to the calling node from env). */
+    parent?: string;
+    /** Node that created this node. Unlike parent (manager) and spawned_by
+     *  (provenance), it is the actor of the `created` push. */
+    creator?: string | null;
+    /** Node acting when neither creator nor parent is (a node forking another). */
+    actor?: string | null;
+    /** Spawn an INDEPENDENT root instead of a managed child: parent=null, no
+     *  subscription back to the spawner, spawned_by=spawner. Resident and brought
+     *  forefront by default — see `rootLifecycle` for the unattended variant. */
+    root?: boolean;
+    /** Lifecycle for the new node. Roots default to resident and managed
+     *  children default to terminal. A resident child remains an interactable,
+     *  wakeable conversation without owing a final; a terminal child remains a
+     *  bounded worker that must finalize. For roots, terminal keeps the
+     *  unattended no-viewer behavior. */
+    rootLifecycle?: Lifecycle;
+    /** Direct root creation waits until the broker accepts viewers before it
+     *  returns. Cron-launched births use `launch`: the daemon must never wait in
+     *  its supervision loop. */
+    readiness?: 'await' | 'launch';
+    /** Fork the new node from an existing pi conversation instead of starting it
+     *  fresh: a node id (resolved to that node's session file), an absolute
+     *  `.jsonl` path, or a partial pi session uuid. pi COPIES that history into a
+     *  new session for the child — the source is untouched — then `prompt` is the
+     *  next message. A one-shot at birth; the child resumes its own session after. */
+    forkFrom?: string;
+    /** Set ONLY by the daemon when a `spawn`/spawn-cron wake births this node: the
+     *  provenance of the timer that fired (see WakeOrigin). In-memory only — it is
+     *  NOT part of the stored recipe (the daemon spreads it in at fire time via
+     *  `spawnChild({ ...recipe, wakeOrigin })`); `node new` never sets it. When set,
+     *  a <crtr-wake> block is prepended to the kickoff so the newborn knows a clock
+     *  birthed it. */
+    wakeOrigin?: WakeOrigin;
+    /** Pin the node to a model spec — exact `provider/id`, `provider/tier`
+     *  (e.g. `openai/ultra`), bare tier (ultra/strong/medium/light), or family
+     *  alias (opus/sonnet/haiku) — overriding the persona's declared default.
+     *  The supplied spec resolves once through the target ladders and its concrete
+     *  provider/model is persisted as the exact launch recipe. Omit to use the
+     *  persona default. */
+    model?: string;
+    /** Per-run scope allow-list. Omit to inherit the spawner's list. */
+    scopes?: string[];
+    /** Sticky run isolation; cannot be turned off by a descendant. */
+    isolated?: boolean;
+    /** App run identity set at birth; children inherit from the spawner. */
+    run?: SpawnNodeOpts['run'];
+    /** Commit run rows inside the same transaction as the newborn node. */
+    withinCreate?: SpawnNodeOpts['withinCreate'];
+    /** Select the profile this node runs under — an exact profile id or a unique
+     *  manifest name (or the closest match to one), resolved through
+     *  `resolveProfileOperand`. Omit to INHERIT the
+     *  spawner's current `profile_id` (managed child or --root alike — --root only
+     *  means top-level, it does not reset to a different profile; a shell root
+     *  falls back to the stable root profile in the startup selector). Passed
+     *  through unchanged into a scheduled birth command so a cron-launched birth
+     *  re-resolves the SAME choice at run time (an explicit value re-validates;
+     *  inheritance re-reads the creator's THEN-current profile). */
+    profile?: string | null;
+    /** Create a managed worktree for this node and pin its cwd to it. */
+    worktree?: boolean;
+    /** Local branch the managed worktree is cut from and later landed onto. */
+    worktreeBase?: string;
+    /** Absolute wall-clock deadline committed with this birth. */
+    deadlineAt?: string;
+    /** Delivery target committed with this birth before the broker launches. */
+    outcomeDelivery?: OutcomeDeliveryBinding;
+    /** Invocation-selected repository from which to cut a managed worktree. */
+    worktreeCwd?: string;
+    /** Preallocated node id, used when a managed worktree must be named before birth. */
+    nodeId?: string;
+    /** Bind the newborn to a review. Its transcript is then sliced at that
+     *  review's durable boundary marker, so a fork of a companion shows only the
+     *  review-era conversation rather than the origin context it inherited. */
+    reviewBinding?: ReviewBinding;
+    /** Hidden ambient "current situation" text — NOT the visible prompt/body.
+     *  Stored as a `situational` card BEFORE launch so canvas-context-intro's
+     *  session_start bearings nest it from the node's very first turn. Passed
+     *  through unchanged into a scheduled node-birth command. Omit for no
+     *  ambient context. */
+    situationalContext?: string;
+}
+/** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
+ *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).
+ *  A live node id resolves to its captured session FILE (absolute, cwd-immune); a
+ *  relative path is made absolute; a bare/partial uuid is resolved against pi's
+ *  sessions store. Throws when a known node has no captured session file, or when
+ *  a uuid resolves to zero or multiple sessions. */
+export declare function resolveForkSource(value: string): string;
+/** Resolve the profile a spawned child runs under: an explicit `--profile`
+ *  operand (id, name, or closest match) resolved through `resolveProfileOperand`, else INHERIT
+ *  the spawner's current `profile_id` (null when the spawner has none). `--root`
+ *  never resets this to null on its own; only an explicit override does. When
+ *  there is NO spawner at all — `crtr node new --root` run directly from a
+ *  shell, not from inside a node — there is no profile to inherit, so this runs
+ *  the same startup selector the front door uses (MRU covering `cwd`, else the
+ *  root-profile prompt/default). */
+export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string, options?: {
+    readOnlySelection?: boolean;
+}): Promise<string | null>;
+/** Reject a permanently invalid launch recipe against the registry that will
+ * serve it. Registered-but-unauthenticated/cooling requests intentionally pass
+ * this authoring check so broker policy for transient availability is unchanged. */
+export declare function assertLaunchModelRegistered(request: ModelRequest | undefined, options: {
+    cwd: string;
+    profileId: string | null;
+}, registry?: ModelRegistryLike): Promise<void>;
+export interface SpawnChildResult {
+    node: NodeMeta;
+    /** The birth found the broker cap full: the row exists and is marked frozen,
+     *  but no engine was launched. The node-lifecycle tick starts it when a slot
+     *  frees. */
+    frozen: boolean;
+    /** The viewer window opened for a --root in tmux; null otherwise (a managed
+     *  child opens no viewer, and a --root spawned outside tmux opens none). */
+    window: string | null;
+    /** The session the --root's viewer opened into (the caller's current session);
+     *  null when no viewer was opened. */
+    session: string | null;
+}
+/** Resolve who a spawn is attributed to. A managed child needs a spine parent
+ *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
+ *  does not: it is top-level by definition and the spawner identity is
+ *  provenance only — a human shell with no CRTR_NODE_ID is a legitimate root
+ *  spawner, so `crtr node new --root` from outside a node must not throw. */
+export declare function resolveSpawner(parent: string | undefined, ctxNodeId: string | null, root: boolean): string | null;
+/** Spawn a node from a live node. By default a managed terminal worker in a
+ *  background window, with the spawner auto-subscribed (active) via spawnNode.
+ *  With `root`: an independent resident root — parent=null, NO subscription back
+ *  to the spawner (it carries spawned_by=spawner for provenance only), brought
+ *  forefront so a human can pick up the conversation directly. */
+type BeforeBrokerLaunch = (nodeId: string) => void;
+type AfterNodeCreated = (nodeId: string) => void;
+export declare function spawnChildPrepared(opts: SpawnChildOpts, beforeBrokerLaunch?: BeforeBrokerLaunch, afterNodeCreated?: AfterNodeCreated): Promise<SpawnChildResult>;
+export declare function spawnChild(opts: SpawnChildOpts): Promise<SpawnChildResult>;
+/** Invoke the best-effort node-start plan before any cold broker launch. */
+export declare function invokeBirthLifecycleHooks(meta: NodeMeta): Promise<void>;
+/** Create an independent, idle root from a node's conversation and durable
+ * context. Runtime/graph state is intentionally not inherited. */
+/** Fork `sourceId` into a fresh root. `scopes` is the fork's allow-list; omit
+ *  for a root with no ceiling. */
+export declare function forkNode(sourceId: string, scopes?: string[], forker?: string): Promise<SpawnChildResult>;
+export {};

package/dist/core/runtime/spawn.js

@@ -0,0 +1,3 @@
+var oe=Object.defineProperty;var a=(e,o)=>oe(e,"name",{value:o,configurable:!0});import{accessSync as re,constants as ie}from"node:fs";import{isAbsolute as te,resolve as de,join as ae}from"node:path";import{appSpace as se}from"../layout.js";import{ApiError as z}from"../../api/errors.js";import{spawnNode as ce,forkSourceNode as le,currentNodeContext as fe,rootOfSpine as ue,newNodeId as me,preflightNodeId as he}from"./nodes.js";import{resolveProfileOperand as we}from"../profiles/manifest.js";import{selectProfileForCwd as pe,selectProfileForCwdReadOnly as ke}from"../profiles/select.js";import{buildLaunchSpecAsync as U,buildPiArgv as _e}from"./launch.js";import{createManagedWorktreeAsync as ve,rollbackManagedWorktreeAsync as ge}from"../worktree-mutation-async.js";import{usage as u,brokerLaunchFailed as R}from"../errors.js";import{writeGoal as ye}from"./kickoff.js";import{appendSituationalContext as be,formatSituationalProse as xe}from"./situational-context.js";import{ensureRoadmap as Ce}from"./roadmap.js";import{buildWakeBearings as Fe}from"./bearings.js";import{encodeKickoffOrigin as $e,KICKOFF_ORIGIN_ENV as Se}from"./stamp/protocol.js";import{beginExecution as Ee,crtrHome as Oe,getNode as f,fullName as V,jobDir as Re,recordExecutionPid as Pe,abortExecution as D,setFrozen as Ie}from"../canvas/index.js";import{contextDir as B,nodeAgentDir as A}from"../canvas/node-agent-paths.js";import{copyTreeBeneath as Ne}from"../spaces/open-beneath.js";import{conversationIdFromPath as P,conversationStore as v}from"../conversation-store/index.js";import{boundFleet as De,brokerThresholdsForDaemon as Be}from"./fleet.js";import{emitEvent as Ae}from"../events/emit.js";import{openViewerWindow as Le,focusOf as Te,windowOfPane as je}from"./placement.js";import{waitForBrokerViewSocket as We}from"./placement-tmux.js";import{transition as g}from"./lifecycle.js";import{beginBootFaultAttempt as Me}from"../canvas/recovery.js";import{headlessBrokerHost as L}from"./host.js";import{ensureDaemon as He}from"../../daemon/manage.js";import{readConfig as Ke}from"../config.js";import{modelRequestFromConfig as qe,unregisteredConcreteModel as ze}from"../model-routes.js";import{openModelRegistry as Ue}from"./model-registry.js";import{MODEL_SPEC_NEXT as Ve}from"./model-selection.js";import{forkNodeLedger as Xe}from"./ledger.js";import{discoverLifecycleHookRegistry as Ge}from"../command-hooks/discovery.js";import{invokeLifecycleHooks as Je}from"../command-hooks/transport/exec-lifecycle.js";function y(e){return{detail:{schema:"crtr.node-outcome-detail/v1",message:e instanceof Error?e.message:String(e)}}}a(y,"launchFailureOutcome");async function Qe(e,o,d){try{return await L.launch(e,o,d)}catch(r){try{g(e,"crash",{reason:"launch_failed",outcome:y(r)})}catch{}const t=r.message;throw R(t.startsWith("[broker]")?t:`[broker] refusing to launch ${e}: ${t}`,"Inspect the cause above, fix the launch recipe or environment, then retry.")}}a(Qe,"launchBrokerOrCrash");function Ye(e,o){try{g(e,"crash",{reason:"launch_failed",outcome:y(o)})}catch{}try{L.teardown(e)}catch{}}a(Ye,"crashAndTearDown");function Ze(e){const o=v().list().map(({conversation_id:t,path:s})=>({id:t,path:s})),d=o.filter(t=>t.id===e),r=d.length>0?d:o.filter(t=>t.id.startsWith(e));if(r.length===0)throw u(`--fork-from '${e}': no pi session with that id found.`,{next:"Pass a live node id, a real session uuid/prefix, or an absolute .jsonl session path."});if(r.length>1)throw u(`--fork-from '${e}': ambiguous \u2014 ${r.length} sessions match that id prefix; pass the full id or the .jsonl path.`,{next:"Pass the full session uuid or an absolute .jsonl path to disambiguate."});return r[0].path}a(Ze,"resolveSessionUuid");function X(e){const o=e.trim();if(o==="")throw u("--fork-from requires a node id, session file, or session uuid.",{next:"Pass a live node id, an absolute .jsonl session path, or a session uuid/prefix."});if(o.includes("/")||o.endsWith(".jsonl")){const r=P(te(o)?o:de(process.cwd(),o));if(r===null)throw u(`--fork-from '${o}': invalid conversation path.`,{next:"Pass a conversation file path or id."});return v().header(r).path}const d=f(o);if(d!==null){const r=d.pi_session_file;if(r==null||r==="")throw u(`node ${o} has no pi session yet \u2014 it has not captured a session FILE to fork from (the broker forks a .jsonl path, not a bare id).`,{next:"Pick a node that has captured a session, or drop --fork-from."});const t=P(r);if(t===null)throw u(`node ${o} has no valid conversation id.`,{next:"Pick a node with a captured conversation."});return v().header(t).path}return Ze(o)}a(X,"resolveForkSource");async function en(e,o,d,r={}){return e===null?null:e!==void 0&&e!==""?we(e).profileId:o!==null?f(o)?.profile_id??null:r.readOnlySelection===!0?ke(d):pe(d)}a(en,"resolveProfileId");function G(e){const o=e.modelIntent===void 0?void 0:`${e.modelIntent.family}/${e.modelIntent.strength}`;return qe(e.model,o,e.modelExact===!0)}a(G,"requestFromLaunch");async function J(e,o,d){if(e===void 0||e.kind==="logical")return;const r=ze(e,d??await Ue(),o);if(r!==void 0)throw u(`model '${r.request.spec}' is not registered in this daemon.`,{received:r.request.spec,next:Ve})}a(J,"assertLaunchModelRegistered");function nn(e,o,d){const r=e??o??null;if(!d&&r===null)throw new Error("spawnChild requires a calling node (CRTR_NODE_ID) or an explicit parent");return r}a(nn,"resolveSpawner");async function Q(e,o,d){try{He()}catch{}const r=fe(),t=e.root===!0,s=nn(e.parent,r.nodeId??null,t),c=e.mode??"base",h=e.rootLifecycle??(t?"resident":"terminal"),Y=t&&h==="resident",T=s===null?null:f(s),Z=e.creator===void 0||e.creator===null?null:f(e.creator);e.nodeId!==void 0&&he(e.nodeId);const w=e.forkFrom!==void 0?X(e.forkFrom):void 0,j=w===void 0?null:le(w),I=[T,Z,j].some(l=>l?.isolated===!0||l?.run_id!=null&&f(l.run_id)?.isolated===!0);if(I&&e.isolated===!1)throw new z(403,"isolated_run","isolation cannot be turned off under an isolated run",{param:"isolated"});const C=I||e.isolated===!0;if(C&&e.worktree===!0)throw new z(400,"invalid_request","isolated nodes cannot use a worktree",{param:"worktree"});const F=e.worktree===!0,p=C||F?e.nodeId??me():e.nodeId,$=C?e.run!==void 0&&t&&!I?e.cwd:ae(se(e.run?.grantee??T?.grantee??"app:terminal").nodes,p):e.cwd,b=await en(e.profile,s,$),W=(await U(e.kind,c,{lifecycle:h,hasManager:!t,model:e.model,modelOverride:e.model!==void 0,cwd:$,profileId:b})).launch;await J(G(W),{cwd:$,profileId:b});const M=j?.node_id??null;let k,S=$;try{F&&(k=await ve(e.worktreeCwd??e.cwd,p,e.worktreeBase),S=k.path);const l=F?(await U(e.kind,c,{lifecycle:h,hasManager:!t,model:e.model,modelOverride:e.model!==void 0,cwd:S,profileId:b})).launch:W;F&&await J(G(l),{cwd:S,profileId:b});const n=await ce({kind:e.kind,mode:c,lifecycle:h,cwd:S,name:e.name??e.kind,description:e.description,parent:t?null:s,creator:e.creator,...e.actor===void 0?{}:{actor:e.actor},forkSourceNode:M,spawnedBy:t?s??void 0:void 0,profile_id:b,...e.scopes===void 0?{}:{scopes:e.scopes},isolated:C,...e.run===void 0?{}:{run:e.run},...e.withinCreate===void 0?{}:{withinCreate:e.withinCreate},forkFrom:e.forkFrom,forkSourceFile:w,modelOverride:e.model===void 0?void 0:l.model,...k!==void 0?{managedWorktree:k}:{},...p!==void 0?{nodeId:p}:{},...e.reviewBinding===void 0?{}:{reviewBinding:e.reviewBinding},...e.deadlineAt===void 0?{}:{deadlineAt:e.deadlineAt},...e.outcomeDelivery===void 0?{}:{outcomeDelivery:e.outcomeDelivery},launch:l});if(d?.(n.node_id),e.forkFrom!==void 0)try{Xe(n.node_id,M??null)}catch(i){throw g(n.node_id,"crash",{reason:"launch_failed",outcome:y(i)}),i}if(ye(n.node_id,e.prompt),e.situationalContext!==void 0&&be(n.node_id,xe(e.situationalContext)),o!==void 0)try{o(n.node_id)}catch(i){throw g(n.node_id,"crash",{reason:"launch_failed",outcome:y(i)}),i}const N=e.prompt!=="",ee=`${N&&e.wakeOrigin!==void 0?`${Fe(e.wakeOrigin)}
+
+`:""}${e.prompt}`;c==="orchestrator"&&Ce(n.node_id,{goal:e.prompt.trim()}),await on(n);let H;if(w!==void 0)try{const i=P(w);if(i===null)throw new Error(`invalid fork source ${w}`);const m=v().fork(i,n.node_id);H=v().header(m).path}catch(i){throw g(n.node_id,"crash",{reason:"launch_failed",outcome:y(i)}),i}const _=_e(n,{prompt:ee,resumeSessionPath:H});if(_.env={..._.env,CRTR_SUBTREE:ue(n.node_id)},N){const i=e.wakeOrigin!==void 0?{type:"runtime",kind:"wake",wake:e.wakeOrigin}:{type:"runtime",kind:"kickoff",...n.spawned_by!=null&&n.spawned_by!==""?{spawnedBy:n.spawned_by}:{}};_.env[Se]=$e(i)}const E=De();if(!E.reserveSlot(n.node_id))return Ie(n.node_id,new Date().toISOString()),Ae({level:"info",event:"broker.frozen",node_id:n.node_id,fields:{live_count:E.size(),hard_cap:Be().automaticReviveCap}}),{node:f(n.node_id),frozen:!0,window:null,session:null};const ne=Me(n.node_id),x=Ee(n.node_id,{daemonEpoch:E.epoch()});_.env={..._.env,CRTR_EXECUTION_ID:x};let O;try{O=await Qe(n.node_id,_,{cwd:n.cwd,name:V(n),resuming:!1})}catch(i){throw D(x,{reason:"launch_failed"}),i}finally{E.releaseReservation(n.node_id)}if(O.pid===null){const i=new Error(`broker host returned no pid for ${n.node_id}`);throw D(x,{reason:"launch_failed"}),g(n.node_id,"crash",{reason:"launch_failed",outcome:y(i)}),R(`failed to launch the broker engine for ${n.node_id} (${n.name}) \u2014 the node was not started.`,`Inspect canonical event diagnostics with \`crtr sys logs --node ${n.node_id}\`, then verify the pi engine can start in this environment.`)}if(Pe(x,n.node_id,O.pid)==="shutdown")throw D(x,{reason:"superseded"}),L.teardown(n.node_id),R(`broker execution was superseded for ${n.node_id}`,"Retry spawning the node.");if(Y&&e.readiness==="await"&&!await We(n.node_id,O.exited)){const i=ne.explanation();throw Ye(n.node_id,new Error(i??`broker view socket never bound for ${n.node_id}`)),R(i!==null?`the root broker ${n.node_id} could not start \u2014 ${i}`:`the root broker ${n.node_id} never bound its view socket \u2014 it was not started.`,i!==null?"Resolve the cause named above, then retry.":`The broker engine exited before binding its view socket. Inspect canonical event diagnostics with \`crtr sys logs --node ${n.node_id}\`, then retry.`)}let K=null,q=null;if(!t&&s!==null&&Ke("user").auto_open_child_viewers)try{const i=Te(s);if(i!==null&&i.pane!==null&&i.pane!==""){const m=Le(n.node_id,i.session??"",{name:V(n),cwd:e.cwd,besidePane:i.pane,waitForBroker:!0,initialWhip:N});m!==null&&m.pane!==null&&m.pane!==""&&(q=m.session,K=je(m.pane))}}catch{}return{node:f(n.node_id),frozen:!1,window:K,session:q}}catch(l){throw k!==void 0&&p!==void 0&&f(p)===null&&await ge(k),l}}a(Q,"spawnChildPrepared");async function Hn(e){return Q(e)}a(Hn,"spawnChild");async function on(e){const o=Ge(e.cwd,e.profile_id).plans.get("node:start")??[];await Je(o,{node:{id:e.node_id,name:e.name,kind:e.kind,mode:e.mode,lifecycle:e.lifecycle,cwd:e.cwd,nodeDir:A(e.node_id),contextDir:B(e.node_id),jobDir:Re(e.node_id)},runtime:{isBirth:!0,canvasHome:Oe(),profile:e.profile_id??null}})}a(on,"invokeBirthLifecycleHooks");const rn=new Set(["initial-prompt.md","yield-message.md","result.json","jobs"]);async function Kn(e,o,d){const r=f(e);if(r===null)throw u(`unknown node: ${e}`,{received:e,next:"List nodes and pass the id of a node with a captured pi session."});const t=X(e),s=B(e);try{v().header(P(t)),re(s,ie.R_OK)}catch(c){throw new Error(`cannot fork ${e}: its conversation or context is unreadable \u2014 ${c.message}`)}return Q({kind:r.kind,mode:"base",cwd:r.cwd,prompt:"",root:!0,readiness:"await",forkFrom:e,...d===void 0?{}:{actor:d},profile:r.profile_id,model:r.model_override??void 0,...o===void 0?{}:{scopes:o}},c=>{const h=B(c);Ne(A(e),s,A(c),h,rn)})}a(Kn,"forkNode");export{J as assertLaunchModelRegistered,Kn as forkNode,on as invokeBirthLifecycleHooks,X as resolveForkSource,en as resolveProfileId,nn as resolveSpawner,Hn as spawnChild,Q as spawnChildPrepared};

package/dist/core/runtime/stamp/channel.d.ts

@@ -0,0 +1,20 @@
+import type { MessageOrigin } from './protocol.js';
+export interface MessageAnnouncement {
+    origin: MessageOrigin;
+}
+/** The correlation key for one message body. Announcers pass the text they are
+ *  about to send; the writer passes the text pi persisted. */
+export declare function messageSignature(text: string): string;
+/** Announce the origin of the user message `text` that is about to be sent. */
+export declare function announceMessageOrigin(text: string, origin: MessageOrigin): void;
+/** Take the announced metadata for a persisted message body, or null when no
+ *  seam announced this message. */
+export declare function claimMessageAnnouncement(text: string): MessageAnnouncement | null;
+/** Contribute namespaced fields to the next stamp the writer emits. Unknown
+ *  namespaces pass through untouched; the core writer never interprets them. */
+export declare function contributeStampExt(namespace: string, fields: Record<string, unknown>): void;
+/** Whether any contribution is waiting — an assistant message is stamped only
+ *  when one is, so an ordinary assistant turn costs no line. */
+export declare function hasPendingStampExt(): boolean;
+/** Take every buffered contribution, merged per namespace. */
+export declare function drainStampExt(): Record<string, Record<string, unknown>> | undefined;

package/dist/core/runtime/stamp/channel.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var o=(n,t)=>m(n,"name",{value:t,configurable:!0});import{createHash as f}from"node:crypto";const i=Symbol.for("@crouton-kit/crtr:stamp-channel"),g=16;function s(){const n=globalThis,t=n[i];if(t!==void 0)return t;const e={announcements:[],ext:[]};return n[i]=e,e}o(s,"channel");function c(n){return f("sha1").update(n.trim()).digest("hex")}o(c,"messageSignature");function l(n,t){const e=s();for(e.announcements.push({signature:c(n),origin:t});e.announcements.length>g;)e.announcements.shift()}o(l,"announceMessageOrigin");function d(n){const t=s(),e=c(n),r=t.announcements.findIndex(u=>u.signature===e);if(r<0)return null;const[a]=t.announcements.splice(r,1);return{origin:a.origin}}o(d,"claimMessageAnnouncement");function h(n,t){s().ext.push({namespace:n,fields:t})}o(h,"contributeStampExt");function S(){return s().ext.length>0}o(S,"hasPendingStampExt");function E(){const n=s();if(n.ext.length===0)return;const t={};for(const{namespace:e,fields:r}of n.ext.splice(0))t[e]={...t[e],...r};return t}o(E,"drainStampExt");export{l as announceMessageOrigin,d as claimMessageAnnouncement,h as contributeStampExt,E as drainStampExt,S as hasPendingStampExt,c as messageSignature};