@open-agent-toolkit/cli 0.3.15 → 0.3.16

package/dist/commands/gate/index.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { link, mkdir, readdir, readFile, realpath, rmdir, rm, writeFile, } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve, } from 'node:path';
 import { buildCommandContext, } from '../../app/command-context.js';
@@ -46,6 +46,7 @@ const DEFAULT_DEPENDENCIES = {
     processEnv: process.env,
     writeGateRunMarker,
     removeGateRunMarker,
+    isProcessAlive,
     writeGateProjectLogReceipt,
     sleep: async (ms) => {
         await new Promise((settle) => setTimeout(settle, ms));
@@ -92,9 +93,20 @@ const GATE_CHECK_TIMEOUT_MS = 5_000;
 const GATE_EXEC_TIMEOUT_MS = 15 * 60 * 1_000;
 const GATE_LIVENESS_INTERVAL_MS = 30_000;
 const AMBIENT_ACTIVITY_ATTRIBUTION = 'not attributable to this gate child';
+/**
+ * Run markers and duplicate-run claims share one directory. A gate exports it
+ * to its reviewer child as `OAT_GATE_RUN_MARKER_DIR`, so a nested gate finds
+ * its parent's claim even when the child's TMPDIR differs.
+ */
+function gateRunMarkerDir(env) {
+    const exported = env.OAT_GATE_RUN_MARKER_DIR?.trim();
+    return exported && isAbsolute(exported)
+        ? exported
+        : join(tmpdir(), 'oat-gate-runs');
+}
 async function writeGateRunMarker(path, marker, warn) {
     try {
-        await mkdir(join(tmpdir(), 'oat-gate-runs'), { recursive: true });
+        await mkdir(dirname(path), { recursive: true });
         await writeFile(path, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
         return true;
     }
@@ -156,6 +168,171 @@ function warnWhenReceiptIsTracked(path, warn) {
         warn(`Gate project log receipt ${path} is not ignored by git. Add a gate-receipts ignore rule for this projects root, or the receipt will be committed by the next repository-wide add.`);
     }
 }
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to another user.
+        return isErrorCode(error, 'EPERM');
+    }
+}
+function isErrorCode(error, code) {
+    return (!!error &&
+        typeof error === 'object' &&
+        'code' in error &&
+        error.code === code);
+}
+function normalizeGateRunKey(value) {
+    return value?.trim().toLowerCase() ?? '';
+}
+function gateRunClaimPath(dir, identity) {
+    const key = createHash('sha256')
+        .update([
+        identity.projectRoot,
+        normalizeGateRunKey(identity.reviewType),
+        normalizeGateRunKey(identity.reviewScope),
+    ].join('\0'))
+        .digest('hex')
+        .slice(0, 32);
+    return join(dir, `claim-${key}.lock`);
+}
+async function readGateRunClaim(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isErrorCode(error, 'ENOENT')) {
+            return null;
+        }
+        throw error;
+    }
+    let record = null;
+    try {
+        record = rawRecord(JSON.parse(text));
+    }
+    catch {
+        record = null;
+    }
+    const holder = record &&
+        typeof record.runId === 'string' &&
+        typeof record.pid === 'number' &&
+        Number.isInteger(record.pid) &&
+        record.pid > 0
+        ? { runId: record.runId, pid: record.pid, path }
+        : null;
+    return { text, holder };
+}
+/**
+ * Atomically claims the duplicate-run slot for one project root, review type,
+ * and scope. The claim content is written to a private file created with
+ * `wx`, then hard-linked to the shared claim path; `link` fails with EEXIST
+ * when another run holds the slot, so two simultaneous gates can never both
+ * acquire it and a reader never sees a half-written claim. A claim whose
+ * owner is dead, or which cannot be parsed, is replaced once. Destructive
+ * recovery and release share an exclusive mutation directory; recovery reads
+ * ownership again under that guard before removing anything. A crashed guard
+ * is deliberately not reclaimed automatically: competing cleanup cannot safely
+ * remove a replacement owner of the guard itself.
+ */
+async function acquireGateRunClaim(input) {
+    await mkdir(input.dir, { recursive: true });
+    const path = gateRunClaimPath(input.dir, input);
+    const content = `${JSON.stringify({
+        runId: input.runId,
+        pid: process.pid,
+        projectRoot: input.projectRoot,
+        reviewType: input.reviewType?.trim() || null,
+        reviewScope: input.reviewScope?.trim() || null,
+        claimedAt: new Date().toISOString(),
+    })}\n`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const draft = join(input.dir, `.claim-${input.runId}.tmp`);
+        await writeFile(draft, content, { encoding: 'utf8', flag: 'wx' });
+        try {
+            await link(draft, path);
+            return { status: 'acquired', path };
+        }
+        catch (error) {
+            if (!isErrorCode(error, 'EEXIST')) {
+                throw error;
+            }
+        }
+        finally {
+            await rm(draft, { force: true });
+        }
+        const existing = await readGateRunClaim(path);
+        if (!existing) {
+            continue; // Released between the link and the read.
+        }
+        if (existing.holder && input.isProcessAlive(existing.holder.pid)) {
+            return { status: 'held', holder: existing.holder };
+        }
+        if (attempt > 0) {
+            break;
+        }
+        const mutationPath = `${path}.mutation`;
+        try {
+            await mkdir(mutationPath);
+        }
+        catch (error) {
+            if (isErrorCode(error, 'EEXIST')) {
+                throw new Error(`Gate claim mutation is in progress at ${mutationPath}. Retry after it finishes; remove this guard only after verifying no gate is still using it.`, { cause: error });
+            }
+            throw error;
+        }
+        try {
+            // A faster recovery may have replaced the stale claim before we took
+            // the guard. Never move the shared path aside to discover its owner.
+            const current = await readGateRunClaim(path);
+            if (current?.holder && input.isProcessAlive(current.holder.pid)) {
+                return { status: 'held', holder: current.holder };
+            }
+            if (current) {
+                await rm(path);
+            }
+        }
+        finally {
+            await rmdir(mutationPath);
+        }
+    }
+    const final = await readGateRunClaim(path);
+    return {
+        status: 'held',
+        holder: final?.holder ?? { runId: 'unknown', pid: 0, path },
+    };
+}
+/** Removes a claim only while it still belongs to this run. */
+async function releaseGateRunClaim(path, runId, warn) {
+    const mutationPath = `${path}.mutation`;
+    try {
+        await mkdir(mutationPath);
+        try {
+            const existing = await readGateRunClaim(path);
+            if (existing?.holder?.runId === runId) {
+                await rm(path);
+            }
+        }
+        finally {
+            await rmdir(mutationPath);
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        warn(`Unable to release gate run claim ${path}: ${detail}`);
+    }
+}
+async function resolveGateProjectRoot(repoRoot, projectPath) {
+    const absolute = resolve(repoRoot, projectPath);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
 async function removeGateRunMarker(path, warn) {
     try {
         await rm(path);
@@ -476,7 +653,8 @@ function resolveGateExecTimeout(input) {
     }
     const scope = input.reviewScope?.trim().toLowerCase() ?? '';
     if (reviewType === 'artifact') {
-        return { timeoutMs: 900_000, source: 'scope-default' };
+        // Artifact and plan reviews read the full surface; they default to 30 minutes.
+        return { timeoutMs: 1_800_000, source: 'scope-default' };
     }
     if (reviewType === 'code') {
         if (/^p\d+-t\d+$/.test(scope)) {
@@ -1523,11 +1701,15 @@ function writeReviewGateResult(context, payload) {
     context.logger.info(payload.handoff);
 }
 function writeReviewGateExecutionFailure(context, payload) {
-    const message = payload.refusal
-        ? `Review did not complete: reviewer refused the headless route (${payload.refusal}).`
-        : payload.timedOut
-            ? `Review did not complete: target ${payload.target} timed out after ${payload.timeoutMs}ms.`
-            : `Review did not complete: target ${payload.target} exited with code ${payload.exitCode}.`;
+    const message = payload.claimFailure
+        ? `Review did not start: duplicate-run exclusion could not be established (${payload.claimFailure}).`
+        : payload.duplicateRun
+            ? `Review did not start: gate run ${payload.duplicateRun.runId} (pid ${payload.duplicateRun.pid}) is already reviewing ${payload.project} (${payload.duplicateRun.reviewType} review, scope ${payload.duplicateRun.scope}). Wait for it to finish, or remove its claim ${payload.duplicateRun.path} if that process is not a gate.`
+            : payload.refusal
+                ? `Review did not complete: reviewer refused the headless route (${payload.refusal}).`
+                : payload.timedOut
+                    ? `Review did not complete: target ${payload.target} timed out after ${payload.timeoutMs}ms.`
+                    : `Review did not complete: target ${payload.target} exited with code ${payload.exitCode}.`;
     if (context.json) {
         context.logger.json({
             status: 'review_failed',
@@ -1556,6 +1738,7 @@ function writeReviewGateExecutionFailure(context, payload) {
             ...(payload.activityEvidence
                 ? { activityEvidence: payload.activityEvidence }
                 : {}),
+            ...(payload.recursion ? { recursion: payload.recursion } : {}),
             message,
         });
         return;
@@ -2482,6 +2665,8 @@ async function disposeValidatedReviewArtifact(snapshot, identity, dependencies,
 }
 async function runReviewGate(prompt, options, context, dependencies) {
     const runId = randomUUID();
+    let recursion;
+    let runClaimPath;
     let runMarkerPath;
     let runMarkerWritten = false;
     let branchLocalGateCli;
@@ -2525,6 +2710,71 @@ async function runReviewGate(prompt, options, context, dependencies) {
             rawPersisted,
         });
         const dispatchReport = buildGateDispatchReport(gateInvocation, options.reviewScope?.trim() || 'gate-review');
+        // Claim the project, review type, and scope atomically before anything is
+        // launched or logged, so a second live gate (a reviewer that launches its
+        // own gate, or two simultaneous launches) is rejected.
+        const runMarkerDir = gateRunMarkerDir(dependencies.processEnv);
+        const projectRoot = await resolveGateProjectRoot(repoRoot, projectPath);
+        let duplicateRun = null;
+        let claimFailure;
+        try {
+            const claim = await acquireGateRunClaim({
+                dir: runMarkerDir,
+                projectRoot,
+                reviewType: options.reviewType,
+                reviewScope: options.reviewScope,
+                runId,
+                isProcessAlive: dependencies.isProcessAlive,
+            });
+            if (claim.status === 'acquired') {
+                runClaimPath = claim.path;
+                recursion = { decision: 'none' };
+            }
+            else {
+                duplicateRun = claim.holder;
+                recursion = { decision: 'rejected', matchedRunId: claim.holder.runId };
+            }
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            context.logger.warn(`Unable to claim this gate run in ${runMarkerDir}: ${detail}; review will not start.`);
+            recursion = { decision: 'unchecked' };
+            claimFailure = detail;
+        }
+        if (context.json) {
+            dependencies.writeDiagnostic(`${JSON.stringify({
+                type: 'gate-recursion',
+                runId,
+                ...recursion,
+                ...(duplicateRun
+                    ? { matchedPid: duplicateRun.pid, claimPath: duplicateRun.path }
+                    : {}),
+            })}\n`);
+        }
+        if (duplicateRun || claimFailure) {
+            writeReviewGateExecutionFailure(context, {
+                runId,
+                target: selected.id,
+                project: projectPath,
+                projectResolutionSource: reviewProject.source,
+                exitCode: 1,
+                ...(duplicateRun
+                    ? {
+                        duplicateRun: {
+                            ...duplicateRun,
+                            reviewType: options.reviewType?.trim() || 'untyped',
+                            scope: options.reviewScope?.trim() || 'none',
+                        },
+                    }
+                    : {}),
+                claimFailure,
+                gateInvocation,
+                dispatchReport,
+                recursion,
+            });
+            process.exitCode = 1;
+            return;
+        }
         postSelectionContext = {
             project: projectPath,
             projectResolutionSource: reviewProject.source,
@@ -2575,7 +2825,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 : []),
             prompt.join(' '),
         ]);
-        runMarkerPath = join(tmpdir(), 'oat-gate-runs', `${runId}.json`);
+        runMarkerPath = join(runMarkerDir, `${runId}.json`);
         runMarkerWritten = await dependencies.writeGateRunMarker(runMarkerPath, {
             runId,
             targetId: selected.id,
@@ -2583,6 +2833,8 @@ async function runReviewGate(prompt, options, context, dependencies) {
             reviewType: options.reviewType?.trim() || null,
             reviewScope: options.reviewScope?.trim() || null,
             project: projectPath,
+            projectRoot,
+            pid: process.pid,
             startedAt: new Date().toISOString(),
             budgetMs: timeout.timeoutMs,
             budgetSource: timeout.source,
@@ -2615,6 +2867,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 OAT_GATE_CLI_PATH: branchLocalGateCli.cliPath,
                 OAT_GATE_CLI_ROOT: branchLocalGateCli.cliRoot,
                 OAT_GATE_ROUTE_RECEIPT_PATH: branchLocalGateCli.routeReceiptPath,
+                OAT_GATE_RUN_MARKER_DIR: runMarkerDir,
             },
         }, timeout);
         const routeReceipt = await dependencies.readGateRouteReceipt(branchLocalGateCli.routeReceiptPath, branchLocalGateCli.cliRoot, selected.target.runtime);
@@ -2648,6 +2901,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                     : {}),
                 gateInvocation,
                 dispatchReport,
+                recursion,
             });
             process.exitCode = 1;
             return true;
@@ -2693,6 +2947,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                     : {}),
                 gateInvocation,
                 dispatchReport,
+                recursion,
             });
             process.exitCode = childExitCode;
             return;
@@ -2719,6 +2974,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                     : {}),
                 gateInvocation,
                 dispatchReport,
+                recursion,
             });
             process.exitCode = childExitCode;
             return;
@@ -2850,6 +3106,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
             dispatchReport,
             corroboration,
             ...(childResult.timedOut ? { lateCompletion: true } : {}),
+            recursion,
         });
         // Record the disposition only once the envelope is written, so a failed
         // emission cannot leave the log claiming a result no caller received.
@@ -2939,6 +3196,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                                 ? { lateCompletion: true }
                                 : {}),
                             postSelectionRecovery: true,
+                            recursion,
                         });
                         buffered.flush();
                         recoveryEmitted = true;
@@ -2994,6 +3252,9 @@ async function runReviewGate(prompt, options, context, dependencies) {
             if (runMarkerPath) {
                 await dependencies.removeGateRunMarker(runMarkerPath, (message) => context.logger.warn(message));
             }
+            if (runClaimPath) {
+                await releaseGateRunClaim(runClaimPath, runId, (message) => context.logger.warn(message));
+            }
         }
         finally {
             if (projectLogFinalization && !projectLogFinalized) {

package/dist/commands/shared/frontmatter.d.ts

@@ -1,6 +1,6 @@
 export declare const PROJECT_STATE_KINDS: readonly ['implementation', 'coordination'];
 export declare const PROJECT_STATE_PHASES: readonly ['discovery', 'spec', 'design', 'plan', 'implement', 'decomposition'];
-export declare const PROJECT_STATE_FRONTMATTER_FIELDS: readonly ['oat_kind', 'oat_parent', 'oat_siblings', 'oat_depends_on', 'oat_children', 'oat_inherited_context_revalidated', 'oat_phase', 'oat_phase_status', 'oat_status', 'oat_workflow_mode', 'oat_lifecycle', 'oat_current_task', 'oat_last_commit', 'oat_blockers', 'oat_hill_checkpoints', 'oat_hill_completed', 'oat_parallel_execution', 'oat_implement_exit_gate', 'oat_skill_gate_overrides', 'oat_pr_status', 'oat_pr_url', 'oat_project_created', 'oat_project_completed', 'oat_project_state_updated', 'oat_docs_updated', 'oat_generated', 'oat_template', 'oat_template_name'];
+export declare const PROJECT_STATE_FRONTMATTER_FIELDS: readonly ['oat_kind', 'oat_parent', 'oat_siblings', 'oat_depends_on', 'oat_children', 'oat_inherited_context_revalidated', 'oat_phase', 'oat_phase_status', 'oat_status', 'oat_workflow_mode', 'oat_lifecycle', 'oat_current_task', 'oat_last_commit', 'oat_blockers', 'oat_hill_checkpoints', 'oat_hill_completed', 'oat_parallel_execution', 'oat_implement_exit_gate', 'oat_quick_start_gate', 'oat_skill_gate_overrides', 'oat_pr_status', 'oat_pr_url', 'oat_project_created', 'oat_project_completed', 'oat_project_state_updated', 'oat_docs_updated', 'oat_generated', 'oat_template', 'oat_template_name'];
 export type ProjectStateKind = (typeof PROJECT_STATE_KINDS)[number];
 export type ProjectStatePhase = (typeof PROJECT_STATE_PHASES)[number];
 export type ProjectStateFrontmatterField = (typeof PROJECT_STATE_FRONTMATTER_FIELDS)[number];

package/dist/commands/shared/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/commands/shared/frontmatter.js

@@ -29,6 +29,7 @@ export const PROJECT_STATE_FRONTMATTER_FIELDS = [
     'oat_hill_completed',
     'oat_parallel_execution',
     'oat_implement_exit_gate',
+    'oat_quick_start_gate',
     'oat_skill_gate_overrides',
     'oat_pr_status',
     'oat_pr_url',

package/dist/commands/state/generate.d.ts

@@ -18,6 +18,6 @@ export interface GenerateStateResult {
     recommendedStep: string;
     recommendedReason: string;
 }
-export declare function phaseInHillList(phase: string, listStr: string): boolean;
+export declare function phaseInHillList(phase: string, list: string | readonly string[]): boolean;
 export declare function generateStateDashboard(options: GenerateStateOptions): Promise<GenerateStateResult>;
 //# sourceMappingURL=generate.d.ts.map

package/dist/commands/state/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAU9E,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAkHD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvE;AAgiBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAkF9B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAmB9E,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA0ID,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAC/B,OAAO,CAET;AAomBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAkF9B"}

package/dist/commands/state/generate.js

@@ -1,16 +1,18 @@
 import { execSync } from 'node:child_process';
-import { readdir, writeFile } from 'node:fs/promises';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 import { classifyLegacySyncedRecord, probeAuthoritativeCompletedRef, } from '../project/list.js';
 import { defaultGitRunner } from '../project/sync/git.js';
 import { listSyncedRecords } from '../project/sync/record.js';
 import { buildSyncTarget } from '../project/sync/ref-sync.js';
 import { probeSyncedTerminalRefs } from '../project/sync/resolve-target.js';
-import { parseFrontmatterField } from '../shared/frontmatter.js';
+import { getFrontmatterBlock, parseFrontmatterField, } from '../shared/frontmatter.js';
 import { resolveProjectsRoot } from '../shared/oat-paths.js';
 import { resolveScopeRoot } from '../shared/project-scope.js';
 import { readOatLocalConfig } from '../../config/oat-config.js';
 import { ensureDir, fileExists } from '../../fs/io.js';
+import { evaluateQuickPlanReadiness, quickPlanNotReadyReason, } from '@open-agent-toolkit/control-plane';
+import YAML from 'yaml';
 const defaultGit = {
     isGitRepo(root) {
         try {
@@ -81,8 +83,53 @@ async function readActiveProject(repoRoot) {
     result.status = 'active';
     return result;
 }
-export function phaseInHillList(phase, listStr) {
-    return listStr.includes(`"${phase}"`);
+/**
+ * Reads a HiLL phase list in any YAML form the router's parsed state accepts:
+ * a parsed array, or flow text with double, single, or no quotes.
+ */
+function toPhaseList(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item).trim()).filter(Boolean);
+    }
+    if (typeof value !== 'string')
+        return [];
+    return value
+        .trim()
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((item) => item
+        .trim()
+        .replace(/^(["'])(.*)\1$/, '$2')
+        .trim())
+        .filter(Boolean);
+}
+export function phaseInHillList(phase, list) {
+    return toPhaseList(list).includes(phase);
+}
+/**
+ * Parses the HiLL lists from the state frontmatter as YAML, so block arrays
+ * are read whole (a line-oriented field read sees only the first item). A
+ * frontmatter block that is not valid YAML falls back to the textual lists.
+ */
+async function readHillLists(stateFile) {
+    try {
+        const block = getFrontmatterBlock(await readFile(stateFile, 'utf8'));
+        const parsed = block ? YAML.parse(block) : null;
+        if (parsed && typeof parsed === 'object') {
+            const record = parsed;
+            return {
+                checkpoints: toPhaseList(record.oat_hill_checkpoints),
+                completed: toPhaseList(record.oat_hill_completed),
+            };
+        }
+    }
+    catch {
+        // Fall through to the textual read.
+    }
+    return {
+        checkpoints: toPhaseList(await parseFrontmatterField(stateFile, 'oat_hill_checkpoints')),
+        completed: toPhaseList(await parseFrontmatterField(stateFile, 'oat_hill_completed')),
+    };
 }
 async function readProjectState(repoRoot, projectPath) {
     const stateFile = join(repoRoot, projectPath, 'state.md');
@@ -101,12 +148,14 @@ async function readProjectState(repoRoot, projectPath) {
         ? await parseFrontmatterField(stateFile, 'oat_pause_reason')
         : '';
     const blockers = (await parseFrontmatterField(stateFile, 'oat_blockers')) || '[]';
-    const hillCheckpoints = (await parseFrontmatterField(stateFile, 'oat_hill_checkpoints')) || '[]';
-    const hillCompleted = (await parseFrontmatterField(stateFile, 'oat_hill_completed')) || '[]';
+    const { checkpoints: hillCheckpoints, completed: hillCompleted } = await readHillLists(stateFile);
     const workflowMode = (await parseFrontmatterField(stateFile, 'oat_workflow_mode')) ||
         'spec-driven';
     const docsUpdatedRaw = await parseFrontmatterField(stateFile, 'oat_docs_updated');
     const docsUpdated = docsUpdatedRaw && docsUpdatedRaw !== 'null' ? docsUpdatedRaw : '';
+    const quickPlanReadiness = workflowMode === 'quick' && phase === 'plan'
+        ? evaluateQuickPlanReadiness(await readOptionalFile(join(repoRoot, projectPath, 'plan.md')))
+        : null;
     let hillStatus;
     if (phaseInHillList(phase, hillCheckpoints)) {
         hillStatus = phaseInHillList(phase, hillCompleted) ? 'passed' : 'pending';
@@ -128,8 +177,19 @@ async function readProjectState(repoRoot, projectPath) {
         hillStatus,
         workflowMode,
         docsUpdated,
+        quickPlanReadiness,
     };
 }
+async function readOptionalFile(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
 async function readKnowledgeStatus(repoRoot) {
     const indexFile = join(repoRoot, '.oat', 'repo', 'knowledge', 'project-index.md');
     const result = {
@@ -212,8 +272,10 @@ function computeNextStep(project, hasProjects, state) {
             reason: 'Project is paused — open to resume',
         };
     }
-    // HiLL checkpoint gating
-    if (state.phaseStatus === 'complete' &&
+    // HiLL checkpoint gating. A quick plan phase checks a pending checkpoint at
+    // any status before quick plan readiness, as the control-plane router does.
+    const quickPlanPhase = state.workflowMode === 'quick' && state.phase === 'plan';
+    if ((state.phaseStatus === 'complete' || quickPlanPhase) &&
         phaseInHillList(state.phase, state.hillCheckpoints) &&
         !phaseInHillList(state.phase, state.hillCompleted)) {
         // Spec is no longer a discrete HiLL checkpoint in newly-scaffolded projects —
@@ -242,6 +304,23 @@ function computeNextStep(project, hasProjects, state) {
             reason: 'Continue the promoted quick workflow',
         };
     }
+    // A quick plan phase routes by quick plan readiness at every status, as the
+    // control-plane router does: a plan that is not ready resumes quick-start in
+    // place, and a ready plan goes to implementation (readiness implies a
+    // complete plan whose `oat_ready_for` names it, so the router gives the
+    // explicit-pointer reason). The shared `plan:*` routes below serve the other
+    // modes. generate.test.ts pins parity with `recommendSkill`.
+    if (quickPlanPhase && state.quickPlanReadiness) {
+        return state.quickPlanReadiness.ready
+            ? {
+                step: 'oat-project-implement',
+                reason: 'Current artifact is complete and explicitly points to the next skill',
+            }
+            : {
+                step: 'oat-project-quick-start',
+                reason: quickPlanNotReadyReason(state.quickPlanReadiness),
+            };
+    }
     // Workflow mode routing
     const key = `${state.workflowMode}:${state.phase}:${state.phaseStatus}`;
     const routeMap = {

package/dist/commands/sync/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/apply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAoB3D,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EAExB,MAAM,cAAc,CAAC;AAwYtB,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,aAAa,EAAE,EAC3B,YAAY,EAAE,uBAAuB,GACpC,OAAO,CAAC,IAAI,CAAC,CA0Mf"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/apply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAoB3D,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EAExB,MAAM,cAAc,CAAC;AAwatB,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,aAAa,EAAE,EAC3B,YAAY,EAAE,uBAAuB,GACpC,OAAO,CAAC,IAAI,CAAC,CAiNf"}