@deksden-com/dd-flow-cli 0.9.0-beta.75 → 0.9.0-beta.79

package/dist/services/plans.js

@@ -4,7 +4,7 @@ import { appendAudit } from "./audit.js";
 import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { requireProjectByRoot } from "./projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { planSummary, planWithProgress, updatePlanProgress } from "./plan-runtime.js";
+import { planSummary, planWithProgress, prepareCanonicalPlan, updatePlanProgress } from "./plan-runtime.js";
 export function getPlanStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const current = planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false });
@@ -20,40 +20,43 @@ export function getPlanStatus(context, input) {
     };
 }
 export function startPlanItem(context, input) {
-    return updatePlanItem(context, input.projectRoot, input.protocolId, input.itemId, (item, plan) => {
-        assertDependenciesClosed(plan, item);
-        return { ...item, status: "in_progress", summary: item.summary || "Started." };
-    });
+    return updatePlanItem(context, { ...input, action: "start" });
 }
 export function completePlanItem(context, input) {
-    return updatePlanItem(context, input.projectRoot, input.protocolId, input.itemId, (item, plan) => {
-        assertDependenciesClosed(plan, item);
-        return { ...item, status: "done", summary: input.summary, evidence: [...new Set([...item.evidence, ...input.evidence])] };
-    });
+    return updatePlanItem(context, { ...input, action: "done" });
 }
 export function blockPlanItem(context, input) {
-    return updatePlanItem(context, input.projectRoot, input.protocolId, input.itemId, (item) => ({
-        ...item,
-        status: "blocked",
-        summary: input.reason,
-        block_reason: input.reason,
-        user_required: input.userRequired
-    }));
+    return updatePlanItem(context, { ...input, action: "block" });
 }
 export function skipPlanItem(context, input) {
-    return updatePlanItem(context, input.projectRoot, input.protocolId, input.itemId, (item) => ({
-        ...item,
-        status: "skipped",
-        summary: input.reason
-    }));
+    return updatePlanItem(context, { ...input, action: "skip" });
 }
-function updatePlanItem(context, projectRoot, protocolId, itemId, transform) {
+export function preparePlanItemMutation(context, input) {
+    const { projectRoot, protocolId, itemId } = input;
+    const text = (value) => typeof value === "string" && value.trim().length > 0;
+    if (!text(itemId) || !["start", "done", "block", "skip"].includes(input.action) ||
+        (input.action === "done" && (!text(input.summary) || !Array.isArray(input.evidence) || !input.evidence.every(text))) ||
+        ((input.action === "block" || input.action === "skip") && !text(input.reason)) ||
+        (input.action === "block" && typeof input.userRequired !== "boolean")) {
+        throw new AppError("validation", "Plan item requires a valid action, item ID, nonempty summary/reason, text evidence and boolean userRequired", 2, { phase: "prepare", effect: "no_effect", recoverable: true });
+    }
     const protocol = scopedProtocol(context, projectRoot, protocolId);
-    const current = planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path });
+    const scope = { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path };
+    const current = planWithProgress(context, scope, { bind: false });
+    prepareCanonicalPlan(context, scope, current.canonical);
     const item = current.plan.items.find((candidate) => candidate.id === itemId);
     if (!item)
         throw new AppError("not_found", `Plan item is not found: ${itemId}`, 1);
-    const nextItem = transform(item, current.plan);
+    if (input.action === "start" || input.action === "done")
+        assertDependenciesClosed(current.plan, item);
+    const nextItem = input.action === "start" ? { ...item, status: "in_progress", summary: item.summary || "Started." }
+        : input.action === "done" ? { ...item, status: "done", summary: input.summary, evidence: [...new Set([...item.evidence, ...input.evidence])] }
+            : input.action === "block" ? { ...item, status: "blocked", summary: input.reason, block_reason: input.reason, user_required: input.userRequired }
+                : { ...item, status: "skipped", summary: input.reason };
+    return { protocol, item, nextItem };
+}
+export function updatePlanItem(context, input) {
+    const { protocol, item, nextItem } = preparePlanItemMutation(context, input);
     updatePlanProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path, item: nextItem });
     if (nextItem.status === "done") {
         context.db.run("UPDATE flow_jobs SET status = 'done', finished_at = COALESCE(finished_at, ?), updated_at = ? WHERE project_id = ? AND protocol_id = ? AND plan_item_id = ?", [context.now(), context.now(), protocol.project_id, protocol.id, nextItem.id]);
@@ -63,7 +66,7 @@ function updatePlanItem(context, projectRoot, protocolId, itemId, transform) {
         protocolId: protocol.id,
         projectId: protocol.project_id,
         eventType: "plan.progress.updated",
-        payload: { protocol_id: protocol.id, item_id: itemId, from: item.status, to: nextItem.status }
+        payload: { protocol_id: protocol.id, item_id: input.itemId, from: item.status, to: nextItem.status }
     });
     return { ok: true, protocol_id: protocol.id, item: nextItem, plan: planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }) };
 }

package/dist/services/projects.js

@@ -37,8 +37,13 @@ export function registerProject(context, input) {
     }
     return { ok: true, project: { ...project, status: "active", updated_at: now }, db_path: context.db.path };
 }
-export function archiveProject(context, input) {
-    const reason = input.reason.trim();
+export function prepareProjectArchive(context, input) {
+    if (Boolean(input.idOrAlias) === Boolean(input.root))
+        throw new AppError("usage", "Project archive requires exactly one project ID/alias or --root", 2);
+    for (const value of [input.idOrAlias, input.root])
+        if (value !== undefined && (typeof value !== "string" || !value.trim()))
+            throw new AppError("validation", "Project archive target must be a non-empty string", 2);
+    const reason = typeof input.reason === "string" ? input.reason.trim() : "";
     if (!reason) {
         throw new AppError("validation", "project archive requires --reason", 2);
     }
@@ -50,6 +55,10 @@ export function archiveProject(context, input) {
     if (!project) {
         throw new AppError("not_found", "Project is not registered.", 1, { root: input.root, input: input.idOrAlias });
     }
+    return { project, reason };
+}
+export function archiveProject(context, input) {
+    const { project, reason } = prepareProjectArchive(context, input);
     const now = context.now();
     const result = context.db.run("UPDATE projects SET status = 'archived', updated_at = ? WHERE id = ? AND status <> 'archived'", [now, project.id]);
     if (result.changes === 1) {

package/dist/services/prompts.js

@@ -9,7 +9,8 @@ import { validatePlanItem } from "../domain/validation.js";
 import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
-import { planWithProgress } from "./plan-runtime.js";
+import { boundCanonicalPlan, planWithProgress, prepareCanonicalPlan } from "./plan-runtime.js";
+import { prepareTextFile } from "../cli/input-preparation.js";
 import { registerFlowJob } from "./sessions.js";
 const profiles = {
     code_implementation: {
@@ -22,7 +23,7 @@ const profiles = {
         static_files: [".memory-bank/dd-flow/common/worker-session.md", ".memory-bank/dd-flow/workers/verify.md"]
     }
 };
-export function renderWorkerPrompt(context, input) {
+export function prepareWorkerPrompt(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const protocol = requireProtocol(context, protocolIdForRun(context, project.id, input.runId), project.id);
@@ -43,8 +44,10 @@ export function renderWorkerPrompt(context, input) {
         projectId: protocol.project_id,
         protocolId: protocol.id,
         planPath: protocol.plan_path
-    });
+    }, { bind: false });
     const plan = planRuntime?.plan ?? null;
+    if (planRuntime)
+        prepareCanonicalPlan(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, planRuntime.canonical);
     const genericTask = input.taskFile ? readWorkerTask(input.taskFile, runHomePath(run)) : null;
     const item = genericTask?.item ?? plan?.items.find((candidate) => candidate.id === input.planItemId);
     if (!item)
@@ -64,13 +67,6 @@ export function renderWorkerPrompt(context, input) {
     const profile = profiles[input.profile];
     if (!profile)
         throw new AppError("prompt_profile_unsupported", `Unsupported prompt profile: ${input.profile}`, 2);
-    const job = registerFlowJob(context, {
-        projectId: protocol.project_id,
-        runId: run.id,
-        protocolId: protocol.id,
-        planItemId: item.id,
-        groupId: item.execution_context.planned_write_areas[0] ?? null
-    });
     const staticInputs = profile.static_files.map((file) => readStaticInput(projectRoot, file));
     const requiredRead = item.execution_context.required_read.map((file) => checkedReference(projectRoot, runHomePath(run), file, "required_read", true));
     const discoveryBoundary = item.execution_context.discovery_boundary.map((file) => checkedReference(projectRoot, runHomePath(run), file, "discovery_boundary", false));
@@ -78,7 +74,6 @@ export function renderWorkerPrompt(context, input) {
     const runHome = runHomePath(run);
     const outputDir = path.join(runHome, stage.dir, "subagents", item.id);
     assertWithin(runHome, outputDir, "output directory");
-    ensureDir(outputDir);
     const prompt = renderPrompt({
         item,
         input,
@@ -90,6 +85,20 @@ export function renderWorkerPrompt(context, input) {
         staticInputs,
         ...(genericTask ? { handoff: genericTask.handoff } : {})
     });
+    return { protocol, run, item, plan, planRuntime, genericTask, workspaceRoot, staticInputs, requiredRead, discoveryBoundary, plannedWriteAreas, outputDir, prompt, canonVersion: readCanonVersion(projectRoot) };
+}
+export function renderWorkerPrompt(context, input, prepared = prepareWorkerPrompt(context, input)) {
+    const { protocol, run, item, plan, planRuntime, genericTask, workspaceRoot, staticInputs, requiredRead, discoveryBoundary, plannedWriteAreas, outputDir, prompt, canonVersion } = prepared;
+    if (planRuntime)
+        boundCanonicalPlan(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, planRuntime.canonical);
+    const job = registerFlowJob(context, {
+        projectId: protocol.project_id,
+        runId: run.id,
+        protocolId: protocol.id,
+        planItemId: item.id,
+        groupId: item.execution_context.planned_write_areas[0] ?? null
+    });
+    ensureDir(outputDir);
     const promptPath = path.join(outputDir, "launch-prompt.md");
     const stackPath = path.join(outputDir, "prompt-stack.json");
     const reportPath = path.join(outputDir, "render-report.json");
@@ -104,7 +113,7 @@ export function renderWorkerPrompt(context, input) {
         plan_item_id: input.taskFile ? null : item.id,
         task_id: input.taskFile ? item.id : null,
         job_id: job.job_id,
-        canon_version: readCanonVersion(projectRoot),
+        canon_version: canonVersion,
         renderer_version: getCliVersionReport().cli.version,
         static_inputs: staticInputs.map(({ path: inputPath, sha256 }) => ({ path: inputPath, sha256 })),
         validation: { required_read: requiredRead, discovery_boundary: discoveryBoundary, planned_write_areas: plannedWriteAreas },
@@ -143,9 +152,7 @@ function runHomePath(run) {
 function readWorkerTask(taskFile, runHome) {
     const resolved = path.resolve(taskFile);
     assertWithin(runHome, resolved, "worker task file");
-    if (!fs.existsSync(resolved))
-        throw new AppError("not_found", "Worker task file is missing", 1, { path: taskFile });
-    const task = parseJsonObject(fs.readFileSync(resolved, "utf8"), resolved);
+    const task = parseJsonObject(prepareTextFile(resolved, "worker task").text, resolved);
     if (task.schema_id !== "dd-flow/worker-task@1" || !task.task || typeof task.task !== "object") {
         throw new AppError("validation", "Worker task must use dd-flow/worker-task@1 with a task object", 2, { path: taskFile });
     }
@@ -180,7 +187,7 @@ function validateWorkerTaskHandoff(value, runHome) {
         const reportPath = path.resolve(report.report_path);
         assertWithin(runHome, reportPath, "predecessor report");
         if (!fs.existsSync(reportPath))
-            throw new AppError("not_found", "Accepted predecessor report is missing", 1, { path: report.report_path });
+            throw new AppError("runtime_artifact_missing", "Accepted predecessor report is missing", 1, { path: report.report_path });
         return { aspect_id: report.aspect_id, verdict, report_path: reportPath };
     });
     const recovery = handoff.recovery_attempt_paths ?? [];

package/dist/services/protocols.js

@@ -6,9 +6,8 @@ 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, planJsonPath, resolveProjectRoot, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
+import { ensureDir, planJsonPath, resolveProjectRoot, resolveProtocolPlanPath, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit, getAuditEvents } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
 import { ensureRuntimeProtocolFiles, readStateFile, writeState } from "../protocol/local-files.js";
@@ -17,14 +16,20 @@ import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProje
 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) {
+export function prepareProtocolRegistration(context, input) {
+    if (typeof input.handshakeId !== "string" || !input.handshakeId.trim() || /[/\\\0]/.test(input.handshakeId) || [".", ".."].includes(input.handshakeId))
+        throw new AppError("validation", "Protocol handshake must be a non-empty identifier, not a path", 2);
     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);
+    return { projectRoot, project, workspacePath, protocolId, runtimeDir };
+}
+export function registerProtocol(context, input) {
+    const { projectRoot, project, workspacePath, protocolId, runtimeDir } = prepareProtocolRegistration(context, input);
+    const now = context.now();
     const state = ensureRuntimeProtocolFiles({
         runtimeDir,
         protocolId,
@@ -243,7 +248,22 @@ export function implementProtocol(context, input) {
         }
     };
 }
-export function transitionProtocol(context, input) {
+export function prepareProtocolTransition(context, input) {
+    const { value } = prepareJsonFile(input.jsonFile, "Protocol transition payload");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "Protocol transition payload must be an object", 2);
+    const payload = value;
+    for (const [key, field] of Object.entries(payload)) {
+        const valid = key === "next_action" ? typeof field === "string"
+            : ["route", "workspace"].includes(key) ? Boolean(field && typeof field === "object" && !Array.isArray(field))
+                : ["blockers", "active_def"].includes(key) && Array.isArray(field);
+        if (!valid)
+            throw new AppError("validation", `Unsupported field or invalid value in protocol transition: ${key}`, 2, { file: input.jsonFile, parameter: key });
+    }
+    protocolTransitionState(context, input);
+    return payload;
+}
+function protocolTransitionState(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const state = readProtocolRuntimeState(context, protocol).state;
@@ -256,8 +276,10 @@ export function transitionProtocol(context, input) {
     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);
+    return { project, protocol, state, flowContract, from, to };
+}
+export function transitionProtocol(context, input, payload = prepareProtocolTransition(context, input)) {
+    const { project, protocol, state, flowContract, from, to } = protocolTransitionState(context, input);
     const nextState = {
         ...state,
         stage: to,
@@ -579,7 +601,10 @@ export function requireProtocol(context, protocolId, projectId) {
             candidates: matches.map((protocol) => ({ project_id: protocol.project_id, project_root: protocol.project_root }))
         });
     }
-    return matches[0];
+    return resolvedProtocolRecord(matches[0]);
+}
+function resolvedProtocolRecord(protocol) {
+    return { ...protocol, plan_path: resolveProtocolPlanPath(protocol.project_root, protocol.id, protocol.plan_path) };
 }
 function cancelQueueForProtocol(context, protocol, reason, force) {
     const job = context.db.get("SELECT id, status, claimed_by_session_id FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
@@ -736,12 +761,20 @@ export function readProtocolRuntimeState(context, protocol) {
     const expected = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
     if (protocol.state_path !== expected)
         throw new AppError("protocol_state_migration_required", "Protocol runtime path requires explicit cleanup scan/apply before use", 1, { protocol_id: protocol.id, path: protocol.state_path, expected_path: expected });
-    return repairProtocolRuntimeState(context, protocol);
+    return resolveProtocolRuntimeState(context, { ...protocol }, false);
 }
 /** Explicit cleanup migration; productive readers accept only the current path. */
 export function repairProtocolRuntimeState(context, protocol) {
+    // Readers project the canonical plan path without migrating storage. Repair
+    // must start from the stored locations, not that already-normalized view.
+    const stored = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [protocol.project_id, protocol.id]);
+    if (stored)
+        Object.assign(protocol, stored);
+    return resolveProtocolRuntimeState(context, protocol, true);
+}
+function resolveProtocolRuntimeState(context, protocol, repair) {
     const diagnostics = [];
-    normalizeProtocolPlanPath(context, protocol, diagnostics);
+    normalizeProtocolPlanPath(context, protocol, diagnostics, repair);
     try {
         if (protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id))
             throw new AppError("protocol_state_migration_required", "Retired state files are not runtime authority", 1);
@@ -759,7 +792,8 @@ export function repairProtocolRuntimeState(context, protocol) {
                 recommended_action: "legacy protocol state_path was moved to stable runtime storage"
             });
             const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
-            context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
+            if (repair && context.db.writable)
+                context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
             protocol.state_path = stableStatePath;
             protocol.plan_path = stablePlanPath;
             return { state: readStateFile(stableStatePath, protocol.id), diagnostics };
@@ -792,7 +826,7 @@ export function repairProtocolRuntimeState(context, protocol) {
         flow_contract: flowContract,
         updated_at: protocol.updated_at
     };
-    if (!context.db.writable) {
+    if (!repair || !context.db.writable) {
         return { state, diagnostics };
     }
     const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
@@ -811,9 +845,9 @@ export function repairProtocolRuntimeState(context, protocol) {
     });
     return { state, diagnostics };
 }
-function normalizeProtocolPlanPath(context, protocol, diagnostics) {
-    const canonicalPlanPath = planJsonPath(protocol.project_root, protocol.id);
-    if (protocol.plan_path === canonicalPlanPath || !fs.existsSync(canonicalPlanPath))
+function normalizeProtocolPlanPath(context, protocol, diagnostics, repair) {
+    const canonicalPlanPath = resolveProtocolPlanPath(protocol.project_root, protocol.id, protocol.plan_path);
+    if (protocol.plan_path === canonicalPlanPath)
         return;
     diagnostics.push({
         code: "protocol_plan_relocated",
@@ -823,7 +857,7 @@ function normalizeProtocolPlanPath(context, protocol, diagnostics) {
         source: "project_canonical_plan",
         recommended_action: "use the project canonical plan as the sole semantic plan source"
     });
-    if (context.db.writable) {
+    if (repair && context.db.writable) {
         context.db.run("UPDATE protocols SET plan_path = ?, updated_at = ? WHERE project_id = ? AND id = ?", [canonicalPlanPath, context.now(), protocol.project_id, protocol.id]);
     }
     protocol.plan_path = canonicalPlanPath;
@@ -884,10 +918,11 @@ export function persistProtocolState(context, protocol, state) {
 }
 function findProtocol(context, protocolId, projectId) {
     if (projectId) {
-        return context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+        const protocol = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+        return protocol ? resolvedProtocolRecord(protocol) : undefined;
     }
     const matches = context.db.all("SELECT * FROM protocols WHERE id = ? ORDER BY project_id", [protocolId]);
-    return matches.length === 1 ? matches[0] : undefined;
+    return matches.length === 1 ? resolvedProtocolRecord(matches[0]) : undefined;
 }
 function protocolDocumentsForProject(projectRoot) {
     const protocolRoot = path.join(projectRoot, ".memory-bank", "protocol");

package/dist/services/recovery-observation-budget.js

@@ -15,7 +15,7 @@ export const recoveryRpcTimeout = (maximum) => {
 /** Call only while holding the existing owner-claim transaction. A replay of
  * an explicit request never replenishes time, even after another request. */
 export function renewRecoveryObservation(snapshot, requestId) {
-    if (!requestId.trim() || requestId.length > 200)
+    if (typeof requestId !== "string" || !requestId.trim() || requestId.length > 200)
         throw new AppError("usage", "Reconciliation requires a nonempty request ID of at most 200 characters", 2);
     const previous = snapshot.recovery_observation;
     const ids = previous?.reconciliation_ids ?? [];

package/dist/services/run-controller-adapter.js

@@ -103,7 +103,7 @@ async function recoverCompletedOperation(context, manifest, session, executable,
     // is reconciled by run-control after the owner is fenced; probing it from the
     // failing transport path would be a second adapter invocation and can itself
     // be mistaken for replay.
-    if (args[0] === "session" && args[1] === "create")
+    if (args[0] === "session" && ["create", "inspect", "status"].includes(args[1]))
         return null;
     // A detached adapter without a native daemon has no durable operation
     // journal to inspect. Avoid a second adapter invocation in that case; the
@@ -131,6 +131,10 @@ async function awaitSettlement(context, row, manifest, session, executable, args
     while (["pending", "blocked"].includes(String(settlement(current)?.state))) {
         if (signal?.aborted)
             throw new AppError("harness_settlement_interrupted", "Harness settlement was interrupted", 1, { operation_id: operationId });
+        // A completed parent with live children is normal controller waiting, not
+        // failed bookkeeping. Keep its budget reserved until a later inspection.
+        if (args[0] === "session" && ["prompt", "inspect", "status"].includes(args[1]) && settlement(current)?.reason === "tree_unsettled")
+            return { ...initial, ...current, ...(initial.assistant_text !== undefined ? { assistant_text: initial.assistant_text } : {}) };
         if (Date.now() >= deadline)
             throw new AppError("settlement_recovery_required", "Completed provider operation requires settlement recovery", 1, { operation_id: operationId, settlement: settlement(current) });
         await new Promise(resolve => setTimeout(resolve, Math.min(delay, Math.max(0, deadline - Date.now()))));
@@ -141,9 +145,14 @@ async function awaitSettlement(context, row, manifest, session, executable, args
         try {
             // This only retries durable bookkeeping against the same operation
             // receipt.  It cannot replay the provider request.
-            current = await runHarnessAdapter({ executable, args: settlementRetryArgs(args, operationId), env: controllerEnvironment(context, manifest, session), operationId: `${operationId}:settlement`, runtimeOwner: session.owner, timeoutMs: Math.min(30_000, Math.max(1, deadline - Date.now())), ...(signal ? { signal } : {}) });
+            const inspect = args[0] === "session" && ["inspect", "status"].includes(args[1]);
+            current = await runHarnessAdapter({ executable, args: inspect ? settlementInspectArgs(args) : settlementRetryArgs(args, operationId), env: controllerEnvironment(context, manifest, session), operationId: `${operationId}:settlement`, runtimeOwner: session.owner, timeoutMs: Math.min(30_000, Math.max(1, deadline - Date.now())), ...(signal ? { signal } : {}) });
+            if (inspect)
+                validateReceipt(current, session, args);
         }
         catch (error) {
+            if (error instanceof AppError && ["session_identity_mismatch", "profile_integrity_violation"].includes(error.code))
+                throw error;
             current = { settlement: { state: "pending", reason: "inspection_error", error: errorRecord(error) } };
         }
         if (!(["pending", "blocked"].includes(String(settlement(current)?.state))))
@@ -154,12 +163,15 @@ async function awaitSettlement(context, row, manifest, session, executable, args
             continue;
         try {
             current = await runHarnessAdapter({ executable, args: settlementInspectArgs(args), env: controllerEnvironment(context, manifest, session), operationId: `${operationId}:settlement-inspect`, runtimeOwner: session.owner, timeoutMs: Math.min(30_000, Math.max(1, deadline - Date.now())), ...(signal ? { signal } : {}) });
+            validateReceipt(current, session, args);
         }
         catch (error) {
+            if (error instanceof AppError && ["session_identity_mismatch", "profile_integrity_violation"].includes(error.code))
+                throw error;
             current = { settlement: { state: "pending", reason: "inspection_error", error: errorRecord(error) } };
         }
     }
-    return current;
+    return adapterSessionId(current) ? { ...initial, ...current, ...(initial.assistant_text !== undefined ? { assistant_text: initial.assistant_text } : {}) } : { ...initial, settlement: settlement(current) };
 }
 export async function controllerAdapter(context, row, manifest, session, args, assertOwner, retainedOperationId, signal) {
     assertOwner?.();
@@ -173,33 +185,32 @@ export async function controllerAdapter(context, row, manifest, session, args, a
     appendEvent(context, row.controller_id, "operation_requested", { operation_id: operationId, operation: args.slice(0, 2), session_id: session.id || null });
     try {
         assertOwner?.();
-        let receipt = await runHarnessAdapter({ executable, args, env: controllerEnvironment(context, manifest, session), operationId, runtimeOwner: session.owner, timeoutMs: args[0] === "session" && args[1] === "prompt" ? null : 120_000, ...(signal ? { signal } : {}) });
+        let receipt;
+        let recoveredOperation = false;
+        try {
+            receipt = await runHarnessAdapter({ executable, args, env: controllerEnvironment(context, manifest, session), operationId, runtimeOwner: session.owner, timeoutMs: args[0] === "session" && args[1] === "prompt" ? null : 120_000, ...(signal ? { signal } : {}) });
+        }
+        catch (error) {
+            const retained = await recoverCompletedOperation(context, manifest, session, executable, args, operationId, signal);
+            if (!retained)
+                throw error;
+            receipt = retained;
+            recoveredOperation = true;
+        }
+        validateReceipt(receipt, session, args);
+        context.db.run("UPDATE run_controller_operations SET receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(receipt), context.now(), operationId]);
         if (["pending", "blocked"].includes(String(settlement(receipt)?.state))) {
             const recovered = await awaitSettlement(context, row, manifest, session, executable, args, operationId, receipt, assertOwner, signal);
-            receipt = { ...receipt, settlement: settlement(recovered) };
+            receipt = recovered;
         }
         context.db.run("UPDATE run_controller_operations SET receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(receipt), context.now(), operationId]);
         validateReceipt(receipt, session, args);
         context.db.run("UPDATE run_controller_operations SET status = 'completed', updated_at = ? WHERE operation_id = ?", [context.now(), operationId]);
         assertOwner?.();
-        appendEvent(context, row.controller_id, "operation_completed", { operation_id: operationId, operation: args.slice(0, 2), session_id: adapterSessionId(receipt) });
+        appendEvent(context, row.controller_id, recoveredOperation ? "operation_recovered" : "operation_completed", { operation_id: operationId, operation: args.slice(0, 2), session_id: adapterSessionId(receipt) });
         return receipt;
     }
     catch (error) {
-        const retained = await recoverCompletedOperation(context, manifest, session, executable, args, operationId, signal);
-        if (retained) {
-            let receipt = retained;
-            if (["pending", "blocked"].includes(String(settlement(receipt)?.state))) {
-                const recovered = await awaitSettlement(context, row, manifest, session, executable, args, operationId, receipt, assertOwner, signal);
-                receipt = { ...receipt, settlement: settlement(recovered) };
-            }
-            context.db.run("UPDATE run_controller_operations SET receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(receipt), context.now(), operationId]);
-            validateReceipt(receipt, session, args);
-            context.db.run("UPDATE run_controller_operations SET status = 'completed', error_json = NULL, updated_at = ? WHERE operation_id = ?", [context.now(), operationId]);
-            assertOwner?.();
-            appendEvent(context, row.controller_id, "operation_recovered", { operation_id: operationId, operation: args.slice(0, 2), session_id: adapterSessionId(receipt) });
-            return receipt;
-        }
         try {
             context.db.run("UPDATE run_controller_operations SET status = CASE WHEN status = 'dispatching' THEN 'outcome_unknown' ELSE status END, error_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify(errorRecord(error)), context.now(), operationId]);
         }

package/dist/services/run-controller-state.js

@@ -20,6 +20,11 @@ export function controllerReceipt(row) {
 }
 export function appendEvent(context, id, type, data) { context.db.run("INSERT INTO run_controller_events (controller_id, event_type, data_json, created_at) VALUES (?, ?, ?, ?)", [id, type, JSON.stringify(data), context.now()]); }
 export function saveState(context, row, state) { context.db.run("UPDATE run_controllers SET state_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [JSON.stringify(state), context.now(), row.controller_id, row.owner_token]); }
+export function retainControllerContinuation(state, fingerprint, error) {
+    if (state.last_continuation === fingerprint)
+        throw new AppError(error.code, error.message, 1, error.details);
+    state.last_continuation = fingerprint;
+}
 export function digest(value) { return digestBytes(JSON.stringify(value)); }
 export function digestBytes(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
 export function errorRecord(error) {