toolroll 0.5.0

package/dist/sync.js

@@ -0,0 +1,279 @@
+/**
+ * External dispatch's sync pass (v20; five review rounds are the spec).
+ *
+ * What this does: pulls a tracker's nominated work into the overlay as
+ * ORDINARY local tasks (mirrors), refreshes every known mirror's remote
+ * state, verifies the plane marker, and delivers pending write-back
+ * intents — all at daemon cadence, zero tokens.
+ *
+ * What this never does: touch claims or runs (the latch is a write to the
+ * mirror row; admission and completion enforce it), import issue BODIES
+ * (titles only, through the canonical proposal validator — a tracker
+ * anyone can write to is a prompt-injection surface), or treat absence
+ * from a capped listing as closure (every known mirror is fetched
+ * INDIVIDUALLY; only a COMPLETE pass advances freshness).
+ *
+ * The plane marker is detection, never a distributed lease: a fixed-name
+ * repository label carries this plane's id in its description. A 404 is
+ * semantic "missing" only AFTER an authenticated access proof on the
+ * repository itself — GitHub 404s private resources the caller cannot
+ * see, and that must read as an OPERATIONAL block, fail closed.
+ */
+import { createHash } from "node:crypto";
+import { run } from "./exec.js";
+import { describeFailure, parseJson } from "./backend.js";
+import { fileTaskProposal } from "./proposal.js";
+const GH = "gh";
+export const SYNC_TIMEOUT_MS = 20_000;
+export const MARKER_LABEL = "standing-orders-plane";
+/** Bounded forward scan: pages of 100, at most this many pages per pass. */
+export const MAX_FORWARD_PAGES = 10;
+const operational = (message) => ({ ok: false, kind: "operational", message });
+export function ghDispatchAdapter(runner = run, timeoutMs = SYNC_TIMEOUT_MS) {
+    const call = (args) => runner(GH, args, { timeoutMs });
+    return {
+        async repoAccess(remoteRepo) {
+            const result = await call(["api", `repos/${remoteRepo}`]);
+            if (result.code !== 0)
+                return operational(describeFailure(result));
+            const parsed = parseJson(result.stdout);
+            if (parsed === null || typeof parsed !== "object")
+                return operational("gh returned something unreadable for the repository");
+            const permissions = parsed["permissions"];
+            return { ok: true, push: permissions !== undefined && permissions["push"] === true };
+        },
+        async listAllOpen(remoteRepo) {
+            const issues = [];
+            for (let page = 1; page <= MAX_FORWARD_PAGES; page++) {
+                const result = await call(["api", `repos/${remoteRepo}/issues?state=open&per_page=100&page=${page}`]);
+                if (result.code !== 0)
+                    return operational(describeFailure(result));
+                const parsed = parseJson(result.stdout);
+                if (!Array.isArray(parsed))
+                    return operational("gh returned something that is not a list");
+                for (const raw of parsed) {
+                    const issue = readRemoteIssue(raw);
+                    // The issues API interleaves pull requests; a PR is not a task.
+                    if (issue !== null && !(typeof raw === "object" && raw !== null && "pull_request" in raw)) {
+                        issues.push(issue);
+                    }
+                }
+                if (parsed.length < 100)
+                    return { ok: true, issues, complete: true };
+            }
+            return { ok: true, issues, complete: false };
+        },
+        async getIssue(remoteRepo, number) {
+            const result = await call(["api", `repos/${remoteRepo}/issues/${number}`]);
+            if (result.code !== 0) {
+                // The caller has ALREADY proved authenticated access this pass, so a
+                // 404 here is the issue itself being gone.
+                return /404|Not Found/i.test(result.stderr) ? { ok: true, found: null } : operational(describeFailure(result));
+            }
+            const issue = readRemoteIssue(parseJson(result.stdout));
+            return issue === null ? operational("gh returned an issue in a shape we do not know") : { ok: true, found: issue };
+        },
+        async readMarker(remoteRepo) {
+            const result = await call(["api", `repos/${remoteRepo}/labels/${MARKER_LABEL}`]);
+            if (result.code !== 0) {
+                return /404|Not Found/i.test(result.stderr) ? { ok: true, plane: null, malformed: false } : operational(describeFailure(result));
+            }
+            const parsed = parseJson(result.stdout);
+            const description = parsed !== null && typeof parsed["description"] === "string" ? String(parsed["description"]) : "";
+            const match = /^plane:([0-9a-f]{16})$/.exec(description.trim());
+            if (match?.[1] !== undefined)
+                return { ok: true, plane: match[1], malformed: false };
+            return { ok: true, plane: null, malformed: true };
+        },
+        async writeMarker(remoteRepo, planeId) {
+            const result = await call([
+                "label", "create", MARKER_LABEL, "--repo", remoteRepo, "--force",
+                "--description", `plane:${planeId}`, "--color", "ededed",
+            ]);
+            return result.code === 0 ? { ok: true } : operational(describeFailure(result));
+        },
+        async deleteMarker(remoteRepo) {
+            const result = await call(["api", "-X", "DELETE", `repos/${remoteRepo}/labels/${MARKER_LABEL}`]);
+            return result.code === 0 || /404|Not Found/i.test(result.stderr) ? { ok: true } : operational(describeFailure(result));
+        },
+        async comment(remoteRepo, number, body) {
+            const result = await call(["issue", "comment", number, "--repo", remoteRepo, "--body", body]);
+            return result.code === 0 ? { ok: true } : operational(describeFailure(result));
+        },
+        async close(remoteRepo, number) {
+            const result = await call(["issue", "close", number, "--repo", remoteRepo]);
+            return result.code === 0 ? { ok: true } : operational(describeFailure(result));
+        },
+    };
+}
+function readRemoteIssue(record) {
+    if (typeof record !== "object" || record === null)
+        return null;
+    const raw = record;
+    if (typeof raw["number"] !== "number")
+        return null;
+    return {
+        number: raw["number"],
+        title: typeof raw["title"] === "string" ? raw["title"] : "",
+        state: String(raw["state"]).toLowerCase() === "closed" ? "closed" : "open",
+    };
+}
+/** ghi-<owner>-<name>-<n>-<hash8>: collision-resistant across long slugs. */
+export function mirrorTaskId(remoteRepo, remoteId) {
+    const hash = createHash("sha256").update(`${remoteRepo}#${remoteId}`).digest("hex").slice(0, 8);
+    const slug = remoteRepo.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 30);
+    return `ghi-${slug}-${remoteId}-${hash}`;
+}
+/**
+ * One pass over one dispatch grant. Order is the spec's: access proof →
+ * marker verdict → forward scan → reverse sweep (every known mirror,
+ * individually) → intent delivery → ledger close. Only a pass in which
+ * EVERY step succeeded closes `complete` and advances freshness.
+ */
+export async function syncPass(store, grant, adapter, now) {
+    const remoteRepo = grant.remoteRepo;
+    const report = { remoteRepo, outcome: "failed", detail: null, candidates: 0, mirrored: 0, latched: 0, delivered: 0 };
+    // 1. Authenticated access proof — WITHOUT it, every 404 downstream is
+    //    operational, and dispatch blocks immediately (no grace window).
+    const access = await adapter.repoAccess(remoteRepo);
+    if (!access.ok) {
+        store.setDispatchBlocked(grant.repo, grant.backend, "unreachable", now(), access.message);
+        report.outcome = "blocked";
+        report.detail = access.message;
+        return report;
+    }
+    // 2. The marker verdict — semantic states only from a complete response.
+    const marker = await adapter.readMarker(remoteRepo);
+    if (!marker.ok) {
+        store.setDispatchBlocked(grant.repo, grant.backend, "unreachable", now(), marker.message);
+        report.outcome = "blocked";
+        report.detail = marker.message;
+        return report;
+    }
+    if (marker.malformed) {
+        store.setDispatchBlocked(grant.repo, grant.backend, "multiple-or-malformed", now(), "the plane marker's description is not this tool's shape");
+        report.outcome = "blocked";
+        report.detail = "marker malformed";
+        return report;
+    }
+    if (marker.plane === null) {
+        store.setDispatchBlocked(grant.repo, grant.backend, "missing", now(), "no plane marker on the repository — enroll again to write it");
+        report.outcome = "blocked";
+        report.detail = "marker missing";
+        return report;
+    }
+    if (marker.plane !== grant.planeId) {
+        store.setDispatchBlocked(grant.repo, grant.backend, "foreign", now(), `the repository's marker names another plane (${marker.plane.slice(0, 6)}…)`);
+        report.outcome = "blocked";
+        report.detail = "foreign plane";
+        return report;
+    }
+    // A VERIFIED matching marker clears any standing block — transient or
+    // semantic — because verification is exactly what a block awaited. The
+    // LIVE row is read here; the caller's copy may predate the block.
+    const live = store.grantFor(grant.repo, grant.backend);
+    if (live?.dispatchBlocked != null) {
+        store.setDispatchBlocked(grant.repo, grant.backend, null, now());
+    }
+    const pass = store.openSyncPass(grant.backend, remoteRepo, now());
+    let capped = false;
+    // 3. Forward: candidates. Only selector=all ESTABLISHES from the scan —
+    //    'ours' mirrors are established at creation/intake, never nominated
+    //    by a listing (provenance is a record, not a label).
+    const listing = await adapter.listAllOpen(remoteRepo);
+    if (!listing.ok) {
+        store.closeSyncPass(pass.id, "failed", { candidates: 0, mirrored: 0 }, now(), listing.message);
+        report.detail = listing.message;
+        return report;
+    }
+    if (!listing.complete)
+        capped = true;
+    report.candidates = listing.issues.length;
+    for (const issue of listing.issues) {
+        const existing = store.mirrorByRemote(grant.backend, remoteRepo, String(issue.number));
+        if (existing !== null)
+            continue;
+        if (grant.selector !== "all")
+            continue;
+        const localId = mirrorTaskId(remoteRepo, String(issue.number));
+        const filed = store.transact(() => {
+            const made = fileTaskProposal(store, { id: localId, title: issue.title, repo: grant.repo, filedVia: "sync" }, now());
+            if (!made.ok)
+                return made;
+            const established = store.establishMirror({
+                localTaskId: made.id,
+                backend: grant.backend,
+                remoteRepo,
+                remoteId: String(issue.number),
+                provenance: "granted-all",
+                establishedBy: "sync",
+                syncGeneration: pass.generation,
+            }, now());
+            if (!established.ok)
+                throw new Error(`mirror not established: ${established.reason}`);
+            return made;
+        });
+        if (filed.ok)
+            report.mirrored += 1;
+        // A title the validator refuses is NOT mirrored — the pass records it
+        // in detail and stays honest about the count.
+        else if (report.detail === null)
+            report.detail = `refused: ${filed.message}`;
+    }
+    // 4. Reverse: every known mirror, individually — absence from a listing
+    //    proves nothing (finding 2).
+    let reverseFailed = null;
+    for (const mirror of store.externalMirrors(grant.backend, remoteRepo)) {
+        const seen = await adapter.getIssue(remoteRepo, mirror.remoteId);
+        if (!seen.ok) {
+            reverseFailed = seen.message;
+            break;
+        }
+        if (seen.found === null) {
+            store.latchMirror(mirror.localTaskId, "missing", pass.generation, now());
+            report.latched += 1;
+        }
+        else if (seen.found.state === "closed") {
+            store.latchMirror(mirror.localTaskId, "closed", pass.generation, now());
+            report.latched += 1;
+        }
+        else {
+            store.observeMirrorOpen(mirror.localTaskId, pass.generation);
+        }
+    }
+    if (reverseFailed !== null) {
+        store.closeSyncPass(pass.id, "failed", { candidates: report.candidates, mirrored: report.mirrored }, now(), reverseFailed);
+        report.detail = reverseFailed;
+        return report;
+    }
+    // 5. Intents, under the grant's classes exactly — a denial is a typed
+    //    refusal on the intent's own ledger, never a run rewrite.
+    for (const intent of store.pendingExternalIntents()) {
+        const mirror = store.mirrorByTask(intent.mirror);
+        if (mirror === null || mirror.remoteRepo !== remoteRepo || mirror.backend !== grant.backend)
+            continue;
+        const allowed = intent.kind === "comment"
+            ? grant.mutations.includes("comment")
+            : intent.kind === "close"
+                ? grant.mutations.includes("close")
+                : grant.mutations.includes("transition");
+        if (!allowed) {
+            store.settleExternalIntent(intent.id, "refused", now(), `the grant does not allow ${intent.kind}`);
+            continue;
+        }
+        const sent = intent.kind === "comment"
+            ? await adapter.comment(remoteRepo, mirror.remoteId, intent.body ?? "")
+            : await adapter.close(remoteRepo, mirror.remoteId);
+        if (sent.ok) {
+            store.settleExternalIntent(intent.id, "delivered", now());
+            report.delivered += 1;
+        }
+        else {
+            store.settleExternalIntent(intent.id, "refused", now(), sent.message);
+        }
+    }
+    const outcome = capped ? "capped" : "complete";
+    store.closeSyncPass(pass.id, outcome, { candidates: report.candidates, mirrored: report.mirrored }, now(), report.detail);
+    report.outcome = outcome;
+    return report;
+}

package/dist/task-composer.d.ts

@@ -0,0 +1,13 @@
+/** UI choices translate into the same digest-bound schedules as the CLI. */
+import { type Schedule } from "./routine.js";
+export declare function composerSchedule(fields: URLSearchParams): {
+    ok: true;
+    schedule: string | null;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function scheduleFields(schedule: Schedule): Record<string, string>;
+/** A normal form works without JavaScript; enhancement only folds unused fields. */
+export declare function scheduleEditorHtml(raw: string | null, submitted?: URLSearchParams): string;
+export declare function scheduleEditorScript(): string;

package/dist/task-composer.js

@@ -0,0 +1,52 @@
+/** UI choices translate into the same digest-bound schedules as the CLI. */
+import { parseSchedule, scheduleText, validTimezone } from "./routine.js";
+export function composerSchedule(fields) {
+    const repeat = fields.get("repeat") ?? "once";
+    if (repeat === "once")
+        return { ok: true, schedule: null };
+    if (!["daily", "weekly", "custom"].includes(repeat))
+        return { ok: false, message: "Choose how often this task repeats." };
+    if (repeat === "custom") {
+        const count = Number(fields.get("interval"));
+        const unit = fields.get("interval-unit");
+        const multiplier = unit === "minutes" ? 1 : unit === "hours" ? 60 : unit === "days" ? 1440 : 0;
+        if (!Number.isInteger(count) || count < 1 || multiplier === 0 || parseSchedule(`every:${count * multiplier}`) === null)
+            return { ok: false, message: "Choose an interval between 5 minutes and 7 days." };
+        return { ok: true, schedule: `every:${count * multiplier}` };
+    }
+    const time = fields.get("time") ?? "";
+    const timezone = fields.get("timezone") ?? "UTC";
+    if (!validTimezone(timezone))
+        return { ok: false, message: "Choose a valid timezone." };
+    const text = `${repeat === "weekly" ? `weekly:${fields.get("weekday") ?? ""}` : "daily"}:${time}@${timezone}`;
+    const schedule = parseSchedule(text);
+    return schedule === null ? { ok: false, message: "Choose a valid time and day for this task." } : { ok: true, schedule: scheduleText(schedule) };
+}
+export function scheduleFields(schedule) {
+    if (schedule.kind === "every") {
+        const unit = schedule.minutes % 1440 === 0 ? "days" : schedule.minutes % 60 === 0 ? "hours" : "minutes";
+        return { repeat: "custom", interval: String(schedule.minutes / (unit === "days" ? 1440 : unit === "hours" ? 60 : 1)), "interval-unit": unit };
+    }
+    return { repeat: schedule.kind, time: schedule.hhmm, timezone: schedule.timezone ?? "UTC", ...(schedule.kind === "weekly" ? { weekday: String(schedule.day) } : {}) };
+}
+const escape = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+/** A normal form works without JavaScript; enhancement only folds unused fields. */
+export function scheduleEditorHtml(raw, submitted) {
+    const parsed = raw === null ? null : parseSchedule(raw);
+    const fields = submitted?.has("repeat") ? Object.fromEntries(submitted) : parsed === null ? {} : scheduleFields(parsed);
+    const repeat = fields.repeat ?? "daily";
+    const value = (name, fallback) => escape(fields[name] ?? fallback);
+    return `<fieldset data-schedule-editor${raw === null && submitted === undefined ? ' data-detect-timezone="true"' : ""}><legend>When to run</legend>` +
+        `<label>Repeat<select name="repeat">${[["daily", "Daily"], ["weekly", "Weekly"], ["custom", "Custom interval"]].map(([id, label]) => `<option value="${id}"${repeat === id ? " selected" : ""}>${label}</option>`).join("")}</select></label>` +
+        `<div data-schedule-kind="weekly"><label>Day<select name="weekday">${["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"].map((day, index) => `<option value="${index}"${String(index) === (fields.weekday ?? "1") ? " selected" : ""}>${day}</option>`).join("")}</select></label></div>` +
+        `<div data-schedule-kind="calendar"><label>Time<input type="time" name="time" value="${value("time", "09:00")}"></label><label>Timezone<input type="text" name="timezone" value="${value("timezone", "UTC")}" autocomplete="off" placeholder="America/Los_Angeles"></label><p class="meta">Daily and weekly times follow this timezone. A skipped clock time skips that occurrence; a repeated time runs once.</p></div>` +
+        `<div data-schedule-kind="custom"><label>Every<input type="number" name="interval" min="1" value="${value("interval", "60")}"></label><label>Unit<select name="interval-unit">${["minutes", "hours", "days"].map(unit => `<option${unit === (fields["interval-unit"] ?? "minutes") ? " selected" : ""}>${unit}</option>`).join("")}</select></label><p class="meta">Intervals range from 5 minutes to 7 days.</p></div></fieldset>`;
+}
+export function scheduleEditorScript() {
+    return `(function(){document.querySelectorAll('[data-schedule-editor]').forEach(function(root){
+    var repeat=root.querySelector('[name=repeat]'),zone=root.querySelector('[name=timezone]');
+    if(root.dataset.detectTimezone==='true'){try{zone.value=Intl.DateTimeFormat().resolvedOptions().timeZone||'UTC';}catch(e){}}
+    function update(){root.querySelectorAll('[data-schedule-kind]').forEach(function(group){var active=group.dataset.scheduleKind===repeat.value||(group.dataset.scheduleKind==='calendar'&&repeat.value!=='custom');group.hidden=!active;group.querySelectorAll('input,select').forEach(function(field){field.disabled=!active;});});}
+    repeat.addEventListener('change',update);update();
+  });})();`;
+}

package/dist/task-control.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Safe task stop and resume (v52): the ONE domain API every surface — the
+ * CLI, the authenticated console, the focused chat — speaks, and the fences
+ * every execution road consults.
+ *
+ * The contract, in the operator's words: a stop names one exact active
+ * attempt. The first answer is "stop requested", never "stopped" — the
+ * request is durable before any process is signalled, and the attempt is
+ * SETTLED only once all owned runs ended and retained process witnesses
+ * establish exit. A dead worker can leave live subprocesses; recovery
+ * keeps that stop pending. Other tasks keep running. The task stays
+ * paused across restarts under a hold this stop owns, beside — never over —
+ * any hold that already stood. Resume names the same exact attempt, refuses
+ * until it is quiescent, lifts only that hold, approves nothing, and lets
+ * the next pass re-prove the signed scope, take a fresh claim, and inherit
+ * the preserved draft with fresh proof.
+ *
+ * Nothing here is a second engine: the stop rides the existing run, claim,
+ * hold, recovery, invocation-gateway, and held-session machinery. This
+ * module only names the door and the fence.
+ */
+import { type DispatchDiagnosis } from "./dispatch.js";
+import type { Run, RunStop, Store } from "./store.js";
+/** How often a running attempt re-reads its stop row while a child runs.
+ * A stop is observed within this bound even when the console that filed
+ * it lives in another process on the same database. */
+export declare const STOP_WATCH_MS = 1500;
+/**
+ * The stop fence, as a predicate: an operator stop applies to the run (its
+ * own, or an owning ancestor's), or the caller's own watch-level stop says
+ * so. Every road that used to ask `shouldStop?.()` asks this instead.
+ */
+export declare function stopRequestedFor(store: Store, runId: number, also?: () => boolean): boolean;
+/** The words a road records when a stop wins: who asked, and where the
+ * work stays. */
+export declare function stopWords(store: Store, runId: number, worktree: string | null, fallback: string): string;
+/**
+ * End every live child THIS process holds for one attempt and its owned
+ * descendants — the exact-attempt handle, never a pid read from durable
+ * state. Returns how many process groups were signalled.
+ */
+export declare function terminateStoppedAttempt(store: Store, runId: number): number;
+/** Whether this process still tracks a live child for the attempt or any
+ * run it owns — the in-process half of "quiescent". */
+export declare function attemptHasLiveChildren(store: Store, runId: number): boolean;
+/**
+ * Run a child-bearing step under the stop watch: while `body` runs, the
+ * run's stop row is re-read every `intervalMs`; the moment a stop applies
+ * the run's owned children are killed through their handles and the
+ * caller's `onStop` fires once. The body's own settlement then observes
+ * the stop through `stopRequestedFor` and seals the attempt as
+ * interrupted — this watch never writes an outcome itself.
+ */
+export declare function underStopWatch<T>(store: Store, runId: number, body: () => Promise<T>, options?: {
+    intervalMs?: number;
+    onStop?: () => void;
+}): Promise<T>;
+export type StopRequest = {
+    taskId: string;
+    runId: number;
+    by: string;
+    via: "cli" | "web" | "telegram" | "slack" | "discord" | "teams";
+    /** The held-session supervisor in this process, when there is one: a
+     * held attempt is fenced through its own handle the moment the request
+     * is durable (the lapse interval would take the same road within
+     * seconds for a request filed elsewhere). */
+    held?: {
+        stop(runId: number): Promise<void>;
+    } | undefined;
+    /** A composing confirmation transaction runs this effect only after it commits. */
+    deferSignal?: ((signal: () => void) => void) | undefined;
+};
+export type StopOutcome = {
+    ok: true;
+    stop: RunStop;
+    repeated: boolean;
+    terminated: number;
+    taskId: string;
+} | {
+    ok: false;
+    reason: "no-task" | "no-run" | "wrong-task" | "finished" | "not-live" | "tournament" | "publication";
+    detail: string;
+};
+/**
+ * The shared stop door. Records the durable request first (one fenced
+ * transaction: exact run, still open, this task's current claim, no
+ * tournament, no admitted publication), THEN signals every child this
+ * process holds for the attempt. A worker in another process observes the
+ * same row through its stop watch within STOP_WATCH_MS.
+ */
+export declare function requestTaskStop(store: Store, request: StopRequest, now: Date): StopOutcome;
+export type ResumeRequest = {
+    taskId: string;
+    runId: number;
+    by: string;
+    via: "cli" | "web";
+    /** The workspace occupancy probe (the worktree pool's `inUse`): a
+     * checkout some process still holds is not quiescent, whatever the
+     * rows say — the concrete gate names the pid. */
+    occupied?: (worktree: string) => {
+        held: boolean;
+        by?: number | string | undefined;
+    };
+};
+export type ResumeOutcome = {
+    ok: true;
+    stop: RunStop;
+    taskId: string;
+    gate: DispatchDiagnosis | null;
+} | {
+    ok: false;
+    reason: "no-task" | "no-stop" | "wrong-task" | "stopping" | "already-resumed" | "superseded" | "busy" | "review" | "occupied";
+    detail: string;
+};
+/**
+ * The shared resume door. Refuses in words until the exact stopped attempt
+ * is quiescent — settled, every owned run ended, no live claim, its
+ * workspace not held by any process this machine can still see — then
+ * lifts exactly this stop's hold. `gate` reports what still keeps the
+ * next pass from starting work (an approval that must be signed again, a
+ * worker that is offline), so a resume that cannot yet start is never
+ * mistaken for one that did. A stopped review is refused here and pointed
+ * at the explicit bounded review-retry door.
+ */
+export declare function resumeTaskStop(store: Store, request: ResumeRequest, now: Date): ResumeOutcome;
+/**
+ * What a surface shows for one task (v52) — the SAME projection on the
+ * task page, the focused chat, `task show`, and the status fragment, so no
+ * two surfaces can disagree about which exact run a control names:
+ *
+ *   stop      — an attempt is live; the control names its run.
+ *   stopping  — a stop is recorded and not yet settled.
+ *   paused    — a settled stop stands on the task's newest attempt.
+ *   review-stopped — a review attempt was stopped; "Review again" is the
+ *               explicit bounded retry door.
+ *   none      — nothing to control.
+ */
+export type TaskControlView = {
+    kind: "none";
+} | {
+    kind: "stop";
+    run: number;
+    role: Run["role"];
+} | {
+    kind: "stopping";
+    run: number;
+    role: Run["role"];
+    stop: RunStop;
+    unsettledRun: boolean;
+    detail?: string | null;
+} | {
+    kind: "paused";
+    run: number;
+    role: Run["role"];
+    stop: RunStop;
+    outcome: Run["outcome"];
+    committed: boolean;
+    worktree: string | null;
+} | {
+    kind: "review-stopped";
+    run: number;
+    sourceRun: number | null;
+    stop: RunStop;
+};
+export declare function taskControlOf(store: Store, taskRef: number, now: Date): TaskControlView;