@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/delegation/process-liveness.d.ts

@@ -0,0 +1,98 @@
+import { parseProcStat, processStartToken } from '../detached-process.ts';
+/**
+ * Synchronous process evidence for worker recovery and resource cleanup. Unreadable cwd is no
+ * evidence; other uncertainty stays alive or unknown, never proven gone.
+ */
+export { parseProcStat, processStartToken };
+/** `pgid`: the session leader leads its own process group (hearsay-tools/cezarion#890). */
+export type RecordedProcess = {
+    pid: number;
+    startToken?: string | undefined;
+    pgid?: number | undefined;
+};
+export type WorkerProcessRecord = {
+    generation: string;
+    controller: RecordedProcess;
+    processes: RecordedProcess[];
+};
+export type GenerationLiveness = 'gone' | 'alive' | 'unknown';
+/** A different recorded Linux boot proves every original process group ended. */
+export declare function processPredatesCurrentBoot(entry: RecordedProcess): boolean;
+/** Live and the same incarnation. A token-less entry (or an unreadable current token) counts while the PID exists. */
+export declare function recordedProcessLive(entry: RecordedProcess): boolean;
+/** Whether a recorded session leader's group may be signalled (hearsay-tools/cezarion#890). A live
+ * leader must be the exact recorded incarnation; a different one means the group emptied and its
+ * number was reused. A dead leader proves nothing: its number may since have been reused, and a
+ * double-fork daemon leaves exactly a live group with a dead leader. Such a group is signalled
+ * only when it holds the worker's paths: `holderGroups` are the groups of those holders. */
+export declare function recordedGroupSignalable(entry: RecordedProcess, holderGroups?: readonly number[]): boolean;
+export declare function isCurrentProcess(entry: RecordedProcess): boolean;
+/** The `/proc` reads the Linux scan makes; injectable for platform/error boundary coverage. */
+export type ProcReader = {
+    readdir: () => string[];
+    readlink: (pid: string) => string;
+};
+/** The darwin scan: `lsof` for working directories, of every process or of one. */
+export type DarwinReader = {
+    lsof: () => {
+        ok: boolean;
+        stdout: string;
+    };
+    lsofPid?: (pid: number) => {
+        ok: boolean;
+        stdout: string;
+    };
+};
+/** Each other process's readable working directory, by pid, or `unknown` when none can be listed. */
+export type CwdSnapshot = ReadonlyMap<number, string> | 'unknown';
+/** A snapshot taken on first use. Shared only inside one synchronous reprobe tick, never across
+ * a yield; destroy, admission and history deletion scan fresh (hearsay-tools/cezarion#879). */
+export type CwdSource = () => CwdSnapshot;
+/** Every other process's readable working directory, in one scan pass; `unknown` when the
+ * processes cannot be listed at all. An unreadable cwd is no evidence (hearsay-tools/cezarion#889):
+ * a process that vanished, another user's, or a non-dumpable one of ours (login `sshd`,
+ * `systemd --user`, `gpg-agent`, which every host has) is skipped, as `lsof` skips what it cannot
+ * read. win32 has no cwd scan and answers none: Windows refuses to delete a directory a process
+ * holds, so the checked removal is the proof there, beside the recorded processes. */
+export declare function scanProcessCwds(platform?: NodeJS.Platform, proc?: ProcReader, darwin?: DarwinReader): CwdSnapshot;
+/** One lazy `scan`, memoized for the life of the returned source. */
+export declare function sharedCwdScan(scan?: () => CwdSnapshot): CwdSource;
+/** PIDs (never this process) whose readable working directory is one of `dirs` or beneath it,
+ * from `cwds` when the caller shares a snapshot, else from a fresh scan. cezar's own short-lived
+ * git children in a worktree make this read "alive" briefly: conservative, and a retry self-heals. */
+export declare function processesWithCwdUnder(dirs: string | readonly string[], platform?: NodeJS.Platform, proc?: ProcReader, darwin?: DarwinReader, cwds?: CwdSnapshot): number[] | 'unknown';
+/** Whether one process's working directory is still one of `dirs` or beneath it, without a scan:
+ * one `readlink` on Linux, one `lsof` of that process on darwin. `false` when it moved away or
+ * cannot be read (no evidence, hearsay-tools/cezarion#889); `undefined` on win32, whose scan names
+ * no holder in the first place. */
+export declare function processCwdUnder(pid: number, dirs: readonly string[], platform?: NodeJS.Platform, proc?: ProcReader, darwin?: DarwinReader): boolean | undefined;
+export type GenerationProbe = {
+    liveness: GenerationLiveness;
+    controller?: number;
+    pids: number[];
+};
+/** Fresh resource proof for destroy, reuse, admission, scratch cleanup and history deletion.
+ * Controller boot says nothing about who holds persistent paths, so it always scans. A process
+ * blocks only when its readable cwd is under `paths`, when it is a live recorded process of the
+ * generation, or when it is a live foreign controller (hearsay-tools/cezarion#889). `paths` are
+ * the worktree and every scratch location; a missing record (legacy) relies on the scan alone.
+ * A live foreign controller short-circuits the scan; otherwise `pids` names every holder.
+ * `cwds` is a reprobe tick's shared snapshot (hearsay-tools/cezarion#879); without it, it scans. */
+export declare function inspectGeneration({ record, paths, cwds }: {
+    record?: WorkerProcessRecord;
+    paths: readonly string[];
+    cwds?: CwdSource | undefined;
+}): GenerationProbe;
+export declare function probeGeneration(input: {
+    record?: WorkerProcessRecord;
+    paths: readonly string[];
+}): GenerationLiveness;
+/** Execution-only proof: a known reboot ended all old descendants, provided neither the
+ * controller nor any recorded process is still live. Never use this to authorize reuse/deletion;
+ * execution settlement itself deletes nothing. Legacy or unknown boot evidence keeps the descendant scan. */
+export declare function inspectExecutionGeneration(input: {
+    record?: WorkerProcessRecord;
+    paths: readonly string[];
+    pathsComplete?: boolean;
+    cwds?: CwdSource | undefined;
+}): GenerationProbe;

package/dist/delegation/process-liveness.js

@@ -0,0 +1,213 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { exitedStat, linuxBootId, parseProcStat, processStartToken } from '../detached-process.js';
+/**
+ * Synchronous process evidence for worker recovery and resource cleanup. Unreadable cwd is no
+ * evidence; other uncertainty stays alive or unknown, never proven gone.
+ */
+// A process's start identity lives with the helper that starts detached processes (hearsay-tools/cezarion#1717).
+export { parseProcStat, processStartToken };
+function pidExists(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+    if (process.platform !== 'linux')
+        return true;
+    // A zombie leader can still have live threads. Unreadable stat is not proof of exit.
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return !exitedStat(stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/));
+    }
+    catch {
+        return true;
+    }
+}
+const LINUX_TOKEN = /^(?:[0-9a-f-]{36}:)?(\d+)$/;
+const LINUX_BOOT_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+/** A known different boot proves that no descendant of this controller can still exist. */
+function controllerPredatesBoot(token, boot) {
+    const recordedBoot = token?.match(/^(.+):\d+$/)?.[1];
+    return recordedBoot !== undefined && boot !== undefined && LINUX_BOOT_ID.test(recordedBoot) && LINUX_BOOT_ID.test(boot) && recordedBoot !== boot;
+}
+/** A different recorded Linux boot proves every original process group ended. */
+export function processPredatesCurrentBoot(entry) {
+    return process.platform === 'linux' && controllerPredatesBoot(entry.startToken, linuxBootId());
+}
+/** Liveness-only comparison: when exactly one Linux token lacks the boot id (it was unreadable on one
+ * side), the `starttime` suffix decides. Reaping still requires an exact match. */
+function sameIncarnation(recorded, current) {
+    if (recorded === current)
+        return true;
+    const a = LINUX_TOKEN.exec(recorded), b = LINUX_TOKEN.exec(current);
+    return !!a && !!b && recorded.includes(':') !== current.includes(':') && a[1] === b[1];
+}
+/** Live and the same incarnation. A token-less entry (or an unreadable current token) counts while the PID exists. */
+export function recordedProcessLive(entry) {
+    if (!pidExists(entry.pid))
+        return false;
+    if (entry.startToken === undefined)
+        return true;
+    const current = processStartToken(entry.pid);
+    return current === undefined || sameIncarnation(entry.startToken, current);
+}
+/** Whether a recorded session leader's group may be signalled (hearsay-tools/cezarion#890). A live
+ * leader must be the exact recorded incarnation; a different one means the group emptied and its
+ * number was reused. A dead leader proves nothing: its number may since have been reused, and a
+ * double-fork daemon leaves exactly a live group with a dead leader. Such a group is signalled
+ * only when it holds the worker's paths: `holderGroups` are the groups of those holders. */
+export function recordedGroupSignalable(entry, holderGroups = []) {
+    if (entry.pgid === undefined || entry.pgid !== entry.pid)
+        return false;
+    if (pidExists(entry.pid))
+        return entry.startToken !== undefined && processStartToken(entry.pid) === entry.startToken;
+    return holderGroups.includes(entry.pgid);
+}
+export function isCurrentProcess(entry) {
+    if (entry.pid !== process.pid)
+        return false;
+    const own = processStartToken(process.pid);
+    return entry.startToken === undefined || own === undefined || sameIncarnation(entry.startToken, own);
+}
+const lsofCwd = (args, timeout) => {
+    const lsof = spawnSync('lsof', [...args, '-d', 'cwd', '-Fpn'], { encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024 });
+    // Status 1 is ordinary: some process was unreadable, and an unreadable cwd is no evidence.
+    return { ok: !lsof.error && (lsof.status === 0 || lsof.status === 1) && !!lsof.stdout, stdout: lsof.stdout ?? '' };
+};
+const realDarwin = {
+    lsof: () => lsofCwd(['-a'], 5_000),
+    lsofPid: pid => lsofCwd(['-a', '-p', String(pid)], 2_000),
+};
+const realProc = {
+    readdir: () => readdirSync('/proc'),
+    readlink: pid => readlinkSync(`/proc/${pid}/cwd`),
+};
+/** Every other process's readable working directory, in one scan pass; `unknown` when the
+ * processes cannot be listed at all. An unreadable cwd is no evidence (hearsay-tools/cezarion#889):
+ * a process that vanished, another user's, or a non-dumpable one of ours (login `sshd`,
+ * `systemd --user`, `gpg-agent`, which every host has) is skipped, as `lsof` skips what it cannot
+ * read. win32 has no cwd scan and answers none: Windows refuses to delete a directory a process
+ * holds, so the checked removal is the proof there, beside the recorded processes. */
+export function scanProcessCwds(platform = process.platform, proc = realProc, darwin = realDarwin) {
+    const found = new Map();
+    if (platform === 'win32')
+        return found;
+    if (platform === 'linux') {
+        let entries;
+        try {
+            entries = proc.readdir();
+        }
+        catch {
+            return 'unknown';
+        }
+        for (const entry of entries) {
+            if (!/^\d+$/.test(entry) || Number(entry) === process.pid)
+                continue;
+            try {
+                found.set(Number(entry), proc.readlink(entry));
+            }
+            catch { /* unreadable: no evidence */ }
+        }
+        return found;
+    }
+    if (platform !== 'darwin')
+        return 'unknown';
+    const lsof = darwin.lsof();
+    if (!lsof.ok)
+        return 'unknown';
+    let pid;
+    for (const line of lsof.stdout.split('\n')) {
+        if (line.startsWith('p'))
+            pid = Number(line.slice(1));
+        else if (line.startsWith('n') && pid !== undefined && pid !== process.pid)
+            found.set(pid, line.slice(1));
+    }
+    return found;
+}
+/** One lazy `scan`, memoized for the life of the returned source. */
+export function sharedCwdScan(scan = scanProcessCwds) {
+    let snapshot;
+    return () => snapshot ??= scan();
+}
+/** PIDs (never this process) whose readable working directory is one of `dirs` or beneath it,
+ * from `cwds` when the caller shares a snapshot, else from a fresh scan. cezar's own short-lived
+ * git children in a worktree make this read "alive" briefly: conservative, and a retry self-heals. */
+export function processesWithCwdUnder(dirs, platform = process.platform, proc = realProc, darwin = realDarwin, cwds) {
+    const snapshot = cwds ?? scanProcessCwds(platform, proc, darwin);
+    if (snapshot === 'unknown')
+        return 'unknown';
+    const targets = (typeof dirs === 'string' ? [dirs] : dirs).map(dir => { try {
+        return realpathSync(dir);
+    }
+    catch {
+        return resolve(dir);
+    } });
+    const under = (cwd) => { const path = cwd.replace(/ \(deleted\)$/, ''); return targets.some(target => path === target || path.startsWith(target + sep)); };
+    return [...snapshot].filter(([, cwd]) => under(cwd)).map(([pid]) => pid);
+}
+/** Whether one process's working directory is still one of `dirs` or beneath it, without a scan:
+ * one `readlink` on Linux, one `lsof` of that process on darwin. `false` when it moved away or
+ * cannot be read (no evidence, hearsay-tools/cezarion#889); `undefined` on win32, whose scan names
+ * no holder in the first place. */
+export function processCwdUnder(pid, dirs, platform = process.platform, proc = realProc, darwin = realDarwin) {
+    let cwd;
+    if (platform === 'linux') {
+        try {
+            cwd = proc.readlink(String(pid));
+        }
+        catch {
+            return false;
+        }
+    }
+    else if (platform === 'darwin') {
+        const lsof = darwin.lsofPid?.(pid);
+        cwd = lsof?.ok ? lsof.stdout.split('\n').find(line => line.startsWith('n'))?.slice(1) : undefined;
+        if (cwd === undefined)
+            return false;
+    }
+    else
+        return undefined;
+    const found = processesWithCwdUnder(dirs, platform, proc, undefined, new Map([[pid, cwd]]));
+    return found !== 'unknown' && found.length > 0;
+}
+/** Fresh resource proof for destroy, reuse, admission, scratch cleanup and history deletion.
+ * Controller boot says nothing about who holds persistent paths, so it always scans. A process
+ * blocks only when its readable cwd is under `paths`, when it is a live recorded process of the
+ * generation, or when it is a live foreign controller (hearsay-tools/cezarion#889). `paths` are
+ * the worktree and every scratch location; a missing record (legacy) relies on the scan alone.
+ * A live foreign controller short-circuits the scan; otherwise `pids` names every holder.
+ * `cwds` is a reprobe tick's shared snapshot (hearsay-tools/cezarion#879); without it, it scans. */
+export function inspectGeneration({ record, paths, cwds }) {
+    if (record && !isCurrentProcess(record.controller) && recordedProcessLive(record.controller))
+        return { liveness: 'alive', controller: record.controller.pid, pids: [] };
+    const recorded = record?.processes.filter(recordedProcessLive).map(entry => entry.pid) ?? [];
+    const scan = processesWithCwdUnder(paths, undefined, undefined, undefined, cwds?.());
+    const pids = [...new Set([...recorded, ...(scan === 'unknown' ? [] : scan)])];
+    return { liveness: pids.length ? 'alive' : scan === 'unknown' ? 'unknown' : 'gone', pids };
+}
+export function probeGeneration(input) {
+    return inspectGeneration(input).liveness;
+}
+/** Execution-only proof: a known reboot ended all old descendants, provided neither the
+ * controller nor any recorded process is still live. Never use this to authorize reuse/deletion;
+ * execution settlement itself deletes nothing. Legacy or unknown boot evidence keeps the descendant scan. */
+export function inspectExecutionGeneration(input) {
+    const record = input.record;
+    if (record && recordedProcessLive(record.controller))
+        return { liveness: 'alive', controller: record.controller.pid, pids: [] };
+    const pids = record?.processes.filter(recordedProcessLive).map(entry => entry.pid) ?? [];
+    if (pids.length)
+        return { liveness: 'alive', pids };
+    if (process.platform === 'linux' && controllerPredatesBoot(record?.controller.startToken, linuxBootId()))
+        return { liveness: 'gone', pids: [] };
+    const probe = inspectGeneration(input);
+    // Unknown scratch locations can hide a legacy descendant even when every known path is
+    // clear. Keep live PID diagnostics, but never turn a partial scan into proof of termination.
+    return probe.liveness === 'gone' && input.pathsComplete === false ? { liveness: 'unknown', pids: [] } : probe;
+}
+//# sourceMappingURL=process-liveness.js.map

package/dist/delegation/process-liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-liveness.js","sourceRoot":"","sources":["../../src/delegation/process-liveness.ts"],"names":[],"mappings":"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"}

package/dist/delegation/provision.d.ts

@@ -0,0 +1,36 @@
+import type { RunManager } from '../workflows/run.ts';
+import type { RunStore } from '../runs/store.ts';
+import { CredentialRegistry } from './credentials.ts';
+import { DelegationService, type DelegationProject } from './service.ts';
+export type DelegationSession = {
+    restrictCrossSessionMessaging: true;
+    env: Record<string, string>;
+    instructions: string;
+    revoke(): void;
+};
+export type DelegationProvisioner = (runId: string) => DelegationSession | undefined;
+export declare function bundledWorkerInvocation(command?: 'worker' | 'discover' | 'message'): string;
+export declare function provisionDelegationSession(options: {
+    projectId: string;
+    runId: string;
+    store: RunStore;
+    credentials: CredentialRegistry;
+    url: string;
+    rebrand?: boolean;
+}): DelegationSession | undefined;
+/** Owns one invisible loopback listener in this controller, for cockpit AND headless use. */
+export declare class DelegationController {
+    readonly service: DelegationService;
+    readonly credentials: CredentialRegistry;
+    private transport?;
+    private projects;
+    private closed;
+    private warned;
+    get url(): string | undefined;
+    static start(): Promise<DelegationController>;
+    private unavailable;
+    attachProject(project: DelegationProject & {
+        manager: Pick<RunManager, 'setDelegationProvisioner'>;
+    }): () => void;
+    close(): Promise<void>;
+}

package/dist/delegation/provision.js

@@ -0,0 +1,218 @@
+import { commandText } from '../home/command.js';
+import { productEnvEntries } from '../core/product-env.js';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { CredentialRegistry } from './credentials.js';
+import { messagingAllowed, workersAllowed } from '../contract/index.js';
+import { DelegationService, rootDelegation } from './service.js';
+import { WORKERS_OFF } from './policy.js';
+import { openCompletionRequests } from '../workflows/completion-policy.js';
+import { createDelegationRoutes } from './routes.js';
+import { createDelegationApp, startDelegationTransport } from './transport.js';
+import { delegationEndpoint } from './cli.js';
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export function bundledWorkerInvocation(command = 'worker') {
+    // Source-mode dev uses this checkout's loader; a published installation needs only Node.
+    const source = import.meta.url.endsWith('.ts');
+    const entry = fileURLToPath(new URL(source ? '../index.ts' : '../index.js', import.meta.url));
+    return [process.execPath, ...(source ? ['--import', import.meta.resolve('tsx')] : []), entry].map(quote).join(' ') + ` ${command}`;
+}
+export function provisionDelegationSession(options) {
+    delegationEndpoint(options.url);
+    const run = options.store.getRun(options.runId);
+    if (!run || run.delegation?.role === 'invalid')
+        return;
+    const invocation = bundledWorkerInvocation();
+    const messaging = bundledWorkerInvocation('message');
+    const conversationGuidance = [
+        `Use ${messaging} for task conversations. Root tasks can message peer root tasks in the same project and their owned workers; workers may address only their parent. Use ${messaging} tasks [--all] [--offset <n>] to discover peers (32 per page); workers cannot list peers. Peer review/terminal tasks need their human to continue them; messages never resume a peer.`,
+        `Use ${messaging} request <recipient-run-id> '<text>' --id <message-UUID> to request an explicit reply; use ${messaging} progress <recipient-run-id> '<text>' --id <message-UUID> for an update without an obligation.`,
+        `Use ${messaging} follow-up <recipient-run-id> '<text>' --id <message-UUID> --request-id <request-UUID> to clarify your request, or ${messaging} reply <recipient-run-id> '<text>' --id <message-UUID> --request-id <request-UUID> to answer an incoming request.`,
+        `A request's ID is its message ID. Reuse a message ID only for an exact retry, including timeout; changed payloads are rejected.`,
+        `Messages reach the recipient's live session as soon as they are accepted, including mid-turn; they are read at its next model step. ${messaging} inbox remains a fallback read during an active turn; it acknowledges only the messages it returns. Use ${messaging} conversation <recipient-run-id> [--before <cursor>] for history or investigation; it does not acknowledge messages.`,
+        `Use ${messaging} conversation <recipient-run-id> [--before <cursor>] to inspect messages/outcomes, ${messaging} cancel-request <request-UUID> to cancel your obligation, and ${messaging} wait --request <request-UUID> [--request <another-UUID>] --mode <one|any|all> --timeout-seconds <1-1800> (or cezar_wait with kind "request") to register a request wait.`,
+        `A root task that waits for a peer to write uses ${messaging} wait --peer <task-id> [--peer <another-task-id>] --timeout-seconds <1-1800> (or cezar_wait with kind "peer"): a message from a named peer, or that peer settling, resolves it; workers cannot register it.`,
+        `Request and wait deadlines default to 600 seconds. Several waits can be open at once (workers, peers, CI, timers); messages wake you and close no wait, except a named peer's message to a peer wait; ${messaging} cancel-wait <wait-id> stops one wait without cancelling requests or work.`,
+        `Wait returns immediately: end your turn to release capacity; Messages wake you and close no wait; end the turn again to keep waiting. A message does not resolve a pending request: only its reply does.`,
+        `Acceptance, provider delivery, explicit reply, and task completion are distinct. Only reply resolves a request as replied; a reply after deadline expiry amends timed-out to replied-late without reopening the obligation; other settled outcomes stay unchanged.`,
+        `Parents can resume their settled done/review/failed worker by sending a new instruction with ${invocation} resume <worker-id> '<instruction>' --id <new-message-UUID> --timeout-seconds <1-86400>. A resume request stays pending until reply, lifecycle settlement or its deadline (default 600 seconds, maximum 86400 seconds / 24 hours); set e.g. --timeout-seconds 7200 for a two-hour review round. Extended deadlines require actually resuming a settled worker; active workers still accept at most 1800 seconds. A worker wait has its own deadline and never extends the request. Exact retries never create another continuation.`,
+        `Ordinary requests to review/terminal recipients return not-delivered with a reason and next command, and exit 1. Changing a rejected send requires a new message ID. Workers cannot resume parents; stopped/destroyed workers need a new worker. Messages never answer a human's question; a parent's reply answers only its worker's routed question.`,
+        `Pending conversations are submitted together within a 100,000-character batch limit. Each keeps its own ID and request outcome; receipts report queued, delivered and consumed separately. A wait refusal explains why; successful registration parks only when you end your turn.`,
+        `At most 100,000 characters per message, 32 undelivered inputs per recipient, 1,024 family messages, and 32 pending requests. Peer messages count toward the ledger and recipient input caps. A peer message that starts a new turn charges the automatic-wake budget (40 turns); when spent, messages stay queued until the human resets it. Steering inside a running turn and family messages do not charge.`,
+        `Controller persistence prevents duplicate queue entries; a crash between provider acceptance and its delivery checkpoint can still make delivery ambiguous.`,
+        `Credentials stay in the environment: never read, echo, forward, or persist them.`,
+    ].join(' ');
+    // hearsay-tools/cezarion#2279: native subagents are allowed; tasks talk only through cez message.
+    const subagentOnly = `You may use native subagents and message them with your runner's tools. No agent channel to another task exists: tell the user instead.`;
+    const subagentMessaging = [
+        `You may message your own native subagents with your runner's tools.`,
+        `Reach another Cezar task only through ${messaging}; never use your runner's native tools for that.`,
+    ].join(' ');
+    const worker = run.delegation?.role === 'worker';
+    const owned = run.delegation?.role === 'root' && run.delegation.receipts.length > 0;
+    // Accepted peer requests still allow a reply, a wait or a cancel after messaging goes off.
+    const open = openCompletionRequests(options.store, run.id);
+    const owesRequests = open.sent.length + open.incoming.length > 0;
+    const workersOn = workersAllowed(run);
+    const messagingOn = messagingAllowed(run);
+    // hearsay-tools/cezarion#2784: with both switches off, no worker receipt (a deleted worker's counts) and no open request, the session gets no
+    // credential; it keeps the governed-session cross-session controls (runner-specific, D1). The endpoint
+    // alone marks it as a controller-bound session, so `cez discover` refuses instead of falling
+    // back to the cockpit, as it does for any partial credential.
+    if (!worker && !workersOn && !messagingOn && !owned && !owesRequests) {
+        return { restrictCrossSessionMessaging: true, env: { ...productEnvEntries('DELEGATION_URL', options.url, options.rebrand) }, revoke: () => { },
+            instructions: `Cezar workers and task messaging are off for this task; a human can turn them on in the task menu, and they reach you at your next session. ${subagentOnly}` };
+    }
+    // Root authority is durable before a token exists. The switches never edit it: they are read per call.
+    if (!run.delegation)
+        options.store.commitDelegation([{ id: run.id, delegation: rootDelegation() }]);
+    const messagingOff = messagingOn ? [] : [`Task messaging is off for this task: you cannot list, message or wait on peer tasks; a human can turn it on in the task menu. Messages with your own workers, and replies to peer requests accepted earlier, still work.`];
+    const rootInstructions = () => workersOn ? [
+        `Use native subagents for work that needs no separate worktree: research, code reading and focused analysis.`,
+        `For example, a subagent reads the parser and summarizes how it handles errors.`,
+        `Use Cezar workers for work that needs its own worktree, its own commits or a lifecycle Cezar tracks.`,
+        `Also use a Cezar worker when the task needs a model available only through another runner, even if the work is research or analysis.`,
+        `Native subagents need no Cezar worker, worktree, collection or destruction.`,
+        subagentMessaging,
+        `Owned workers are available through the bundled command ${invocation}.`,
+        `Commands return JSON.`,
+        `Before choosing a runner, model or effort, use ${bundledWorkerInvocation('discover')} runners, then ${bundledWorkerInvocation('discover')} models --runner=<name>.`,
+        `Discovery lists host default-account runner status, enablement, model IDs and advertised per-model effortLevels; absent effort metadata means unknown. It uses your controller automatically.`,
+        `When overrides are allowed and effortLevels is nonempty, choose an explicit --effort level for the task from that list. Do not leave effort on auto by habit.`,
+        `A spawn --effort pin applies to every agent step whose effort is unset. Use a shared effort only when every affected step's model advertises that level; otherwise use a workflow with compatible per-step effort settings. A high-only model and a low-only model need separate step settings.`,
+        `An empty effortLevels list advertises no levels; absent metadata means support is unknown. Do not guess supported levels or override locked native settings.`,
+        `A fresh nonempty default-account catalog rejects unknown explicit default-account model pins before creating a worker and reports available models and alternative runners; unavailable, empty or stale discovery does not invent choices. Inherited defaults and accepted retries stay unchanged.`,
+        ...messagingOff,
+        conversationGuidance,
+        `Worker questions arrive as requests carrying a question; answer with ${messaging} reply <worker-id> '<answer>' --id <new-message-UUID> --request-id <question-id>, one '<header>: <answer>' line per question (an option's label, or your own words for a question without options), which the worker reads verbatim as its answer. If you cannot decide, ask the human with your own question, then reply. Progress and follow-ups never answer it, and you cannot finish while it is unanswered.`,
+        `Use ${invocation} spawn --baseline parent-head --request-id <UUID> '<task>' (or an explicit committed ref).`,
+        `Reuse the request ID only for the exact same task/baseline/context/runner/model/effort/workflow/skill on a retry.`,
+        `Optional spawn flags: --workflow <name> or --skill <name> (mutually exclusive), --context '<selected text>' or --context-file <local-UTF-8-file> (mutually exclusive), --attach <path> (repeatable; copies a git-ignored file from your worktree into the worker's worktree at the same relative path before it starts; tracked or unignored files and .gitignore are refused, commit those instead), --runner <claude|codex|opencode|pi|cursor|omp>, --model <model>, --effort <low|medium|high|xhigh|max|auto>.`,
+        `--workflow runs a catalog workflow (the built-in quick-task or a .ai/cezar/workflows/*.yaml name) inside the worker, agent and check steps alike; --skill runs one discovered skill as the worker task; omitting both means quick-task; a worker inherits your extra system prompt, never your selected skill.`,
+        `--runner, --model and --effort fill only the steps that leave those fields unset; an unknown name fails. Agent steps may mix runners: each step is pinned to its own runner, account, model, effort and grants at spawn, and a step's agentProfile names its account explicitly.`,
+        `Example: spawn --baseline parent-head --request-id <UUID> --runner codex --effort high --context 'Inspect only the parser' 'Review parser'. Use high here only when the selected model advertises it and overrides are allowed.`,
+        `Example: spawn --baseline parent-head --request-id <UUID> --workflow review 'Review the parser change'.`,
+        `Task plus context text is limited to 100,000 characters.`,
+        `The API also accepts up to 32 baseline-file, parent-attachment or parent-file references, with at most 8 MiB of copied attachments.`,
+        `Inspect reports worker-local input paths.`,
+        `Omitted --runner inherits the active parent's runner; same-runner workers inherit omitted model/account/effort, while mixed-runner workers use that runner's project/default account and model.`,
+        `Omitting --effort or using --effort auto applies the same rules: same-runner workers inherit the parent's effort; workers on another runner leave effort to that runner. Omission and auto do not clear an inherited effort pin.`,
+        `Accepted identity and grants remain fixed.`,
+        `Use list to find every worker you own, including incomplete cleanup with remaining resources. Use inspect <worker-id>, collect <worker-id>, steer <worker-id> '<text>', stop <worker-id>, destroy <worker-id>, diff <worker-id>, or wait <worker-id>... --mode <one|any|all> --timeout-seconds <1-1800>.`,
+        `Mode defaults to any; one requires one worker, all requires every selected worker to settle.`,
+        `cancel-wait <wait-id> stops one wait, is safe to retry, and never touches workers.`,
+        `Wait registers and returns immediately: end your turn to release capacity, then Cezar resumes you on a selected terminal outcome or deadline (default 600 seconds).`,
+        `Your other waits stay open beside it; timeout/cancellation reports partial outcomes and unresolved workers. The same wait is open to you as cezar_wait with kind "worker".`,
+        `When a worker you wait on parks before finishing, Cezar sends you a notice from it naming what it waits on, at most one per wait; like any message it wakes you and closes no wait.`,
+        `collect returns revision/status/settled plus typed summary/head/diff/artifacts availability and records the latest evidence under the parent.`,
+        `An available diff.path points to a JSON result file: read its diffSnapshot field for the bounded patch, not the file as a raw patch.`,
+        `Running output is partial.`,
+        `Collect the latest settled revision of every worker before completing; Continue invalidates older readiness.`,
+        `A done while workers are live or uncollected is refused once with what to do first; done again while workers are live makes Cezar wait on them for you and wake you when they have all settled, never silently finishing.`,
+        `If a parent is already under review, Continue the parent first, then the worker.`,
+        `Review changes and deliberately integrate desired worker commits with Git before cleanup; no automatic merge or review acceptance.`,
+        `Collect/integrate desired results, destroy owned resources, explicitly delete child histories through the cockpit/API, then delete parent history.`,
+        `Summary and bounded diff snapshots survive until parent deletion; general artifact bytes are not archived.`,
+        `Branch/path strings and SHAs are historical descriptors after removal.`,
+        `At most 32 outstanding workers (accepted, live, or not yet verifiably destroyed) and 1,024 creations per parent; destroy finished workers to free capacity. These limits bound resources and runaway spawning, not spending; 32 undelivered steering messages per worker.`,
+        `Review is a human gate.`,
+        `Destruction may be incomplete; inspect remaining resources and retry explicitly.`,
+        `Credentials are supplied only in the environment: never read, echo, forward or include them in commands, messages, prompts, events or files.`,
+        `Workers cannot spawn Cezar workers or message peers.`,
+        `This is cooperative local supervision, not process isolation.`,
+    ] : [
+        `Use native subagents for research, code reading and focused analysis.`,
+        subagentMessaging,
+        WORKERS_OFF,
+        ...(owned ? [`You still manage the workers you own with ${invocation} list, inspect, collect, steer, stop, destroy, diff and wait. Collect the latest settled revision of every worker before completing.`] : []),
+        ...messagingOff,
+        conversationGuidance,
+    ];
+    const generation = randomUUID();
+    const token = options.credentials.issue(options.projectId, run.id, generation);
+    options.store.registerSessionSecret(token);
+    return {
+        restrictCrossSessionMessaging: true,
+        env: { ...productEnvEntries('DELEGATION_URL', options.url, options.rebrand), ...productEnvEntries('DELEGATION_TOKEN', token, options.rebrand) },
+        instructions: run.delegation?.role === 'worker'
+            ? [
+                `You are an owned cezar worker. Your parent run ID is ${run.delegation.parentRunId}.`,
+                conversationGuidance,
+                `You cannot spawn Cezar workers. You cannot control peers, merge automatically, or accept your own review.`,
+                commandText(`Follow your assigned task and selected input context. Ask your parent with cez message request; any question you raise goes to your parent too, never to a human. Your parent answers or asks the human itself; do not wait for a human.`),
+                `You may use native subagents for research, code reading and focused analysis.`,
+                subagentMessaging,
+                `Commit reviewed work before your parent deliberately integrates it; report the summary, commits, tests and remaining concerns.`,
+                `When you park before finishing while your parent waits on you, Cezar tells your parent what you wait on and quotes your last message: end such a turn by saying what you wait on and what you have done.`,
+            ].join(' ')
+            : rootInstructions().join(' '),
+        revoke: () => options.credentials.revoke(run.id, generation),
+    };
+}
+/** Owns one invisible loopback listener in this controller, for cockpit AND headless use. */
+export class DelegationController {
+    service = new DelegationService();
+    credentials = new CredentialRegistry();
+    transport;
+    projects = new Map();
+    closed = false;
+    warned = false;
+    get url() { return this.transport?.url; }
+    static async start() {
+        const controller = new DelegationController();
+        // Always on since hearsay-tools/cezarion#2784: each task's switches gate workers and messaging.
+        try {
+            controller.transport = await startDelegationTransport(createDelegationApp(createDelegationRoutes(controller.service, controller.credentials)));
+        }
+        catch {
+            controller.unavailable();
+        }
+        return controller;
+    }
+    unavailable() {
+        if (!this.warned) {
+            this.warned = true;
+            console.warn('Delegation unavailable; ordinary runs remain enabled.');
+        }
+    }
+    attachProject(project) {
+        if (this.closed)
+            return () => { };
+        this.projects.get(project.id)?.detach();
+        const unregister = this.service.registerProject(project);
+        const clear = project.manager.setDelegationProvisioner(runId => {
+            if (this.closed || !this.transport)
+                return;
+            try {
+                return provisionDelegationSession({ projectId: project.id, runId, store: project.store, credentials: this.credentials, url: this.transport.url });
+            }
+            catch {
+                this.credentials.revoke(runId);
+                this.unavailable();
+                return;
+            }
+        });
+        const detach = () => {
+            clear();
+            unregister();
+            // By project, not by run: a credential outlives nothing the store has to list (#779).
+            this.credentials.revokeProject(project.id);
+            if (this.projects.get(project.id)?.detach === detach)
+                this.projects.delete(project.id);
+        };
+        this.projects.set(project.id, { project, detach });
+        return detach;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const { detach } of [...this.projects.values()])
+            detach();
+        this.credentials.close();
+        const transport = this.transport;
+        this.transport = undefined;
+        await transport?.close();
+    }
+}
+//# sourceMappingURL=provision.js.map

package/dist/delegation/provision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision.js","sourceRoot":"","sources":["../../src/delegation/provision.ts"],"names":[],"mappings":"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"}

package/dist/delegation/questions.d.ts

@@ -0,0 +1,24 @@
+import type { AgentInput, AskRequest, ConversationMessage, ConversationState } from '../contract/index.js';
+/** A worker's question travels to its owning parent as a conversation request (#505). Its ID
+ * derives from the worker and the ask's event seq, so routing it again after a restart finds
+ * the same message instead of asking twice. */
+export declare function questionMessage(input: {
+    workerRunId: string;
+    parentRunId: string;
+    askSeq: number;
+    request: AskRequest;
+    now: string;
+}): ConversationMessage;
+/** What the parent reads: the context, the questions, their options, and the exact reply command. */
+export declare function formatQuestionText(workerRunId: string, messageId: string, request: AskRequest): string;
+/** Only a reply naming this question answers it; progress and follow-ups never do. */
+export declare function answersQuestion(message: ConversationMessage, input: AgentInput): boolean;
+/** Routed questions still awaiting an answer. Each one holds a reserved conversation slot, and
+ * a slot in its worker's inbox, for its reply: otherwise ordinary traffic could fill both and
+ * leave a question nobody can answer (#505). */
+export declare function openQuestions(state: ConversationState): ConversationMessage[];
+/** Ledger room the open requests hold for their replies: every accepted request with no outcome,
+ *  a worker's question among them (hearsay-tools/cezarion#1990 review). A reply spends its own. */
+export declare function reservedReplies(state: ConversationState): number;
+/** A UUID-shaped (version 4 layout) identifier derived from a stable key. */
+export declare function uuidFrom(key: string): string;