@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,461 @@
+/** What a node is doing right now. `active` means the engine process — a detached
+ *  headless broker — is live, NOT that it holds a window or that anyone is
+ *  watching it (attachment is a separate axis: the `focuses` table tracks each
+ *  node's one viewer pane, and the broker records its helloed-viewer count).
+ *  Crucially, `active` does NOT mean the node is GENERATING right now: a live
+ *  engine sits dormant between turns (waiting on a child, a human, or just left
+ *  open), so `active` ≠ busy — it only means the process was never closed. To tell
+ *  whether an active node is actually working, check its pi session-file mtime or
+ *  CPU, not its status. UI shows active+idle; `done` is hidden but revivable;
+ *  `canceled` is a user-closed node (also hidden, also revivable — not a fault);
+ *  only `dead` is a fault. */
+export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** Does stopping finalize the node? terminal = worker (finalizes on push --final);
+ *  resident = an interactable conversation that parks and remains wakeable
+ *  without being forced to submit a final. */
+export type Lifecycle = 'terminal' | 'resident';
+/** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
+export type Mode = 'base' | 'orchestrator';
+/** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
+export type ExitIntent = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
+export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined' | 'out_of_memory' | 'cap_exhausted';
+export type NodeOutcomeKind = 'result' | 'failure';
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export declare const OUTCOME_PAYLOAD_MAX_BYTES: number;
+export interface NodeOutcomeDetailV1 {
+    schema: 'crtr.node-outcome-detail/v1';
+    message?: string;
+    fault_kind?: import('../fault-classifier.js').FaultKind;
+    error_class?: import('../events/types.js').ErrorClassCode;
+    retry?: {
+        attempt: number;
+        max: number;
+    };
+    respawn_failures?: number;
+    deadline?: {
+        deadline_at: string;
+        elapsed_ms: number;
+    };
+    /** Present only for reason `declined`: what the node gave `crtr push result --decline`. */
+    declined?: DeclinedResult;
+    truncated?: true;
+}
+/** A declined structured result. `code` is opaque here — the requester validates it. */
+export interface DeclinedResult {
+    reason: string;
+    code: string;
+    retryable: boolean;
+}
+/** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
+ *  org chart, views, completion routing). `spawned_by` is audit only. */
+/** The pi launch recipe, persisted so the daemon can faithfully revive a node
+ *  as its *current* self. Rewritten on every polymorph (base→orchestrator). */
+export interface LaunchSpec {
+    /** Model id/pattern passed to pi `--model`. */
+    model?: string;
+    /** Original logical family/strength preference, retained after normalization. */
+    modelIntent?: import('../../types.js').ModelIntent;
+    /** True for an exact-consult launch: `model` is the verbatim captured
+     *  `provider/id:thinking` spec, bypassing the review floor/normalize and
+     *  every launch-time/turn-time provider fallback — an unavailable exact
+     *  model must fail rather than substitute. See `buildLaunchSpec`. */
+    modelExact?: boolean;
+    /** pi `--tools` allow-list. */
+    tools?: string[];
+    /** pi `-e` extension paths, loaded once; they self-gate on live {kind,mode}. */
+    extensions: string[];
+    /** Resolved system prompt text (passed via --append-system-prompt / --system-prompt). */
+    systemPrompt?: string;
+    /** Extra env injected into the pi process. */
+    env: Record<string, string>;
+    /** A managed-worktree request for a node in a Blaxel sandbox (D102): the start script switches the image's clone of
+     *  `repository` to a new `branch` cut from `base`. Absent on a Mac, where crtrd makes the worktree. */
+    worktree?: {
+        repository: string;
+        branch: string;
+        base: string;
+    };
+}
+/** The repository fingerprint a refusal was decided against. An examination
+ *  that reads the same values can skip the whole proof cascade: nothing about
+ *  the refusal can have changed. */
+export interface ManagedWorktreeObservation {
+    /** Tip of `refs/heads/<base_ref>`, or null when it no longer resolves. */
+    base: string | null;
+    /** Tip of the base branch's upstream (or `origin/<base_ref>` fallback). */
+    upstream: string | null;
+    /** Tip of `refs/heads/<branch>`, or null when the branch is gone. */
+    branch: string | null;
+    /** `absent`, or a hash of the checkout's HEAD plus `git status --porcelain`. */
+    checkout: string | null;
+}
+/** Reconciliation bookkeeping owned SOLELY by the daemon's managed-worktree
+ *  sweep. Present only while a record is not yet reconciled; cleared when
+ *  cleanup completes. */
+export interface ManagedWorktreeSweep {
+    /** Structured code for why the last pass did not complete cleanup. */
+    reason: string;
+    detail?: string;
+    observed: ManagedWorktreeObservation;
+    /** Consecutive passes that examined this record without completing it. */
+    attempts: number;
+    last_attempt: string;
+    /** The sweep does not re-examine this record before this instant. */
+    next_attempt: string;
+    /** Set once `attempts` reaches the terminal backoff tier: this record needs a
+     *  human, and `crtr sys worktrees` lists it with its reason. It is still
+     *  fingerprint-checked at the capped interval, so work that lands later is
+     *  still cleaned up. */
+    quarantined?: true;
+}
+export interface ManagedWorktree {
+    state: 'open' | 'closed' | 'abandoned';
+    /** A closed worktree remains registered until its owner has exited, so Git
+     *  never deletes the caller's live checkout beneath it. The daemon sweep is
+     *  the one authority that turns `pending` into `complete`. */
+    cleanup?: 'pending' | 'complete';
+    path: string;
+    branch: string;
+    repo_root: string;
+    base_ref: string;
+    base_sha: string;
+    created: string;
+    closed?: string;
+    abandoned?: {
+        branch: string;
+        tip_sha: string;
+        at: string;
+        by: string;
+    };
+    /** Recorded by `close` when the rebase succeeded but fast-forwarding the base
+     *  was blocked. The sweep lands a dead node's commits ONLY for a record
+     *  carrying this: the daemon finishes a job someone started, it never invents
+     *  the intent to land. */
+    land_intent?: {
+        at: string;
+        blocked: string;
+    };
+    sweep?: ManagedWorktreeSweep;
+    /** Recorded ONLY by an explicit branch-moved `close` when the checkout's
+     *  actual branch has drifted from `branch` (its recorded `crtr/*` ref is
+     *  gone — ordinary PR work moved it there) but that branch's content was
+     *  proven, immediately before this was written, already contained in the
+     *  recorded base or its upstream. Authorizes ONLY the daemon sweep's later
+     *  checkout removal for this EXACT path + git common dir + observed branch
+     *  + observed SHA — the sweep re-verifies all four before acting and NEVER
+     *  deletes `observed_branch`, since it is not a `crtr/*` branch crouter
+     *  created. A mismatch on re-verification invalidates the authorization; a
+     *  fresh explicit close must re-establish it. Absent for every ordinary
+     *  managed worktree, and for `abandon`'s branch-moved path (which disposes
+     *  immediately instead of deferring, so it needs no persisted grant). */
+    disposal?: {
+        observed_branch: string;
+        observed_sha: string;
+        common_dir: string;
+        authorized: string;
+    };
+}
+/** Immutable companion provenance. The origin session/leaf/model coordinates
+ *  remain canonical in the review row rather than being duplicated into node
+ *  metadata. `kind` names the surface the companion serves: absent or `review`
+ *  is a human document review; `page_feedback` binds a page ticket's feedback
+ *  conversation, with review_id = ticket id and target_file = the page source. */
+export interface ReviewBinding {
+    kind?: 'review' | 'page_feedback';
+    review_id: string;
+    origin_node_id: string;
+    branch_file: string;
+    target_file: string;
+}
+/** A node's durable configuration, stored in SQL node columns. Sessions and
+ *  managed worktrees have their own SQL stores. */
+export interface NodeIdentity {
+    node_id: string;
+    name: string;
+    /** A 2-4 word kebab-case handle derived from the node's first prompt (named
+     *  headlessly by pi; see runtime/naming.ts). Shown in the editor label. */
+    description?: string;
+    /** The same first prompt named as PROSE — a sentence-case phrase with its
+     *  punctuation intact, produced by the same headless namer in the same call as
+     *  `description`. Kebab case is right for a tmux window and an editor label
+     *  and wrong for a conversation list, so a surface reading to a person takes
+     *  this. Absent on a node named before titles existed. */
+    title?: string;
+    /** A single Nerd Font glyph depicting the node's work, chosen by the same
+   *  headless namer that produced `description` (see runtime/naming.ts). Kept as
+   *  its own field rather than baked into the description so each surface decides
+   *  whether to render it; absent on a node named before icons existed, or when
+   *  the model returned nothing usable. */
+    icon?: string;
+    /** How many times this node has been (re)launched — born at 0, bumped on
+     *  every revive. Exposed to the pi footer as CRTR_CYCLES so a refresh/crash
+     *  cycle reads at a glance there. */
+    cycles?: number;
+    created: string;
+    /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
+    cwd: string;
+    /** Which HOST launches + supervises this node: 'tmux' (a pane) or 'broker' (the
+     *  headless in-process engine). NULL ⇒ 'tmux' (every pre-broker node). */
+    host_kind?: 'tmux' | 'broker' | null;
+    /** The profile this node runs under, a stable profile-directory id
+     *  (`<slug>-<id>`, see `core/profiles/manifest.ts`). It is chosen once at spawn
+     *  (inherited from the spawner, or `--profile`) and is the runtime→resolver seam
+     *  (`CRTR_PROFILE_ID`) the memory/gate substrate reads. NULL only for historical
+     *  root/no-profile rows; new root conversations use the stable root profile id. */
+    profile_id?: string | null;
+    /** Role the node was born as: explore | developer | plan | review | general… */
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    /** The last {kind,mode,lifecycle} whose context delivery was acknowledged.
+     *  Meta-only (not a db column). Born equal to the initial persona; later
+     *  changes advance only after a baseline or provider-gated transition is
+     *  durably registered. Historical rows may omit `kind`; reads resolve it to
+     *  the current kind so they do not fabricate a transition. */
+    persona_ack?: {
+        kind?: string;
+        mode: Mode;
+        lifecycle: Lifecycle;
+    };
+    /** Spine parent — my manager (who subscribes to me); drives canvas nesting +
+     *  orphaning. null for a root (top-level, no manager). */
+    parent?: string | null;
+    /** Provenance — who spawned me (the `spawned_by` edge). Decoupled from
+     *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
+     *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
+    spawned_by?: string | null;
+    /** Actor that created this node; null when an external process did. Unlike
+     *  `parent` (manager) and `spawned_by` (provenance edge), this determines
+     *  whether birth is announced to the manager. */
+    creator?: string | null;
+    /** Raw `--fork-from` operand retained for identity framing and audit. */
+    fork_from?: string | null;
+    /** Resolved absolute source session file used for every pre-bind fork retry. */
+    fork_source_file?: string | null;
+    /** Immutable review-companion binding. Undefined for ordinary nodes. */
+    review_binding?: ReviewBinding | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passive_default?: boolean;
+    /** The pi session id for `--session <id>` revival. */
+    pi_session_id?: string | null;
+    /** Absolute path to pi's session `.jsonl` file, captured at session_start via
+     *  ctx.sessionManager.getSessionFile(). Preferred over pi_session_id when
+     *  resuming: pi resolves a BARE `--session <id>` relative to the launch cwd
+     *  first (and shows an interactive cross-project "Fork? [y/N]" prompt when the
+     *  revive cwd differs from the session's creation cwd), whereas an absolute
+     *  PATH is opened directly — immune to any cwd discrepancy. Null for older
+     *  nodes booted before this field existed → revive falls back to the bare id. */
+    pi_session_file?: string | null;
+    /** True while a cycling (`--crtr-new-cycle`) launch remains unconfirmed. Set
+     *  monotonically by reviveNode before launch and cleared only by the stophook's
+     *  confirmed `session_start`. While true, reviveNode's locked arbitration
+     *  vetoes every caller's strict-resume preference so a failed cycle cannot
+     *  reopen the old context. */
+    cycle_pending?: boolean | null;
+    /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
+     *  persona's declared default. Durable so it survives a polymorph: every
+     *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
+     *  buildLaunchSpec, while the persona default is recomputed fresh for the
+     *  (possibly new) kind. Null/undefined ⇒ use the persona default. */
+    model_override?: string | null;
+    /** Sticky run isolation, inherited by every descendant at birth. */
+    isolated?: boolean;
+    /** Per-run allow-list; null inherits the full runtime vocabulary. */
+    scopes?: string[] | null;
+    grantee?: string;
+    sub?: string | null;
+    grant_id?: string | null;
+    client_id?: string | null;
+    metadata_json?: string | null;
+    run_id?: string | null;
+    event_cursor?: number | null;
+    last_activity_at?: string | null;
+    usage_json?: string | null;
+    /** The reference that caused this run (`message:<id>`, `request:<id>`, `cron_run:<id>`), set on a run's root from `run.start`; null for a root. */
+    caused_by?: string | null;
+    /** A run root's latest turn error (`run.get` `last_turn_error`), JSON; null once a turn completes without one. */
+    last_turn_error_json?: string | null;
+    deleting_at?: string | null;
+    /** Full pi launch recipe; rewritten on every polymorph. */
+    launch?: LaunchSpec;
+    /** Managed git worktree owned by this node (if any). */
+    managed_worktree?: ManagedWorktree | null;
+}
+/** A node's live runtime state, stored in the WAL-backed `nodes` row. Each
+ *  field is mutated by an atomic single-statement `UPDATE` (setStatus / setIntent /
+ *  setPresence / recordPid+clearPid). The daemon reconciles process and presence
+ *  state from tmux and broker reality. */
+export interface NodeRuntime {
+    /** What the node is doing right now. */
+    status: NodeStatus;
+    /** Why the node last stopped (done | refresh | idle-release). Drives reap-vs-revive.
+     *  Optional on the hydrated view (a fresh construction omits it); the row
+     *  column is always present, defaulting null. */
+    intent?: ExitIntent;
+    frozen_at?: string | null;
+    respawn_failures?: number;
+    respawn_not_before?: string | null;
+    launched_at?: string | null;
+    last_settled_at?: string | null;
+    terminal_reason?: TerminalReason | null;
+    /** Immutable basename of the committed canonical final report, or null. */
+    final_report?: string | null;
+    /** ISO timestamp carried by the committed canonical final report, or null. */
+    finalized_at?: string | null;
+    /** Durable terminal outcome. `outcome_at` is its write-once latch. */
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    /** Absolute wall-clock spawn deadline, or null when unbounded. */
+    deadline_at?: string | null;
+    /** Cumulative input tokens reported by the broker telemetry producer. */
+    telemetry_tokens_in?: number | null;
+    /** Latest live context-window token gauge reported by the broker. */
+    telemetry_context_tokens?: number | null;
+    /** Latest tool summary reported by the broker. */
+    telemetry_last_activity?: string | null;
+    /** Timestamp of the latest broker telemetry update. */
+    telemetry_updated_at?: string | null;
+    /** OS pid of the live broker process, recorded on boot (stophook session_start).
+     *  The daemon's authoritative liveness signal — every node is a detached broker,
+     *  so `isPidAlive(pi_pid)` is the sole liveness check. Cleared to null by
+     *  reviveNode until the fresh broker re-records it, so the relaunch gap reads as
+     *  a dead pid (guarded by the daemon's revive grace, not a double-spawn). */
+    pi_pid?: number | null;
+    /** Stable process-identity fingerprint (`pid.ts`'s `composeIdentity`) captured
+     *  at the SAME moment `pi_pid` is recorded (`recordPid`) — the LAUNCH-time
+     *  baseline `headlessBrokerHost.teardown()` compares `pi_pid`'s CURRENT
+     *  identity against before signaling anything:
+     *  a mismatch proves the OS has already recycled `pi_pid` for an unrelated
+     *  process since this node launched it, and teardown must refuse to signal
+     *  that stranger. `null` for a node booted before this field existed, or if
+     *  the launch-time identity capture itself failed (fail-open — no baseline
+     *  means no guard, not a false mismatch). Cleared to null alongside `pi_pid`
+     *  by `clearPid` and the boot-liveness sweep (a new boot invalidates both). */
+    pi_pid_identity?: string | null;
+    /** Presence: the tmux session (its root's home) and window this node renders
+     *  in while active. Cleared when the node goes done/dead and its window closes.
+     *  The row IS the presence registry (one atomic setPresence per move).
+     *  v3: a DERIVED CACHE of `pane`'s current location — reconciled from the pane,
+     *  never trusted when a user move could have desynced them. */
+    tmux_session?: string | null;
+    window?: string | null;
+    /** LOCATION's authoritative handle — the durable tmux `%pane_id` this node's
+     *  pane is anchored on. tmux preserves it across `move-pane`/`join-pane`/
+     *  `break-pane` and window renumbering, so `window`/`tmux_session` above are a
+     *  cache reconciled from it and pane-existence is the liveness probe. A
+     *  not-focused + not-generating node has `pane = null` (no pane). Authoritative
+     *  in the row exactly like `window`/`tmux_session` — a RUNTIME field, NOT meta
+     *  identity — written by the one atomic `setPresence` UPDATE. */
+    pane?: string | null;
+    /** Active fault projected from SQL recovery state; stale daemon provider faults are suppressed. */
+    fault?: import('../fault-classifier.js').Fault | null;
+    /** True only while the live execution has an open turn and its PID is alive. */
+    streaming?: boolean;
+}
+/** The hydrated node view `getNode()` returns: durable configuration and live
+ *  runtime from SQL, with session and worktree state from their named stores.
+ *  It retains the historical `NodeMeta` name for existing callers. */
+export type NodeMeta = NodeIdentity & NodeRuntime;
+/** The queryable projection of a node's SQL configuration and runtime state. */
+export interface NodeRow {
+    node_id: string;
+    name: string;
+    /** The pi-generated first-task description; see NodeIdentity.description.
+     *  Absent for a node not yet named — the column's NULL is mapped to undefined
+     *  at `rowFrom` so identity, row, and DTO all spell "unnamed" the same way. */
+    description?: string;
+    /** Relaunch count; see NodeIdentity.cycles. Absent on a row written before
+     *  this column. */
+    cycles?: number;
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    cwd: string;
+    /** Which HOST launches + supervises this node; see NodeIdentity.host_kind. */
+    host_kind: 'tmux' | 'broker' | null;
+    /** The profile this node runs under; see NodeIdentity.profile_id. NULL only
+     *  for historical root/no-profile rows. */
+    profile_id: string | null;
+    /** Sticky run isolation, inherited by every descendant at birth. */
+    isolated: boolean;
+    /** Per-run allow-list; null inherits the full runtime vocabulary. */
+    scopes: string[] | null;
+    grantee?: string;
+    sub?: string | null;
+    grant_id?: string | null;
+    client_id?: string | null;
+    metadata_json?: string | null;
+    run_id?: string | null;
+    event_cursor?: number | null;
+    last_activity_at?: string | null;
+    usage_json?: string | null;
+    /** The reference that caused this run (`message:<id>`, `request:<id>`, `cron_run:<id>`), set on a run's root from `run.start`; null for a root. */
+    caused_by?: string | null;
+    /** A run root's latest turn error (`run.get` `last_turn_error`), JSON; null once a turn completes without one. */
+    last_turn_error_json?: string | null;
+    deleting_at?: string | null;
+    parent: string | null;
+    created: string;
+    /** Authoritative runtime columns (see NodeRuntime). */
+    intent: ExitIntent;
+    frozen_at?: string | null;
+    respawn_failures?: number;
+    respawn_not_before?: string | null;
+    launched_at?: string | null;
+    last_settled_at?: string | null;
+    terminal_reason?: TerminalReason | null;
+    final_report?: string | null;
+    finalized_at?: string | null;
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    deadline_at?: string | null;
+    /** Cumulative input tokens reported by the broker telemetry producer. */
+    telemetry_tokens_in?: number | null;
+    /** Latest live context-window token gauge reported by the broker. */
+    telemetry_context_tokens?: number | null;
+    /** Latest tool summary reported by the broker. */
+    telemetry_last_activity?: string | null;
+    /** Timestamp of the latest broker telemetry update. */
+    telemetry_updated_at?: string | null;
+    pi_pid: number | null;
+    /** See `NodeRuntime.pi_pid_identity`. */
+    pi_pid_identity: string | null;
+    window: string | null;
+    tmux_session: string | null;
+    /** The durable LOCATION handle (the tmux `%pane_id`); see NodeRuntime.pane. */
+    pane: string | null;
+    /** Active fault projected from SQL recovery state; stale daemon provider faults are suppressed. */
+    fault?: import('../fault-classifier.js').Fault | null;
+    /** True only while the live execution has an open turn and its PID is alive. */
+    streaming?: boolean;
+}
+/** A FOCUS row as stored in the `focuses` table (canvas.db, migration v6): one
+ *  durable on-screen viewport the user looks at, bound to one node. Plural —
+ *  many focuses live at once across windows and sessions (the plural
+ *  generalization of the old single focus pointer). Anchored on the durable tmux
+ *  `%pane_id`; `session` is a derived cache reconciled from the pane. `node_id`
+ *  is UNIQUE — a node occupies at most one focus (Q5). */
+export interface FocusRow {
+    /** Stable internal id for the viewport (the table's primary key). */
+    focus_id: string;
+    /** The durable `%pane_id` realizing the focus, or null before it is placed. */
+    pane: string | null;
+    /** Derived cache of the user session the pane lives in (reconciled from pane). */
+    session: string | null;
+    /** The node this focus shows. UNIQUE → a node occupies ≤1 focus. */
+    node_id: string;
+}
+/** A subscription as seen from one endpoint. */
+export interface SubscriptionRef {
+    /** The node id at the other end of the edge. */
+    node_id: string;
+    active: boolean;
+    created: string;
+}

package/dist/core/canvas/types.js

@@ -0,0 +1,6 @@
+// The canvas vocabulary — the node + edge model the whole runtime hangs on.
+//
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the node graph and
+// runtime state. Each node directory holds only its artifacts.
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export const OUTCOME_PAYLOAD_MAX_BYTES = 64 * 1024;

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

@@ -0,0 +1,39 @@
+import { type CanvasDb } from './db.js';
+export interface ControllerWait {
+    waitId: string;
+    nodeId: string;
+    controllerId: string;
+    generation: number;
+    createdAt: number;
+    satisfiedAt: number | null;
+}
+/** Replace a node's live controller wait while retaining the prior row as history. */
+export declare function armControllerWait(nodeId: string, controllerId: string, now?: number): Promise<ControllerWait>;
+export declare function readControllerWait(nodeId: string): Promise<ControllerWait | null>;
+/** Clear only the wait that was observed for this sender; a rearm wins a race. */
+export declare function settleMatchingControllerWait(nodeId: string, senderId: string | null, now: number, db?: CanvasDb): Promise<boolean>;
+/** Clear a matching wait only if its controller is no longer active or idle. */
+export declare function settleDeadControllerWait(nodeId: string, controllerId: string, now: number, db?: CanvasDb): Promise<boolean>;
+/** Live rows drive controller-death reconciliation without relying on the retired node columns. */
+export declare function liveControllerWaits(): Promise<ControllerWait[]>;
+/** A node's live wait on a watched object, ended by the event its kind declares `endsWait` (`waits`, kind `object`). */
+export interface ObjectWait {
+    waitId: string;
+    nodeId: string;
+    objectId: string;
+    createdAt: number;
+}
+/** Arm a node's wait on an object, inside the caller's write transaction; an existing live wait on the same object stands. */
+export declare function armObjectWait(db: CanvasDb, nodeId: string, objectId: string, now?: number): Promise<void>;
+/** Settle every live wait on `objectId` (its ending event was published), or only `nodeId`'s (it stopped watching). */
+export declare function settleObjectWaits(db: CanvasDb, objectId: string, nodeId?: string | null, now?: number): Promise<number>;
+/** A node that ended waits on nothing: settle all of its live object waits. */
+export declare function settleNodeObjectWaits(db: CanvasDb, nodeId: string, now?: number): Promise<number>;
+/** Every node's live object waits with the watched object's kind and name, for the roster. A deleted object
+ *  settles its waits on publish, so none should dangle; a wait whose object row is gone is skipped rather than shown nameless. */
+export declare function liveObjectWaitsNamed(db?: CanvasDb): Promise<Array<ObjectWait & {
+    objectType: string;
+    objectName: string;
+}>>;
+export declare function hasLiveObjectWait(nodeId: string): Promise<boolean>;
+export declare function hasLiveControllerWait(nodeId: string): Promise<boolean>;

package/dist/core/canvas/waits.js

@@ -0,0 +1,104 @@
+import { randomBytes } from 'node:crypto';
+import { withCanvasWrite, openDb } from './db.js';
+function waitFrom(row) {
+    if (row.kind !== 'controller')
+        throw new Error(`wait ${row.wait_id} is not a controller wait`);
+    return {
+        waitId: row.wait_id,
+        nodeId: row.node_id,
+        controllerId: row.target_id,
+        generation: row.generation,
+        createdAt: row.created_at,
+        satisfiedAt: row.satisfied_at,
+    };
+}
+function newWaitId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (id === '00000000000000000000000000000000');
+    return id;
+}
+/** Replace a node's live controller wait while retaining the prior row as history. */
+export async function armControllerWait(nodeId, controllerId, now = Date.now()) {
+    return await withCanvasWrite(async (db) => {
+        await db.prepare("UPDATE waits SET satisfied_at = ? WHERE node_id = ? AND kind = 'controller' AND satisfied_at IS NULL").run(now, nodeId);
+        const generation = Number((await db.prepare("SELECT COALESCE(MAX(generation), 0) AS generation FROM waits WHERE node_id = ? AND kind = 'controller'").get(nodeId)).generation) + 1;
+        const wait = {
+            wait_id: newWaitId(),
+            node_id: nodeId,
+            kind: 'controller',
+            target_id: controllerId,
+            generation,
+            created_at: now,
+            satisfied_at: null,
+        };
+        await db.prepare(`INSERT INTO waits (wait_id, node_id, kind, target_id, generation, created_at, satisfied_at)
+       VALUES (?, ?, 'controller', ?, ?, ?, NULL)`).run(wait.wait_id, wait.node_id, wait.target_id, wait.generation, wait.created_at);
+        return waitFrom(wait);
+    });
+}
+export async function readControllerWait(nodeId) {
+    const row = await (await openDb()).prepare("SELECT * FROM waits WHERE node_id = ? AND kind = 'controller' AND satisfied_at IS NULL").get(nodeId);
+    return row === undefined ? null : waitFrom(row);
+}
+/** Clear only the wait that was observed for this sender; a rearm wins a race. */
+export async function settleMatchingControllerWait(nodeId, senderId, now, db) {
+    db ??= await openDb();
+    if (senderId === null)
+        return false;
+    const row = await db.prepare("SELECT wait_id, generation FROM waits WHERE node_id = ? AND kind = 'controller' AND target_id = ? AND satisfied_at IS NULL").get(nodeId, senderId);
+    if (row === undefined)
+        return false;
+    return Number((await db.prepare('UPDATE waits SET satisfied_at = ? WHERE wait_id = ? AND generation = ? AND satisfied_at IS NULL').run(now, row.wait_id, row.generation)).changes) === 1;
+}
+/** Clear a matching wait only if its controller is no longer active or idle. */
+export async function settleDeadControllerWait(nodeId, controllerId, now, db) {
+    db ??= await openDb();
+    const row = await db.prepare(`SELECT w.wait_id, w.generation, target.status AS controller_status
+       FROM waits w LEFT JOIN nodes target ON target.node_id = w.target_id
+      WHERE w.node_id = ? AND w.kind = 'controller' AND w.target_id = ? AND w.satisfied_at IS NULL`).get(nodeId, controllerId);
+    if (row === undefined || row.controller_status === 'active' || row.controller_status === 'idle')
+        return false;
+    return Number((await db.prepare('UPDATE waits SET satisfied_at = ? WHERE wait_id = ? AND generation = ? AND satisfied_at IS NULL').run(now, row.wait_id, row.generation)).changes) === 1;
+}
+/** Live rows drive controller-death reconciliation without relying on the retired node columns. */
+export async function liveControllerWaits() {
+    return (await (await openDb()).prepare("SELECT * FROM waits WHERE kind = 'controller' AND satisfied_at IS NULL").all()).map(waitFrom);
+}
+/** Arm a node's wait on an object, inside the caller's write transaction; an existing live wait on the same object stands. */
+export async function armObjectWait(db, nodeId, objectId, now = Date.now()) {
+    await db.prepare(`INSERT INTO waits (wait_id, node_id, kind, target_id, generation, created_at, satisfied_at)
+     SELECT ?, ?, 'object', ?, 1, ?, NULL
+     WHERE NOT EXISTS (SELECT 1 FROM waits WHERE node_id = ? AND kind = 'object' AND target_id = ? AND satisfied_at IS NULL)`).run(newWaitId(), nodeId, objectId, now, nodeId, objectId);
+}
+/** Settle every live wait on `objectId` (its ending event was published), or only `nodeId`'s (it stopped watching). */
+export async function settleObjectWaits(db, objectId, nodeId = null, now = Date.now()) {
+    return Number(nodeId === null
+        ? (await db.prepare("UPDATE waits SET satisfied_at = ? WHERE kind = 'object' AND target_id = ? AND satisfied_at IS NULL").run(now, objectId)).changes
+        : (await db.prepare("UPDATE waits SET satisfied_at = ? WHERE kind = 'object' AND target_id = ? AND node_id = ? AND satisfied_at IS NULL").run(now, objectId, nodeId)).changes);
+}
+/** A node that ended waits on nothing: settle all of its live object waits. */
+export async function settleNodeObjectWaits(db, nodeId, now = Date.now()) {
+    return Number((await db.prepare("UPDATE waits SET satisfied_at = ? WHERE kind = 'object' AND node_id = ? AND satisfied_at IS NULL").run(now, nodeId)).changes);
+}
+/** Every node's live object waits with the watched object's kind and name, for the roster. A deleted object
+ *  settles its waits on publish, so none should dangle; a wait whose object row is gone is skipped rather than shown nameless. */
+export async function liveObjectWaitsNamed(db) {
+    db ??= await openDb();
+    return (await db.prepare(`SELECT w.wait_id, w.node_id, w.target_id, w.created_at, o.type AS object_type, o.name AS object_name
+       FROM waits w JOIN objects o ON o.id = w.target_id
+      WHERE w.kind = 'object' AND w.satisfied_at IS NULL AND o.deleted_at IS NULL
+      ORDER BY w.node_id, w.created_at, w.seq`)
+        .all())
+        .map((row) => ({ waitId: row.wait_id, nodeId: row.node_id, objectId: row.target_id, createdAt: row.created_at, objectType: row.object_type, objectName: row.object_name }));
+}
+export async function hasLiveObjectWait(nodeId) {
+    return await (await openDb()).prepare("SELECT 1 FROM waits WHERE node_id = ? AND kind = 'object' AND satisfied_at IS NULL LIMIT 1").get(nodeId) !== undefined;
+}
+export async function hasLiveControllerWait(nodeId) {
+    const row = await (await openDb()).prepare(`SELECT 1 FROM waits w JOIN nodes target ON target.node_id = w.target_id
+      WHERE w.node_id = ? AND w.kind = 'controller' AND w.satisfied_at IS NULL
+        AND target.status IN ('active', 'idle') LIMIT 1`).get(nodeId);
+    return row !== undefined;
+}

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

@@ -0,0 +1,41 @@
+import { type CanvasDb } from './db.js';
+import type { ManagedWorktree, ManagedWorktreeObservation } from './types.js';
+export declare function worktreeFromRow(row: Record<string, unknown> | undefined): ManagedWorktree | null;
+export declare function readWorktree(nodeId: string): Promise<ManagedWorktree | null>;
+export declare function openWorktree(nodeId: string, worktree: ManagedWorktree, db?: CanvasDb): Promise<void>;
+export declare function closeWorktree(nodeId: string, input: {
+    cleanup: 'pending' | 'complete';
+    closedAt: string;
+}): Promise<void>;
+/** Complete a worktree close and repoint the node in the same SQL transaction.
+ * A close invalidates the active transcript because Pi remains in the old
+ * checkout; the next launch starts from the durable base checkout. */
+export declare function closeWorktreeAndRepoint(nodeId: string, input: {
+    cwd: string;
+    cleanup: 'pending' | 'complete';
+    closedAt: string;
+    unbindSession: boolean;
+}): Promise<void>;
+export declare function abandonWorktree(nodeId: string, abandoned: NonNullable<ManagedWorktree['abandoned']>): Promise<void>;
+export declare function abandonWorktreeAndRepoint(nodeId: string, input: {
+    cwd: string;
+    abandoned: NonNullable<ManagedWorktree['abandoned']>;
+}): Promise<void>;
+export declare function recordLandIntent(nodeId: string, intent: NonNullable<ManagedWorktree['land_intent']>): Promise<void>;
+export declare function recordDisposalGrant(nodeId: string, disposal: NonNullable<ManagedWorktree['disposal']>): Promise<void>;
+export declare function recordSweepAttempt(nodeId: string, input: {
+    reason: string;
+    detail?: string;
+    observed: ManagedWorktreeObservation;
+    attempts: number;
+    lastAttemptAt: string;
+    nextAttemptAt: string;
+    quarantined: boolean;
+}): Promise<void>;
+export declare function completeCleanup(nodeId: string): Promise<void>;
+export declare function hasUnreconciledWorktree(nodeId: string): Promise<boolean>;
+export declare function sweepCandidates(now: string): Promise<string[]>;
+export declare function quarantinedWorktrees(): Promise<Array<{
+    nodeId: string;
+    worktree: ManagedWorktree;
+}>>;