@hecer/yoke 1.3.0 → 1.4.0

package/dist/loop/claim-lease.js

@@ -0,0 +1,131 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+const ClaimOperationLeaseSchema = z.object({
+    schemaVersion: z.literal(1),
+    token: z.string().uuid(),
+    pid: z.number().int().positive(),
+    createdAt: z.string().min(1),
+});
+function operationPath(file) {
+    return `${file}.operation`;
+}
+function recoveryPath(file) {
+    return `${operationPath(file)}.recovery`;
+}
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+function publish(file, value, token = randomUUID()) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = `${file}.${token}.tmp`;
+    writeFileSync(temporary, JSON.stringify(value), { flag: 'wx' });
+    try {
+        linkSync(temporary, file);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function readLease(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return ClaimOperationLeaseSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+function expired(lease, options) {
+    const createdAt = Date.parse(lease.createdAt);
+    return !options.isAlive(lease.pid) && (!Number.isFinite(createdAt) || options.now.getTime() - createdAt > options.staleMs);
+}
+function lease(token, options) {
+    return { schemaVersion: 1, token, pid: process.pid, createdAt: options.now.toISOString() };
+}
+function acquireRecovery(file, options) {
+    const token = randomUUID();
+    if (publish(file, lease(token, options), token))
+        return token;
+    const observed = readLease(file);
+    if (!observed || !expired(observed, options))
+        return null;
+    options.filesystem?.beforeRecoveryRemove?.(file);
+    const current = readLease(file);
+    if (!current || current.token !== observed.token || !expired(current, options))
+        return null;
+    rmSync(file, { force: true });
+    return publish(file, lease(token, options), token) ? token : null;
+}
+export function publishClaimFile(file, value) {
+    return publish(file, value);
+}
+export function replaceClaimFile(file, value) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(value), { flag: 'wx' });
+    renameSync(temporary, file);
+}
+export function acquireClaimOperation(file, options) {
+    const token = randomUUID();
+    const candidate = lease(token, options);
+    const operation = operationPath(file);
+    if (publish(operation, candidate, token))
+        return token;
+    const observed = readLease(operation);
+    if (!observed || !expired(observed, options))
+        return null;
+    const recovery = recoveryPath(file);
+    const recoveryToken = acquireRecovery(recovery, options);
+    if (!recoveryToken)
+        return null;
+    try {
+        const current = readLease(operation);
+        if (!current || !expired(current, options))
+            return null;
+        rmSync(operation, { force: true });
+        return publish(operation, candidate, token) ? token : null;
+    }
+    finally {
+        releaseClaimOperation(recovery, recoveryToken, true);
+    }
+}
+export function releaseClaimOperation(file, token, rawPath = false) {
+    const operation = rawPath ? file : operationPath(file);
+    const current = readLease(operation);
+    if (current?.token === token)
+        rmSync(operation, { force: true });
+}
+export function withClaimOperation(file, context, readRecords, task) {
+    return withClaimOperations(file, context, readRecords, () => [], task);
+}
+export function withClaimOperations(file, context, readRecords, claimFiles, task) {
+    const token = acquireClaimOperation(file, context);
+    if (!token)
+        return null;
+    const acquired = [];
+    const orderedFiles = [...new Set(claimFiles(readRecords()).filter(candidate => candidate !== file))].sort((left, right) => left.localeCompare(right));
+    try {
+        for (const nextFile of orderedFiles) {
+            const nextToken = acquireClaimOperation(nextFile, context);
+            if (!nextToken)
+                return null;
+            acquired.push({ file: nextFile, token: nextToken });
+        }
+        return task(readRecords());
+    }
+    finally {
+        for (const lease of acquired.reverse())
+            releaseClaimOperation(lease.file, lease.token);
+        releaseClaimOperation(file, token);
+    }
+}

package/dist/loop/claims.js

@@ -1,57 +1,194 @@
-import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-const pathFor = (dir, id) => join(dir, '.yoke', 'claims', `${id}.json`);
-export function acquireClaim(dir, storyId, owner, opts = {}) {
-    const path = pathFor(dir, storyId);
-    mkdirSync(join(dir, '.yoke', 'claims'), { recursive: true });
-    const now = opts.now ?? new Date();
-    try {
-        const old = JSON.parse(readFileSync(path, 'utf8'));
-        if (now.getTime() - Date.parse(old.claimedAt) <= (opts.staleMs ?? 30 * 60_000))
-            return null;
-        rmSync(path, { force: true });
-    }
-    catch { /* absent or malformed */ }
-    const claim = { storyId, owner, pid: opts.pid ?? process.pid, claimedAt: now.toISOString() };
+import { z } from 'zod';
+import { isPidAlive } from './lock.js';
+import { publishClaimFile, replaceClaimFile, withClaimOperations } from './claim-lease.js';
+import { storyPathSegment } from './prd.js';
+export const CLAIM_SCHEMA_VERSION = 2;
+const LegacyClaimSchema = z.object({
+    storyId: z.string().min(1),
+    owner: z.string().min(1),
+    pid: z.number().int().positive(),
+    claimedAt: z.string().min(1),
+});
+const RichClaimSchema = LegacyClaimSchema.extend({
+    schemaVersion: z.literal(CLAIM_SCHEMA_VERSION),
+    dispatcherId: z.string().min(1),
+    ownerToken: z.string().min(1),
+    heartbeatAt: z.string().min(1),
+    baseCommit: z.string().min(1).optional(),
+    worktree: z.string().min(1).optional(),
+    provider: z.enum(['claude', 'codex', 'gemini']).optional(),
+    model: z.string().min(1).optional(),
+    role: z.enum(['implementation', 'quality', 'repair', 'review']).optional(),
+    cancellation: z.object({
+        requestedAt: z.string().min(1),
+        reason: z.string().min(1),
+    }).optional(),
+});
+const StoredClaimSchema = z.union([RichClaimSchema, LegacyClaimSchema]);
+function claimsDir(dir) {
+    return join(dir, '.yoke', 'claims');
+}
+function pathFor(dir, id) {
+    return join(claimsDir(dir), `${storyPathSegment(id)}.json`);
+}
+function claimOwner(claim) {
+    return 'ownerToken' in claim ? claim.ownerToken : claim.owner;
+}
+function readClaimFile(file) {
+    if (!existsSync(file))
+        return null;
     try {
-        const fd = openSync(path, 'wx');
-        writeFileSync(fd, JSON.stringify(claim));
-        closeSync(fd);
-        return claim;
+        return StoredClaimSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
     }
     catch {
         return null;
     }
 }
-export function releaseClaim(dir, storyId, owner) {
-    const path = pathFor(dir, storyId);
-    try {
-        const claim = JSON.parse(readFileSync(path, 'utf8'));
-        if (claim.owner !== owner)
+function claimRecords(dir, storyId) {
+    const canonicalPath = pathFor(dir, storyId);
+    const records = [];
+    const canonicalClaim = readClaimFile(canonicalPath);
+    if (canonicalClaim?.storyId === storyId)
+        records.push({ path: canonicalPath, claim: canonicalClaim });
+    if (!existsSync(claimsDir(dir)))
+        return records;
+    for (const file of readdirSync(claimsDir(dir))) {
+        const path = join(claimsDir(dir), file);
+        if (path === canonicalPath)
+            continue;
+        const claim = readClaimFile(path);
+        if (claim?.storyId === storyId)
+            records.push({ path, claim });
+    }
+    return records;
+}
+function resolveClaimRecord(dir, storyId) {
+    return claimRecords(dir, storyId)[0] ?? null;
+}
+function matchingClaimRecords(records, ownerToken) {
+    return records.filter(record => claimOwner(record.claim) === ownerToken);
+}
+export function readClaim(dir, storyId) {
+    return resolveClaimRecord(dir, storyId)?.claim ?? null;
+}
+function isExpired(claim, now, staleMs, isAlive) {
+    const heartbeatAt = 'heartbeatAt' in claim ? claim.heartbeatAt : claim.claimedAt;
+    const heartbeatMs = Date.parse(heartbeatAt);
+    return !isAlive(claim.pid) && (!Number.isFinite(heartbeatMs) || now.getTime() - heartbeatMs > staleMs);
+}
+function richClaim(storyId, owner, options) {
+    const now = options.now ?? new Date();
+    const ownerToken = options.ownerToken ?? owner;
+    return {
+        schemaVersion: CLAIM_SCHEMA_VERSION,
+        storyId,
+        owner: ownerToken,
+        ownerToken,
+        dispatcherId: options.dispatcherId ?? owner,
+        pid: options.pid ?? process.pid,
+        claimedAt: now.toISOString(),
+        heartbeatAt: now.toISOString(),
+        ...(options.baseCommit ? { baseCommit: options.baseCommit } : {}),
+        ...(options.worktree ? { worktree: options.worktree } : {}),
+        ...(options.provider ? { provider: options.provider } : {}),
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.role ? { role: options.role } : {}),
+    };
+}
+function promoteClaim(claim, now) {
+    if ('schemaVersion' in claim)
+        return claim;
+    return {
+        schemaVersion: CLAIM_SCHEMA_VERSION,
+        storyId: claim.storyId,
+        owner: claim.owner,
+        ownerToken: claim.owner,
+        dispatcherId: claim.owner,
+        pid: claim.pid,
+        claimedAt: claim.claimedAt,
+        heartbeatAt: now.toISOString(),
+    };
+}
+export function acquireClaim(dir, storyId, owner, options = {}) {
+    const candidate = richClaim(storyId, owner, options);
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        if (records.some(record => !isExpired(record.claim, now, staleMs, isAlive)))
+            return null;
+        for (const record of records)
+            rmSync(record.path, { force: true });
+        return publishClaimFile(pathFor(dir, storyId), candidate) ? candidate : null;
+    });
+}
+export function heartbeatClaim(dir, storyId, ownerToken, options = {}) {
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        const record = records.find(candidate => claimOwner(candidate.claim) === ownerToken);
+        if (!record)
+            return null;
+        const updated = { ...promoteClaim(record.claim, now), heartbeatAt: now.toISOString() };
+        for (const matchingRecord of matchingClaimRecords(records, ownerToken))
+            replaceClaimFile(matchingRecord.path, updated);
+        return updated;
+    });
+}
+export function requestClaimCancellation(dir, storyId, ownerToken, reason, options = {}) {
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        const record = records.find(candidate => claimOwner(candidate.claim) === ownerToken);
+        if (!record)
+            return null;
+        const updated = {
+            ...promoteClaim(record.claim, now),
+            cancellation: { reason, requestedAt: now.toISOString() },
+        };
+        for (const matchingRecord of matchingClaimRecords(records, ownerToken))
+            replaceClaimFile(matchingRecord.path, updated);
+        return updated;
+    });
+}
+export function releaseClaim(dir, storyId, ownerToken, options = {}) {
+    const now = options.now ?? new Date();
+    const staleMs = options.staleMs ?? 30 * 60_000;
+    const isAlive = options.isAlive ?? isPidAlive;
+    const file = resolveClaimRecord(dir, storyId)?.path ?? pathFor(dir, storyId);
+    return withClaimOperations(file, { now, staleMs, isAlive }, () => claimRecords(dir, storyId), records => records.map(record => record.path), records => {
+        const matchingRecords = matchingClaimRecords(records, ownerToken);
+        if (!matchingRecords.length)
             return false;
-        rmSync(path, { force: true });
+        for (const record of matchingRecords)
+            rmSync(record.path, { force: true });
         return true;
-    }
-    catch {
-        return false;
-    }
+    }) ?? false;
 }
-export function cleanupClaims(dir, owner) {
-    const claimsDir = join(dir, '.yoke', 'claims');
+export function cleanupClaims(dir, ownerToken) {
+    const dirPath = claimsDir(dir);
     let removed = 0;
     try {
-        for (const file of readdirSync(claimsDir)) {
-            const path = join(claimsDir, file);
-            try {
-                const claim = JSON.parse(readFileSync(path, 'utf8'));
-                if (!owner || claim.owner === owner) {
-                    rmSync(path, { force: true });
-                    removed++;
-                }
+        for (const file of readdirSync(dirPath)) {
+            const path = join(dirPath, file);
+            const claim = readClaimFile(path);
+            if (!claim)
+                continue;
+            if (!ownerToken || claimOwner(claim) === ownerToken) {
+                rmSync(path, { force: true });
+                removed += 1;
             }
-            catch { /* scoped cleanup never guesses ownership */ }
         }
     }
-    catch { /* no claims */ }
+    catch {
+        return removed;
+    }
     return removed;
 }

package/dist/loop/cleanup.js

@@ -1,14 +1,17 @@
-import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { parseProviderProcessRecord } from '../agents/process-record.js';
+import { processIncarnation } from '../agents/process-incarnation.js';
 import { acquireTakeoverLease, acquireTakeoverRecoveryLease, lockPath, takeoverLockPath, readLock, isPidAlive, releaseTakeoverLease, releaseTakeoverRecoveryLease, takeoverRecoveryPath, } from './lock.js';
-import { killProcessTree } from './watchdog.js';
+import { killProcessForCleanup, killProcessTreeForCleanup } from './watchdog.js';
+import { cleanupClaims } from './claims.js';
 // Reap orphaned runners PROJECT-SCOPED: kill only pids recorded in this project's
 // .yoke/runner.pid files (main dir + each worktree). Never by process-name or
 // command-line pattern — that takes down runners belonging to OTHER projects,
 // which then stall mid-story. Skipped entirely while the loop lock holder is
 // alive: a live loop's runner is healthy, not an orphan.
-function reapRecordedRunners(targetDir, wtDir, isAlive, killTree) {
+export function reapRecordedRunners(targetDir, wtDir, isAlive, isTreeAlive, killChildTree, killWatchdog, currentIncarnation) {
     const pidFiles = [join(targetDir, '.yoke', 'runner.pid')];
     if (existsSync(wtDir)) {
         for (const name of readdirSync(wtDir))
@@ -18,28 +21,85 @@ function reapRecordedRunners(targetDir, wtDir, isAlive, killTree) {
     for (const file of pidFiles) {
         if (!existsSync(file))
             continue;
+        let rec;
         try {
-            const rec = JSON.parse(readFileSync(file, 'utf8'));
-            // Child (agent tree) first, then the watchdog wrapper.
-            for (const pid of [rec.childPid, rec.watchdogPid]) {
-                if (typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && isAlive(pid)) {
-                    killTree(pid);
-                    killed++;
+            rec = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch { /* malformed record — still consume the file below */ }
+        if (!rec) {
+            rmSync(file, { force: true });
+            continue;
+        }
+        // Child (agent tree) first, then the watchdog wrapper.
+        for (const [pid, incarnation, treeOwned] of [[rec.childPid, rec.childIncarnation, true], [rec.watchdogPid, rec.watchdogIncarnation, false]]) {
+            const alive = typeof pid === 'number' && Number.isInteger(pid) && pid > 0 && (isAlive(pid) || (treeOwned && isTreeAlive(pid)));
+            if (alive && typeof pid === 'number') {
+                if (isAlive(pid) && (typeof incarnation !== 'string' || currentIncarnation(pid) !== incarnation)) {
+                    throw new Error(`could not confirm legacy runner process incarnation for pid ${pid}`);
+                }
+                const terminated = treeOwned ? killChildTree(pid) : killWatchdog(pid);
+                if (!terminated && (isAlive(pid) || (treeOwned && isTreeAlive(pid)))) {
+                    throw new Error(`could not confirm legacy runner process tree termination for pid ${pid}`);
                 }
+                if (terminated)
+                    killed++;
             }
         }
-        catch { /* malformed record — still consume the file below */ }
         rmSync(file, { force: true });
     }
     return killed;
 }
+export function reapProviderProcesses(targetDir, isAlive, isTreeAlive, killTree, currentIncarnation = processIncarnation) {
+    const recordsDir = join(targetDir, '.yoke', 'provider-processes');
+    if (!existsSync(recordsDir))
+        return 0;
+    const expectedTarget = resolve(targetDir);
+    let killed = 0;
+    for (const name of readdirSync(recordsDir)) {
+        const recordPath = join(recordsDir, name);
+        let parsed = null;
+        try {
+            parsed = parseProviderProcessRecord(JSON.parse(readFileSync(recordPath, 'utf8')));
+        }
+        catch { /* malformed records are not trusted or consumed */ }
+        if (!parsed || parsed.targetDir !== expectedTarget)
+            continue;
+        if (isAlive(parsed.childPid) || isTreeAlive(parsed.childPid)) {
+            if (isAlive(parsed.childPid) && currentIncarnation(parsed.childPid) !== parsed.startedAt) {
+                throw new Error(`could not confirm provider process incarnation for pid ${parsed.childPid}`);
+            }
+            const terminated = killTree(parsed.childPid);
+            if (!terminated && (isAlive(parsed.childPid) || isTreeAlive(parsed.childPid))) {
+                throw new Error(`could not confirm provider process tree termination for pid ${parsed.childPid}`);
+            }
+            if (terminated)
+                killed++;
+        }
+        rmSync(recordPath, { force: true });
+    }
+    return killed;
+}
+export function isProviderTreeAlive(pid) {
+    if (process.platform === 'win32')
+        return isPidAlive(pid);
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 // Cleans ONLY yoke-created runtime artifacts: recorded orphan runners,
 // .yoke/worktrees/*, and a stale loop.lock. Never touches user-created
 // worktrees, a lock whose holder is alive, or any process it did not record.
 export function runLoopCleanup(targetDir, opts = {}) {
     const git = opts.git ?? ((args, cwd) => { execFileSync('git', args, { cwd, stdio: 'pipe' }); });
     const isAlive = opts.isAlive ?? isPidAlive;
-    const killTree = opts.killTree ?? killProcessTree;
+    const killWatchdog = opts.killTree ?? killProcessForCleanup;
+    const killProviderTree = opts.killTree ?? killProcessTreeForCleanup;
+    const providerTreeAlive = process.platform === 'win32' ? isAlive : isProviderTreeAlive;
+    const currentIncarnation = opts.processIncarnation ?? processIncarnation;
     const wtDir = join(targetDir, '.yoke', 'worktrees');
     const recoveryFile = takeoverRecoveryPath(targetDir);
     if (opts.discardStaleRecovery && existsSync(recoveryFile)) {
@@ -112,20 +172,34 @@ export function runLoopCleanup(targetDir, opts = {}) {
             console.log(`Loop lock held by a live process (pid ${holder.pid}) — no cleanup performed.`);
             return 0;
         }
-        const killed = reapRecordedRunners(targetDir, wtDir, isAlive, killTree);
-        if (killed > 0)
-            console.log(`Killed ${killed} orphaned runner process tree(s) recorded in runner.pid files.`);
+        let killed;
+        try {
+            killed = reapRecordedRunners(targetDir, wtDir, isAlive, providerTreeAlive, killProviderTree, killWatchdog, currentIncarnation) + reapProviderProcesses(targetDir, isAlive, providerTreeAlive, killProviderTree, currentIncarnation);
+        }
+        catch (error) {
+            console.error(`Failed to reap recorded process trees: ${error.message}`);
+            return 1;
+        }
         let removed = 0;
         let failed = 0;
         if (existsSync(wtDir)) {
             for (const name of readdirSync(wtDir)) {
                 const path = join(wtDir, name);
+                try {
+                    killed += reapProviderProcesses(path, isAlive, providerTreeAlive, killProviderTree, currentIncarnation);
+                }
+                catch (error) {
+                    console.error(`Failed to reap provider processes for worktree ${path}: ${error.message}`);
+                    failed++;
+                    continue;
+                }
                 if (!opts.removeWorktrees) {
                     console.log(`Yoke worktree retained: ${path} (pass --remove-worktrees to remove it)`);
                     continue;
                 }
                 try {
                     git(['worktree', 'remove', '--force', path], targetDir);
+                    markCandidateWorktreeRemoved(targetDir, path);
                     removed++;
                 }
                 catch (e) {
@@ -140,6 +214,10 @@ export function runLoopCleanup(targetDir, opts = {}) {
                 catch { /* best-effort */ }
             }
         }
+        if (killed > 0)
+            console.log(`Killed ${killed} orphaned process tree(s) from project-scoped Yoke records.`);
+        if (opts.removeWorktrees && failed === 0)
+            cleanupClaims(targetDir);
         const lockFile = lockPath(targetDir);
         if (existsSync(lockFile)) {
             rmSync(lockFile, { force: true });
@@ -152,3 +230,27 @@ export function runLoopCleanup(targetDir, opts = {}) {
         releaseTakeoverLease(targetDir, cleanupLease.ownerToken);
     }
 }
+function markCandidateWorktreeRemoved(targetDir, worktree) {
+    const proofRoot = join(targetDir, '.yoke', 'proof');
+    if (!existsSync(proofRoot))
+        return;
+    for (const storyId of readdirSync(proofRoot)) {
+        const candidates = join(proofRoot, storyId, 'candidates');
+        if (!existsSync(candidates))
+            continue;
+        for (const candidateId of readdirSync(candidates)) {
+            const status = join(candidates, candidateId, 'status.json');
+            if (!existsSync(status))
+                continue;
+            try {
+                const parsed = JSON.parse(readFileSync(status, 'utf8'));
+                if (parsed.worktree !== worktree)
+                    continue;
+                writeFileSync(status, JSON.stringify({ ...parsed, state: 'removed', reason: 'external cleanup recovered candidate worktree' }));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+}

package/dist/loop/decision.js

@@ -72,12 +72,43 @@ export const DecisionResumeSchema = z.object({
     permissions: z.enum(['safe', 'unsafe', 'read-only']).optional(),
     parallel: z.number().int().positive().optional(),
     routing: z.boolean().optional(),
+    quality: z.boolean().optional(),
+    qualityRounds: z.number().int().positive().optional(),
+    qualityMinutes: z.number().int().positive().optional(),
+    qualityPolicy: z.enum(['blocking', 'advisory']).optional(),
+    candidates: z.number().int().positive().optional(),
     projectId: z.string().regex(/^[a-f0-9]{16}$/u).optional(),
     baseCommit: z.string().regex(/^[a-f0-9]{40,64}$/u).optional(),
     prdHash: z.string().regex(/^[a-f0-9]{64}$/u).optional(),
     decisionCommit: z.string().regex(/^[a-f0-9]{40,64}$/u).optional(),
     answerId: z.string().regex(/^[a-f0-9]{16}$/u).optional(),
 });
+export function buildTrustedDecisionResumeState(input) {
+    return DecisionResumeSchema.parse({
+        version: 1,
+        storyId: input.storyId,
+        requestId: input.requestId,
+        answered: false,
+        ...(input.maxIterations !== undefined ? { maxIterations: input.maxIterations } : {}),
+        ...(input.agent ? { agent: input.agent } : {}),
+        isolate: input.isolate,
+        ...(input.reviewer ? { reviewer: input.reviewer } : {}),
+        review: input.review,
+        allowSelfReview: input.allowSelfReview,
+        ...(input.timeoutMinutes !== undefined ? { timeoutMinutes: input.timeoutMinutes } : {}),
+        json: input.json,
+        ...(input.onAmbiguity ? { onAmbiguity: input.onAmbiguity } : {}),
+        ...(input.decisionPolicy ? { decisionPolicy: input.decisionPolicy } : {}),
+        permissions: input.permissions,
+        parallel: input.parallel,
+        routing: input.routing,
+        ...(input.quality !== undefined ? { quality: input.quality } : {}),
+        ...(input.qualityRounds !== undefined ? { qualityRounds: input.qualityRounds } : {}),
+        ...(input.qualityMinutes !== undefined ? { qualityMinutes: input.qualityMinutes } : {}),
+        ...(input.qualityPolicy ? { qualityPolicy: input.qualityPolicy } : {}),
+        ...(input.candidates !== undefined ? { candidates: input.candidates } : {}),
+    });
+}
 export function decisionRequestPath(targetDir) {
     return join(targetDir, '.yoke', 'decision-request.yaml');
 }