@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/progress-bar.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { assetRoot } from '../asset-root.js';
+/** What a bar does when there is no terminal to draw on, or when the painter
+ *  cannot be spawned: nothing. The step still runs and still reports its
+ *  `✓`/`✗` outcome line, which is the authoritative result. */
+const NO_BAR = { setFraction() { }, stop: async () => { } };
+function painterPath() {
+    // assetRoot() is `dist/` in a runtime generation and `src/` in a source
+    // checkout; `bin/` sits beside both.
+    return join(dirname(assetRoot()), 'bin', 'progress-painter.mjs');
+}
+/** Start an animated bar on `stream`, drawn by a child process so it keeps
+ *  moving while this process blocks inside the step it describes. */
+export function startProgressBar(label, stream = process.stdout) {
+    if (!stream.isTTY)
+        return NO_BAR;
+    let child;
+    try {
+        child = spawn(process.execPath, [painterPath(), label], { stdio: ['pipe', stream.fd, 'ignore'] });
+    }
+    catch {
+        return NO_BAR;
+    }
+    let alive = true;
+    // A painter that already exited turns the next write into EPIPE on this
+    // pipe; the bar is cosmetic, so the write is dropped rather than raised.
+    child.stdin?.on('error', () => { alive = false; });
+    const exited = new Promise((resolve) => {
+        child.once('exit', () => { alive = false; resolve(); });
+        child.once('error', () => { alive = false; resolve(); });
+    });
+    return {
+        setFraction(fraction) {
+            if (!alive)
+                return;
+            child.stdin?.write(`${Math.min(1, Math.max(0, fraction))}\n`);
+        },
+        async stop() {
+            if (alive)
+                child.stdin?.end();
+            // A painter that does not exit on EOF must never hold up the install it
+            // is only illustrating: kill it and move on to the outcome line.
+            const killed = new Promise((resolve) => setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 1000).unref());
+            await Promise.race([exited, killed]);
+            // Idempotent after a clean exit, and the only restore after a kill.
+            stream.write('\r\x1b[2K\x1b[?25h');
+        },
+    };
+}

package/dist/core/runtime/provider-credential-gate.d.ts

@@ -0,0 +1,8 @@
+import type { CredentialStore } from '@earendil-works/pi-ai';
+/** The daemon, which owns the rows, registers its row-backed store; every other process asks the daemon over /v1/model-auth. */
+export declare function registerGateCredentialStore(store: CredentialStore): void;
+export declare const NO_PROVIDER_CREDENTIAL_MESSAGE = "crtr: no provider credential; run `crtr sys setup` to log in.";
+/** Check the setup catalog before a path creates a broker-backed node. `profileEnvNames` are the names stored on the
+ *  launching profile (values are never needed: a stored value is never empty). */
+export declare function hasConfiguredProviderCredential(profileEnvNames: readonly string[]): Promise<boolean>;
+export declare function exitForMissingProviderCredential(): never;

package/dist/core/runtime/provider-credential-gate.js

@@ -0,0 +1,33 @@
+import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { join } from 'node:path';
+import { ApiCredentialStore } from '../model-auth/api-credential-store.js';
+import { cliClient } from '../../commands/api-client.js';
+import { hasProviderCredential } from '../provider-credential.js';
+import { piAgentDir } from './package-health.js';
+import { PROVIDER_ENV_KEYS } from './spawn-env.js';
+let daemonCredentials;
+/** The daemon, which owns the rows, registers its row-backed store; every other process asks the daemon over /v1/model-auth. */
+export function registerGateCredentialStore(store) { daemonCredentials = store; }
+export const NO_PROVIDER_CREDENTIAL_MESSAGE = 'crtr: no provider credential; run `crtr sys setup` to log in.';
+/** Check the setup catalog before a path creates a broker-backed node. `profileEnvNames` are the names stored on the
+ *  launching profile (values are never needed: a stored value is never empty). */
+export async function hasConfiguredProviderCredential(profileEnvNames) {
+    const profileEnv = Object.fromEntries(profileEnvNames.map((name) => [name, 'stored']));
+    // A provider key set on the HOST environment counts exactly as much as one
+    // stored on the profile: source B of `buildSpawnEnv` copies `process.env`'s
+    // provider keys into every broker verbatim, so a host that exports one can
+    // launch a node. Consulting only the profile store refused those launches.
+    if (Object.values(PROVIDER_ENV_KEYS).some((name) => (profileEnv[name] ?? process.env[name])?.trim())) {
+        return true;
+    }
+    const agentDir = piAgentDir();
+    const runtime = await ModelRuntime.create({
+        credentials: daemonCredentials ?? new ApiCredentialStore(() => cliClient()),
+        modelsPath: join(agentDir, 'models.json'),
+    });
+    return await hasProviderCredential(runtime, new ModelRegistry(runtime));
+}
+export function exitForMissingProviderCredential() {
+    process.stderr.write(`${NO_PROVIDER_CREDENTIAL_MESSAGE}\n`);
+    process.exit(1);
+}

package/dist/core/runtime/recovery-hold.d.ts

@@ -0,0 +1,21 @@
+/** A stop in progress on a node, held on the node's row (`recovery_held_until`, `recovery_held_by`).
+ *  Dead-row recovery leaves a held node alone, so the broker's exit cannot be read as a crash and
+ *  resumed before the caller that is stopping it on purpose (a grant-sync revocation stop) decides the
+ *  row's next state. The same hold is the single-flight of a node's stop across processes: one
+ *  holder at a time, and a holder that died frees the node when the hold expires. */
+export declare const RECOVERY_HOLD_MS: number;
+/** A stop's claim on a node. It renews itself every third of the hold's length while the stop runs, so a stop longer than
+ *  the hold never lets recovery restart the node; `renew` is also the fence a stop checks before each step it must not
+ *  repeat after losing the hold. */
+export interface RecoveryHold {
+    /** Extends the hold; false when it lapsed and another stop took it (or its expiry passed). */
+    renew(): Promise<boolean>;
+    release(): Promise<void>;
+}
+/** Claims the hold for a fresh owner token, or null when another stop holds the node. A holder that overran its expiry
+ *  cannot renew or release a successor's hold: both match the owner token. */
+export declare function holdRecovery(nodeId: string): Promise<RecoveryHold | null>;
+export declare function isRecoveryHeld(nodeId: string): Promise<boolean>;
+/** Waits until no stop holds the node. `lapsed` means the last holder never released (it died or stalled past expiry), so
+ *  the stop it was running did not finish; `released` means it finished and cleared the hold itself. */
+export declare function waitForRecoveryHold(nodeId: string): Promise<'released' | 'lapsed'>;

package/dist/core/runtime/recovery-hold.js

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { openDb } from '../canvas/db.js';
+/** A stop in progress on a node, held on the node's row (`recovery_held_until`, `recovery_held_by`).
+ *  Dead-row recovery leaves a held node alone, so the broker's exit cannot be read as a crash and
+ *  resumed before the caller that is stopping it on purpose (a grant-sync revocation stop) decides the
+ *  row's next state. The same hold is the single-flight of a node's stop across processes: one
+ *  holder at a time, and a holder that died frees the node when the hold expires. */
+export const RECOVERY_HOLD_MS = 5 * 60_000;
+/** Claims the hold for a fresh owner token, or null when another stop holds the node. A holder that overran its expiry
+ *  cannot renew or release a successor's hold: both match the owner token. */
+export async function holdRecovery(nodeId) {
+    const owner = randomUUID();
+    const now = new Date();
+    const db = await openDb();
+    const claimed = await db.prepare(`UPDATE nodes SET recovery_held_until = ?, recovery_held_by = ?
+    WHERE node_id = ? AND (recovery_held_until IS NULL OR recovery_held_until <= ?)`)
+        .run(new Date(now.getTime() + RECOVERY_HOLD_MS).toISOString(), owner, nodeId, now.toISOString());
+    if (claimed.changes !== 1)
+        return null;
+    const renew = async () => {
+        const at = new Date();
+        return (await (await openDb()).prepare('UPDATE nodes SET recovery_held_until = ? WHERE node_id = ? AND recovery_held_by = ? AND recovery_held_until > ?')
+            .run(new Date(at.getTime() + RECOVERY_HOLD_MS).toISOString(), nodeId, owner, at.toISOString())).changes === 1;
+    };
+    const timer = setInterval(() => { void renew().catch(() => undefined); }, RECOVERY_HOLD_MS / 3);
+    timer.unref();
+    return {
+        renew,
+        release: async () => {
+            clearInterval(timer);
+            await (await openDb()).prepare('UPDATE nodes SET recovery_held_until = NULL, recovery_held_by = NULL WHERE node_id = ? AND recovery_held_by = ?').run(nodeId, owner);
+        },
+    };
+}
+export async function isRecoveryHeld(nodeId) {
+    return await (await openDb()).prepare('SELECT 1 AS held FROM nodes WHERE node_id = ? AND recovery_held_until > ?')
+        .get(nodeId, new Date().toISOString()) !== undefined;
+}
+/** Waits until no stop holds the node. `lapsed` means the last holder never released (it died or stalled past expiry), so
+ *  the stop it was running did not finish; `released` means it finished and cleared the hold itself. */
+export async function waitForRecoveryHold(nodeId) {
+    while (await isRecoveryHeld(nodeId))
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    const row = await (await openDb()).prepare('SELECT recovery_held_by FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.recovery_held_by == null ? 'released' : 'lapsed';
+}

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

@@ -0,0 +1,49 @@
+/** Validate a target is NOT latched (the ordinary, non-reopen doorway). Reads
+ *  `final_report` fresh — never a caller-supplied snapshot. Throws
+ *  `node_finalized` when latched; otherwise a no-op (the common case). No
+ *  side effect either way. */
+export declare function assertNotFinalized(nodeId: string): Promise<void>;
+/** Validate a target IS latched (the `--reopen` doorway) and return the exact
+ *  `final_report` value observed, so the caller can CAS-clear it later via
+ *  `commitReopen` — once every OTHER fallible precondition the requested
+ *  operation needs has already passed (e.g. `--fresh`'s recoverable-state
+ *  check). Throws `not_finalized` when the target has nothing to clear. Pure
+ *  read — never mutates. */
+export declare function assertFinalizedForReopen(nodeId: string): Promise<string>;
+/** Clear `nodeId`'s finalization latch — retract-pointer-only (only
+ *  `final_report`/`finalized_at`; the report file and every delivered feed
+ *  event are untouched). CAS'd against `expectedFinalReport` (the value the
+ *  caller observed via `assertFinalizedForReopen`): if the row no longer
+ *  matches — a concurrent `--reopen` already cleared it, or (impossible
+ *  without a reopen in between, but defended anyway) a fresh final landed —
+ *  this throws `reopen_latch_changed` instead of silently clobbering a newer
+ *  canonical result. Callers MUST NOT proceed to revive/deliver when this
+ *  throws. */
+export declare function commitReopen(nodeId: string, expectedFinalReport: string): Promise<void>;
+/** Commit the wider message-delivery reopen: settle the node's lifecycle, then
+ * retract a final latch when one exists. Unlike the revive/fresh gate, an
+ * unlatched node is valid here.
+ *
+ * Lifecycle rule: resident is for a node with no manager to report to (an app
+ * or person conversation, e.g. a hosted SMS thread reopened by a new text), so
+ * a reopen by a person, an app run, or a node that is not the target's manager
+ * makes the target resident. When `callerNodeId` is a node that is a tree
+ * subscriber of the target (its parent/manager re-tasking its own child), the
+ * target keeps its current lifecycle: a terminal child stays terminal and keeps
+ * owing a final report, which is what wakes the manager. Either way the final
+ * latch is cleared and a done/canceled/dead row returns to active.
+ *
+ * Writing lifecycle first leaves a failed latch CAS with the canonical-final
+ * pointer intact. Both writes finish before either delivery channel begins. */
+export declare function commitReopenResident(nodeId: string, expectedFinalReport?: string, callerNodeId?: string | null): Promise<string | null>;
+/** Convenience wrapper for a doorway with NO intervening fallible step between
+ *  the gate check and the reopen clear (`node lifecycle revive` has nothing
+ *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,
+ *  clears in one call.
+ *
+ *  - `reopen` false + latched → throws `node_finalized`.
+ *  - `reopen` true + latched → settles lifecycle per `commitReopenResident` (resident, unless `callerNodeId` is the target's manager),
+ *    CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + not latched → throws `not_finalized`.
+ *  - `reopen` false + not latched → no-op (the common case). */
+export declare function assertReopenGate(nodeId: string, reopen: boolean, callerNodeId?: string | null): Promise<void>;

package/dist/core/runtime/reopen.js

@@ -0,0 +1,160 @@
+// The re-task/reopen gate — enforced at every doorway that can revive a
+// node: `node message send` immediate delivery, `node wait deadline`, and
+// `node lifecycle revive`.
+//
+// `final_report` is a write-once latch (`feed.ts`'s `commitCanonicalFinal`);
+// nothing else ever clears it. Reviving a latched node without reconciling
+// that latch hands it a mandate whose only completion verb — `push final` —
+// is guaranteed to error against the still-set column. So every doorway
+// refuses instead of silently reviving; the refusal names the one remedy,
+// `--reopen`, which clears ONLY the live pointer (retract-pointer-only — the
+// report file on disk and every already-delivered feed event are untouched)
+// so the node's next real `push final` re-latches through the normal
+// `WHERE final_report IS NULL` guard.
+//
+// Concurrency: every check here reads `final_report` FRESH from
+// the DB — never a caller-cached snapshot from an earlier point in the
+// command — and the actual clear is a compare-and-swap (`UPDATE ... WHERE
+// final_report = <the exact value just observed>`), mirroring the CAS
+// `commitCanonicalFinal` already uses in feed.ts and the `BEGIN
+// IMMEDIATE`-guarded critical section `reviveNode` already uses in revive.ts.
+// This closes two races a stale-snapshot + unconditional clear left open:
+//   1. Two concurrent `--reopen` calls both observe final A. The first clears
+//      and revives; the node produces a NEW final B. The second (delayed)
+//      call's clear, if unconditional, would erase B. CAS-conditioning the
+//      UPDATE on the specific value each caller observed makes the second
+//      call's compare fail (0 rows) instead of clobbering B — it throws
+//      `reopen_latch_changed` and must NOT proceed to revive/deliver.
+//   2. A target finalizes AFTER a NO-reopen caller's gate check but BEFORE its
+//      delivery/revive actually runs — reviveNode's own belt-and-suspenders
+//      check (revive.ts, same `BEGIN IMMEDIATE` section as the double-launch
+//      guard) refuses to revive a node whose `final_report` is set, closing
+//      the remaining window as close to the true side effect as the codebase
+//      already gets for the double-launch race this pattern was modeled on.
+//
+// `assertFinalizedForReopen`/`commitReopen` are deliberately split (not one
+// check-and-clear call) so a caller with an intervening fallible precondition
+// (such as fresh-revive's recoverable-state check) can validate BEFORE
+// mutating the live pointer — the explicit operation must not retract a
+// canonical final unless it can actually enact the requested re-task.
+import { clearFinalReportIfMatches, getFinalReport, getNode, updateNode } from '../canvas/index.js';
+import { subscribersOf } from '../canvas/tree.js';
+import { InputError } from '../io.js';
+import { transition } from './lifecycle.js';
+import { noticeChangedWhileDone } from './ledger.js';
+async function currentFinalReport(nodeId) {
+    return await getFinalReport(nodeId);
+}
+function throwNodeFinalized(nodeId, finalReport) {
+    throw new InputError({
+        error: 'node_finalized',
+        message: `${nodeId} already submitted its canonical final result (\`crtr canvas read ${nodeId}/${finalReport}\`) — reviving it now would hand it a mandate it can never finish, since a second \`push final\` always errors against an already-latched node.`,
+        next: `Re-run this exact command with --reopen to clear ${nodeId}'s spent latch and re-task it in place.`,
+    });
+}
+function throwNotFinalized(nodeId) {
+    throw new InputError({
+        error: 'not_finalized',
+        message: `${nodeId} is not finalized — --reopen has nothing to clear.`,
+        next: 'Drop --reopen.',
+    });
+}
+/** Validate a target is NOT latched (the ordinary, non-reopen doorway). Reads
+ *  `final_report` fresh — never a caller-supplied snapshot. Throws
+ *  `node_finalized` when latched; otherwise a no-op (the common case). No
+ *  side effect either way. */
+export async function assertNotFinalized(nodeId) {
+    const finalReport = await currentFinalReport(nodeId);
+    if (finalReport !== null)
+        throwNodeFinalized(nodeId, finalReport);
+}
+/** Validate a target IS latched (the `--reopen` doorway) and return the exact
+ *  `final_report` value observed, so the caller can CAS-clear it later via
+ *  `commitReopen` — once every OTHER fallible precondition the requested
+ *  operation needs has already passed (e.g. `--fresh`'s recoverable-state
+ *  check). Throws `not_finalized` when the target has nothing to clear. Pure
+ *  read — never mutates. */
+export async function assertFinalizedForReopen(nodeId) {
+    const finalReport = await currentFinalReport(nodeId);
+    if (finalReport === null)
+        throwNotFinalized(nodeId);
+    return finalReport;
+}
+/** Clear `nodeId`'s finalization latch — retract-pointer-only (only
+ *  `final_report`/`finalized_at`; the report file and every delivered feed
+ *  event are untouched). CAS'd against `expectedFinalReport` (the value the
+ *  caller observed via `assertFinalizedForReopen`): if the row no longer
+ *  matches — a concurrent `--reopen` already cleared it, or (impossible
+ *  without a reopen in between, but defended anyway) a fresh final landed —
+ *  this throws `reopen_latch_changed` instead of silently clobbering a newer
+ *  canonical result. Callers MUST NOT proceed to revive/deliver when this
+ *  throws. */
+export async function commitReopen(nodeId, expectedFinalReport) {
+    const cleared = await clearFinalReportIfMatches(nodeId, expectedFinalReport);
+    if (!cleared) {
+        throw new InputError({
+            error: 'reopen_latch_changed',
+            message: `${nodeId}'s finalization latch changed since it was last inspected — a concurrent --reopen (or a fresh push final) already moved it, so clearing it now would risk erasing a newer canonical result.`,
+            next: 'Re-run this exact command — it will re-inspect the current state before acting.',
+        });
+    }
+}
+/** True when `callerNodeId` is a tree subscriber of `nodeId` — its parent or
+ *  manager (`subscribersOf`). Only such a caller re-tasks a node it already owes
+ *  a report to. */
+async function isManagerOf(callerNodeId, nodeId) {
+    if (callerNodeId === null || callerNodeId === undefined)
+        return false;
+    return (await subscribersOf(nodeId)).some((subscriber) => subscriber.node_id === callerNodeId);
+}
+/** Commit the wider message-delivery reopen: settle the node's lifecycle, then
+ * retract a final latch when one exists. Unlike the revive/fresh gate, an
+ * unlatched node is valid here.
+ *
+ * Lifecycle rule: resident is for a node with no manager to report to (an app
+ * or person conversation, e.g. a hosted SMS thread reopened by a new text), so
+ * a reopen by a person, an app run, or a node that is not the target's manager
+ * makes the target resident. When `callerNodeId` is a node that is a tree
+ * subscriber of the target (its parent/manager re-tasking its own child), the
+ * target keeps its current lifecycle: a terminal child stays terminal and keeps
+ * owing a final report, which is what wakes the manager. Either way the final
+ * latch is cleared and a done/canceled/dead row returns to active.
+ *
+ * Writing lifecycle first leaves a failed latch CAS with the canonical-final
+ * pointer intact. Both writes finish before either delivery channel begins. */
+export async function commitReopenResident(nodeId, expectedFinalReport, callerNodeId) {
+    const finalReport = await currentFinalReport(nodeId);
+    if (!(await isManagerOf(callerNodeId, nodeId)))
+        await updateNode(nodeId, { lifecycle: 'resident' });
+    // A reopened node that is still parked in a terminal status has to come back
+    // to `active`, or its row keeps claiming it is finished while a broker runs
+    // its new mandate. Gated on terminal so a message landing on a live node
+    // never rewrites the intent it is working under.
+    const meta = await getNode(nodeId);
+    if (meta !== null && (meta.status === 'done' || meta.status === 'canceled' || meta.status === 'dead')) {
+        if (meta.status === 'done' && meta.last_settled_at != null)
+            await noticeChangedWhileDone(nodeId, meta.last_settled_at);
+        await transition(nodeId, 'revive');
+    }
+    if (finalReport !== null)
+        await commitReopen(nodeId, expectedFinalReport ?? finalReport);
+    return finalReport;
+}
+/** Convenience wrapper for a doorway with NO intervening fallible step between
+ *  the gate check and the reopen clear (`node lifecycle revive` has nothing
+ *  fallible between the gate and `reviveNode`). Validates and, when `reopen`,
+ *  clears in one call.
+ *
+ *  - `reopen` false + latched → throws `node_finalized`.
+ *  - `reopen` true + latched → settles lifecycle per `commitReopenResident` (resident, unless `callerNodeId` is the target's manager),
+ *    CAS-clears the latch (side effect) and returns.
+ *  - `reopen` true + not latched → throws `not_finalized`.
+ *  - `reopen` false + not latched → no-op (the common case). */
+export async function assertReopenGate(nodeId, reopen, callerNodeId) {
+    if (reopen) {
+        const expectedFinalReport = await assertFinalizedForReopen(nodeId);
+        await commitReopenResident(nodeId, expectedFinalReport, callerNodeId);
+        return;
+    }
+    await assertNotFinalized(nodeId);
+}

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

@@ -0,0 +1,114 @@
+import { type NodeMeta } from '../canvas/index.js';
+import type { WakeOrigin } from './bearings.js';
+/** A true session resume normally needs no prompt. A broker-certified runtime
+ * abort is the one exception: continue the persisted transcript with a factual
+ * warning rather than creating a fresh cycle. */
+export type ReviveWakeReason = WakeOrigin | 'runtime-restart-abort';
+import { processRunner } from './runner/process.js';
+/** Pick the `--session` source for a revive. Both resume=true (a true resume)
+ *  and resume=false (a refresh-yield) resume by the absolute session-file path
+ *  (immune to cwd; pi opens it directly) — but ONLY when that file actually
+ *  exists on disk. A node's `pi_session_file` can be recorded in meta with
+ *  nothing ever written there (e.g. its first-boot engine died before
+ *  session_start ever ran), and `headlessBrokerHost.launch`'s preflight
+ *  (host.ts) fatally rejects handing pi a `--session` for a missing path OR a
+ *  bare id — either would crash the revive and strand the node dead with
+ *  nothing to recover it. So when there is no real `.jsonl` to resume, this
+ *  selects NEITHER source regardless of `resume`: the caller then falls
+ *  through to a truly fresh (`--fresh`-equivalent) launch, which is always
+ *  safe. The only difference between the two `resume` values (when the file
+ *  DOES exist) is `newCycle`: resume=false additionally roots a fresh cycle
+ *  branch (`--crtr-new-cycle`) rather than continuing the existing leaf. Pure
+ *  so the decision is unit-testable without tmux or a real filesystem fixture
+ *  beyond a temp file. */
+export declare function resumeArgs(meta: NodeMeta, resume: boolean): Promise<{
+    resumeSessionPath?: string;
+    newCycle?: boolean;
+}>;
+/** Whether a fresh context window would have anything on disk to stand on: a
+ *  goal, a roadmap, or both. The negative is what makes a fresh cycle worse
+ *  than a resume — the new window would wake amnesiac, with no statement of
+ *  what it is for. Read by the parked-resident veto below and by the message
+ *  handler's explicit fresh-revive gate. */
+export declare function hasFreshGroundState(nodeId: string): Promise<boolean>;
+export interface ReviveResult {
+    /** Always null — the broker engine is never placed in a tmux window. Kept on
+     *  the result for caller back-compat. */
+    window: string | null;
+    /** The node's last live LOCATION session, or null — the broker engine has no
+     *  tmux session of its own (it opens no viewer). Kept for caller back-compat. */
+    session: string | null;
+    /** True only for a TRUE resume — pi replays the saved conversation history
+     *  from its absolute session-file path. False for a fresh launch AND for an
+     *  in-place cycle (which also passes `--session <path>`, but to open a new
+     *  branch rather than replay the old one). */
+    resumed: boolean;
+    /** Launch handle for the detached broker, so callers can fail fast on its real
+     *  exit before the socket appears. */
+    launch?: Awaited<ReturnType<typeof processRunner.start>>;
+    /** Reads a fatal launch fault recorded by THIS revive attempt, scoped via
+     *  `beginBootFaultAttempt` at the exact clear-then-launch boundary below.
+     *  Present only when a fresh launch actually happened (absent on the
+     *  double-revive no-op, where nothing was cleared or relaunched). */
+    faultExplanation?: () => Promise<string | null>;
+    /** What this call actually did. `already-live` means a broker was already
+     *  running for the node and nothing was launched; `frozen` means no slot was
+     *  free and the row is now waiting for one — the tick thaws it. */
+    outcome: ReviveOutcome;
+}
+export type ReviveOutcome = 'launched' | 'already-live' | 'frozen';
+export type AttachReviveDecision = {
+    parked: true;
+} | {
+    parked: false;
+    result: ReviveResult;
+};
+interface ReviveOptions {
+    resume: boolean;
+    capacity: ReviveCapacityPolicy;
+    wakeReason?: ReviveWakeReason;
+    recovery?: boolean;
+    /** Set only by {@link decideAttachRevive}: a viewer attach/focus launched
+     *  this broker so a person can look. Like `recovery`, it is NOT a wake. */
+    viewerAttach?: boolean;
+}
+/** What a caller wants when the broker cap is full. `freeze` suits a caller
+ *  whose reason to run survives waiting (durable mail, a cron sink, a recovery
+ *  respawn): the row is marked frozen and the tick relaunches it when a slot
+ *  frees. `refuse` suits a caller that must have a live broker NOW (an attach,
+ *  a bridge, a companion bind) and can only report the refusal. */
+export type ReviveCapacityPolicy = 'freeze' | 'refuse';
+/** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
+ *  meta. Opens no viewer (engine-only).
+ *
+ *  `recovery: true` marks a launch that only replaces a broker instance which
+ *  died or was torn down — the daemon's respawn after a broker exit, and the
+ *  `reviveAll` sweep over disconnected nodes. Nothing external arrived for the
+ *  node, so such a launch is NOT a wake and does not consume the node's armed
+ *  deadline (see the consumeDeadlineOnWake call below). A viewer attach (the
+ *  `viewerAttach` flag {@link decideAttachRevive} sets) is not a wake either.
+ *
+ *  Throws if the node does not exist. All other failures propagate as-is —
+ *  callers (daemon, command) decide how to handle.
+ */
+export declare function reviveNode(nodeId: string, opts: ReviveOptions): Promise<ReviveResult>;
+/** The attach-specific entry to the revive boundary. A focus viewer may decline
+ * to wake an exact parked resident while preserving the ordinary activating
+ * attach default. The fleet check and parked decision are synchronous with the
+ * launch below, so an already-running broker wins before dormancy is observed.
+ *
+ * Attaching only to look is not a wake: every launch through this entry is
+ * marked `viewerAttach`, so it leaves the node's armed `node wait deadline`
+ * cron in place. Anything the person types reaches the node as a message, and
+ * that delivery is the wake that consumes the deadline. */
+export declare function decideAttachRevive(nodeId: string, opts: Omit<ReviveOptions, 'viewerAttach'>, wakeParked: boolean): Promise<AttachReviveDecision>;
+/** A recorded cwd that no longer exists (e.g. a closed managed worktree whose tombstone dir was later
+ *  reaped) can never host a launch. Fail loud with a typed, user-visible error naming the path instead
+ *  of letting `headlessBrokerHost.launch` fail deep inside the crash/doctrine-wake catch, where it would
+ *  surface as an opaque `internal error` (toErrorBody masks every 5xx). Callers admit work to a node
+ *  with this before changing any state. Returns where the node runs: its Blaxel environment (null on a machine) and whether a remote machine hosts it. */
+export declare function assertRecordedCwdExists(nodeId: string, meta: NodeMeta): Promise<{
+    blaxelEnvironment: string | null;
+    remoteMachine: boolean;
+}>;
+export {};