@deksden-com/dd-flow-cli 0.1.0 → 0.3.0

package/dist/services/flow-guidance.js

@@ -0,0 +1,214 @@
+import path from "node:path";
+import { defaultFlowContract, flowContractForState } from "../domain/flow-contract.js";
+export function buildProtocolFlowGuidance(input) {
+    const contract = flowContractForState(input.state);
+    const stageChain = latestRunStageChain(input.latestRun);
+    return buildFlowGuidance({
+        currentStage: input.state.stage,
+        contract,
+        stageChain,
+        runId: stringValue(input.latestRun?.id),
+        queueStatus: input.queueStatus ?? null
+    });
+}
+export function buildRunFlowGuidance(input) {
+    const contract = input.contract ?? defaultFlowContract;
+    const chain = input.stageRuns.map((stage) => `${String(stage.stage ?? "unknown")}:${String(stage.status ?? "unknown")}`);
+    const currentStage = input.protocolStage ?? inferStageFromRun(input.stageRuns);
+    return buildFlowGuidance({
+        currentStage,
+        contract,
+        stageChain: chain,
+        runId: input.runId ?? null,
+        runDir: input.runDir ?? null,
+        stageRuns: input.stageRuns
+    });
+}
+export function buildStaticFlowGuidance(input) {
+    return buildFlowGuidance({
+        currentStage: input.stage,
+        contract: input.contract ?? defaultFlowContract,
+        stageChain: [],
+        runId: null,
+        queueStatus: input.queueStatus ?? null
+    });
+}
+function buildFlowGuidance(input) {
+    const planDone = hasDoneStage(input.stageChain, "plan");
+    const codeDone = hasDoneStage(input.stageChain, "code") || hasDoneStage(input.stageChain, "implementation") || hasDoneStage(input.stageChain, "readiness");
+    const evidence = evidencePaths(input.runId, input.runDir ?? null, input.stageRuns);
+    if (input.currentStage === "closed" || input.currentStage === "cancelled") {
+        return guidance(input, {
+            action: "none",
+            prompt: "none",
+            evidence: [],
+            guards: [{ id: "flow_terminal", status: "not_applicable", summary: `Protocol is ${input.currentStage}.` }],
+            missing: []
+        });
+    }
+    if (input.currentStage === "ready_for_merge" || input.currentStage === "queued_for_merge") {
+        return guidance(input, {
+            action: input.currentStage === "queued_for_merge" ? "wait for or run merge worker" : "run merge flow",
+            prompt: ".memory-bank/dd-flow/merge.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [
+                {
+                    id: "merge_requires_ready_for_merge",
+                    status: "pass",
+                    summary: input.queueStatus ? `Protocol is ${input.currentStage}; queue status is ${input.queueStatus}.` : `Protocol is ${input.currentStage}.`
+                }
+            ],
+            missing: []
+        });
+    }
+    if (input.currentStage === "integration") {
+        return guidance(input, {
+            action: "finish merge job",
+            prompt: ".memory-bank/dd-flow/merge/job.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [{ id: "merge_requires_ready_for_merge", status: "pass", summary: "Merge job is in integration stage." }],
+            missing: []
+        });
+    }
+    if (input.currentStage === "readiness") {
+        return guidance(input, {
+            action: "complete readiness and mark ready for merge",
+            prompt: ".memory-bank/dd-flow/code/readiness.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [{ id: "merge_requires_ready_for_merge", status: codeDone ? "unknown" : "fail", summary: codeDone ? "Code evidence exists; readiness must still be completed." : "Code evidence is missing." }],
+            missing: codeDone ? ["ready_for_merge transition"] : ["code stage report", "ready_for_merge transition"]
+        });
+    }
+    if (input.currentStage === "implementation" || input.currentStage === "hardening") {
+        return guidance(input, {
+            action: "continue code flow",
+            prompt: input.currentStage === "hardening" ? ".memory-bank/dd-flow/finish.md" : ".memory-bank/dd-flow/code.md",
+            evidence: evidence.plan.length > 0 ? evidence.plan : defaultEvidence(input.runId, input.runDir ?? null, "02-plan"),
+            guards: [{
+                    id: "code_flow_requires_plan_ready",
+                    status: planDone ? "pass" : "unknown",
+                    summary: planDone ? "Plan stage evidence exists." : "Plan evidence was not found in the linked run."
+                }],
+            missing: planDone ? [] : ["plan stage report", "ready_for_code verdict"]
+        });
+    }
+    if (input.currentStage === "plan") {
+        return guidance(input, {
+            action: planDone ? "run code flow" : "complete plan flow",
+            prompt: planDone ? ".memory-bank/dd-flow/code.md" : ".memory-bank/dd-flow/plan.md",
+            evidence: evidence.plan.length > 0 ? evidence.plan : defaultEvidence(input.runId, input.runDir ?? null, "02-plan"),
+            guards: [{
+                    id: "code_flow_requires_plan_ready",
+                    status: planDone ? "pass" : "fail",
+                    summary: planDone ? "Plan stage report exists in linked run evidence." : "Plan stage evidence is not complete."
+                }],
+            missing: planDone ? [] : ["plan stage report", "ready_for_code verdict"]
+        });
+    }
+    if (input.currentStage === "specify" || input.currentStage === "priming" || input.currentStage === "prime" || input.currentStage === "registered") {
+        const action = input.currentStage === "registered" ? "run protocol/specify flow" : "run plan flow after specification is complete";
+        return guidance(input, {
+            action,
+            prompt: input.currentStage === "registered" ? ".memory-bank/dd-flow/protocol.md" : ".memory-bank/dd-flow/plan.md",
+            evidence: [],
+            guards: [{
+                    id: "plan_requires_protocol_and_specification",
+                    status: input.currentStage === "registered" ? "unknown" : "pass",
+                    summary: input.currentStage === "registered" ? "Protocol is registered; specification evidence must be checked by the prompt." : "Protocol has progressed past registration."
+                }],
+            missing: input.currentStage === "registered" ? ["specification evidence"] : []
+        });
+    }
+    if (input.currentStage === "blocked") {
+        return guidance(input, {
+            action: "resolve blocker and continue named safe flow",
+            prompt: "depends_on_blocker",
+            evidence: [],
+            guards: [{ id: "flow_blocked", status: "fail", summary: "Protocol is blocked." }],
+            missing: ["blocker resolution"]
+        });
+    }
+    if (input.currentStage === "waiting_for_user") {
+        return guidance(input, {
+            action: "collect user answer",
+            prompt: "active_protocol_context",
+            evidence: [],
+            guards: [{ id: "flow_waiting_for_user", status: "unknown", summary: "Protocol is waiting for user input." }],
+            missing: ["user answer"]
+        });
+    }
+    return guidance(input, {
+        action: `continue ${input.currentStage}`,
+        prompt: "active_flow_prompt",
+        evidence: [],
+        guards: [{ id: "flow_guidance_unknown_stage_policy", status: "unknown", summary: `No specific guidance rule for stage ${input.currentStage}.` }],
+        missing: []
+    });
+}
+function guidance(input, value) {
+    return {
+        current_stage: input.currentStage,
+        allowed_next_stages: input.contract.transitions[input.currentStage] ?? [],
+        recommended_next_action: value.action,
+        recommended_prompt: value.prompt,
+        required_predecessor_evidence: value.evidence,
+        guards: value.guards,
+        blocked_if_missing: value.missing
+    };
+}
+function latestRunStageChain(run) {
+    return Array.isArray(run?.stage_chain) ? run.stage_chain.filter((item) => typeof item === "string") : [];
+}
+function hasDoneStage(chain, stage) {
+    return chain.includes(`${stage}:done`);
+}
+function inferStageFromRun(stageRuns) {
+    const done = new Set(stageRuns.filter((stage) => stage.status === "done").map((stage) => stage.stage));
+    if (done.has("merge"))
+        return "closed";
+    if (done.has("code") || done.has("implementation") || done.has("readiness"))
+        return "ready_for_merge";
+    if (done.has("plan"))
+        return "plan";
+    return "registered";
+}
+function evidencePaths(runId, runDir, stageRuns) {
+    const result = { plan: [], code: [] };
+    if (!stageRuns)
+        return result;
+    for (const stage of stageRuns) {
+        const bucket = stage.stage === "plan" ? result.plan : ["code", "implementation", "readiness"].includes(String(stage.stage)) ? result.code : null;
+        if (!bucket)
+            continue;
+        const dir = stage.dir ? path.posix.join(runDir ?? legacyRunDir(runId), stage.dir) : stage.dir;
+        for (const field of [stage.data, stage.stage_report, stage.report]) {
+            if (field)
+                bucket.push(toEvidencePath(runId, runDir, stage.dir, field, dir));
+        }
+    }
+    return result;
+}
+function toEvidencePath(runId, runDir, stageDir, field, prefixedStageDir) {
+    if (!runId)
+        return field;
+    if (field.startsWith(".tasks/dd-flow-runs/"))
+        return field;
+    if (field.startsWith("runs/"))
+        return field;
+    if (stageDir && field.startsWith(`${stageDir}/`)) {
+        return path.posix.join(runDir ?? legacyRunDir(runId), field);
+    }
+    return prefixedStageDir ? path.posix.join(prefixedStageDir, field) : field;
+}
+function defaultEvidence(runId, runDir, dir) {
+    if (!runId)
+        return [`<RUN>/${dir}/stage-report.json`, `<RUN>/${dir}/stage-report.html`];
+    const base = path.posix.join(runDir ?? legacyRunDir(runId), dir);
+    return [path.posix.join(base, "stage-report.json"), path.posix.join(base, "stage-report.html")];
+}
+function legacyRunDir(runId) {
+    return runId ? path.posix.join(".tasks/dd-flow-runs", runId) : "<RUN>";
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/services/ids.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatFullId, parseFullEntityId } from "../domain/entity-ids.js";
+import { AppError } from "../shared/errors.js";
+import { projectRunHome, resolveProjectRoot } from "../storage/paths.js";
+const kindConfig = {
+    protocol: { type: "PRT", table: "protocols", fileRoot: ".memory-bank/protocol" },
+    run: { type: "RUN", table: "flow_runs", fileRoot: ".tasks/dd-flow-runs" }
+};
+export function previewNextEntityId(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const kind = parseEntityKind(input.type);
+    const slug = normalizeSlug(input.slug);
+    const config = kindConfig[kind];
+    const used = new Set();
+    for (const id of databaseIds(context, config.table, config.type)) {
+        addSequence(used, id, config.type);
+    }
+    for (const id of filesystemIds(projectRoot, config.fileRoot, config.type)) {
+        addSequence(used, id, config.type);
+    }
+    if (kind === "run") {
+        for (const id of homeRunIds(context, projectRoot)) {
+            addSequence(used, id, config.type);
+        }
+        for (const id of filesystemIds(projectRoot, ".tasks", config.type)) {
+            addSequence(used, id, config.type);
+        }
+    }
+    for (let sequence = 1; sequence <= 999; sequence += 1) {
+        if (used.has(sequence))
+            continue;
+        const id = formatFullId(config.type, sequence, slug);
+        const parsed = parseFullEntityId(id);
+        return {
+            ok: true,
+            project_root: projectRoot,
+            entity: {
+                kind,
+                type: config.type,
+                id,
+                short_id: parsed.shortId,
+                slug,
+                sequence,
+                reserved: false
+            }
+        };
+    }
+    throw new AppError("validation", `${config.type} id sequence exhausted`, 2);
+}
+function homeRunIds(context, projectRoot) {
+    const project = context.db.get("SELECT id FROM projects WHERE root = ? AND status = 'active'", [projectRoot]);
+    if (!project) {
+        return [];
+    }
+    const root = projectRunHome(context.ddFlowHome, project.id, "__placeholder__").replace(/__placeholder__$/, "");
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [];
+    }
+    return fs.readdirSync(root).filter((entry) => entry.startsWith("RUN-"));
+}
+function parseEntityKind(value) {
+    const normalized = value.toLowerCase();
+    if (normalized === "protocol" || normalized === "prt")
+        return "protocol";
+    if (normalized === "run")
+        return "run";
+    throw new AppError("validation", "--type must be protocol or run", 2, { type: value });
+}
+function databaseIds(context, table, type) {
+    return context.db.all(`SELECT id FROM ${table} WHERE id LIKE ?`, [`${type}-%`]).map((row) => row.id);
+}
+function filesystemIds(projectRoot, relativeRoot, type) {
+    const root = path.join(projectRoot, relativeRoot);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [];
+    }
+    return fs
+        .readdirSync(root)
+        .filter((entry) => entry.startsWith(`${type}-`))
+        .map((entry) => entry.replace(/\.md$/, ""));
+}
+function addSequence(used, id, type) {
+    try {
+        const parsed = parseFullEntityId(id);
+        if (parsed.type !== type)
+            return;
+        used.add(Number(parsed.shortId.slice(type.length + 1)));
+    }
+    catch {
+        return;
+    }
+}
+function normalizeSlug(value) {
+    const slug = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    if (!slug) {
+        throw new AppError("validation", "--slug must contain at least one ASCII letter or digit", 2);
+    }
+    return slug;
+}

package/dist/services/lanes.js

@@ -17,6 +17,9 @@ export function getLaneStatus(context, input) {
         locks: laneLocksForProject(context, project.id, input.lane)
     };
 }
+export function expireProjectLaneLocks(context, projectId) {
+    expireStaleLocks(context, projectId);
+}
 export function setLaneWorkspace(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const lane = normalizeLane(input.lane);
@@ -267,10 +270,11 @@ function assertWorkerMayAcquireLaneLock(context, projectId, lane, workerId) {
     const latest = context.db.get(`SELECT status, stop_reason, flow_kind FROM flow_sessions
      WHERE project_id = ? AND worker_id = ? AND flow_kind IN ('merge_worker', 'merge_job')
      ORDER BY updated_at DESC, rowid DESC LIMIT 1`, [projectId, workerId]);
-    if (latest?.status === "stopped") {
-        throw new AppError("merge_worker_stopped", "Stopped merge worker cannot acquire the merge lane lock until it registers a new active session", 1, {
+    if (latest && ["stopped", "stopping"].includes(latest.status)) {
+        throw new AppError("merge_worker_stopped", "Stopped or stopping merge worker cannot acquire the merge lane lock until it registers a new active session", 1, {
             worker_id: workerId,
             flow_kind: latest.flow_kind,
+            status: latest.status,
             stop_reason: latest.stop_reason
         });
     }

package/dist/services/merge-queue.js

@@ -2,10 +2,10 @@ import { loadProjectFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { persistProtocolState, protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { acquireLaneLock, ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, requireLaneLockOwner } from "./lanes.js";
-import { stoppedMergeWorkerState } from "./sessions.js";
+import { stopMergeWorker, stoppedMergeWorkerState } from "./sessions.js";
 const mergeLockTtlSeconds = 300;
 export function getMergeQueueStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -16,6 +16,14 @@ export function getMergeQueueStatus(context, input) {
 }
 export function claimNextMergeJob(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const stopState = stoppedMergeWorkerState(context, project.id, input.workerId);
+    if (stopState.stopped) {
+        throw new AppError("merge_worker_stopped", "Stopped or stopping merge worker cannot claim another merge job", 1, {
+            worker_id: input.workerId,
+            status: stopState.status,
+            reason: stopState.reason
+        });
+    }
     requireLaneLockOwner(context, {
         projectRoot: project.root,
         lane: "merge",
@@ -47,6 +55,7 @@ export function claimNextMergeJob(context, input) {
             eventType: "merge_queue.claimed",
             payload: { protocol_id: job.protocol_id, worker_id: input.workerId }
         });
+        transitionClaimedProtocolToIntegration(context, job.protocol_id, input.workerId, now);
         claimedProtocolId = job.protocol_id;
         context.db.exec("COMMIT");
     }
@@ -184,7 +193,8 @@ export function completeMergeJob(context, input) {
         eventType: "merge_queue.completed",
         payload: { protocol_id: protocol.id, worker_id: input.workerId, summary: input.summary, flow_contract_id: flowContract.id }
     });
-    return { ok: true, job: queueJobByProtocol(context, protocol.id), next_stage: targetStage };
+    const stop_after_current = stopAfterCurrentIfRequested(context, protocol.project_id, protocol.project_root, input.workerId, "merge complete after stop request");
+    return { ok: true, job: queueJobByProtocol(context, protocol.id), next_stage: targetStage, stop_after_current };
 }
 export function noteMergeJob(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
@@ -230,6 +240,16 @@ export function failMergeJob(context, input) {
     context.db.run(`UPDATE merge_queue
      SET status = ?, attempts_count = attempts_count + 1, last_reason = ?, updated_at = ?
      WHERE id = ?`, [status, input.reason, now, job.id]);
+    if (input.requeue) {
+        const state = readProtocolRuntimeState(context, protocol).state;
+        persistProtocolState(context, protocol, {
+            ...state,
+            stage: "ready_for_merge",
+            status: "running",
+            next_action: "merge_requeued",
+            updated_at: now
+        });
+    }
     appendAudit(context, {
         protocolId: protocol.id,
         projectId: protocol.project_id,
@@ -237,7 +257,8 @@ export function failMergeJob(context, input) {
         reason: input.reason,
         payload: { protocol_id: protocol.id, worker_id: input.workerId, requeue: input.requeue }
     });
-    return { ok: true, job: queueJobByProtocol(context, protocol.id) };
+    const stop_after_current = stopAfterCurrentIfRequested(context, protocol.project_id, protocol.project_root, input.workerId, "merge fail after stop request");
+    return { ok: true, job: queueJobByProtocol(context, protocol.id), stop_after_current };
 }
 export function cancelMergeQueueJob(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
@@ -317,6 +338,39 @@ function requireClaimedJob(context, protocolId, sessionId) {
     }
     return job;
 }
+function transitionClaimedProtocolToIntegration(context, protocolId, workerId, now) {
+    const protocol = requireProtocol(context, protocolId);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const flowContract = loadProjectFlowContract(protocol.project_root);
+    if (!["ready_for_merge", "queued_for_merge"].includes(state.stage)) {
+        throw new AppError("merge_protocol_not_ready", "Cannot claim a protocol whose runtime state is not ready for merge", 1, {
+            protocol_id: protocolId,
+            stage: state.stage,
+            allowed: ["ready_for_merge", "queued_for_merge"]
+        });
+    }
+    const diagnostics = protocolRunDiagnostics(context, protocol, state).diagnostics;
+    const blockingDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (blockingDiagnostics.length > 0) {
+        throw new AppError("merge_protocol_run_mismatch", "Cannot claim a protocol while protocol and run evidence disagree", 1, {
+            protocol_id: protocolId,
+            diagnostics: blockingDiagnostics
+        });
+    }
+    persistProtocolState(context, protocol, {
+        ...state,
+        stage: "integration",
+        status: flowContract.stages.integration?.terminal ? "integration" : "running",
+        next_action: "run_integration",
+        updated_at: now
+    });
+    appendAudit(context, {
+        protocolId,
+        projectId: protocol.project_id,
+        eventType: "protocol.integration_claimed",
+        payload: { protocol_id: protocolId, worker_id: workerId, flow_contract_id: flowContract.id }
+    });
+}
 function releaseLaneLockIfOwned(context, input) {
     try {
         releaseLaneLock(context, input);
@@ -328,6 +382,16 @@ function releaseLaneLockIfOwned(context, input) {
         throw error;
     }
 }
+function stopAfterCurrentIfRequested(context, projectId, projectRoot, workerId, reason) {
+    const requested = context.db.get(`SELECT session_id FROM flow_sessions
+     WHERE project_id = ? AND worker_id = ? AND flow_kind = 'merge_worker'
+       AND status = 'stopping' AND current_stage = 'stop_after_current'
+     ORDER BY updated_at DESC, rowid DESC LIMIT 1`, [projectId, workerId]);
+    if (!requested) {
+        return { requested: false };
+    }
+    return { requested: true, stop: stopMergeWorker(context, { projectRoot, workerId, reason }) };
+}
 async function delay(milliseconds) {
     await new Promise((resolve) => setTimeout(resolve, milliseconds));
 }

package/dist/services/merge-worker.js

@@ -0,0 +1,177 @@
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { appendAudit } from "./audit.js";
+import { ensureLaneWorkspace, acquireLaneLock, releaseLaneLock, expireProjectLaneLocks } from "./lanes.js";
+import { claimNextMergeJob, queueForProject } from "./merge-queue.js";
+import { requireProjectByRoot } from "./projects.js";
+import { buildStaticFlowGuidance } from "./flow-guidance.js";
+import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { registerFlowSession, stopMergeWorker } from "./sessions.js";
+export function getMergeWorkerStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return {
+        ok: true,
+        project: { id: project.id, root: project.root },
+        merge_worker: detectMergeWorkerState(context, project.id),
+        queue: queueForProject(context, project.id).map((job) => withJobGuidance(context, { ...job }))
+    };
+}
+export function startMergeWorker(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const workspacePath = resolveProjectRoot(input.workspacePath ?? project.root);
+    const detection = detectMergeWorkerState(context, project.id);
+    if (detection.state !== "clear") {
+        return { ok: true, started: false, reason: "merge_worker_already_active", merge_worker: detection, queue: queueForProject(context, project.id) };
+    }
+    ensureLaneWorkspace(context, { projectRoot: project.root, lane: "merge", workspacePath, branch: input.branch });
+    const registered = registerFlowSession(context, {
+        payloadJson: JSON.stringify({
+            project_root: project.root,
+            flow_kind: "merge_worker",
+            protocol_id: null,
+            worker_id: input.workerId,
+            workspace_path: workspacePath,
+            continuation_policy: "merge_queue",
+            current_stage: "waiting_for_merge_job",
+            next_action: "merge_queue_wait_next"
+        })
+    });
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "merge_worker.started",
+        payload: { project_id: project.id, worker_id: input.workerId, workspace_path: workspacePath }
+    });
+    return { ok: true, started: true, session: registered.session, merge_worker: detectMergeWorkerState(context, project.id) };
+}
+export function stopProjectMergeWorker(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const workers = activeMergeWorkerSessions(context, project.id);
+    const targetWorkerId = input.workerId ?? uniqueWorkerId(workers);
+    if (!targetWorkerId) {
+        return { ok: true, stopped: false, reason: "no_active_merge_worker", merge_worker: detectMergeWorkerState(context, project.id) };
+    }
+    const targetSessions = workers.filter((session) => session.worker_id === targetWorkerId);
+    if (targetSessions.length === 0) {
+        throw new AppError("merge_worker_not_found", "Merge worker is not active", 1, { worker_id: targetWorkerId });
+    }
+    const claimed = claimedJobsForWorker(context, project.id, targetWorkerId);
+    if (claimed.length > 0) {
+        const now = context.now();
+        for (const session of targetSessions) {
+            context.db.run(`UPDATE flow_sessions
+         SET status = 'stopping', stop_reason = ?, current_stage = ?, next_action = ?, updated_at = ?
+         WHERE project_id = ? AND session_id = ?`, [input.reason, "stop_after_current", "finish_current_merge_job_then_stop", now, project.id, session.session_id]);
+        }
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "merge_worker.stop_after_current",
+            reason: input.reason,
+            payload: { project_id: project.id, worker_id: targetWorkerId, claimed_jobs: claimed.map((job) => job.protocol_id) }
+        });
+        return { ok: true, stopped: false, stop_after_current: true, worker_id: targetWorkerId, claimed_jobs: claimed, merge_worker: detectMergeWorkerState(context, project.id) };
+    }
+    return {
+        ...stopMergeWorker(context, { projectRoot: project.root, workerId: targetWorkerId, reason: input.reason }),
+        stopped: true,
+        worker_id: targetWorkerId,
+        merge_worker: detectMergeWorkerState(context, project.id)
+    };
+}
+export function oneShotMergeClaim(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const workspacePath = resolveProjectRoot(input.workspacePath ?? project.root);
+    const detection = detectMergeWorkerState(context, project.id);
+    if (detection.state !== "clear") {
+        return { ok: true, claimed: false, mode: "status_only", reason: "active_merge_worker_or_lock", merge_worker: detection, queue: queueForProject(context, project.id) };
+    }
+    ensureLaneWorkspace(context, { projectRoot: project.root, lane: "merge", workspacePath });
+    const lock = acquireLaneLock(context, {
+        projectRoot: project.root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath,
+        ttlSeconds: 300,
+        reason: "one-shot merge"
+    });
+    const claimed = claimNextMergeJob(context, { projectRoot: project.root, workerId: input.workerId, workspacePath });
+    if (!claimed.job) {
+        releaseLaneLock(context, {
+            projectRoot: project.root,
+            lane: "merge",
+            workerId: input.workerId,
+            workspacePath,
+            reason: "one-shot merge no job"
+        });
+    }
+    return {
+        ok: true,
+        claimed: Boolean(claimed.job),
+        mode: "one_shot",
+        job: claimed.job ? withJobGuidance(context, { ...claimed.job }) : null,
+        lock: claimed.job ? lock.lock : null,
+        flow_guidance: claimed.job ? withJobGuidance(context, { ...claimed.job }).flow_guidance : undefined
+    };
+}
+function withJobGuidance(context, job) {
+    const protocolId = typeof job.protocol_id === "string" ? job.protocol_id : "";
+    if (!protocolId)
+        return job;
+    try {
+        const protocol = requireProtocol(context, protocolId);
+        const state = readProtocolRuntimeState(context, protocol).state;
+        return {
+            ...job,
+            flow_guidance: buildStaticFlowGuidance({
+                stage: state.stage,
+                ...(state.flow_contract ? { contract: state.flow_contract } : {}),
+                queueStatus: String(job.status ?? "")
+            })
+        };
+    }
+    catch {
+        return job;
+    }
+}
+function detectMergeWorkerState(context, projectId) {
+    expireProjectLaneLocks(context, projectId);
+    const workers = activeMergeWorkerSessions(context, projectId);
+    const workerIds = [...new Set(workers.map((worker) => worker.worker_id).filter((value) => Boolean(value)))];
+    const claimed = context.db.all(`SELECT protocol_id, claimed_by_session_id, status, updated_at FROM merge_queue
+     WHERE project_id = ? AND status = 'claimed'
+     ORDER BY updated_at DESC, id DESC`, [projectId]);
+    const lock = context.db.get(`SELECT worker_id, status, expires_at, reason FROM lane_locks
+     WHERE project_id = ? AND lane = 'merge' AND status = 'active'
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId]);
+    if (workerIds.length > 1) {
+        return { state: "blocked", reason: "multiple_active_merge_workers", workers };
+    }
+    if (workerIds.length === 1) {
+        return { state: "active_worker", worker_id: workerIds[0], workers, claimed_jobs: claimed.filter((job) => job.claimed_by_session_id === workerIds[0]), lock: lock ?? null };
+    }
+    if (claimed.length > 0) {
+        return { state: "blocked", reason: "claimed_job_without_active_worker", claimed_jobs: claimed, lock: lock ?? null };
+    }
+    if (lock) {
+        return { state: "blocked", reason: "active_merge_lock_without_worker", lock };
+    }
+    return { state: "clear" };
+}
+function activeMergeWorkerSessions(context, projectId) {
+    return context.db.all(`SELECT session_id, worker_id, status, current_stage, next_action, updated_at FROM flow_sessions
+     WHERE project_id = ? AND flow_kind = 'merge_worker' AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')
+     ORDER BY updated_at DESC, rowid DESC`, [projectId]);
+}
+function claimedJobsForWorker(context, projectId, workerId) {
+    return context.db.all(`SELECT protocol_id, claimed_by_session_id, status, updated_at FROM merge_queue
+     WHERE project_id = ? AND status = 'claimed' AND claimed_by_session_id = ?
+     ORDER BY updated_at DESC, id DESC`, [projectId, workerId]);
+}
+function uniqueWorkerId(workers) {
+    const workerIds = [...new Set(workers.map((worker) => worker.worker_id).filter((value) => Boolean(value)))];
+    if (workerIds.length === 0)
+        return undefined;
+    if (workerIds.length > 1) {
+        throw new AppError("merge_worker_ambiguous", "Multiple active merge workers exist; pass --worker-id", 1, { worker_ids: workerIds });
+    }
+    return workerIds[0];
+}