@kylecheng3146/agent-ops 0.10.0 → 0.10.2

package/dist/runtime/src/run/integration.js

@@ -4,6 +4,7 @@ import { canonicalJson } from "../config/hash.js";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { parseWorktreeListPorcelain, readWorktreeRecord } from "../parallel/service.js";
 import { FileRunRepository } from "./service.js";
 function ledger(commonDir) { return new FileRunRepository(join(commonDir, "agent-ops", "runs"), commonDir); }
 function proofPath(commonDir, runId) { return join(commonDir, "agent-ops", "runs", runId, "integration-proof.json"); }
@@ -84,6 +85,11 @@ export async function readRunIntegrationProof(commonDir, record) {
         return null;
     if (state.ownerSessionId !== record.sessionId || state.coordinatorId !== record.workerId)
         throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "Recovery coordinator does not match the sealed transaction.");
+    const coordinator = state.workers.find(w => w.workerId === state.coordinatorId);
+    if (record.mainRoot !== state.root || record.ownerSessionId !== state.ownerSessionId ||
+        (state.workers.length > 0 && (coordinator === undefined || coordinator.worktree !== record.path ||
+            coordinator.generation !== record.workerGeneration || coordinator.ownerSessionId !== record.ownerSessionId)))
+        throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "Recovery requires the current coordinator worktree owner and generation.");
     return await readSealedProof(commonDir, record.runId, state.integration);
 }
 /** A failed pre-merge CAS may be retried only after archiving the unused sealed transaction. */
@@ -133,17 +139,15 @@ export async function markRunIntegration(commonDir, record, status, step, receip
     await ledger(commonDir).mutate(record.runId, current => {
         if (current.integration === null || current.ownerSessionId !== record.sessionId || current.coordinatorId !== record.workerId)
             throw new AgentOpsError("RUN_INTEGRATION_OWNERSHIP", "The integration transaction is missing or belongs to another coordinator.");
+        if (current.status !== "active" || current.disableRestart || current.awaitingResume)
+            throw new AgentOpsError("RUN_RESUME_DISABLED", "A paused, stopped or disabled run cannot advance integration steps.");
         return { ...current, integration: { ...current.integration, status, updatedAt: new Date().toISOString(),
                 completedSteps: [...new Set([...current.integration.completedSteps, step])],
                 ...(receipt === undefined ? {} : { receiptPath: receipt.path, receiptDigest: receipt.digest }) } };
     });
 }
-/**
- * Finish bookkeeping after a coordinator checkout vanished. This only verifies
- * sealed artifacts and advances the ledger; it never recreates a checkout or
- * starts a native writer.
- */
-export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
+/** Validate the sealed transaction before any remaining cleanup or final bookkeeping. */
+export async function validateRunIntegrationCleanup(commonDir, runId, git, allowMissingNote = false) {
     const repository = ledger(commonDir);
     const state = await repository.read(runId);
     if (state === null || state.integration === null)
@@ -154,7 +158,7 @@ export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
     await readSealedProof(commonDir, runId, integration);
     if (integration.status !== "cleaned" &&
         (integration.status !== "receipt-written" || !integration.completedSteps.includes("receipt") ||
-            !integration.completedSteps.includes("note"))) {
+            !integration.completedSteps.includes("target") || !integration.completedSteps.includes("tasks"))) {
         throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recovery requires a recorded receipt and Git note before cleanup can be completed.");
     }
     if (integration.receiptPath === null || integration.receiptDigest === null)
@@ -177,9 +181,10 @@ export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
     validateRunIntegrationReceipt(integration, receipt);
     const note = await git(state.root, ["notes", "--ref=agent-ops", "show", integration.candidate]);
     const noteText = note.stdout;
-    if (note.exitCode !== 0 || !noteText.includes(`session: ${state.ownerSessionId}`) ||
-        !noteText.includes(`receipt: ${integration.receiptPath}`) ||
-        !noteText.includes(`receipt-sha256: ${integration.receiptDigest}`)) {
+    const noteBound = note.exitCode === 0 && noteText.split("\n").includes(`session: ${state.ownerSessionId}`) &&
+        noteText.split("\n").includes(`receipt: ${integration.receiptPath}`) &&
+        noteText.split("\n").includes(`receipt-sha256: ${integration.receiptDigest}`);
+    if (!noteBound && !(allowMissingNote && !integration.completedSteps.includes("note") && note.exitCode === 1)) {
         throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "The sealed receipt is not bound by the Git note for the candidate.");
     }
     const target = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
@@ -189,10 +194,27 @@ export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
         (await git(state.root, ["merge-base", "--is-ancestor", integration.candidate, target.stdout.trim()])).exitCode === 0;
     if (!exact && !historic)
         throw new AgentOpsError("RUN_INTEGRATION_TARGET_CHANGED", "The target is inconsistent with the sealed, receipt-bound integration history.");
-    await repository.mutate(runId, current => {
-        if (current.integration === null || current.integration.transactionId !== integration.transactionId ||
-            current.integration.candidate !== integration.candidate || current.integration.expectedTarget !== integration.expectedTarget)
+    return { state, integration, receipt: receipt, noteBound, observedTarget: target.stdout.trim() };
+}
+/** After owned checkouts vanish, advance bookkeeping without executing product proof or native writers. */
+export async function recoverRunIntegrationAfterCleanup(commonDir, runId, git) {
+    const { state, integration, observedTarget } = await validateRunIntegrationCleanup(commonDir, runId, git);
+    const listing = await git(state.root, ["worktree", "list", "--porcelain"]);
+    if (listing.exitCode !== 0)
+        throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Cannot confirm that integration checkouts were cleaned.");
+    for (const checkout of parseWorktreeListPorcelain(listing.stdout)) {
+        const record = await readWorktreeRecord(checkout.path);
+        if (record?.runId === runId || state.workers.some(worker => worker.worktree === checkout.path))
+            throw new AgentOpsError("RUN_INTEGRATION_CLEANUP_PENDING", "An owned integration checkout still exists; finish its missing cleanup steps before marking the run cleaned.");
+    }
+    const repository = ledger(commonDir);
+    await repository.mutate(runId, async (current) => {
+        const target = await git(state.root, ["rev-parse", state.targetBranch + "^{commit}"]);
+        if (current.revision !== state.revision || canonicalJson(current.integration) !== canonicalJson(integration) ||
+            target.exitCode !== 0 || target.stdout.trim() !== observedTarget)
             throw new AgentOpsError("RUN_INTEGRATION_STALE", "The integration changed during recovery.");
+        if (current.integration === null)
+            throw new AgentOpsError("RUN_INTEGRATION_REQUIRED", "The integration disappeared during recovery.");
         if (current.integration.status === "cleaned")
             return current;
         if (current.integration.status !== "receipt-written")

package/dist/runtime/src/run/policy.js

@@ -9,7 +9,9 @@ import { evaluateGuardrail } from "../guardrails/evaluate.js";
 import { validateConfig } from "../schema/validate.js";
 import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
 import { redactSecrets } from "../security/redact.js";
-import { activeWallTimeMs } from "./scheduler.js";
+import { remainingRunTimeMs } from "./scheduler.js";
+import { MAX_EVENTS } from "./service.js";
+export const RUN_POLICY_TTL_MS = 60 * 60 * 1000;
 function fail(code, message) { throw new AgentOpsError(code, message); }
 const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function validApprovals(value) {
@@ -62,13 +64,14 @@ export async function runPolicyAssessment(state, policy, capabilityId) {
         const assessment = current.approvals.find(a => a.capabilityId === capabilityId);
         if (assessment !== undefined && canonicalJson(capabilities(current.config).get(capabilityId) ?? null) === canonicalJson(definition))
             return assessment;
-        if (current.previousDigest === null)
+        const digest = current.assessmentDigest ?? current.previousDigest;
+        if (digest === null)
             break;
-        const source = await readPrivateFile(join(state.commonDir, "agent-ops/runs", state.runId, "policies", current.previousDigest + ".json"), state.commonDir);
-        if (source === null || sha256(source) !== current.previousDigest)
+        const source = await readPrivateFile(join(state.commonDir, "agent-ops/runs", state.runId, "policies", digest + ".json"), state.commonDir);
+        if (source === null || sha256(source) !== digest)
             fail("RUN_POLICY_CHANGED", "Historical capability assessment is missing or changed.");
         const previous = JSON.parse(source);
-        current = (await readRunPolicy({ ...state, policyBinding: { artifactDigest: current.previousDigest, configHash: calculateConfigHash(previous.config),
+        current = (await readRunPolicy({ ...state, policyBinding: { artifactDigest: digest, configHash: calculateConfigHash(previous.config),
                 runtimeHash: previous.runtimeHash, expiresAt: previous.expiresAt } }, previous.runtimeHash, Date.now(), true));
     }
     return fail("RUN_POLICY_APPROVAL_REQUIRED", "The current capability lacks a matching historical run assessment.");
@@ -107,6 +110,8 @@ export function validateRunPolicyChange(previous, candidate, approvals) {
     return config;
 }
 export async function readRunPolicy(state, runtimeHash, now = Date.now(), allowExpired = false) {
+    if (!Number.isSafeInteger(now) || now < 0 || now > 8.64e15 - RUN_POLICY_TTL_MS)
+        fail("RUN_CLOCK_INVALID", "Policy clock must be a valid nonnegative timestamp with room for a finite grant.");
     const binding = state.policyBinding;
     if (binding === undefined)
         return null;
@@ -121,11 +126,19 @@ export async function readRunPolicy(state, runtimeHash, now = Date.now(), allowE
     catch {
         return fail("RUN_POLICY_INVALID", "Run policy JSON is invalid.");
     }
-    if (!plain(parsed) || Object.keys(parsed).some(key => !["schemaVersion", "runId", "config", "baseConfig", "baseTrustBinding", "runtimeHash", "expiresAt", "approvals", "previousDigest"].includes(key)) ||
+    if (!plain(parsed) || Object.keys(parsed).some(key => !["schemaVersion", "runId", "config", "baseConfig", "baseTrustBinding", "runtimeHash", "expiresAt", "issuedAt", "approvals", "previousDigest", "assessmentDigest"].includes(key)) ||
         !validBaseBinding(parsed.baseTrustBinding, state.root) || !validApprovals(parsed.approvals) ||
-        !(parsed.previousDigest === null || (typeof parsed.previousDigest === "string" && /^[a-f0-9]{64}$/u.test(parsed.previousDigest))))
+        !(parsed.previousDigest === null || (typeof parsed.previousDigest === "string" && /^[a-f0-9]{64}$/u.test(parsed.previousDigest))) ||
+        (parsed.assessmentDigest !== undefined && (typeof parsed.assessmentDigest !== "string" || !/^[a-f0-9]{64}$/u.test(parsed.assessmentDigest))))
         fail("RUN_POLICY_INVALID", "Run policy artifact has an invalid structure or trust origin.");
     const artifact = parsed;
+    const expires = Date.parse(artifact.expiresAt), issued = Date.parse(artifact.issuedAt ?? state.createdAt);
+    if (typeof artifact.expiresAt !== "string" || (artifact.issuedAt !== undefined && typeof artifact.issuedAt !== "string") ||
+        !Number.isFinite(expires) || !Number.isFinite(issued) || expires <= issued ||
+        (artifact.issuedAt !== undefined && expires - issued > RUN_POLICY_TTL_MS))
+        fail("RUN_POLICY_INVALID", "Policy requires a valid finite authorization window.");
+    if (now < issued)
+        fail("RUN_CLOCK_INVALID", "Policy clock moved behind its issuance; manual reconciliation is required.");
     if (artifact.schemaVersion !== 1 || artifact.runId !== state.runId || !validateConfig(artifact.config).ok ||
         !validateConfig(artifact.baseConfig).ok || calculateConfigHash(artifact.config) !== binding.configHash ||
         artifact.runtimeHash !== binding.runtimeHash || artifact.expiresAt !== binding.expiresAt ||
@@ -143,7 +156,7 @@ export async function bindRunPolicy(repository, runId, input) {
     if (state === null)
         return fail("RUN_NOT_FOUND", "Run does not exist.");
     const now = input.now ?? Date.now();
-    if (!Number.isFinite(now) || !validBaseBinding(input.baseTrustBinding, state.root))
+    if (!Number.isSafeInteger(now) || now < 0 || !validBaseBinding(input.baseTrustBinding, state.root))
         fail("RUN_POLICY_INVALID", "Policy requires the original canonical repository trust binding and a valid clock.");
     const previous = await readRunPolicy(state, input.resumeRuntime === true ? state.policyBinding?.runtimeHash ?? input.runtimeHash : input.runtimeHash, now, true);
     if ((state.policyBinding?.artifactDigest ?? undefined) !== input.expectedDigest)
@@ -159,12 +172,13 @@ export async function bindRunPolicy(repository, runId, input) {
     if (!validateConfig(config).ok || !/^[a-f0-9]{64}$/u.test(input.runtimeHash) ||
         (previous === null && input.baseTrustBinding.configHash !== calculateConfigHash(config)))
         fail("RUN_POLICY_INVALID", "Run policy or runtime identity is invalid.");
-    const remaining = state.budget.limitMs - activeWallTimeMs(state.budget.activeIntervals, now);
+    const remaining = remainingRunTimeMs(state, now);
     if (remaining <= 0)
         fail("RUN_BUDGET_EXHAUSTED", "No active execution budget remains.");
     const artifact = { schemaVersion: 1, runId, config, baseConfig: previous?.baseConfig ?? config,
         baseTrustBinding: previous?.baseTrustBinding ?? input.baseTrustBinding, runtimeHash: input.runtimeHash,
-        expiresAt: new Date(now + remaining).toISOString(), approvals: (input.approvals ?? []).map(a => ({ ...a, reason: redactSecrets(a.reason) })), previousDigest: previous === null ? null : state.policyBinding.artifactDigest };
+        issuedAt: new Date(now).toISOString(), expiresAt: new Date(now + Math.min(remaining, RUN_POLICY_TTL_MS)).toISOString(),
+        approvals: (input.approvals ?? []).map(a => ({ ...a, reason: redactSecrets(a.reason) })), previousDigest: previous === null ? null : state.policyBinding.artifactDigest };
     const content = canonicalJson(artifact), digest = sha256(content);
     await writePrivateFile(join(state.commonDir, "agent-ops", "runs", runId, "policies", digest + ".json"), content, state.commonDir);
     return await repository.mutate(runId, current => {
@@ -174,3 +188,44 @@ export async function bindRunPolicy(repository, runId, input) {
                 artifactDigest: digest, expiresAt: artifact.expiresAt } };
     });
 }
+/** Renew the same finite grant without changing native identities, scope or trust. Reads never renew. */
+export async function renewRunPolicy(repository, runId, input) {
+    const state = await repository.read(runId);
+    if (state === null)
+        return fail("RUN_NOT_FOUND", "Run does not exist.");
+    if (state.status !== "active" || state.disableRestart || state.awaitingResume || state.events.some(e => e.code === "RUN_COMMAND_DENIED"))
+        return fail("RUN_POLICY_DISABLED", "Renewal cannot awaken a stopped run or erase a denial.");
+    const now = input.now ?? Date.now();
+    if (now < Date.parse(state.budget.lastObservedAt))
+        return fail("RUN_CLOCK_INVALID", "Policy clock moved behind the last observed accounting time.");
+    const authority = await input.authority();
+    const previous = await readRunPolicy(state, authority.runtimeHash, now, true);
+    if (previous === null)
+        return fail("RUN_POLICY_INVALID", "Renewal requires an existing bound authorization.");
+    const assertAuthority = (current) => {
+        if (!current.trusted || current.runtimeHash !== previous.runtimeHash ||
+            canonicalJson(current.baseTrustBinding) !== canonicalJson(previous.baseTrustBinding) ||
+            calculateConfigHash(current.config) !== calculateConfigHash(previous.baseConfig))
+            fail("RUN_POLICY_AUTHORITY_CHANGED", "Original trust, repository configuration or executable runtime changed; obtain genuine authorization before resume.");
+    };
+    assertAuthority(authority);
+    if (Date.parse(previous.expiresAt) > now)
+        return state;
+    if (remainingRunTimeMs(state, now) <= 0)
+        return fail("RUN_BUDGET_EXHAUSTED", "Legacy finite runs require manual resume before renewal.");
+    const artifact = { ...previous, issuedAt: new Date(now).toISOString(),
+        expiresAt: new Date(now + Math.min(RUN_POLICY_TTL_MS, remainingRunTimeMs(state, now))).toISOString(),
+        assessmentDigest: previous.assessmentDigest ?? state.policyBinding.artifactDigest,
+        previousDigest: state.policyBinding.artifactDigest };
+    const content = canonicalJson(artifact), digest = sha256(content);
+    await writePrivateFile(join(state.commonDir, "agent-ops", "runs", runId, "policies", digest + ".json"), content, state.commonDir);
+    assertAuthority(await input.authority());
+    return await repository.mutate(runId, current => {
+        if (current.revision !== state.revision || current.status !== "active" || current.disableRestart || current.awaitingResume ||
+            current.policyBinding?.artifactDigest !== state.policyBinding.artifactDigest || current.events.some(e => e.code === "RUN_COMMAND_DENIED"))
+            return fail("RUN_POLICY_STALE", "Run stop, denial or scope changed during renewal.");
+        return { ...current, policyBinding: { ...state.policyBinding, artifactDigest: digest, expiresAt: artifact.expiresAt },
+            events: [...current.events, { id: `renewal-${digest.slice(0, 32)}`, at: artifact.issuedAt, type: "diagnostic",
+                    code: "RUN_POLICY_RENEWED", workerId: null, taskId: null, detail: `Same-authority finite grant renewed from ${state.policyBinding.artifactDigest}.` }].slice(-MAX_EVENTS) };
+    });
+}

package/dist/runtime/src/run/scheduler.js

@@ -63,16 +63,17 @@ export function planSchedule(state) {
     const running = state.tasks.filter((task) => task.status === "running" || task.status === "awaiting-delivery");
     const blocked = state.tasks.filter((task) => task.status === "blocked");
     const ready = state.tasks.filter((task) => ["planned", "ready"].includes(task.status) && dependencyState(state.tasks, task) === "ready");
+    const slotConsumers = state.workers.filter(worker => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status));
     return {
-        ready,
+        ready: ready.filter(task => task.taskId !== state.rootTaskId),
         running,
         blocked,
-        availableSlots: Math.max(0, Math.min(state.jobs, MAX_ACTIVE_WORKERS) - running.length)
+        availableSlots: Math.max(0, Math.min(state.jobs, MAX_ACTIVE_WORKERS) - slotConsumers.length)
     };
 }
 /**
  * Compute whole-run active wall time as the union of intervals. This prevents
- * two parallel writers from doubling the 60-minute run budget.
+ * two parallel writers from doubling measured consumption.
  */
 export function activeWallTimeMs(intervals, nowMs) {
     if (!Number.isFinite(nowMs) || nowMs < 0)
@@ -101,7 +102,11 @@ export function activeWallTimeMs(intervals, nowMs) {
     return start === null ? 0 : total + end - start;
 }
 export function budgetExpired(state, now = Date.now()) {
-    return activeWallTimeMs(state.budget.activeIntervals, now) >= state.budget.limitMs;
+    return state.budget.limitMs !== null && activeWallTimeMs(state.budget.activeIntervals, now) >= state.budget.limitMs;
+}
+/** Infinity is internal only: callers retain their finite command/review timeouts. */
+export function remainingRunTimeMs(state, now = Date.now()) {
+    return state.budget.limitMs === null ? Infinity : state.budget.limitMs - activeWallTimeMs(state.budget.activeIntervals, now);
 }
 /** Two consecutive identical failure rounds without a useful change stop one child. */
 export function noProgressForTwoRounds(rounds) {
@@ -249,7 +254,7 @@ export class RunScheduler {
             throw error("RUN_CLOCK_INVALID", "Budget clock is invalid.");
         return await this.#repository.mutate(runId, (current) => {
             const accumulatedMs = activeWallTimeMs(current.budget.activeIntervals, nowMs);
-            const expired = accumulatedMs >= current.budget.limitMs;
+            const expired = current.budget.limitMs !== null && accumulatedMs >= current.budget.limitMs;
             return {
                 ...current,
                 status: expired && ["active", "awaiting-input"].includes(current.status) ? "budget-limited" : current.status,

package/dist/runtime/src/run/service.js

@@ -5,6 +5,8 @@ import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { budgetExpired } from "./scheduler.js";
+import { approvalRetryEvents } from "./controls.js";
+import { redactSecrets } from "../security/redact.js";
 export const RUN_PHASES = ["planning", "implementing", "verifying", "reviewing", "integrating"];
 /** Writer slots are deliberately bounded; the coordinator may occupy one. */
 export const MAX_ACTIVE_WORKERS = 2;
@@ -13,7 +15,7 @@ const ID = /^[A-Za-z0-9._:/-]{1,256}$/u;
 const SHA = /^[a-f0-9]{40,64}$/u;
 const SHA256 = /^[a-f0-9]{64}$/u;
 const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
-const MAX_EVENTS = 2_000;
+export const MAX_EVENTS = 2_000;
 const MAX_GOAL_LENGTH = 64_000;
 const MAX_TIME_BUDGET_MS = 24 * 60 * 60 * 1_000;
 function invalid(message) {
@@ -101,8 +103,10 @@ export function assertRunState(value) {
         state.budget.activeIntervals.some(interval => !plain(interval)))
         return invalid("Run state contains malformed nested records.");
     if (!RUN_ID.test(state.runId) || !SHA.test(state.goalHash) || state.goal.length > MAX_GOAL_LENGTH ||
-        sha256(state.goal) !== state.goalHash || !Number.isSafeInteger(state.budget.limitMs) ||
-        state.budget.limitMs <= 0 || state.budget.limitMs > MAX_TIME_BUDGET_MS ||
+        sha256(state.goal) !== state.goalHash || (state.budget.limitMs !== null && (!Number.isSafeInteger(state.budget.limitMs) ||
+        state.budget.limitMs <= 0 || state.budget.limitMs > MAX_TIME_BUDGET_MS)) ||
+        (state.budget.legacyLimitMs !== undefined && (!Number.isSafeInteger(state.budget.legacyLimitMs) || state.budget.legacyLimitMs <= 0 || state.budget.legacyLimitMs > MAX_TIME_BUDGET_MS)) ||
+        (state.budget.upgradedAt !== undefined && !Number.isFinite(Date.parse(state.budget.upgradedAt))) ||
         !Number.isSafeInteger(state.budget.accumulatedMs) || state.budget.accumulatedMs < 0 ||
         !Array.isArray(state.budget.activeIntervals) || state.budget.activeIntervals.some((interval) => !Number.isSafeInteger(interval.startMs) || interval.startMs < 0 ||
         (interval.endMs !== null && (!Number.isSafeInteger(interval.endMs) || interval.endMs < interval.startMs))) ||
@@ -154,10 +158,8 @@ export function createRunState(input) {
     if (input.jobs !== undefined && (!Number.isSafeInteger(input.jobs) || input.jobs < 1 || input.jobs > 2)) {
         throw new AgentOpsError("RUN_JOBS_INVALID", "A run supports one or two implementation workers.");
     }
-    const limitMs = input.timeBudgetMs ?? 60 * 60 * 1_000;
-    if (!Number.isSafeInteger(limitMs) || limitMs <= 0 || limitMs > MAX_TIME_BUDGET_MS) {
-        throw new AgentOpsError("RUN_BUDGET_INVALID", "Run time budget must be a positive value no greater than 24 hours.");
-    }
+    if (input.timeBudgetMs !== undefined)
+        throw new AgentOpsError("RUN_TIME_BUDGET_UNSUPPORTED", "New runs have no total time cap; omit --time-budget. Command and review timeouts remain effective.");
     const runId = input.runId ?? `run-${randomUUID().replaceAll("-", "").slice(0, 16)}`;
     if (!RUN_ID.test(runId))
         throw new AgentOpsError("RUN_ID_INVALID", "Run id must contain 8-64 lowercase letters, digits, and hyphens.");
@@ -186,7 +188,7 @@ export function createRunState(input) {
         awaitingResume: false,
         disableRestart: false,
         budget: {
-            limitMs,
+            limitMs: null,
             activeIntervals: [],
             accumulatedMs: 0,
             startedAt: iso(now, "budget.startedAt"),
@@ -315,6 +317,48 @@ export class FileRunRepository {
         });
     }
 }
+const RECOVERABLE = new Set(["RUN_RECOVERY_DIRTY", "RUN_NATIVE_VERSION_CHANGED", "RUN_RUNTIME_CHANGED", "RUN_REPO_UNTRUSTED",
+    "RUN_NATIVE_UNAVAILABLE", "RUN_RESTART_STORM", "RUN_POLICY_RECOVERY_REQUIRED", "RUN_POLICY_EXPIRED", "RUN_POLICY_DISABLED", "NATIVE_GOAL_NOT_ACTIVE", "RUN_WORKER_STALE", "RUN_IDENTITY_INVALID", "RUN_TIME_BUDGET_EXCEEDED", "RUN_SETUP_RECOVERY_REQUIRED", "RUN_NATIVE_START_FAILED"]);
+function resumeBlocker(current, acknowledged = new Set()) {
+    return [...current.events].reverse().find(e => !acknowledged.has(e.id) && (RECOVERABLE.has(e.code) || ["RUN_NO_PROGRESS_REPEAT", "RUN_COMMAND_DENIED"].includes(e.code)));
+}
+function cannotResume(current, acknowledged = new Set()) {
+    return current.status === "complete" || current.events.some(e => e.code === "RUN_COMMAND_DENIED" && !acknowledged.has(e.id)) ||
+        (current.integration?.proofDigest === undefined && (current.workers.some(w => w.workerId === current.coordinatorId && w.status === "blocked" && w.lastFailure !== null && w.lastFailure.failureClass !== "native-start") ||
+            (current.status === "blocked" && !RECOVERABLE.has(resumeBlocker(current, acknowledged)?.code ?? ""))));
+}
+/** Observations are not proof validation; resume still reconciles every authority and sealed artifact. */
+export function describeRunRecovery(state, now = Date.now()) {
+    const diagnostics = [...state.events].reverse().filter(e => e.type === "diagnostic");
+    const event = diagnostics[0]?.code === "RUN_CLEANUP_UNCHANGED"
+        ? diagnostics.find(e => e.code === "RUN_CLEANUP_BLOCKED") ?? diagnostics[0] : diagnostics[0];
+    let cause = event === undefined ? null : { code: event.code, detail: redactSecrets(event.detail ?? "").slice(0, 4096) };
+    if (event?.code === "RUN_CLEANUP_BLOCKED") {
+        try {
+            const saved = JSON.parse(event.detail ?? "{}");
+            if (typeof saved.code === "string" && typeof saved.message === "string")
+                cause = { code: saved.code, detail: redactSecrets(saved.message).slice(0, 4096) };
+        }
+        catch { /* Retain the recorded diagnostic when old metadata cannot be decoded. */ }
+    }
+    const sealedProof = state.integration?.proofDigest !== undefined;
+    const cleanup = state.integration?.status === "cleaned" ? "complete" :
+        state.integration?.status === "receipt-written" ? "pending" : "not-ready";
+    const resumable = !cannotResume(state);
+    const code = cause?.code ?? "";
+    const remediation = state.status === "complete" ? "No action: the completed run and its receipt are immutable." :
+        state.events.some(e => e.code === "RUN_COMMAND_DENIED") ? "Obtain genuine new authorization for the recorded denial; resume cannot erase it." :
+            /TRUST/u.test(code) ? "Restore repository trust through the supported authorization process, then manually resume; trust is revalidated." :
+                /IDENTITY|GENERATION|STALE/u.test(code) ? "Confirm the old writer is dead and reconcile its owned worktree, native identity and current generation; never replay an old request." :
+                    /PROOF|RECEIPT|TARGET_CHANGED|OWNERSHIP/u.test(code) ? "Reconcile the sealed proof, receipt, target and owner mismatch; preserve the checkout and never replace sealed artifacts." :
+                        /NO_PROGRESS/u.test(code) ? "Inspect the saved failure history; ordinary resume cannot reset no-progress counters." :
+                            cleanup === "pending" ? "Resolve the recorded cleanup blocker, then manually resume the original run. Only missing steps run after proof, receipt, target and ownership validation; unchanged cleanup inputs are refused." :
+                                RECOVERABLE.has(code) ? `Resolve ${code}, then manually resume the original run; runtime, policy, identity and worktree checks still apply.` :
+                                    state.status === "awaiting-input" ? "Answer the pending question with agent-ops run respond." :
+                                        !resumable ? "Inspect agent-ops run logs and repair the recorded blocker before requesting recovery; do not blindly resume." :
+                                            "Inspect agent-ops run logs before a manual resume; reconciliation precedes any writer restart.";
+    return { phase: state.phase ?? "unknown", cause, sealedProof: sealedProof ? "recorded-unchecked" : "none", cleanup, resumable, remediation };
+}
 /**
  * Small service facade used by the CLI and supervisor. Native host execution is
  * injected; this layer owns persistent run identity and never treats a host's
@@ -374,29 +418,32 @@ export class RunService {
         }));
         return { state, message: `Run ${runId} is paused.` };
     }
-    async resume(runId) {
-        const state = await this.#repository.mutate(runId, (current) => {
-            const recoverable = new Set(["RUN_RECOVERY_DIRTY", "RUN_NATIVE_VERSION_CHANGED", "RUN_RUNTIME_CHANGED", "RUN_REPO_UNTRUSTED",
-                "RUN_NATIVE_UNAVAILABLE", "RUN_RESTART_STORM", "RUN_POLICY_RECOVERY_REQUIRED", "RUN_POLICY_EXPIRED", "RUN_SETUP_RECOVERY_REQUIRED", "RUN_NATIVE_START_FAILED"]);
-            const blocker = [...current.events].reverse().find(e => recoverable.has(e.code) || ["RUN_NO_PROGRESS_REPEAT", "RUN_COMMAND_DENIED"].includes(e.code));
-            const terminalBlocker = current.events.some(e => e.code === "RUN_COMMAND_DENIED") ||
-                current.workers.some(w => w.workerId === current.coordinatorId && w.status === "blocked" && w.lastFailure !== null && w.lastFailure.failureClass !== "native-start");
-            if (current.status === "complete" || (current.integration?.proofDigest === undefined &&
-                (terminalBlocker || (current.status === "blocked" && !recoverable.has(blocker?.code ?? ""))))) {
+    async resume(runId, retryApprovalIds = [], upgradeBudget = true) {
+        const state = await this.#repository.mutate(runId, async (current) => {
+            const acknowledged = await approvalRetryEvents(current, retryApprovalIds);
+            const recoverable = RECOVERABLE;
+            const blocker = resumeBlocker(current, acknowledged);
+            if (cannotResume(current, acknowledged)) {
                 throw new AgentOpsError("RUN_NOT_RESUMABLE", `Run ${runId} is ${current.status}.`);
             }
-            if (current.integration?.proofDigest === undefined && budgetExpired(current, Date.parse(this.#now())))
+            if (current.integration?.proofDigest === undefined && !upgradeBudget && budgetExpired(current, Date.parse(this.#now())))
                 throw new AgentOpsError("RUN_BUDGET_EXHAUSTED", "Explicit resume preserves the whole-run budget; no execution allowance remains.");
-            const recover = ["blocked", "paused"].includes(current.status) && recoverable.has(blocker?.code ?? "");
+            const recover = ["blocked", "paused", "budget-limited"].includes(current.status) && recoverable.has(blocker?.code ?? "");
             return {
                 ...current,
-                ...(recover ? { workers: current.workers.map(w => w.status === "blocked" && (w.lastFailure === null || w.lastFailure.failureClass === "native-start") ? { ...w, status: "stopped" } : w),
+                ...(upgradeBudget && current.budget.limitMs !== null ? {
+                    budget: { ...current.budget, limitMs: null, legacyLimitMs: current.budget.limitMs, upgradedAt: this.#now() },
+                    events: [...current.events, event({ type: "diagnostic", code: "RUN_BUDGET_UPGRADED", workerId: null, taskId: null,
+                            detail: `Manual resume removed legacy total cap ${current.budget.limitMs}ms; accounting and independent blockers remain.` }, this.#now())].slice(-MAX_EVENTS)
+                } : {}),
+                ...(recover ? { workers: current.workers.map(w => w.status === "blocked" && (w.lastFailure === null || w.lastFailure.failureClass === "native-start") &&
+                        !current.tasks.some(t => t.taskId === w.taskId && t.status === "blocked" && !recoverable.has(t.blockedReason ?? "")) ? { ...w, status: "stopped" } : w),
                     tasks: current.tasks.map(t => t.status === "blocked" && recoverable.has(t.blockedReason ?? "") ? { ...t, status: "ready", blockedReason: null } : t) } : {}),
                 status: "active",
                 awaitingResume: false,
                 disableRestart: false,
                 controls: [...current.controls, {
-                        action: "resume", actor: "user", reason: null, requestedAt: this.#now(), expiresAt: null, appliedAt: null
+                        action: "resume", actor: "user", reason: retryApprovalIds.length === 0 ? null : "retry-approval:" + JSON.stringify(retryApprovalIds), requestedAt: this.#now(), expiresAt: null, appliedAt: null
                     }]
             };
         });

package/dist/runtime/src/run/supervisor.js

@@ -109,13 +109,17 @@ export class RunSupervisor {
             throw error("RUN_WORKER_NOT_FOUND", `Registered worker disappeared: ${workerId}`);
         return { workerId, taskId: input.taskId, ownerSessionId: input.ownerSessionId, generation: worker.generation, worktree: worker.worktree };
     }
-    async startWorker(runId, workerId, generation, goal) {
+    async startWorker(runId, workerId, generation, goal, manualResumeAt) {
         assertId(workerId, "workerId");
         if (!Number.isSafeInteger(generation) || generation < 1)
             throw error("RUN_GENERATION_INVALID", "Worker generation is invalid.");
         const before = await this.#repository.read(runId);
         if (before === null)
             throw error("RUN_NOT_FOUND", `Run not found: ${runId}`);
+        const control = before.controls.at(-1);
+        if (manualResumeAt !== undefined && (control?.actor !== "user" || control.action !== "resume" ||
+            control.requestedAt !== manualResumeAt || !Number.isFinite(Date.parse(manualResumeAt)) || Date.parse(manualResumeAt) > Date.parse(this.#now())))
+            throw error("RUN_WORKER_STALE", "Native recovery requires the current explicit manual resume.");
         if (before.host !== this.#host.host)
             throw error("RUN_HOST_MISMATCH", `Run ${runId} is assigned to ${before.host}, not ${this.#host.host}.`);
         const worker = before.workers.find((candidate) => candidate.workerId === workerId);
@@ -126,12 +130,16 @@ export class RunSupervisor {
         const starting = await this.#repository.mutate(runId, (current) => {
             if (current.status !== "active" || current.disableRestart || current.awaitingResume)
                 throw error("RUN_START_DISABLED", "Run state no longer permits starting a writer.");
+            if (manualResumeAt !== undefined && current.controls.at(-1)?.requestedAt !== manualResumeAt)
+                throw error("RUN_WORKER_STALE", "Manual recovery changed before native start.");
             if (budgetExpired(current, Date.parse(this.#now())))
                 throw error("RUN_BUDGET_EXHAUSTED", "The cumulative run budget cannot be reset by starting another worker.");
             const currentWorker = current.workers.find((candidate) => candidate.workerId === workerId);
             if (currentWorker === undefined || currentWorker.generation !== generation || currentWorker.status !== "assigned") {
                 throw error("RUN_WORKER_STALE", `Worker ${workerId} changed before native start.`);
             }
+            if (current.workers.filter(candidate => candidate.workerId !== workerId && activeWorker(candidate)).length >= current.jobs)
+                throw error("RUN_WORKER_LIMIT", "No native execution slot is available.");
             return replaceWorker(replaceTask(current, currentWorker.taskId, { status: "running" }), {
                 ...currentWorker,
                 status: "starting",
@@ -150,7 +158,8 @@ export class RunSupervisor {
                 ownerSessionId: startingWorker.ownerSessionId,
                 generation,
                 worktree: startingWorker.worktree,
-                contractHash: before.currentContractHash
+                contractHash: before.currentContractHash,
+                ...(manualResumeAt === undefined ? {} : { manualResumeAt })
             });
         }
         catch (cause) {

package/dist/runtime/src/run/transport.js

@@ -38,6 +38,7 @@ export class NativeRunTransport {
         const saved = (await this.repository.read(input.runId))?.workers.find(w => w.workerId === input.workerId);
         const request = { runId: input.runId, workerId: input.workerId, generation: input.generation,
             contractHash: input.contractHash, cwd: input.worktree,
+            ...(input.manualResumeAt === undefined ? {} : { manualResumeAt: input.manualResumeAt }),
             env: { AGENT_OPS_SESSION_ID: input.ownerSessionId, AGENT_OPS_HOST: this.host,
                 CODEX_THREAD_ID: undefined, AGENT_OPS_AGENT_ID: undefined,
                 AGENT_OPS_RUN_ID: input.runId, AGENT_OPS_WORKER_ID: input.workerId,

package/dist/runtime/src/security/permissions.js

@@ -37,6 +37,7 @@ const execFile = promisify(execFileCallback);
 const lockQueues = new Map();
 const heartbeatFailures = new Map();
 const heartbeatPaths = new Set();
+const heartbeatReleases = new Map();
 // A heartbeat lives as long as the process. Its handle is held here, not only
 // by the interval below, so a reset or mocked timer can never let garbage
 // collection close it (an uncaught error since Node 26).
@@ -172,6 +173,14 @@ async function ensureProcessHeartbeat(parent, anchorDirectory) {
                 });
             });
         }, HEARTBEAT_INTERVAL_MS);
+        heartbeatReleases.set(heartbeatPath, async () => {
+            clearInterval(timer);
+            await handle.close();
+            heartbeatHandles.delete(handle);
+            heartbeatPaths.delete(heartbeatPath);
+            processHeartbeats.delete(cacheKey);
+            heartbeatReleases.delete(heartbeatPath);
+        });
         timer.unref();
         return heartbeat;
     })();
@@ -184,6 +193,82 @@ async function ensureProcessHeartbeat(parent, anchorDirectory) {
         throw error;
     }
 }
+async function fileIdentity(path) {
+    try {
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const { dev, ino } = await handle.stat({ bigint: true });
+            return { dev, ino };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Retire authenticated runtime markers without weakening Git's dirty-file guard. */
+export async function cleanupWorktreeHeartbeats(root, paths) {
+    const candidates = [];
+    for (const relativePath of paths) {
+        const match = /^\.(?:claude|codex)\/\.agent-ops-process-([1-9]\d*)-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/u.exec(relativePath);
+        if (match === null)
+            continue;
+        const path = join(root, relativePath), pid = Number(match[1]);
+        const unsafe = () => new AgentOpsError("WORKTREE_HEARTBEAT_UNSAFE", `Preserve unverified heartbeat ${relativePath} (PID ${pid}).`);
+        const blocked = () => new AgentOpsError("WORKTREE_HEARTBEAT_ACTIVE", `Preserve heartbeat ${relativePath}: PID ${pid} is active or its death cannot be confirmed.`);
+        if (!Number.isSafeInteger(pid) || pid > 2147483647)
+            throw unsafe();
+        const parent = await lstat(dirname(path));
+        if (parent.isSymbolicLink() || !parent.isDirectory())
+            throw unsafe();
+        let handle;
+        try {
+            handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            const status = await handle.stat({ bigint: true });
+            if (!status.isFile() || status.nlink !== 1n || status.size > 128n ||
+                await handle.readFile("utf8") !== `runtime:${match[2]}\n`)
+                throw unsafe();
+            const own = pid === process.pid && match[2] === PROCESS_INSTANCE_TOKEN && heartbeatReleases.has(path);
+            if (own) {
+                if ([...lockQueues.keys()].some(key => key.startsWith(`${resolve(root)}\0`)))
+                    throw blocked();
+            }
+            else if (isProcessActive(pid))
+                throw blocked();
+            candidates.push({ path, relative: relativePath, pid, own, dev: status.dev, ino: status.ino });
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            if (error instanceof AgentOpsError)
+                throw error;
+            throw unsafe();
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    // Validate the complete set before removing anything; foreign owners fail closed.
+    for (const candidate of candidates) {
+        const status = await lstat(candidate.path, { bigint: true });
+        // Identity is compared handle to handle, as it was captured: on Windows, Node 22.14.0
+        // reports different dev/ino for lstat and fstat of the same file.
+        const identity = await fileIdentity(candidate.path);
+        if (!status.isFile() || status.isSymbolicLink() || identity === undefined || identity.dev !== candidate.dev || identity.ino !== candidate.ino)
+            throw new AgentOpsError("WORKTREE_HEARTBEAT_UNSAFE", `Heartbeat changed before cleanup: ${candidate.relative}.`);
+        if (!candidate.own && isProcessActive(candidate.pid))
+            throw new AgentOpsError("WORKTREE_HEARTBEAT_ACTIVE", `Preserve heartbeat ${candidate.relative}: PID ${candidate.pid} is active or its death cannot be confirmed.`);
+        if (candidate.own) {
+            const release = heartbeatReleases.get(candidate.path);
+            if (release === undefined || [...lockQueues.keys()].some(key => key.startsWith(`${resolve(root)}\0`)))
+                throw new AgentOpsError("WORKTREE_HEARTBEAT_ACTIVE", `Current-process locks still protect ${candidate.relative} (PID ${candidate.pid}).`);
+            await release();
+        }
+        await rm(candidate.path);
+    }
+}
 async function assertProcessHeartbeat(parent, heartbeat) {
     const heartbeatPath = join(parent, heartbeat.file);
     try {

package/dist/runtime/src/task/debug-state.js

@@ -50,7 +50,7 @@ export function validDebugState(v) {
     if (new Set(v.receipts.map(r => r.id)).size !== v.receipts.length || v.receipts.filter(r => r.round).length > v.maxRounds)
         return false;
     for (const g of v.grants)
-        if (!exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs"]) || !text(g.eventId) || !text(g.sessionId) || !hash(g.sourceDigest) || g.grantedMs !== DEBUG_EXTENSION_MS)
+        if (!(exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs"]) || (exact(g, ["eventId", "sessionId", "sourceDigest", "grantedMs", "spentAtGrantMs"]) && integer(g.spentAtGrantMs))) || !text(g.eventId) || !text(g.sessionId) || !hash(g.sourceDigest) || (g.grantedMs !== DEBUG_EXTENSION_MS && g.grantedMs !== null))
             return false;
     if (new Set(v.grants.map(g => g.eventId)).size !== v.grants.length)
         return false;
@@ -79,10 +79,16 @@ export function createDebugState(rootTaskId, baselineCommit, settings = DEBUG_DE
         hypotheses: [], receipts: [], strategy: null, grants: [], foreground: null, operation: null, checkpoint: null };
 }
 export function debugRounds(state) { return state.receipts.filter(r => r.round).length; }
-export function debugRemainingMs(state, now = Date.now()) {
+export function debugSpentMs(state, now = Date.now()) {
     const starts = [state.foreground?.startedAt, state.operation?.startedAt].filter((startedAt) => startedAt !== undefined);
     const active = starts.length === 0 ? 0 : Math.max(0, now - Math.min(...starts));
-    return Math.max(0, state.budgetMs + state.grants.reduce((n, g) => n + g.grantedMs, 0) - state.consumedMs - active);
+    return state.consumedMs + active;
+}
+export function debugRemainingMs(state, now = Date.now()) {
+    if (state.grants.some(g => g.grantedMs === null))
+        return Number.POSITIVE_INFINITY;
+    const limit = state.grants.reduce((n, g) => Math.max(n, g.spentAtGrantMs ?? n) + (g.grantedMs ?? 0), state.budgetMs);
+    return Math.max(0, limit - debugSpentMs(state, now));
 }
 export function debugStopCause(state, now = Date.now()) {
     if (state.control?.paused === true)