@deksden-com/dd-flow-cli 0.1.0

package/dist/services/protocols.js

@@ -0,0 +1,606 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { canTransition } from "../domain/contracts.js";
+import { defaultFlowContract, flowContractForState, loadProjectFlowContract } from "../domain/flow-contract.js";
+import { requireStage } from "../domain/validation.js";
+import { AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+import { ensureReadableFile } from "../storage/database.js";
+import { ensureDir, resolveProjectRoot, runtimePlanJsonPath, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
+import { appendAudit, getAuditEvents } from "./audit.js";
+import { requireProjectByRoot } from "./projects.js";
+import { ensureRuntimeProtocolFiles, readPlanFile, readStateFile, writeState } from "../protocol/local-files.js";
+import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
+export function registerProtocol(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const now = context.now();
+    const workspacePath = input.workspacePath ? resolveProjectRoot(input.workspacePath) : undefined;
+    const idRoot = workspacePath ?? projectRoot;
+    const protocolId = inferProtocolId(idRoot, input.handshakeId);
+    const runtimeDir = runtimeProtocolDir(context.ddFlowHome, project.id, protocolId);
+    const state = ensureRuntimeProtocolFiles({
+        runtimeDir,
+        protocolId,
+        projectRoot,
+        handshakeId: input.handshakeId,
+        workspacePath,
+        now
+    });
+    const existing = findProtocol(context, protocolId);
+    const params = [
+        protocolId,
+        input.handshakeId,
+        project.id,
+        projectRoot,
+        state.status,
+        state.stage,
+        state.next_action,
+        JSON.stringify(state.route),
+        JSON.stringify(state.workspace),
+        JSON.stringify(state.blockers),
+        JSON.stringify(state.active_def),
+        runtimeStateJsonPath(context.ddFlowHome, project.id, protocolId),
+        runtimePlanJsonPath(context.ddFlowHome, project.id, protocolId),
+        existing?.created_at ?? now,
+        now
+    ];
+    context.db.run(`INSERT INTO protocols
+      (id, handshake_id, project_id, project_root, status, stage, next_action,
+       route_json, workspace_json, blockers_json, active_def_json, state_path, plan_path,
+       created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       handshake_id = excluded.handshake_id,
+       project_id = excluded.project_id,
+       project_root = excluded.project_root,
+       status = excluded.status,
+       stage = excluded.stage,
+       next_action = excluded.next_action,
+       route_json = excluded.route_json,
+       workspace_json = excluded.workspace_json,
+       blockers_json = excluded.blockers_json,
+       active_def_json = excluded.active_def_json,
+       state_path = excluded.state_path,
+       plan_path = excluded.plan_path,
+       updated_at = excluded.updated_at`, params);
+    appendAudit(context, {
+        protocolId,
+        projectId: project.id,
+        eventType: existing ? "protocol.registration_refreshed" : "protocol.registered",
+        payload: {
+            protocol_id: protocolId,
+            handshake_id: input.handshakeId,
+            project_root: projectRoot,
+            workspace_path: workspacePath ?? null,
+            runtime_dir: runtimeDir
+        }
+    });
+    return { ok: true, protocol: protocolStatusPayload(requireProtocol(context, protocolId)), state };
+}
+export function getProtocolStatus(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const runtime = readProtocolRuntimeState(context, protocol);
+    const state = runtime.state;
+    const plan = readPlanFile(protocol.plan_path);
+    return {
+        ok: true,
+        protocol: protocolStatusPayload(protocol),
+        diagnostics: runtime.diagnostics,
+        state,
+        plan: plan ? summarizePlan(plan) : state.plan,
+        merge_queue: context.db.get("SELECT * FROM merge_queue WHERE protocol_id = ?", [protocol.id]),
+        worktree: context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocol.id]),
+        hook_status: hookStatusForProject(context, protocol.project_id),
+        codex_home_profiles: codexHomeProfilesForProject(context, protocol.project_id),
+        flow_sessions: activeFlowSessionBindingsForProject(context, protocol.project_id).filter((session) => session.protocol_id === protocol.id),
+        codex_session_bindings: activeCodexSessionBindingsForProject(context, protocol.project_id).filter((binding) => binding.protocol_id === protocol.id),
+        codex_hook_events: codexHookEventsForProject(context, protocol.project_id).filter((event) => event.protocol_id === protocol.id),
+        audit: getAuditEvents(context, protocol.id)
+    };
+}
+export function transitionProtocol(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const flowContract = flowContractForState(state);
+    const from = requireStage(state.stage, flowContract);
+    const to = requireStage(input.to, flowContract);
+    if (!input.force && !canTransition(from, to, flowContract)) {
+        throw new AppError("invalid_transition", `Transition ${from} -> ${to} requires --force --reason`, 1);
+    }
+    if (input.force && (!input.reason || input.reason.trim().length === 0)) {
+        throw new AppError("validation", "Forced transitions require --reason", 2);
+    }
+    ensureReadableFile(input.jsonFile);
+    const payload = parseJsonObject(fs.readFileSync(input.jsonFile, "utf8"), input.jsonFile);
+    const nextState = {
+        ...state,
+        stage: to,
+        status: statusForStage(to, flowContract),
+        next_action: typeof payload.next_action === "string" ? payload.next_action : state.next_action,
+        route: objectOrExisting(payload.route, state.route),
+        workspace: objectOrExisting(payload.workspace, state.workspace),
+        blockers: Array.isArray(payload.blockers) ? payload.blockers : state.blockers,
+        active_def: Array.isArray(payload.active_def) ? payload.active_def : state.active_def,
+        updated_at: context.now()
+    };
+    persistProtocolState(context, protocol, nextState);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "protocol.transition",
+        forced: input.force,
+        ...(input.reason ? { reason: input.reason } : {}),
+        payload: { from, to, payload, flow_contract_id: flowContract.id, flow_contract_version: flowContract.version }
+    });
+    return { ok: true, protocol_id: protocol.id, from, to, forced: input.force, state: nextState };
+}
+export function readyForMerge(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const flowContract = flowContractForState(state);
+    const stage = requireStage(state.stage, flowContract);
+    if (!flowContract.readiness.allowed_from.includes(stage)) {
+        throw new AppError("readiness_invalid_stage", "Protocol state does not allow ready-for-merge", 1, {
+            stage: state.stage,
+            allowed: flowContract.readiness.allowed_from,
+            flow_contract_id: flowContract.id
+        });
+    }
+    const missing = readinessMissingFields(state);
+    if (missing.length > 0) {
+        throw new AppError("readiness_missing_fields", "Protocol is missing explicit readiness fields", 1, { missing });
+    }
+    if (state.active_def.length > 0) {
+        throw new AppError("readiness_blocked", "Protocol has open deferrals", 1, { active_def: state.active_def });
+    }
+    const plan = readPlanFile(protocol.plan_path);
+    const openRequired = plan?.items.filter((item) => item.required && !["done", "skipped"].includes(item.status)) ?? [];
+    if (openRequired.length > 0) {
+        throw new AppError("readiness_plan_open", "Protocol has open required plan items", 1, {
+            items: openRequired.map((item) => ({ id: item.id, status: item.status }))
+        });
+    }
+    const now = context.now();
+    const nextStage = flowContract.readiness.target_stage;
+    const nextState = { ...state, stage: nextStage, status: statusForStage(nextStage, flowContract), updated_at: now };
+    persistProtocolState(context, protocol, nextState);
+    const existingQueueJob = context.db.get("SELECT status FROM merge_queue WHERE protocol_id = ?", [
+        protocol.id
+    ]);
+    if (existingQueueJob && ["claimed", "merged", "cancelled", "failed"].includes(existingQueueJob.status)) {
+        appendAudit(context, {
+            protocolId: protocol.id,
+            projectId: protocol.project_id,
+            eventType: "protocol.ready_for_merge_unchanged",
+            payload: { protocol_id: protocol.id, queue_status: existingQueueJob.status, flow_contract_id: flowContract.id }
+        });
+        return { ok: true, protocol_id: protocol.id, queue_status: existingQueueJob.status, state: nextState };
+    }
+    context.db.run(`INSERT INTO merge_queue
+       (protocol_id, project_id, status, claimed_by_session_id, claimed_at, completed_at, created_at, updated_at)
+     VALUES (?, ?, ?, NULL, NULL, NULL, ?, ?)
+     ON CONFLICT(protocol_id) DO UPDATE SET
+       status = excluded.status,
+       claimed_by_session_id = NULL,
+       claimed_at = NULL,
+       completed_at = NULL,
+       updated_at = excluded.updated_at`, [protocol.id, protocol.project_id, "ready", now, now]);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "protocol.ready_for_merge",
+        payload: { protocol_id: protocol.id, queue_status: "ready", flow_contract_id: flowContract.id }
+    });
+    return { ok: true, protocol_id: protocol.id, queue_status: "ready", state: nextState };
+}
+export function cancelProtocol(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const reason = input.reason.trim();
+    if (!reason) {
+        throw new AppError("validation", "protocol cancel requires --reason", 2);
+    }
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const now = context.now();
+    const worktree = context.db.get("SELECT worktree_path, status FROM worktree_records WHERE protocol_id = ?", [protocol.id]);
+    const worktreeRemoval = input.worktree === "remove" ? removeProtocolWorktreeBeforeCancel(protocol, state, worktree, input.force) : undefined;
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const nextState = {
+            ...state,
+            stage: "cancelled",
+            status: "cancelled",
+            next_action: "cancelled",
+            updated_at: now
+        };
+        persistProtocolState(context, protocol, nextState);
+        let cancelledQueue = { ok: true, skipped: true, reason: "option_disabled" };
+        if (input.cancelQueue) {
+            cancelledQueue = cancelQueueForProtocol(context, protocol, reason, input.force);
+        }
+        let closedSessions = 0;
+        if (input.closeSessions) {
+            const result = context.db.run(`UPDATE flow_sessions
+         SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+         WHERE project_id = ?
+           AND protocol_id = ?
+           AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, protocol.project_id, protocol.id]);
+            closedSessions = Number(result.changes);
+        }
+        const lockRelease = input.releaseLocks
+            ? releaseRelatedMergeLocks(context, protocol, reason)
+            : { ok: true, skipped: true, reason: "option_disabled" };
+        let worktreeOutcome = { ok: true, skipped: true, reason: input.worktree === "keep" ? "keep_requested" : "no_active_worktree" };
+        if (input.worktree === "remove") {
+            const nextWorktreeStatus = worktreeRemoval?.status ?? "removed";
+            const result = worktree
+                ? context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ?
+             WHERE protocol_id = ? AND status = 'active'`, [nextWorktreeStatus, now, now, protocol.id])
+                : { changes: 0 };
+            worktreeOutcome = {
+                ok: true,
+                changed: result.changes === 1,
+                status: nextWorktreeStatus,
+                reason: worktreeRemoval?.reason ?? "path_absent_or_no_record",
+                source: worktreeRemoval?.source ?? "none",
+                path: worktreeRemoval?.path ?? null,
+                physical_removed: worktreeRemoval?.physical_removed ?? false,
+                branch: worktreeRemoval?.branch ?? { ok: true, skipped: true, reason: "no_feature_branch" }
+            };
+        }
+        appendAudit(context, {
+            protocolId: protocol.id,
+            projectId: protocol.project_id,
+            eventType: "protocol.cancelled",
+            reason,
+            forced: input.force,
+            payload: {
+                protocol_id: protocol.id,
+                close_sessions: input.closeSessions,
+                cancel_queue: input.cancelQueue,
+                release_locks: input.releaseLocks,
+                worktree: input.worktree,
+                closed_sessions: closedSessions,
+                queue: cancelledQueue,
+                lock_release: lockRelease,
+                worktree_outcome: worktreeOutcome
+            }
+        });
+        context.db.exec("COMMIT");
+        return {
+            ok: true,
+            protocol_id: protocol.id,
+            state: nextState,
+            queue: cancelledQueue,
+            closed_sessions: closedSessions,
+            lock_release: lockRelease,
+            worktree_outcome: worktreeOutcome,
+            worktree: context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocol.id]) ?? null
+        };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function requireProtocol(context, protocolId) {
+    const protocol = findProtocol(context, protocolId);
+    if (!protocol) {
+        throw new AppError("not_found", `Protocol is not registered: ${protocolId}`, 1);
+    }
+    return protocol;
+}
+function cancelQueueForProtocol(context, protocol, reason, force) {
+    const job = context.db.get("SELECT id, status, claimed_by_session_id FROM merge_queue WHERE protocol_id = ?", [protocol.id]);
+    if (!job) {
+        return { ok: true, skipped: true, reason: "no_queue_job" };
+    }
+    if (job.status === "cancelled") {
+        return { ok: true, cancelled: false, reason: "already_cancelled", job };
+    }
+    if (job.status === "claimed" && !force) {
+        throw new AppError("merge_job_claimed", "Claimed queue cancellation requires --force --reason", 1, {
+            protocol_id: protocol.id,
+            claimed_by_session_id: job.claimed_by_session_id
+        });
+    }
+    if (["merged", "failed"].includes(job.status) && !force) {
+        throw new AppError("merge_job_terminal", `Queue job is ${job.status}; cancellation requires --force --reason`, 1, {
+            protocol_id: protocol.id,
+            status: job.status
+        });
+    }
+    context.db.run("UPDATE merge_queue SET status = 'cancelled', last_reason = ?, updated_at = ? WHERE id = ?", [
+        reason,
+        context.now(),
+        job.id
+    ]);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "merge_queue.cancelled",
+        reason,
+        forced: force,
+        payload: { protocol_id: protocol.id, from: job.status, source: "protocol_cancel" }
+    });
+    return { ok: true, cancelled: true, from: job.status };
+}
+function removeProtocolWorktreeBeforeCancel(protocol, state, record, force) {
+    const stateWorkspace = state.workspace;
+    const rawPath = record?.worktree_path || (typeof stateWorkspace.worktree_path === "string" ? stateWorkspace.worktree_path : "");
+    const source = record?.worktree_path ? "record" : "state";
+    if (!rawPath) {
+        return {
+            status: "removed",
+            reason: "path_absent_or_no_record",
+            source: "state",
+            path: "",
+            physical_removed: false,
+            branch: { ok: true, skipped: true, reason: "no_feature_branch" }
+        };
+    }
+    const worktreePath = path.resolve(rawPath);
+    const projectRoot = path.resolve(protocol.project_root);
+    if (worktreePath === projectRoot) {
+        throw new AppError("worktree_is_project_root", "Refusing to remove the stable project root as a feature worktree", 1, {
+            path: worktreePath,
+            project_root: projectRoot
+        });
+    }
+    const cwd = path.resolve(process.cwd());
+    if (cwd === worktreePath || cwd.startsWith(`${worktreePath}${path.sep}`)) {
+        throw new AppError("worktree_current_cwd", "Refusing to remove the current process working directory", 1, {
+            path: worktreePath,
+            cwd
+        });
+    }
+    const existsBefore = fs.existsSync(worktreePath);
+    if (existsBefore && !force) {
+        const dirty = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
+        if (dirty.status === 0 && dirty.stdout.trim().length > 0) {
+            throw new AppError("worktree_dirty", "Refusing to remove dirty worktree without --force --reason", 1, {
+                path: worktreePath
+            });
+        }
+    }
+    let physicalRemoved = false;
+    if (existsBefore) {
+        const args = ["-C", projectRoot, "worktree", "remove"];
+        if (force)
+            args.push("--force");
+        args.push(worktreePath);
+        const removed = spawnSync("git", args, { encoding: "utf8" });
+        if (removed.status !== 0) {
+            throw new AppError("worktree_remove_failed", "Git failed to remove the feature worktree", 1, {
+                path: worktreePath,
+                exit_code: removed.status,
+                stderr: removed.stderr.trim()
+            });
+        }
+        physicalRemoved = !fs.existsSync(worktreePath);
+    }
+    const featureBranch = record?.feature_branch ||
+        (typeof stateWorkspace.feature_branch === "string" && stateWorkspace.feature_branch.trim()
+            ? stateWorkspace.feature_branch.trim()
+            : "");
+    const branch = removeLocalFeatureBranch(projectRoot, featureBranch, force);
+    const existsAfter = fs.existsSync(worktreePath);
+    return {
+        status: existsAfter ? "kept" : "removed",
+        reason: existsAfter ? "physical_checkout_kept" : existsBefore ? "physical_checkout_removed" : "path_absent",
+        source,
+        path: worktreePath,
+        physical_removed: physicalRemoved,
+        branch
+    };
+}
+function removeLocalFeatureBranch(projectRoot, branch, force) {
+    if (!branch)
+        return { ok: true, skipped: true, reason: "no_feature_branch" };
+    const listed = spawnSync("git", ["-C", projectRoot, "branch", "--list", branch], { encoding: "utf8" });
+    if (listed.status !== 0 || listed.stdout.trim().length === 0) {
+        return { ok: true, skipped: true, reason: "branch_absent", branch };
+    }
+    const deleted = spawnSync("git", ["-C", projectRoot, "branch", force ? "-D" : "-d", branch], { encoding: "utf8" });
+    if (deleted.status !== 0) {
+        return {
+            ok: false,
+            skipped: true,
+            reason: force ? "branch_delete_failed" : "branch_not_merged",
+            branch,
+            stderr: deleted.stderr.trim()
+        };
+    }
+    return { ok: true, skipped: false, reason: force ? "branch_force_deleted" : "branch_deleted", branch };
+}
+function releaseRelatedMergeLocks(context, protocol, reason) {
+    const workers = context.db.all(`SELECT DISTINCT worker_id FROM flow_sessions
+     WHERE project_id = ? AND protocol_id = ? AND worker_id IS NOT NULL`, [protocol.project_id, protocol.id]).map((row) => row.worker_id).filter((workerId) => Boolean(workerId));
+    const job = context.db.get("SELECT claimed_by_session_id FROM merge_queue WHERE protocol_id = ?", [protocol.id]);
+    if (job?.claimed_by_session_id) {
+        workers.push(job.claimed_by_session_id);
+    }
+    const uniqueWorkers = [...new Set(workers)];
+    const released = [];
+    const now = context.now();
+    for (const workerId of uniqueWorkers) {
+        const lock = context.db.get(`SELECT id, worker_id FROM lane_locks
+       WHERE project_id = ? AND lane = 'merge' AND status = 'active' AND worker_id = ?
+       ORDER BY updated_at DESC, id DESC LIMIT 1`, [protocol.project_id, workerId]);
+        if (!lock) {
+            continue;
+        }
+        context.db.run(`UPDATE lane_locks SET status = 'released', released_at = ?, reason = ?, updated_at = ? WHERE id = ?`, [now, reason, now, lock.id]);
+        appendAudit(context, {
+            projectId: protocol.project_id,
+            eventType: "lane_lock.released",
+            reason,
+            payload: { project_id: protocol.project_id, lane: "merge", worker_id: workerId, lock_id: lock.id, source: "protocol_cancel" }
+        });
+        released.push({ lock_id: lock.id, worker_id: workerId });
+    }
+    return { ok: true, released: released.length, locks: released };
+}
+export function readProtocolRuntimeState(context, protocol) {
+    const diagnostics = [];
+    try {
+        return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
+    }
+    catch {
+        const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+        if (protocol.state_path !== stableStatePath && fs.existsSync(stableStatePath)) {
+            diagnostics.push({
+                code: "runtime_state_relocated",
+                severity: "warning",
+                old_path: protocol.state_path,
+                path: stableStatePath,
+                source: "stable_runtime_state",
+                recommended_action: "legacy protocol state_path was moved to stable runtime storage"
+            });
+            const stablePlanPath = runtimePlanJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+            context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE id = ?", [stableStatePath, stablePlanPath, protocol.id]);
+            protocol.state_path = stableStatePath;
+            protocol.plan_path = stablePlanPath;
+            return { state: readStateFile(stableStatePath, protocol.id), diagnostics };
+        }
+        diagnostics.push({
+            code: "runtime_state_missing",
+            severity: "warning",
+            path: protocol.state_path,
+            source: "protocols.state_path",
+            recommended_action: "runtime state reconstructed from SQLite; run cleanup scan/apply if this persists"
+        });
+    }
+    const plan = context.db.get("SELECT plan_json FROM plans WHERE protocol_id = ?", [protocol.id]);
+    const planSummary = plan
+        ? planSummaryForState(JSON.parse(plan.plan_json))
+        : { plan_id: null, total: 0, done: 0, blocked: 0 };
+    const flowContract = loadProjectFlowContract(protocol.project_root);
+    const state = {
+        schema_version: "0.1.0",
+        protocol_id: protocol.id,
+        project_root: protocol.project_root,
+        status: protocol.status,
+        stage: requireStage(protocol.stage, flowContract),
+        next_action: protocol.next_action,
+        route: JSON.parse(protocol.route_json),
+        workspace: JSON.parse(protocol.workspace_json),
+        plan: planSummary,
+        blockers: JSON.parse(protocol.blockers_json),
+        active_def: JSON.parse(protocol.active_def_json),
+        flow_contract: flowContract,
+        updated_at: protocol.updated_at
+    };
+    const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    const stablePlanPath = runtimePlanJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    ensureDir(path.dirname(stableStatePath));
+    writeState(stableStatePath, state);
+    context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE id = ?", [stableStatePath, stablePlanPath, protocol.id]);
+    const repairedFrom = protocol.state_path;
+    protocol.state_path = stableStatePath;
+    protocol.plan_path = stablePlanPath;
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "protocol.runtime_state_repaired",
+        payload: { protocol_id: protocol.id, path: stableStatePath, repaired_from: repairedFrom, source: "sqlite" }
+    });
+    return { state, diagnostics };
+}
+export function persistProtocolState(context, protocol, state) {
+    ensureDir(path.dirname(protocol.state_path));
+    writeState(protocol.state_path, state);
+    context.db.run(`UPDATE protocols SET
+       status = ?, stage = ?, next_action = ?, route_json = ?, workspace_json = ?,
+       blockers_json = ?, active_def_json = ?, updated_at = ?
+     WHERE id = ?`, [
+        state.status,
+        state.stage,
+        state.next_action,
+        JSON.stringify(state.route),
+        JSON.stringify(state.workspace),
+        JSON.stringify(state.blockers),
+        JSON.stringify(state.active_def),
+        state.updated_at,
+        protocol.id
+    ]);
+    if (state.status === "closed" || state.stage === "closed") {
+        const now = context.now();
+        context.db.run(`UPDATE flow_sessions
+       SET status = 'stopped', stop_reason = 'protocol closed', updated_at = ?, stopped_at = ?
+       WHERE project_id = ?
+         AND protocol_id = ?
+         AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [now, now, protocol.project_id, protocol.id]);
+    }
+}
+function findProtocol(context, protocolId) {
+    return context.db.get("SELECT * FROM protocols WHERE id = ?", [protocolId]);
+}
+function inferProtocolId(projectRoot, handshakeId) {
+    const directDir = path.join(projectRoot, ".memory-bank", "protocol", handshakeId);
+    if (fs.existsSync(directDir)) {
+        return handshakeId;
+    }
+    if (handshakeId.startsWith("PRT-")) {
+        return handshakeId;
+    }
+    return `PRT-${handshakeId.replace(/[^a-zA-Z0-9_-]+/g, "-")}`;
+}
+function statusForStage(stage, flowContract = defaultFlowContract) {
+    if (stage === "blocked" ||
+        stage === "waiting_for_user" ||
+        stage === "closed" ||
+        stage === "cancelled" ||
+        stage === "ready_for_merge" ||
+        flowContract.stages[stage]?.terminal) {
+        return stage;
+    }
+    return "running";
+}
+function objectOrExisting(value, existing) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : existing;
+}
+function protocolStatusPayload(protocol) {
+    return {
+        id: protocol.id,
+        handshake_id: protocol.handshake_id,
+        project_id: protocol.project_id,
+        project_root: protocol.project_root,
+        status: protocol.status,
+        stage: protocol.stage,
+        next_action: protocol.next_action,
+        route: JSON.parse(protocol.route_json),
+        workspace: JSON.parse(protocol.workspace_json),
+        state_path: protocol.state_path,
+        plan_path: protocol.plan_path,
+        updated_at: protocol.updated_at
+    };
+}
+function summarizePlan(plan) {
+    return planSummaryForState(plan);
+}
+function planSummaryForState(plan) {
+    return {
+        plan_id: plan.plan_id,
+        total: plan.items.length,
+        done: plan.items.filter((item) => item.status === "done").length,
+        blocked: plan.items.filter((item) => item.status === "blocked").length
+    };
+}
+function readinessMissingFields(state) {
+    const missing = [];
+    if (!state.protocol_id)
+        missing.push("protocol_id");
+    if (!state.project_root)
+        missing.push("project_root");
+    if (state.route.git === "feature_worktree") {
+        if (typeof state.workspace.feature_branch !== "string" || state.workspace.feature_branch.length === 0) {
+            missing.push("workspace.feature_branch");
+        }
+        if (typeof state.workspace.worktree_path !== "string" || state.workspace.worktree_path.length === 0) {
+            missing.push("workspace.worktree_path");
+        }
+    }
+    return missing;
+}