@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.100

package/dist/services/merge-server.js

@@ -1,10 +1,14 @@
+import { managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { runtimeBudgetForRun } from "./runtime-budget.js";
 import { flowCommand } from "./stage-pause.js";
-import { validateSchema } from "./schema-validation.js";
-import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+import { adapterSessionId, prepareHarnessFlowExecutable, runHarnessAdapter } from "./harness-adapter.js";
+import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
+import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
+import { loadAgentProfile, resolveExecutionPolicy, runtimeHarness } from "./execution-policy.js";
 /** A deterministic dispatcher; only the launched harness Session performs agent work. */
 export async function serveMergeRequests(context, input) {
     const running = context.db.get("SELECT server_id, pid FROM merge_servers WHERE status IN ('running','stopping') ORDER BY started_at LIMIT 1");
@@ -57,62 +61,109 @@ export async function serveMergeRequests(context, input) {
 export function mergeServerStatus(context) { return { ok: true, servers: context.db.all("SELECT server_id, profile_id, status, pid, started_at, heartbeat_at, stopped_at, journal_path FROM merge_servers ORDER BY started_at DESC") }; }
 export function stopMergeServer(context, input) { const changed = context.db.run("UPDATE merge_servers SET status = 'stopping', heartbeat_at = ? WHERE server_id = ? AND status = 'running'", [context.now(), input.serverId]); if (changed.changes !== 1)
     throw new AppError("not_found", "Running merge-server was not found", 1, { server_id: input.serverId }); return { ok: true, server_id: input.serverId, status: "stopping" }; }
+/** Both dispatchers enter the same project FIFO before creating any provider Session. */
+export function claimQueuedMergeRequest(context, input) {
+    context.db.beginWriteTransaction();
+    try {
+        const request = context.db.get("SELECT merge_request_id, project_id, run_id, executor_work_id, target_workspace, execution_route, status, created_at FROM merge_requests WHERE merge_request_id = ?", [input.requestId]);
+        if (!request)
+            throw new AppError("not_found", "MERGE request was not found", 1);
+        const generation = assertRunMutationAllowed(context, request.project_id, request.run_id, input.expectedGeneration);
+        const earlier = context.db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?)) LIMIT 1", [request.project_id, request.created_at, request.created_at, request.merge_request_id]);
+        if (request.status !== "queued" || request.execution_route !== "server" || earlier) {
+            context.db.exec("COMMIT");
+            return null;
+        }
+        const token = crypto.randomUUID();
+        context.db.run("UPDATE merge_requests SET status = 'dispatching', dispatch_owner = ?, dispatch_lease_token = ?, dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued'", [input.ownerId, token, new Date(Date.now() + 120_000).toISOString(), context.now(), request.merge_request_id]);
+        context.db.exec("COMMIT");
+        return { request, token, generation };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
 async function dispatch(context, input) {
-    const token = crypto.randomUUID();
-    const leaseUntil = new Date(Date.now() + 120_000).toISOString();
-    const claimed = context.db.run("UPDATE merge_requests SET status = 'dispatching', dispatch_owner = ?, dispatch_lease_token = ?, dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued' AND execution_route = 'server'", [input.serverId, token, leaseUntil, context.now(), input.request.merge_request_id]);
-    if (claimed.changes !== 1)
+    const run = context.db.get("SELECT index_json, project_root FROM runs WHERE project_id = ? AND id = ?", [input.request.project_id, input.request.run_id]);
+    if (!run)
+        throw new AppError("not_found", "MERGE RUN was not found", 1, { run_id: input.request.run_id });
+    const snapshot = JSON.parse(run.index_json).execution_profile;
+    if (snapshot?.settings?.execution) {
+        if (!snapshot.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "MERGE dispatch requires frozen RUN agent profiles", 1, { run_id: input.request.run_id });
+        const resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: snapshot.settings.execution, profiles: snapshot.agent_profiles, stage: "merge" });
+        input = { ...input, profile: resolved.coordinator };
+    }
+    const claim = claimQueuedMergeRequest(context, { requestId: input.request.merge_request_id, ownerId: input.serverId });
+    if (!claim)
         return;
+    const { generation, token } = claim;
     const stateDir = path.join(input.root, input.request.merge_request_id);
     fs.mkdirSync(stateDir, { recursive: true });
     const promptFile = path.join(stateDir, "launch.md");
     const adapterJournal = path.join(stateDir, "adapter.events.jsonl");
-    const stageCommand = `${flowCommand(context)} stage start ${input.request.run_id} --stage merge --project-root ${JSON.stringify(input.request.target_workspace)} --json --progress-jsonl`;
-    fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
+    const flowExecutable = prepareHarnessFlowExecutable(context, stateDir);
+    let runtimeContext = { ...context, env: { ...context.env, DD_FLOW_BIN: flowExecutable } };
+    const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${input.request.run_id}:merge:${input.request.merge_request_id}`, role: "merge", project_id: input.request.project_id, run_id: input.request.run_id, work_id: input.request.executor_work_id, operation_id: `${input.request.merge_request_id}:${token}`, state_dir: stateDir, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, input.request.project_id, input.request.run_id) };
     event(input.journal, { type: "launch_intent", server_id: input.serverId, request_id: input.request.merge_request_id, token, profile: input.profile, prompt_file: promptFile, at: context.now() });
     input.progress?.(`launching ${input.request.merge_request_id} with ${input.profile.id}`);
-    const executable = context.env[`DD_FLOW_${input.profile.harness.toUpperCase()}_ADAPTER`] ?? `dd-${input.profile.harness}`;
-    const common = ["--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", input.request.target_workspace, "--dd-flow-home", context.ddFlowHome, "--json"];
+    const executable = resolveHarnessCommand(context.ddFlowHome, input.profile.harness, "adapter");
+    const common = ["--dd-flow-bin", flowExecutable, "--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", run.project_root, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, input.profile.harness), "--json"];
+    const retained = { profile: input.profile, executable, owner: runtimeOwner, session_id: null, state_dir: stateDir, create_operation_id: `${input.request.merge_request_id}:${token}:session.create`, prompt_operation_id: `${input.request.merge_request_id}:${token}:session.prompt` };
+    const retain = () => { context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ? AND dispatch_owner = ? AND dispatch_lease_token = ?", [JSON.stringify(retained), context.now(), input.request.merge_request_id, input.serverId, token]); };
+    retain();
+    const leaseHeartbeat = setInterval(() => { if (guarded(context, input.request) || (recoveryGuard(context, input.request.project_id, input.request.run_id)?.generation ?? 0) !== generation)
+        return; const now = context.now(); context.db.run("UPDATE merge_requests SET dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'dispatching' AND dispatch_owner = ? AND dispatch_lease_token = ?", [new Date(Date.now() + 120_000).toISOString(), now, input.request.merge_request_id, input.serverId, token]); }, 30_000);
+    leaseHeartbeat.unref();
     try {
-        const adapterCall = (args, timeoutMs, progressMessage) => runHarnessAdapter({ executable, args, env: context.env, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), ...(progressMessage ? { progressMessage } : {}), onEvidence: (value) => event(input.journal, { type: "adapter_call", ...value }) });
+        const adapterCall = (args, timeoutMs, progressMessage) => { assertRunMutationAllowed(context, input.request.project_id, input.request.run_id, generation); return runHarnessAdapter({ executable, args, env: runtimeContext.env, runtimeOwner, operationId: `${input.request.merge_request_id}:${token}:${args[0]}.${args[1]}`, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), ...(progressMessage ? { progressMessage } : {}), onEvidence: (value) => event(input.journal, { type: "adapter_call", ...value }) }); };
         await adapterCall(["daemon", "start", ...common]);
         const created = await adapterCall(["session", "create", ...common]);
         const sessionId = adapterSessionId(created);
         if (!sessionId)
             throw new AppError("merge_adapter_invalid", "Harness adapter did not return a Session id", 1, { harness: input.profile.harness, response: created });
+        Object.assign(retained, { session_id: sessionId, create: created });
+        retain();
+        runtimeContext = managedInvocationContext(runtimeContext, { harness: runtimeHarness(input.profile), stateDir, sessionId, projectRoot: run.project_root, runId: input.request.run_id, generation });
+        const stageCommand = managedLifecycleCommand(runtimeContext, `${flowCommand(runtimeContext)} stage start ${input.request.run_id} --stage merge --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`);
+        fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
         const prompted = await adapterCall(["session", "prompt", "--session-id", sessionId, "--prompt-file", promptFile, ...common], 45 * 60 * 1000, `MERGE ${input.request.merge_request_id} Session ${sessionId} is still running`);
+        Object.assign(retained, { response: prompted });
+        retain();
+        assertRunMutationAllowed(context, input.request.project_id, input.request.run_id, generation);
         const request = context.db.get("SELECT status FROM merge_requests WHERE merge_request_id = ?", [input.request.merge_request_id]);
-        context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ profile: input.profile, executable, session_id: sessionId, response: prompted }), context.now(), input.request.merge_request_id]);
         event(input.journal, { type: "adapter_settled", request_id: input.request.merge_request_id, session_id: sessionId, request_status: request?.status ?? null, at: context.now() });
         if (request?.status === "dispatching")
-            context.db.run("UPDATE merge_requests SET status = 'queued', dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_did_not_start_stage", response: prompted }), context.now(), input.request.merge_request_id]);
+            context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_did_not_start_stage", response: prompted }), context.now(), input.request.merge_request_id]);
     }
     catch (error) {
+        if (error instanceof AppError && ["run_recovery_guarded", "run_recovery_generation_stale"].includes(error.code)) {
+            event(input.journal, { type: "recovery_dispatch_blocked", request_id: input.request.merge_request_id, code: error.code, at: context.now() });
+            throw error;
+        }
         const request = context.db.get("SELECT status FROM merge_requests WHERE merge_request_id = ?", [input.request.merge_request_id]);
         if (request?.status === "dispatching")
-            context.db.run("UPDATE merge_requests SET status = 'queued', dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_launch_failed", error: String(error) }), context.now(), input.request.merge_request_id]);
+            context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_launch_failed", error: String(error) }), context.now(), input.request.merge_request_id]);
         else if (request?.status === "active")
             context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_lost_after_stage_start", error: String(error) }), context.now(), input.request.merge_request_id]);
         throw error;
     }
+    finally {
+        clearInterval(leaseHeartbeat);
+    }
 }
-function nextServerRequests(context, limit) { const selected = new Set(); return context.db.all("SELECT merge_request_id, project_id, run_id, executor_work_id, target_workspace, execution_route, status, created_at FROM merge_requests WHERE status = 'queued' AND execution_route = 'server' ORDER BY created_at, merge_request_id").filter((request) => { if (selected.has(request.project_id) || context.db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?)) LIMIT 1", [request.project_id, request.created_at, request.created_at, request.merge_request_id]))
+function nextServerRequests(context, limit) { const selected = new Set(); return context.db.all("SELECT merge_request_id, project_id, run_id, executor_work_id, target_workspace, execution_route, status, created_at FROM merge_requests WHERE status = 'queued' AND execution_route = 'server' ORDER BY created_at, merge_request_id").filter((request) => { if (guarded(context, request) || selected.has(request.project_id) || context.db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled','superseded') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?)) LIMIT 1", [request.project_id, request.created_at, request.created_at, request.merge_request_id]))
     return false; selected.add(request.project_id); return true; }).slice(0, limit); }
-function reconcileExpiredDispatches(context) { const expired = context.db.all("SELECT merge_request_id, executor_work_id FROM merge_requests WHERE status = 'dispatching' AND dispatch_lease_expires_at < ?", [context.now()]); for (const request of expired) {
+function reconcileExpiredDispatches(context) { const expired = context.db.all("SELECT merge_request_id, executor_work_id, project_id, run_id FROM merge_requests WHERE status = 'dispatching' AND dispatch_lease_expires_at < ?", [context.now()]); for (const request of expired) {
+    if (guarded(context, request))
+        continue;
     const work = context.db.get("SELECT status FROM works WHERE work_id = ?", [request.executor_work_id]);
-    if (work?.status === "created")
-        context.db.run("UPDATE merge_requests SET status = 'queued', dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "expired_dispatch_requeued" }), context.now(), request.merge_request_id]);
-    else
-        context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "expired_dispatch_with_started_work", work_status: work?.status ?? null }), context.now(), request.merge_request_id]);
+    context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "expired_dispatch_outcome_unknown", work_status: work?.status ?? null }), context.now(), request.merge_request_id]);
 } }
-function loadProfile(context, id) { const file = path.join(context.ddFlowHome, "agent-profiles", `${id}.json`); let value; try {
-    value = JSON.parse(fs.readFileSync(file, "utf8"));
-}
-catch (error) {
-    throw new AppError("agent_profile_missing", "Merge-server agent profile is unavailable", 1, { id, file, cause: String(error) });
-} validateSchema({ schemaName: "agent-profile", file }); if (value.id !== id)
-    throw new AppError("agent_profile_invalid", "Agent profile id does not match its requested filename", 2, { file, expected: id, actual: value.id ?? null }); return value; }
+function loadProfile(context, id) { return loadAgentProfile(context.ddFlowHome, id); }
 function event(file, value) { fs.appendFileSync(file, `${JSON.stringify(value)}\n`); }
+function guarded(context, request) { const guard = recoveryGuard(context, request.project_id, request.run_id); return Boolean(guard && ["draining", "sealed", "resuming"].includes(guard.status)); }
 function delay(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
 function processAlive(pid) { if (!pid)
     return false; try {

package/dist/services/migrations.js

@@ -10,6 +10,7 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityContexts, selectEngine } from "./engines.js";
 import { getCliBuildInfo } from "./build-info.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
 export function assessMigrationImpact(context, input) {
     const root = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd: process.cwd() });
     if (!root.root)
@@ -147,7 +148,7 @@ export function planMigration(context, input) {
         }
     };
 }
-export function applyMigration(context, input) {
+export function prepareMigrationApply(context, input) {
     const classification = input.classification ?? classifyCliOperation(["migration", "apply"], context.env);
     if (classification.mode !== "mb_upgrade") {
         throw new AppError("upgrade_authorization_required", "Migration apply requires explicit mb-upgrade authorization", 1, {
@@ -197,6 +198,13 @@ export function applyMigration(context, input) {
         });
     }
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const current = activeStateSummary(context, project.id);
+    if (activeStateBlockers(current).length)
+        throw new AppError("migration_active_state", "Migration apply requires a quiescent shared home", 1, { active_state: current });
+    return { project, sourceVersion, targetVersion, verifiedBackup, reportEngine, chain };
+}
+export function applyMigration(context, input, prepared = prepareMigrationApply(context, input)) {
+    const { project, sourceVersion, targetVersion, verifiedBackup, reportEngine, chain } = prepared;
     const writeDb = getDatabase(context.ddFlowHome, "migrate");
     const already = writeDb.get("SELECT value_json FROM runtime_config WHERE key = ?", [applyKey(project.id, sourceVersion, targetVersion)]);
     if (already) {
@@ -217,7 +225,10 @@ export function applyMigration(context, input) {
         chain: chain.steps.map((step) => ({ ...step, status: "applied" }))
     };
     try {
-        writeDb.exec("BEGIN IMMEDIATE");
+        writeDb.beginWriteTransaction();
+        const current = activeStateSummary({ ...context, db: writeDb }, project.id);
+        if (activeStateBlockers(current).length)
+            throw new AppError("migration_active_state", "Migration apply requires a quiescent shared home", 1, { active_state: current });
         writeDb.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at) VALUES (?, ?, ?, ?)`, [applyKey(project.id, sourceVersion, targetVersion), JSON.stringify(result), context.now(), context.now()]);
         writeDb.exec("COMMIT");
     }
@@ -513,13 +524,7 @@ function activeStateBlockers(active) {
     return blockers;
 }
 function readJsonObject(filePath) {
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    }
-    catch (error) {
-        throw new AppError("invalid_json", `Cannot read migration report: ${filePath}`, 2, { cause: String(error) });
-    }
+    const { value: parsed } = prepareJsonFile(filePath, "Migration report");
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new AppError("validation", "Migration report must be a JSON object", 2, { file: filePath });
     }

package/dist/services/native-daemon-history.js

@@ -0,0 +1,49 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { managedProcessBinding, managedProcessStatus, processTreeIsAlive, resourceHome } from "./managed-processes.js";
+import { retainedDaemonOperations } from "./run-control.js";
+import { managedProviderBelongsToDaemon } from "./managed-daemon-binding.js";
+/** A replaced daemon is a settled resource, never another Session to resume. */
+export function historicalDaemonSettlement(context, scopeId, record) {
+    const metadata = JSON.parse(record.metadata_json);
+    if (!record.kind.endsWith("-daemon") || !metadata.state_dir || !path.isAbsolute(metadata.state_dir))
+        throw new AppError("runtime_scope_owner_unknown", "Native history requires an absolute daemon directory", 1);
+    const current = JSON.parse(fs.readFileSync(path.join(metadata.state_dir, "daemon.json"), "utf8"));
+    if (current.resource_process?.id === record.id)
+        return null;
+    if (record.state !== "stopped" || record.termination_reason !== "daemon_stopped" || !record.pid || !record.pid_started_at || processTreeIsAlive(record))
+        throw new AppError("runtime_scope_owner_unknown", "Previous daemon has no physical completion proof", 1);
+    const directory = path.join(metadata.state_dir, "daemon-history");
+    const matches = fs.readdirSync(directory).filter(name => /^[a-zA-Z0-9-]+\.json$/.test(name)).map(name => {
+        const file = path.join(directory, name);
+        if (!fs.lstatSync(file).isFile())
+            throw new AppError("runtime_scope_owner_unknown", "Daemon history must contain regular receipts", 1);
+        const bytes = fs.readFileSync(file, "utf8");
+        return { file, bytes, state: JSON.parse(bytes) };
+    }).filter(candidate => candidate.state.resource_process?.id === record.id);
+    if (matches.length !== 1)
+        throw new AppError("runtime_scope_owner_unknown", "Previous daemon has no unique retained receipt", 1);
+    const { file, bytes, state } = matches[0], owner = state.config?.runtime_owner;
+    if (!state.daemon_id || path.basename(file) !== `${state.daemon_id}.json` || !owner || owner.budget?.scope_id !== scopeId || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.state_dir !== metadata.state_dir || owner.adapter_executable !== metadata.adapter_executable || owner.dd_flow_home !== metadata.dd_flow_home || owner.resource_home !== resourceHome(context) || (owner.project_id ?? null) !== record.project_id || (owner.run_id ?? null) !== record.run_id || (owner.work_id ?? null) !== record.work_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || state.resource_process?.lease_token !== record.lease_token || state.pid !== record.pid)
+        throw new AppError("runtime_scope_owner_unknown", "Archived daemon does not match its registration", 1);
+    const closed = state.shutdown_state === "clean" && state.active_tree === false
+        ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && operation.result?.clean === true) : undefined;
+    const fresh = managedProcessStatus(context).find(item => item.id === record.id);
+    if (!closed || !fresh || fresh.lease_token !== record.lease_token || fresh.pid !== record.pid || fresh.pid_started_at !== record.pid_started_at || fresh.metadata_json !== record.metadata_json || fresh.state !== "stopped" || fresh.termination_reason !== "daemon_stopped" || processTreeIsAlive(fresh) || fs.readFileSync(file, "utf8") !== bytes)
+        throw new AppError("runtime_scope_outcome_unknown", "Previous daemon lacks stable clean shutdown evidence", 1);
+    const providers = managedProcessStatus(context).filter(item => managedProviderBelongsToDaemon(item, fresh, state));
+    if (state.provider_process && (providers.length !== 1 || providers[0].state !== "stopped" || providers[0].termination_reason !== "daemon_stopped" || !providers[0].operation_id?.startsWith(`${owner.operation_id}:`) || processTreeIsAlive(providers[0])))
+        throw new AppError("runtime_scope_outcome_unknown", "Archived provider lacks its exact physical completion proof", 1);
+    return { historical: true, process_id: record.id, role: metadata.role, state_dir: metadata.state_dir, daemon_id: state.daemon_id,
+        processes: providers.map(item => ({ process_id: item.id, native_settled: true, binding: managedProcessBinding(item, resourceHome(context)) })),
+        settled: true, native_settled: true, operation_id: String(closed.operation_id), owner_operation_id: owner.operation_id,
+        inventory_version: crypto.createHash("sha256").update(JSON.stringify([bytes, closed])).digest("hex") };
+}
+export function assertHistoricalDaemonSettlement(context, scopeId, proof) {
+    const record = managedProcessStatus(context).find(item => item.id === proof.process_id);
+    const fresh = record && historicalDaemonSettlement(context, scopeId, record);
+    if (!fresh || proof.historical !== true || proof.native_settled !== true || fresh.inventory_version !== proof.inventory_version)
+        throw new AppError("runtime_scope_inventory_changed", "Archived daemon settlement changed after observation", 1);
+}

package/dist/services/native-session-control.js

@@ -0,0 +1,39 @@
+import { AppError } from "../shared/errors.js";
+import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+export async function cancelControlledNativeSession(input) {
+    input.assertCurrent();
+    const reply = await runHarnessAdapter({ executable: input.executable,
+        args: input.observe ? ["daemon", "operation", "--operation-id", input.operationId, "--state-dir", input.stateDir, "--json"] : ["session", "cancel", "--session-id", input.sessionId, "--state-dir", input.stateDir, "--json"],
+        env: input.env, operationId: input.observe ? `${input.operationId}:observe` : input.operationId, timeoutMs: 30_000 });
+    if (input.observe && (reply.operation_id !== input.operationId || reply.operation !== "session.cancel" || reply.session_id !== input.sessionId))
+        throw new AppError("controller_operation_mismatch", "Cancellation observation belongs to another operation or Session", 1);
+    if (input.observe && reply.state === "failed") {
+        if (!reply.error || typeof reply.error !== "object" || Array.isArray(reply.error))
+            throw new AppError("controller_operation_mismatch", "Cancellation failure has no terminal error", 1);
+        input.assertCurrent();
+        return { status: "failed", receipt: reply };
+    }
+    const result = input.observe ? reply.state === "completed" ? reply.result : null : reply;
+    // A completed cancel command is an immutable ACK, not proof that the
+    // provider tree has stopped. Callers must use a separate fresh inspection.
+    if (!input.observe || reply.state === "completed")
+        assertNativeCancellationReceipt(result, input.sessionId);
+    input.assertCurrent();
+    return { status: result ? "completed" : "outcome_unknown", receipt: (result ?? reply) };
+}
+export function assertNativeCancellationReceipt(value, sessionId) {
+    const identity = adapterSessionId(value);
+    if (!value || typeof value !== "object" || Array.isArray(value) || identity && identity !== sessionId)
+        throw new AppError("controller_operation_mismatch", "Cancellation receipt has no valid result for its target Session", 1);
+}
+/** Native observation is shared by RUN and non-Work EVAL owners. */
+export async function inspectControlledNativeSession(input) {
+    input.assertCurrent();
+    const receipt = await runHarnessAdapter({ executable: input.executable, args: ["session", "inspect", "--session-id", input.sessionId, "--state-dir", input.stateDir, ...(input.settlementObservation ? ["--no-flow"] : []), "--json"], env: input.env, operationId: input.operationId, timeoutMs: 30_000 });
+    if (adapterSessionId(receipt) !== input.sessionId)
+        throw new AppError("controller_operation_mismatch", "Session observation belongs to another target", 1);
+    if (input.harness && receipt.harness !== undefined && receipt.harness !== input.harness)
+        throw new AppError("controller_operation_mismatch", "Session observation belongs to another harness", 1);
+    input.assertCurrent();
+    return receipt;
+}

package/dist/services/plan-runtime.js

@@ -6,17 +6,23 @@ import { parseJsonObject } from "../shared/json.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 export function readCanonicalPlan(planPath, protocolId) {
     if (!fs.existsSync(planPath) || !fs.statSync(planPath).isFile()) {
-        throw new AppError("not_found", `Canonical protocol plan is missing: ${planPath}`, 1, { plan_path: planPath });
+        throw new AppError("runtime_artifact_missing", `Canonical protocol plan is missing: ${planPath}`, 1, { plan_path: planPath });
     }
     const raw = fs.readFileSync(planPath, "utf8");
-    const value = parseJsonObject(raw, planPath);
-    const plan = validatePlan(value, protocolId);
-    const revisionValue = value.revision;
-    const revision = typeof revisionValue === "number" && Number.isInteger(revisionValue) && revisionValue > 0 ? revisionValue : 1;
-    return { plan, raw, sha256: crypto.createHash("sha256").update(raw).digest("hex"), revision };
+    try {
+        const value = parseJsonObject(raw, planPath);
+        const plan = validatePlan(value, protocolId);
+        const revisionValue = value.revision;
+        const revision = typeof revisionValue === "number" && Number.isInteger(revisionValue) && revisionValue > 0 ? revisionValue : 1;
+        return { plan, raw, sha256: crypto.createHash("sha256").update(raw).digest("hex"), revision };
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "validation")
+            throw error;
+        throw new AppError("runtime_artifact_invalid", "Canonical protocol plan is invalid", 1, { plan_path: planPath, cause_code: error.code });
+    }
 }
-export function boundCanonicalPlan(context, input) {
-    const canonical = readCanonicalPlan(input.planPath, input.protocolId);
+export function prepareCanonicalPlan(context, input, canonical = readCanonicalPlan(input.planPath, input.protocolId)) {
     const binding = context.db.get("SELECT plan_revision, plan_sha256, plan_path FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [input.projectId, input.protocolId]);
     if (binding && (binding.plan_revision !== canonical.revision || binding.plan_sha256 !== canonical.sha256)) {
         throw new AppError("plan_stale", "Canonical plan changed after the runtime binding was created", 1, {
@@ -28,6 +34,11 @@ export function boundCanonicalPlan(context, input) {
             plan_path: input.planPath
         });
     }
+    return canonical;
+}
+export function boundCanonicalPlan(context, input, prepared) {
+    const canonical = prepareCanonicalPlan(context, input, prepared);
+    const binding = context.db.get("SELECT plan_revision, plan_sha256, plan_path FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [input.projectId, input.protocolId]);
     const now = context.now();
     if (!binding) {
         context.db.run(`INSERT INTO plan_bindings (project_id, protocol_id, plan_revision, plan_sha256, plan_path, bound_at, updated_at)

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/portable-refs.js

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export function assertPortableArtifactRef(value, input) {
+    const parsed = parseArtifactRef(value);
+    let file;
+    let root;
+    if (parsed.path.startsWith("run://")) {
+        const prefix = `run://${input.runId}/`;
+        if (!parsed.path.startsWith(prefix) || parsed.path.slice(prefix.length).split("/").includes(".."))
+            throw new AppError("invalid_evidence_ref", "Artifact RUN reference must stay in the current RUN", 2, { ref: value });
+        root = input.runHome;
+        file = path.join(root, parsed.path.slice(prefix.length));
+    }
+    else {
+        root = input.workspaceRoot;
+        if (!parsed.path)
+            throw new AppError("invalid_evidence_ref", "Artifact reference must name a file", 2, { ref: value });
+        file = path.isAbsolute(parsed.path) ? parsed.path : path.join(root, parsed.path);
+    }
+    if (!fs.existsSync(file))
+        throw new AppError("evidence_ref_missing", "Artifact reference does not exist", 2, { ref: value, resolved_path: file });
+    const realRoot = fs.realpathSync(root);
+    const realFile = fs.realpathSync(file);
+    if (!contained(realRoot, realFile))
+        throw new AppError("invalid_evidence_ref", "Artifact reference must stay inside its declared workspace", 2, { ref: value, resolved_path: realFile, root: realRoot });
+    if (parsed.lines)
+        validateLineRanges(realFile, parsed.lines, value);
+    return realFile;
+}
+function parseArtifactRef(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw new AppError("invalid_evidence_ref", "Artifact reference must be a non-empty string", 2, { ref: value });
+    const [rawPath, ...fragments] = value.split("#");
+    if (fragments.length > 1 || (fragments.length === 1 && !fragments[0]))
+        throw new AppError("invalid_evidence_ref", "Artifact reference has an invalid fragment", 2, { ref: value });
+    const match = rawPath.match(/^(.*):(\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$/);
+    if (!match)
+        return { path: rawPath, fragment: fragments[0] ?? null, lines: null };
+    const lines = match[2].split(",").map((item) => {
+        const [startText, endText] = item.split("-");
+        const start = Number(startText);
+        const end = Number(endText ?? startText);
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start)
+            throw new AppError("invalid_evidence_ref", "Artifact line ranges must be positive and ordered", 2, { ref: value, range: item });
+        return { start, end };
+    });
+    return { path: match[1], fragment: fragments[0] ?? null, lines };
+}
+function contained(root, file) { const relative = path.relative(root, file); return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative)); }
+function validateLineRanges(file, ranges, ref) {
+    const source = fs.readFileSync(file, "utf8");
+    const lines = source === "" ? 0 : source.replace(/\r?\n$/, "").split(/\r?\n/).length;
+    const invalid = ranges.find((range) => range.end > lines);
+    if (invalid)
+        throw new AppError("evidence_line_out_of_range", "Artifact line range exceeds the referenced file", 2, { ref, file, line_count: lines, invalid_range: invalid });
+}

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) {
@@ -140,7 +149,7 @@ export function migrateProjectIds(context, input) {
         throw new AppError("conflict", `Target project id already exists: ${target.id}`, 1, plan);
     }
     context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         context.db.run("UPDATE projects SET id = ?, short_id = ?, slug = ?, state_root = ?, updated_at = ? WHERE id = ?", [target.id, target.short_id, target.slug, target.state_root, now, oldId]);
         for (const table of projectReferenceTables()) {
@@ -232,9 +241,13 @@ export function findProjectByRoot(context, root) {
     return context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
 }
 export function requireProjectByRoot(context, root) {
-    const project = findProjectByRoot(context, root);
+    // Callers may receive a path through a native adapter or shell.  Resolve
+    // aliases such as macOS `/var` -> `/private/var` before comparing with the
+    // canonical root persisted in the project registry.
+    const canonical = normalizeStoredRoot(root);
+    const project = findProjectByRoot(context, canonical);
     if (!project) {
-        throw new AppError("not_found", `Project is not registered: ${root}`, 1);
+        throw new AppError("not_found", `Project is not registered: ${canonical}`, 1);
     }
     return project;
 }