@north-light/cli 0.0.0 → 0.3.414

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

@@ -0,0 +1,14 @@
+export interface Telemetry {
+    tokens_in?: number;
+    tokens_out?: number;
+    /** Live context-window size from the last turn_end (pi's getContextUsage). */
+    context_tokens?: number;
+    model?: string;
+    updated_at?: string;
+}
+/** Read a node's telemetry record. Missing/corrupt → {}. Never throws. */
+export declare function readTelemetry(nodeId: string): Telemetry;
+/** The node's current context-window size in tokens, or null when unknown.
+ *  Prefers the live `context_tokens` gauge; falls back to cumulative
+ *  `tokens_in` (the dashboard's coarse proxy) only when no live gauge exists. */
+export declare function readContextTokens(nodeId: string): number | null;

package/dist/core/canvas/telemetry.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var r=(e,t)=>n(e,"name",{value:t,configurable:!0});import{existsSync as o,readFileSync as i}from"node:fs";import{join as u}from"node:path";import{jobDir as f}from"./paths.js";function s(e){const t=u(f(e),"telemetry.json");if(!o(t))return{};try{return JSON.parse(i(t,"utf8"))}catch{return{}}}r(s,"readTelemetry");function a(e){const t=s(e);return typeof t.context_tokens=="number"?t.context_tokens:typeof t.tokens_in=="number"?t.tokens_in:null}r(a,"readContextTokens");export{a as readContextTokens,s as readTelemetry};

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

@@ -0,0 +1,29 @@
+import type { SubscriptionRef } from './types.js';
+/** One tree edge between two nodes: `from_id` watches `to_id`. */
+export interface RosterEdge {
+    from_id: string;
+    to_id: string;
+    active: boolean;
+    created: string;
+}
+/** Every in-tree node→node watch, oldest first — the roster's topology half. */
+export declare function rosterEdges(): RosterEdge[];
+/** `subscriber` asks to watch `publisher` (an `ask` watch, in the tree). Re-running sets the
+ *  pair's tree subscriptions active or passive (`{"3":"next-turn"}`). */
+export declare function subscribe(subscriber: string, publisher: string, active?: boolean): void;
+/** Drop the pair's tree subscriptions; a reading or message watch on the same pair survives. */
+export declare function unsubscribe(subscriber: string, publisher: string): void;
+/** Rewrite the listening configuration of the pair's tree subscriptions: NULL (the watcher's
+ *  default) for active, `{"3":"next-turn"}` for passive. */
+export declare function setSubscriptionActive(subscriber: string, publisher: string, active: boolean): void;
+/** Who watches `publisher` in the tree — the targets a push fans out to. */
+export declare function subscribersOf(publisher: string): SubscriptionRef[];
+/** The nodes `subscriber` watches in the tree — its reports. */
+export declare function subscriptionsOf(subscriber: string): SubscriptionRef[];
+/** Every node below `root` in the tree, excluding root. */
+export declare function view(root: string): string[];
+/** Stop-guard primitive: does this node hold an active tree subscription to a live node —
+ *  something that can actually wake it? */
+export declare function hasActiveLiveSubscription(nodeId: string): boolean;
+/** Whether a live node still actively watches this one in the tree — a report this node owes. */
+export declare function hasLiveSubscriber(nodeId: string): boolean;

package/dist/core/canvas/tree.js

@@ -0,0 +1,12 @@
+var S=Object.defineProperty;var i=(o,t)=>S(o,"name",{value:t,configurable:!0});import{prepared as A}from"../sqlite-statements.js";import{openDb as c,withCanvasWrite as u}from"./db.js";import{getById as v,nodeObject as a}from"../graph/objects.js";import{recordWatch as b,unwatch as O,descendants as R,configFromJson as E,configToJson as T}from"../graph/watches.js";import{publish as j}from"../graph/events.js";import{DEFAULT_LISTEN as D}from"../graph/types.js";const y=["spawn","job-start","ask"],h="('spawn','job-start','ask')",I=[{threshold:3,delivery:"next-turn"}];function l(o){const t=o.find(e=>e.threshold<=7);return t!==void 0&&t.delivery!=="next-turn"}i(l,"wakesAtSeven");function d(o,t,...e){const n=o.prepare(`SELECT wo.id AS from_id, oo.id AS to_id, ws.config_json, ws.created_at,
+            wo.listen_json, wn.status AS from_status, onode.status AS to_status
+       FROM watches w
+       JOIN objects wo ON wo.rowid = w.watcher AND wo.type = 'node'
+       JOIN objects oo ON oo.rowid = w.object AND oo.type = 'node'
+       JOIN watch_subscriptions ws ON ws.watch = w.rowid AND ws.started_by IN ${h}
+       JOIN nodes wn ON wn.node_id = wo.id
+       JOIN nodes onode ON onode.node_id = oo.id
+      WHERE w.in_tree = 1 ${t}
+      ORDER BY ws.created_at, ws.rowid`).all(...e),r=new Map;for(const s of n){const w=s.config_json,f=s.listen_json,_=w!=null?E(w):f!=null?E(f):D,p=`${s.from_id}\0${s.to_id}`,m=r.get(p);if(m){m.active||=l(_);continue}r.set(p,{from_id:s.from_id,to_id:s.to_id,active:l(_),created:s.created_at,from_status:s.from_status??null,to_status:s.to_status??null})}return[...r.values()]}i(d,"treeEdges");function C(){return d(c(),"").map(({from_id:o,to_id:t,active:e,created:n})=>({from_id:o,to_id:t,active:e,created:n}))}i(C,"rosterEdges");function H(o,t,e=!0){u(n=>{const r=a(n,o),s=a(n,t);b(n,r,s,"ask"),g(o,t,e),j(n,{event:"watched",object:s,actor:r,attrs:{}})})}i(H,"subscribe");function M(o,t){u(e=>{const n=a(e,o),r=a(e,t);for(const s of y)O(e,n,r,{startedBy:s})})}i(M,"unsubscribe");function g(o,t,e){u(n=>{n.prepare(`UPDATE watch_subscriptions SET config_json = ?
+        WHERE started_by IN ${h}
+          AND watch IN (SELECT rowid FROM watches WHERE watcher = ? AND object = ?)`).run(e?null:T(I),a(n,o).rowid,a(n,t).rowid)})}i(g,"setSubscriptionActive");function B(o){return d(c(),"AND oo.id = ?",o).map(t=>({node_id:t.from_id,active:t.active,created:t.created}))}i(B,"subscribersOf");function P(o){return d(c(),"AND wo.id = ?",o).map(t=>({node_id:t.to_id,active:t.active,created:t.created}))}i(P,"subscriptionsOf");function U(o){const t=c(),e=v(t,o);if(e?.type!=="node")return[];const n=A(t,"SELECT 1 FROM nodes WHERE node_id = ?");return R(t,e).map(r=>r.id).filter(r=>n.get(r)!==void 0)}i(U,"view");const N=new Set(["active","idle"]);function V(o){return d(c(),"AND wo.id = ?",o).some(t=>t.active&&N.has(t.to_status??""))}i(V,"hasActiveLiveSubscription");function Q(o){return d(c(),"AND oo.id = ?",o).some(t=>t.active&&N.has(t.from_status??""))}i(Q,"hasLiveSubscriber");export{V as hasActiveLiveSubscription,Q as hasLiveSubscriber,C as rosterEdges,g as setSubscriptionActive,H as subscribe,B as subscribersOf,P as subscriptionsOf,M as unsubscribe,U as view};

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

@@ -0,0 +1,454 @@
+/** 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';
+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>;
+}
+/** 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;
+    /** 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;
+    /** Controller whose next inbox delivery permits this terminal node to sleep.
+     * Mutable durable runtime state: ancestry never implies a wait. */
+    waiting_for?: string | null;
+    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;
+    /** 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;
+    waiting_for: string | null;
+    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 @@
+const A=65536;export{A as OUTCOME_PAYLOAD_MAX_BYTES};

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

@@ -0,0 +1,18 @@
+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): ControllerWait;
+export declare function readControllerWait(nodeId: string): 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?: import("node:sqlite").DatabaseSync): 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?: import("node:sqlite").DatabaseSync): boolean;
+/** Live rows drive controller-death reconciliation without relying on the retired node columns. */
+export declare function liveControllerWaits(): ControllerWait[];
+export declare function hasLiveControllerWait(nodeId: string): boolean;

package/dist/core/canvas/waits.js

@@ -0,0 +1,6 @@
+var _=Object.defineProperty;var r=(t,e)=>_(t,"name",{value:e,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{randomBytes as E}from"node:crypto";import{openDb as s,withCanvasWrite as u}from"./db.js";function l(t){return{waitId:t.wait_id,nodeId:t.node_id,controllerId:t.target_id,generation:t.generation,createdAt:t.created_at,satisfiedAt:t.satisfied_at}}r(l,"waitFrom");function w(){let t;do t=E(16).toString("hex");while(t==="00000000000000000000000000000000");return t}r(w,"newWaitId");function L(t,e,o=Date.now()){return u(n=>{a(n,"UPDATE waits SET satisfied_at = ? WHERE node_id = ? AND satisfied_at IS NULL").run(o,t);const i=Number(a(n,"SELECT COALESCE(MAX(generation), 0) AS generation FROM waits WHERE node_id = ?").get(t).generation)+1,d={wait_id:w(),node_id:t,kind:"controller",target_id:e,generation:i,created_at:o,satisfied_at:null};return a(n,`INSERT INTO waits (wait_id, node_id, kind, target_id, generation, created_at, satisfied_at)
+       VALUES (?, ?, 'controller', ?, ?, ?, NULL)`).run(d.wait_id,d.node_id,d.target_id,d.generation,d.created_at),l(d)})}r(L,"armControllerWait");function A(t){const e=a(s(),"SELECT * FROM waits WHERE node_id = ? AND kind = 'controller' AND satisfied_at IS NULL").get(t);return e===void 0?null:l(e)}r(A,"readControllerWait");function S(t,e,o,n=s()){if(e===null)return!1;const i=a(n,"SELECT wait_id, generation FROM waits WHERE node_id = ? AND kind = 'controller' AND target_id = ? AND satisfied_at IS NULL").get(t,e);return i===void 0?!1:Number(a(n,"UPDATE waits SET satisfied_at = ? WHERE wait_id = ? AND generation = ? AND satisfied_at IS NULL").run(o,i.wait_id,i.generation).changes)===1}r(S,"settleMatchingControllerWait");function D(t,e,o,n=s()){const i=a(n,`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(t,e);return i===void 0||i.controller_status==="active"||i.controller_status==="idle"?!1:Number(a(n,"UPDATE waits SET satisfied_at = ? WHERE wait_id = ? AND generation = ? AND satisfied_at IS NULL").run(o,i.wait_id,i.generation).changes)===1}r(D,"settleDeadControllerWait");function W(){return a(s(),"SELECT * FROM waits WHERE kind = 'controller' AND satisfied_at IS NULL").all().map(l)}r(W,"liveControllerWaits");function I(t){return a(s(),`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(t)!==void 0}r(I,"hasLiveControllerWait");export{L as armControllerWait,I as hasLiveControllerWait,W as liveControllerWaits,A as readControllerWait,D as settleDeadControllerWait,S as settleMatchingControllerWait};

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

@@ -0,0 +1,41 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { ManagedWorktree, ManagedWorktreeObservation } from './types.js';
+export declare function worktreeFromRow(row: Record<string, unknown> | undefined): ManagedWorktree | null;
+export declare function readWorktree(nodeId: string): ManagedWorktree | null;
+export declare function openWorktree(nodeId: string, worktree: ManagedWorktree, db?: DatabaseSync): void;
+export declare function closeWorktree(nodeId: string, input: {
+    cleanup: 'pending' | 'complete';
+    closedAt: string;
+}): 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;
+}): void;
+export declare function abandonWorktree(nodeId: string, abandoned: NonNullable<ManagedWorktree['abandoned']>): void;
+export declare function abandonWorktreeAndRepoint(nodeId: string, input: {
+    cwd: string;
+    abandoned: NonNullable<ManagedWorktree['abandoned']>;
+}): void;
+export declare function recordLandIntent(nodeId: string, intent: NonNullable<ManagedWorktree['land_intent']>): void;
+export declare function recordDisposalGrant(nodeId: string, disposal: NonNullable<ManagedWorktree['disposal']>): void;
+export declare function recordSweepAttempt(nodeId: string, input: {
+    reason: string;
+    detail?: string;
+    observed: ManagedWorktreeObservation;
+    attempts: number;
+    lastAttemptAt: string;
+    nextAttemptAt: string;
+    quarantined: boolean;
+}): void;
+export declare function completeCleanup(nodeId: string): void;
+export declare function hasUnreconciledWorktree(nodeId: string): boolean;
+export declare function sweepCandidates(now: string): string[];
+export declare function quarantinedWorktrees(): Array<{
+    nodeId: string;
+    worktree: ManagedWorktree;
+}>;

package/dist/core/canvas/worktrees.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var n=(e,t)=>l(e,"name",{value:t,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{openDb as s,withCanvasWrite as p}from"./db.js";function _(e){const t=JSON.stringify(e);if(t===void 0)throw new TypeError("worktree value must be JSON-serializable");return t}n(_,"json");function d(e){if(typeof e=="string")return JSON.parse(e)}n(d,"parse");function i(e){if(e===void 0)return null;const t=d(e.sweep_observed_json),o=e.attempts,r=t===void 0?void 0:{reason:e.sweep_reason,...e.sweep_detail===null?{}:{detail:e.sweep_detail},observed:t,attempts:o,last_attempt:e.sweep_last_at,next_attempt:e.next_attempt_at,...e.quarantined===1?{quarantined:!0}:{}};return{state:e.state,...e.cleanup_state===null?{}:{cleanup:e.cleanup_state},path:e.path,branch:e.branch,repo_root:e.repo_root,base_ref:e.base_ref,base_sha:e.base_sha,created:e.created_at,...e.closed_at===null?{}:{closed:e.closed_at},...d(e.abandoned_json)===void 0?{}:{abandoned:d(e.abandoned_json)},...d(e.land_intent_json)===void 0?{}:{land_intent:d(e.land_intent_json)},...r===void 0?{}:{sweep:r},...d(e.disposal_json)===void 0?{}:{disposal:d(e.disposal_json)}}}n(i,"worktreeFromRow");function c(e){return i(a(s(),"SELECT * FROM worktrees WHERE node_id = ?").get(e))}n(c,"readWorktree");function N(e,t,o=s()){a(o,"INSERT INTO worktrees (node_id, state, cleanup_state, path, branch, repo_root, base_ref, base_sha, created_at, closed_at, next_attempt_at, attempts, quarantined, sweep_reason, sweep_detail, sweep_last_at, sweep_observed_json, abandoned_json, land_intent_json, disposal_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL)").run(e,t.state,t.cleanup??null,t.path,t.branch,t.repo_root,t.base_ref,t.base_sha,t.created,t.closed??null)}n(N,"openWorktree");function U(e,t){a(s(),"UPDATE worktrees SET state = 'closed', cleanup_state = ?, closed_at = ?, land_intent_json = NULL, sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(t.cleanup,t.closedAt,e)}n(U,"closeWorktree");function f(e,t){p(o=>{a(o,"UPDATE nodes SET cwd = ? WHERE node_id = ?").run(t.cwd,e),t.unbindSession&&a(o,"UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL").run(t.closedAt,e),a(o,"UPDATE worktrees SET state = 'closed', cleanup_state = ?, closed_at = ?, land_intent_json = NULL, sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(t.cleanup,t.closedAt,e)})}n(f,"closeWorktreeAndRepoint");function b(e,t){a(s(),"UPDATE worktrees SET state = 'abandoned', abandoned_json = ? WHERE node_id = ? AND abandoned_json IS NULL").run(_(t),e)}n(b,"abandonWorktree");function A(e,t){p(o=>{a(o,"UPDATE nodes SET cwd = ? WHERE node_id = ?").run(t.cwd,e),a(o,"UPDATE worktrees SET state = 'abandoned', abandoned_json = ? WHERE node_id = ? AND abandoned_json IS NULL").run(_(t.abandoned),e)})}n(A,"abandonWorktreeAndRepoint");function m(e,t){a(s(),"UPDATE worktrees SET land_intent_json = ? WHERE node_id = ? AND land_intent_json IS NULL").run(_(t),e)}n(m,"recordLandIntent");function w(e,t){a(s(),"UPDATE worktrees SET disposal_json = ? WHERE node_id = ? AND disposal_json IS NULL").run(_(t),e)}n(w,"recordDisposalGrant");function R(e,t){a(s(),"UPDATE worktrees SET sweep_reason = ?, sweep_detail = ?, sweep_observed_json = ?, attempts = ?, sweep_last_at = ?, next_attempt_at = ?, quarantined = ? WHERE node_id = ?").run(t.reason,t.detail??null,_(t.observed),t.attempts,t.lastAttemptAt,t.nextAttemptAt,t.quarantined?1:0,e)}n(R,"recordSweepAttempt");function S(e){a(s(),"UPDATE worktrees SET state = 'closed', cleanup_state = 'complete', sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(e)}n(S,"completeCleanup");function T(e){return a(s(),"SELECT 1 FROM worktrees WHERE node_id = ? AND state != 'abandoned' AND (state = 'open' OR cleanup_state IS NULL OR cleanup_state != 'complete')").get(e)!==void 0}n(T,"hasUnreconciledWorktree");function D(e){return a(s(),"SELECT w.node_id FROM worktrees w JOIN nodes n ON n.node_id = w.node_id WHERE n.status IN ('done', 'dead', 'canceled') AND n.frozen_at IS NULL 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)) AND (w.next_attempt_at IS NULL OR w.next_attempt_at <= ?) ORDER BY w.next_attempt_at, w.node_id").all(e).map(({node_id:t})=>t)}n(D,"sweepCandidates");function j(){return a(s(),"SELECT node_id FROM worktrees WHERE quarantined = 1 ORDER BY sweep_last_at").all().flatMap(({node_id:e})=>{const t=c(e);return t===null?[]:[{nodeId:e,worktree:t}]})}n(j,"quarantinedWorktrees");export{b as abandonWorktree,A as abandonWorktreeAndRepoint,U as closeWorktree,f as closeWorktreeAndRepoint,S as completeCleanup,T as hasUnreconciledWorktree,N as openWorktree,j as quarantinedWorktrees,c as readWorktree,w as recordDisposalGrant,m as recordLandIntent,R as recordSweepAttempt,D as sweepCandidates,i as worktreeFromRow};

package/dist/core/clipboard-text.d.ts

@@ -0,0 +1,11 @@
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export declare function writeClipboardText(text: string): boolean;
+/** Write `text` to the system clipboard AND, inside tmux, to the tmux paste
+ *  buffer via `tmux load-buffer -w -` (which makes tmux emit OSC 52 outward on
+ *  the app's behalf). Never emits OSC 52 from this process. Never throws.
+ *  Returns which operations succeeded. */
+export declare function writeClipboardTextEverywhere(text: string): {
+    system: boolean;
+    tmux: boolean;
+};

package/dist/core/clipboard-text.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(t,e)=>i(t,"name",{value:e,configurable:!0});import{spawnSync as s}from"node:child_process";const c=3e3;function u(){if(process.platform==="darwin")return[["pbcopy",[]]];const t=!!process.env.WAYLAND_DISPLAY||process.env.XDG_SESSION_TYPE==="wayland",e=["xclip",["-selection","clipboard"]],r=["wl-copy",[]];return t?[r,e]:[e,r]}n(u,"writers");function p(t){for(const[e,r]of u()){const o=s(e,r,{input:t,timeout:c,encoding:"utf-8"});if(o.error){if(o.error.code==="ENOENT")continue;continue}if(o.status===0)return!0}return!1}n(p,"writeClipboardText");function l(t){const e=p(t);let r=!1;if(process.env.TMUX!==void 0){const o=s("tmux",["load-buffer","-w","-"],{input:t,timeout:c,encoding:"utf-8"});r=!o.error&&o.status===0}return{system:e,tmux:r}}n(l,"writeClipboardTextEverywhere");export{p as writeClipboardText,l as writeClipboardTextEverywhere};

package/dist/core/command-hooks/artifact.d.ts

@@ -0,0 +1,16 @@
+import type { PluginManifest } from '../../types.js';
+import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface LifecycleDeclarationCandidate {
+    event: string;
+    op: string;
+    index: number;
+}
+export interface HookArtifactValidation {
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
+    issues: HookManifestIssue[];
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export declare function validatePluginHookArtifact(root: string, manifest: Pick<PluginManifest, 'hooks' | 'hookExecutable'>): HookArtifactValidation;