@north-light/cli 0.0.0 → 0.3.414

package/dist/core/canvas/deliveries.d.ts

@@ -0,0 +1,120 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type DeliveryFailure, type DeliverySettlement as ProcessDeliverySettlement } from './delivery-contract.js';
+export type DeliveryState = 'pending' | 'handed_off' | 'acknowledged' | 'permanent_failed';
+export type DeliveryUrgency = 'critical' | 'urgent' | 'normal' | 'deferred';
+export interface DeliveryRecord {
+    deliveryId: string;
+    messageId: string;
+    destinationId: string;
+    urgency: DeliveryUrgency;
+    wake: 0 | 1;
+    state: DeliveryState;
+    attempts: number;
+    nextAttemptAt: number | null;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acknowledgedAt: number | null;
+    failedAt: number | null;
+    lastFailure: DeliveryFailure | null;
+    idempotencyKey: string | null;
+    canceledAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ClaimedNodeMail extends DeliveryRecord {
+    message: {
+        messageId: string;
+        seq: number;
+        operationId: string;
+        createdAt: string;
+        senderNodeId: string | null;
+        senderName: string | null;
+        kind: 'update' | 'urgent' | 'final' | 'message' | 'completed';
+        label: string;
+        bodyRef: string | null;
+        bodyJson: unknown | null;
+        disposition: 'human-answer' | 'human-canceled' | null;
+    };
+    handoff: 'fresh' | 'inherited';
+}
+type StoredDelivery = {
+    delivery_id: string;
+    message_id: string;
+    destination_id: string;
+    urgency: DeliveryUrgency;
+    wake: number;
+    state: DeliveryState;
+    attempts: number;
+    next_attempt_at: number | null;
+    claimed_at: number | null;
+    claim_owner: string | null;
+    acknowledged_at: number | null;
+    failed_at: number | null;
+    last_failure_json: string | null;
+    idempotency_key: string | null;
+    canceled_at: number | null;
+    created_at: number;
+    updated_at: number;
+};
+export declare function deliveryFrom(row: StoredDelivery): DeliveryRecord;
+/** Claim one broker channel. A refreshing or stale broker receives hold and changes nothing.
+ * Empty polls have no handoff to commit. If mail arrives after the plain read,
+ * the next tick claims it, just as if it arrived after the write transaction. */
+export declare function claimNodeMail(nodeId: string, executionId: string, channel: 'wake' | 'passive' | 'deferred_run', now?: number): {
+    action: 'claimed' | 'hold';
+    deliveries: ClaimedNodeMail[];
+};
+/** Pre-launch wake claim. It uses the same state transition but deliberately does not reject refresh intent. */
+export declare function claimKickoffMail(nodeId: string, executionId: string, now?: number): ClaimedNodeMail[];
+export type DeliverySettlement = {
+    state: 'acknowledged';
+} | {
+    state: 'released';
+} | {
+    state: 'permanent_failed';
+    failure: DeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: DeliveryFailure;
+};
+export declare function normalizedSettlement(settlement: DeliverySettlement | ProcessDeliverySettlement): DeliverySettlement;
+/** The one execution/attempt/owner fence for node mail and external actions. */
+export declare function settleDelivery(deliveryId: string, attempts: number, claimOwner: string, settlement: DeliverySettlement | ProcessDeliverySettlement, now?: number): boolean;
+/** Deliberate operator retry of a delivery that failed for good: back to pending, due now,
+ *  with a fresh attempt budget. The id and the claim fence are unchanged, and the last
+ *  failure stays recorded until the next attempt replaces it. Returns false when the id
+ *  is not a failed, uncanceled push delivery. */
+export declare function retryFailedDelivery(deliveryId: string, now?: number): boolean;
+/** Broker acknowledgement additionally checks that the execution is live before the per-row fence.
+ *  Refresh intent does not refuse it: a yielding turn still acknowledges the mail
+ *  its conversation consumed, and the watcher withholds the queued mail the
+ *  refresh abort discarded so the replacement execution replays only that. */
+export declare function acknowledgeNodeMail(nodeId: string, executionId: string, deliveries: Array<{
+    deliveryId: string;
+    attempts: number;
+    disposition: 'acknowledged' | 'released';
+}>, now?: number): {
+    action: 'acknowledged' | 'hold';
+    results: Array<{
+        deliveryId: string;
+        outcome: 'acknowledged' | 'released' | 'stale';
+    }>;
+};
+/** The immutable action document belonging to one external-action obligation. */
+export declare function messageBodyForDelivery(deliveryId: string): unknown | null;
+export declare function duePushDeliveries(now: number): DeliveryRecord[];
+export declare function claimPushDelivery(deliveryId: string, now: number, claimOwner: string): DeliveryRecord | null;
+export declare function resetHandedOffDeliveries(now: number): number;
+/** The lane checks the claim immediately before launching the action. An action
+ * superseded after claim but before dispatch must not start with stale input. */
+export declare function pushDeliveryClaimIsCurrent(delivery: DeliveryRecord, owner: string): boolean;
+/** Reset mail held by an execution that is no longer this node's one live execution.
+ * Push receiver deliveries have a due timestamp and are claimed by the daemon lane. */
+export declare function resetStaleExecutionMail(now: number): number;
+export declare function hasUnseenWakeMail(nodeId: string): boolean;
+export declare function hasWakeMailSince(nodeId: string, since: number): boolean;
+export declare function acknowledgedNodeMailCount(nodeId: string): number;
+/** Create the messaging schema and import every legacy mailbox/action/wait row. The caller owns the encompassing migration transaction. */
+export declare function migrateMessagingState(db: DatabaseSync): void;
+export {};

package/dist/core/canvas/deliveries.js

@@ -0,0 +1,102 @@
+var C=Object.defineProperty;var l=(e,a)=>C(e,"name",{value:a,configurable:!0});import{prepared as s}from"../sqlite-statements.js";import{existsSync as R,readFileSync as y}from"node:fs";import{randomBytes as H}from"node:crypto";import{openDb as T,prepared as L,withCanvasWrite as N}from"./db.js";import{inboxPath as D,passivePath as k}from"./paths.js";import{withRetryBudget as X}from"./delivery-contract.js";import{emitEvent as F}from"../events/emit.js";function v(e){return{deliveryId:e.delivery_id,messageId:e.message_id,destinationId:e.destination_id,urgency:e.urgency,wake:e.wake===1?1:0,state:e.state,attempts:e.attempts,nextAttemptAt:e.next_attempt_at,claimedAt:e.claimed_at,claimOwner:e.claim_owner,acknowledgedAt:e.acknowledged_at,failedAt:e.failed_at,lastFailure:e.last_failure_json===null?null:JSON.parse(e.last_failure_json),idempotencyKey:e.idempotency_key,canceledAt:e.canceled_at,createdAt:e.created_at,updatedAt:e.updated_at}}l(v,"deliveryFrom");function S(e,a,o,d){return L(e,`SELECT 1 FROM nodes n JOIN executions e ON e.node_id = n.node_id
+      WHERE n.node_id = ? AND e.execution_id = ? AND e.state != 'exited'${d?" AND n.intent IS NOT 'refresh'":""}`).get(a,o)!==void 0}l(S,"executionIsLive");function I(e,a,o,d,r,m=!1){return L(e,`SELECT d.*, m.message_id AS m_message_id, m.seq, m.operation_id, m.created_at AS message_created_at,
+            m.sender_node_id, m.sender_name, m.kind, m.label, m.body_ref, m.body_json, m.disposition,
+            CASE WHEN d.state = 'handed_off' THEN 'inherited' ELSE 'fresh' END AS handoff
+       FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+      WHERE d.destination_id = ? AND d.wake = ?
+        ${m?"AND m.kind = 'message' AND json_extract(m.body_json, '$.start_turn') = 0":d===0?"AND NOT (m.kind = 'message' AND coalesce(json_extract(m.body_json, '$.start_turn'), 1) = 0)":""}
+        AND d.canceled_at IS NULL
+        AND (d.state = 'pending' OR (d.state = 'handed_off' AND d.claim_owner = ?))
+      ORDER BY m.seq`).all(a,d,o).map(i=>({...v(i),message:{messageId:i.m_message_id,seq:Number(i.seq),operationId:i.operation_id,createdAt:i.message_created_at,senderNodeId:i.sender_node_id,senderName:i.sender_name,kind:i.kind,label:i.label,bodyRef:i.body_ref,bodyJson:i.body_json===null?null:JSON.parse(i.body_json),disposition:i.disposition},handoff:r?.has(i.delivery_id)===!0?"fresh":i.handoff}))}l(I,"nodeMailRows");const w=`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+  WHERE d.destination_id = ? AND d.wake = ? AND d.state = 'pending' AND d.canceled_at IS NULL
+    AND NOT (d.wake = 0 AND m.kind = 'message' AND coalesce(json_extract(m.body_json, '$.start_turn'), 1) = 0)`,j=`UPDATE deliveries SET state = 'handed_off', attempts = attempts + 1, claim_owner = ?, claimed_at = ?, updated_at = ?
+  WHERE delivery_id IN (${w})`;function Q(e,a,o,d=Date.now()){const r=o==="wake"?1:0;if(o==="deferred_run")return N(E=>{if(!S(E,e,a,!0))return{action:"hold",deliveries:[]};const i=s(E,`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+        WHERE d.destination_id = ? AND d.wake = 0 AND d.canceled_at IS NULL
+          AND m.kind = 'message' AND json_extract(m.body_json, '$.start_turn') = 0
+          AND (d.state = 'pending' OR (d.state = 'handed_off' AND d.claim_owner = ?))`).all(e,a),t=new Set(s(E,`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+        WHERE d.destination_id = ? AND d.wake = 0 AND d.state = 'pending' AND d.canceled_at IS NULL
+          AND m.kind = 'message' AND json_extract(m.body_json, '$.start_turn') = 0`).all(e).map(n=>n.delivery_id));return i.length&&s(E,`UPDATE deliveries SET state = 'handed_off', attempts = attempts + 1, claim_owner = ?, claimed_at = ?, updated_at = ?
+        WHERE delivery_id IN (${i.map(()=>"?").join(",")}) AND state = 'pending'`).run(a,d,d,...i.map(n=>n.delivery_id)),{action:"claimed",deliveries:I(E,e,a,0,t,!0)}});const m=T();return!m.isTransaction&&L(m,w).get(e,r)===void 0?S(m,e,a,!0)?{action:"claimed",deliveries:I(m,e,a,r)}:{action:"hold",deliveries:[]}:N(E=>{if(!S(E,e,a,!0))return{action:"hold",deliveries:[]};const i=new Set(L(E,w).all(e,r).map(t=>t.delivery_id));return L(E,j).run(a,d,d,e,r),{action:"claimed",deliveries:I(E,e,a,r,i)}})}l(Q,"claimNodeMail");function V(e,a,o=Date.now()){return N(d=>{if(!S(d,e,a,!1))throw new Error(`execution ${a} is not live for node ${e}`);const r=new Set(s(d,`SELECT delivery_id FROM deliveries
+        WHERE destination_id = ? AND wake = 1 AND state = 'pending' AND canceled_at IS NULL`).all(e).map(m=>m.delivery_id));return s(d,`UPDATE deliveries SET state = 'handed_off', attempts = attempts + 1, claim_owner = ?, claimed_at = ?, updated_at = ?
+        WHERE destination_id = ? AND wake = 1 AND state = 'pending' AND canceled_at IS NULL`).run(a,o,o,e),I(d,e,a,1,r)})}l(V,"claimKickoffMail");function M(e){return e.state==="accepted"?{state:"acknowledged"}:e}l(M,"normalizedSettlement");function W(e,a,o,d,r=Date.now()){const m=[],E=N(i=>{const n=s(i,"SELECT canceled_at FROM deliveries WHERE delivery_id = ? AND next_attempt_at IS NOT NULL").get(e)?.canceled_at!=null?{state:"acknowledged"}:M(d),_=X(n,a),c=_.settlement,A=c.state==="pending"||c.state==="permanent_failed"?JSON.stringify(c.failure):null,g=c.state==="released"?"pending":c.state,u=c.state==="pending"?c.nextAttemptAt:g==="pending"?r:null,p=Number(s(i,`UPDATE deliveries
+          SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+              acknowledged_at = ?, failed_at = ?, last_failure_json = ?, updated_at = ?
+        WHERE delivery_id = ? AND state = 'handed_off' AND attempts = ? AND claim_owner = ?`).run(g,u,g==="acknowledged"?r:null,g==="permanent_failed"?r:null,A,r,e,a,o).changes)===1;if(p&&_.exhausted&&c.state==="permanent_failed"){const O=s(i,"SELECT destination_id, message_id FROM deliveries WHERE delivery_id = ?").get(e);m.push({failure:c.failure,destinationId:O.destination_id,messageId:O.message_id})}return p});for(const i of m)F({level:"error",event:"delivery.exhausted",outcome:"failed",attempt:a,fields:{delivery_id:e,destination_id:i.destinationId,message_id:i.messageId,failure:i.failure,retry:`crtr sys retry-delivery ${e}`}});return E}l(W,"settleDelivery");function z(e,a=Date.now()){return N(o=>Number(s(o,`UPDATE deliveries
+        SET state = 'pending', attempts = 0, next_attempt_at = ?, failed_at = NULL, updated_at = ?
+      WHERE delivery_id = ? AND state = 'permanent_failed' AND canceled_at IS NULL AND last_failure_json IS NOT NULL`).run(a,a,e).changes)===1)}l(z,"retryFailedDelivery");function Z(e,a,o,d=Date.now()){return N(r=>S(r,e,a,!1)?{action:"acknowledged",results:o.map(E=>{const i=s(r,"SELECT 1 FROM deliveries WHERE delivery_id = ? AND destination_id = ?").get(E.deliveryId,e)!==void 0;return{deliveryId:E.deliveryId,outcome:i&&W(E.deliveryId,E.attempts,a,{state:E.disposition},d)?E.disposition:"stale"}})}:{action:"hold",results:[]})}l(Z,"acknowledgeNodeMail");function ee(e){const a=s(T(),`SELECT m.body_json FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+      WHERE d.delivery_id = ?`).get(e);return a===void 0||a.body_json===null?null:JSON.parse(a.body_json)}l(ee,"messageBodyForDelivery");function te(e){return s(T(),`SELECT * FROM deliveries
+      WHERE state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?
+      ORDER BY next_attempt_at, created_at, delivery_id`).all(e).map(v)}l(te,"duePushDeliveries");function ae(e,a,o){return N(d=>{const r=s(d,`UPDATE deliveries AS d SET state = 'handed_off', attempts = attempts + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+        WHERE d.delivery_id = ? AND d.state = 'pending' AND d.canceled_at IS NULL AND d.next_attempt_at <= ?
+          AND NOT EXISTS (SELECT 1 FROM deliveries old JOIN messages prior ON prior.message_id = old.message_id
+            JOIN messages next ON next.message_id = d.message_id
+            WHERE old.destination_id = d.destination_id AND old.delivery_id != d.delivery_id
+              AND old.state = 'handed_off' AND old.canceled_at IS NOT NULL
+              AND prior.event = 'outcome' AND next.event = 'outcome' AND prior.object_id = next.object_id)`).run(a,o,a,e,a);return Number(r.changes)===0?null:v(s(d,"SELECT * FROM deliveries WHERE delivery_id = ?").get(e))})}l(ae,"claimPushDelivery");function ne(e){return N(a=>{const o=s(a,`UPDATE deliveries SET state = 'permanent_failed', next_attempt_at = NULL,
+      claimed_at = NULL, claim_owner = NULL, failed_at = ?, updated_at = ?
+      WHERE state = 'handed_off' AND canceled_at IS NOT NULL AND next_attempt_at IS NOT NULL`).run(e,e),d=s(a,`UPDATE deliveries SET state = 'pending', next_attempt_at = CASE WHEN next_attempt_at IS NOT NULL THEN ? ELSE NULL END,
+         claimed_at = NULL, claim_owner = NULL, updated_at = ?
+         WHERE state = 'handed_off' AND (canceled_at IS NULL OR next_attempt_at IS NULL)`).run(e,e);return Number(o.changes)+Number(d.changes)})}l(ne,"resetHandedOffDeliveries");function ie(e,a){return s(T(),`SELECT 1 FROM deliveries WHERE delivery_id = ? AND state = 'handed_off'
+    AND attempts = ? AND claim_owner = ? AND canceled_at IS NULL`).get(e.deliveryId,e.attempts,a)!==void 0}l(ie,"pushDeliveryClaimIsCurrent");function de(e){return N(a=>Number(s(a,`UPDATE deliveries AS d SET state = 'pending', claimed_at = NULL, claim_owner = NULL, updated_at = ?
+      WHERE d.state = 'handed_off' AND d.next_attempt_at IS NULL
+        AND NOT EXISTS (
+          SELECT 1 FROM executions e WHERE e.node_id = d.destination_id AND e.execution_id = d.claim_owner AND e.state != 'exited'
+        )`).run(e).changes))}l(de,"resetStaleExecutionMail");function se(e){return s(T(),`SELECT 1 FROM deliveries WHERE destination_id = ? AND wake = 1
+       AND canceled_at IS NULL AND urgency != 'deferred' AND state IN ('pending', 'handed_off') LIMIT 1`).get(e)!==void 0}l(se,"hasUnseenWakeMail");function re(e,a){return s(T(),`SELECT 1 FROM deliveries WHERE destination_id = ? AND wake = 1
+       AND urgency != 'deferred' AND created_at >= ? LIMIT 1`).get(e,a)!==void 0}l(re,"hasWakeMailSince");function oe(e){return Number(s(T(),"SELECT COUNT(*) AS count FROM deliveries WHERE destination_id = ? AND acknowledged_at IS NOT NULL").get(e).count)}l(oe,"acknowledgedNodeMailCount");function f(){let e;do e=H(16).toString("hex");while(e==="00000000000000000000000000000000");return e}l(f,"newId");function U(e){if(!R(e))return[];const a=y(e,"utf8");return a.trim()===""?[]:a.split(`
+`).filter(o=>o.trim()!=="").map((o,d)=>{let r;try{r=JSON.parse(o)}catch(m){throw new Error(`invalid mailbox JSON at ${e}:${d+1}: ${m.message}`)}if(!/^(?!0{32}$)[0-9a-f]{32}$/.test(r.entry_id)||!/^(?!0{32}$)[0-9a-f]{32}$/.test(r.operation_id))throw new Error(`invalid mailbox identity at ${e}:${d+1}`);if(typeof r.ts!="string"||typeof r.label!="string")throw new Error(`incomplete mailbox entry at ${e}:${d+1}`);return r})}l(U,"readJsonLines");function $(e){return R(e)?new Set(y(e,"utf8").split(`
+`).map(a=>a.trim()).filter(Boolean)):new Set}l($,"readCanceled");function _e(e){e.exec(`
+CREATE TABLE IF NOT EXISTS messages (
+  message_id TEXT PRIMARY KEY,
+  seq INTEGER NOT NULL UNIQUE,
+  operation_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  sender_node_id TEXT,
+  sender_name TEXT,
+  kind TEXT NOT NULL CHECK (kind IN ('update', 'urgent', 'final', 'message', 'completed')),
+  label TEXT NOT NULL,
+  body_ref TEXT,
+  body_json TEXT,
+  disposition TEXT CHECK (disposition IS NULL OR disposition IN ('human-answer', 'human-canceled'))
+);
+CREATE TABLE IF NOT EXISTS deliveries (
+  delivery_id TEXT PRIMARY KEY,
+  message_id TEXT REFERENCES messages(message_id),
+  destination_kind TEXT NOT NULL CHECK (destination_kind IN ('node_inbox', 'external_action')),
+  destination_id TEXT NOT NULL,
+  urgency TEXT NOT NULL CHECK (urgency IN ('critical', 'urgent', 'normal', 'deferred')),
+  wake INTEGER NOT NULL CHECK (wake IN (0, 1)),
+  state TEXT NOT NULL CHECK (state IN ('armed', 'pending', 'handed_off', 'acknowledged', 'permanent_failed')),
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+  next_attempt_at INTEGER,
+  claimed_at INTEGER,
+  claim_owner TEXT,
+  acknowledged_at INTEGER,
+  failed_at INTEGER,
+  last_failure_json TEXT,
+  adapter_json TEXT,
+  effect_json TEXT,
+  idempotency_key TEXT,
+  canceled_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  CHECK (state = 'armed' OR message_id IS NOT NULL)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS messages_seq ON messages(seq);
+CREATE INDEX IF NOT EXISTS deliveries_node_inbox ON deliveries(destination_id, wake, state, created_at) WHERE destination_kind = 'node_inbox';
+CREATE INDEX IF NOT EXISTS deliveries_external_due ON deliveries(state, next_attempt_at) WHERE destination_kind = 'external_action';
+CREATE INDEX IF NOT EXISTS deliveries_handed_off ON deliveries(claim_owner) WHERE state = 'handed_off';
+CREATE INDEX IF NOT EXISTS deliveries_message ON deliveries(message_id);
+CREATE UNIQUE INDEX IF NOT EXISTS deliveries_idempotency ON deliveries(idempotency_key) WHERE idempotency_key IS NOT NULL;
+CREATE TABLE IF NOT EXISTS waits (
+  wait_id TEXT PRIMARY KEY,
+  node_id TEXT NOT NULL REFERENCES nodes(node_id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind = 'controller'),
+  target_id TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  satisfied_at INTEGER
+);
+CREATE UNIQUE INDEX IF NOT EXISTS waits_live ON waits(node_id) WHERE satisfied_at IS NULL;
+CREATE INDEX IF NOT EXISTS waits_node ON waits(node_id);
+`);const a=[];for(const t of s(e,"SELECT node_id FROM nodes").all()){const n=t.node_id,_=U(D(n)),c=R(`${D(n)}.cursor`)?y(`${D(n)}.cursor`,"utf8").trim():"",A=_.findIndex(u=>u.entry_id===c),g=$(`${D(n)}.canceled`);_.forEach((u,p)=>a.push({nodeId:n,wake:1,source:"inbox",fileRank:0,physicalIndex:p,entry:u,acknowledged:A>=0&&p<=A,canceled:g.has(u.entry_id),seq:0}));for(const[u,p]of[[0,`${k(n)}.draining`],[1,k(n)]])U(p).forEach((O,x)=>a.push({nodeId:n,wake:0,source:"passive",fileRank:u,physicalIndex:x,entry:O,acknowledged:!1,canceled:!1,seq:0}))}a.sort((t,n)=>t.entry.ts.localeCompare(n.entry.ts)||t.nodeId.localeCompare(n.nodeId)||t.fileRank-n.fileRank||t.physicalIndex-n.physicalIndex),a.forEach((t,n)=>{t.seq=n+1});const o=new Map;for(const t of a){const n=`${t.nodeId}\0${t.source}`,_=o.get(n)??[];_.push(t),o.set(n,_)}for(const t of o.values()){const n=t.map(_=>_.seq).sort((_,c)=>_-c);t.sort((_,c)=>_.fileRank-c.fileRank||_.physicalIndex-c.physicalIndex).forEach((_,c)=>{_.seq=n[c]})}const d=s(e,"INSERT INTO messages (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"),r=s(e,"INSERT INTO deliveries (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, acknowledged_at, canceled_at, created_at, updated_at) VALUES (?, ?, 'node_inbox', ?, ?, ?, ?, 0, ?, ?, ?, ?)");for(const t of a){const n=t.entry;d.run(n.entry_id,t.seq,n.operation_id,n.ts,n.from,n.from_name??null,n.kind,n.label,n.ref??null,n.data===void 0?null:JSON.stringify(n.data),n.disposition??null);const _=Date.parse(n.ts),c=Number.isFinite(_)?_:0;r.run(f(),n.entry_id,t.nodeId,n.tier,t.wake,t.acknowledged?"acknowledged":"pending",t.acknowledged?c:null,t.canceled?c:null,c,c)}const m=s(e,"SELECT * FROM human_action_deliveries").all();for(const t of m){const n=f();d.run(n,h(e),f(),new Date(t.created_at).toISOString(),null,null,"completed",t.request_id,null,t.completion_json,null);const _=t.state==="running"?"handed_off":t.state==="accepted"?"acknowledged":t.state;s(e,"INSERT INTO deliveries (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, next_attempt_at, claimed_at, claim_owner, acknowledged_at, failed_at, last_failure_json, adapter_json, idempotency_key, created_at, updated_at) VALUES (?, ?, 'external_action', 'human_action', 'normal', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)").run(f(),n,_,t.attempt,t.next_attempt_at,t.claimed_at,t.claim_owner,t.accepted_at,t.permanent_failed_at,t.last_failure_json,JSON.stringify({adapter:"subprocess",argv:JSON.parse(t.argv_json),cwd:t.cwd}),`human-action:${t.request_id}`,t.created_at,t.updated_at)}const E=s(e,"SELECT * FROM node_outcome_deliveries").all();for(const t of E){const n=t.document_json===null?null:f();n!==null&&d.run(n,h(e),f(),new Date(t.created_at).toISOString(),null,null,"completed",t.node_id,null,t.document_json,null);const _=t.document_json===null?"armed":t.state==="running"?"handed_off":t.state==="accepted"?"acknowledged":t.state;s(e,"INSERT INTO deliveries (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, next_attempt_at, claimed_at, claim_owner, acknowledged_at, failed_at, last_failure_json, adapter_json, idempotency_key, created_at, updated_at) VALUES (?, ?, 'external_action', ?, 'normal', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)").run(f(),n,t.action_name,_,t.attempt,t.next_attempt_at,t.claimed_at,t.claim_owner,t.accepted_at,t.permanent_failed_at,t.last_failure_json,JSON.stringify({adapter:"subprocess",argv:JSON.parse(t.argv_json),cwd:t.cwd,config_origin:t.config_origin,payload:t.payload_json===null?null:JSON.parse(t.payload_json)}),`node-outcome:${t.node_id}`,t.created_at,t.updated_at)}const i=s(e,"SELECT node_id, waiting_for, waiting_for_generation FROM nodes WHERE waiting_for IS NOT NULL").all();for(const t of i)s(e,"INSERT INTO waits (wait_id, node_id, kind, target_id, generation, created_at, satisfied_at) VALUES (?, ?, 'controller', ?, ?, ?, NULL)").run(f(),t.node_id,t.waiting_for,t.waiting_for_generation,Date.now())}l(_e,"migrateMessagingState");function h(e){return Number(s(e,"SELECT COALESCE(MAX(seq), 0) AS seq FROM messages").get().seq)+1}l(h,"nextSeq");export{Z as acknowledgeNodeMail,oe as acknowledgedNodeMailCount,V as claimKickoffMail,Q as claimNodeMail,ae as claimPushDelivery,v as deliveryFrom,te as duePushDeliveries,se as hasUnseenWakeMail,re as hasWakeMailSince,ee as messageBodyForDelivery,_e as migrateMessagingState,M as normalizedSettlement,ie as pushDeliveryClaimIsCurrent,ne as resetHandedOffDeliveries,de as resetStaleExecutionMail,z as retryFailedDelivery,W as settleDelivery};

package/dist/core/canvas/delivery-contract.d.ts

@@ -0,0 +1,37 @@
+export interface DeliveryFailure {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exitCode?: number;
+    signal?: string;
+    message?: string;
+    stderr?: string;
+}
+export type DeliverySettlement = {
+    state: 'accepted';
+} | {
+    state: 'permanent_failed';
+    failure: DeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: DeliveryFailure;
+};
+/** Durable exponential retry delay for the attempt that just failed. */
+export declare function deliveryBackoffMs(attempt: number): number;
+/** Attempts a retried delivery gets before it is failed for good. With the one-hour
+ *  delay cap this is roughly ten hours of trying: long enough to ride out a
+ *  receiver outage, short enough that undeliverable work becomes a visible failure
+ *  instead of a row that stays pending and scheduled forever. */
+export declare const DELIVERY_MAX_ATTEMPTS = 20;
+/** The retry budget applied at the one settlement fence. A retryable failure of
+ *  the last permitted attempt becomes a terminal one that keeps the original
+ *  failure's detail and says why it stopped. `exhausted` is true only for that
+ *  conversion, so the caller announces it exactly once. */
+export declare function withRetryBudget<T extends {
+    state: string;
+}>(settlement: T, attempts: number): {
+    settlement: T | {
+        state: 'permanent_failed';
+        failure: DeliveryFailure;
+    };
+    exhausted: boolean;
+};

package/dist/core/canvas/delivery-contract.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var a=(e,r)=>i(e,"name",{value:r,configurable:!0});function f(e){return Math.min(5e3*2**(e-1),36e5)}a(f,"deliveryBackoffMs");const s=20;function o(e,r){if(e.state!=="pending"||r<s)return{settlement:e,exhausted:!1};const t=e.failure,n=t.message??t.exitCode?.toString()??t.signal??t.kind;return{exhausted:!0,settlement:{state:"permanent_failed",failure:{...t,message:`retry budget exhausted after ${r} attempts; last failure: ${n}`}}}}a(o,"withRetryBudget");export{s as DELIVERY_MAX_ATTEMPTS,f as deliveryBackoffMs,o as withRetryBudget};

package/dist/core/canvas/executions.d.ts

@@ -0,0 +1,29 @@
+export interface Execution {
+    executionId: string;
+    nodeId: string;
+    daemonEpoch: string | null;
+    pid: number | null;
+    processIdentity: string | null;
+    state: 'launching' | 'running' | 'exited';
+    startedAt: string;
+    endedAt: string | null;
+    exitReason: string | null;
+}
+export declare function liveExecutionForNode(nodeId: string): Execution | null;
+export declare function beginExecution(nodeId: string, input: {
+    daemonEpoch: string | null;
+}): string;
+/** Returns shutdown when a late broker references an execution no longer live. */
+export declare function recordExecutionPid(executionId: string, nodeId: string, pid: number): 'recorded' | 'shutdown';
+export declare function endExecution(executionId: string, input: {
+    reason: string;
+}): boolean;
+export declare function abortExecution(executionId: string, input: {
+    reason: string;
+}): boolean;
+export declare function endLiveExecution(nodeId: string, input: {
+    reason: string;
+}): boolean;
+export declare function migrateLegacyExecutionIdentities(captureIdentity?: (pid: number) => string | undefined): {
+    migrated: string[];
+};

package/dist/core/canvas/executions.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var r=(e,t)=>g(e,"name",{value:t,configurable:!0});import{prepared as c}from"../sqlite-statements.js";import{randomUUID as h}from"node:crypto";import{openDb as f,prepared as A,withCanvasWrite as p}from"./db.js";import{capturePidIdentities as l,captureLivenessSnapshot as T,identitiesMatch as D,isBootScopedIdentity as L,isLegacyTicksIdentity as S}from"./pid.js";import{existsSync as y,readFileSync as U}from"node:fs";import{LAUNCHER_SOCKET as R}from"../../launcher/spec.js";import{forgetNodeToken as H,mintNodeToken as O,revokeNodeTokens as x}from"./node-tokens.js";function E(){return new Date().toISOString()}r(E,"now");function W(e){return{executionId:e.execution_id,nodeId:e.node_id,daemonEpoch:e.daemon_epoch??null,pid:e.pid??null,processIdentity:e.process_identity??null,state:e.state,startedAt:e.started_at,endedAt:e.ended_at??null,exitReason:e.exit_reason??null}}r(W,"hydrate");function B(e){const t=A(f(),"SELECT * FROM executions WHERE node_id = ? AND state != 'exited'").get(e);return t===void 0?null:W(t)}r(B,"liveExecutionForNode");function K(e,t){return p(n=>{const i=E();c(n,"UPDATE executions SET state = 'exited', ended_at = ?, exit_reason = 'superseded' WHERE node_id = ? AND state != 'exited'").run(i,e),x(n,"node_id",e,i);const o=h();return c(n,"INSERT INTO executions (execution_id, node_id, daemon_epoch, pid, process_identity, state, started_at, ended_at, exit_reason) VALUES (?, ?, ?, NULL, NULL, 'launching', ?, NULL, NULL)").run(o,e,t.daemonEpoch,i),O(n,o,e,i),o})}r(K,"beginExecution");function V(e,t,n){const i=l([n])?.get(n)??null;return p(o=>{if(c(o,"UPDATE executions SET pid = ?, process_identity = ?, state = 'running' WHERE execution_id = ? AND node_id = ? AND state = 'launching'").run(n,i,e,t).changes>0)return"recorded";const d=c(o,"SELECT pid FROM executions WHERE execution_id = ? AND node_id = ? AND state = 'running'").get(e,t);if(d?.pid===n)return"recorded";if(process.platform==="linux"&&y(R)&&d?.pid!=null){const N=T(),u=[d.pid];for(let a=0;a<u.length;a++)u.push(...N?.childrenOf.get(u[a])??[]);if(u.includes(n))return"recorded";for(const a of u)try{const m=U(`/proc/${a}/status`,"utf8"),_=/^NSpid:\s*(.+)$/m.exec(m)?.[1]?.trim().split(/\s+/).map(Number)??[];if(_.length>1&&_.at(-1)===n)return"recorded"}catch{}}return"shutdown"})}r(V,"recordExecutionPid");function P(e,t){return H(e),p(n=>{const i=E(),o=c(n,"UPDATE executions SET state = 'exited', ended_at = ?, exit_reason = ? WHERE execution_id = ? AND state != 'exited'").run(i,t.reason,e);return x(n,"broker_process_id",e,i),Number(o.changes)===1})}r(P,"endExecution");function j(e,t){return P(e,t)}r(j,"abortExecution");function q(e,t){return p(n=>{const i=E(),o=c(n,"UPDATE executions SET state = 'exited', ended_at = ?, exit_reason = ? WHERE node_id = ? AND state != 'exited'").run(i,t.reason,e);return x(n,"node_id",e,i),Number(o.changes)===1})}r(q,"endLiveExecution");function z(e=t=>l([t])?.get(t)){const t=f(),n=c(t,"SELECT execution_id, pid, process_identity FROM executions WHERE state = 'running' AND pid IS NOT NULL AND process_identity IS NOT NULL").all(),i=c(t,"UPDATE executions SET process_identity = ? WHERE execution_id = ? AND pid = ? AND process_identity = ? AND state = 'running'"),o=[];for(const s of n){if(!S(s.process_identity))continue;const d=e(s.pid);d===void 0||!L(d)||!D(d,s.process_identity)||i.run(d,s.execution_id,s.pid,s.process_identity).changes>0&&o.push(s.execution_id)}return{migrated:o}}r(z,"migrateLegacyExecutionIdentities");export{j as abortExecution,K as beginExecution,P as endExecution,q as endLiveExecution,B as liveExecutionForNode,z as migrateLegacyExecutionIdentities,V as recordExecutionPid};

package/dist/core/canvas/extensions.d.ts

@@ -0,0 +1,9 @@
+export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result", "canvas-prompt-scrub", "canvas-stamp", "canvas-elapsed"];
+/** Structural shipped-hook identity: a canvas-hook stem directly under a
+ * `pi-extensions` directory. A user's own extension elsewhere may share the
+ * stem and is not shipped. */
+export declare function isShippedCanvasExtension(path: string): boolean;
+/** Remove persisted shipped canvas extensions while retaining genuine
+ * caller/kind extras, including a custom extension whose basename happens to
+ * resemble a canvas hook outside a pi-extensions directory. */
+export declare function customExtensionPaths(extensions: readonly string[] | undefined): string[];

package/dist/core/canvas/extensions.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var e=(s,a)=>l(s,"name",{value:a,configurable:!0});import{extname as x}from"node:path";const r=["canvas-inbox-watcher","canvas-review-boundary","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-tool-guide","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve","canvas-preview-result","canvas-prompt-scrub","canvas-stamp","canvas-elapsed"],h=[["canvas-inbox-watcher","canvas-review-boundary","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-tool-guide","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve","canvas-preview-result","canvas-prompt-scrub","canvas-stamp"],["canvas-inbox-watcher","canvas-review-boundary","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-tool-guide","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve","canvas-preview-result","canvas-prompt-scrub"],["canvas-inbox-watcher","canvas-review-boundary","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-tool-guide","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve","canvas-preview-result"],["canvas-inbox-watcher","canvas-review-boundary","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-tool-guide","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve"],["canvas-inbox-watcher","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-review-boundary","canvas-context-intro","canvas-tool-guide","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve"],["canvas-inbox-watcher","canvas-stophook","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve"],["canvas-stophook","canvas-inbox-watcher","canvas-recap","canvas-goal-capture","canvas-passive-context","canvas-context-intro","canvas-doc-substrate","canvas-structured-output","canvas-bash-valve"]];function d(s,a){if(s.length<a.length)return!1;const n=s.slice(0,a.length),t=n[0].replaceAll("\\","/"),c="/pi-extensions/",o=t.lastIndexOf(c),v=t.endsWith(".js")?".js":t.endsWith(".ts")?".ts":null;if(o<1||v===null)return!1;const u=t.slice(0,o+c.length);return a.every((i,p)=>n[p].replaceAll("\\","/")===`${u}${i}${v}`)}e(d,"matchesExtensionPrefix");function b(s){return[r,...h].find(n=>d(s,n))?.length??0}e(b,"extensionPrefixLength");function g(s){const a=s.replaceAll("\\","/"),n=a.lastIndexOf("/"),t=a.slice(0,n).split("/").at(-1),c=a.slice(n+1),o=c.slice(0,c.length-x(c).length);return t==="pi-extensions"&&r.includes(o)}e(g,"isShippedCanvasExtension");function m(s){const a=s??[];return a.slice(b(a)).filter(n=>!g(n))}e(m,"customExtensionPaths");export{r as CANVAS_EXTENSION_NAMES,m as customExtensionPaths,g as isShippedCanvasExtension};

package/dist/core/canvas/focuses.d.ts

@@ -0,0 +1,22 @@
+import type { FocusRow } from './types.js';
+/** INSERT a viewport. Throws on UNIQUE(node_id) if `node_id` already occupies
+ *  another focus (or on PK conflict if `focus_id` exists) — by design. */
+export declare function openFocusRow(focus_id: string, pane: string | null, session: string | null, node_id: string): void;
+/** Hot-swap a focus's occupant — single-statement UPDATE. Respects
+ *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
+ *  (correct — vacate-first is placement.focus()'s job, not this setter's). */
+export declare function setFocusOccupant(focus_id: string, node_id: string): void;
+/** Re-point a viewer row's durable pane + its derived session cache after the
+ *  pane moves. Single-statement UPDATE. */
+export declare function setFocusPane(focus_id: string, pane: string | null, session: string | null): void;
+/** DELETE a viewport. */
+export declare function closeFocusRow(focus_id: string): void;
+/** The focus a node occupies (≤1, UNIQUE node_id), or null. */
+export declare function getFocusByNode(node_id: string): FocusRow | null;
+/** The focus realized by a given pane (`%id`), or null. */
+export declare function getFocusByPane(pane: string): FocusRow | null;
+/** A focus by its stable id, or null. Used by placement to read a row back by id
+ *  after openFocusRow registers a viewer. */
+export declare function getFocusById(focus_id: string): FocusRow | null;
+/** Every focus row, ordered by id. */
+export declare function listFocuses(): FocusRow[];

package/dist/core/canvas/focuses.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(o,e)=>i(o,"name",{value:e,configurable:!0});import{prepared as s}from"../sqlite-statements.js";import{openDb as u}from"./db.js";function c(o){return{focus_id:o.focus_id,pane:o.pane??null,session:o.session??null,node_id:o.node_id}}n(c,"focusFrom");function p(o,e,t,E){s(u(),"INSERT INTO focuses (focus_id, pane, session, node_id) VALUES (?, ?, ?, ?)").run(o,e,t,E)}n(p,"openFocusRow");function R(o,e){s(u(),"UPDATE focuses SET node_id = ? WHERE focus_id = ?").run(e,o)}n(R,"setFocusOccupant");function a(o,e,t){s(u(),"UPDATE focuses SET pane = ?, session = ? WHERE focus_id = ?").run(e,t,o)}n(a,"setFocusPane");function l(o){s(u(),"DELETE FROM focuses WHERE focus_id = ?").run(o)}n(l,"closeFocusRow");function F(o){const e=s(u(),"SELECT * FROM focuses WHERE node_id = ?").get(o);return e?c(e):null}n(F,"getFocusByNode");function _(o){const e=s(u(),"SELECT * FROM focuses WHERE pane = ?").get(o);return e?c(e):null}n(_,"getFocusByPane");function T(o){const e=s(u(),"SELECT * FROM focuses WHERE focus_id = ?").get(o);return e?c(e):null}n(T,"getFocusById");function S(){return s(u(),"SELECT * FROM focuses ORDER BY focus_id").all().map(c)}n(S,"listFocuses");export{l as closeFocusRow,T as getFocusById,F as getFocusByNode,_ as getFocusByPane,S as listFocuses,p as openFocusRow,R as setFocusOccupant,a as setFocusPane};

package/dist/core/canvas/history.d.ts

@@ -0,0 +1,104 @@
+import type { NodeStatus } from './types.js';
+export type HistorySource = 'inbox' | 'transcript';
+/** Every origin token `--origin` accepts. `human` is a person at a front door;
+ *  the rest mirror the runtime origin kinds; `unknown` is a message that
+ *  carries no stamp at all — its own bucket, never folded into another, since
+ *  a rising unknown rate is how a delivery seam that stopped announcing shows
+ *  itself. */
+export declare const ORIGIN_TOKENS: readonly ["human", "inbox", "wake", "revive", "restart-continuation", "stop-guard", "park", "recovery", "context-nudge", "kickoff", "unknown"];
+/** Message roles carried by a transcript artifact. */
+export declare const MESSAGE_ROLES: readonly ["user", "assistant", "toolResult"];
+/** One searchable unit of a past conversation: an inbox entry or a transcript
+ *  message. */
+export interface HistoryArtifact {
+    /** Stable handle passed verbatim to `history read` — `<node-id>:<relpath>`. */
+    ref: string;
+    nodeId: string;
+    /** `inbox/<n>` or `session/<n>`. */
+    relpath: string;
+    source: HistorySource;
+    /** ISO 8601 artifact timestamp. */
+    ts: string;
+    /** Sort key: epoch ms of ts. */
+    tsMs: number;
+    /** A one-line label for the entry or message. */
+    title: string;
+    nodeName: string;
+    nodeKind: string;
+    nodeStatus: NodeStatus;
+    nodeCwd: string;
+    nodeDesc: string;
+    /** The full body. */
+    loadBody: () => string;
+    /** What drove this message to arrive. Set ONLY on inbound artifacts — a
+     *  user-role transcript message or an inbox entry — because origin is a
+     *  property of arrival. An assistant turn leaves it undefined, so `--origin`
+     *  excludes generated turns without needing a role filter beside it. */
+    origin?: string;
+    /** Transcript only: user | assistant | toolResult. */
+    role?: string;
+    /** Sender attribution: an inbox stamp's delivered entries, or an inbox
+     *  entry's own sender. Comma-joined when a delivery carried several. */
+    from?: string;
+}
+export interface ScopeFilter {
+    /** A specific cwd. Default (all flags absent) = the caller's cwd. */
+    cwd?: string;
+    /** Every cwd on the canvas. */
+    allCwds?: boolean;
+    /** A node and its subscription descendants (one initiative / sub-DAG). */
+    under?: string;
+    /** Explicit node ids. */
+    nodes?: string[];
+}
+export interface CorpusFilter {
+    types?: HistorySource[];
+    /** Node kinds (developer, spec, …). */
+    kinds?: string[];
+    /** Node lifecycle statuses. */
+    statuses?: NodeStatus[];
+    /** Inclusive lower / upper bound on artifact ts, epoch ms. */
+    sinceMs?: number;
+    untilMs?: number;
+    /** Message-attribute narrowing — meaningful for transcript + inbox only.
+     *  An artifact without the field never survives the corresponding filter. */
+    origins?: string[];
+    roles?: string[];
+    /** Case-insensitive substring against the artifact's sender attribution. */
+    from?: string;
+}
+/** The cwd the caller means by default: the calling node's cwd (resolved from
+ *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
+ *  when not run as a node. */
+export declare function callerCwd(): string;
+/** Build the searchable artifact set for a scope + corpus filter. Node facets
+ *  are applied against the db rows first (cheap); only surviving nodes' files
+ *  are read. */
+export declare function buildCorpus(scope: ScopeFilter, corpus: CorpusFilter): HistoryArtifact[];
+export type GroupKey = 'origin' | 'node' | 'kind' | 'day' | 'type' | 'role';
+export interface CorpusGroup {
+    key: string;
+    count: number;
+}
+/** Collapse a built corpus into counts by one dimension, descending by count.
+ *  Artifacts that do not carry the grouped dimension are omitted rather than
+ *  bucketed as empty — grouping by origin answers "what drove arrivals", and a
+ *  generated turn is not an arrival. `unknown` is a real origin value here, not
+ *  a missing one. */
+export declare function groupCorpus(arts: HistoryArtifact[], by: GroupKey): CorpusGroup[];
+export interface ResolvedRef {
+    nodeId: string;
+    relpath: string;
+    source: HistorySource;
+    ts: string;
+    nodeName: string;
+    /** Rendered body. */
+    body: string;
+    /** The verbatim record (session bytes or jsonl line); null for an inbox entry. */
+    raw: string | null;
+    path: string | null;
+}
+/** Resolve a `<node-id>:inbox/<n>`, `<node-id>:session` or
+ *  `<node-id>:session/<n>` handle to its content. Returns null when the node is
+ *  unknown, the ref names another corpus, or the entry does not exist. */
+export declare function resolveRef(ref: string): ResolvedRef | null;

package/dist/core/canvas/history.js

@@ -0,0 +1,14 @@
+var w=Object.defineProperty;var d=(e,s)=>w(e,"name",{value:s,configurable:!0});import{prepared as M}from"../sqlite-statements.js";import{envNodeId as v}from"../../shared/env.js";import{getNode as p,listNodes as j,view as E}from"./canvas.js";import{openDb as O}from"./db.js";import{readTextIfExists as I}from"../fs-utils.js";import{conversationIdFromPath as y,conversationStore as g,ConversationNotFoundError as C}from"../conversation-store/index.js";import{reportBodyByName as B}from"../feed/reports.js";import{readStamps as R}from"../runtime/stamp/protocol.js";const ee=["human","inbox","wake","revive","restart-continuation","stop-guard","park","recovery","context-nudge","kickoff","unknown"],ne=["user","assistant","toolResult"];function A(){const e=v();if(e!==void 0&&e!==""){const s=p(e);if(s!==null)return s.cwd}return process.cwd()}d(A,"callerCwd");function k(e){const s=Date.parse(e);return Number.isNaN(s)?0:s}d(k,"toMs");function _(e){return M(O(),`SELECT m.created_at, m.sender_node_id, d.urgency, m.kind, m.label, m.body_ref, m.body_json
+       FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+      WHERE d.destination_id = ? AND d.wake = 1
+      ORDER BY m.seq, d.created_at, d.delivery_id`).all(e).map(n=>({ts:n.created_at,from:n.sender_node_id,tier:n.urgency,kind:n.kind,label:n.label,ref:n.body_ref,data:n.body_json===null?null:JSON.parse(n.body_json)}))}d(_,"allInboxEntries");function N(e){const s=[`from: ${e.from??"system"}`,`tier: ${e.tier}`].join(`
+`),n=`[${e.kind}] ${e.label}`,t=typeof e.data=="object"&&e.data!==null&&!Array.isArray(e.data)?e.data.body:void 0,o=typeof t=="string"?t.trim():"",i=typeof t=="string",r=e.ref!==null?i?I(e.ref)??"":B(e.ref)??"":o,l=r!==""&&r!==e.label,u=[s,n];return e.ref!==null&&u.push(`ref: ${e.ref}`),l&&u.push(r),u.join(`
+
+`)}d(N,"inboxEntryBody");function D(e,s,n,t){const o=`inbox/${String(t).padStart(6,"0")}`,i=N(n),r={ref:`${e.node_id}:${o}`,nodeId:e.node_id,relpath:o,source:"inbox",ts:n.ts,tsMs:k(n.ts),title:`[${n.kind}] from ${n.from??"system"}: ${n.label}`,nodeName:e.name,nodeKind:e.kind,nodeStatus:e.status,nodeCwd:e.cwd,nodeDesc:s,loadBody:d(()=>i,"loadBody"),origin:"inbox"};return typeof n.from=="string"&&n.from!==""&&(r.from=n.from),r}d(D,"inboxArtifact");function $(e){const s=p(e)?.pi_session_file,n=typeof s=="string"?y(s):null;if(n===null)return null;try{return g().header(n).path}catch(t){if(t instanceof C)return null;throw t}}d($,"resolveSessionFile");function T(e){if(typeof e=="string")return e;if(!Array.isArray(e))return"";const s=[];for(const n of e){if(n===null||typeof n!="object")continue;const t=n;t.type==="text"&&typeof t.text=="string"?s.push(t.text):t.type==="toolCall"&&s.push(`Tool: ${typeof t.name=="string"?t.name:"call"}`)}return s.join(`
+`)}d(T,"textFromBlocks");function F(e){return e==null?"unknown":e.type==="human"?"human":e.kind}d(F,"originToken");function L(e){if(e==null||e.type!=="runtime")return;const s=e.entries;if(s===void 0||s.length===0)return;const n=new Set;for(const t of s){const o=t.fromName??t.from;typeof o=="string"&&o!==""&&n.add(o)}return n.size===0?void 0:[...n].join(", ")}d(L,"sendersOf");function S(e){const s=$(e);if(s===null)return[];const n=g().read(y(s)).entries,t=new Map;for(const i of R(n)){if(i.kind!=="message")continue;const r=i.payload;typeof r.msgTs=="number"&&t.set(r.msgTs,r.origin)}const o=[];for(const i of n){if(i===null||typeof i!="object")continue;const r=i;if(r.type!=="message")continue;const l=r.message;if(l===null||typeof l!="object")continue;const u=l,f=typeof u.role=="string"?u.role:"";if(f==="")continue;const a=typeof u.timestamp=="number"?u.timestamp:void 0,c=typeof r.timestamp=="string"?r.timestamp:a!==void 0?new Date(a).toISOString():"",m=T(u.content),b={index:o.length,role:f,text:m,ts:c,tsMs:a??k(c)};if(f==="user"){const h=a!==void 0&&t.has(a)?t.get(a):null;b.origin=F(h);const x=L(h);x!==void 0&&(b.from=x)}o.push(b)}return o}d(S,"sessionMessages");function J(e,s){const n=g().read(y(e)).entries;let t=0;for(const o of n){if(o.type!=="message")continue;const i=o.message;if(!(i===null||typeof i!="object"||typeof i.role!="string")){if(t===s)return JSON.stringify(o);t++}}return null}d(J,"rawSessionLine");function K(e,s,n){const t=`session/${String(n.index).padStart(6,"0")}`,o=n.text.split(`
+`).map(r=>r.trim()).find(r=>r!=="")??"",i={ref:`${e.node_id}:${t}`,nodeId:e.node_id,relpath:t,source:"transcript",ts:n.ts,tsMs:n.tsMs,title:`[${n.role}] ${o.length>80?`${o.slice(0,80)}\u2026`:o}`,nodeName:e.name,nodeKind:e.kind,nodeStatus:e.status,nodeCwd:e.cwd,nodeDesc:s,loadBody:d(()=>n.text,"loadBody"),role:n.role};return n.origin!==void 0&&(i.origin=n.origin),n.from!==void 0&&(i.from=n.from),i}d(K,"transcriptArtifact");function W(e){return p(e)?.description??""}d(W,"nodeDescOf");function te(e,s){const n=P(e),t=s.kinds,o=s.statuses,i=n.filter(f=>!(t!==void 0&&t.length>0&&!t.includes(f.kind)||o!==void 0&&o.length>0&&!o.includes(f.status))),r=s.types!==void 0&&s.types.length>0?s.types:["inbox"],l=new Set(r),u=[];for(const f of i){const a=W(f.node_id);if(l.has("inbox")&&_(f.node_id).forEach((c,m)=>u.push(D(f,a,c,m))),l.has("transcript"))for(const c of S(f.node_id))u.push(K(f,a,c))}return u.filter(f=>s.sinceMs!==void 0&&f.tsMs<s.sinceMs||s.untilMs!==void 0&&f.tsMs>s.untilMs?!1:G(f,s))}d(te,"buildCorpus");function G(e,s){const{origins:n,roles:t,from:o}=s;return!(n!==void 0&&n.length>0&&(e.origin===void 0||!n.includes(e.origin))||t!==void 0&&t.length>0&&(e.role===void 0||!t.includes(e.role))||o!==void 0&&o!==""&&(e.from===void 0||!e.from.toLowerCase().includes(o.toLowerCase())))}d(G,"matchesMessageFilters");function oe(e,s){const n=new Map;for(const t of e){let o;switch(s){case"origin":o=t.origin;break;case"role":o=t.role;break;case"node":o=`${t.nodeName} (${t.nodeId})`;break;case"kind":o=t.nodeKind;break;case"type":o=t.source;break;case"day":o=t.ts.slice(0,10)||void 0;break}o===void 0||o===""||n.set(o,(n.get(o)??0)+1)}return[...n.entries()].map(([t,o])=>({key:t,count:o})).sort((t,o)=>o.count-t.count||t.key.localeCompare(o.key))}d(oe,"groupCorpus");function P(e){const s=j(),n=new Map(s.map(o=>[o.node_id,o]));if(e.nodes!==void 0&&e.nodes.length>0)return e.nodes.map(o=>n.get(o)).filter(o=>o!==void 0);if(e.under!==void 0&&e.under!=="")return[e.under,...E(e.under)].map(i=>n.get(i)).filter(i=>i!==void 0);if(e.allCwds===!0)return s;const t=e.cwd!==void 0&&e.cwd!==""?e.cwd:A();return s.filter(o=>o.cwd===t)}d(P,"scopedRows");function se(e){const s=e.indexOf(":");if(s===-1)return null;const n=e.slice(0,s),t=e.slice(s+1),o=p(n);if(o===null)return null;if(t.startsWith("inbox/")){const i=Number(t.slice(6)),r=_(n)[i];return r===void 0?null:{nodeId:n,relpath:t,source:"inbox",ts:r.ts,nodeName:o.name,body:N(r),raw:null,path:null}}if(t==="session"||t.startsWith("session/")){const i=$(n);if(i===null)return null;const r=S(n);if(t==="session"){const f=r.map(a=>`## ${a.role}${a.origin!==void 0?` (origin: ${a.origin})`:""}
+
+${a.text}`).join(`
+
+`);return{nodeId:n,relpath:t,source:"transcript",ts:r[r.length-1]?.ts??o.created,nodeName:o.name,body:f,raw:(()=>{const{header:a,entries:c}=g().read(y(i));return[a,...c].map(m=>`${JSON.stringify(m)}
+`).join("")})(),path:i}}const l=Number(t.slice(8)),u=r[l];return u===void 0?null:{nodeId:n,relpath:t,source:"transcript",ts:u.ts,nodeName:o.name,body:u.text,raw:J(i,l),path:i}}return null}d(se,"resolveRef");export{ne as MESSAGE_ROLES,ee as ORIGIN_TOKENS,te as buildCorpus,A as callerCwd,oe as groupCorpus,se as resolveRef};

package/dist/core/canvas/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './labels.js';
+export * from './paths.js';
+export * from './canvas.js';
+export * from './executions.js';
+export * from './sessions.js';
+export * from './worktrees.js';
+export * from './source.js';
+export * from './history.js';
+export * from './focuses.js';
+export * from './crons.js';
+export * from './telemetry.js';
+export * from './structured-requests.js';
+export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

@@ -0,0 +1 @@
+export*from"./types.js";export*from"./labels.js";export*from"./paths.js";export*from"./canvas.js";export*from"./executions.js";export*from"./sessions.js";export*from"./worktrees.js";export*from"./source.js";export*from"./history.js";export*from"./focuses.js";export*from"./crons.js";export*from"./telemetry.js";export*from"./structured-requests.js";import{openDb as d,closeDb as g}from"./db.js";export{g as closeDb,d as openDb};

package/dist/core/canvas/install-id.d.ts

@@ -0,0 +1,9 @@
+/** 4-16 lowercase [a-z0-9] characters — the shape both an env-supplied and a
+ *  self-minted install id must satisfy. */
+export declare function isValidInstallId(id: string): boolean;
+/** Get-or-create the canvas-install id every minted node id embeds. Called
+ *  once at daemon boot (`crtrd.ts`) — a thrown error there fails boot loudly,
+ *  which is the intended behavior for both an invalid env value and a
+ *  stored/env mismatch. Runs in the caller's canvas write transaction when
+ *  one is open, else its own. `env` is injectable for tests. */
+export declare function resolveInstallId(env?: NodeJS.ProcessEnv): string;

package/dist/core/canvas/install-id.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var a=(t,e)=>u(t,"name",{value:e,configurable:!0});import{prepared as l}from"../sqlite-statements.js";import{randomBytes as d}from"node:crypto";import{withCanvasWrite as I}from"./db.js";const i="install_id",h=/^[a-z0-9]{4,16}$/,c="abcdefghijklmnopqrstuvwxyz0123456789";function f(t){return h.test(t)}a(f,"isValidInstallId");function m(){const t=d(8);let e="";for(let n=0;n<8;n++)e+=c[t[n]%c.length];return e}a(m,"mintInstallId");function v(t){return l(t,"SELECT value FROM canvas_meta WHERE key = ?").get(i)?.value??null}a(v,"readInstallId");function T(t,e){l(t,"INSERT INTO canvas_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(i,e)}a(T,"writeInstallId");function _(t=process.env){return I(e=>{const n=v(e),s=t.CRTR_INSTALL_ID,r=s!==void 0&&s!==""?s:null;if(n!==null){if(r!==null&&r!==n)throw new Error(`CRTR_INSTALL_ID='${r}' conflicts with the install id already persisted in this canvas home ('${n}'). This canvas home was minted under a different install id \u2014 refusing to boot rather than silently mask what is usually a provisioning bug (this process pointed at the wrong volume/home).`);return n}if(r!==null&&!f(r))throw new Error(`CRTR_INSTALL_ID='${r}' is not a valid install id \u2014 expected 4-16 lowercase [a-z0-9] characters.`);const o=r??m();return T(e,o),o})}a(_,"resolveInstallId");export{f as isValidInstallId,_ as resolveInstallId};

package/dist/core/canvas/labels.d.ts

@@ -0,0 +1,30 @@
+import type { Mode, NodeMeta } from './types.js';
+/** Nerd Font glyph for a node's mode in its persona badge. A base worker reads
+ *  as a single figure (nf-fa-user, U+F007); an orchestrator reads as a fan-out
+ *  hierarchy (nf-fa-sitemap, U+F0E8). */
+export declare function modeIcon(mode: Mode): string;
+/** The minimal shape `fullName` needs — satisfied by NodeMeta, by NodeRow, and
+ *  by anything else carrying name + kind (description optional). */
+export interface NamedNode {
+    name: string;
+    kind: string;
+    description?: string;
+    icon?: string;
+}
+/** A node's human label: its explicit handle plus the pi-generated description
+ *  of its first task, e.g. `fix-auth refactor-login-flow`. The handle is
+ *  dropped when it's just the kind default (non-informative, and the kind is
+ *  surfaced elsewhere), so a default-named node reads as its description alone
+ *  (`refactor-login-flow`). Falls back to the bare name when no description
+ *  exists yet (a node not yet named, e.g. a bare root before its first
+ *  message). Never empty. */
+export declare function fullName(node: NamedNode): string;
+/** The node's persona label, rendered in the attach editor's bottom-right
+ *  badge. */
+export declare function personaLabel(meta: Pick<NodeMeta, 'kind' | 'mode'>): string;
+/** The pi session display name — the editor label in the top-left. It carries
+ *  ONE name: a person's explicit handle when present, otherwise the generated
+ *  description of the node's first task. Unlike `fullName` it never prints
+ *  both, so the chip doesn't read as two names side by side. Persona lives in
+ *  the editor's bottom-right badge. Recomputed from meta on every revive. */
+export declare function editorLabel(meta: NodeMeta): string;

package/dist/core/canvas/labels.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var o=(n,r)=>c(n,"name",{value:r,configurable:!0});function s(n){return n==="orchestrator"?"\uF0E8":"\uF007"}o(s,"modeIcon");function a(n){const r=(n.description??"").trim(),e=[n.name&&n.name!==n.kind?n.name:"",r].filter(t=>t!=="").join(" ");return e!==""?e:n.name}o(a,"fullName");function m(n){return`${s(n.mode)} ${n.kind}`}o(m,"personaLabel");function d(n){const r=(n.icon??"").trim(),i=n.name&&n.name!==n.kind?n.name.trim():"",e=(n.description??"").trim(),t=i!==""?i:e!==""?e:n.name;return r!==""?`${r} ${t}`:t}o(d,"editorLabel");export{d as editorLabel,a as fullName,s as modeIcon,m as personaLabel};

package/dist/core/canvas/managed-worktree-sweep-candidates.d.ts

@@ -0,0 +1,4 @@
+/** Find only terminal nodes with an unreconciled, explicitly disposable worktree.
+ * Keep due-time parsing in JS: Date.parse accepts more than SQLite's date
+ * functions, and malformed dates are due rather than permanently skipped. */
+export declare function managedWorktreeSweepCandidates(now: number): string[];

package/dist/core/canvas/managed-worktree-sweep-candidates.js

@@ -0,0 +1,12 @@
+var d=Object.defineProperty;var a=(t,o)=>d(t,"name",{value:o,configurable:!0});import{openDb as _,prepared as r}from"./db.js";function w(t){const o=r(_(),`
+    SELECT w.node_id, w.sweep_observed_json, w.next_attempt_at,
+           w.abandoned_json, w.land_intent_json, w.disposal_json
+    FROM worktrees w
+    JOIN nodes n ON n.node_id = w.node_id
+    WHERE n.status IN ('done', 'dead', 'canceled')
+      AND n.node_id NOT IN (SELECT node_id FROM warm_pool)
+      AND w.state IN ('open', 'closed')
+      AND (w.state = 'open' OR w.cleanup_state IS NULL OR w.cleanup_state != 'complete')
+      AND (w.state = 'closed' OR (n.status = 'done' AND n.final_report IS NOT NULL))
+    ORDER BY n.created
+  `).all(),s=[];for(const e of o){try{for(const n of[e.sweep_observed_json,e.abandoned_json,e.land_intent_json,e.disposal_json])n!==null&&JSON.parse(n)}catch{continue}if(e.sweep_observed_json!==null&&e.next_attempt_at!==null){const n=Date.parse(e.next_attempt_at);if(!Number.isNaN(n)&&n>t)continue}s.push(e.node_id)}return s}a(w,"managedWorktreeSweepCandidates");export{w as managedWorktreeSweepCandidates};