instar 0.28.95 → 0.28.96

package/dist/server/routes.js

@@ -22,6 +22,7 @@ import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { SafeGitExecutor } from '../core/SafeGitExecutor.js';
 import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
+import { validateStageTransition } from '../core/StageTransitionValidator.js';
 const execFile = promisify(execFileCb);
 /**
  * Per-session continue-ceiling (spec § (b) Outcomes).
@@ -74,6 +75,7 @@ async function postVerifyEvidence(projectDir, evidence, pointer) {
 }
 import { ReflectionMetrics } from '../monitoring/ReflectionMetrics.js';
 import { HomeostasisMonitor } from '../monitoring/HomeostasisMonitor.js';
+import { verifyMergedItemsViaGit } from '../core/ProjectRoundExecution.js';
 import { ProcessIntegrity } from '../core/ProcessIntegrity.js';
 import { getOutboundQueueStatus, cleanupDeliveredOutbound, buildAgentList } from '../messaging/GitSyncTransport.js';
 import { verifyAgentToken, getAgentToken } from '../messaging/AgentTokenManager.js';
@@ -494,6 +496,26 @@ function pickFields(obj, fields) {
     }
     return out;
 }
+/** Maps a /projects/:id/next action verb to the suggested skill invocation. */
+function skillCommandForAction(action, projectId, roundIndex) {
+    switch (action) {
+        case 'await-user-approval':
+            return `/project approve ${projectId}`;
+        case 'ack-required':
+            return `/project ack ${projectId}`;
+        case 'resolve-conflict':
+            return `/project resolve-conflict ${projectId}`;
+        case 'accept-partial':
+            return `/project accept-partial ${projectId} ${roundIndex}`;
+        case 'run-spec-converge':
+            return `/spec-converge`;
+        case 'run-drift-check':
+            return `/project drift-check ${projectId} ${roundIndex}`;
+        case 'start-round':
+        default:
+            return `/project run-round ${projectId} ${roundIndex}`;
+    }
+}
 export function createRoutes(ctx) {
     const router = Router();
     // ── PR-REVIEW-HARDENING kill-switch (Phase A) ─────────────────────
@@ -4982,9 +5004,21 @@ export function createRoutes(ctx) {
             return;
         }
         const status = typeof req.query.status === 'string' ? req.query.status : undefined;
-        const items = status
+        // Phase 1b PR 5 — server-side filters added so the dashboard
+        // Initiatives tab can hide project-kind records (rendered in the
+        // separate Projects tab) and any record that's a child of a
+        // project (rendered inside its parent's card).
+        const excludeKind = typeof req.query.excludeKind === 'string' ? req.query.excludeKind : undefined;
+        const excludeParented = req.query.excludeParented === 'true';
+        let items = status
             ? ctx.initiativeTracker.list({ status: status })
             : ctx.initiativeTracker.list();
+        if (excludeKind) {
+            items = items.filter((i) => (i.kind ?? 'task') !== excludeKind);
+        }
+        if (excludeParented) {
+            items = items.filter((i) => !i.parentProjectId);
+        }
         res.json({ items, count: items.length });
     });
     router.get('/initiatives/digest', (_req, res) => {
@@ -5109,7 +5143,7 @@ export function createRoutes(ctx) {
         const items = ctx.initiativeTracker.list({ kind: 'project' });
         res.json({ items, count: items.length });
     });
-    router.get('/projects/:id', (req, res) => {
+    router.get('/projects/:id', async (req, res) => {
         if (!ctx.initiativeTracker) {
             res.status(503).json({ error: 'Initiative tracker not configured' });
             return;
@@ -5124,9 +5158,105 @@ export function createRoutes(ctx) {
             return;
         }
         // Join children that point at this project via parentProjectId.
-        const children = ctx.initiativeTracker
+        let children = ctx.initiativeTracker
             .list()
             .filter((i) => i.parentProjectId === project.id);
+        // Lazy merged-state reconciler — spec § Phase 1.4 lines 256-258.
+        //
+        // GET /projects/:id is documented as "may mutate": when a 'building' child's
+        // mergeCommitOid is no longer ancestor of origin/main, we transition it to
+        // 'regressed' and clear future autoAdvanceAt on its round.
+        //
+        // Selection contract:
+        //   - debounce: skip any child with `ciCheckedAt < 6h ago`
+        //   - cap: at most 3 child-revalidations per GET
+        //   - order: oldest `ciCheckedAt` first (treat undefined as 1970), ties broken
+        //     by `roundIndex` ASC, then `itemId` ASC — no child can starve.
+        //   - opt-out: `?reconcile=false` (or `?reconcile=0`) skips entirely
+        const reconcileFlag = req.query.reconcile;
+        const wantReconcile = reconcileFlag !== 'false' && reconcileFlag !== '0';
+        if (wantReconcile && project.targetRepoPath) {
+            const nowMs = Date.now();
+            const debounceMs = 6 * 60 * 60 * 1000; // 6 hours
+            const roundIndexOf = (childId) => {
+                const rounds = project.rounds ?? [];
+                for (let i = 0; i < rounds.length; i++) {
+                    if ((rounds[i].itemIds ?? []).includes(childId))
+                        return i;
+                }
+                return Number.MAX_SAFE_INTEGER;
+            };
+            const candidates = children
+                .filter((c) => c.pipelineStage === 'building' && typeof c.mergeCommitOid === 'string' && c.mergeCommitOid)
+                .filter((c) => {
+                const t = c.ciCheckedAt ? Date.parse(c.ciCheckedAt) : 0;
+                return !(Number.isFinite(t) && t > 0 && nowMs - t < debounceMs);
+            })
+                .sort((a, b) => {
+                const ta = a.ciCheckedAt ? Date.parse(a.ciCheckedAt) : 0;
+                const tb = b.ciCheckedAt ? Date.parse(b.ciCheckedAt) : 0;
+                if (ta !== tb)
+                    return ta - tb;
+                const ra = roundIndexOf(a.id);
+                const rb = roundIndexOf(b.id);
+                if (ra !== rb)
+                    return ra - rb;
+                return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+            })
+                .slice(0, 3);
+            const candidateIds = candidates.map((c) => c.id);
+            if (candidateIds.length > 0) {
+                let verified = new Set();
+                try {
+                    verified = await verifyMergedItemsViaGit(project.targetRepoPath, candidateIds, ctx.initiativeTracker);
+                }
+                catch {
+                    // git not available, no network, etc. — leave verified empty so we
+                    // still update ciCheckedAt to back off; better than a hot loop.
+                }
+                let touched = false;
+                for (const cand of candidates) {
+                    const child = ctx.initiativeTracker.get(cand.id);
+                    if (!child)
+                        continue;
+                    const isMerged = verified.has(cand.id);
+                    try {
+                        await ctx.initiativeTracker.update(cand.id, {
+                            pipelineStage: isMerged ? 'merged' : 'regressed',
+                            ciCheckedAt: new Date(nowMs).toISOString(),
+                            ifMatch: child.version,
+                        });
+                        touched = true;
+                        if (!isMerged) {
+                            // On regression: clear future autoAdvanceAt on the child's round
+                            // so the next round doesn't auto-fire while this one is broken.
+                            const projAfter = ctx.initiativeTracker.get(project.id);
+                            const rIdx = roundIndexOf(cand.id);
+                            if (projAfter && rIdx < (projAfter.rounds ?? []).length) {
+                                const newRounds = (projAfter.rounds ?? []).map((r, i) => i > rIdx ? { ...r, autoAdvanceAt: undefined } : r);
+                                try {
+                                    await ctx.initiativeTracker.update(project.id, {
+                                        rounds: newRounds,
+                                        ifMatch: projAfter.version,
+                                    });
+                                }
+                                catch {
+                                    // OCC race; next GET will retry.
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // OCC race or validator reject; leave as-is for next GET.
+                    }
+                }
+                if (touched) {
+                    children = ctx.initiativeTracker
+                        .list()
+                        .filter((i) => i.parentProjectId === project.id);
+                }
+            }
+        }
         // Optional field selector: `?fields=id,title,pipelineStage`. Used by
         // the dashboard projects selector (Phase 1.10). Always preserves `id`.
         const fieldsParam = typeof req.query.fields === 'string' ? req.query.fields : '';
@@ -5143,17 +5273,470 @@ export function createRoutes(ctx) {
         }
         res.json({ project, children });
     });
+    // GET /projects/:id/next — structured next-action payload.
+    //
+    // Spec § Phase 1.5 (line 268): returns `{ action, params, estimatedCost?,
+    // skillCommand? }` for the FIRST round whose status is not 'complete'.
+    // Ordering: roundIndex ASC, then pipelineStage ASC, then itemId ASC.
+    //
+    // Action verbs the spec enumerates (a non-exhaustive contract):
+    //   - 'await-user-approval' — first round needs `firstLaunchAckAt`
+    //   - 'ack-required'         — unacknowledgedAdvanceCount >= cap
+    //   - 'resolve-conflict'     — `awaitingReconciliation` non-empty
+    //   - 'accept-partial'       — round is partially-complete
+    //   - 'run-spec-converge'    — at least one item is `spec-drafted`
+    //   - 'run-drift-check'      — at least one item is `approved`, no fresh
+    //                              drift verdict
+    //   - 'start-round'          — all preconditions met, ready to fire
+    //
+    // The endpoint does NOT run the runner's preflight — that's a heavier
+    // check at fire time. The action is a hint for the dashboard + skill UI.
     router.get('/projects/:id/next', (req, res) => {
+        if (!ctx.initiativeTracker) {
+            res.status(503).json({ error: 'Initiative tracker not configured' });
+            return;
+        }
         if (!initiativeIdRe.test(req.params.id)) {
             res.status(400).json({ error: 'invalid project id' });
             return;
         }
-        // Next-action computation lands in Phase 1b's ProjectRoundRunner.
-        res.status(501).json({
-            action: 'not-implemented',
-            message: 'next-action computation lands in Phase 1b',
+        const project = ctx.initiativeTracker.get(req.params.id);
+        if (!project || (project.kind ?? 'task') !== 'project') {
+            res.status(404).json({ error: 'project not found' });
+            return;
+        }
+        const rounds = project.rounds ?? [];
+        const idx = rounds.findIndex((r) => (r.status ?? 'pending') !== 'complete');
+        if (idx === -1) {
+            res.status(204).end();
+            return;
+        }
+        const r = rounds[idx];
+        let action = 'start-round';
+        const childrenById = new Map(ctx.initiativeTracker
+            .list()
+            .filter((i) => i.parentProjectId === project.id)
+            .map((c) => [c.id, c]));
+        const itemsForRound = (r.itemIds ?? []).map((id) => childrenById.get(id)).filter(Boolean);
+        if ((project.awaitingReconciliation ?? []).length > 0) {
+            action = 'resolve-conflict';
+        }
+        else if ((r.status ?? 'pending') === 'partially-complete') {
+            action = 'accept-partial';
+        }
+        else if (idx === 0 && !project.firstLaunchAckAt) {
+            action = 'await-user-approval';
+        }
+        else if ((project.unacknowledgedAdvanceCount ?? 0) >= 2) {
+            action = 'ack-required';
+        }
+        else if (itemsForRound.some((c) => c?.pipelineStage === 'spec-drafted')) {
+            action = 'run-spec-converge';
+        }
+        else if (itemsForRound.some((c) => c?.pipelineStage === 'approved' && !r.lastDriftVerdict)) {
+            action = 'run-drift-check';
+        }
+        res.json({
+            action,
+            params: {
+                projectId: project.id,
+                projectVersion: project.version,
+                roundIndex: idx,
+                name: r.name,
+                itemIds: r.itemIds,
+                status: r.status ?? 'pending',
+                autoAdvanceAt: r.autoAdvanceAt,
+            },
+            skillCommand: skillCommandForAction(action, project.id, idx),
         });
     });
+    // ── /projects/:id mutating routes (Phase 1b PR 3) ──────────────
+    //
+    // All mutating endpoints require `If-Match: <version>` (OCC). Missing
+    // header → 428. Stale version → 409. Spec § Phase 1.3.
+    //
+    // /advance is a single-item stage transition driven by StageTransitionValidator.
+    // /halt, /ack, /accept-partial route through ProjectRoundRunner.
+    function parseIfMatch(req, res) {
+        const header = req.headers['if-match'];
+        if (typeof header !== 'string' || !header.trim()) {
+            res.status(428).json({ error: 'If-Match header required' });
+            return null;
+        }
+        const n = parseInt(header.replace(/"/g, ''), 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            res.status(400).json({ error: 'If-Match must be a positive integer version' });
+            return null;
+        }
+        return n;
+    }
+    function lookupProject(req, res) {
+        if (!ctx.initiativeTracker) {
+            res.status(503).json({ error: 'Initiative tracker not configured' });
+            return null;
+        }
+        if (!initiativeIdRe.test(req.params.id)) {
+            res.status(400).json({ error: 'invalid project id' });
+            return null;
+        }
+        const project = ctx.initiativeTracker.get(req.params.id);
+        if (!project || (project.kind ?? 'task') !== 'project') {
+            res.status(404).json({ error: 'project not found' });
+            return null;
+        }
+        return project;
+    }
+    // POST /projects/:id/advance — advance one child item by one stage.
+    //
+    // Body shape:
+    //   {
+    //     "itemId": "<child id>",
+    //     "fromStage": "<optional explicit current stage>",
+    //     "targetStage": "spec-drafted|spec-converged|approved|building|merged|skipped|outline",
+    //     "artifact": {
+    //       "specPath"?: "...",          // outline → spec-drafted
+    //       "prNumber"?: 123,            // building → merged
+    //       "taskFlowRecordId"?: "...",  // approved → building
+    //       "skippedReason"?: "...",     // any → skipped
+    //       "skippedBy"?: "...",         // any → skipped
+    //       "unskippedAt"?: "..."        // skipped → outline
+    //     }
+    //   }
+    //
+    // The HTTP layer does NOT enforce gates the ProjectRoundRunner already
+    // enforces — `/advance` is a single-item transition that operates on
+    // child records, not on round status. Round-level invariants (lock,
+    // first-launch ack, owner machine, etc.) apply only to /run-round
+    // and to the autonomous loop, both of which ship in a later PR.
+    router.post('/projects/:id/advance', async (req, res) => {
+        const project = lookupProject(req, res);
+        if (!project)
+            return;
+        if (!ctx.initiativeTracker)
+            return; // narrow for TS
+        const ifMatch = parseIfMatch(req, res);
+        if (ifMatch === null)
+            return;
+        if (ifMatch !== project.version) {
+            res.status(409).json({ error: 'version mismatch', currentVersion: project.version });
+            return;
+        }
+        const body = (req.body ?? {});
+        const itemId = typeof body.itemId === 'string' ? body.itemId : '';
+        const targetStage = typeof body.targetStage === 'string' ? body.targetStage : null;
+        if (!itemId) {
+            res.status(400).json({ error: '"itemId" required' });
+            return;
+        }
+        if (!targetStage) {
+            res.status(400).json({ error: '"targetStage" required' });
+            return;
+        }
+        const child = ctx.initiativeTracker.get(itemId);
+        if (!child || child.parentProjectId !== project.id) {
+            res.status(404).json({ error: `child item "${itemId}" not found under project ${project.id}` });
+            return;
+        }
+        if (!project.targetRepoPath) {
+            res.status(400).json({ error: 'project has no targetRepoPath; cannot validate artifacts' });
+            return;
+        }
+        const artifact = body.artifact ?? {};
+        const validationCtx = {
+            targetRepoPath: project.targetRepoPath,
+            specPath: typeof artifact.specPath === 'string' ? artifact.specPath : undefined,
+            prNumber: typeof artifact.prNumber === 'number' ? artifact.prNumber : undefined,
+            taskFlowRecordId: typeof artifact.taskFlowRecordId === 'string' ? artifact.taskFlowRecordId : undefined,
+            skippedReason: typeof artifact.skippedReason === 'string' ? artifact.skippedReason : undefined,
+            skippedBy: typeof artifact.skippedBy === 'string' ? artifact.skippedBy : undefined,
+            unskippedAt: typeof artifact.unskippedAt === 'string' ? artifact.unskippedAt : undefined,
+        };
+        const fromStage = typeof body.fromStage === 'string'
+            ? body.fromStage
+            : child.pipelineStage;
+        const result = await validateStageTransition(fromStage, targetStage, validationCtx);
+        if (!result.ok) {
+            res.status(409).json({ error: 'stage transition rejected', code: result.code, reason: result.reason });
+            return;
+        }
+        try {
+            const updated = await ctx.initiativeTracker.update(itemId, {
+                pipelineStage: targetStage,
+                ifMatch: child.version,
+            });
+            // Bump the project version too so concurrent advance calls don't
+            // operate on a stale view. We touch description ("last advance
+            // <timestamp>") to force a meaningful update.
+            const refreshed = await ctx.initiativeTracker.update(project.id, {
+                // No-op-but-bump: nudge `lastTouchedAt` indirectly via update.
+                nextCheckAt: project.nextCheckAt,
+                ifMatch: project.version,
+            });
+            res.json({
+                item: { id: updated.id, pipelineStage: updated.pipelineStage, version: updated.version },
+                project: { id: refreshed.id, version: refreshed.version },
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'OccVersionMismatchError') {
+                const cv = err.currentVersion;
+                res.status(409).json({ error: 'version mismatch', currentVersion: cv });
+                return;
+            }
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    // POST /projects/:id/halt — kills the active round. Idempotent.
+    router.post('/projects/:id/halt', async (req, res) => {
+        const project = lookupProject(req, res);
+        if (!project)
+            return;
+        if (!ctx.projectRoundRunner) {
+            res.status(503).json({ error: 'ProjectRoundRunner not configured' });
+            return;
+        }
+        const reason = typeof (req.body ?? {}).reason === 'string' ? req.body.reason : 'no reason given';
+        try {
+            const result = await ctx.projectRoundRunner.halt(project.id, reason);
+            if (!result) {
+                res.status(409).json({ error: 'project has no halt-able round' });
+                return;
+            }
+            res.json({ id: result.project.id, roundIndex: result.roundIndex, version: result.project.version });
+        }
+        catch (err) {
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    // POST /projects/:id/ack — record user acknowledgment.
+    router.post('/projects/:id/ack', async (req, res) => {
+        const project = lookupProject(req, res);
+        if (!project)
+            return;
+        if (!ctx.projectRoundRunner) {
+            res.status(503).json({ error: 'ProjectRoundRunner not configured' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const idx = typeof body.forRoundIndex === 'number' ? body.forRoundIndex : (typeof body.roundIndex === 'number' ? body.roundIndex : 0);
+        if (!Number.isInteger(idx) || idx < 0) {
+            res.status(400).json({ error: '"forRoundIndex" must be a non-negative integer' });
+            return;
+        }
+        try {
+            const updated = await ctx.projectRoundRunner.recordAck(project.id, idx);
+            if (!updated) {
+                res.status(404).json({ error: 'project not found' });
+                return;
+            }
+            res.json({
+                id: updated.id,
+                firstLaunchAckAt: updated.firstLaunchAckAt,
+                lastAckedRoundIndex: updated.lastAckedRoundIndex,
+                unacknowledgedAdvanceCount: updated.unacknowledgedAdvanceCount,
+                version: updated.version,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'OccVersionMismatchError') {
+                const cv = err.currentVersion;
+                res.status(409).json({ error: 'version mismatch', currentVersion: cv });
+                return;
+            }
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    // POST /projects/:id/accept-partial — close a partially-complete round.
+    router.post('/projects/:id/accept-partial', async (req, res) => {
+        const project = lookupProject(req, res);
+        if (!project)
+            return;
+        if (!ctx.projectRoundRunner) {
+            res.status(503).json({ error: 'ProjectRoundRunner not configured' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const idx = typeof body.roundIndex === 'number' ? body.roundIndex : -1;
+        const reason = typeof body.reason === 'string' ? body.reason : '';
+        const skippedBy = typeof body.skippedBy === 'string' ? body.skippedBy : '';
+        if (!Number.isInteger(idx) || idx < 0) {
+            res.status(400).json({ error: '"roundIndex" must be a non-negative integer' });
+            return;
+        }
+        if (!reason.trim()) {
+            res.status(400).json({ error: '"reason" required' });
+            return;
+        }
+        if (!skippedBy.trim()) {
+            res.status(400).json({ error: '"skippedBy" required' });
+            return;
+        }
+        try {
+            const result = await ctx.projectRoundRunner.acceptPartial(project.id, idx, reason, skippedBy);
+            if (!result) {
+                res.status(404).json({ error: 'project or round not found' });
+                return;
+            }
+            res.json({
+                id: result.project.id,
+                skippedItemIds: result.skippedItemIds,
+                version: result.project.version,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'OccVersionMismatchError') {
+                const cv = err.currentVersion;
+                res.status(409).json({ error: 'version mismatch', currentVersion: cv });
+                return;
+            }
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    // POST /projects/:id/claim-ownership — multi-machine ownership transfer.
+    //
+    // Body: {} or { force?: boolean }
+    // Header: If-Match: <version> (OCC)
+    //
+    // Spec § P5: the claimer must (a) commit-and-push the claim before
+    // acting on it, (b) wait 60s for git-sync to converge, (c) re-read
+    // before any auto-action. This endpoint ONLY records the ownership
+    // change; the wait-and-converge happens at the caller level (the
+    // round runner, the auto-advance poller, the dashboard). Claim is
+    // refused (409) if the current owner's heartbeat is still fresh and
+    // `force: true` was not set.
+    router.post('/projects/:id/claim-ownership', async (req, res) => {
+        const project = lookupProject(req, res);
+        if (!project)
+            return;
+        if (!ctx.initiativeTracker)
+            return; // narrow for TS
+        if (!ctx.machineHeartbeat || !ctx.machineHeartbeat.config) {
+            res.status(503).json({ error: 'machine heartbeat not configured' });
+            return;
+        }
+        const ifMatch = parseIfMatch(req, res);
+        if (ifMatch === null)
+            return;
+        if (ifMatch !== project.version) {
+            res.status(409).json({ error: 'version mismatch', currentVersion: project.version });
+            return;
+        }
+        const force = (req.body ?? {}).force === true;
+        const heartbeat = ctx.machineHeartbeat.api;
+        const currentOwner = project.ownerMachineId;
+        const claimer = ctx.machineHeartbeat.config.machineId;
+        if (currentOwner === claimer) {
+            // Already owned by claimer — idempotent success.
+            res.json({ id: project.id, ownerMachineId: claimer, version: project.version, alreadyOwned: true });
+            return;
+        }
+        if (currentOwner && !heartbeat.isStale(currentOwner) && !force) {
+            res.status(409).json({
+                error: 'current owner heartbeat is still fresh; pass {force:true} to claim anyway',
+                currentOwner,
+            });
+            return;
+        }
+        try {
+            const updated = await ctx.initiativeTracker.update(project.id, {
+                ownerMachineId: claimer,
+                ifMatch: project.version,
+            });
+            res.json({
+                id: updated.id,
+                ownerMachineId: updated.ownerMachineId,
+                previousOwner: currentOwner ?? null,
+                version: updated.version,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'OccVersionMismatchError') {
+                const cv = err.currentVersion;
+                res.status(409).json({ error: 'version mismatch', currentVersion: cv });
+                return;
+            }
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    // POST /projects/:id/drift-check — run the drift checker for a given
+    // round and return the verdict. Wraps ProjectDriftChecker.run().
+    //
+    // Body: { roundIndex: number, specPath: string, referencedFiles: string[],
+    //         timeoutMs?: number, modelId?: string }
+    //
+    // Mutex-guarded per project (spec § Phase 1.5 line 279). Without it two
+    // concurrent calls would double-spend the drift-spend ledger and
+    // double-bill the LLM. A second concurrent call returns 409 with
+    // `{error: 'drift-check already in flight'}` so the caller can poll.
+    //
+    // 400 on validation; 503 if no checker configured; 200 with verdict envelope
+    // on success. We do NOT require If-Match: drift is a read-only signal.
+    const driftInFlight = new Set();
+    router.post('/projects/:id/drift-check', async (req, res) => {
+        if (!ctx.initiativeTracker) {
+            res.status(503).json({ error: 'Initiative tracker not configured' });
+            return;
+        }
+        if (!ctx.projectDriftChecker) {
+            res.status(503).json({ error: 'ProjectDriftChecker not configured' });
+            return;
+        }
+        if (!initiativeIdRe.test(req.params.id)) {
+            res.status(400).json({ error: 'invalid project id' });
+            return;
+        }
+        const project = ctx.initiativeTracker.get(req.params.id);
+        if (!project || (project.kind ?? 'task') !== 'project') {
+            res.status(404).json({ error: 'project not found' });
+            return;
+        }
+        if (!project.targetRepoPath) {
+            res.status(400).json({ error: 'project has no targetRepoPath' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const roundIndex = typeof body.roundIndex === 'number' ? body.roundIndex : -1;
+        const specPath = typeof body.specPath === 'string' ? body.specPath : '';
+        const referencedFiles = Array.isArray(body.referencedFiles)
+            ? body.referencedFiles.filter((f) => typeof f === 'string')
+            : [];
+        if (!Number.isInteger(roundIndex) || roundIndex < 0) {
+            res.status(400).json({ error: '"roundIndex" (non-negative integer) required' });
+            return;
+        }
+        if (!specPath.trim()) {
+            res.status(400).json({ error: '"specPath" (string) required' });
+            return;
+        }
+        const rounds = project.rounds ?? [];
+        if (roundIndex >= rounds.length) {
+            res.status(400).json({ error: 'roundIndex out of range', rounds: rounds.length });
+            return;
+        }
+        if (driftInFlight.has(project.id)) {
+            res.status(409).json({ error: 'drift-check already in flight for this project' });
+            return;
+        }
+        driftInFlight.add(project.id);
+        try {
+            const verdict = await ctx.projectDriftChecker.run({
+                projectId: project.id,
+                roundIndex,
+                targetRepoPath: project.targetRepoPath,
+                specPath,
+                referencedFiles,
+                timeoutMs: typeof body.timeoutMs === 'number' ? body.timeoutMs : undefined,
+                modelId: typeof body.modelId === 'string' ? body.modelId : undefined,
+            });
+            res.json({ verdict, projectId: project.id, roundIndex });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+        finally {
+            driftInFlight.delete(project.id);
+        }
+    });
     router.post('/projects', async (req, res) => {
         if (!ctx.initiativeTracker) {
             res.status(503).json({ error: 'Initiative tracker not configured' });