@north-light/cli 0.0.0 → 0.3.413

package/dist/core/bash-jobs.d.ts

@@ -0,0 +1,180 @@
+export interface BashJobPaths {
+    jobId: string;
+    /** The node's agent folder (the parent of its context folder): every job
+     * file resolves beneath it, so a symlink the agent plants is never followed. */
+    root: string;
+    dir: string;
+    cmdSh: string;
+    jobLog: string;
+    jobExit: string;
+    jobRun: string;
+    jobBg: string;
+    jobDone: string;
+    /** Process-group id of the job's detached supervisor, written at spawn. It is
+     * what makes a job stoppable from outside the agent that started it (the
+     * Inspector's cancel) — without it on disk, only the agent's own handoff
+     * notice knows the group to signal. */
+    jobPgid: string;
+    /** Launch-time identity of the detached supervisor, used to refuse a PID that
+     * has since been reused by an unrelated process. */
+    jobPgidIdentity: string;
+    /** Human-readable label supplied with the bash call, when any. */
+    jobPurpose: string;
+    /** Epoch-ms cancel deadline for an AUTO-backgrounded job. Present only when
+     * the valve backgrounded the job on its own; its presence marks the job as
+     * subject to the daemon's claim-or-cancel deadline. Absent for a deliberate
+     * handoff (tmux menu, broker termination), which runs to completion. */
+    jobDeadline: string;
+}
+/** A purpose is display text, never shell input. Keep the file-backed control
+ * plane to one bounded, visible line so old or hand-written job directories
+ * cannot inject control content into terminal or JSON presenters. */
+export declare function normalizeBashJobPurpose(value: unknown): string | null;
+export declare function bashJobsDir(contextDir: string): string;
+/** Whether a job id can safely be used as one path segment. Generated ids are
+ * numeric epoch prefixes plus a hex suffix; this broader safe alphabet keeps
+ * older file-backed ids readable without allowing path or request delimiters. */
+export declare function isSafeBashJobId(jobId: string): boolean;
+export declare function bashJobPaths(contextDir: string, jobId: string): BashJobPaths;
+/** The job's supervisor process group, or undefined for a job started before
+ * pgid was persisted (or a partially-written dir). */
+export declare function readJobPgid(contextDir: string, jobId: string): number | undefined;
+/** Launch-time identity of the supervisor. Missing for jobs created before
+ * process-identity persistence, which are deliberately not safe to signal. */
+export declare function readJobPgidIdentity(contextDir: string, jobId: string): string | undefined;
+/** The optional human-readable job label. Jobs created before labels existed
+ * have no file and deliberately project null. */
+export declare function readJobPurpose(contextDir: string, jobId: string): string | null;
+/** Scheduler niceness every command a node runs is started with. Agent work —
+ * builds, test suites, typechecks — sits below the daemon, the brokers, the
+ * viewers, and the person's own shell, so a fan-out of release builds cannot
+ * starve them: the scheduler only honors this under contention and it costs
+ * nothing on an idle host. */
+export declare const DEFAULT_BASH_NICENESS = 10;
+/** The politest priority the scheduler accepts. A NEGATIVE niceness (more
+ * priority than the broker itself) needs root: `nice` prints a permission error
+ * into the command's own log and runs it at the inherited priority anyway, so
+ * the override range stops at 0. */
+export declare const MAX_BASH_NICENESS = 19;
+/** Per-node override of the bash niceness, written by `crtr node config --nice`
+ * and read by the valve when it starts each command. Node-local like the job
+ * dirs beside it, so a change applies to the node's very next command without
+ * waiting for a revive. */
+export declare function bashNicenessPath(contextDir: string): string;
+/** The niceness this node's commands run at. Any missing, malformed, or
+ * out-of-range file reads as the default rather than an odd priority. */
+export declare function readBashNiceness(contextDir: string): number;
+/** Set the node's bash niceness. The caller owns validation; the store keeps
+ * one integer so the valve's read stays a single file read per command. */
+export declare function writeBashNiceness(contextDir: string, niceness: number): void;
+/** The auto-background cancel deadline (epoch ms), or undefined for a job with
+ * no deadline (a deliberate handoff, or a legacy job dir). A non-finite or
+ * malformed file reads as no deadline rather than an instant expiry. */
+export declare function readJobDeadlineMs(contextDir: string, jobId: string): number | undefined;
+/** Arm or move an auto-backgrounded job's cancel deadline to `deadlineMs`
+ * (epoch ms). Written by the valve at auto-handoff and rewritten when the
+ * owning node claims more time. */
+export declare function writeJobDeadlineMs(paths: BashJobPaths, deadlineMs: number): void;
+/** Drop a job's cancel deadline so it runs to completion — the node has claimed
+ * it. Best-effort: a job with no deadline file is already in this state. */
+export declare function clearJobDeadline(paths: BashJobPaths): void;
+/** Launcher jobs have a root-owned bwrap pid, not a process group; direct
+ *  jobs keep their detached supervisor process group. */
+export declare function isBashJobProcessGroupAlive(pgid: number, identity?: string): boolean;
+/** Best-effort cancellation for a detached bash supervisor. It snapshots the
+ * observable descendant tree while the supervisor is still alive, signals its
+ * leaves before their parents, then uses the shared identity-guarded KILL
+ * escalation. A descendant that detached and reparented before this snapshot
+ * is outside this guarantee. */
+export declare function cancelBashJobProcessTree(pgid: number, expectedIdentity: string): Promise<boolean>;
+export type StopBackgroundBashJobResult = {
+    kind: 'stopped';
+    signaled: boolean;
+    pgid: number;
+    logPath: string;
+} | {
+    kind: 'missing';
+} | {
+    kind: 'retired';
+    logPath: string;
+} | {
+    kind: 'not-stoppable';
+    logPath: string;
+};
+/** Stop one live background job using the same best-effort tree cancellation
+ * semantics as inline abort and timeout. The caller owns the user-facing
+ * notification; this primitive owns only the job control-plane mutation.
+ *
+ * Only a job in the live-background state the roster projects (job.bg present,
+ * job.exit absent) may be signaled. Job directories persist after the
+ * supervisor exits, so a retired, still-foreground, or already-stopped job
+ * would otherwise have its recorded pgid signaled long after the OS could have
+ * reused that id for an unrelated process group. */
+export declare function stopBackgroundBashJob(contextDir: string, jobId: string, allowForeground?: boolean, nodeId?: string, reason?: string): Promise<StopBackgroundBashJobResult>;
+/** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
+ * rather than the whole file, which for a long-running job can be enormous. */
+export declare function tailJobLog(logPath: string, count: number): string[];
+/** Lines written to a job log so far, counting a trailing unterminated line as
+ * one. Reads the whole file in fixed-size chunks, so even a log at the 10 MiB
+ * cap costs one buffer rather than its full size in memory. */
+export declare function countJobLogLines(logPath: string): number;
+/** Mint a fresh job id — `${Date.now()}-${hex}`. The sole minting site; the
+ * valve calls this instead of building the literal inline so the epoch-ms
+ * prefix is a real contract shared with its parser (jobStartedAtMs), not an
+ * incidental string format. */
+export declare function newBashJobId(): string;
+/** Parse the start epoch (ms) out of a job id's prefix. undefined unless the
+ * id is exactly `<finite-number>-<nonempty-suffix>` — defensive against a
+ * hand-created directory that doesn't follow the newBashJobId contract,
+ * including one with no separator at all (`indexOf('-') === -1` must not
+ * silently parse as a truncated prefix). */
+export declare function jobStartedAtMs(jobId: string): number | undefined;
+/** Render an elapsed duration the way every bash-handoff surface (the valve's
+ * notice, the `node bash background` result/toast, and the attach cockpit)
+ * shows it: `<60s -> "12s"`; `60s-59m -> "3m 40s"`; `>=60m -> "1h 04m"`. */
+export declare function formatBashElapsed(ms: number): string;
+/** The command line worth SHOWING for a job: the first non-empty line of
+ * `cmd.sh`, whitespace-collapsed to one line. */
+export declare function bashJobCommandLine(command: string): string;
+export interface BashJobStatus {
+    jobId: string;
+    /** Full text of cmd.sh. */
+    command: string;
+    /** Human-readable label, or null for an unlabeled or legacy job. */
+    purpose: string | null;
+    startedAtMs: number;
+    logPath: string;
+    /** Auto-background cancel deadline (epoch ms), or null for a job that runs to
+     * completion (a deliberate handoff, or one the node has claimed). */
+    deadlineAtMs: number | null;
+}
+/** Every live backgrounded bash job for this node — job.bg present, job.exit
+ * absent — whether handed off by the menu, the valve deadline, or broker
+ * termination. Read-only; never mutates. Skips malformed/partially-written
+ * directories. Returns oldest-first by startedAtMs. */
+export declare function activeBackgroundBashJobs(contextDir: string, includeForeground?: boolean): BashJobStatus[];
+/** Every live background job for this node whose auto-cancel deadline has
+ * passed at `now`. The daemon's deadline lane stops exactly these. A job with
+ * no deadline (deliberate handoff, or one the node claimed) never appears. */
+export declare function expiredAutoBackgroundBashJobs(contextDir: string, now: number): BashJobStatus[];
+/** Credit every armed auto-cancel deadline for an interval the node was not
+ * permitted to run. A profile pause stops the owning node, so without this the
+ * claim window burns down while the only agent that could claim it is stopped,
+ * and resume greets it with a job already canceled for not being claimed. A
+ * deliberate handoff carries no deadline and is untouched. */
+export declare function shiftAutoBackgroundBashDeadlines(contextDir: string, byMs: number): number;
+export type BackgroundBashJobResult = 'backgrounded' | 'already-backgrounded' | 'finished' | 'missing';
+/** Atomically hand one foreground job to its detached supervisor. The rename
+ * is the ownership decision: exactly one caller can move job.run to job.bg,
+ * while the supervisor races to move the same source to job.done. */
+export declare function backgroundBashJob(paths: BashJobPaths): BackgroundBashJobResult;
+/** The start time (ms epoch) of the oldest still-foreground bash command for
+ * this node, or undefined when none is running. This is the authoritative
+ * source for the attach viewer's background hint: a fresh or reconnected
+ * attach reads the same job.run state that backgrounding and completion race
+ * to claim, without viewer-local call tracking that can go stale. */
+export declare function oldestRunningBashJobStartedAtMs(contextDir: string): number | undefined;
+/** Request immediate handoff for every bash command still waiting on pi. Only
+ * the caller that wins the job.run → job.bg rename reports the job as handed
+ * off; another backgrounder or the foreground-completion path may win the race. */
+export declare function backgroundRunningBashJobs(contextDir: string): BashJobPaths[];

package/dist/core/bash-jobs.js

@@ -0,0 +1,8 @@
+var L=Object.defineProperty;var o=(t,e)=>L(t,"name",{value:e,configurable:!0});import{randomBytes as $}from"node:crypto";import{closeSync as B,openSync as j,readSync as y,statSync as R}from"node:fs";import{dirname as g,join as a}from"node:path";import{captureTeardownSnapshot as T,isAnyPidAlive as I,isPidAlive as _,killProcessTreePids as S}from"./canvas/pid.js";import{launcherRequest as F}from"../launcher/client.js";import{LaunchRefused as O}from"../launcher/spec.js";import{createFileBeneath as x,existsBeneath as C,readdirBeneath as v,readFileBeneath as z,renameBeneath as X,unlinkBeneath as G,writeFileBeneath as P}from"./spaces/open-beneath.js";const H=280;function q(t){if(typeof t!="string"||/[\p{Cc}\p{Cf}]/u.test(t))return null;const e=t.trim();return e===""?null:Buffer.byteLength(e,"utf8")<=H?e:null}o(q,"normalizeBashJobPurpose");function m(t){return a(t,"jobs")}o(m,"bashJobsDir");function p(t,e){return z(g(t),e).toString("utf8")}o(p,"readJobText");function E(t){return v(g(t),m(t)).map(e=>e.name)}o(E,"jobIds");function c(t,e){return C(t.root,e)}o(c,"has");function J(t,e){try{G(t,e)}catch(n){if(n.code!=="ENOENT")throw n}}o(J,"unlinkIfPresent");function at(t){return typeof t=="string"&&t!==""&&t!=="."&&t!==".."&&/^[A-Za-z0-9._~-]+$/u.test(t)&&Buffer.byteLength(t,"utf8")<=128}o(at,"isSafeBashJobId");function l(t,e){const n=a(m(t),e);return{jobId:e,root:g(t),dir:n,cmdSh:a(n,"cmd.sh"),jobLog:a(n,"job.log"),jobExit:a(n,"job.exit"),jobRun:a(n,"job.run"),jobBg:a(n,"job.bg"),jobDone:a(n,"job.done"),jobPgid:a(n,"job.pgid"),jobPgidIdentity:a(n,"job.pgid-identity"),jobPurpose:a(n,"purpose"),jobDeadline:a(n,"job.deadline")}}o(l,"bashJobPaths");function U(t,e){try{const n=Number(p(t,l(t,e).jobPgid).trim());return Number.isInteger(n)&&n>1?n:void 0}catch{return}}o(U,"readJobPgid");function W(t,e){try{const n=p(t,l(t,e).jobPgidIdentity).trim();return n===""?void 0:n}catch{return}}o(W,"readJobPgidIdentity");function K(t,e){try{return q(p(t,l(t,e).jobPurpose))}catch{return null}}o(K,"readJobPurpose");const M=10,Y=19;function A(t){return a(m(t),"niceness")}o(A,"bashNicenessPath");function ct(t){try{const e=Number(p(t,A(t)).trim());return!Number.isInteger(e)||e<0||e>Y?M:e}catch{return M}}o(ct,"readBashNiceness");function dt(t,e){P(g(t),A(t),`${Math.trunc(e)}
+`)}o(dt,"writeBashNiceness");function Z(t,e){try{const n=Number(p(t,l(t,e).jobDeadline).trim());return Number.isFinite(n)?n:void 0}catch{return}}o(Z,"readJobDeadlineMs");function Q(t,e){P(t.root,t.jobDeadline,`${Math.trunc(e)}
+`)}o(Q,"writeJobDeadlineMs");function ft(t){try{J(t.root,t.jobDeadline)}catch{}}o(ft,"clearJobDeadline");function lt(t,e){if(e===`launcher:${t}`)return _(t);try{return process.kill(-t,0),!0}catch(n){return n.code==="EPERM"}}o(lt,"isBashJobProcessGroupAlive");async function V(t,e){const n=T(t,e);if(n.reused||n.tree.length===0)return!1;const r=[...n.tree].reverse(),u=I(r);return S(r,"SIGTERM",n.identities),await new Promise(i=>setTimeout(i,400)),S(r,"SIGKILL",n.identities),u}o(V,"cancelBashJobProcessTree");async function ht(t,e,n=!1,r,u){const i=l(t,e);if(!c(i,i.dir))return{kind:"missing"};if(!c(i,i.jobBg)&&!(n&&c(i,i.jobRun))||c(i,i.jobExit))return{kind:"retired",logPath:i.jobLog};const s=U(t,e),d=W(t,e);if(s===void 0||d===void 0)return{kind:"not-stoppable",logPath:i.jobLog};const h=a(i.dir,"job.stop");try{x(i.root,h,u===void 0?"":`${u}
+`)}catch(f){if(f.code==="EEXIST")return{kind:"retired",logPath:i.jobLog};throw f}try{let f;if(d===`launcher:${s}`){if(r===void 0)throw new Error("launcher job stop requires its owning node");try{if(!("ok"in await F({operation:"stop",pid:s,nodeId:r})))throw new Error("launcher did not stop job");f=!0}catch(b){if(!(b instanceof O&&b.refusal==="invalid_spec"))throw b;f=!1}}else f=await V(s,d);try{x(i.root,i.jobExit,`143
+`)}catch(b){if(b.code!=="EEXIST")throw b}return{kind:"stopped",signaled:f,pgid:s,logPath:i.jobLog}}catch(f){throw J(i.root,h),f}}o(ht,"stopBackgroundBashJob");function bt(t,e){if(e<=0)return[];const n=64*1024;let r;try{const u=R(t).size,i=Math.max(0,u-n),s=Buffer.alloc(Math.min(u,n));r=j(t,"r"),y(r,s,0,s.length,i);const d=s.toString("utf8"),h=(i>0?d.slice(d.indexOf(`
+`)+1):d).split(`
+`);return h[h.length-1]===""&&h.pop(),h.slice(-e)}catch{return[]}finally{r!==void 0&&B(r)}}o(bt,"tailJobLog");function pt(t){let e;try{e=j(t,"r");const n=Buffer.alloc(64*1024);let r=0,u=0;for(;;){const i=y(e,n,0,n.length,null);if(i===0)break;for(let s=0;s<i;s+=1)n[s]===10&&(r+=1);u=n[i-1]}return u!==0&&u!==10?r+1:r}catch{return 0}finally{e!==void 0&&B(e)}}o(pt,"countJobLogLines");function gt(){return`${Date.now()}-${$(4).toString("hex")}`}o(gt,"newBashJobId");function k(t){const e=t.indexOf("-");if(e<=0||e===t.length-1)return;const n=Number(t.slice(0,e));return Number.isFinite(n)?n:void 0}o(k,"jobStartedAtMs");function mt(t){const e=Math.max(0,Math.floor(t/1e3));if(e<60)return`${e}s`;const n=Math.floor(e/60),r=e%60;if(n<60)return`${n}m ${String(r).padStart(2,"0")}s`;const u=Math.floor(n/60),i=n%60;return`${u}h ${String(i).padStart(2,"0")}m`}o(mt,"formatBashElapsed");function Bt(t){return(t.split(`
+`).map(n=>n.trim()).find(n=>n!=="")??"").replace(/\s+/g," ")}o(Bt,"bashJobCommandLine");function w(t,e=!1){let n;try{n=E(t)}catch{return[]}const r=[];for(const u of n){const i=k(u);if(i===void 0)continue;const s=l(t,u);let d;try{if(!c(s,s.jobBg)&&!(e&&c(s,s.jobRun))||c(s,s.jobExit))continue;d=p(t,s.cmdSh)}catch{continue}r.push({jobId:u,command:d,purpose:K(t,u),startedAtMs:i,logPath:s.jobLog,deadlineAtMs:Z(t,u)??null})}return r.sort((u,i)=>u.startedAtMs-i.startedAtMs)}o(w,"activeBackgroundBashJobs");function jt(t,e){return w(t).filter(n=>n.deadlineAtMs!==null&&e>=n.deadlineAtMs)}o(jt,"expiredAutoBackgroundBashJobs");function yt(t,e){if(!Number.isFinite(e)||e<=0)return 0;let n=0;for(const r of w(t))if(r.deadlineAtMs!==null)try{Q(l(t,r.jobId),r.deadlineAtMs+e),n+=1}catch{}return n}o(yt,"shiftAutoBackgroundBashDeadlines");function D(t){try{return X(t.root,t.jobRun,t.jobBg),"backgrounded"}catch(e){if(e.code!=="ENOENT")throw e;return c(t,t.jobBg)?"already-backgrounded":c(t,t.jobDone)?"finished":"missing"}}o(D,"backgroundBashJob");function N(t){let e;try{e=E(t)}catch{return[]}return e.flatMap(n=>{const r=l(t,n);try{return c(r,r.cmdSh)&&c(r,r.jobLog)&&c(r,r.jobRun)?[r]:[]}catch{return[]}})}o(N,"runningBashJobs");function St(t){let e;for(const n of N(t)){const r=k(n.jobId);r!==void 0&&(e===void 0||r<e)&&(e=r)}return e}o(St,"oldestRunningBashJobStartedAtMs");function xt(t){const e=[];for(const n of N(t))D(n)==="backgrounded"&&e.push(n);return e}o(xt,"backgroundRunningBashJobs");export{M as DEFAULT_BASH_NICENESS,Y as MAX_BASH_NICENESS,w as activeBackgroundBashJobs,D as backgroundBashJob,xt as backgroundRunningBashJobs,Bt as bashJobCommandLine,l as bashJobPaths,m as bashJobsDir,A as bashNicenessPath,V as cancelBashJobProcessTree,ft as clearJobDeadline,pt as countJobLogLines,jt as expiredAutoBackgroundBashJobs,mt as formatBashElapsed,lt as isBashJobProcessGroupAlive,at as isSafeBashJobId,k as jobStartedAtMs,gt as newBashJobId,q as normalizeBashJobPurpose,St as oldestRunningBashJobStartedAtMs,ct as readBashNiceness,Z as readJobDeadlineMs,U as readJobPgid,W as readJobPgidIdentity,K as readJobPurpose,yt as shiftAutoBackgroundBashDeadlines,ht as stopBackgroundBashJob,bt as tailJobLog,dt as writeBashNiceness,Q as writeJobDeadlineMs};

package/dist/core/bootstrap.d.ts

@@ -0,0 +1 @@
+export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var t=(e,r)=>s(e,"name",{value:r,configurable:!0});import{homedir as p}from"node:os";import{join as c,relative as f,sep as m}from"node:path";import{appsRoot as u}from"./layout.js";import{findProjectScopeRoot as S,userScopeRoot as n}from"./scope.js";import{ensureScopeInitialized as d}from"./config.js";import{initializeFreshScopedStore as h}from"./scoped-state/migrate.js";import{CRTR_DIR_NAME as l}from"../types.js";import{envDebug as R}from"../shared/env.js";const a=new Set(["help","--help","-h","--version","-v"]);function g(e){const r=e[2];return r===void 0||r==="sys"&&e[3]==="migrate"?!0:a.has(r)}t(g,"shouldSkipForArgv");function D(e){try{if(process.env.CRTR_NO_AUTO_INIT==="1"||g(e)||(h({kind:"user",root:n()}),S()!==null))return;const r=process.cwd();if(r===p())return;const o=f(u(),r).split(m);if(o.length===2&&o[1]==="home")return;const i=c(r,l);if(i===n())return;d("project",i)}catch(r){if(R()){const o=r instanceof Error?r.message:String(r);process.stderr.write(`crtr: project-init error: ${o}
+`)}}}t(D,"ensureProjectScope");export{D as ensureProjectScope};

package/dist/core/broker-client/client.d.ts

@@ -0,0 +1,89 @@
+import { EventEmitter } from 'node:events';
+import type { NodeRow } from '../canvas/types.js';
+import type { BrokerDataFrame, BrokerToClient, ClientToBroker, DequeueFrame, GetHumanForkCoordinatesFrame, GetSettingsFrame, GetTreeFrame, ListMemoryRefsFrame, ListModelsFrame, ListScopedModelsFrame, ListSessionsFrame } from '../runtime/broker-protocol.js';
+import { type RedialOptions, type Transport } from './transport.js';
+export { BrokerUnavailableError, type Transport } from './transport.js';
+export { SocketTransport } from './transport-socket.js';
+export { RelayTransport, type RelayTarget } from './transport-relay.js';
+/** A correlated read-op (or `dequeue`) request MINUS the client-chosen `id` —
+ *  {@link BrokerClient.request} mints the `id`, sends the frame, and resolves
+ *  with the matching `data` reply. The picker/operator code builds these; the
+ *  client owns the correlation token so callers never hand-roll one. */
+export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame, 'id'> | Omit<GetTreeFrame, 'id'> | Omit<GetSettingsFrame, 'id'> | Omit<ListScopedModelsFrame, 'id'> | Omit<DequeueFrame, 'id'> | Omit<GetHumanForkCoordinatesFrame, 'id'> | Omit<ListMemoryRefsFrame, 'id'>;
+export interface BrokerClientOptions {
+    /** Where the frames go. Defaults to a {@link SocketTransport} against this
+     *  node's local `view.sock` — the common case. Pass a {@link RelayTransport}
+     *  to attach a remote node instead; every method behaves identically either
+     *  way. */
+    transport?: Transport;
+}
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same target while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` and an
+ *  exact unfinalized parked resident are NOT terminal — either can wake while
+ *  the viewer remains seated. Local canvas rows only — a remote target has no
+ *  local row, so callers driving a remote attach must not consult this. */
+export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
+/** The plan-fixed interface (Wave 3): `connect()`, `on('frame', …)`,
+ *  `send(frame)`, `on('close', …)`, plus `connect`/`error` events. */
+export interface BrokerClient {
+    on(event: 'connect', listener: () => void): this;
+    on(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'connect', listener: () => void): this;
+    once(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    once(event: 'close', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+export declare class BrokerClient extends EventEmitter {
+    private readonly nodeId;
+    private readonly transport;
+    private closeEmitted;
+    /** Tracks live connect↔close state so {@link request} can fail fast on a
+     *  dead/absent connection rather than parking a promise the reply will
+     *  never reach (transport-agnostic mirror of the old socket.destroyed
+     *  check). A post-close request lands here too — {@link rejectAllPending}
+     *  already ran by the time this flips false. */
+    private connected;
+    /** The last transport-level error message, so a close can reject any
+     *  in-flight requests with the precise reason (e.g. an oversized-frame
+     *  overflow) instead of a generic one. Cleared on every fresh connect. */
+    private lastTransportError;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onFrame}, the request's timeout, or transport teardown. */
+    private pending;
+    constructor(nodeId: string, options?: BrokerClientOptions);
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or transport teardown). Mints
+     *  the `id`, sends `{...frame, id}`, and parks a resolver consumed by
+     *  {@link onFrame}. The reply is narrowed by the caller on its `kind`. */
+    request(frame: ReadOpRequest): Promise<BrokerDataFrame>;
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
+    private rejectAllPending;
+    /** Open the connection. Emits `connect` on success or `error` (a
+     *  {@link BrokerUnavailableError} when the target has no reachable broker)
+     *  on failure. Idempotent guard is the caller's job — call once. */
+    connect(): void;
+    /** Re-establish the connection after a broker exit (a yield→revive cycle),
+     *  to the SAME target. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on a retryable dial failure. */
+    redial(options?: RedialOptions): Promise<void>;
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
+    send(frame: ClientToBroker): void;
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
+    close(): void;
+    private onFrame;
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    private emitError;
+}

package/dist/core/broker-client/client.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var o=(r,t)=>c(r,"name",{value:t,configurable:!0});import{EventEmitter as l}from"node:events";import{randomUUID as p}from"node:crypto";import{SocketTransport as a}from"./transport-socket.js";import{BrokerUnavailableError as k}from"./transport.js";import{SocketTransport as x}from"./transport-socket.js";import{RelayTransport as S}from"./transport-relay.js";const d=1e4;function E(r){return r===null?!0:r.lifecycle==="resident"&&r.status==="done"&&r.intent==="parked"&&r.final_report==null?!1:r.status==="done"||r.status==="dead"||r.status==="canceled"}o(E,"reconnectShouldGiveUp");class g extends l{static{o(this,"BrokerClient")}nodeId;transport;closeEmitted=!1;connected=!1;lastTransportError;pending=new Map;constructor(t,e={}){super(),this.nodeId=t,this.transport=e.transport??new a(t),this.transport.on("connect",()=>{this.closeEmitted=!1,this.connected=!0,this.lastTransportError=void 0,this.emit("connect")}),this.transport.on("frame",n=>this.onFrame(n)),this.transport.on("error",n=>{this.lastTransportError=n.message,this.emitError(n)}),this.transport.on("close",()=>this.onClose())}request(t){const e=p();return new Promise((n,s)=>{if(!this.connected){s(new Error(`cannot issue '${t.type}': no live broker connection`));return}const i=setTimeout(()=>{this.pending.delete(e),s(new Error(`request '${t.type}' timed out after ${d}ms`))},d);typeof i.unref=="function"&&i.unref(),this.pending.set(e,{resolve:n,reject:s,timer:i}),this.send({...t,id:e})})}rejectAllPending(t){for(const{reject:e,timer:n}of this.pending.values())clearTimeout(n),e(new Error(t));this.pending.clear()}connect(){this.transport.connect()}redial(t){return this.transport.redial(t)}send(t){this.transport.send(t)}close(){this.transport.destroy()}onFrame(t){if(t.type==="data"){const e=typeof t.id=="string"?this.pending.get(t.id):void 0;e&&(this.pending.delete(t.id),clearTimeout(e.timer),e.resolve(t));return}if(t.type==="error"&&typeof t.id=="string"&&this.pending.has(t.id)){const e=this.pending.get(t.id);this.pending.delete(t.id),clearTimeout(e.timer),e.reject(new Error(t.message||`request failed: ${t.code}`));return}this.emit("frame",t)}onClose(){this.closeEmitted||(this.closeEmitted=!0,this.connected=!1,this.rejectAllPending(this.lastTransportError??"broker connection closed"),this.emit("close"))}emitError(t){this.listenerCount("error")>0&&this.emit("error",t)}}export{g as BrokerClient,k as BrokerUnavailableError,S as RelayTransport,x as SocketTransport,E as reconnectShouldGiveUp};

package/dist/core/broker-client/index.d.ts

@@ -0,0 +1 @@
+export { BrokerClient, BrokerUnavailableError, reconnectShouldGiveUp, RelayTransport, SocketTransport, type BrokerClientOptions, type ReadOpRequest, type RelayTarget, type Transport, } from './client.js';

package/dist/core/broker-client/index.js

@@ -0,0 +1 @@
+import{BrokerClient as o,BrokerUnavailableError as a,reconnectShouldGiveUp as n,RelayTransport as t,SocketTransport as l}from"./client.js";export{o as BrokerClient,a as BrokerUnavailableError,t as RelayTransport,l as SocketTransport,n as reconnectShouldGiveUp};

package/dist/core/broker-client/transport-relay.d.ts

@@ -0,0 +1,47 @@
+import { EventEmitter } from 'node:events';
+import type { ClientToBroker } from '../runtime/broker-protocol.js';
+import { type RedialOptions, type Transport } from './transport.js';
+/** A resolved remote canvas target — see `core/remote-canvas-target.ts` for how
+ *  this is assembled from config (`relayTokenRef`) plus the 0600 secrets store
+ *  via `resolveRemoteCanvasTarget`. This transport itself never takes the
+ *  token from argv — `canvas config add --relay-token -` is the only accepted
+ *  form for writing a token to the store — stdin-only, never argv; that is a
+ *  one-time config-write path, not this call. */
+export interface RelayTarget {
+    /** The preview endpoint origin, e.g. `https://<hash>.preview.bl.run`. */
+    previewEndpoint: string;
+    /** The raw bearer token. NEVER logged, NEVER echoed. */
+    relayToken: string;
+}
+export interface LocalRelayTarget {
+    /** The owner's daemon API socket. The viewer has already called ensureAttach. */
+    socketPath: string;
+}
+export declare class RelayTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private readonly target;
+    private ws;
+    private closeEmitted;
+    constructor(nodeId: string, target: RelayTarget | LocalRelayTarget);
+    private get url();
+    private dial;
+    connect(): void;
+    /** Re-dial the same daemon attach endpoint after a broker replacement. */
+    redial(_options?: RedialOptions): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private onMessage;
+    private onError;
+    /** A 1008 invalid-id close or a 1011 whose reason starts with "no running
+     *  broker" or "no node " is a terminal unavailable-broker signal from the
+     *  crtrd attach bridge. Surface it as BrokerUnavailableError so the reconnect
+     *  supervisor applies its normal give-up path across transports. `classify`
+     *  only handles the 1008/protocol case: its 1011 classification answers
+     *  whether a close is connection-shaped, not whether the broker is gone.
+     *  Everything else (1006 abnormal, 1000 normal, or an unrecognized 1011
+     *  reason) is a transient or expected drop that the caller may redial. */
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    private emitError;
+}

package/dist/core/broker-client/transport-relay.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var a=(r,t)=>l(r,"name",{value:t,configurable:!0});import{EventEmitter as d}from"node:events";import{WebSocket as h}from"ws";import{classify as m}from"../fault-classifier.js";import{BrokerUnavailableError as f}from"./transport.js";function u(r,t){if("socketPath"in r)return`ws+unix://${r.socketPath}:/v1/nodes/${encodeURIComponent(t)}/attach?revive=0`;const e=new URL(r.previewEndpoint);return e.protocol=e.protocol==="http:"?"ws:":"wss:",e.pathname=`/v1/nodes/${encodeURIComponent(t)}/attach`,e.search="?wakeParked=1",e.hash="",e.toString()}a(u,"relayUrl");class k extends d{static{a(this,"RelayTransport")}nodeId;target;ws;closeEmitted=!1;constructor(t,e){super(),this.nodeId=t,this.target=e}get url(){return u(this.target,this.nodeId)}dial(){const t=new h(this.url,{..."relayToken"in this.target?{headers:{authorization:`Bearer ${this.target.relayToken}`}}:{},perMessageDeflate:!1});return this.ws=t,t}connect(){const t=this.dial();t.on("open",()=>{this.emit("connect")}),t.on("message",e=>this.onMessage(e)),t.on("error",e=>this.onError(e)),t.on("close",(e,n)=>this.onClose(e,n.toString()))}redial(t){return this.destroy(),this.closeEmitted=!1,new Promise((e,n)=>{const o=this.dial();let i=!1;o.on("open",()=>{i||(i=!0,this.emit("connect"),e())}),o.on("message",s=>this.onMessage(s)),o.on("error",s=>{if(i){this.onError(s);return}i=!0;try{o.terminate()}catch{}n(s)}),o.on("close",(s,c)=>{i&&this.onClose(s,c.toString())})})}send(t){const e=this.ws;if(!(e===void 0||e.readyState!==h.OPEN))try{e.send(JSON.stringify(t))}catch{}}destroy(){const t=this.ws;if(t!==void 0&&t.readyState<=h.OPEN)try{t.close()}catch{}}onMessage(t){let e;try{e=JSON.parse(t.toString())}catch{return}this.emit("frame",e)}onError(t){this.emitError(new Error(`relay transport error: ${t.message}`))}onClose(t,e){if(this.closeEmitted)return;this.closeEmitted=!0;const n=m("viewer\u2194broker",{code:t,reason:e});(t===1008||n.kind==="protocol"||t===1011&&(/^no running broker/.test(e)||/^no node /.test(e)))&&this.emitError(new f(this.nodeId)),this.emit("close")}emitError(t){this.listenerCount("error")>0&&this.emit("error",t)}}export{k as RelayTransport};

package/dist/core/broker-client/transport-socket.d.ts

@@ -0,0 +1,35 @@
+import { EventEmitter } from 'node:events';
+import { type ClientToBroker } from '../runtime/broker-protocol.js';
+import { type RedialOptions, type Transport } from './transport.js';
+export declare class SocketTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private readonly options;
+    private socket;
+    private decoder;
+    private closeEmitted;
+    /** One redial fault line per reconnect EPISODE, not per attempt — see
+     *  {@link recordSocketFault}. */
+    private redialFaultRecorded;
+    /** `recordsViewerFaults: false` is for an internal daemon reader: its
+     *  connect outcome says nothing about any person's viewer. */
+    constructor(nodeId: string, options?: {
+        recordsViewerFaults?: boolean;
+    });
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
+    get socketPath(): string;
+    private recordSocketFault;
+    connect(): void;
+    /** Re-establish the socket after a broker exit, on the SAME stable
+     *  `view.sock` path. Installs a FRESH FrameDecoder (a half-frame from the
+     *  dead stream must not corrupt the new one). */
+    redial(options?: RedialOptions): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private clearSocketFault;
+    private onData;
+    private onError;
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    private emitError;
+}

package/dist/core/broker-client/transport-socket.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var d=(n,e)=>m(n,"name",{value:e,configurable:!0});import{EventEmitter as u}from"node:events";import{viewSocketPath as k}from"../canvas/paths.js";import{connectViewSocket as a}from"../runtime/view-socket.js";import{classify as E}from"../fault-classifier.js";import{clearNodeFault as F,recordNodeFault as p}from"../runtime/broker/daemon-ops.js";import{emitEvent as c}from"../events/emit.js";import{CLIENT_READ_CAPS as l,encodeFrame as v,FrameDecoder as h,FrameOverflowError as w}from"../runtime/broker-protocol.js";import{BrokerUnavailableError as b}from"./transport.js";class U extends u{static{d(this,"SocketTransport")}nodeId;options;socket;decoder=new h(l);closeEmitted=!1;redialFaultRecorded=!1;constructor(e,t={}){super(),this.nodeId=e,this.options=t}get socketPath(){return k(this.nodeId)}recordSocketFault(e,t){if(this.options.recordsViewerFaults===!1)return;if(e==="redial"){if(this.redialFaultRecorded)return;this.redialFaultRecorded=!0}const o=E("viewer\u2194broker",t);p(this.nodeId,{link:"viewer\u2194broker",op:e,kind:o.kind,retry:e==="redial"?{disposition:"auto",by:"client"}:{disposition:"manual"},message:t instanceof Error?t.message:String(t)}).catch(r=>{c({event:"broker.daemon.operation.failed",level:"error",node_id:this.nodeId,error:r,fields:{operation:"viewer_fault_record"}})})}connect(){const e=a(this.nodeId);this.socket=e,e.on("connect",()=>{this.redialFaultRecorded=!1,this.clearSocketFault(),this.emit("connect")}),e.on("data",t=>this.onData(t)),e.on("error",t=>this.onError(t,"connect")),e.on("close",()=>this.onClose())}redial(e={}){return this.destroy(),this.decoder=new h(l),this.closeEmitted=!1,e.brokerUnavailableIsExpected&&(this.redialFaultRecorded=!1,this.clearSocketFault()),new Promise((t,o)=>{const r=a(this.nodeId);this.socket=r;let s=!1;r.on("connect",()=>{s||(s=!0,this.redialFaultRecorded=!1,this.clearSocketFault(),this.emit("connect"),t())}),r.on("data",i=>this.onData(i)),r.on("error",i=>{if(s){this.onError(i,"redial");return}s=!0;const f=i.code==="ECONNREFUSED"||i.code==="ENOENT";(!e.brokerUnavailableIsExpected||!f)&&this.recordSocketFault("redial",i);try{r.destroy()}catch{}o(i)}),r.on("close",()=>this.onClose())})}send(e){const t=this.socket;if(!(t===void 0||t.destroyed))try{t.write(v(e))}catch{}}destroy(){const e=this.socket;if(e!==void 0&&!e.destroyed)try{e.destroy()}catch{}}clearSocketFault(){this.options.recordsViewerFaults!==!1&&F(this.nodeId,{link:"viewer\u2194broker"}).catch(e=>{c({event:"broker.daemon.operation.failed",level:"error",node_id:this.nodeId,error:e,fields:{operation:"viewer_fault_clear"}})})}onData(e){let t;try{t=this.decoder.push(e)}catch(o){const r=o instanceof w?`broker sent an oversized frame (${o.message}) \u2014 disconnecting`:`failed to decode a broker frame: ${String(o)}`;this.emitError(new Error(r)),this.destroy();return}for(const o of t)this.emit("frame",o)}onError(e,t){this.recordSocketFault(t,e),e.code==="ECONNREFUSED"||e.code==="ENOENT"?this.emitError(new b(this.nodeId)):this.emitError(new Error(`view socket error: ${e.message}`))}onClose(){this.closeEmitted||(this.closeEmitted=!0,this.emit("close"))}emitError(e){this.listenerCount("error")>0&&this.emit("error",e)}}export{U as SocketTransport};

package/dist/core/broker-client/transport.d.ts

@@ -0,0 +1,36 @@
+import type { EventEmitter } from 'node:events';
+import type { BrokerToClient, ClientToBroker } from '../runtime/broker-protocol.js';
+export interface RedialOptions {
+    /** The node is dormant, so no broker at the target is normal until it wakes. */
+    brokerUnavailableIsExpected?: boolean;
+}
+export interface Transport extends EventEmitter {
+    /** Open the connection. Emits 'connect' on success, 'error' on a fatal
+     *  connect-time failure. Call once. */
+    connect(): void;
+    /** Re-establish the connection to the SAME target after a drop. Resolves on
+     *  a fresh 'connect'; rejects on a retryable dial failure (the caller's
+     *  reconnect supervisor decides whether to try again). */
+    redial(options?: RedialOptions): Promise<void>;
+    /** Encode + send one client→broker frame. No-op on a dead/absent connection;
+     *  never throws. */
+    send(frame: ClientToBroker): void;
+    /** Tear down the connection. 'close' fires if it has not already. */
+    destroy(): void;
+    on(event: 'connect', listener: () => void): this;
+    on(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'connect', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+/** Surfaced when a Transport's target has no reachable broker — locally, no
+ *  socket file / nothing listening; remotely, a crtrd attach close signaling
+ *  "no broker for this node". The command catches this to exit non-zero with a
+ *  focus/revive hint — same meaning regardless of which Transport raised it. */
+export declare class BrokerUnavailableError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}

package/dist/core/broker-client/transport.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var o=(e,r)=>n(e,"name",{value:r,configurable:!0});class a extends Error{static{o(this,"BrokerUnavailableError")}nodeId;constructor(r){super(`node ${r} has no running broker \u2014 focus or revive it first`),this.nodeId=r,this.name="BrokerUnavailableError"}}export{a as BrokerUnavailableError};

package/dist/core/canvas/app-run.d.ts

@@ -0,0 +1,3 @@
+import type { NodeMeta, NodeRow } from './types.js';
+/** Run IDs also identify terminal roots; only a non-terminal app owns run history. */
+export declare function isAppRun(row: Pick<NodeRow | NodeMeta, 'run_id' | 'grantee'>): boolean;

package/dist/core/canvas/app-run.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var p=(n,e)=>r(n,"name",{value:e,configurable:!0});function a(n){return!!n.run_id&&(n.grantee??"app:terminal")!=="app:terminal"}p(a,"isAppRun");export{a as isAppRun};

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

@@ -0,0 +1,18 @@
+export interface TicketEntry {
+    node_id: string;
+    name: string;
+    cwd: string;
+    count: number;
+    /** Open ticket titles for this node, newest first. */
+    subjects: string[];
+}
+/** Kept for callers that reset a canvas home in process. SQL has no directory-scan cache to invalidate. */
+export declare function invalidateTicketCounts(): void;
+/** Count pending tickets asked by one node. */
+export declare function countTickets(nodeId: string): number;
+/** Pending tickets for every reachable asking node, including the root. */
+export declare function pendingTicketsForView(rootId: string): TicketEntry[];
+/** Per-node pending ticket counts for an explicit node set. */
+export declare function ticketCountsForNodes(ids: string[]): Record<string, number>;
+/** Pending tickets across the entire canvas, attributed to asking nodes. */
+export declare function ticketsAcrossCanvas(): TicketEntry[];

package/dist/core/canvas/attention.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var s=(t,n)=>u(t,"name",{value:n,configurable:!0});import{listOpenReplyBearingRequests as d}from"../human/requests.js";import{getNode as f,listNodes as l,view as p}from"./canvas.js";function h(){}s(h,"invalidateTicketCounts");function c(){const t=new Map;for(const n of d()){const e=n.requester_node_id,o=t.get(e);o===void 0?t.set(e,[n.title]):o.push(n.title)}return t}s(c,"ticketSubjects");function w(t){return c().get(t)?.length??0}s(w,"countTickets");function k(t){const n=c(),e=[];for(const o of[t,...p(t)]){const i=f(o),r=n.get(o)??[];i!==null&&r.length>0&&e.push({node_id:o,name:i.name,cwd:i.cwd,count:r.length,subjects:r})}return e}s(k,"pendingTicketsForView");function _(t){const n=c();return Object.fromEntries(t.map(e=>[e,n.get(e)?.length??0]))}s(_,"ticketCountsForNodes");function b(){const t=c(),n=[];for(const e of l()){const o=t.get(e.node_id)??[];o.length>0&&n.push({node_id:e.node_id,name:e.name,cwd:e.cwd,count:o.length,subjects:o})}return n}s(b,"ticketsAcrossCanvas");export{w as countTickets,h as invalidateTicketCounts,k as pendingTicketsForView,_ as ticketCountsForNodes,b as ticketsAcrossCanvas};

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

@@ -0,0 +1,6 @@
+/** The Linux kernel's per-boot identity at `/proc/sys/kernel/random/boot_id` —
+ *  a fresh random UUID minted on every kernel boot, or null when unreadable
+ *  (non-Linux dev, or the file is absent). Exact when present: a microVM
+ *  recreate boots a new kernel (new id); a plain daemon restart within the same
+ *  boot leaves it identical. */
+export declare function readKernelBootId(): string | null;

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

@@ -0,0 +1 @@
+var e=Object.defineProperty;var t=(r,n)=>e(r,"name",{value:n,configurable:!0});import{readFileSync as o}from"node:fs";function d(){try{const r=o("/proc/sys/kernel/random/boot_id","utf8").trim();return r.length>0?r:null}catch{return null}}t(d,"readKernelBootId");export{d as readKernelBootId};

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

@@ -0,0 +1,92 @@
+export { readKernelBootId } from './boot-id.js';
+/** The kernel's per-boot identity + a wall-clock fallback estimate. */
+export interface BootIdentity {
+    /** `/proc/sys/kernel/random/boot_id` (a fresh UUID per kernel boot), or null
+     *  when unreadable (non-Linux). Exact when present. */
+    bootId: string | null;
+    /** Best-effort wall-clock estimate of when the current boot started. Fallback
+     *  discriminator only, used when `bootId` is null on either side. */
+    bootEpochMs: number;
+}
+/** Identity of the CURRENT OS boot. `now` is injectable for tests. */
+export declare function currentBootIdentity(now?: number): BootIdentity;
+/** Pure decision core: does `current` belong to a DIFFERENT boot than the
+ *  persisted `known`? `known === null` (no history — a fresh install, or the
+ *  first run of a build that added this marker) is never a boot change: there
+ *  is nothing to contradict it, and treating "no history" as a change could
+ *  clear genuinely live pids that predate this feature.
+ *
+ *  When BOTH sides carry a kernel `boot_id`, that exact identity decides it — no
+ *  wall-clock window, so a real quick reboot/recreate (a short-lived prior boot
+ *  whose start is <60s away) is still detected. Only when a `boot_id` is missing
+ *  on either side (non-Linux dev) does it fall back to the epoch-drift window.
+ *  Unit-testable without real uptime/fs. */
+export declare function bootChanged(current: BootIdentity, known: BootIdentity | null): boolean;
+/** POSITIVE proof that `current` is the SAME boot the persisted `known` marker
+ *  recorded — as distinct from `!bootChanged(...)`, which is merely "no change
+ *  detected" and is also true when there is no history, a malformed marker, or
+ *  only the coarse wall-clock fallback to go on. Proof requires an exact kernel
+ *  `boot_id` present and equal on BOTH sides. This gates the one-time legacy
+ *  identity migration: that sweep rewrites a legacy row's baseline as
+ *  `<currentBootId>#<ticks>`, permanently blessing the recorded pid as a
+ *  current-boot process, so it must run ONLY when we can prove the recorded pid
+ *  really is from this boot — never on a mere ticks match under an unproven
+ *  boot (the epoch fallback or an absent/malformed marker could otherwise bless
+ *  an unrelated stranger process that happens to collide on pid+ticks). */
+export declare function bootProvenSame(current: BootIdentity, known: BootIdentity | null): boolean;
+export interface BootReconcileResult {
+    /** True when a boot change was detected (and, therefore, pids were cleared). */
+    changed: boolean;
+    /** node_ids whose stale `pi_pid` was cleared. */
+    cleared: string[];
+    /** True ONLY when this run positively proved same-boot provenance against the
+     *  persisted marker (exact `boot_id` present and equal on both sides). Gates
+     *  the legacy identity migration — see `bootProvenSame`. False on a boot
+     *  change, a first-ever/absent/malformed marker, or a wall-clock-fallback
+     *  match. */
+    sameBootProven: boolean;
+}
+/** Idempotent and safe to call from every revive entry point (daemon startup,
+ *  reviveNode): compares the current boot's identity against the last one
+ *  recorded, and if they differ, clears `pi_pid` on every node that has one —
+ *  regardless of status, since reviveNode's double-launch guard reads `pi_pid`
+ *  unconditionally, not just on active/idle rows. The first caller after a
+ *  genuine boot change does the sweep and persists the new marker; every call
+ *  after that (in this process or another) reads a matching marker and no-ops.
+ *
+ *  SINGLE-WRITER: the whole read-marker + sweep + write-marker runs in one
+ *  `BEGIN IMMEDIATE` transaction. A concurrent caller (a manual revive racing
+ *  daemon startup, in a separate process) blocks on the SQLite write lock until
+ *  this commits, then reads the already-updated marker and no-ops — so it can
+ *  never `clearPid` a broker pid the first caller's revive just recorded, which
+ *  would otherwise hide a live broker behind `pi_pid=NULL` and risk a second
+ *  broker on the same session.
+ *
+ *  `current` defaults to the real identity; tests inject a synthetic one against
+ *  an isolated CRTR_HOME to simulate a boot change without a real reboot. */
+export declare function reconcileBootLiveness(current?: BootIdentity): BootReconcileResult;
+/** The one-time execution-identity migration, injected into the startup
+ *  composition. In production this is `migrateLegacyExecutionIdentities` from
+ *  executions.ts. It remains injected so tests can exercise this composition
+ *  without reaching process inspection. */
+export type MigrateLegacyExecutionIdentities = (captureIdentity?: (pid: number) => string | undefined) => {
+    migrated: string[];
+};
+export interface BootStartupResult {
+    /** The pid-liveness reconciliation result (boot-change sweep + provenance). */
+    reconcile: BootReconcileResult;
+    /** node_ids whose legacy identity baseline was migrated — empty when the
+     *  provenance gate skipped the sweep. */
+    migrated: string[];
+}
+/** The daemon's one-time startup boot composition, the single source of truth
+ *  for its ORDERING and GATE: reconcile pid liveness FIRST (clearing any pids
+ *  recorded before this boot), then run the legacy identity migration ONLY when
+ *  reconciliation positively PROVED same-boot provenance (`sameBootProven`).
+ *  Both `runDaemon` and the migration-gate regression tests call this, so a
+ *  revert that inverts the gate, drops it, or reorders migration ahead of
+ *  reconciliation is caught here rather than only in a test-side duplicate.
+ *
+ *  `migrate` is injected (see `MigrateLegacyPidIdentities`); `current` and
+ *  `captureIdentity` pass through to the two steps for test injection. */
+export declare function reconcileAndMigrateBoot(migrate: MigrateLegacyExecutionIdentities, current?: BootIdentity, captureIdentity?: (pid: number) => string | undefined): BootStartupResult;

package/dist/core/canvas/boot.js

@@ -0,0 +1 @@
+var E=Object.defineProperty;var n=(e,o)=>E(e,"name",{value:o,configurable:!0});import{prepared as d}from"../sqlite-statements.js";import{uptime as f}from"node:os";import{openDb as p}from"./db.js";import{readKernelBootId as b}from"./boot-id.js";import{readKernelBootId as R}from"./boot-id.js";const I=6e4;function M(e=Date.now()){return{bootId:b(),bootEpochMs:e-Math.round(f()*1e3)}}n(M,"currentBootIdentity");function m(e,o){return o===null?!1:e.bootId!==null&&o.bootId!==null?e.bootId!==o.bootId:Math.abs(e.bootEpochMs-o.bootEpochMs)>I}n(m,"bootChanged");function x(e,o){return o!==null&&e.bootId!==null&&o.bootId!==null&&e.bootId===o.bootId}n(x,"bootProvenSame");const s="boot_identity";function h(e){const o=d(e,"SELECT value FROM canvas_meta WHERE key = ?").get(s);if(o===void 0)return null;try{const t=JSON.parse(o.value);return typeof t.bootEpochMs!="number"?null:{bootId:typeof t.bootId=="string"?t.bootId:null,bootEpochMs:t.bootEpochMs}}catch{return null}}n(h,"readBootMarker");function u(e,o){e.prepare("INSERT INTO canvas_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(s,JSON.stringify(o))}n(u,"writeBootMarker");function O(e=M()){const o=p();o.exec("BEGIN IMMEDIATE");try{const t=h(o);if(!m(e,t)){t===null&&u(o,e);const a=x(e,t);return o.exec("COMMIT"),{changed:!1,cleared:[],sameBootProven:a}}const r=d(o,"SELECT execution_id, node_id FROM executions WHERE state != 'exited'").all(),c=d(o,"UPDATE executions SET state = 'exited', ended_at = ?, exit_reason = 'boot-change' WHERE execution_id = ? AND state != 'exited'"),i=[],l=new Date().toISOString();for(const a of r)c.run(l,a.execution_id).changes>0&&i.push(a.node_id);return u(o,e),o.exec("COMMIT"),{changed:!0,cleared:i,sameBootProven:!1}}catch(t){try{o.exec("ROLLBACK")}catch{}throw t}}n(O,"reconcileBootLiveness");function v(e,o,t){const r=O(o),c=r.sameBootProven?e(t).migrated:[];return{reconcile:r,migrated:c}}n(v,"reconcileAndMigrateBoot");export{m as bootChanged,x as bootProvenSame,M as currentBootIdentity,R as readKernelBootId,v as reconcileAndMigrateBoot,O as reconcileBootLiveness};