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

package/dist/delegation/routes.js

@@ -0,0 +1,85 @@
+import { WaitDeadlineConflict } from '../ci-wait/errors.js';
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { ZodError } from 'zod';
+import { z } from 'zod';
+import { discoveryRequestSchema } from '../contract/index.js';
+import { conversationSendRequestSchema, conversationInspectRequestSchema, conversationCancelRequestSchema, inboxReceiptRequestSchema, requestWaitRequestSchema } from '../contract/index.js';
+import { workerListQuerySchema, workerCancelWaitRequestSchema, workerSpawnRequestSchema, workerSteerRequestSchema, workerWaitRequestSchema, workerParamsSchema, workerEmptyRequestSchema, peerWaitRequestSchema } from '../contract/index.js';
+import { jsonZodValidator, paramZodValidator, queryZodValidator } from '../server/validators.js';
+import { isLoopbackHostHeader } from '../server/capabilities.js';
+import { DelegationPolicyError } from './policy.js';
+import { RunWriteRefusedError } from '../runs/store.js';
+import { withProjectAdmission } from '../server/cockpit-ownership.js';
+export function delegationFailure(error) {
+    // A run read from `.ai/squawk/` names that path and the binary that migrated the project.
+    const fallback = error instanceof RunWriteRefusedError && error.ownership === 'fallback';
+    const known = error instanceof DelegationPolicyError ? error : error instanceof WaitDeadlineConflict || fallback
+        ? new DelegationPolicyError('incompatible_state', error.message) : error instanceof ZodError
+        ? new DelegationPolicyError('invalid_input', 'Invalid delegation input')
+        : new DelegationPolicyError('incompatible_state', 'Delegation operation could not be completed');
+    const status = known.code === 'unauthenticated' ? 401 : known.code === 'denied_scope' ? 403
+        : known.code === 'invalid_input' || known.code === 'invalid_baseline' ? 400
+            : known.code === 'unavailable_transport' ? 503 : 409;
+    return { body: { code: known.code, error: known.message.slice(0, 2_000), ...(known.modelChoices ? { modelChoices: known.modelChoices } : {}) }, status };
+}
+/** Only this family runs on the private listener. It never inherits hosted cockpit exposure. */
+export function createDelegationRoutes(service, credentials) {
+    const authenticateDelegation = async (c, next) => {
+        const host = c.req.header('host');
+        const origin = c.req.header('origin');
+        let originOK = origin === undefined;
+        try {
+            if (origin !== undefined)
+                originOK = new URL(origin).origin === new URL(c.req.url).origin && new URL(origin).host === host;
+        }
+        catch { /* reject */ }
+        if (!isLoopbackHostHeader(host ?? '') || !originOK || c.req.header('sec-fetch-site') === 'cross-site') {
+            return c.json({ code: 'denied_scope', error: 'Worker scope denied' }, 403);
+        }
+        const authorization = c.req.header('authorization');
+        const token = authorization?.match(/^Bearer ([A-Za-z0-9_-]{43})$/)?.[1];
+        const caller = token ? credentials.authenticate(token) : undefined;
+        if (!caller)
+            return c.json({ code: 'unauthenticated', error: 'Delegation authentication required' }, 401);
+        c.set('caller', caller);
+        // The private listener is a second entry into the project: a migration fence or an unfinished
+        // journal refuses each request, as it refuses a cockpit route.
+        const dataDir = service.projectDataDir(caller);
+        if (!dataDir)
+            return next();
+        return withProjectAdmission(dataDir, next, (error) => c.json({ code: 'incompatible_state', error: error.message }, 409));
+    };
+    const invalid = { code: 'invalid_input', message: 'Invalid delegation input' };
+    return new Hono()
+        .onError((error, c) => { const failure = delegationFailure(error); return c.json(failure.body, failure.status); })
+        .use('*', authenticateDelegation)
+        .use('*', bodyLimit({ maxSize: 1_048_576, onError: c => c.json({ code: 'invalid_input', error: 'Delegation request too large' }, 400) }))
+        .get('/list', queryZodValidator(workerListQuerySchema, invalid), async (c) => c.json(await service.list(c.get('caller'), c.req.valid('query')), 200))
+        .use('*', queryZodValidator(workerEmptyRequestSchema, invalid))
+        .post('/discover', jsonZodValidator(discoveryRequestSchema, invalid), async (c) => c.json(await service.discover(c.get('caller'), c.req.valid('json')), 200))
+        .post('/spawn', jsonZodValidator(workerSpawnRequestSchema, invalid), async (c) => c.json(await service.spawn(c.get('caller'), c.req.valid('json')), 201))
+        .post('/wait', jsonZodValidator(z.union([workerWaitRequestSchema, requestWaitRequestSchema, peerWaitRequestSchema]), invalid), async (c) => {
+        const value = c.req.valid('json');
+        return c.json(await ('peerIds' in value ? service.waitPeers(c.get('caller'), value) : 'requestIds' in value ? service.waitRequests(c.get('caller'), value) : service.wait(c.get('caller'), value)), 200);
+    })
+        .post('/cancel-wait', jsonZodValidator(workerCancelWaitRequestSchema, invalid), async (c) => c.json(await service.cancelWait(c.get('caller'), c.req.valid('json')), 200))
+        .post('/send', jsonZodValidator(conversationSendRequestSchema, invalid), async (c) => c.json(await service.send(c.get('caller'), c.req.valid('json')), 200))
+        .post('/follow-up', jsonZodValidator(conversationSendRequestSchema, invalid), async (c) => c.json(await service.followUp(c.get('caller'), c.req.valid('json')), 200))
+        .post('/reply', jsonZodValidator(conversationSendRequestSchema, invalid), async (c) => c.json(await service.reply(c.get('caller'), c.req.valid('json')), 200))
+        .post('/conversation', jsonZodValidator(conversationInspectRequestSchema, invalid), async (c) => c.json(await service.conversation(c.get('caller'), c.req.valid('json')), 200))
+        .post('/inbox', jsonZodValidator(workerEmptyRequestSchema, invalid), async (c) => c.json(await service.inbox(c.get('caller')), 200))
+        .post('/inbox/ack', jsonZodValidator(inboxReceiptRequestSchema, invalid), async (c) => c.json(await service.ackInbox(c.get('caller'), c.req.valid('json')), 200))
+        .post('/inbox/release', jsonZodValidator(inboxReceiptRequestSchema, invalid), async (c) => c.json(await service.releaseInbox(c.get('caller'), c.req.valid('json')), 200))
+        .post('/cancel-request', jsonZodValidator(conversationCancelRequestSchema, invalid), async (c) => c.json(await service.cancelRequest(c.get('caller'), c.req.valid('json')), 200))
+        .get('/:workerId', paramZodValidator(workerParamsSchema, invalid), async (c) => c.json(await service.inspect(c.get('caller'), c.req.valid('param')), 200))
+        .post('/:workerId/collect', paramZodValidator(workerParamsSchema, invalid), jsonZodValidator(workerEmptyRequestSchema, { ...invalid, absent: {}, malformed: null }), async (c) => c.json(await service.collect(c.get('caller'), c.req.valid('param')), 200))
+        .post('/:workerId/steer', paramZodValidator(workerParamsSchema, invalid), jsonZodValidator(workerSteerRequestSchema, invalid), async (c) => c.json(await service.steer(c.get('caller'), c.req.valid('param'), c.req.valid('json')), 200))
+        .post('/:workerId/stop', paramZodValidator(workerParamsSchema, invalid), jsonZodValidator(workerEmptyRequestSchema, { ...invalid, absent: {}, malformed: null }), async (c) => c.json(await service.stop(c.get('caller'), c.req.valid('param')), 200))
+        .post('/:workerId/destroy', paramZodValidator(workerParamsSchema, invalid), jsonZodValidator(workerEmptyRequestSchema, { ...invalid, absent: {}, malformed: null }), async (c) => {
+        const result = await service.destroy(c.get('caller'), c.req.valid('param'));
+        return result.state === 'incomplete' ? c.json(result, 409) : c.json(result, 200);
+    })
+        .get('/:workerId/diff', paramZodValidator(workerParamsSchema, invalid), async (c) => c.json(await service.diff(c.get('caller'), c.req.valid('param')), 200));
+}
+//# sourceMappingURL=routes.js.map

package/dist/delegation/routes.js.map

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

package/dist/delegation/scratch-cleanup.d.ts

@@ -0,0 +1,33 @@
+import type { RunStore } from '../runs/store.ts';
+/**
+ * Keep terminal cleanup intent in the generation checkpoint as well as the index. Retain and
+ * retry unknown evidence. One timer and shared process snapshot serve pending cleanup.
+ */
+export declare class WorkerScratchCleanup {
+    private store;
+    private dataDir;
+    private busy;
+    private due;
+    private timer?;
+    /** The `at` the timer was armed for; with the clock, it decides what a tick takes. */
+    private armedFor;
+    private ticking;
+    private recoveryTimer?;
+    private enabled;
+    private backoff;
+    constructor(store: RunStore, dataDir: string, busy: (id: string) => boolean);
+    pause(): void;
+    recover(): void;
+    /** A cleanup intent: probe now. An id already pending for the same generation keeps its place
+     * in the backoff, so a repeated terminal `run` event cannot reset it; a new generation starts over. */
+    schedule(id: string): void;
+    /**
+     * Admission for one arm: no due entry when scratch is absent, foreign, live, or still running.
+     * Retain still runs before that last gate so older complete checkpoints stay reconstructed.
+     */
+    private scratchCleanupDue;
+    private arm;
+    private wake;
+    private tick;
+    private probe;
+}

package/dist/delegation/scratch-cleanup.js

@@ -0,0 +1,155 @@
+import { autosaveCleanupIds } from '../autosave-cleanup.js';
+import { agentTmpDirMayExist, removeAgentTmpDir, sweepAgentTmpDirs } from '../runs/agent-tmpdir.js';
+import { workerEvidenceRunIds } from '../runs/worker-execution.js';
+import { sharedCwdScan } from './process-liveness.js';
+import { noJitter, retryDelayMs, SCRATCH_BACKOFF } from './retry-backoff.js';
+/**
+ * Keep terminal cleanup intent in the generation checkpoint as well as the index. Retain and
+ * retry unknown evidence. One timer and shared process snapshot serve pending cleanup.
+ */
+export class WorkerScratchCleanup {
+    store;
+    dataDir;
+    busy;
+    due = new Map();
+    timer;
+    /** The `at` the timer was armed for; with the clock, it decides what a tick takes. */
+    armedFor = 0;
+    ticking = false;
+    recoveryTimer;
+    enabled = true;
+    // Private and overridable so tests need not wait out production cadence.
+    backoff = SCRATCH_BACKOFF;
+    constructor(store, dataDir, busy) {
+        this.store = store;
+        this.dataDir = dataDir;
+        this.busy = busy;
+    }
+    pause() {
+        this.enabled = false;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.due.clear();
+        clearTimeout(this.recoveryTimer);
+        this.recoveryTimer = undefined;
+    }
+    recover() {
+        // A store that could not open (#779) knows none of its runs: every scratch dir would look orphaned.
+        if (this.store.unavailable)
+            return;
+        this.enabled = true;
+        clearTimeout(this.recoveryTimer);
+        this.recoveryTimer = undefined;
+        const retained = workerEvidenceRunIds(this.dataDir);
+        const autosaves = autosaveCleanupIds(this.dataDir);
+        // Only runs that can own scratch matter: the live set, and every worker or quarantined run
+        // by id (indexed, nothing decoded, #779). Other finished runs were reaped when they ended.
+        const live = this.store.listRuns();
+        const owners = [...this.store.listWorkerIds(), ...this.store.listQuarantinedRunIds()];
+        for (const id of new Set([...live.map(run => run.id), ...owners, ...(retained ?? [])]))
+            this.schedule(id);
+        // The sweep independently reserves every private-evidence id, even if the index lost it, and
+        // every run another process claims (#779): its live runs are not in this store's live set, and
+        // their scratch is theirs.
+        if (autosaves)
+            sweepAgentTmpDirs(this.dataDir, [...new Set([...live.filter(run => this.busy(run.id) || ['queued', 'running', 'waiting'].includes(run.status)).map(run => run.id), ...owners,
+                    ...this.store.listForeignClaimedRunIds(), ...(autosaves ?? [])])]);
+        if (!retained || !autosaves) { // failed enumeration must not permanently lose a wake source
+            this.recoveryTimer = setTimeout(() => this.recover(), 60_000);
+            this.recoveryTimer.unref?.();
+        }
+    }
+    /** A cleanup intent: probe now. An id already pending for the same generation keeps its place
+     * in the backoff, so a repeated terminal `run` event cannot reset it; a new generation starts over. */
+    schedule(id) {
+        const pending = this.due.get(id);
+        if (pending && this.store.readWorkerExecution(id)?.generation === pending.generation)
+            return;
+        this.arm(id, 0, 0);
+    }
+    /**
+     * Admission for one arm: no due entry when scratch is absent, foreign, live, or still running.
+     * Retain still runs before that last gate so older complete checkpoints stay reconstructed.
+     */
+    scratchCleanupDue(id) {
+        if (!this.enabled || this.store.unavailable)
+            return false;
+        // The scratch check first: most ids have none, and a finished record is decoded to ask (#779).
+        if (!agentTmpDirMayExist(this.dataDir, id))
+            return false;
+        // Another process's run (#779, plan step 3): cleaning up after it is its owner's job, or the
+        // job of whoever adopts it once that owner is gone.
+        if (this.store.writeRefusal(id))
+            return false;
+        const run = this.store.getRun(id);
+        if (run && (['queued', 'running', 'waiting'].includes(run.status) ||
+            (run.delegation?.role !== 'worker' && run.delegation?.role !== 'invalid')))
+            return false;
+        // Reconstruct older complete checkpoints while the valid terminal index still exists.
+        try {
+            this.store.retainWorkerScratchCleanup(id);
+        }
+        catch { /* retry unreadable evidence */ }
+        const proof = this.store.readWorkerExecution(id);
+        if (run?.delegation?.role === 'worker' && proof && proof.phase !== 'complete')
+            return false;
+        return { generation: proof?.generation, resourceId: proof?.scratchCleanup?.resourceId };
+    }
+    arm(id, attempts, delay, from = Date.now()) {
+        this.due.delete(id);
+        const proof = this.scratchCleanupDue(id);
+        if (!proof)
+            return;
+        this.due.set(id, { at: from + delay, attempts, generation: proof.generation, resourceId: proof.resourceId });
+        if (!this.ticking)
+            this.wake();
+    }
+    wake() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        if (!this.enabled || !this.due.size)
+            return;
+        let next = Infinity;
+        for (const { at } of this.due.values())
+            next = Math.min(next, at);
+        this.armedFor = next;
+        this.timer = setTimeout(() => this.tick(), Math.max(0, next - Date.now()));
+        this.timer.unref?.();
+    }
+    tick() {
+        this.timer = undefined;
+        if (!this.enabled)
+            return;
+        // Ids due within 5 % of the fast cadence ride along, so near neighbours share the scan, and
+        // every id this tick retains is re-armed from the same instant, so they stay together.
+        const now = Date.now();
+        const dueBy = Math.max(this.armedFor, now) + this.backoff.fastMs / 20;
+        const cwds = sharedCwdScan();
+        this.ticking = true;
+        try {
+            for (const [id, pending] of [...this.due])
+                if (pending.at <= dueBy)
+                    this.probe(id, pending, cwds, now);
+        }
+        finally {
+            this.ticking = false;
+        }
+        this.wake();
+    }
+    probe(id, { attempts, generation, resourceId }, cwds, now) {
+        this.due.delete(id);
+        const execution = this.store.readWorkerExecution(id);
+        // No await between ownership/generation + holder proof and rm. Admission is synchronous
+        // too, so a queued stale callback can never touch the next generation's scratch. The
+        // shared snapshot is this synchronous tick's: it never outlives a yield.
+        try {
+            if (generation && resourceId && execution?.generation === generation && !this.busy(id) &&
+                this.store.workerScratchResourcesSafe(id, generation, resourceId, cwds))
+                removeAgentTmpDir(this.dataDir, id);
+        }
+        catch { /* Transient evidence/read failures retain the durable intent for another wake. */ }
+        // Uncertainty has no age limit or force-delete exit; it backs off instead.
+        this.arm(id, attempts + 1, retryDelayMs(attempts, this.backoff, noJitter), now);
+    }
+}
+//# sourceMappingURL=scratch-cleanup.js.map

package/dist/delegation/scratch-cleanup.js.map

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

package/dist/delegation/service.d.ts

@@ -0,0 +1,264 @@
+import type { Home } from '../home/home.ts';
+import { type HostDiscovery } from '../discovery/catalog.ts';
+export { rootDelegation } from './conversations.ts';
+import { type DiscoveryRequest, type DiscoveryResponse } from '../contract/index.js';
+import { type ConversationSendRequest, type ConversationSendResult, type ConversationInspectRequest, type ConversationInspectResult, type ConversationCancelRequest, type InboxReserveResult, type InboxReceiptRequest, type InboxReceiptResult, type RequestWaitRequest, type RequestOutcome } from '../contract/index.js';
+import { type PeerWaitRequest, type WorkerCancelWaitRequest, type WorkerListPage, type WorkerListQuery, type WorkerCollectedResult, type WorkerInspection, type WorkerParams, type WorkerSpawnRequest, type WorkerSteerRequest, type WorkerWaitRequest } from '../contract/index.js';
+import type { RunStore } from '../runs/store.ts';
+import type { RunManager } from '../workflows/run.ts';
+import type { Caller } from './credentials.ts';
+import { type WorkerCleanupOptions } from './worker-cleanup.ts';
+export type DelegationManager = Pick<RunManager, 'acknowledgeInbox' | 'awaitRunTermination' | 'builtinSkills' | 'canClaimInboxInput' | 'cancelPeerWait' | 'cancelWorkerWait' | 'claimWorkerCleanup' | 'continueRun' | 'deliverConversationInput' | 'enqueueOwnedRun' | 'isActive' | 'pauseWorkerCleanup' | 'previewHost' | 'reconcileWorkerWaits' | 'recoverWorkerCleanup' | 'registerPeerWait' | 'registerRequestWait' | 'registerWorkerWait' | 'releaseInbox' | 'requestWorkerStop' | 'reserveInboxInputs' | 'selectDelegationExecutionSettings' | 'settleOrphanedWorkerExecution' | 'steerWorker' | 'takeWorkerTerminationBlocker'>;
+export type DelegationProject = {
+    home: Home;
+    id: string;
+    root: string;
+    store: RunStore;
+    manager: DelegationManager;
+};
+/** A single controller's shared policy adapter; managers retain scheduling and lifecycle ownership. */
+export declare class DelegationService {
+    private readonly cleanupOptions;
+    private discovery?;
+    setDiscovery(discovery: HostDiscovery): void;
+    discover(caller: Caller, value: DiscoveryRequest): Promise<DiscoveryResponse>;
+    private validateModels;
+    private projects;
+    private serial;
+    private cleanups;
+    constructor(cleanupOptions?: WorkerCleanupOptions);
+    registerProject(project: DelegationProject): () => void;
+    /** Called only after manager recovery, when persisted destroy intents may be retried. */
+    armDestroyRetries(projectId: string): void;
+    /** The data directory of the caller's project, for the listener's migration admission. */
+    projectDataDir(caller: Caller): string | undefined;
+    private context;
+    private serialized;
+    private target;
+    /**
+     * The relationship resolver (spec 2026-10-27-task-communication-protocol § 2): `family` for a
+     * root and its direct owned worker, `peer` for two root tasks of the caller's project, and
+     * `denied_scope` with one text for everything else. `send` asks for the live pair a new message
+     * needs; without it the pair is checked for reading. A peer's own durable records (history, its
+     * requests, its inbox) are read through `peerRecords` instead, which a deleted peer does not block.
+     */
+    private conversationPair;
+    /** The caller's own peer records need only its participation: a root task whose own history is
+     *  not being deleted. The record read names the counterpart; a deleted peer does not block it. */
+    private peerRecords;
+    /** The ledger a new message lands in (spec § 2, Which ledger holds a message): a new request or
+     *  progress message in the sender's family ledger, a follow-up or reply with the request it names. */
+    private ledgerFor;
+    private currentConversation;
+    private conversationReceipt;
+    send(caller: Caller, value: ConversationSendRequest): Promise<ConversationSendResult>;
+    /** Runs entirely under the ledger lock; mutable records are read at the queue head. */
+    private sendLocked;
+    private assertSendScope;
+    private retrySend;
+    private commitSend;
+    followUp(caller: Caller, value: ConversationSendRequest): Promise<ConversationSendResult>;
+    reply(caller: Caller, value: ConversationSendRequest): Promise<ConversationSendResult>;
+    /**
+     * One pair's history. A family pair reads its one ledger; a peer pair reads both roots' ledgers
+     * and merges them in `(createdAt, id)` order, newest `CONVERSATION_PAGE_MESSAGES` first, with
+     * `nextBefore` when older messages exist (spec § 2). A deleted peer leaves the caller's ledger.
+     */
+    conversation(caller: Caller, value: ConversationInspectRequest): Promise<ConversationInspectResult>;
+    /** The ledgers a history read covers: the family's one, or each peer root's own while it exists.
+     *  A peer whose history is being deleted, or is deleted, stays readable to a participant (spec § 2). */
+    private historyLedgers;
+    inbox(caller: Caller): Promise<InboxReserveResult>;
+    /** A peer input addressed to the caller: its participation is the whole check (spec § 2, two
+     *  levels). When the sender's ledger went with its deletion, the input still carries the message. */
+    private peerInboxEntry;
+    /** A family input: the pair must still be admitted, as before peers existed. */
+    private familyInboxEntry;
+    private inboxReceipt;
+    ackInbox(caller: Caller, value: InboxReceiptRequest): Promise<InboxReceiptResult>;
+    releaseInbox(caller: Caller, value: InboxReceiptRequest): Promise<InboxReceiptResult>;
+    /** A request the caller sent, from its family ledger. A peer request needs only the caller's own
+     *  record: wait and cancel still work after the peer's deletion (spec § 2). */
+    private ownRequest;
+    cancelRequest(caller: Caller, value: ConversationCancelRequest): Promise<RequestOutcome>;
+    waitRequests(caller: Caller, value: RequestWaitRequest): Promise<{
+        wait: {
+            id: string;
+            workerIds: string[];
+            requestIds?: string[] | undefined;
+            requestOutcomes?: {
+                requestId: string;
+                status: "cancelled" | "completed-without-reply" | "deleted" | "destroyed" | "failed" | "human-fallback" | "replied" | "replied-late" | "sender-closed" | "timed-out";
+                observedAt: string;
+                replyId?: string | undefined;
+            }[] | undefined;
+            deadline: string;
+            mode?: "all" | "any" | "one" | undefined;
+            revisions?: {
+                workerId: string;
+                revision: number;
+            }[] | undefined;
+            reason?: "cancelled" | "message" | "outcome" | "timeout" | undefined;
+            phase: "parked" | "registered" | "wake-pending";
+            outcomes: {
+                workerId: string;
+                status: "cancelled" | "done" | "failed" | "review";
+                observedAt: string;
+                summary?: string | undefined;
+                revision?: number | undefined;
+            }[];
+            wakeId?: string | undefined;
+        };
+        instruction: string;
+    }>;
+    /** `cez message wait --peer` (hearsay-tools/cezarion#1995): the manager checks each peer through
+     *  the relationship resolver, so a worker or a non-peer is `denied_scope`. */
+    waitPeers(caller: Caller, value: PeerWaitRequest): Promise<{
+        wait: {
+            id: string;
+            peerIds: string[];
+            deadline: string;
+            phase: "cancelled" | "delivered" | "open" | "resolved";
+            result?: {
+                reason: "message";
+                peerRunId: string;
+                messageId: string;
+            } | {
+                reason: "settled";
+                peerRunId: string;
+            } | {
+                reason: "timeout";
+            } | undefined;
+        };
+        instruction: string;
+    }>;
+    spawn(caller: Caller, value: WorkerSpawnRequest): Promise<{
+        workerId: string;
+        baselineSha: string;
+    }>;
+    list(caller: Caller, query?: WorkerListQuery): Promise<WorkerListPage>;
+    inspect(caller: Caller, params: WorkerParams): Promise<WorkerInspection>;
+    /** The wait an inspection shows: the newest open or owed list wait naming the worker, in the
+     *  legacy `WorkerWait` shape (hearsay-tools/cezarion#1235). Cezar's completion wait carries no
+     *  deadline, which that shape requires, so inspection shows it as `completionWait`
+     *  (hearsay-tools/cezarion#1301). */
+    private inspectedWait;
+    collect(caller: Caller, params: WorkerParams): Promise<WorkerCollectedResult>;
+    steer(caller: Caller, params: WorkerParams, value: WorkerSteerRequest): Promise<{
+        workerId: string;
+        state: "delivered" | "queued";
+    }>;
+    stop(caller: Caller, params: WorkerParams): Promise<{
+        workerId: string;
+        state: "stopping" | "terminated";
+    }>;
+    diff(caller: Caller, params: WorkerParams): Promise<{
+        workerId: string;
+        baselineSha: string;
+        diff: string;
+        truncated: boolean;
+    }>;
+    wait(caller: Caller, value: WorkerWaitRequest): Promise<{
+        wait: {
+            id: string;
+            workerIds: string[];
+            requestIds?: string[] | undefined;
+            requestOutcomes?: {
+                requestId: string;
+                status: "cancelled" | "completed-without-reply" | "deleted" | "destroyed" | "failed" | "human-fallback" | "replied" | "replied-late" | "sender-closed" | "timed-out";
+                observedAt: string;
+                replyId?: string | undefined;
+            }[] | undefined;
+            deadline: string;
+            mode?: "all" | "any" | "one" | undefined;
+            revisions?: {
+                workerId: string;
+                revision: number;
+            }[] | undefined;
+            reason?: "cancelled" | "message" | "outcome" | "timeout" | undefined;
+            phase: "parked" | "registered" | "wake-pending";
+            outcomes: {
+                workerId: string;
+                status: "cancelled" | "done" | "failed" | "review";
+                observedAt: string;
+                summary?: string | undefined;
+                revision?: number | undefined;
+            }[];
+            wakeId?: string | undefined;
+        };
+        instruction: string;
+    }>;
+    cancelWait(caller: Caller, value: WorkerCancelWaitRequest): Promise<{
+        wait: {
+            id: string;
+            peerIds: string[];
+            deadline: string;
+            phase: "cancelled" | "delivered" | "open" | "resolved";
+            result?: {
+                reason: "message";
+                peerRunId: string;
+                messageId: string;
+            } | {
+                reason: "settled";
+                peerRunId: string;
+            } | {
+                reason: "timeout";
+            } | undefined;
+        };
+    } | {
+        wait: {
+            id: string;
+            workerIds: string[];
+            requestIds?: string[] | undefined;
+            requestOutcomes?: {
+                requestId: string;
+                status: "cancelled" | "completed-without-reply" | "deleted" | "destroyed" | "failed" | "human-fallback" | "replied" | "replied-late" | "sender-closed" | "timed-out";
+                observedAt: string;
+                replyId?: string | undefined;
+            }[] | undefined;
+            deadline: string;
+            mode?: "all" | "any" | "one" | undefined;
+            revisions?: {
+                workerId: string;
+                revision: number;
+            }[] | undefined;
+            reason?: "cancelled" | "message" | "outcome" | "timeout" | undefined;
+            phase: "parked" | "registered" | "wake-pending";
+            outcomes: {
+                workerId: string;
+                status: "cancelled" | "done" | "failed" | "review";
+                observedAt: string;
+                summary?: string | undefined;
+                revision?: number | undefined;
+            }[];
+            wakeId?: string | undefined;
+        };
+    }>;
+    destroy(caller: Caller, params: WorkerParams): Promise<{
+        workerId: string;
+        state: "complete" | "incomplete";
+        deleted?: ({
+            kind: "worktree";
+            path: string;
+        } | {
+            kind: "branch";
+            ref: string;
+        })[] | undefined;
+        remaining: ("branch" | "process" | "worktree")[];
+        error?: string | undefined;
+    }>;
+    /** Existing human HTTP authority, bound to its resolved project; never mint a pretend agent caller. */
+    destroyForHuman(projectId: string, workerId: string): Promise<{
+        workerId: string;
+        state: "complete" | "incomplete";
+        deleted?: ({
+            kind: "worktree";
+            path: string;
+        } | {
+            kind: "branch";
+            ref: string;
+        })[] | undefined;
+        remaining: ("branch" | "process" | "worktree")[];
+        error?: string | undefined;
+    }>;
+}