toolroll 0.9.62 → 0.9.65

package/dist/console-instance.d.ts

@@ -0,0 +1,124 @@
+import { type Socket } from "node:net";
+import type { Store } from "./store.js";
+export declare const CONSOLE_INSTANCE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS console_instance (\n  id         INTEGER PRIMARY KEY CHECK (id = 1),\n  secret     TEXT NOT NULL,\n  pid        INTEGER NOT NULL,\n  port       INTEGER NOT NULL,\n  build      TEXT NOT NULL,\n  socket     TEXT NOT NULL,\n  started_at TEXT NOT NULL\n);";
+/**
+ * The socket's own owner-only directory beside the database's REAL file (a symlinked database resolves to the one
+ * folder every spelling shares). Each console start binds a socket of its own, under a fresh random name recorded
+ * with its secret: no console ever needs to remove — or can remove — another console's socket.
+ */
+/** Toolroll's own name, so it never collides with a project or worktree that happens to sit beside the database. */
+export declare const INSTANCE_DIR = ".toolroll-run";
+export declare function instanceRunDir(databaseFile: string): string;
+/** The console's own answer to a challenge over HTTP (an edge route, no sign-in: it reveals nothing). */
+export declare const INSTANCE_PATH = "/__instance";
+export type InstanceRecord = {
+    secret: string;
+    pid: number;
+    port: number;
+    build: string;
+    socket: string;
+    startedAt: string;
+};
+export type HelloFacts = {
+    pid: number;
+    build: string;
+    database: string;
+    port: number;
+};
+/** The record as stored: none, one this build can't read (never taken for none), or the record. */
+export declare function readInstanceState(store: Store): {
+    state: "none";
+} | {
+    state: "invalid";
+} | {
+    state: "ok";
+    record: InstanceRecord;
+};
+export declare function readInstance(store: Store): InstanceRecord | null;
+/** A stopping console forgets itself — only its own record, never a newer start's. */
+export declare function clearInstance(store: Store, secret: string): void;
+export declare const socketProof: (secret: string, challenge: string) => string;
+export declare const httpProof: (secret: string, challenge: string, address: string, port: number) => string;
+/** The HTTP answer: bound to the address and port THIS connection was received on, as the console saw them. */
+export declare function instanceHttpAnswer(secret: string, challenge: string | null, local: {
+    address: string | undefined;
+    port: number | undefined;
+}): {
+    status: number;
+    body: string;
+};
+/**
+ * The run directory must be private to this user: a real, canonical directory owned by this user with no access for
+ * anyone else (0700), inside a canonical directory owned by this user that nobody else can write. Checked before any
+ * change is made, and before connecting or binding.
+ */
+export declare function runDirProblem(dir: string, uid?: number, mustExist?: boolean): string | null;
+/** A socket path that binds exactly (no truncation), named as a console names its own. */
+export declare function socketPathProblem(path: string): string | null;
+/**
+ * `up`: the run directory, made 0700 if it isn't there. An existing one is used only as it is (never chmodded): one
+ * that isn't private to this user is refused. Everything is checked before anything is created.
+ */
+export declare function prepareRunDir(dir: string, uid?: number): string | null;
+/** Ask a socket one question; null when nobody is listening (or it said nothing usable in time). */
+export declare function askSocket(socketPath: string, request: object, timeoutMs?: number, connect?: (path: string) => Socket): Promise<{
+    answer: Record<string, unknown>;
+} | {
+    none: "no-listener" | "no-answer";
+}>;
+/**
+ * The console's discovery socket: one line in, one line out. `hello` (with a challenge) answers the public facts and
+ * the socket proof; every other verb is refused. It reads nothing else and changes nothing. Bound under a fresh name
+ * no other process has, so it never clears or replaces anything; its own listener removes it on close.
+ */
+export declare function openInstanceSocket(databaseFile: string, facts: HelloFacts, secret: () => string | null): Promise<{
+    ok: true;
+    name: string;
+    close: () => void;
+} | {
+    ok: false;
+    problem: string;
+}>;
+/**
+ * A record's console: "live" (its socket answers a fresh challenge with the record's secret and pid), "gone" (nobody
+ * is listening on its socket, or the socket isn't there), or "unknown" (anything else: slow, malformed, a wrong proof).
+ * Only "gone" lets another start take the record.
+ */
+export declare function recordLiveness(databaseFile: string, record: InstanceRecord, ask?: typeof askSocket): Promise<"live" | "gone" | "unknown">;
+/**
+ * `up` claims the record for its socket — unless a live console already holds it (another start on the same
+ * database, by any spelling of its path). The write is a compare-and-set on the record it checked: two starts racing
+ * can't both win. Null: not claimed (this console runs, but `toolroll` won't attach to it).
+ */
+export declare function claimInstance(store: Store, databaseFile: string, facts: {
+    pid: number;
+    port: number;
+    build: string;
+    socket: string;
+}, now: Date, liveness?: (record: InstanceRecord) => Promise<"live" | "gone" | "unknown">): Promise<string | null>;
+export type AttachProof = {
+    ok: true;
+    url: string;
+    port: number;
+    pid: number;
+    build: string;
+} | {
+    ok: false;
+    state: "none";
+    message: string;
+} | {
+    ok: false;
+    state: "refused";
+    message: string;
+};
+export type AttachSeams = {
+    ask?: typeof askSocket;
+    fetch?: typeof fetch;
+    challenge?: () => string;
+};
+/**
+ * Prove the console this installation's database names is live, on both channels, before anything is shown or
+ * opened. "none": no console runs (no record, or nobody on the socket); "refused": something answers that can't
+ * prove it is the console (or a different build) — the person restarts it.
+ */
+export declare function proveLiveConsole(databaseFile: string, store: Store, build: string, seams?: AttachSeams): Promise<AttachProof>;

package/dist/console-instance.js

@@ -0,0 +1,337 @@
+/**
+ * THE RUNNING CONSOLE, PROVED LIVE (docs/plans/agents-cockpit.md B1).
+ *
+ * Bare `toolroll` in a repository attaches to a console already running for this installation instead of starting a
+ * second one. Build agents run as the operator's own user, so nothing the filesystem says can tell the operator from
+ * an agent: the console's Unix socket is DISCOVERY ONLY. It answers one verb, `hello`, with facts an agent could learn
+ * anyway, and changes nothing.
+ *
+ * What proves the console is real is a fresh random instance secret, minted at each start of `up` and written to the
+ * database (behind the agent fence) with its pid, build and port. The CLI reads it from the database it opens itself,
+ * then makes the LIVE console answer two fresh challenges with it: over the socket (HMAC of "socket:" + challenge),
+ * and over the advertised HTTP listener (HMAC of "http:" + challenge + " " + address + " " + port, where the address and
+ * port are what the console itself saw as the receiving end of that very connection). The CLI requires those to be
+ * 127.0.0.1 and the recorded port, so a relay on 127.0.0.1 forwarding to the console's other address is refused, as are
+ * a replayed hello, a stale record with a recycled pid, and another process now on that port.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { lstatSync, mkdirSync, realpathSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { basename, dirname, join } from "node:path";
+export const CONSOLE_INSTANCE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS console_instance (
+  id         INTEGER PRIMARY KEY CHECK (id = 1),
+  secret     TEXT NOT NULL,
+  pid        INTEGER NOT NULL,
+  port       INTEGER NOT NULL,
+  build      TEXT NOT NULL,
+  socket     TEXT NOT NULL,
+  started_at TEXT NOT NULL
+);`;
+/**
+ * The socket's own owner-only directory beside the database's REAL file (a symlinked database resolves to the one
+ * folder every spelling shares). Each console start binds a socket of its own, under a fresh random name recorded
+ * with its secret: no console ever needs to remove — or can remove — another console's socket.
+ */
+/** Toolroll's own name, so it never collides with a project or worktree that happens to sit beside the database. */
+export const INSTANCE_DIR = ".toolroll-run";
+export function instanceRunDir(databaseFile) {
+    let file = databaseFile;
+    try {
+        file = realpathSync(databaseFile);
+    }
+    catch {
+        try {
+            file = join(realpathSync(dirname(databaseFile)), basename(databaseFile));
+        }
+        catch { /* not there yet: as given */ }
+    }
+    return join(dirname(file), INSTANCE_DIR);
+}
+const SOCKET_NAME = /^[0-9a-f]{16}\.sock$/;
+/** The longest Unix socket path the platform binds without truncating (sun_path less its NUL). */
+const SOCKET_PATH_MAX = process.platform === "darwin" ? 103 : 107;
+/** The console's own answer to a challenge over HTTP (an edge route, no sign-in: it reveals nothing). */
+export const INSTANCE_PATH = "/__instance";
+const CHALLENGE = /^[0-9a-f]{32,128}$/;
+const LINE_CAP = 4096;
+/** The record as stored: none, one this build can't read (never taken for none), or the record. */
+export function readInstanceState(store) {
+    const row = store.handle.prepare("SELECT secret, pid, port, build, socket, started_at FROM console_instance WHERE id = 1").get();
+    if (row === undefined)
+        return { state: "none" };
+    const secret = String(row["secret"]), pid = Number(row["pid"]), port = Number(row["port"]), socket = String(row["socket"]);
+    if (!/^[0-9a-f]{64}$/.test(secret) || !Number.isSafeInteger(pid) || !Number.isInteger(port) || port < 1 || port > 65535 || !SOCKET_NAME.test(socket))
+        return { state: "invalid" };
+    return { state: "ok", record: { secret, pid, port, build: String(row["build"]), socket, startedAt: String(row["started_at"]) } };
+}
+export function readInstance(store) {
+    const read = readInstanceState(store);
+    return read.state === "ok" ? read.record : null;
+}
+/** A stopping console forgets itself — only its own record, never a newer start's. */
+export function clearInstance(store, secret) {
+    store.handle.prepare("DELETE FROM console_instance WHERE id = 1 AND secret = ?").run(secret);
+}
+export const socketProof = (secret, challenge) => createHmac("sha256", secret).update(`socket:${challenge}`).digest("hex");
+export const httpProof = (secret, challenge, address, port) => createHmac("sha256", secret).update(`http:${challenge} ${address} ${port}`).digest("hex");
+const PROOF = /^[0-9a-f]{64}$/;
+/** Constant-time comparison of two proofs, each first required to be exactly 64 hex characters. */
+const same = (a, b) => typeof a === "string" && PROOF.test(a) && PROOF.test(b) && timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+/** The HTTP answer: bound to the address and port THIS connection was received on, as the console saw them. */
+export function instanceHttpAnswer(secret, challenge, local) {
+    if (challenge === null || !CHALLENGE.test(challenge) || local.address === undefined || local.port === undefined)
+        return { status: 400, body: JSON.stringify({ error: "challenge" }) };
+    return { status: 200, body: JSON.stringify({ proof: httpProof(secret, challenge, local.address, local.port) }) };
+}
+/**
+ * The run directory must be private to this user: a real, canonical directory owned by this user with no access for
+ * anyone else (0700), inside a canonical directory owned by this user that nobody else can write. Checked before any
+ * change is made, and before connecting or binding.
+ */
+export function runDirProblem(dir, uid = process.getuid?.() ?? -1, mustExist = true) {
+    const parent = dirname(dir);
+    let above;
+    try {
+        above = lstatSync(parent);
+    }
+    catch {
+        return `${parent} doesn't exist`;
+    }
+    try {
+        if (realpathSync(parent) !== parent)
+            return `${parent} isn't its own real path`;
+    }
+    catch {
+        return `${parent} doesn't exist`;
+    }
+    if (!above.isDirectory())
+        return `${parent} isn't a directory`;
+    if (uid >= 0 && above.uid !== uid)
+        return `${parent} belongs to another user`;
+    if ((above.mode & 0o022) !== 0)
+        return `${parent} can be written by other users`;
+    let info;
+    try {
+        info = lstatSync(dir);
+    }
+    catch {
+        return mustExist ? `${dir} doesn't exist` : null;
+    }
+    if (!info.isDirectory())
+        return `${dir} isn't a directory`;
+    if (uid >= 0 && info.uid !== uid)
+        return `${dir} belongs to another user`;
+    try {
+        lstatSync(join(dir, ".git"));
+        return `${dir} holds a repository, not Toolroll's sockets`;
+    }
+    catch { /* as it should be */ }
+    if ((info.mode & 0o077) !== 0)
+        return `${dir} is open to other users — Toolroll uses it only when it is yours alone (chmod 700)`;
+    return null;
+}
+/** A socket path that binds exactly (no truncation), named as a console names its own. */
+export function socketPathProblem(path) {
+    if (!SOCKET_NAME.test(basename(path)))
+        return `${path} isn't a console socket`;
+    if (Buffer.byteLength(path) > SOCKET_PATH_MAX)
+        return `${path} is too long for a socket here`;
+    return null;
+}
+/**
+ * `up`: the run directory, made 0700 if it isn't there. An existing one is used only as it is (never chmodded): one
+ * that isn't private to this user is refused. Everything is checked before anything is created.
+ */
+export function prepareRunDir(dir, uid = process.getuid?.() ?? -1) {
+    const before = runDirProblem(dir, uid, false);
+    if (before !== null)
+        return before;
+    try {
+        mkdirSync(dir, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            return `${dir} couldn't be made`;
+    }
+    return runDirProblem(dir, uid, true);
+}
+/** Ask a socket one question; null when nobody is listening (or it said nothing usable in time). */
+export function askSocket(socketPath, request, timeoutMs = 2_000, connect = path => createConnection(path)) {
+    return new Promise(resolve => {
+        let settled = false, buffer = "";
+        const done = (value) => { if (settled)
+            return; settled = true; clearTimeout(timer); socket.destroy(); resolve(value); };
+        const socket = connect(socketPath);
+        const timer = setTimeout(() => done({ none: "no-answer" }), timeoutMs);
+        socket.setEncoding("utf8");
+        socket.on("error", (error) => done({ none: error.code === "ECONNREFUSED" || error.code === "ENOENT" ? "no-listener" : "no-answer" }));
+        socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+        socket.on("data", chunk => {
+            buffer += chunk;
+            if (buffer.length > LINE_CAP)
+                return done({ none: "no-answer" });
+            const end = buffer.indexOf("\n");
+            if (end < 0)
+                return;
+            try {
+                const parsed = JSON.parse(buffer.slice(0, end));
+                done(parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? { answer: parsed } : { none: "no-answer" });
+            }
+            catch {
+                done({ none: "no-answer" });
+            }
+        });
+        socket.on("end", () => done({ none: "no-answer" }));
+    });
+}
+/**
+ * The console's discovery socket: one line in, one line out. `hello` (with a challenge) answers the public facts and
+ * the socket proof; every other verb is refused. It reads nothing else and changes nothing. Bound under a fresh name
+ * no other process has, so it never clears or replaces anything; its own listener removes it on close.
+ */
+export async function openInstanceSocket(databaseFile, facts, secret) {
+    const dir = instanceRunDir(databaseFile);
+    const problem = prepareRunDir(dir);
+    if (problem !== null)
+        return { ok: false, problem };
+    const name = `${randomBytes(8).toString("hex")}.sock`, socketPath = join(dir, name);
+    const pathProblem = socketPathProblem(socketPath);
+    if (pathProblem !== null)
+        return { ok: false, problem: pathProblem };
+    const server = createServer(socket => {
+        let buffer = "";
+        socket.setEncoding("utf8");
+        socket.setTimeout(5_000, () => socket.destroy());
+        const reply = (body) => { socket.end(`${JSON.stringify(body)}\n`); };
+        socket.on("error", () => socket.destroy());
+        socket.on("data", chunk => {
+            buffer += chunk;
+            if (buffer.length > LINE_CAP)
+                return void socket.destroy();
+            const end = buffer.indexOf("\n");
+            if (end < 0)
+                return;
+            let asked;
+            try {
+                asked = JSON.parse(buffer.slice(0, end));
+            }
+            catch {
+                return reply({ error: "refused" });
+            }
+            const verb = asked !== null && typeof asked === "object" ? asked.verb : undefined;
+            const challenge = asked !== null && typeof asked === "object" ? asked.challenge : undefined;
+            const key = secret();
+            if (verb !== "hello" || typeof challenge !== "string" || !CHALLENGE.test(challenge) || key === null)
+                return reply({ error: "refused" });
+            reply({ ...facts, proof: socketProof(key, challenge) });
+        });
+    });
+    // A Unix bind never replaces an existing path (EADDRINUSE).
+    const listening = await new Promise(resolve => { server.once("error", () => resolve(false)); server.listen(socketPath, () => resolve(true)); });
+    if (!listening)
+        return { ok: false, problem: `couldn't listen on ${socketPath}` };
+    return { ok: true, name, close: () => { server.close(); } };
+}
+/**
+ * A record's console: "live" (its socket answers a fresh challenge with the record's secret and pid), "gone" (nobody
+ * is listening on its socket, or the socket isn't there), or "unknown" (anything else: slow, malformed, a wrong proof).
+ * Only "gone" lets another start take the record.
+ */
+export async function recordLiveness(databaseFile, record, ask = askSocket) {
+    const socketPath = join(instanceRunDir(databaseFile), record.socket);
+    if (socketPathProblem(socketPath) !== null)
+        return "unknown";
+    const challenge = randomBytes(32).toString("hex");
+    const asked = await ask(socketPath, { verb: "hello", challenge }, 5_000);
+    if ("none" in asked)
+        return asked.none === "no-listener" ? "gone" : "unknown";
+    return asked.answer["pid"] === record.pid && same(asked.answer["proof"], socketProof(record.secret, challenge)) ? "live" : "unknown";
+}
+/**
+ * `up` claims the record for its socket — unless a live console already holds it (another start on the same
+ * database, by any spelling of its path). The write is a compare-and-set on the record it checked: two starts racing
+ * can't both win. Null: not claimed (this console runs, but `toolroll` won't attach to it).
+ */
+export async function claimInstance(store, databaseFile, facts, now, liveness = record => recordLiveness(databaseFile, record)) {
+    const rawSecret = () => { const row = store.handle.prepare("SELECT secret FROM console_instance WHERE id = 1").get(); return row === undefined ? null : String(row["secret"]); };
+    const checked = rawSecret();
+    // Taken only from nobody, or from a console confirmed gone: never on a check that merely failed, and never over a
+    // record this build can't read.
+    const current = readInstanceState(store);
+    if (current.state === "invalid")
+        return null;
+    if (current.state === "ok" && await liveness(current.record) !== "gone")
+        return null;
+    const secret = randomBytes(32).toString("hex");
+    return store.transact(() => {
+        // Exactly the record that was checked (or none): anything else is another start's newer claim.
+        if (rawSecret() !== checked)
+            return null;
+        store.handle.prepare("INSERT INTO console_instance (id, secret, pid, port, build, socket, started_at) VALUES (1, ?, ?, ?, ?, ?, ?) ON CONFLICT (id) DO UPDATE SET secret = excluded.secret, pid = excluded.pid, port = excluded.port, build = excluded.build, socket = excluded.socket, started_at = excluded.started_at")
+            .run(secret, facts.pid, facts.port, facts.build, facts.socket, now.toISOString());
+        return secret;
+    });
+}
+/**
+ * Prove the console this installation's database names is live, on both channels, before anything is shown or
+ * opened. "none": no console runs (no record, or nobody on the socket); "refused": something answers that can't
+ * prove it is the console (or a different build) — the person restarts it.
+ */
+export async function proveLiveConsole(databaseFile, store, build, seams = {}) {
+    const restart = "stop it and run `toolroll up` again";
+    // No record: nothing is running here (a console that couldn't claim one isn't offered). One this build can't read
+    // isn't "nothing": it is refused.
+    const read = readInstanceState(store);
+    if (read.state === "none")
+        return { ok: false, state: "none", message: "no console is running" };
+    if (read.state === "invalid")
+        return { ok: false, state: "refused", message: `the console's record can't be read — ${restart}` };
+    const record = read.record;
+    const dir = instanceRunDir(databaseFile);
+    const problem = runDirProblem(dir) ?? socketPathProblem(join(dir, record.socket));
+    if (problem !== null)
+        return { ok: false, state: "refused", message: `the console's socket can't be trusted: ${problem}` };
+    const socketPath = join(dir, record.socket);
+    try {
+        const socket = lstatSync(socketPath);
+        if (!socket.isSocket() || (process.getuid !== undefined && socket.uid !== process.getuid()))
+            return { ok: false, state: "refused", message: `the console's socket can't be trusted: ${socketPath} isn't this user's socket` };
+    }
+    catch (error) {
+        // Only "not there" means nothing is running; a socket the system won't show can't be checked.
+        if (error.code === "ENOENT")
+            return { ok: false, state: "none", message: "no console is running" };
+        return { ok: false, state: "refused", message: `the console's socket can't be checked — ${restart}` };
+    }
+    const challenge = seams.challenge ?? (() => randomBytes(32).toString("hex"));
+    const first = challenge();
+    const asked = await (seams.ask ?? askSocket)(socketPath, { verb: "hello", challenge: first });
+    if ("none" in asked) {
+        // Stale (a console that died): nobody is listening, so nothing is running. Discovery removes nothing.
+        if (asked.none === "no-listener")
+            return { ok: false, state: "none", message: "no console is running" };
+        return { ok: false, state: "refused", message: `the console's socket didn't answer — ${restart}` };
+    }
+    const hello = asked.answer;
+    if (hello["build"] !== record.build || hello["build"] !== build) {
+        return { ok: false, state: "refused", message: `the running console is a different build (${String(hello["build"] ?? "unknown")}, this is ${build}) — ${restart}` };
+    }
+    if (hello["pid"] !== record.pid || hello["port"] !== record.port || !same(hello["proof"], socketProof(record.secret, first))) {
+        return { ok: false, state: "refused", message: `the console on the socket couldn't prove it's this installation's — ${restart}` };
+    }
+    const second = challenge();
+    let body;
+    try {
+        const answer = await (seams.fetch ?? fetch)(`http://127.0.0.1:${record.port}${INSTANCE_PATH}?c=${second}`, { redirect: "manual", signal: AbortSignal.timeout(3_000) });
+        body = answer.status === 200 ? await answer.json() : null;
+    }
+    catch {
+        body = null;
+    }
+    const proof = body !== null && typeof body === "object" ? body.proof : undefined;
+    if (!same(proof, httpProof(record.secret, second, "127.0.0.1", record.port))) {
+        return { ok: false, state: "refused", message: `the address 127.0.0.1:${record.port} couldn't prove it's the console — ${restart}` };
+    }
+    return { ok: true, url: `http://127.0.0.1:${record.port}`, port: record.port, pid: record.pid, build: record.build };
+}

package/dist/contracts/chat-actions.d.ts

@@ -85,6 +85,20 @@ export declare const chatActionRequestSchemas: {
         repo: z.ZodString;
         starter: z.ZodString;
     }, z.core.$strict>;
+    readonly sweep_cancel_rest: z.ZodObject<{
+        sweep: z.ZodInt;
+    }, z.core.$strict>;
+    readonly sweep_file: z.ZodObject<{
+        repo: z.ZodString;
+        title: z.ZodString;
+        brief: z.ZodString;
+        items: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            item: z.ZodString;
+        }, z.core.$strict>>;
+        acceptance: z.ZodArray<z.ZodUnknown>;
+        maxParallel: z.ZodNumber;
+    }, z.core.$strict>;
     readonly flow_edit: z.ZodObject<{
         flow: z.ZodInt;
         name: z.ZodOptional<z.ZodString>;
@@ -309,6 +323,8 @@ export declare const sharedActionSchema: z.ZodObject<{
         subagent_state: "subagent_state";
         subagent_tools: "subagent_tools";
         subagent_undo: "subagent_undo";
+        sweep_cancel_rest: "sweep_cancel_rest";
+        sweep_file: "sweep_file";
         task_cancel: "task_cancel";
         task_resume: "task_resume";
         tool_add: "tool_add";

package/dist/contracts/chat-actions.js

@@ -41,6 +41,10 @@ export const chatActionRequestSchemas = {
     tool_remove: z.strictObject({ repo: words, name: words }),
     flow_create: z.strictObject({ repo: words, name: words, definition: nested, trigger: nested.optional() }),
     flow_starter: z.strictObject({ repo: words, starter: words }),
+    // Lead fan-out (docs/plans/lead-fan-out.md): N tasks under one brief, one yes.
+    sweep_cancel_rest: z.strictObject({ sweep: id }),
+    sweep_file: z.strictObject({ repo: words, title: words, brief: words, items: z.array(z.strictObject({ title: words, item: words })).min(2).max(20),
+        acceptance: z.array(z.unknown()).min(1), maxParallel: z.number().int().min(1).max(8) }),
     flow_edit: z.strictObject({ flow: id, name: words.optional(), definition: nested.optional() }),
     flow_card_add: z.strictObject({ flow: id, title: words, description: z.unknown().optional(), zone: words.optional() }),
     flow_card_move: z.strictObject({ card: id, zone: words }),

package/dist/contracts/chat-content.d.ts

@@ -31,6 +31,15 @@ export declare const chatContentShape: {
     }, z.core.$strict>>;
     task: z.ZodOptional<z.ZodString>;
     run: z.ZodOptional<z.ZodInt>;
+    /** A notice its person's watch may hold at the final fence (cockpit §3): set at planning only for a kind a watch
+     * can hold. Absent: never held (a security alert, the digest, anything unmarked). */
+    watch: z.ZodOptional<z.ZodLiteral<true>>;
+    /** Every task (and agent) a `watch` part covers, when it covers more than one: it is held only while its person is
+     * watching every one of them. */
+    subjects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ref: z.ZodNullable<z.ZodInt>;
+        run: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>>;
     edit: z.ZodOptional<z.ZodString>;
     phase: z.ZodOptional<z.ZodLiteral<"armed">>;
     link: z.ZodOptional<z.ZodObject<{
@@ -123,6 +132,11 @@ export declare const chatContentSchema: z.ZodObject<{
     }, z.core.$strict>>;
     task: z.ZodOptional<z.ZodString>;
     run: z.ZodOptional<z.ZodInt>;
+    watch: z.ZodOptional<z.ZodLiteral<true>>;
+    subjects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ref: z.ZodNullable<z.ZodInt>;
+        run: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>>;
     edit: z.ZodOptional<z.ZodString>;
     phase: z.ZodOptional<z.ZodLiteral<"armed">>;
     link: z.ZodOptional<z.ZodObject<{
@@ -205,6 +219,11 @@ export declare const savedChatPartSchema: z.ZodObject<{
     }, z.core.$strict>>;
     task: z.ZodOptional<z.ZodString>;
     run: z.ZodOptional<z.ZodInt>;
+    watch: z.ZodOptional<z.ZodLiteral<true>>;
+    subjects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ref: z.ZodNullable<z.ZodInt>;
+        run: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>>;
     edit: z.ZodOptional<z.ZodString>;
     phase: z.ZodOptional<z.ZodLiteral<"armed">>;
     link: z.ZodOptional<z.ZodObject<{

package/dist/contracts/chat-content.js

@@ -26,6 +26,12 @@ export const chatContentShape = {
     shot: z.strictObject({ follows: z.int().nullable() }).optional(),
     task: z.string().optional(),
     run: z.int().optional(),
+    /** A notice its person's watch may hold at the final fence (cockpit §3): set at planning only for a kind a watch
+     * can hold. Absent: never held (a security alert, the digest, anything unmarked). */
+    watch: z.literal(true).optional(),
+    /** Every task (and agent) a `watch` part covers, when it covers more than one: it is held only while its person is
+     * watching every one of them. */
+    subjects: z.array(z.strictObject({ ref: z.int().nullable(), run: z.int().nullable() })).max(100).optional(),
     edit: z.string().optional(),
     phase: z.literal("armed").optional(),
     link: link.optional(),

package/dist/contracts/cli.d.ts

@@ -647,6 +647,14 @@ export declare const COMMAND_OUTPUTS: {
             readable: z.ZodBoolean;
             zones: z.ZodArray<z.ZodUnknown>;
             triggers: z.ZodArray<z.ZodUnknown>;
+            unattended: z.ZodNullable<z.ZodObject<{
+                until: z.ZodString;
+                signedBy: z.ZodString;
+                budgetMicrousd: z.ZodNullable<z.ZodNumber>;
+                dailyRunCap: z.ZodNullable<z.ZodNumber>;
+                runsToday: z.ZodNumber;
+                covers: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>>;
         }, z.core.$loose>;
     }, z.core.$loose>, z.ZodObject<{
         envelopeVersion: z.ZodLiteral<1>;

package/dist/contracts/cli.js

@@ -184,7 +184,9 @@ export const COMMAND_OUTPUTS = {
     "task unhold": answers("task unhold", { id: str }),
     "task wait": answers("task wait", { task: str, outcome: str }),
     "flows list": answers("flows list", { flows: z.array(flowListed) }),
-    "flows show": answers("flows show", { flow: z.looseObject({ id: int, name: str, repo: str, project: str, readable: z.boolean(), zones: list, triggers: list }) }),
+    "flows show": answers("flows show", { flow: z.looseObject({ id: int, name: str, repo: str, project: str, readable: z.boolean(), zones: list, triggers: list,
+            // Whether the flow runs on its own, and until when (null: it doesn't).
+            unattended: nullable(z.looseObject({ until: str, signedBy: str, budgetMicrousd: nullable(int), dailyRunCap: nullable(int), runsToday: int, covers: z.array(str) })) }) }),
     grants: answers("grants", { count: int, grants: list }),
     "runner list": answers("runner list", { count: int, runners: list }),
     "incident list": answers("incident list", { incidents: list }),