@deksden-com/dd-flow-cli 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @deksden-com/dd-flow-cli
 
+## 0.4.0
+
+### Minor Changes
+
+- Add branch/workspace protocol context for agents: `protocol branch-status`, `branch_context` in protocol and merge JSON outputs, and branch bundle status with eligible, not-ready and claimed protocol lists.
+
+  Add `merge bundle status|claim|complete|fail` commands so a merge worker can integrate one feature branch containing multiple ready protocols under the existing merge lane lock.
+
+### Patch Changes
+
+- cfdcf1d: Fix compatibility status reporting so selected compatible engines advertise `normal_write` in `allowed_modes`; blocked operations are now reported only when a write is actually blocked by missing or incompatible engine resolution.
+
 ## 0.3.1
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.3.1",
-  "cli_commit": "b677e824e7d3b1e6553e7963eeceeb1db02e86db",
-  "built_at": "2026-07-03T20:02:54.356Z",
+  "cli_version": "0.4.0",
+  "cli_commit": "3ab5ed2a5efcd2d1aa8a13a530b94995abe2bd3b",
+  "built_at": "2026-07-05T17:44:47.134Z",
   "built_with_canon": {
-    "version": "2.9.0",
-    "commit": "7e8b51c1321e290d18df3572d6ab26ed32b85403",
+    "version": "2.10.0",
+    "commit": "228a069278ead592d2bee435a33e0da90536227b",
     "flow_contract": "dd-flow-canonical-2026-06",
     "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
     "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",

package/dist/cli/help.js

@@ -24,7 +24,7 @@ Core commands:
   id next                       Preview next typed ids for protocol or run allocation.
   plan set/status/item          Attach and update protocol plans.
   lane workspace/lock/status    Manage shared workspace lanes and leases.
-  merge status/one-shot         Inspect or claim one merge job from the current session.
+  merge status/one-shot/bundle  Inspect, claim, or complete merge work from the current session.
   merge-worker status/start/stop Manage long-lived project merge workers.
   merge-queue status/next       Claim, wait for, complete, or fail merge jobs.
   session register/status/stop  Register flow sessions and stop workers.
@@ -173,6 +173,8 @@ Examples:
 Usage:
   dd-flow protocol register <handshake-id> --project-root <root> [--workspace-path <checkout>] --json
   dd-flow protocol status <protocol-id> --json
+  dd-flow protocol branch-status <protocol-id> --json
+  dd-flow protocol branch-status --project-root <root> --path <workspace> --json
   dd-flow protocol ready --project-root <root> --json
   dd-flow protocol blockers <protocol-id> --project-root <root> --json
   dd-flow protocol implement <protocol-id> --project-root <root> [--force --reason <text>] --json
@@ -181,7 +183,7 @@ Usage:
   dd-flow protocol ready-for-merge <protocol-id> --json
   dd-flow protocol cancel <protocol-id> --reason <text> [--close-sessions true|false] [--cancel-queue true|false] [--release-locks true|false] [--worktree keep|remove] [--force] --json
 
-ready, blockers and implement read protocol markdown frontmatter plus runtime state. implement is a preflight/guidance command: it never performs implementation, refuses unresolved blocked_by_protocols unless --force --reason is supplied, refuses terminal protocols and reports the expected next prompt/stage. transition validates the snapshotted flow contract stored in protocol runtime state, writes an audit event and updates lifecycle fields from the payload. --json-file is accepted as a compatibility alias for --payload-file. sync-from-run repairs legacy protocol/run mismatch from concrete RUN evidence instead of requiring manual runtime JSON edits.
+ready, blockers and implement read protocol markdown frontmatter plus runtime state. branch-status is read-only and reports the current protocol/workspace branch context: sibling protocols in the same branch/worktree, queue status, active sessions and merge bundle eligibility. implement is a preflight/guidance command: it never performs implementation, refuses unresolved blocked_by_protocols unless --force --reason is supplied, refuses terminal protocols and reports the expected next prompt/stage. transition validates the snapshotted flow contract stored in protocol runtime state, writes an audit event and updates lifecycle fields from the payload. --json-file is accepted as a compatibility alias for --payload-file. sync-from-run repairs legacy protocol/run mismatch from concrete RUN evidence instead of requiring manual runtime JSON edits.
 
 The project_root is the stable project identity used for queues, sessions, lanes, and dashboards. Runtime state is stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runtime so feature worktree removal does not break status, cancel, or merge finalization. The optional workspace_path records the concrete checkout where the agent works. With --worktree remove, cancel removes the disposable git worktree recorded in runtime state or worktree records; with --force it also force-deletes the local feature branch when present.`
     ],
@@ -299,10 +301,14 @@ Related lane commands:
         `dd-flow merge - current-session merge entrypoint helpers
 
 Usage:
-  dd-flow merge status --project-root <root> --json
+  dd-flow merge status --project-root <root> [--path <workspace>] --json
   dd-flow merge one-shot --project-root <root> --worker-id <id> [--path <workspace>] --json
+  dd-flow merge bundle status --project-root <root> --path <workspace> --json
+  dd-flow merge bundle claim --project-root <root> --worker-id <id> --path <workspace> --json
+  dd-flow merge bundle complete --project-root <root> --worker-id <id> --path <workspace> --summary <text> --json
+  dd-flow merge bundle fail --project-root <root> --worker-id <id> --path <workspace> --reason <text> --requeue true|false --json
 
-merge status reports active merge worker, claimed protocols, active merge lane lock and queue state. merge one-shot is status-only when a long-lived worker, claimed protocol or active lock exists; otherwise it acquires the merge lane, claims at most one ready protocol, and returns queue_item/protocol/claim plus legacy job for the shared merge job prompt. If no protocol is ready, it releases the lock and returns queue_item: null and job: null.`
+merge status reports active merge worker, claimed protocols, active merge lane lock, queue state and branch_context when --path is provided. merge one-shot keeps legacy single-protocol behavior and also returns branch_context. merge bundle commands operate on all ready protocols in the current branch/worktree: status is read-only, claim requires the merge lane lock owner, complete closes all claimed protocols after branch integration, and fail requeues or fails the claimed bundle.`
     ],
     [
         "merge-worker",
@@ -330,6 +336,10 @@ Usage:
 
 The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing queued protocols. Outputs use queue_item/protocol/claim as the primary contract and retain job as a compatibility alias. note updates the final completion summary after post-complete cleanup and does not require a lane lock. --path defaults to the current working directory. Use --worker-id as the owner identity.
 
+For branch-level integration prefer:
+  dd-flow merge bundle status --project-root "$PWD" --path "$PWD" --json
+  dd-flow merge bundle claim --project-root "$PWD" --worker-id merge-worker --path "$PWD" --json
+
 Examples:
   dd-flow merge-queue wait-next --project-root "$PWD" --worker-id merge-worker --path "$PWD" --timeout 1200 --poll-interval 10 --acquire-lock true --json
   dd-flow merge-queue complete PRT-123 --worker-id merge-worker --path "$PWD" --summary "merged locally; cleanup follows" --json

package/dist/cli/run-cli.js

@@ -5,7 +5,7 @@ import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
 import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
 import { blockPlanItem, completePlanItem, getPlanStatus, setProtocolPlan, skipPlanItem, startPlanItem } from "../services/plans.js";
-import { cancelMergeQueueJob, claimNextMergeJob, completeMergeJob, failMergeJob, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
+import { cancelMergeQueueJob, claimNextMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
 import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
@@ -18,6 +18,7 @@ import { getCliVersionReport } from "../services/build-info.js";
 import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, openGlobalDashboard, openProtocolDashboard, refreshAllDashboards, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
 import { dashboardTargetSummary, preferredDashboardCommand, relatedDashboardCommands, resolveDashboardTarget } from "../services/dashboard-targets.js";
 import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker } from "../services/sessions.js";
+import { getProtocolBranchContext } from "../services/branch-context.js";
 import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, listFlowRuns, startFlowRun } from "../services/runs.js";
 import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
@@ -223,6 +224,18 @@ function renderHumanResult(args, result) {
         const job = record.job;
         lines.push(`job: ${String(job.protocol_id ?? "none")} ${String(job.status ?? "")}`.trim());
     }
+    const branchContext = recordObject(record.branch_context);
+    const mergeBundle = recordObject(branchContext?.merge_bundle);
+    if (branchContext) {
+        lines.push(`branch: ${String(branchContext.feature_branch ?? branchContext.grouping_key ?? "unknown")}`);
+        const protocols = Array.isArray(branchContext.protocols) ? branchContext.protocols.length : 0;
+        lines.push(`branch_protocols: ${protocols}`);
+        if (mergeBundle) {
+            const eligible = Array.isArray(mergeBundle.eligible_protocols) ? mergeBundle.eligible_protocols.length : 0;
+            const notReady = Array.isArray(mergeBundle.not_ready_protocols) ? mergeBundle.not_ready_protocols.length : 0;
+            lines.push(`bundle: ${String(mergeBundle.reason ?? "unknown")} ready=${eligible} not_ready=${notReady}`);
+        }
+    }
     if (record.stopped)
         lines.push(`stopped: ${String(record.reason ?? "true")}`);
     if (record.timed_out)
@@ -422,6 +435,14 @@ async function dispatch(args, context, io) {
     if (family === "protocol" && command === "status") {
         return getProtocolStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
     }
+    if (family === "protocol" && command === "branch-status") {
+        const protocolId = parsed.positional[0];
+        return getProtocolBranchContext(context, {
+            ...(protocolId ? { protocolId } : {}),
+            projectRoot: optionalOption(parsed, "project-root"),
+            workspacePath: optionalOption(parsed, "path")
+        });
+    }
     if (family === "protocol" && command === "ready") {
         return getReadyProtocols(context, { projectRoot: requiredOption(parsed, "project-root") });
     }
@@ -655,7 +676,38 @@ function dispatchMergeQueue(context, command, parsed) {
 }
 function dispatchMerge(context, command, parsed) {
     if (command === "status") {
-        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: optionalOption(parsed, "path") });
+    }
+    if (command === "bundle") {
+        const action = requiredPosition(parsed, 0, "bundle action");
+        if (action === "status") {
+            return getMergeBundleStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: workspacePathOption(parsed) });
+        }
+        if (action === "claim") {
+            return claimMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed)
+            });
+        }
+        if (action === "complete") {
+            return completeMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed),
+                summary: requiredOption(parsed, "summary")
+            });
+        }
+        if (action === "fail") {
+            return failMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed),
+                reason: requiredOption(parsed, "reason"),
+                requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue")
+            });
+        }
+        throw new AppError("usage", `Unknown merge bundle action: ${action}`, 2);
     }
     if (command === "one-shot") {
         return oneShotMergeClaim(context, {

package/dist/services/branch-context.js

@@ -0,0 +1,254 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
+export function getProtocolBranchContext(context, input) {
+    const resolved = resolveBranchContextInput(context, input);
+    const rows = context.db.all(`SELECT id, project_id, project_root, status, stage, next_action, workspace_json, route_json, active_def_json, updated_at
+     FROM protocols
+     WHERE project_id = ?
+     ORDER BY updated_at ASC, id ASC`, [resolved.project.id]);
+    const queues = new Map(context.db
+        .all(`SELECT protocol_id, status, claimed_by_session_id, claimed_at, attempts_count, updated_at
+         FROM merge_queue
+         WHERE project_id = ?`, [resolved.project.id])
+        .map((row) => [row.protocol_id, row]));
+    const worktrees = new Map(context.db
+        .all(`SELECT protocol_id, integration_branch, feature_branch, base_ref, worktree_path, status
+         FROM worktree_records
+         WHERE project_id = ?`, [resolved.project.id])
+        .map((row) => [row.protocol_id, row]));
+    const sessions = context.db.all(`SELECT protocol_id, worker_id, flow_kind, status, current_stage, next_action
+     FROM flow_sessions
+     WHERE project_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [resolved.project.id]);
+    const sessionsByProtocol = new Map();
+    for (const session of sessions) {
+        if (!session.protocol_id)
+            continue;
+        sessionsByProtocol.set(session.protocol_id, [...(sessionsByProtocol.get(session.protocol_id) ?? []), session]);
+    }
+    const candidates = rows.map((row) => summarizeProtocol(row, queues.get(row.id), worktrees.get(row.id), sessionsByProtocol.get(row.id) ?? []));
+    const protocols = candidates.filter((candidate) => protocolMatchesBranch(candidate, resolved));
+    const eligible = protocols.filter((item) => item.bundle_eligible).map((item) => item.id);
+    const notReady = protocols.filter((item) => !item.bundle_eligible && !terminalStage(item.stage) && item.queue_status !== "claimed").map((item) => item.id);
+    const claimed = protocols.filter((item) => item.queue_status === "claimed").map((item) => item.id);
+    const blocked = protocols.filter((item) => item.stage === "blocked" || item.bundle_blockers.length > 0).map((item) => item.id);
+    const diagnostics = branchDiagnostics(resolved);
+    const diagnosticBlockers = diagnostics.filter((item) => item.severity === "error").map((item) => String(item.code));
+    const claimable = eligible.length > 0 && notReady.length === 0 && claimed.length === 0 && blocked.length === 0 && diagnosticBlockers.length === 0;
+    return {
+        ok: true,
+        branch_context: {
+            current_protocol_id: resolved.protocol?.id ?? null,
+            project_id: resolved.project.id,
+            project_root: resolved.project.root,
+            integration_branch: resolved.integrationBranch,
+            feature_branch: resolved.featureBranch,
+            worktree_path: resolved.workspacePath,
+            grouping_key: resolved.groupingKey,
+            git: resolved.git,
+            diagnostics,
+            protocols,
+            merge_bundle: {
+                eligible_protocols: eligible,
+                not_ready_protocols: notReady,
+                claimed_protocols: claimed,
+                blocked_protocols: blocked,
+                claimable,
+                reason: claimable ? "claimable" : bundleReason(eligible, notReady, claimed, blocked, diagnosticBlockers)
+            }
+        }
+    };
+}
+export function requireClaimableBranchBundle(context, input) {
+    const branchContext = getProtocolBranchContext(context, { projectRoot: input.projectRoot, workspacePath: input.workspacePath });
+    const contextBody = branchContext.branch_context;
+    const bundle = contextBody.merge_bundle;
+    if (bundle.claimable !== true) {
+        throw new AppError("merge_bundle_not_claimable", "Branch bundle is not claimable", 1, { branch_context: contextBody });
+    }
+    const protocolIds = Array.isArray(bundle.eligible_protocols) ? bundle.eligible_protocols.map(String) : [];
+    if (protocolIds.length === 0) {
+        throw new AppError("merge_bundle_empty", "Branch bundle has no ready protocols", 1, { branch_context: contextBody });
+    }
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return { project, branchContext, protocolIds };
+}
+function resolveBranchContextInput(context, input) {
+    if (input.protocolId) {
+        const protocol = context.db.get(`SELECT id, project_id, project_root, status, stage, next_action, workspace_json, route_json, active_def_json, updated_at
+       FROM protocols
+       WHERE id = ?`, [input.protocolId]);
+        if (!protocol) {
+            throw new AppError("not_found", `Protocol is not registered: ${input.protocolId}`, 1, { protocol_id: input.protocolId });
+        }
+        const project = requireProjectByRoot(context, protocol.project_root);
+        const workspace = parseRecord(protocol.workspace_json);
+        const worktree = context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocol.id]);
+        const workspacePath = normalizePath(input.workspacePath ?? stringValue(worktree?.worktree_path) ?? stringValue(workspace.worktree_path));
+        const git = gitFacts(workspacePath ?? project.root);
+        const featureBranch = stringValue(worktree?.feature_branch) ?? stringValue(workspace.feature_branch) ?? stringValue(git.actual_branch);
+        return {
+            project,
+            protocol,
+            featureBranch,
+            workspacePath,
+            integrationBranch: stringValue(worktree?.integration_branch) ?? stringValue(workspace.integration_branch),
+            groupingKey: groupingKey(project.id, featureBranch, workspacePath),
+            git: { ...git, matches_runtime: branchMatches(featureBranch, stringValue(git.actual_branch)) }
+        };
+    }
+    if (!input.projectRoot) {
+        throw new AppError("usage", "branch context requires <protocol-id> or --project-root", 2);
+    }
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const workspacePath = normalizePath(input.workspacePath ?? project.root);
+    const git = gitFacts(workspacePath ?? project.root);
+    const featureBranch = stringValue(git.actual_branch);
+    return {
+        project,
+        protocol: null,
+        featureBranch,
+        workspacePath,
+        integrationBranch: null,
+        groupingKey: groupingKey(project.id, featureBranch, workspacePath),
+        git: { ...git, matches_runtime: true }
+    };
+}
+function summarizeProtocol(row, queue, worktree, activeSessions) {
+    const workspace = parseRecord(row.workspace_json);
+    const featureBranch = stringValue(worktree?.feature_branch) ?? stringValue(workspace.feature_branch);
+    const worktreePath = normalizePath(stringValue(worktree?.worktree_path) ?? stringValue(workspace.worktree_path));
+    const activeDef = parseJsonArray(row.active_def_json);
+    const queueStatus = queue?.status ?? null;
+    const bundleBlockers = bundleBlockersFor(row.stage, queueStatus, activeDef.length);
+    return {
+        id: row.id,
+        stage: row.stage,
+        status: row.status,
+        lifecycle: normalizeProtocolLifecycle({ rawStage: row.stage, rawStatus: row.status, queueStatus }),
+        queue_status: queueStatus,
+        queue_claimed_by: queue?.claimed_by_session_id ?? null,
+        active_sessions: activeSessions,
+        integration_branch: stringValue(worktree?.integration_branch) ?? stringValue(workspace.integration_branch),
+        feature_branch: featureBranch,
+        worktree_path: worktreePath,
+        bundle_eligible: ["ready_for_merge", "queued_for_merge"].includes(row.stage) && ["ready", "requeued"].includes(queueStatus ?? "") && activeDef.length === 0,
+        bundle_blockers: bundleBlockers,
+        updated_at: row.updated_at
+    };
+}
+function protocolMatchesBranch(item, resolved) {
+    if (resolved.featureBranch && item.feature_branch) {
+        return item.feature_branch === resolved.featureBranch;
+    }
+    if (resolved.workspacePath && item.worktree_path) {
+        return item.worktree_path === resolved.workspacePath;
+    }
+    return false;
+}
+function gitFacts(workspacePath) {
+    if (!fs.existsSync(workspacePath)) {
+        return { status: "missing_workspace", actual_branch: null, dirty: null, path: workspacePath };
+    }
+    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    if (branch.status !== 0) {
+        return { status: "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
+    }
+    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8" });
+    return {
+        status: "ok",
+        actual_branch: branch.stdout.trim() || null,
+        dirty: status.status === 0 ? status.stdout.trim().length > 0 : null,
+        path: workspacePath
+    };
+}
+function branchDiagnostics(resolved) {
+    const diagnostics = [];
+    if (resolved.git.status !== "ok") {
+        diagnostics.push({ code: "git_workspace_degraded", severity: "warning", summary: `Git workspace status is ${String(resolved.git.status)}` });
+    }
+    if (resolved.featureBranch && resolved.git.actual_branch && resolved.featureBranch !== resolved.git.actual_branch) {
+        diagnostics.push({
+            code: "branch_runtime_mismatch",
+            severity: "error",
+            summary: `Runtime branch ${resolved.featureBranch} does not match Git branch ${String(resolved.git.actual_branch)}.`
+        });
+    }
+    return diagnostics;
+}
+function bundleBlockersFor(stage, queueStatus, activeDefCount) {
+    const blockers = [];
+    if (activeDefCount > 0)
+        blockers.push("active_def");
+    if (stage === "blocked")
+        blockers.push("protocol_blocked");
+    if (queueStatus === "claimed")
+        blockers.push("already_claimed");
+    return blockers;
+}
+function bundleReason(eligible, notReady, claimed, blocked, diagnostics) {
+    if (diagnostics.length > 0)
+        return diagnostics[0] ?? "diagnostic_blocker";
+    if (claimed.length > 0)
+        return "branch_has_claimed_protocols";
+    if (blocked.length > 0)
+        return "branch_has_blocked_protocols";
+    if (notReady.length > 0)
+        return "branch_has_not_ready_protocols";
+    if (eligible.length === 0)
+        return "no_ready_protocols";
+    return "unknown";
+}
+function terminalStage(stage) {
+    return ["closed", "cancelled"].includes(stage);
+}
+function groupingKey(projectId, featureBranch, workspacePath) {
+    if (featureBranch)
+        return `${projectId}:branch:${featureBranch}`;
+    if (workspacePath)
+        return `${projectId}:worktree:${workspacePath}`;
+    return `${projectId}:unknown`;
+}
+function branchMatches(expected, actual) {
+    if (!expected || !actual)
+        return null;
+    return expected === actual;
+}
+function normalizePath(value) {
+    if (!value)
+        return null;
+    const absolute = path.resolve(value);
+    if (fs.existsSync(absolute))
+        return fs.realpathSync(absolute);
+    const parent = path.dirname(absolute);
+    if (fs.existsSync(parent))
+        return path.join(fs.realpathSync(parent), path.basename(absolute));
+    return absolute;
+}
+function parseRecord(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseJsonArray(value) {
+    if (typeof value !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}

package/dist/services/compatibility-preflight.js

@@ -27,6 +27,7 @@ export function preflightCliCompatibility(context, args, env = process.env) {
 }
 export function compatibilityReport(selection, classification) {
     const build = getCliBuildInfo();
+    const normalWriteAllowed = selection.status === "selected" && Boolean(selection.selected);
     return {
         verdict: selection.status === "selected" ? "ok" : "incompatible",
         memorybank_version: selection.memory_bank_version,
@@ -36,9 +37,11 @@ export function compatibilityReport(selection, classification) {
         engine_resolution: selection.status,
         required_engine_range: selection.required_range,
         recommended_engine_version: selection.recommended_version,
-        allowed_modes: ["read_only_diagnostics", "mb_upgrade"],
+        allowed_modes: normalWriteAllowed
+            ? ["read_only_diagnostics", "normal_write", "mb_upgrade"]
+            : ["read_only_diagnostics", "mb_upgrade"],
         operation_mode: classification.mode,
-        blocked_operation: classification.mode === "normal_write" ? classification.operation : null,
+        blocked_operation: classification.mode === "normal_write" && !normalWriteAllowed ? classification.operation : null,
         install_hint: selection.install_hint,
         project_root: selection.project_root,
         diagnostics: selection.diagnostics

package/dist/services/merge-queue.js

@@ -6,6 +6,7 @@ import { persistProtocolState, protocolRunDiagnostics, readProtocolRuntimeState,
 import { resolveProjectRoot } from "../storage/paths.js";
 import { ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, requireLaneLockOwner, waitAcquireLaneLock } from "./lanes.js";
 import { stopMergeWorker, stoppedMergeWorkerState } from "./sessions.js";
+import { getProtocolBranchContext, requireClaimableBranchBundle } from "./branch-context.js";
 const mergeLockTtlSeconds = 300;
 export function getMergeQueueStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -14,6 +15,9 @@ export function getMergeQueueStatus(context, input) {
         queue: queueForProject(context, project.id)
     };
 }
+export function getMergeBundleStatus(context, input) {
+    return getProtocolBranchContext(context, { projectRoot: input.projectRoot, workspacePath: input.workspacePath });
+}
 export function claimNextMergeJob(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const stopState = stoppedMergeWorkerState(context, project.id, input.workerId);
@@ -69,6 +73,67 @@ export function claimNextMergeJob(context, input) {
         claimed: Boolean(claimedProtocolId)
     });
 }
+export function claimMergeBundle(context, input) {
+    const { project, protocolIds } = requireClaimableBranchBundle(context, {
+        projectRoot: input.projectRoot,
+        workspacePath: input.workspacePath
+    });
+    const stopState = stoppedMergeWorkerState(context, project.id, input.workerId);
+    if (stopState.stopped) {
+        throw new AppError("merge_worker_stopped", "Stopped or stopping merge worker cannot claim a merge bundle", 1, {
+            worker_id: input.workerId,
+            status: stopState.status,
+            reason: stopState.reason
+        });
+    }
+    requireLaneLockOwner(context, {
+        projectRoot: project.root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath: input.workspacePath
+    });
+    const now = context.now();
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const protocolId of protocolIds) {
+            const update = context.db.run(`UPDATE merge_queue
+         SET status = 'claimed', claimed_by_session_id = ?, claimed_at = ?, updated_at = ?
+         WHERE protocol_id = ? AND project_id = ? AND status IN ('ready', 'requeued')`, [input.workerId, now, now, protocolId, project.id]);
+            if (update.changes !== 1) {
+                throw new AppError("merge_bundle_claim_race", "Branch bundle changed while claiming", 1, {
+                    protocol_id: protocolId,
+                    protocol_ids: protocolIds
+                });
+            }
+            transitionClaimedProtocolToIntegration(context, protocolId, input.workerId, now);
+            appendAudit(context, {
+                protocolId,
+                projectId: project.id,
+                eventType: "merge_bundle.claimed_protocol",
+                payload: { protocol_id: protocolId, worker_id: input.workerId, protocol_ids: protocolIds }
+            });
+        }
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "merge_bundle.claimed",
+            payload: { project_id: project.id, worker_id: input.workerId, protocol_ids: protocolIds, workspace_path: input.workspacePath }
+        });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return mergeBundleResult(context, {
+        ok: true,
+        outcome: "claimed",
+        claimed: true,
+        projectRoot: project.root,
+        workspacePath: input.workspacePath,
+        workerId: input.workerId,
+        protocolIds
+    });
+}
 export async function waitNextMergeJob(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const timeoutSeconds = input.timeoutSeconds ?? 0;
@@ -251,6 +316,71 @@ export function completeMergeJob(context, input) {
         stop_after_current
     });
 }
+export function completeMergeBundle(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    requireLaneLockOwner(context, {
+        projectRoot: project.root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath: input.workspacePath
+    });
+    const protocolIds = claimedBundleProtocolIds(context, { projectRoot: project.root, workspacePath: input.workspacePath, workerId: input.workerId });
+    if (protocolIds.length === 0) {
+        throw new AppError("merge_bundle_not_claimed", "No claimed protocols found for this branch bundle and worker", 1, {
+            worker_id: input.workerId,
+            workspace_path: input.workspacePath
+        });
+    }
+    const now = context.now();
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const protocolId of protocolIds) {
+            const protocol = requireProtocol(context, protocolId);
+            const job = requireClaimedJob(context, protocolId, input.workerId);
+            context.db.run(`UPDATE merge_queue
+         SET status = 'merged', last_reason = ?, completed_at = ?, updated_at = ?
+         WHERE id = ?`, [input.summary, now, now, job.id]);
+            const state = readProtocolRuntimeState(context, protocol).state;
+            const flowContract = loadProjectFlowContract(protocol.project_root);
+            const targetStage = flowContract.merge_queue.complete.target_stage;
+            const targetStatus = flowContract.stages[targetStage]?.terminal ? targetStage : "running";
+            persistProtocolState(context, protocol, {
+                ...state,
+                stage: targetStage,
+                status: targetStatus,
+                next_action: flowContract.merge_queue.complete.next_action,
+                updated_at: now
+            });
+            appendAudit(context, {
+                protocolId,
+                projectId: project.id,
+                eventType: "merge_bundle.completed_protocol",
+                payload: { protocol_id: protocolId, worker_id: input.workerId, summary: input.summary, protocol_ids: protocolIds }
+            });
+        }
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "merge_bundle.completed",
+            payload: { project_id: project.id, worker_id: input.workerId, summary: input.summary, protocol_ids: protocolIds }
+        });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    const stop_after_current = stopAfterCurrentIfRequested(context, project.id, project.root, input.workerId, "merge bundle complete after stop request");
+    return mergeBundleResult(context, {
+        ok: true,
+        outcome: "merged",
+        merged: true,
+        projectRoot: project.root,
+        workspacePath: input.workspacePath,
+        workerId: input.workerId,
+        protocolIds,
+        stop_after_current
+    });
+}
 export function noteMergeJob(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
     const job = queueJobByProtocol(context, protocol.id);
@@ -319,6 +449,72 @@ export function failMergeJob(context, input) {
         stop_after_current
     });
 }
+export function failMergeBundle(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    requireLaneLockOwner(context, {
+        projectRoot: project.root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath: input.workspacePath
+    });
+    const protocolIds = claimedBundleProtocolIds(context, { projectRoot: project.root, workspacePath: input.workspacePath, workerId: input.workerId });
+    if (protocolIds.length === 0) {
+        throw new AppError("merge_bundle_not_claimed", "No claimed protocols found for this branch bundle and worker", 1, {
+            worker_id: input.workerId,
+            workspace_path: input.workspacePath
+        });
+    }
+    const now = context.now();
+    const status = input.requeue ? "requeued" : "failed";
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const protocolId of protocolIds) {
+            const protocol = requireProtocol(context, protocolId);
+            const job = requireClaimedJob(context, protocolId, input.workerId);
+            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,
+                projectId: project.id,
+                eventType: "merge_bundle.failed_protocol",
+                reason: input.reason,
+                payload: { protocol_id: protocolId, worker_id: input.workerId, requeue: input.requeue, protocol_ids: protocolIds }
+            });
+        }
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "merge_bundle.failed",
+            reason: input.reason,
+            payload: { project_id: project.id, worker_id: input.workerId, requeue: input.requeue, protocol_ids: protocolIds }
+        });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    const stop_after_current = stopAfterCurrentIfRequested(context, project.id, project.root, input.workerId, "merge bundle fail after stop request");
+    return mergeBundleResult(context, {
+        ok: true,
+        outcome: input.requeue ? "requeued" : "failed",
+        projectRoot: project.root,
+        workspacePath: input.workspacePath,
+        workerId: input.workerId,
+        protocolIds,
+        stop_after_current
+    });
+}
 export function cancelMergeQueueJob(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
     const reason = input.reason.trim();
@@ -407,6 +603,23 @@ function mergeQueueResult(job, extra) {
         job: queueItem
     };
 }
+function mergeBundleResult(context, input) {
+    const branchContext = getProtocolBranchContext(context, { projectRoot: input.projectRoot, workspacePath: input.workspacePath }).branch_context;
+    return {
+        ...input,
+        protocol_ids: input.protocolIds,
+        branch_context: branchContext,
+        queue_items: input.protocolIds.map((protocolId) => queueJobByProtocol(context, protocolId) ?? null)
+    };
+}
+function claimedBundleProtocolIds(context, input) {
+    const branchContext = getProtocolBranchContext(context, { projectRoot: input.projectRoot, workspacePath: input.workspacePath }).branch_context;
+    const protocols = Array.isArray(branchContext.protocols) ? branchContext.protocols : [];
+    return protocols
+        .filter((protocol) => protocol.queue_status === "claimed" && protocol.queue_claimed_by === input.workerId)
+        .map((protocol) => String(protocol.id))
+        .filter(Boolean);
+}
 function requireClaimedJob(context, protocolId, sessionId) {
     const job = queueJobByProtocol(context, protocolId);
     if (!job || job.status !== "claimed") {

package/dist/services/merge-worker.js

@@ -7,13 +7,17 @@ import { requireProjectByRoot } from "./projects.js";
 import { buildStaticFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { registerFlowSession, stopMergeWorker } from "./sessions.js";
+import { getProtocolBranchContext } from "./branch-context.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 }))
+        queue: queueForProject(context, project.id).map((job) => withJobGuidance(context, { ...job })),
+        branch_context: input.workspacePath
+            ? getProtocolBranchContext(context, { projectRoot: project.root, workspacePath: input.workspacePath }).branch_context
+            : null
     };
 }
 export function startMergeWorker(context, input) {
@@ -29,7 +33,8 @@ export function startMergeWorker(context, input) {
             outcome: "status_only",
             reason: "merge_worker_already_active",
             merge_worker: detection,
-            queue: queueForProject(context, project.id)
+            queue: queueForProject(context, project.id),
+            branch_context: getProtocolBranchContext(context, { projectRoot: project.root, workspacePath }).branch_context
         };
     }
     ensureLaneWorkspace(context, { projectRoot: project.root, lane: "merge", workspacePath, branch: input.branch });
@@ -98,7 +103,8 @@ export function oneShotMergeClaim(context, input) {
             outcome: "status_only",
             reason: "active_merge_worker_or_lock",
             merge_worker: detection,
-            queue: queueForProject(context, project.id)
+            queue: queueForProject(context, project.id),
+            branch_context: getProtocolBranchContext(context, { projectRoot: project.root, workspacePath }).branch_context
         };
     }
     ensureLaneWorkspace(context, { projectRoot: project.root, lane: "merge", workspacePath });
@@ -143,6 +149,7 @@ export function oneShotMergeClaim(context, input) {
             : null,
         job: claimed.job ? withJobGuidance(context, { ...claimed.job }) : null,
         lock: claimed.job ? lock.lock : null,
+        branch_context: getProtocolBranchContext(context, { projectRoot: project.root, workspacePath }).branch_context,
         flow_guidance: claimed.job ? withJobGuidance(context, { ...claimed.job }).flow_guidance : undefined
     };
 }

package/dist/services/protocols.js

@@ -15,6 +15,7 @@ import { ensureRuntimeProtocolFiles, readPlanFile, readStateFile, writeState } f
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
 import { buildProtocolFlowGuidance } from "./flow-guidance.js";
 import { lifecycleIsTerminalFailure, lifecycleIsTerminalSuccess, normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
+import { getProtocolBranchContext } from "./branch-context.js";
 export function registerProtocol(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -99,6 +100,7 @@ export function getProtocolStatus(context, input) {
         state,
         plan: plan ? summarizePlan(plan) : state.plan,
         merge_queue: queue,
+        branch_context: getProtocolBranchContext(context, { protocolId: protocol.id }).branch_context,
         flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null }),
         worktree: context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocol.id]),
         hook_status: hookStatusForProject(context, protocol.project_id),
@@ -203,6 +205,7 @@ export function implementProtocol(context, input) {
         blockers,
         active_sessions: activeSessions,
         merge_queue: queue ?? null,
+        branch_context: protocol ? getProtocolBranchContext(context, { protocolId: protocol.id }).branch_context : null,
         lifecycle,
         terminal,
         related_context: document.related_context,
@@ -306,6 +309,7 @@ export function readyForMerge(context, input) {
             protocol_id: protocol.id,
             queue_status: existingQueueJob.status,
             state,
+            branch_context: getProtocolBranchContext(context, { protocolId: protocol.id }).branch_context,
             lifecycle: normalizeProtocolLifecycle({ state, queueStatus: existingQueueJob.status }),
             flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: existingQueueJob.status })
         };
@@ -358,6 +362,7 @@ export function readyForMerge(context, input) {
         protocol_id: protocol.id,
         queue_status: "ready",
         state: nextState,
+        branch_context: getProtocolBranchContext(context, { protocolId: protocol.id }).branch_context,
         lifecycle: normalizeProtocolLifecycle({ state: nextState, queueStatus: "ready" }),
         flow_guidance: buildProtocolFlowGuidance({ state: nextState, latestRun: runDiagnostics.latest_run, queueStatus: "ready" })
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {