toolroll 0.9.18 → 0.9.20

package/dist/browser-workspace.d.ts

@@ -912,6 +912,8 @@ export type BrowserFlowTrigger = {
     status: string | null;
     statusAt: string | null;
     failing: boolean;
+    /** Where the status points a person (a plane review's long waits: Needs you). */
+    statusLink: BrowserLink | null;
     button: {
         label: string;
         questions: string[];

package/dist/chat-delivery.js

@@ -677,13 +677,21 @@ function planResultShots(options, binding, notification, repos, id, now) {
     if (plan.kind === "none" || notification.taskId === null || notification.run === null)
         return;
     const where = { task: notification.taskId, run: notification.run };
-    // The result's message here: its finished-work batch (quiet), or its progress card (every step).
+    // The result's message here: its finished-work batch (quiet), its progress card (every step), or the result's own
+    // notice. The transport threads the screenshots under it once it is posted, and holds them until then.
     const follows = (() => {
         const batch = notification.taskRef === null ? null : store.chatBatchMessageFor(`${state.channel}:${binding.id}`, notification.taskRef, notification.run);
         if (batch !== null)
             return Number(batch);
         const card = state.prepare("SELECT part FROM chat_progress WHERE binding=? AND run=?").get(binding.id, notification.run);
-        return card === undefined ? null : Number(card.part);
+        if (card !== undefined)
+            return Number(card.part);
+        for (const one of store.handle.prepare("SELECT id FROM notification WHERE source_run=? AND recipient IS NULL AND id<? ORDER BY id DESC").all(notification.run, notification.id)) {
+            const part = state.prepare("SELECT id FROM chat_part WHERE event=? ORDER BY id LIMIT 1").get(chatHash(`${state.channel}:notice:${binding.id}:${Number(one["id"])}`));
+            if (part !== undefined)
+                return Number(part.id);
+        }
+        return null;
     })();
     const image = (artifact, sha256) => ({ taskId: where.task, run: where.run, artifact, sha256 });
     const parts = plan.kind === "line" ? [{ text: plan.text, ...where }]

package/dist/discord-chat.js

@@ -2,7 +2,7 @@
 import { chatQuestionButtons } from "./teammate-question.js";
 import { chatAskButtons } from "./chat-ask.js";
 import { chatFlowButtons } from "./chat-flow.js";
-import { refuseResultShots, resultShotsPruned } from "./result-shots.js";
+import { refuseResultShots, resultShotsPruned, shotWaitsUntil } from "./result-shots.js";
 import { channelInbox } from "./chat-inbox.js";
 import { roomCommand } from "./chat-rooms.js";
 import { ChatState, ChatDeliveryError, chatHash, } from "./chat-delivery-state.js";
@@ -210,8 +210,13 @@ export async function deliverDiscordPart(options) {
             state.prepare("UPDATE chat_part SET state='dropped',problem='Removed by retention' WHERE id=?").run(row.id);
             return true;
         }
-        // A screenshot sent with a result replies to that result's message once it is placed.
-        const follows = content.shot?.follows == null ? undefined : state.prepare("SELECT message FROM chat_part WHERE id=? AND state='sent'").get(content.shot.follows)?.message;
+        // A screenshot sent with a result replies to that result's message once it is placed, and waits until then.
+        const result = content.shot?.follows == null ? undefined : state.prepare("SELECT message,state,next_at FROM chat_part WHERE id=?").get(content.shot.follows);
+        if (result !== undefined && !discordId(result["message"]) && result["state"] === "pending") {
+            state.prepare("UPDATE chat_part SET next_at=? WHERE id=?").run(shotWaitsUntil(result["next_at"], now), row.id);
+            return true;
+        }
+        const follows = result?.["message"];
         const thread = discordId(follows) ? String(follows) : event.thread;
         if (content.image) {
             const image = verifyResultImage(store, options.evidenceRoot, repos, content.image);

package/dist/flow-triggers.d.ts

@@ -199,6 +199,13 @@ export declare function firePlaneReview(store: Store, trigger: FlowTriggerRow, c
     joined: number;
     said: string;
 }>;
+/** Where a person sees everything that waits on them. */
+export declare const NEEDS_YOU_HREF = "/work?view=needs-you";
+/** A plane review whose summary mentions long waits on a person links to Needs you. */
+export declare function planeStatusLink(config: TriggerConfig | null, status: string | null): {
+    label: string;
+    href: string;
+} | null;
 /** v96: a schedule (a teammate's routine) makes its card now, once per press, and keeps its own times. */
 export declare function runScheduleNow(store: Store, trigger: FlowTriggerRow, actor: string, now: Date): {
     ok: true;

package/dist/flow-triggers.js

@@ -16,7 +16,9 @@
  * - plane-review — every day at a set time (07:30 in the computer's time zone unless it says),
  *              the plane's last 24 hours read straight from the store (plane-review.ts): one card
  *              per distinct problem worth fixing, and the same problem on a later day joins its
- *              card while that card is still open. A clean day makes nothing. Its row is kept as a
+ *              card while that card is still open. A clean day makes nothing. Waits only a person
+ *              can end make no card; ones over three days are mentioned once in its summary line,
+ *              linked to Needs you. Its row is kept as a
  *              'schedule' (the table's kinds are fixed); its settings say what it is.
  *
  * GitHub and Linear are checked by the worker's pass — `gh` and one HTTPS
@@ -615,10 +617,14 @@ export async function firePlaneReview(store, trigger, config, now, scheduled) {
     if (flow === null || flow.state !== "active")
         return done("The flow isn't active.");
     // Loaded when a review first runs: the reader reaches the integrations and task status, which reach back to these triggers.
-    const { problemCard, problemText, reviewPlane } = await import("./plane-review.js");
+    const { longPersonWaits, longWaitWords, problemCard, problemText, reviewPlane } = await import("./plane-review.js");
     // Only the projects the flow's owner may see: a flow's cards are read by everyone on its project.
     const owner = store.accountOf(flow.owner);
-    const problems = reviewPlane(store, now, repo => owner === null || (repo !== null && store.accountCanAccess(flow.owner, repo)) || (repo === null && owner.projects === null));
+    const canSee = (repo) => owner === null || (repo !== null && store.accountCanAccess(flow.owner, repo)) || (repo === null && owner.projects === null);
+    const problems = reviewPlane(store, now, canSee);
+    // Long waits on a person are said here once, linked to Needs you (planeStatusLink), and file nothing.
+    const waited = longWaitWords(longPersonWaits(store, now, canSee));
+    const said = (words) => waited === null ? words : `${words} ${waited}`;
     const timeZone = schedule !== null && schedule.kind !== "every" ? schedule.timezone ?? "UTC" : "UTC";
     const day = new Intl.DateTimeFormat("en-CA", { year: "numeric", month: "2-digit", day: "2-digit", timeZone }).format(now);
     const dayWords = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone }).format(now);
@@ -646,10 +652,16 @@ export async function firePlaneReview(store, trigger, config, now, scheduled) {
             skipped.push(made.note);
     }
     if (problems.length === 0)
-        return done("A clean day: nothing to fix.");
+        return done(said("A clean day: nothing to fix."));
     const parts = [added > 0 ? `Added ${plural(added, "card")}.` : null, joined > 0 ? `${plural(joined, "problem")} came back and joined ${joined === 1 ? "its card" : "their cards"}.` : null,
         skipped.length > 0 ? `Left out ${plural(skipped.length, "problem")}: ${skipped[0]}.` : null].filter(one => one !== null);
-    return done(parts.length === 0 ? "Nothing new since this morning's review." : parts.join(" "), added, joined);
+    return done(said(parts.length === 0 ? "Nothing new since this morning's review." : parts.join(" ")), added, joined);
+}
+/** Where a person sees everything that waits on them. */
+export const NEEDS_YOU_HREF = "/work?view=needs-you";
+/** A plane review whose summary mentions long waits on a person links to Needs you. */
+export function planeStatusLink(config, status) {
+    return config?.kind === "plane-review" && status !== null && /waited over \d+ days for you\.$/.test(status) ? { label: "Needs you", href: NEEDS_YOU_HREF } : null;
 }
 /** v96: a schedule (a teammate's routine) makes its card now, once per press, and keeps its own times. */
 export function runScheduleNow(store, trigger, actor, now) {

package/dist/flows-ui.js

@@ -1,5 +1,5 @@
 import { draftFor, flowDefinitionOf } from "./flow-engine.js";
-import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, readHooksBase, readLinearKey, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
+import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, planeStatusLink, readHooksBase, readLinearKey, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
 import { deciderOf, FLOW_COLORS, FLOW_KIND_WORDS, FLOW_STAGE_KINDS } from "./flows.js";
 import { flowInsights, troubleWords } from "./flow-insights.js";
 import { parseSortDecision, sortChip } from "./flow-sort.js";
@@ -152,7 +152,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         return {
             id: trigger.id, kind: trigger.kind, words: config === null ? "This trigger can't be read." : describeTrigger(config, store),
             ...(config === null ? { name: "Trigger", detail: "Can't be read" } : triggerHeadline(config, store)),
-            zone: title(config?.zone ?? definition?.start ?? ""), zoneId: config?.zone ?? definition?.start ?? "", state: trigger.state, status: trigger.lastOutcome, statusAt: trigger.lastAt, failing: trigger.failures > 0,
+            zone: title(config?.zone ?? definition?.start ?? ""), zoneId: config?.zone ?? definition?.start ?? "", state: trigger.state, status: trigger.lastOutcome, statusLink: planeStatusLink(config, trigger.lastOutcome), statusAt: trigger.lastAt, failing: trigger.failures > 0,
             button: config?.kind === "button" ? { label: config.label, questions: config.questions } : null,
             hook: config !== null && takesDeliveries(config) ? { ready: hookReady(trigger, setup.dir), needsSecret: config.kind === "linear" } : null,
             checkable: ((config?.kind === "github" || config?.kind === "linear") && config.delivery === "poll") || config?.kind === "email" || (config?.kind === "schedule" && config.script !== undefined) || config?.kind === "plane-review",

package/dist/invoke.d.ts

@@ -39,6 +39,9 @@ export type AgentOutcome = {
     sessionId: string | null;
     /** The agent's spoken conclusion — diagnostics, never the handoff. */
     finalMessage: string | null;
+    /** Claude's `structured_output` alone (see ParsedEnvelope) — the only
+     * field a structured handback may be read from. */
+    structuredOutput?: string | null;
     /** The harness's own account of the ending, when its dialect has one. */
     ending?: AgentEnding | null;
     usage: ProviderUsage;

package/dist/invoke.js

@@ -550,6 +550,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             notFound: result.notFound,
             sessionId: envelope.sessionId,
             finalMessage: envelope.finalMessage,
+            structuredOutput: envelope.structuredOutput ?? null,
             ending: envelope.ending ?? null,
             usage: {
                 tokensIn: envelope.tokensIn,

package/dist/plane-review.d.ts

@@ -11,6 +11,8 @@ export type PlaneProblem = {
     evidence: string[];
 };
 export declare const REVIEW_HOURS = 24;
+/** A person's wait this long is mentioned in the review's summary line. */
+export declare const LONG_WAIT_DAYS = 3;
 export declare const RUN_CAUSES: readonly ["provider", "sign-in", "check", "timeout", "no-handoff", "stuck-lease", "orphaned", "no-change", "other"];
 export type RunCause = (typeof RUN_CAUSES)[number];
 /** Anything shaped like a key is hidden; one short line. */
@@ -30,6 +32,19 @@ export declare function runCause(run: {
  * project counts only when every project may be seen).
  */
 export declare function reviewPlane(store: Store, now: Date, canSee?: (repo: string | null) => boolean): PlaneProblem[];
+/**
+ * Results nobody has opened, and tasks waiting on a person's answer, approval or hold, for over `LONG_WAIT_DAYS`
+ * before `now`. Counted for the review's summary line only; they are never problems.
+ */
+export declare function longPersonWaits(store: Store, now: Date, canSee?: (repo: string | null) => boolean): {
+    results: number;
+    tasks: number;
+};
+/** "3 results have waited over 3 days for you." — or null when nothing has. */
+export declare function longWaitWords(waits: {
+    results: number;
+    tasks: number;
+}): string | null;
 /** A problem as a card's details (or a day's note on a card it joins). */
 export declare function problemText(problem: PlaneProblem, day: string): string;
 /** The card's opening details: the day's evidence, and what it is. */

package/dist/plane-review.js

@@ -6,7 +6,9 @@
  * - failed or no-change runs, grouped by cause (provider error, sign-in
  *   expiry, check failure, timeout, quit without handoff, stuck lease,
  *   orphaned process, no change, other);
- * - tasks waiting on a person for over a day, grouped by what they wait for;
+ * - tasks stuck for over a day on something the system must fix (unfinished
+ *   work no worker holds, repeated failures, an incident hold), grouped by
+ *   what they wait for;
  * - sign-in and plan-limit pauses, per provider;
  * - chat replies that couldn't be delivered, per app;
  * - integrations that are Broken (integration_check);
@@ -17,6 +19,13 @@
  * problem (flow-triggers.ts joins it to its card), and carries counts, run
  * ids and short evidence excerpts with anything shaped like a secret hidden.
  * A clean day is no problems at all. Only projects the reader may see count.
+ *
+ * Waits only a person can end — a result to open, a question to answer, a
+ * plan or task to approve, a hold to lift, a scope to write — are never
+ * problems: each card starts a find-the-cause → fix → pull request flow, and
+ * no code change opens a result for someone. Needs you and chat already ask
+ * the person. `longPersonWaits` counts the ones over `LONG_WAIT_DAYS` so the
+ * review's own summary line can mention them once, filing nothing.
  */
 import { scanForSecrets } from "./evidence.js";
 import { scrubIntegrationText } from "./integrations.js";
@@ -24,8 +33,10 @@ import { taskWaitSnapshot } from "./lead-status.js";
 export const REVIEW_HOURS = 24;
 const EVIDENCE_LINES = 5;
 const WAITING_DAYS = 1;
-/** A Ready result older than this is history, not today's problem. */
-const READY_WINDOW_DAYS = 7;
+/** A person's wait this long is mentioned in the review's summary line. */
+export const LONG_WAIT_DAYS = 3;
+/** What a person, not the code, must do next (lead-status.ts `taskWaitSnapshot`). The rest have a system cause. */
+const PERSON_NEXT = new Set(["Open result", "Answer the task's question", "Answer question", "Remove hold", "Review plan", "Resume or close attempt", "Choose a result", "Approve plan", "Add scope", "Approve task"]);
 export const RUN_CAUSES = ["provider", "sign-in", "check", "timeout", "no-handoff", "stuck-lease", "orphaned", "no-change", "other"];
 const CAUSE_TITLES = {
     provider: "Runs failed on a provider error",
@@ -140,24 +151,12 @@ export function reviewPlane(store, now, canSee = () => true) {
         const run = Number(row["run"]);
         add("run/orphaned", CAUSE_TITLES.orphaned, ["run", "runs"], { run, evidence: `Run ${run} (task ${str(row["task"]) ?? "?"}): process ${str(row["pid"]) ?? "?"} on ${excerpt(str(row["host"]), 40)} was still running after it finished` });
     }
-    // Tasks waiting on a person for over a day, by what they wait for.
-    const waited = new Date(now.getTime() - WAITING_DAYS * 86_400_000).toISOString();
-    const readyFrom = new Date(now.getTime() - READY_WINDOW_DAYS * 86_400_000).toISOString();
-    const tasks = store.handle.prepare(`SELECT task.id, task.title, task.updated_at, ref.repo FROM task JOIN task_ref ref ON ref.backend = 'built-in' AND ref.external_id = task.id
-    WHERE task.updated_at <= ? AND (task.state IN ('queued', 'running') OR (task.state = 'done' AND task.updated_at >= ?)) ORDER BY task.updated_at LIMIT 500`).all(waited, readyFrom);
-    for (const row of tasks) {
-        if (!canSee(str(row["repo"])))
-            continue;
-        // A version a later revision replaced never waits on its own.
-        const family = store.taskFamilyOf(String(row["id"]), null, true);
-        if (family !== null && family.current.id !== String(row["id"]))
-            continue;
-        const snapshot = taskWaitSnapshot(store, String(row["id"]), now);
-        if (snapshot === null || (snapshot.reason !== "needs-person" && snapshot.reason !== "ready"))
+    // Tasks stuck for over a day on a system cause, by what they wait for. Waits on a person are never cards.
+    for (const wait of openWaits(store, new Date(now.getTime() - WAITING_DAYS * 86_400_000), now, canSee)) {
+        if (wait.person)
             continue;
-        const days = Math.floor((now.getTime() - Date.parse(String(row["updated_at"]))) / 86_400_000);
-        add(`waiting/${keyPart(snapshot.next)}`, `Tasks waited over a day: ${snapshot.next}`, ["task", "tasks"], { run: snapshot.run,
-            evidence: `Task ${String(row["id"])} “${excerpt(str(row["title"]), 80)}”: ${plural(days, "day")} waiting` });
+        add(`waiting/${keyPart(wait.next)}`, `Tasks waited over a day: ${wait.next}`, ["task", "tasks"], { run: wait.run,
+            evidence: `Task ${wait.id} “${excerpt(wait.title, 80)}”: ${plural(wait.days, "day")} waiting` });
     }
     // Sign-in and plan-limit pauses.
     if (tableExists(store, "provider_auth_pause")) {
@@ -227,6 +226,49 @@ export function reviewPlane(store, now, canSee = () => true) {
             summary: `${plural(bucket.count, bucket.noun[0], bucket.noun[1])} in the last ${REVIEW_HOURS} hours${runsList.length === 0 ? "" : ` (${runsList.length === 1 ? "run" : "runs"} ${runsList.slice(0, 12).join(", ")}${runsList.length > 12 ? ", …" : ""})`}.` };
     }).sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
 }
+/** Queued or running tasks last touched by `before` that wait, and on what; replaced versions never wait on their own. */
+function openWaits(store, before, now, canSee) {
+    const rows = store.handle.prepare(`SELECT task.id, task.title, task.updated_at, ref.repo FROM task JOIN task_ref ref ON ref.backend = 'built-in' AND ref.external_id = task.id
+    WHERE task.updated_at <= ? AND task.state IN ('queued', 'running') ORDER BY task.updated_at LIMIT 500`).all(before.toISOString());
+    return waitsOf(store, rows, now, canSee);
+}
+function waitsOf(store, rows, now, canSee) {
+    const waits = [];
+    for (const row of rows) {
+        if (!canSee(str(row["repo"])))
+            continue;
+        const id = String(row["id"]);
+        const family = store.taskFamilyOf(id, null, true);
+        if (family !== null && family.current.id !== id)
+            continue;
+        const snapshot = taskWaitSnapshot(store, id, now);
+        if (snapshot === null || (snapshot.reason !== "needs-person" && snapshot.reason !== "ready"))
+            continue;
+        waits.push({ id, title: str(row["title"]), next: snapshot.next, run: snapshot.run, days: Math.floor((now.getTime() - Date.parse(String(row["updated_at"]))) / 86_400_000),
+            person: snapshot.reason === "ready" || PERSON_NEXT.has(snapshot.next) });
+    }
+    return waits;
+}
+/**
+ * Results nobody has opened, and tasks waiting on a person's answer, approval or hold, for over `LONG_WAIT_DAYS`
+ * before `now`. Counted for the review's summary line only; they are never problems.
+ */
+export function longPersonWaits(store, now, canSee = () => true) {
+    const before = new Date(now.getTime() - LONG_WAIT_DAYS * 86_400_000);
+    // Newest first, so years of Complete work never crowds out this week's unopened results.
+    const finished = store.handle.prepare(`SELECT task.id, task.title, task.updated_at, ref.repo FROM task JOIN task_ref ref ON ref.backend = 'built-in' AND ref.external_id = task.id
+    WHERE task.updated_at <= ? AND task.state = 'done' ORDER BY task.updated_at DESC LIMIT 500`).all(before.toISOString());
+    const results = waitsOf(store, finished, now, canSee).filter(wait => wait.person).length;
+    const tasks = openWaits(store, before, now, canSee).filter(wait => wait.person).length;
+    return { results, tasks };
+}
+/** "3 results have waited over 3 days for you." — or null when nothing has. */
+export function longWaitWords(waits) {
+    const parts = [waits.results > 0 ? plural(waits.results, "result") : null, waits.tasks > 0 ? plural(waits.tasks, "task") : null].filter(one => one !== null);
+    if (parts.length === 0)
+        return null;
+    return `${parts.join(" and ")} ${waits.results + waits.tasks === 1 ? "has" : "have"} waited over ${LONG_WAIT_DAYS} days for you.`;
+}
 /** A problem as a card's details (or a day's note on a card it joins). */
 export function problemText(problem, day) {
     return [`${day}: ${problem.summary}`, ...problem.evidence.map(line => `- ${line}`)].join("\n");

package/dist/provider.d.ts

@@ -68,6 +68,10 @@ export type Invocation = {
      * Codex renders it as its own sandbox profile; Claude as deny rules for
      * its file tools (its shell is fenced by the macOS sandbox around it). */
     fence?: readonly string[];
+    /** Claude's structured-output floor for a non-review phase: the scout's
+     * report rides the terminal result event instead of a file plan mode
+     * would refuse to write. Ignored by providers without `--json-schema`. */
+    jsonSchema?: Readonly<Record<string, unknown>>;
 };
 export type ProviderRunner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
 /** The harness's own account of how a turn ended. */
@@ -86,6 +90,10 @@ export type ParsedEnvelope = {
     protocolError: string | null;
     /** The agent's spoken conclusion — diagnostics only, never the handoff. */
     finalMessage: string | null;
+    /** Claude's schema-validated `structured_output` alone, re-serialized —
+     * never the prose result, even when that prose is JSON. Absent or null
+     * when the turn ran without `--json-schema` or returned none. */
+    structuredOutput?: string | null;
     /** How the harness said the turn ended (claude: the result's subtype and
      * turn count) — absent on dialects that carry no such record. */
     ending?: AgentEnding | null;

package/dist/provider.js

@@ -229,7 +229,8 @@ const claudeArgv = (invocation) => [
             // Headless (run 2085): a wakeup, cron job or monitor needs a later
             // turn that a -p process never gets. Denied at the harness too.
             "--disallowedTools", HEADLESS_DISALLOWED_TOOLS.join(","),
-            ...(invocation.toolArgv ?? []), ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : [])
+            ...(invocation.toolArgv ?? []), ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : []),
+            ...(invocation.jsonSchema === undefined ? [] : ["--json-schema", JSON.stringify(invocation.jsonSchema)])
         ]),
 ];
 /**
@@ -276,6 +277,9 @@ function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConf
                 ? "the Claude init event and terminal result announced different session ids"
                 : null,
         finalMessage: claudeFinalMessage(result),
+        structuredOutput: result === null || result.structured_output === undefined || result.structured_output === null
+            ? null
+            : JSON.stringify(result.structured_output),
         ending: result === null ? null : {
             subtype: typeof result.subtype === "string" ? result.subtype : null,
             turns: typeof result.num_turns === "number" && result.num_turns >= 0 ? result.num_turns : null,

package/dist/result-shots.d.ts

@@ -39,6 +39,8 @@ export type ResultShotsPlan =
  * no wait in between, or asks again.
  */
 export declare function resultShotsFor(store: Store, evidenceRoot: string | undefined, repos: readonly string[], row: Pick<Notification, "kind" | "recipient" | "taskId" | "taskRef" | "run">, sent?: ReadonlySet<number>): ResultShotsPlan;
+/** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
+export declare function shotWaitsUntil(resultNextAt: unknown, now: Date): string;
 /** Retention removed this result's files: its screenshots go quietly, never as a complaint. */
 export declare function resultShotsPruned(evidenceRoot: string, run: number): boolean;
 /**

package/dist/result-shots.js

@@ -102,6 +102,11 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const remaining = shots.filter(one => !sent.has(one.artifact));
     return remaining.length === 0 ? { kind: "none", why: "sent" } : { kind: "send", taskId: row.taskId, run: row.run, shots: remaining };
 }
+/** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */
+export function shotWaitsUntil(resultNextAt, now) {
+    const soonest = new Date(now.getTime() + 1_000).toISOString();
+    return typeof resultNextAt === "string" && resultNextAt > soonest ? resultNextAt : soonest;
+}
 /** Retention removed this result's files: its screenshots go quietly, never as a complaint. */
 export function resultShotsPruned(evidenceRoot, run) {
     return existsSync(join(evidenceRoot, String(run), RETENTION_NOTE));

package/dist/scout-report.d.ts

@@ -39,4 +39,97 @@ export declare const REPORT_LIMITS: {
     readonly followUpTitle: 200;
     readonly followUpGoal: 2000;
 };
+/**
+ * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan
+ * mode only lets a session write its own plan file, so a Claude scout
+ * returns a report — or a question for the operator — as structured output
+ * on the terminal result event. Shape only, never the validator: byte caps,
+ * one-line titles and control characters stay `parseReport`'s and
+ * `parseDecision`'s, applied to the re-serialized body.
+ */
+export declare const SCOUT_OUTPUT_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: readonly ["report", "question"];
+        };
+        readonly report: {
+            readonly type: "object";
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                };
+                readonly summary: {
+                    readonly type: "string";
+                };
+                readonly report: {
+                    readonly type: "string";
+                };
+                readonly followUps: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly title: {
+                                readonly type: "string";
+                            };
+                            readonly goal: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["title", "goal"];
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly required: readonly ["title", "summary", "report"];
+            readonly additionalProperties: false;
+        };
+        readonly decision: {
+            readonly type: "object";
+            readonly properties: {
+                readonly urgency: {
+                    readonly type: "string";
+                    readonly enum: readonly ["blocking"];
+                };
+                readonly recap: {
+                    readonly type: "string";
+                };
+                readonly question: {
+                    readonly type: "string";
+                };
+                readonly options: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly label: {
+                                readonly type: "string";
+                            };
+                            readonly consequence: {
+                                readonly type: "string";
+                            };
+                            readonly reversible: {
+                                readonly type: "boolean";
+                            };
+                        };
+                        readonly required: readonly ["id", "label", "consequence", "reversible"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly recommendation: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["urgency", "recap", "question", "options", "recommendation"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly required: readonly ["kind"];
+    readonly additionalProperties: false;
+};
 export declare function parseReport(raw: string): ReportParseResult;

package/dist/scout-report.js

@@ -18,6 +18,69 @@ export const REPORT_LIMITS = {
     followUpTitle: 200,
     followUpGoal: 2_000,
 };
+const REPORT_SHAPE = {
+    type: "object",
+    properties: {
+        title: { type: "string" },
+        summary: { type: "string" },
+        report: { type: "string" },
+        followUps: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: { title: { type: "string" }, goal: { type: "string" } },
+                required: ["title", "goal"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["title", "summary", "report"],
+    additionalProperties: false,
+};
+/** The park mailbox's decision, the same fields `parseDecision` reads. */
+const DECISION_SHAPE = {
+    type: "object",
+    properties: {
+        urgency: { type: "string", enum: ["blocking"] },
+        recap: { type: "string" },
+        question: { type: "string" },
+        options: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    label: { type: "string" },
+                    consequence: { type: "string" },
+                    reversible: { type: "boolean" },
+                },
+                required: ["id", "label", "consequence", "reversible"],
+                additionalProperties: false,
+            },
+        },
+        recommendation: { type: "string" },
+    },
+    required: ["urgency", "recap", "question", "options", "recommendation"],
+    additionalProperties: false,
+};
+/**
+ * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan
+ * mode only lets a session write its own plan file, so a Claude scout
+ * returns a report — or a question for the operator — as structured output
+ * on the terminal result event. Shape only, never the validator: byte caps,
+ * one-line titles and control characters stay `parseReport`'s and
+ * `parseDecision`'s, applied to the re-serialized body.
+ */
+export const SCOUT_OUTPUT_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        kind: { type: "string", enum: ["report", "question"] },
+        report: REPORT_SHAPE,
+        decision: DECISION_SHAPE,
+    },
+    required: ["kind"],
+    additionalProperties: false,
+};
 function refuse(reason, message) {
     return { ok: false, problems: [{ reason, message }] };
 }