@hecer/yoke 0.9.0 → 1.1.0

package/dist/loop/git.js

@@ -1,16 +1,22 @@
 import { execFileSync } from 'node:child_process';
+import { sanitizeCommitMessage } from './identity.js';
 export const realGitOps = {
     isClean(dir) {
         const out = execFileSync('git', ['status', '--porcelain'], { cwd: dir }).toString();
         return out.trim() === '';
     },
-    commitAll(dir, message) {
+    commitAll(dir, message, identity) {
         execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'pipe' });
         const status = execFileSync('git', ['status', '--porcelain'], { cwd: dir }).toString().trim();
         if (status === '') {
             throw new Error('nothing to commit after agent run');
         }
-        execFileSync('git', ['-c', 'commit.gpgsign=false', 'commit', '-m', message], { cwd: dir, stdio: 'pipe' });
+        const identityArgs = identity
+            ? ['-c', `user.name=${identity.authorName}`, '-c', `user.email=${identity.authorEmail}`]
+            : [];
+        const authorArgs = identity ? ['--author', `${identity.authorName} <${identity.authorEmail}>`] : [];
+        const cleanMessage = sanitizeCommitMessage(message, identity?.allowCoAuthors ?? false);
+        execFileSync('git', [...identityArgs, '-c', 'commit.gpgsign=false', 'commit', ...authorArgs, '-m', cleanMessage], { cwd: dir, stdio: 'pipe' });
     },
     addWorktree(repoDir, worktreePath) {
         execFileSync('git', ['worktree', 'add', '--detach', worktreePath, 'HEAD'], { cwd: repoDir, stdio: 'pipe' });
@@ -23,3 +29,26 @@ export const realGitOps = {
         execFileSync('git', ['merge', '--ff-only', sha], { cwd: repoDir, stdio: 'pipe' });
     },
 };
+export function commitPaths(dir, paths, message, identity) {
+    if (paths.length === 0)
+        throw new Error('no commit paths supplied');
+    const identityArgs = identity
+        ? ['-c', `user.name=${identity.authorName}`, '-c', `user.email=${identity.authorEmail}`]
+        : [];
+    const authorArgs = identity ? ['--author', `${identity.authorName} <${identity.authorEmail}>`] : [];
+    const cleanMessage = sanitizeCommitMessage(message, identity?.allowCoAuthors ?? false);
+    execFileSync('git', ['add', '--', ...paths], { cwd: dir, stdio: 'pipe' });
+    try {
+        const staged = execFileSync('git', ['diff', '--cached', '--name-only', '--', ...paths], { cwd: dir, stdio: 'pipe' }).toString().trim();
+        if (!staged)
+            throw new Error('nothing to commit for selected paths');
+        execFileSync('git', [...identityArgs, '-c', 'commit.gpgsign=false', 'commit', '--only', ...authorArgs, '-m', cleanMessage, '--', ...paths], { cwd: dir, stdio: 'pipe' });
+    }
+    catch (error) {
+        try {
+            execFileSync('git', ['reset', '--quiet', '--', ...paths], { cwd: dir, stdio: 'pipe' });
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}

package/dist/loop/identity.js

@@ -0,0 +1,27 @@
+import { execFileSync } from 'node:child_process';
+const readGitConfig = (key, targetDir) => {
+    try {
+        return execFileSync('git', ['config', '--get', key], { cwd: targetDir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return '';
+    }
+};
+export function resolveCommitIdentity(targetDir, config, gitConfig = readGitConfig) {
+    const authorName = config?.authorName?.trim() || gitConfig('user.name', targetDir).trim();
+    const authorEmail = config?.authorEmail?.trim() || gitConfig('user.email', targetDir).trim();
+    if (!authorName)
+        throw new Error('Commit author name is missing. Set commit.authorName in .yoke/config.yaml or git config user.name.');
+    if (!authorEmail)
+        throw new Error('Commit author email is missing. Set commit.authorEmail in .yoke/config.yaml or git config user.email.');
+    return { authorName, authorEmail, allowCoAuthors: config?.allowCoAuthors ?? false };
+}
+export function sanitizeCommitMessage(message, allowCoAuthors) {
+    if (allowCoAuthors)
+        return message;
+    return message
+        .split(/\r?\n/)
+        .filter(line => !/^Co-Authored-By:/i.test(line.trim()))
+        .join('\n')
+        .trim();
+}

package/dist/loop/lock.js

@@ -1,8 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
 export function lockPath(targetDir) {
     return join(targetDir, '.yoke', 'loop.lock');
 }
+export function takeoverLockPath(targetDir) {
+    return join(targetDir, '.yoke', 'loop.lock.takeover');
+}
+export function takeoverRecoveryPath(targetDir) {
+    return join(targetDir, '.yoke', 'loop.lock.takeover.recovery');
+}
 // Liveness probe via signal 0. EPERM means "exists but not ours" — alive.
 export function isPidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -15,8 +22,7 @@ export function isPidAlive(pid) {
         return e.code === 'EPERM';
     }
 }
-export function readLock(targetDir) {
-    const file = lockPath(targetDir);
+function readLockFile(file) {
     if (!existsSync(file))
         return null;
     try {
@@ -27,19 +33,104 @@ export function readLock(targetDir) {
         return null;
     }
 }
+export function readLock(targetDir) {
+    return readLockFile(lockPath(targetDir));
+}
+// Publish complete metadata in one atomic namespace operation. Unlike open('wx')
+// followed by write(), contenders can never observe an empty/partial lock file.
+function publishLock(file, info) {
+    const temp = `${file}.${info.ownerToken ?? randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify(info), { flag: 'wx' });
+    try {
+        linkSync(temp, file);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EEXIST')
+            return false;
+        if (code === 'EPERM' || code === 'ENOTSUP' || code === 'EXDEV' || code === 'EACCES') {
+            throw new Error(`Yoke cannot publish an atomic loop lock on this filesystem (${code}). Move the project to a filesystem with hard-link support.`);
+        }
+        throw error;
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+function releaseLockFile(file, ownerToken) {
+    if (!ownerToken)
+        return;
+    try {
+        if (readLockFile(file)?.ownerToken === ownerToken)
+            rmSync(file, { force: true });
+    }
+    catch { /* best-effort */ }
+}
+export function acquireTakeoverLease(targetDir, pid = process.pid) {
+    const file = takeoverLockPath(targetDir);
+    mkdirSync(dirname(file), { recursive: true });
+    if (existsSync(takeoverRecoveryPath(targetDir))) {
+        return { acquired: false, holderPid: readLockFile(takeoverRecoveryPath(targetDir))?.pid };
+    }
+    const ownerToken = randomUUID();
+    const lease = { pid, startedAt: new Date().toISOString(), ownerToken };
+    return publishLock(file, lease)
+        ? { acquired: true, ownerToken }
+        : { acquired: false, holderPid: readLockFile(file)?.pid };
+}
+export function releaseTakeoverLease(targetDir, ownerToken) {
+    releaseLockFile(takeoverLockPath(targetDir), ownerToken);
+}
+export function acquireTakeoverRecoveryLease(targetDir, pid = process.pid) {
+    const file = takeoverRecoveryPath(targetDir);
+    mkdirSync(dirname(file), { recursive: true });
+    const ownerToken = randomUUID();
+    const lease = { pid, startedAt: new Date().toISOString(), ownerToken };
+    return publishLock(file, lease)
+        ? { acquired: true, ownerToken }
+        : { acquired: false, holderPid: readLockFile(file)?.pid };
+}
+export function releaseTakeoverRecoveryLease(targetDir, ownerToken) {
+    releaseLockFile(takeoverRecoveryPath(targetDir), ownerToken);
+}
 export function acquireLock(targetDir, pid = process.pid) {
     const file = lockPath(targetDir);
-    const holder = readLock(targetDir);
-    if (holder && isPidAlive(holder.pid))
-        return { acquired: false, holderPid: holder.pid };
+    const takeoverFile = takeoverLockPath(targetDir);
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify({ pid, startedAt: new Date().toISOString() }));
-    return holder ? { acquired: true, stalePid: holder.pid } : { acquired: true };
-}
-// Best-effort: a missing file or an unwritable disk must never crash loop teardown.
-export function releaseLock(targetDir) {
+    const ownerToken = randomUUID();
+    const candidate = { pid, startedAt: new Date().toISOString(), ownerToken };
+    // A stale-lock owner is currently being revalidated. Joining that race would
+    // let a late contender publish between removal and replacement.
+    const recoveryFile = takeoverRecoveryPath(targetDir);
+    if (existsSync(takeoverFile) || existsSync(recoveryFile)) {
+        return { acquired: false, holderPid: readLockFile(takeoverFile)?.pid ?? readLockFile(recoveryFile)?.pid };
+    }
+    if (publishLock(file, candidate))
+        return { acquired: true, ownerToken };
+    const observed = readLock(targetDir);
+    if (observed && isPidAlive(observed.pid))
+        return { acquired: false, holderPid: observed.pid };
+    // Serialize stale takeover with a second, atomically published lease. A
+    // crashed takeover lease is deliberately recovered by `yoke loop cleanup`;
+    // guessing here would recreate the same TOCTOU race one level deeper.
+    const takeover = acquireTakeoverLease(targetDir, pid);
+    if (!takeover.acquired)
+        return { ...takeover, stalePid: observed?.pid };
     try {
-        rmSync(lockPath(targetDir), { force: true });
+        const current = readLock(targetDir);
+        if (current && isPidAlive(current.pid))
+            return { acquired: false, holderPid: current.pid, stalePid: observed?.pid };
+        rmSync(file, { force: true });
+        if (publishLock(file, candidate))
+            return { acquired: true, stalePid: current?.pid ?? observed?.pid, ownerToken };
+        return { acquired: false, holderPid: readLock(targetDir)?.pid, stalePid: current?.pid ?? observed?.pid };
     }
-    catch { /* best-effort */ }
+    finally {
+        releaseTakeoverLease(targetDir, takeover.ownerToken);
+    }
+}
+// Best-effort and ownership-checked: teardown never deletes a successor's lock.
+export function releaseLock(targetDir, ownerToken) {
+    releaseLockFile(lockPath(targetDir), ownerToken);
 }

package/dist/loop/loop.js

@@ -4,6 +4,7 @@ import { loadPrd, savePrd, selectNextStory, allPass, progress } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
 import { appendDecision, contextDir } from '../context/context.js';
 import { noopReporter } from './reporter.js';
+import { consumeDecisionRequest } from './decision.js';
 function blockReason(base, targetDir, git) {
     let dirty = false;
     try {
@@ -112,6 +113,20 @@ export function runLoop(opts) {
                 iterations++;
                 if (result.tokens)
                     reporter.addTokens(result.tokens);
+                let decision;
+                try {
+                    decision = consumeDecisionRequest(wt, opts.targetDir, story.id);
+                }
+                catch (error) {
+                    const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
+                if (decision) {
+                    const reason = `critical decision required for story ${story.id}: ${decision.question}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
                 const ambiguity = consumeAmbiguity(wt);
                 if (ambiguity) {
                     const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
@@ -139,6 +154,15 @@ export function runLoop(opts) {
                         return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                     }
                 }
+                if (opts.audit) {
+                    reporter.phase('audit');
+                    const auditVerdict = runGate(opts.audit, wt, story.id);
+                    if (!auditVerdict.passed) {
+                        const reason = blockReason(`story ${story.id} failed security audit: ${auditVerdict.summary}`, opts.targetDir, opts.git);
+                        reporter.blocked(reason);
+                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    }
+                }
                 const summary = result.success
                     ? result.summary
                     : `${result.summary} (runner exited non-zero but verify is green)`;
@@ -162,7 +186,7 @@ export function runLoop(opts) {
                 });
                 const updated = stories.map(s => (s.id === story.id ? { ...s, passes: true } : s));
                 savePrd(wtPrd, updated);
-                opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`);
+                opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
                 opts.git.integrate(opts.targetDir, wt);
                 landed = progress(updated);
             }
@@ -185,6 +209,20 @@ export function runLoop(opts) {
         iterations++;
         if (result.tokens)
             reporter.addTokens(result.tokens);
+        let decision;
+        try {
+            decision = consumeDecisionRequest(opts.targetDir, opts.targetDir, story.id);
+        }
+        catch (error) {
+            const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
+        if (decision) {
+            const reason = `critical decision required for story ${story.id}: ${decision.question}`;
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
         const ambiguity = consumeAmbiguity(opts.targetDir);
         if (ambiguity) {
             const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
@@ -217,6 +255,15 @@ export function runLoop(opts) {
                 return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
             }
         }
+        if (opts.audit) {
+            reporter.phase('audit');
+            const auditVerdict = runGate(opts.audit, opts.targetDir, story.id);
+            if (!auditVerdict.passed) {
+                const reason = blockReason(`story ${story.id} failed security audit: ${auditVerdict.summary}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+        }
         const summary = result.success
             ? result.summary
             : `${result.summary} (runner exited non-zero but verify is green)`;
@@ -247,7 +294,7 @@ export function runLoop(opts) {
         const updated = onDisk.map(s => (s.id === story.id ? { ...s, passes: true } : s));
         savePrd(opts.prdPath, updated);
         try {
-            opts.git.commitAll(opts.targetDir, `yoke: complete ${story.id} ${story.title}`);
+            opts.git.commitAll(opts.targetDir, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
         }
         catch (e) {
             savePrd(opts.prdPath, onDisk); // revert — never persist passes:true without a commit

package/dist/loop/merge-queue.js

@@ -0,0 +1,20 @@
+export class MergeQueue {
+    tail = Promise.resolve();
+    enqueue(job) {
+        const run = async () => {
+            try {
+                await job.rebase();
+                if (!await job.verify())
+                    return { storyId: job.storyId, integrated: false, reason: 'integrated-tree verification failed' };
+                await job.integrate();
+                return { storyId: job.storyId, integrated: true };
+            }
+            catch (error) {
+                return { storyId: job.storyId, integrated: false, reason: error.message };
+            }
+        };
+        const result = this.tail.then(run, run);
+        this.tail = result.then(() => undefined);
+        return result;
+    }
+}

package/dist/loop/parallel.js

@@ -0,0 +1,39 @@
+import { readyStories } from './scheduler.js';
+export async function runParallelLoop(stories, opts) {
+    const completed = [];
+    const failed = [];
+    const activeAreas = new Set();
+    const active = new Map();
+    let iterations = 0;
+    let agentIndex = 0;
+    const launch = (story) => {
+        iterations++;
+        if (story.area)
+            activeAreas.add(story.area);
+        const affinity = story.agent ?? (opts.agents?.length ? opts.agents[agentIndex++ % opts.agents.length] : undefined);
+        const promise = opts.worker(story, affinity).then(result => {
+            if (result.success) {
+                story.passes = true;
+                completed.push(story.id);
+            }
+            else
+                failed.push(story.id);
+        }).catch(() => { failed.push(story.id); }).finally(() => {
+            active.delete(story.id);
+            if (story.area)
+                activeAreas.delete(story.area);
+        });
+        active.set(story.id, promise);
+    };
+    while (iterations < opts.maxIterations && !opts.paused?.()) {
+        const slots = Math.max(0, opts.maxConcurrency - active.size);
+        const ready = readyStories(stories, { activeAreas }).filter(s => !active.has(s.id) && !failed.includes(s.id)).slice(0, slots);
+        for (const story of ready)
+            launch(story);
+        if (active.size === 0)
+            break;
+        await Promise.race(active.values());
+    }
+    await Promise.all(active.values());
+    return { completed, failed, iterations, paused: opts.paused?.() ?? false };
+}

package/dist/loop/prd.js

@@ -7,20 +7,66 @@ export const StorySchema = z.object({
     priority: z.number(),
     acceptance: z.array(z.string().min(1)),
     passes: z.boolean(),
+    needs: z.array(z.string().min(1)).optional(),
+    area: z.string().min(1).optional(),
+    agent: z.enum(['claude', 'codex', 'gemini']).optional(),
 });
 const PrdSchema = z.array(StorySchema);
 export function loadPrd(file) {
-    return PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+    const stories = PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+    const issues = validateDependencies(stories);
+    if (issues.length)
+        throw new Error(`Invalid PRD dependency graph:\n${issues.join('\n')}`);
+    return stories;
 }
 export function savePrd(file, stories) {
     writeFileSync(file, stringify(stories));
 }
 export function selectNextStory(stories) {
-    const open = stories.filter(s => !s.passes);
+    const passed = new Set(stories.filter(s => s.passes).map(s => s.id));
+    const open = stories.filter(s => !s.passes && (s.needs ?? []).every(id => passed.has(id)));
     if (open.length === 0)
         return null;
     return open.reduce((best, s) => (s.priority < best.priority ? s : best));
 }
+export function validateDependencies(stories) {
+    const issues = [];
+    const counts = new Map();
+    for (const story of stories)
+        counts.set(story.id, (counts.get(story.id) ?? 0) + 1);
+    for (const [id, count] of counts)
+        if (count > 1)
+            issues.push(`duplicate story id: ${id}`);
+    const ids = new Set(stories.map(s => s.id));
+    for (const story of stories) {
+        for (const need of story.needs ?? []) {
+            if (need === story.id)
+                issues.push(`story ${story.id} depends on itself`);
+            else if (!ids.has(need))
+                issues.push(`story ${story.id} has unknown dependency ${need}`);
+        }
+    }
+    const byId = new Map(stories.map(s => [s.id, s]));
+    const visiting = new Set();
+    const visited = new Set();
+    const walk = (id, path) => {
+        if (visiting.has(id)) {
+            issues.push(`dependency cycle: ${[...path, id].join(' -> ')}`);
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const need of byId.get(id)?.needs ?? [])
+            if (byId.has(need) && need !== id)
+                walk(need, [...path, id]);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const id of byId.keys())
+        walk(id, []);
+    return [...new Set(issues)];
+}
 export function allPass(stories) {
     return stories.length > 0 && stories.every(s => s.passes);
 }

package/dist/loop/run-command.js

@@ -9,6 +9,10 @@ import { commandVerifier, retryingVerifier } from './verify.js';
 import { readStatus, makeReporter, fmtDuration } from './reporter.js';
 import { acquireLock, releaseLock } from './lock.js';
 import { maybeAutoUpgrade } from '../update/upgrade.js';
+import { resolveCommitIdentity } from './identity.js';
+import { runAudit } from '../audit/command.js';
+import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
+import { clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -30,7 +34,7 @@ export function prdPath(targetDir) {
 export function setLoopEnabled(targetDir, enabled) {
     // TODO(C2): resolve bundled canon version instead of placeholder
     const config = loadConfig(targetDir) ?? defaultConfig('0.0.0');
-    config.loop = { enabled };
+    config.loop = { ...config.loop, enabled };
     saveConfig(targetDir, config);
 }
 export function loopStatus(targetDir, now = () => new Date()) {
@@ -66,11 +70,29 @@ export function resolveIdleMs(flagMinutes, configMinutes) {
     return minutes > 0 ? minutes * 60_000 : 0;
 }
 export function runLoopCommand(targetDir, opts) {
+    if ((opts.parallel ?? 1) > 1) {
+        console.error('Parallel CLI workers are not enabled yet. The dependency-aware dispatcher and merge queue are available as APIs; use --parallel=1 for the synchronous provider runner.');
+        return 2;
+    }
     const config = loadConfig(targetDir);
     if (!config?.loop.enabled) {
         console.error('Loop is disabled. Enable it with: yoke loop on');
         return 2;
     }
+    if (decisionProcessingExists(targetDir)) {
+        console.error(`A critical decision answer needs recovery. Run: yoke loop answer ${targetDir} --choice=<id>`);
+        return 1;
+    }
+    try {
+        if (readPendingDecision(targetDir)) {
+            console.error(`${formatPendingDecision(targetDir)}\nAnswer it with: yoke loop answer ${targetDir} --choice=<id>`);
+            return 1;
+        }
+    }
+    catch (error) {
+        console.error(`Invalid pending Yoke decision: ${error.message}`);
+        return 1;
+    }
     const path = prdPath(targetDir);
     if (!existsSync(path)) {
         console.error(`No PRD found at ${path}. Create one (see canon loop/prd.schema.md).`);
@@ -95,8 +117,31 @@ export function runLoopCommand(targetDir, opts) {
     // it started with; a fetched upgrade applies from the next invocation.
     maybeAutoUpgrade(config.update?.auto);
     const available = opts.isAvailable ?? isAgentAvailable;
-    const runnerAgent = opts.agent ?? config.agents[0] ?? 'claude';
+    const runnerAgent = resolveRunnerAgent(config, opts.agent, detectHostAgent());
+    const git = opts.git ?? realGitOps;
+    let commitIdentity = opts.commitIdentity;
+    if (!commitIdentity && !opts.git) {
+        try {
+            commitIdentity = resolveCommitIdentity(targetDir, config.commit);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 2;
+        }
+    }
+    let audit = opts.audit;
+    if (!audit && config.audit?.enabled) {
+        audit = (dir) => {
+            const result = runAudit(dir, { command: config.audit?.command, suppressions: config.audit?.suppressions });
+            return { passed: result.code === 0, summary: result.error ?? (result.findings.map(f => `${f.ruleId} ${f.file}${f.line ? `:${f.line}` : ''}`).join(', ') || 'audit passed') };
+        };
+    }
+    if (commitIdentity) {
+        const announce = opts.json ? console.error : console.log;
+        announce(`Commits: ${commitIdentity.authorName} <${commitIdentity.authorEmail}> · co-authors: ${commitIdentity.allowCoAuthors ? 'allowed' : 'disabled'}`);
+    }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
+    const permissions = opts.permissions ?? config.runner?.permissions ?? 'safe';
     let runner = opts.runner;
     if (!runner) {
         if (!available(runnerAgent)) {
@@ -107,20 +152,41 @@ export function runLoopCommand(targetDir, opts) {
         // runner switches to stream-json so cumulative usage rides on every status.
         runner = makeRunner(runnerAgent, idleMs, {
             tokenReport: opts.json === true,
-            onAmbiguity: opts.onAmbiguity ?? config.loop.onAmbiguity,
+            onAmbiguity: opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto',
             perfCommand: config.perf?.command,
+            permissions,
         });
+        const announce = opts.json ? console.error : console.log;
+        announce(`Runner: ${runnerAgent} · permissions: ${permissions} · cwd: ${targetDir}`);
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {
-        const reviewerAgent = opts.reviewer ?? runnerAgent;
-        if (!available(reviewerAgent)) {
-            console.error(`Reviewer agent CLI "${reviewerAgent}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
+        const reviewerAgent = opts.reviewer ?? ['codex', 'gemini', 'claude'].find(agent => agent !== runnerAgent && available(agent));
+        if (!reviewerAgent) {
+            if (!opts.allowSelfReview) {
+                console.error('No independent reviewer CLI is available. Install or select a second agent, or pass --allow-self-review explicitly.');
+                return 2;
+            }
+        }
+        const resolvedReviewer = reviewerAgent ?? runnerAgent;
+        if (resolvedReviewer === runnerAgent && !opts.allowSelfReview) {
+            console.error(`Reviewer "${resolvedReviewer}" is also the implementer. Pick another agent or pass --allow-self-review explicitly.`);
+            return 2;
+        }
+        if (!available(resolvedReviewer)) {
+            console.error(`Reviewer agent CLI "${resolvedReviewer}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
             return 2;
         }
-        review = makeReviewRunner(reviewerAgent, idleMs);
+        review = makeReviewRunner(resolvedReviewer, idleMs);
+    }
+    let lock;
+    try {
+        lock = acquireLock(targetDir);
+    }
+    catch (error) {
+        console.error(`Cannot acquire the Yoke loop lock: ${error.message}`);
+        return 2;
     }
-    const lock = acquireLock(targetDir);
     if (!lock.acquired) {
         console.error(`Another loop is already running here (pid ${lock.holderPid}). If that is wrong, run: yoke loop cleanup`);
         return 2;
@@ -129,18 +195,58 @@ export function runLoopCommand(targetDir, opts) {
         console.warn(`Took over a stale loop lock (pid ${lock.stalePid} is gone).`);
     }
     try {
+        const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
         const result = runLoop({
             prdPath: path,
             targetDir,
             runner,
-            git: opts.git ?? realGitOps,
+            git,
+            commitIdentity,
             verify,
             perf,
+            audit,
             maxIterations: opts.maxIterations,
-            isolate: opts.isolate ?? false,
+            isolate: (opts.parallel ?? 1) > 1 ? true : (opts.isolate ?? false),
             review,
-            reporter: opts.reporter ?? makeReporter(targetDir, { json: opts.json }),
+            reporter,
         });
+        try {
+            const pendingDecision = readPendingDecision(targetDir);
+            if (pendingDecision) {
+                writeDecisionResume(targetDir, {
+                    version: 1,
+                    storyId: pendingDecision.storyId,
+                    requestId: decisionRequestId(pendingDecision),
+                    answered: false,
+                    maxIterations: opts.maxIterations,
+                    agent: runnerAgent,
+                    isolate: opts.isolate ?? false,
+                    reviewer: opts.reviewer,
+                    review: opts.review === true || opts.reviewRunner !== undefined,
+                    allowSelfReview: opts.allowSelfReview ?? false,
+                    timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes,
+                    json: opts.json ?? false,
+                    onAmbiguity: opts.decisionPolicy
+                        ? undefined
+                        : opts.onAmbiguity === 'resolve' || opts.onAmbiguity === 'abort'
+                            ? opts.onAmbiguity
+                            : (config.loop.decisionPolicy ? undefined : config.loop.onAmbiguity),
+                    decisionPolicy: opts.decisionPolicy
+                        ?? (opts.onAmbiguity
+                            ? (opts.onAmbiguity === 'auto' || opts.onAmbiguity === 'critical' ? opts.onAmbiguity : undefined)
+                            : config.loop.decisionPolicy),
+                    permissions,
+                    parallel: opts.parallel ?? 1,
+                });
+            }
+            else
+                clearDecisionResume(targetDir);
+        }
+        catch (error) {
+            const reason = `could not persist trusted decision resume state: ${error.message}`;
+            reporter.blocked(reason);
+            return 1;
+        }
         // In json mode stdout belongs to the NDJSON stream — route the narrative summary to stderr.
         const say = opts.json ? (line) => console.error(line) : (line) => console.log(line);
         say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
@@ -157,6 +263,6 @@ export function runLoopCommand(targetDir, opts) {
         return 1;
     }
     finally {
-        releaseLock(targetDir);
+        releaseLock(targetDir, lock.ownerToken);
     }
 }