codex-toys 0.135.0 → 0.136.0

package/dist/cli/workspace-autonomy.js

@@ -1,10 +1,10 @@
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { parse as parseToml } from "smol-toml";
-import { createTurnAutomationHost, resolveTurnAutomationTarget, runTurnAutomationScript, } from "./turn-automation.js";
+import { createTurnAutomationHost, resolveTurnAutomationTarget, runTurnAutomationScript, startAutomationTurnWithRequest, waitAutomationTurnWithRequest, } from "./turn-automation.js";
 import { parseJsonText } from "./json.js";
 export async function discoverWorkspaceRoot(start = process.cwd()) {
     let current = path.resolve(start);
@@ -120,6 +120,10 @@ export async function collectWorkspaceDoctorInfo(context) {
     }
     const runs = await readRuns(context);
     const latestRun = runs.sort((a, b) => b.startedAt.localeCompare(a.startedAt))[0];
+    const deferredRuns = await listDeferredRunIntents(context);
+    const now = new Date();
+    const latestDeferredRun = deferredRuns
+        .toSorted((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
     const failingCount = countFailingTasks(config?.tasks ?? [], runs);
     return {
         mode: context.mode,
@@ -139,7 +143,12 @@ export async function collectWorkspaceDoctorInfo(context) {
         taskCount: config?.tasks.length ?? 0,
         dueCount: dueTasks(config?.tasks ?? [], runs, new Date()).length,
         failingCount,
+        deferredCount: deferredRuns.length,
+        deferredDueCount: deferredRuns.filter((intent) => isDeferredIntentDue(intent, now)).length,
+        deferredRunningCount: deferredRuns.filter((intent) => intent.status === "running").length,
+        deferredFailedCount: deferredRuns.filter((intent) => intent.status === "failed").length,
         latestRun,
+        latestDeferredRun,
         surfaces: config?.surfaces ?? [],
         errors: workspaceDoctorErrors(context),
     };
@@ -158,6 +167,16 @@ export function formatWorkspaceDoctorInfo(info) {
         ["workspace memories", `${info.workspaceMemoryRoot}${info.workspaceMemorySummaryExists ? " (summary)" : ""}`],
         ["tasks", `${info.taskCount} configured, ${info.dueCount} due, ${info.failingCount} failing`],
         ["latest run", info.latestRun ? `${info.latestRun.status} ${info.latestRun.taskId} ${info.latestRun.finishedAt}` : "none"],
+        [
+            "deferred runs",
+            `${info.deferredCount} total, ${info.deferredDueCount} due, ${info.deferredRunningCount} running, ${info.deferredFailedCount} failed`,
+        ],
+        [
+            "latest deferred",
+            info.latestDeferredRun
+                ? `${info.latestDeferredRun.status} ${info.latestDeferredRun.id} ${info.latestDeferredRun.updatedAt}`
+                : "none",
+        ],
     ];
     for (const error of info.errors) {
         rows.push(["error", error]);
@@ -185,10 +204,19 @@ export async function tickWorkspace(context, options) {
     await ensureStateDirs(context);
     const config = await loadWorkspaceConfig(context);
     const previousRuns = await readRuns(context);
-    const due = dueTasks(config.tasks, previousRuns, new Date());
+    const previousIntents = await listDeferredRunIntents(context);
+    const now = new Date();
+    const due = dueTasks(config.tasks, previousRuns, now, previousIntents);
     const runs = [];
     for (const task of due) {
-        runs.push(await runWorkspaceTask(context, config, task, options));
+        await createScheduledWorkspaceTaskIntent(context, task, now);
+    }
+    const executions = await runDueDeferredRuns(context, options);
+    for (const execution of executions.executions) {
+        const workspaceRun = record(execution.output).workspaceRun;
+        if (isWorkspaceRunRecord(workspaceRun)) {
+            runs.push(workspaceRun);
+        }
     }
     const allRuns = [...previousRuns, ...runs];
     for (const rule of config.reactive.filter((item) => item.enabled)) {
@@ -233,6 +261,168 @@ export async function commitActionsWorkspaceState(context, options = {}) {
         output: commit.stdout || commit.stderr,
     };
 }
+export async function createDeferredRunIntent(context, params) {
+    await ensureDeferredRunDirs(context);
+    const input = parseDeferredRunCreateParams(params);
+    const now = new Date().toISOString();
+    const runAt = input.runAt ?? now;
+    const intent = compactUndefined({
+        id: input.id ?? deferredRunId(now),
+        status: "pending",
+        mode: context.mode,
+        runAt,
+        target: input.target,
+        createdAt: now,
+        updatedAt: now,
+        createdBy: input.createdBy,
+        reason: input.reason,
+        source: input.source,
+        attemptIds: [],
+    });
+    await writeNewJsonFile(deferredIntentPath(context, intent.id), intent);
+    return intent;
+}
+export async function listDeferredRunIntents(context, options = {}) {
+    const dir = deferredIntentDir(context);
+    try {
+        const entries = await readdir(dir);
+        const intents = [];
+        for (const entry of entries) {
+            if (!entry.endsWith(".json")) {
+                continue;
+            }
+            try {
+                const intent = normalizeDeferredRunIntent(parseJsonText(await readFile(path.join(dir, entry), "utf8"), path.join(dir, entry)));
+                if (!options.status || intent.status === options.status) {
+                    intents.push(intent);
+                }
+            }
+            catch { }
+        }
+        const sorted = intents.sort((left, right) => left.runAt.localeCompare(right.runAt) || left.createdAt.localeCompare(right.createdAt));
+        return sorted.slice(0, clampLimit(options.limit, 500));
+    }
+    catch {
+        return [];
+    }
+}
+export async function readDeferredRun(context, intentId) {
+    const intent = await readDeferredRunIntent(context, intentId);
+    const attempts = await readDeferredRunAttempts(context, intent.attemptIds);
+    return { intent, attempts };
+}
+export async function cancelDeferredRunIntent(context, intentId) {
+    const intent = await readDeferredRunIntent(context, intentId);
+    if (intent.status !== "pending") {
+        throw new Error(`Only pending deferred runs can be canceled: ${intentId}`);
+    }
+    const now = new Date().toISOString();
+    const canceled = {
+        ...intent,
+        status: "canceled",
+        updatedAt: now,
+        canceledAt: now,
+    };
+    await writeJsonFileAtomic(deferredIntentPath(context, intentId), canceled);
+    return canceled;
+}
+export async function runDueDeferredRuns(context, options) {
+    await ensureStateDirs(context);
+    await ensureDeferredRunDirs(context);
+    const now = options.now ?? new Date();
+    const due = (await listDeferredRunIntents(context))
+        .filter((intent) => isDeferredIntentDue(intent, now))
+        .slice(0, clampLimit(options.limit, 100));
+    const executions = [];
+    for (const intent of due) {
+        const claim = await claimDeferredRunIntent(context, intent, {
+            now,
+            leaseMs: options.leaseMs ?? 30 * 60 * 1000,
+        });
+        if (!claim) {
+            continue;
+        }
+        try {
+            const outputPath = path.join(deferredOutputDir(context), `${claim.attempt.id}.json`);
+            await writeJsonFileAtomic(deferredAttemptPath(context, claim.attempt.id), claim.attempt);
+            const result = await executeDeferredRunTarget(context, claim.intent, {
+                callToybox: options.callToybox,
+                automationCwd: options.automationCwd,
+            });
+            await writeJsonFileAtomic(outputPath, result.output);
+            const finishedAt = new Date().toISOString();
+            const attempt = compactUndefined({
+                ...claim.attempt,
+                status: result.status,
+                finishedAt,
+                outputPath,
+                error: result.error,
+            });
+            const completedIntent = compactUndefined({
+                ...claim.intent,
+                status: result.status,
+                updatedAt: finishedAt,
+                attemptIds: [...new Set([...claim.intent.attemptIds, attempt.id])],
+                lease: undefined,
+                completedAt: result.status === "completed" ? finishedAt : undefined,
+                error: result.error,
+            });
+            await writeJsonFileAtomic(deferredAttemptPath(context, attempt.id), attempt);
+            await writeJsonFileAtomic(deferredIntentPath(context, completedIntent.id), completedIntent);
+            executions.push({
+                intent: completedIntent,
+                attempt,
+                output: result.output,
+            });
+        }
+        finally {
+            await releaseDeferredRunClaim(context, claim.intent.id);
+        }
+    }
+    return { mode: context.mode, executions };
+}
+export async function pruneDeferredRunHistory(context, options) {
+    if (!Number.isInteger(options.olderThanDays) || options.olderThanDays <= 0) {
+        throw new Error("olderThanDays must be a positive integer");
+    }
+    const now = options.now ?? new Date();
+    const cutoff = new Date(now.getTime() - options.olderThanDays * 24 * 60 * 60 * 1000).toISOString();
+    const intents = await listDeferredRunIntents(context);
+    const pruned = [];
+    for (const intent of intents) {
+        if (!isTerminalDeferredRunStatus(intent.status) || intent.updatedAt >= cutoff) {
+            continue;
+        }
+        const attempts = await readDeferredRunAttempts(context, intent.attemptIds);
+        const outputPaths = attempts.flatMap((attempt) => attempt.outputPath ? [attempt.outputPath] : []);
+        pruned.push({
+            id: intent.id,
+            status: intent.status,
+            updatedAt: intent.updatedAt,
+            attemptIds: attempts.map((attempt) => attempt.id),
+            outputPaths,
+        });
+        if (options.dryRun === true) {
+            continue;
+        }
+        await releaseDeferredRunClaim(context, intent.id);
+        for (const outputPath of outputPaths) {
+            await rm(outputPath, { force: true });
+        }
+        for (const attempt of attempts) {
+            await rm(deferredAttemptPath(context, attempt.id), { force: true });
+        }
+        await rm(deferredIntentPath(context, intent.id), { force: true });
+    }
+    return {
+        mode: context.mode,
+        cutoff,
+        dryRun: options.dryRun === true,
+        inspected: intents.length,
+        pruned: pruned.length,
+        intents: pruned,
+    };
+}
 async function runWorkspaceTask(context, config, task, options) {
     const startedAt = new Date().toISOString();
     const runId = workspaceRunId(task.id, startedAt);
@@ -297,6 +487,89 @@ async function runAutomationTask(context, config, task, runId, startedAt, option
     });
     return scriptRun.result;
 }
+async function executeDeferredRunTarget(context, intent, options) {
+    try {
+        const target = intent.target;
+        if (target.kind === "workspace-task") {
+            const config = await loadWorkspaceConfig(context);
+            const task = config.tasks.find((item) => item.id === target.taskId);
+            if (!task) {
+                throw new Error(`Unknown workspace task: ${target.taskId}`);
+            }
+            const workspaceRun = await runWorkspaceTask(context, config, task, options);
+            return {
+                status: workspaceRun.status === "failed" ? "failed" : "completed",
+                output: { workspaceRun },
+                error: workspaceRun.error,
+            };
+        }
+        if (target.kind === "automation") {
+            const config = await loadWorkspaceConfig(context).catch(() => ({
+                name: path.basename(context.repoRoot),
+                surfaces: [],
+                tasks: [],
+                reactive: [],
+                path: context.configPath,
+            }));
+            const result = await runAutomationDeferredTarget(context, config, { ...intent, target }, options);
+            return { status: "completed", output: result };
+        }
+        if (target.kind === "turn") {
+            const started = await startAutomationTurnWithRequest("workspace", target, async (method, params) => await options.callToybox("app.call", {
+                method,
+                params,
+            }));
+            const snapshot = await waitAutomationTurnWithRequest("workspace", async (method, params) => await options.callToybox("app.call", {
+                method,
+                params,
+            }), started);
+            return { status: "completed", output: { turn: snapshot } };
+        }
+        return exhaustiveTarget(target);
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            output: { error: errorMessage(error) },
+            error: errorMessage(error),
+        };
+    }
+}
+async function runAutomationDeferredTarget(context, config, intent, options) {
+    const target = await resolveTurnAutomationTarget(intent.target.automation, {
+        cwd: context.repoRoot,
+    });
+    const startedAt = new Date().toISOString();
+    const event = deferredAutomationEvent(config, intent, startedAt);
+    const prompt = intent.target.prompt ?? target.prompt;
+    const cwd = intent.target.cwd ?? options.automationCwd ?? target.cwd ?? context.repoRoot;
+    const scriptRun = await runTurnAutomationScript({
+        scriptPath: target.scriptPath,
+        automation: target.automation,
+        event,
+        prompt,
+        cwd,
+        timeoutMs: 90_000,
+        host: createTurnAutomationHost({
+            via: "workspace",
+            appRequest: async (method, params) => await options.callToybox("app.call", {
+                method,
+                params,
+            }),
+            workspaceRequest: options.callToybox,
+            defaults: {
+                prompt,
+                cwd,
+                skills: target.skills,
+                model: intent.target.model,
+                sandbox: intent.target.sandbox,
+                approvalPolicy: intent.target.approvalPolicy,
+                permissions: intent.target.permissions,
+            },
+        }),
+    });
+    return scriptRun.result;
+}
 function workspaceAutomationEvent(config, task, runId, startedAt) {
     const event = task.event ?? {};
     const payload = isRecord(event.payload) ? event.payload : {};
@@ -313,6 +586,25 @@ function workspaceAutomationEvent(config, task, runId, startedAt) {
         },
     };
 }
+function deferredAutomationEvent(config, intent, startedAt) {
+    const event = intent.target.event ?? {};
+    const payload = isRecord(event.payload) ? event.payload : {};
+    return {
+        ...event,
+        id: stringValue(event.id, `deferred:${config.name}:${intent.id}`),
+        type: stringValue(event.type, intent.target.automation),
+        source: stringValue(event.source, config.name),
+        occurredAt: stringValue(event.occurredAt, intent.runAt),
+        receivedAt: stringValue(event.receivedAt, startedAt),
+        payload: {
+            deferredRunId: intent.id,
+            ...payload,
+        },
+    };
+}
+function exhaustiveTarget(value) {
+    throw new Error(`Unsupported deferred run target: ${JSON.stringify(value)}`);
+}
 async function runReactiveRule(context, rule) {
     const startedAt = new Date().toISOString();
     const runId = `${startedAt.replace(/[:.]/g, "-")}-${rule.id}`;
@@ -454,7 +746,227 @@ async function readRuns(context) {
         return [];
     }
 }
-function dueTasks(tasks, runs, now) {
+async function createScheduledWorkspaceTaskIntent(context, task, now) {
+    try {
+        return await createDeferredRunIntent(context, {
+            id: scheduledDeferredRunId(task.id, now),
+            runAt: now.toISOString(),
+            target: {
+                kind: "workspace-task",
+                taskId: task.id,
+            },
+            createdBy: "workspace-schedule",
+            reason: `Scheduled workspace task ${task.id}`,
+            source: {
+                kind: "workspace-task-schedule",
+                taskId: task.id,
+                schedule: task.schedule,
+                date: now.toISOString().slice(0, 10),
+            },
+        });
+    }
+    catch (error) {
+        if (isAlreadyExistsError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function readDeferredRunIntent(context, intentId) {
+    const intentPath = deferredIntentPath(context, intentId);
+    try {
+        return normalizeDeferredRunIntent(parseJsonText(await readFile(intentPath, "utf8"), intentPath));
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            throw new Error(`Unknown deferred run: ${intentId}`);
+        }
+        throw error;
+    }
+}
+async function readDeferredRunAttempts(context, attemptIds) {
+    const attempts = [];
+    for (const attemptId of attemptIds) {
+        const attemptPath = deferredAttemptPath(context, attemptId);
+        try {
+            attempts.push(normalizeDeferredRunAttempt(parseJsonText(await readFile(attemptPath, "utf8"), attemptPath)));
+        }
+        catch { }
+    }
+    return attempts.sort((left, right) => left.startedAt.localeCompare(right.startedAt));
+}
+async function claimDeferredRunIntent(context, intent, options) {
+    const current = await readDeferredRunIntent(context, intent.id);
+    if (!isDeferredIntentDue(current, options.now)) {
+        return undefined;
+    }
+    const claimPath = deferredClaimPath(context, current.id);
+    const claimedAt = options.now.toISOString();
+    const attemptId = deferredAttemptId(current.id, claimedAt);
+    const leaseExpiresAt = new Date(options.now.getTime() + options.leaseMs).toISOString();
+    const executorId = `${process.pid}:${randomUUID()}`;
+    const claim = { intentId: current.id, attemptId, claimedAt, leaseExpiresAt, executorId };
+    try {
+        await writeNewJsonFile(claimPath, claim);
+    }
+    catch (error) {
+        if (!isAlreadyExistsError(error)) {
+            throw error;
+        }
+        const existing = await readClaimFile(claimPath);
+        if (!existing || existing.leaseExpiresAt > options.now.toISOString()) {
+            return undefined;
+        }
+        await rm(claimPath, { force: true });
+        try {
+            await writeNewJsonFile(claimPath, claim);
+        }
+        catch (retryError) {
+            if (isAlreadyExistsError(retryError)) {
+                return undefined;
+            }
+            throw retryError;
+        }
+    }
+    const attempt = {
+        id: attemptId,
+        intentId: current.id,
+        status: "running",
+        mode: context.mode,
+        startedAt: claimedAt,
+        executorId,
+        leaseExpiresAt,
+    };
+    const running = {
+        ...current,
+        status: "running",
+        updatedAt: claimedAt,
+        lease: {
+            attemptId,
+            claimedAt,
+            expiresAt: leaseExpiresAt,
+            executorId,
+        },
+    };
+    await writeJsonFileAtomic(deferredIntentPath(context, current.id), running);
+    return { intent: running, attempt };
+}
+async function releaseDeferredRunClaim(context, intentId) {
+    await rm(deferredClaimPath(context, intentId), { force: true });
+}
+async function readClaimFile(file) {
+    try {
+        const parsed = parseJsonText(await readFile(file, "utf8"), file);
+        return isRecord(parsed) && typeof parsed.leaseExpiresAt === "string"
+            ? { leaseExpiresAt: parsed.leaseExpiresAt }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseDeferredRunCreateParams(value) {
+    const input = record(value);
+    const runAt = optionalString(input.runAt);
+    if (runAt && Number.isNaN(Date.parse(runAt))) {
+        throw new Error(`Deferred run runAt must be an ISO-compatible date: ${runAt}`);
+    }
+    const target = parseDeferredRunTarget(input.target);
+    const source = recordOrUndefined(input.source);
+    return compactUndefined({
+        id: optionalString(input.id),
+        runAt,
+        target,
+        createdBy: optionalString(input.createdBy),
+        reason: optionalString(input.reason),
+        source,
+    });
+}
+function parseDeferredRunTarget(value) {
+    const target = record(value);
+    const kind = requiredString(target.kind, "deferred run target kind");
+    if (kind === "workspace-task") {
+        return {
+            kind,
+            taskId: requiredString(target.taskId, "deferred run workspace-task taskId"),
+        };
+    }
+    if (kind === "automation") {
+        return compactUndefined({
+            kind,
+            automation: requiredString(target.automation, "deferred run automation target automation"),
+            event: recordOrUndefined(target.event),
+            prompt: optionalString(target.prompt),
+            cwd: optionalString(target.cwd),
+            model: optionalString(target.model),
+            sandbox: sandboxValue(target.sandbox, "deferred run automation target sandbox"),
+            approvalPolicy: approvalPolicyValue(target.approvalPolicy, "deferred run automation target approvalPolicy"),
+            permissions: optionalString(target.permissions),
+        });
+    }
+    if (kind === "turn") {
+        const prompt = requiredString(target.prompt, "deferred run turn target prompt");
+        return compactUndefined({
+            kind,
+            prompt,
+            threadId: optionalString(target.threadId),
+            cwd: optionalString(target.cwd),
+            model: optionalString(target.model),
+            serviceTier: optionalString(target.serviceTier),
+            sandbox: sandboxValue(target.sandbox, "deferred run turn target sandbox"),
+            approvalPolicy: approvalPolicyValue(target.approvalPolicy, "deferred run turn target approvalPolicy"),
+            permissions: optionalString(target.permissions),
+            responsesapiClientMetadata: stringRecord(target.responsesapiClientMetadata),
+            outputSchema: target.outputSchema,
+        });
+    }
+    throw new Error(`Invalid deferred run target kind: ${kind}`);
+}
+function normalizeDeferredRunIntent(value) {
+    const input = record(value);
+    return {
+        id: requiredString(input.id, "deferred run id"),
+        status: deferredRunStatus(input.status),
+        mode: workspaceMode(input.mode),
+        runAt: requiredString(input.runAt, "deferred run runAt"),
+        target: parseDeferredRunTarget(input.target),
+        createdAt: requiredString(input.createdAt, "deferred run createdAt"),
+        updatedAt: requiredString(input.updatedAt, "deferred run updatedAt"),
+        createdBy: optionalString(input.createdBy),
+        reason: optionalString(input.reason),
+        source: recordOrUndefined(input.source),
+        attemptIds: Array.isArray(input.attemptIds)
+            ? input.attemptIds.filter((entry) => typeof entry === "string")
+            : [],
+        lease: isRecord(input.lease)
+            ? {
+                attemptId: requiredString(input.lease.attemptId, "deferred run lease attemptId"),
+                claimedAt: requiredString(input.lease.claimedAt, "deferred run lease claimedAt"),
+                expiresAt: requiredString(input.lease.expiresAt, "deferred run lease expiresAt"),
+                executorId: requiredString(input.lease.executorId, "deferred run lease executorId"),
+            }
+            : undefined,
+        completedAt: optionalString(input.completedAt),
+        canceledAt: optionalString(input.canceledAt),
+        error: optionalString(input.error),
+    };
+}
+function normalizeDeferredRunAttempt(value) {
+    const input = record(value);
+    return {
+        id: requiredString(input.id, "deferred run attempt id"),
+        intentId: requiredString(input.intentId, "deferred run attempt intentId"),
+        status: deferredAttemptStatus(input.status),
+        mode: workspaceMode(input.mode),
+        startedAt: requiredString(input.startedAt, "deferred run attempt startedAt"),
+        finishedAt: optionalString(input.finishedAt),
+        executorId: requiredString(input.executorId, "deferred run attempt executorId"),
+        leaseExpiresAt: requiredString(input.leaseExpiresAt, "deferred run attempt leaseExpiresAt"),
+        outputPath: optionalString(input.outputPath),
+        error: optionalString(input.error),
+    };
+}
+function dueTasks(tasks, runs, now, intents = []) {
     return tasks.filter((task) => {
         if (!task.enabled) {
             return false;
@@ -462,7 +974,9 @@ function dueTasks(tasks, runs, now) {
         if (!task.schedule) {
             return false;
         }
-        return isScheduleDue(task.schedule, now) && !hasRunForDate(task.id, runs, now);
+        return isScheduleDue(task.schedule, now) &&
+            !hasRunForDate(task.id, runs, now) &&
+            !hasScheduledIntentForDate(task.id, intents, now);
     });
 }
 function isScheduleDue(schedule, now) {
@@ -487,6 +1001,32 @@ function hasRunForDate(taskId, runs, now) {
     const today = now.toISOString().slice(0, 10);
     return runs.some((run) => run.taskId === taskId && run.startedAt.startsWith(today));
 }
+function hasScheduledIntentForDate(taskId, intents, now) {
+    const expected = scheduledDeferredRunId(taskId, now);
+    return intents.some((intent) => intent.id === expected ||
+        (intent.target.kind === "workspace-task" &&
+            intent.target.taskId === taskId &&
+            intent.source?.kind === "workspace-task-schedule" &&
+            intent.source.date === now.toISOString().slice(0, 10)));
+}
+function isDeferredIntentDue(intent, now) {
+    if (intent.status === "pending") {
+        return intent.runAt <= now.toISOString();
+    }
+    if (intent.status === "running" && intent.lease?.expiresAt) {
+        return intent.lease.expiresAt <= now.toISOString();
+    }
+    return false;
+}
+function isTerminalDeferredRunStatus(status) {
+    return status === "completed" || status === "failed" || status === "canceled";
+}
+function isWorkspaceRunRecord(value) {
+    const input = record(value);
+    return typeof input.id === "string" &&
+        typeof input.taskId === "string" &&
+        (input.status === "completed" || input.status === "failed" || input.status === "skipped");
+}
 function countFailingTasks(tasks, runs) {
     return tasks.filter((task) => consecutiveFailures(task.id, runs) > 0).length;
 }
@@ -527,6 +1067,69 @@ async function ensureStateDirs(context) {
         await mkdir(path.join(context.stateRoot, name), { recursive: true });
     }
 }
+async function ensureDeferredRunDirs(context) {
+    for (const dir of [
+        deferredIntentDir(context),
+        deferredAttemptDir(context),
+        deferredOutputDir(context),
+        deferredClaimDir(context),
+    ]) {
+        await mkdir(dir, { recursive: true });
+    }
+}
+function deferredRoot(context) {
+    return path.join(context.stateRoot, "deferred");
+}
+function deferredIntentDir(context) {
+    return path.join(deferredRoot(context), "intents");
+}
+function deferredAttemptDir(context) {
+    return path.join(deferredRoot(context), "attempts");
+}
+function deferredOutputDir(context) {
+    return path.join(deferredRoot(context), "outputs");
+}
+function deferredClaimDir(context) {
+    return path.join(deferredRoot(context), "claims");
+}
+function deferredIntentPath(context, intentId) {
+    return path.join(deferredIntentDir(context), `${safeFileSegment(intentId)}.json`);
+}
+function deferredAttemptPath(context, attemptId) {
+    return path.join(deferredAttemptDir(context), `${safeFileSegment(attemptId)}.json`);
+}
+function deferredClaimPath(context, intentId) {
+    return path.join(deferredClaimDir(context), `${safeFileSegment(intentId)}.json`);
+}
+function deferredRunId(createdAt) {
+    return `deferred-${createdAt.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+}
+function deferredAttemptId(intentId, startedAt) {
+    return `${startedAt.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}-${safeFileSegment(intentId).slice(0, 48)}`;
+}
+function scheduledDeferredRunId(taskId, now) {
+    return `scheduled-${safeFileSegment(taskId)}-${now.toISOString().slice(0, 10)}`;
+}
+function safeFileSegment(value) {
+    const safe = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return safe.slice(0, 120) || "deferred-run";
+}
+async function writeNewJsonFile(file, value) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const handle = await open(file, "wx");
+    try {
+        await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeJsonFileAtomic(file, value) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmpPath = `${file}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+    await writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`);
+    await rename(tmpPath, file);
+}
 async function writeScaffoldFile(workspaceRoot, relativePath, content, overwrite) {
     const file = path.join(workspaceRoot, relativePath);
     const normalizedContent = content.endsWith("\n") ? content : `${content}\n`;
@@ -720,6 +1323,9 @@ function requiredString(value, label) {
 function optionalString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function recordOrUndefined(value) {
+    return isRecord(value) ? value : undefined;
+}
 function record(value) {
     return isRecord(value) ? value : {};
 }
@@ -741,6 +1347,58 @@ function booleanValue(value, label) {
     }
     return value;
 }
+function stringRecord(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function sandboxValue(value, label) {
+    if (value === "danger-full-access" ||
+        value === "read-only" ||
+        value === "workspace-write") {
+        return value;
+    }
+    if (value !== undefined) {
+        throw new Error(`${label} must be danger-full-access, workspace-write, or read-only`);
+    }
+    return undefined;
+}
+function approvalPolicyValue(value, label) {
+    if (value === "never" ||
+        value === "on-failure" ||
+        value === "on-request" ||
+        value === "untrusted") {
+        return value;
+    }
+    if (value !== undefined) {
+        throw new Error(`${label} must be never, on-failure, on-request, or untrusted`);
+    }
+    return undefined;
+}
+function deferredRunStatus(value) {
+    if (value === "pending" ||
+        value === "running" ||
+        value === "completed" ||
+        value === "failed" ||
+        value === "canceled") {
+        return value;
+    }
+    throw new Error(`Invalid deferred run status: ${String(value)}`);
+}
+function deferredAttemptStatus(value) {
+    if (value === "running" || value === "completed" || value === "failed") {
+        return value;
+    }
+    throw new Error(`Invalid deferred run attempt status: ${String(value)}`);
+}
+function workspaceMode(value) {
+    if (value === "local" || value === "actions") {
+        return value;
+    }
+    throw new Error(`Invalid workspace mode: ${String(value)}`);
+}
 function positiveInteger(value, label) {
     if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
         throw new Error(`${label} must be a positive integer`);
@@ -750,6 +1408,18 @@ function positiveInteger(value, label) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function clampLimit(value, fallback) {
+    if (value === undefined || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(1, Math.min(1_000, Math.trunc(value)));
+}
+function isNotFoundError(error) {
+    return isRecord(error) && error.code === "ENOENT";
+}
+function isAlreadyExistsError(error) {
+    return isRecord(error) && error.code === "EEXIST";
+}
 async function exists(file) {
     try {
         await stat(file);