@sema-agent/core 2.8.0 → 2.10.0

package/dist/core/skills-directory.js

@@ -1,5 +1,6 @@
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { canonicalToolName } from "./tool-name-aliases.js";
 const SKILL_FILE = "SKILL.md";
 const RESOURCE_DIRS = ["assets", "references", "scripts"];
 const NAME_MAX_CHARS = 64;
@@ -22,26 +23,139 @@ function parseSkillFile(text) {
     }
     if (end === -1)
         return { fields, body: normalized, hadFrontmatter: false };
-    for (let i = 1; i < end; i++) {
+    let i = 1;
+    while (i < end) {
         const line = lines[i];
         const trimmed = line.trim();
-        if (trimmed === "" || trimmed.startsWith("#"))
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            i++;
             continue;
-        if (/^\s/.test(line))
+        }
+        if (/^\s/.test(line)) {
+            i++;
             continue;
+        }
         const kv = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(trimmed);
-        if (!kv)
+        if (!kv) {
+            i++;
             continue;
+        }
         const [, key, raw] = kv;
+        const rawValue = raw.trim();
+        const block = parseBlockScalarHeader(rawValue);
+        if (block !== undefined) {
+            const read = readBlockScalar(lines, i + 1, end, block);
+            i = read.next;
+            if (!fields.has(key))
+                fields.set(key, read.value);
+            continue;
+        }
+        if (rawValue.startsWith("[") && !isFlowSequenceClosed(rawValue)) {
+            const joined = readFlowSequenceContinuation(lines, i + 1, end, rawValue);
+            i = joined.next;
+            if (!fields.has(key))
+                fields.set(key, joined.value);
+            continue;
+        }
+        i++;
         if (fields.has(key))
             continue;
-        fields.set(key, unquote(raw.trim()));
+        fields.set(key, unquote(rawValue));
     }
     let body = lines.slice(end + 1).join("\n");
     if (body.startsWith("\n"))
         body = body.slice(1);
     return { fields, body, hadFrontmatter: true };
 }
+function parseBlockScalarHeader(value) {
+    const m = /^([|>])([0-9+-]*)$/.exec(value);
+    if (!m)
+        return undefined;
+    const rest = m[2];
+    if (!/^(?:[1-9]?[+-]?|[+-][1-9]?)$/.test(rest))
+        return undefined;
+    const digit = /[1-9]/.exec(rest)?.[0];
+    return { style: m[1] === "|" ? "literal" : "folded", ...(digit !== undefined ? { indent: Number(digit) } : {}) };
+}
+function readBlockScalar(lines, start, end, header) {
+    const indentOf = (s) => /^[ \t]*/.exec(s)[0].length;
+    let indent = header.indent;
+    if (indent === undefined) {
+        for (let j = start; j < end; j++) {
+            if (lines[j].trim() === "")
+                continue;
+            indent = indentOf(lines[j]);
+            break;
+        }
+    }
+    if (indent === undefined || indent === 0)
+        return { value: "", next: start };
+    const taken = [];
+    let j = start;
+    for (; j < end; j++) {
+        const line = lines[j];
+        if (line.trim() === "") {
+            taken.push("");
+            continue;
+        }
+        if (indentOf(line) < indent)
+            break;
+        taken.push(line.slice(indent));
+    }
+    while (taken.length > 0 && taken[taken.length - 1] === "")
+        taken.pop();
+    if (header.style === "literal")
+        return { value: taken.join("\n"), next: j };
+    let folded = "";
+    let blanks = 0;
+    let started = false;
+    let prevMoreIndented = false;
+    for (const cur of taken) {
+        if (cur === "") {
+            blanks++;
+            continue;
+        }
+        const moreIndented = indentOf(cur) > 0;
+        if (!started) {
+            folded = cur;
+            started = true;
+        }
+        else if (blanks > 0) {
+            folded += "\n".repeat(blanks) + cur;
+        }
+        else if (moreIndented || prevMoreIndented) {
+            folded += `\n${cur}`;
+        }
+        else {
+            folded += ` ${cur}`;
+        }
+        blanks = 0;
+        prevMoreIndented = moreIndented;
+    }
+    return { value: folded, next: j };
+}
+function isFlowSequenceClosed(text) {
+    let depth = 0;
+    for (const ch of text) {
+        if (ch === "[")
+            depth++;
+        else if (ch === "]")
+            depth--;
+    }
+    return depth <= 0;
+}
+function readFlowSequenceContinuation(lines, start, end, head) {
+    let acc = head;
+    let j = start;
+    for (; j < end; j++) {
+        acc += ` ${lines[j].trim()}`;
+        if (isFlowSequenceClosed(acc)) {
+            j++;
+            break;
+        }
+    }
+    return { value: acc, next: j };
+}
 function unquote(value) {
     if (value.length < 2)
         return value;
@@ -51,7 +165,13 @@ function unquote(value) {
     const inner = value.slice(1, -1);
     return q === '"' ? inner.replace(/\\t/g, "\t").replace(/\\n/g, "\n") : inner;
 }
-function listRelativeFiles(base, dir, prefix, out) {
+function isInsideRoot(root, p) {
+    if (p === root)
+        return true;
+    const rel = relative(root, p);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function listRelativeFiles(base, dir, prefix, out, walk) {
     let entries;
     try {
         entries = readdirSync(join(base, dir), { withFileTypes: true });
@@ -61,24 +181,68 @@ function listRelativeFiles(base, dir, prefix, out) {
     }
     for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
         const rel = `${prefix}${e.name}`;
-        if (e.isDirectory())
-            listRelativeFiles(base, join(dir, e.name), `${rel}/`, out);
-        else if (e.isFile())
+        const abs = join(base, dir, e.name);
+        const resolved = resolveInsideSkill(abs, rel, walk);
+        if (resolved === undefined)
+            continue;
+        if (resolved.stats.isDirectory()) {
+            if (walk.visited.has(resolved.real))
+                continue;
+            walk.visited.add(resolved.real);
+            listRelativeFiles(base, join(dir, e.name), `${rel}/`, out, walk);
+        }
+        else if (resolved.stats.isFile()) {
             out.push(rel);
+        }
+    }
+}
+function resolveInsideSkill(abs, rel, walk) {
+    let real;
+    let stats;
+    try {
+        real = realpathSync(abs);
+        stats = statSync(abs);
+    }
+    catch (err) {
+        walk.warn({ code: "attachment_skipped", skill: walk.skill, detail: `${rel}: could not be resolved (${errText(err)})` });
+        return undefined;
+    }
+    if (!isInsideRoot(walk.realRoot, real)) {
+        walk.warn({
+            code: "attachment_skipped",
+            skill: walk.skill,
+            detail: `${rel}: resolves outside the skill directory — skipped (attachments are collected from the declared skill directory only)`,
+        });
+        return undefined;
     }
+    return { real, stats };
 }
 function readAttachments(skillDir, skillName, budgetBytes, warn) {
+    let realRoot;
+    try {
+        realRoot = realpathSync(skillDir);
+    }
+    catch (err) {
+        warn({ code: "read_failed", skill: skillName, detail: `the skill directory could not be resolved (${errText(err)}) — attachments skipped` });
+        return [];
+    }
+    const walk = { realRoot, skill: skillName, warn, visited: new Set([realRoot]) };
     const relPaths = [];
     for (const d of RESOURCE_DIRS) {
-        let st;
+        let exists = true;
         try {
-            st = statSync(join(skillDir, d));
+            statSync(join(skillDir, d));
         }
         catch {
-            continue;
+            exists = false;
         }
-        if (st.isDirectory())
-            listRelativeFiles(skillDir, d, `${d}/`, relPaths);
+        if (!exists)
+            continue;
+        const resolved = resolveInsideSkill(join(skillDir, d), d, walk);
+        if (resolved === undefined || !resolved.stats.isDirectory())
+            continue;
+        walk.visited.add(resolved.real);
+        listRelativeFiles(skillDir, d, `${d}/`, relPaths, walk);
     }
     relPaths.sort();
     const files = [];
@@ -114,20 +278,60 @@ function isDecodableText(bytes) {
 function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
-function manifestFromAllowedTools(declared, skillName, deployedTools, warn) {
+const ALL_TOOLS_WILDCARD = "*";
+function splitToolNames(declared) {
+    let text = declared.trim();
+    if (text.startsWith("[") && text.endsWith("]"))
+        text = text.slice(1, -1);
     const names = [];
-    for (const n of declared.split(/\s+/)) {
-        if (n !== "" && !names.includes(n))
-            names.push(n);
+    let current = "";
+    let depth = 0;
+    const flush = () => {
+        const name = unquote(current.trim());
+        if (name !== "")
+            names.push(name);
+        current = "";
+    };
+    for (const ch of text) {
+        if (ch === "(") {
+            depth++;
+            current += ch;
+        }
+        else if (ch === ")") {
+            if (depth > 0)
+                depth--;
+            current += ch;
+        }
+        else if (depth === 0 && (ch === "," || /\s/.test(ch))) {
+            flush();
+        }
+        else {
+            current += ch;
+        }
+    }
+    flush();
+    return names;
+}
+function manifestFromAllowedTools(declared, disallowed, skillName, deployedTools, warn) {
+    const names = [];
+    const seen = new Set();
+    for (const n of splitToolNames(declared)) {
+        const key = canonicalToolName(n);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        names.push(n);
     }
     if (names.length === 0)
         return undefined;
+    if (names.some((n) => n === ALL_TOOLS_WILDCARD))
+        return undefined;
     let allowTools = names;
     if (deployedTools !== undefined) {
-        const mounted = new Set(deployedTools);
-        allowTools = names.filter((n) => mounted.has(n));
+        const mounted = new Set(deployedTools.map(canonicalToolName));
+        allowTools = names.filter((n) => mounted.has(canonicalToolName(n)));
         for (const n of names) {
-            if (!mounted.has(n)) {
+            if (!mounted.has(canonicalToolName(n))) {
                 warn({
                     code: "allowed_tool_not_mounted",
                     skill: skillName,
@@ -136,6 +340,10 @@ function manifestFromAllowedTools(declared, skillName, deployedTools, warn) {
             }
         }
     }
+    if (disallowed.length > 0) {
+        const denied = new Set(disallowed.map(canonicalToolName));
+        allowTools = allowTools.filter((n) => !denied.has(canonicalToolName(n)));
+    }
     return { allowTools, lineageId: `skill:${skillName}` };
 }
 export function createSkillsFromDirectory(dir, options = {}) {
@@ -153,10 +361,23 @@ export function createSkillsFromDirectory(dir, options = {}) {
     catch (err) {
         throw new Error(`skills directory could not be read: ${dir} (${errText(err)})`);
     }
-    const dirNames = entries
-        .filter((e) => e.isDirectory())
-        .map((e) => e.name)
-        .sort();
+    const dirNames = [];
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            dirNames.push(e.name);
+            continue;
+        }
+        if (!e.isSymbolicLink())
+            continue;
+        try {
+            if (statSync(join(dir, e.name)).isDirectory())
+                dirNames.push(e.name);
+        }
+        catch (err) {
+            warn({ code: "read_failed", skill: e.name, detail: `entry is a symbolic link that could not be resolved (${errText(err)}) — skipped` });
+        }
+    }
+    dirNames.sort();
     const skills = [];
     for (const name of dirNames) {
         const skillDir = join(dir, name);
@@ -200,7 +421,15 @@ export function createSkillsFromDirectory(dir, options = {}) {
             continue;
         }
         const allowed = parsed.fields.get("allowed-tools");
-        const manifest = allowed === undefined ? undefined : manifestFromAllowedTools(allowed, name, options.deployedTools, warn);
+        const disallowed = splitToolNames(parsed.fields.get("disallowed-tools") ?? "");
+        const manifest = allowed === undefined ? undefined : manifestFromAllowedTools(allowed, disallowed, name, options.deployedTools, warn);
+        if (disallowed.length > 0 && manifest === undefined) {
+            warn({
+                code: "disallowed_tools_unenforced",
+                skill: name,
+                detail: `disallowed-tools names ${disallowed.map((n) => `"${n}"`).join(", ")}, but this skill produced no allowlist to subtract from (allowed-tools is absent or claims every tool) — the deny declaration is NOT enforced (express it in the task's own tool policy)`,
+            });
+        }
         const files = readAttachments(skillDir, name, budget, warn);
         skills.push({
             name: declaredName,

package/dist/core/task-registry-agent.d.ts

@@ -2,7 +2,7 @@ import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./backgro
 import { type StopSource, type TaskAccess, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import { type ToolResultStore } from "./tool-result-store.js";
 export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
-export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: (keyof BackgroundAgentRecord)[]): void;
+export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: readonly (keyof BackgroundAgentRecord)[]): void;
 export declare function durableAgentArmedLane(core: DurableAgentCore, id: string): boolean;
 export declare function durableAgentRowProbeLane(core: DurableAgentCore, id: string): (() => Promise<boolean>) | undefined;
 export declare function beginDurableClaimLane(core: DurableAgentCore, id: string): boolean;
@@ -71,6 +71,7 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     errorKind?: string;
     stoppedBy?: StopSource;
     seq?: number;
+    cycle?: number;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function abortBackgroundAgentsForOwnerLane(core: DurableAgentCore, access: TaskAccess, opts?: {
     skipSessionScoped?: boolean;

package/dist/core/task-registry-agent.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { uuidv7 } from "../internal/harness.js";
-import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-agent-store.js";
+import { canAccessAgentRecord, BackgroundAgentStoreError, REVIVED_ROW_CLEARED_FIELDS, } from "./background-agent-store.js";
 import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { boundedRedactedSummary } from "./untrusted-egress.js";
@@ -652,6 +652,11 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     const handle = core.handles.get(id);
     if (!handle || handle.type !== "background_agent")
         return undefined;
+    if (outcome.cycle === undefined && (handle.reviveCycle ?? 0) !== 0) {
+        throw new Error(`settleBackgroundAgent("${id}"): the row has been revived (cycle ${handle.reviveCycle}) — pass the cycle this settle speaks for, or use settleRevivedAgent`);
+    }
+    if ((outcome.cycle ?? 0) !== (handle.reviveCycle ?? 0))
+        return undefined;
     if (handle.status !== "running") {
         if (handle.status === "killed") {
             mintCompletionId(handle);
@@ -859,31 +864,11 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
-    durableAgentWriteLane(handle, { status: "running" }, [
-        "settledAt",
-        "stoppedBy",
-        "finalOutput",
-        "finalOutputFull",
-        "error",
-        "errorCode",
-        "errorRetryable",
-        "errorKind",
-        "resultIsPartial",
-        "completionId",
-        "summary",
-        "recentSteps",
-        "editedFiles",
-        "usage",
-    ]);
+    durableAgentWriteLane(handle, { status: "running" }, REVIVED_ROW_CLEARED_FIELDS);
     return { ok: true, cycle: handle.reviveCycle };
 }
 export function settleRevivedAgentLane(core, id, cycle, outcome) {
-    const handle = core.handles.get(id);
-    if (!handle || handle.type !== "background_agent")
-        return undefined;
-    if ((handle.reviveCycle ?? 0) !== cycle)
-        return undefined;
-    return settleBackgroundAgentLane(core, id, outcome);
+    return settleBackgroundAgentLane(core, id, { ...outcome, cycle });
 }
 export function unmarkRetainedContinuationLane(core, id) {
     const handle = core.handles.get(id);
@@ -1023,18 +1008,33 @@ export function notFoundRunningAgentsTail(footer) {
     return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
         (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
 }
+function buildAgentPollDetails(input) {
+    const failed = input.status === "failed";
+    return {
+        task_id: input.taskId,
+        type: "background_agent",
+        status: input.status,
+        retrieval_status: input.retrievalStatus,
+        ...(input.seq !== undefined ? { seq: input.seq } : {}),
+        ...(input.status === "killed" && input.stoppedBy !== undefined ? { stoppedBy: input.stoppedBy } : {}),
+        ...(failed && input.error !== undefined ? { error: delimitUntrusted("agent error", boundedRedactedSummary(input.error, 300)) } : {}),
+        ...(failed && input.errorCode !== undefined ? { errorCode: input.errorCode } : {}),
+        ...(failed && input.errorRetryable !== undefined ? { retryable: input.errorRetryable } : {}),
+        ...(input.resultIsPartial === true ? { partial_result: true } : {}),
+        ...(input.completionId !== undefined ? { completionId: input.completionId } : {}),
+    };
+}
 export function serveDurableAgentRowLane(row) {
     if (row.status === "parked") {
         return {
             content: delimitUntrusted(`TaskOutput ${row.handle}`, `status: parked
 The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
-            details: {
-                task_id: row.handle,
-                type: "background_agent",
+            details: buildAgentPollDetails({
+                taskId: row.handle,
                 status: "parked",
-                retrieval_status: "success",
+                retrievalStatus: "success",
                 ...(row.seq !== undefined ? { seq: row.seq } : {}),
-            },
+            }),
         };
     }
     const kindClause = row.status === "failed" && row.errorKind !== undefined && row.errorRetryable !== undefined
@@ -1046,18 +1046,18 @@ ${row.error ? `error: ${row.error}${kindClause}
 ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${row.handle}`, body),
-        details: {
-            task_id: row.handle,
-            type: "background_agent",
+        details: buildAgentPollDetails({
+            taskId: row.handle,
             status: row.status,
-            retrieval_status: "success",
-            ...(row.status === "killed" && row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}),
+            retrievalStatus: "success",
             ...(row.seq !== undefined ? { seq: row.seq } : {}),
-            ...(row.resultIsPartial ? { partial_result: true } : {}),
+            ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}),
+            ...(row.error !== undefined ? { error: row.error } : {}),
+            ...(row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
+            ...(row.errorRetryable !== undefined ? { errorRetryable: row.errorRetryable } : {}),
+            ...(row.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
-            ...(row.status === "failed" && row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
-            ...(row.status === "failed" && row.errorRetryable !== undefined ? { retryable: row.errorRetryable } : {}),
-        },
+        }),
         ...(row.status === "failed" ? { isError: true } : {}),
     };
 }
@@ -1083,13 +1083,12 @@ export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot,
         return {
             content: delimitUntrusted(`TaskOutput ${handle.id}`, `status: parked
 The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
-            details: {
-                task_id: handle.id,
-                type: "background_agent",
+            details: buildAgentPollDetails({
+                taskId: handle.id,
                 status: "parked",
-                retrieval_status: "success",
+                retrievalStatus: "success",
                 ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
-            },
+            }),
         };
     }
     const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
@@ -1109,21 +1108,18 @@ ${handle.error ? `error: ${handle.error}${kindClause}
 ${resultText}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
-        details: {
-            task_id: handle.id,
-            type: "background_agent",
+        details: buildAgentPollDetails({
+            taskId: handle.id,
             status: handle.status,
-            retrieval_status: retrieval,
+            retrievalStatus: retrieval,
             ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
-            ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
-            ...(handle.status === "failed" && handle.error !== undefined
-                ? { error: delimitUntrusted("agent error", boundedRedactedSummary(handle.error, 300)) }
-                : {}),
-            ...(handle.status === "failed" && handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
-            ...(handle.status === "failed" && handle.errorRetryable !== undefined ? { retryable: handle.errorRetryable } : {}),
-            ...(handle.resultIsPartial ? { partial_result: true } : {}),
+            ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.error !== undefined ? { error: handle.error } : {}),
+            ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+            ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
+            ...(handle.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
-        },
+        }),
         ...(handle.status === "failed" ? { isError: true } : {}),
     };
 }

package/dist/core/task-registry.d.ts

@@ -138,6 +138,7 @@ export declare class TaskRegistry {
         errorKind?: string;
         stoppedBy?: StopSource;
         seq?: number;
+        cycle?: number;
     }): "completed" | "failed" | "killed" | undefined;
     abortBackgroundAgentsForOwner(access: TaskAccess, opts?: {
         skipSessionScoped?: boolean;

package/dist/core/task-registry.js

@@ -518,7 +518,7 @@ export class TaskRegistry {
             this.markStopSource(handle.id, "system");
             const reapTerminalNote = handle.onReapTerminal;
             handle.abort.abort();
-            this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released", cycle: handle.reviveCycle ?? 0 });
             if (reapTerminalNote !== undefined && handle.terminalNotified !== true) {
                 handle.terminalNotified = true;
                 try {

package/dist/core/types.d.ts

@@ -97,6 +97,7 @@ export interface ToolExecuteContext {
     clientContext?: TaskSpec["clientContext"];
     excludeTools?: readonly string[];
     deferTools?: readonly string[];
+    alwaysLoadTools?: readonly string[];
     promptProfile?: "simple" | "classic";
     additionalDirectories?: readonly string[];
     envFacts?: TaskSpec["envFacts"];
@@ -389,6 +390,10 @@ export interface TaskResult {
         atTurn: number;
     };
     structuredOutput?: unknown;
+    rewindNotes?: Array<{
+        code: "conversation_only" | "files_env_unsupported" | "snapshot_store_unconfigured";
+        message: string;
+    }>;
     stats: {
         turns: number;
         tokens: number;
@@ -465,11 +470,14 @@ export interface TaskEventIdentity {
     sourceTaskId?: string;
     bgAgentId?: string;
 }
-export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open";
+export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open" | "recovered" | "gave_up";
 export interface BrainStatus {
     phase: BrainStatusPhase;
     detail?: string;
     retryInSec?: number;
+    retryInMs?: number;
+    attempt?: number;
+    maxRetries?: number;
 }
 export interface ToolActivity {
     phase: "start" | "end";