@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/assigned-lifecycle.js

@@ -0,0 +1,382 @@
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { storageSessionId } from "./session-identity.js";
+import { runtimeHarness } from "./execution-policy.js";
+import { requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { appendAudit } from "./audit.js";
+import { commandOption, commandPosition, continuationCommand, parseLifecycleCommand } from "./lifecycle-command.js";
+import { processStartedAt } from "./managed-processes.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hookSessionIdentity, assertStageStartHookEvent, claimStageStartHookEvent } from "./hooks.js";
+const owned = new WeakMap();
+const assignmentEvent = "lifecycle.controller_assignment";
+function refuse(reason) { throw new AppError("invocation_assignment_unproven", "Managed command has no current assigned execution", 1, { reason, effect: "no_effect", recoverable: false, reconciliation_required: true }); }
+function parsed(command) { const value = parseLifecycleCommand(command); return value.kind === "standalone" ? value.invocation : null; }
+function stageEntryFence(context, scope, stage) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE id=? AND project_root=?", [scope.runId, scope.projectRoot]);
+    const index = row ? JSON.parse(row.index_json) : null;
+    return JSON.stringify([index?.current_stage ?? null, index?.stage_runs?.find((item) => item.stage === stage) ?? null, index?.variables?.["merge.source_repair"]?.cycle ?? null]);
+}
+/** Called by the controller after native creation/resolution, before dispatch. */
+export function retainControllerStageAssignment(context, command, input) {
+    const scope = JSON.parse(context.env.DD_FLOW_INVOCATION_SCOPE ?? "null");
+    const invocation = parsed(command);
+    if (!scope?.runId || !invocation || invocation.operation !== "stage_start" || commandOption(invocation, "stage") !== input.stage)
+        refuse("stage_issuance_scope");
+    const rows = context.db.all("SELECT * FROM lifecycle_invocations WHERE scope_json=? AND status='issued'", [JSON.stringify(scope)])
+        .filter(row => { const item = parsed(row.command); return item?.operation === "stage_start" && commandOption(item, "stage") === input.stage && commandOption(item, "context-sha256") === input.contextSha256; });
+    if (rows.length !== 1)
+        refuse("stage_issuance_ambiguous");
+    const controller = context.db.get("SELECT * FROM run_controllers WHERE controller_id=?", [input.controllerId]);
+    if (!controller || controller.run_id !== scope.runId || controller.generation !== scope.generation || ["completed", "cancelled", "superseded"].includes(controller.status))
+        refuse("controller_stale");
+    const state = JSON.parse(controller.state_json);
+    const session = state.current_session === null ? undefined : state.sessions[state.current_session];
+    if (!session || session.id !== input.sessionId || session.state_dir !== input.stateDir || session.stopped || session.retired)
+        refuse("controller_session_changed");
+    const binding = requireManagedDaemonBinding(context, { stateDir: input.stateDir, projectId: controller.project_id, runId: controller.run_id, ownerId: input.controllerId });
+    const native = binding.state.sessions?.find(item => typeof item === "string" ? item === input.sessionId : item.adapter_session_id === input.sessionId || item.provider_session_id === input.sessionId);
+    const nativeId = typeof native === "string" ? native : native?.provider_session_id;
+    const rootId = typeof native === "string" ? native : native?.root_provider_session_id ?? native?.provider_session_id;
+    if (!nativeId || rootId !== scope.rootSessionId || binding.state.daemon_id !== scope.daemonId)
+        refuse("native_create_mapping_unavailable");
+    const harness = runtimeHarness(session.profile);
+    const identity = { source: "controller_assignment", hookEventId: null, harness, providerSessionId: nativeId,
+        parentSessionId: null, daemonId: scope.daemonId, agentId: null, sessionId: storageSessionId({ harness_id: harness, session_id: nativeId }), nativeSessionId: nativeId,
+        turnId: null, transcriptPath: null, provider: session.profile.provider ?? null, model: null, reasoning: null, mode: null, agentType: null, cwd: session.cwd };
+    const payload = { invocation_id: rows[0].id, scope, controller_id: input.controllerId, owner_token: controller.owner_token,
+        stage_entry_fence: stageEntryFence(context, scope, input.stage), adapter_session_id: input.sessionId,
+        stage: input.stage, context_sha256: input.contextSha256, attempt: input.attempt ?? null, cycle: input.cycle ?? null, identity };
+    const prior = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.invocation_id')=?", [controller.project_id, assignmentEvent, rows[0].id]);
+    if (prior) {
+        if (prior.payload_json !== JSON.stringify(payload))
+            refuse("stage_assignment_changed");
+        return;
+    }
+    appendAudit(context, { projectId: controller.project_id, eventType: assignmentEvent, payload });
+}
+/** Resolve immutable packet membership; a readable UUID or env is not ownership. */
+export function assignedLifecycleBinding(context, row) {
+    const scope = JSON.parse(row.scope_json);
+    const invocation = parsed(row.command);
+    if (!invocation || !scope.runId)
+        return null;
+    const operation = invocation.operation;
+    if (operation === "stage_start") {
+        const retained = context.db.get("SELECT payload_json FROM audit_events WHERE event_type=? AND json_extract(payload_json,'$.invocation_id')=?", [assignmentEvent, row.id]);
+        if (!retained)
+            return null;
+        const launch = JSON.parse(retained.payload_json);
+        if (JSON.stringify(launch.scope) !== row.scope_json || launch.stage !== commandOption(invocation, "stage") || launch.context_sha256 !== commandOption(invocation, "context-sha256"))
+            refuse("stage_packet_changed");
+        const owner = context.db.get("SELECT generation,owner_token,status,state_json FROM run_controllers WHERE controller_id=?", [launch.controller_id]);
+        const state = owner && JSON.parse(owner.state_json);
+        if (!owner || owner.owner_token !== launch.owner_token || stageEntryFence(context, scope, launch.stage) !== launch.stage_entry_fence || owner.generation !== scope.generation || ["completed", "cancelled", "superseded"].includes(owner.status) || !state || state.current_session === null || state.sessions[state.current_session]?.id !== launch.adapter_session_id || state.sessions[state.current_session]?.stopped || state.sessions[state.current_session]?.retired)
+            refuse("stage_owner_changed");
+        return { schema_id: "dd-flow/assigned-lifecycle-admission@1", kind: "managed_assignment", invocation_id: row.id, scope, operation,
+            work_id: null, work_session_id: null, controller_id: launch.controller_id, controller_owner: { token: launch.owner_token, session_id: launch.adapter_session_id }, stage: launch.stage, identity: launch.identity };
+    }
+    if (!["work_finish", "work_fail", "stage_finish", "stage_pause", "stage_resume"].includes(operation))
+        return null;
+    const stage = commandOption(invocation, "stage") ?? null;
+    const target = operation.startsWith("work_") ? commandPosition(invocation, 0) : commandOption(invocation, "work");
+    const matches = context.db.all(`SELECT DISTINCT ws.id,ws.work_id,ws.session_id,ws.start_receipt_json,s.harness,s.provider_session_id,s.parent_session_id,s.cwd,he.daemon_id
+     FROM lifecycle_packet_assignments pa JOIN work_sessions ws ON (pa.packet_sha256=json_extract(ws.start_receipt_json,'$.prompt_sha256')
+       OR EXISTS (SELECT 1 FROM audit_events a WHERE a.event_type='lifecycle.coordinator_packet'
+         AND json_extract(a.payload_json,'$.work_session_id')=ws.id AND json_extract(a.payload_json,'$.packet_sha256')=pa.packet_sha256))
+     JOIN works w ON w.work_id=ws.work_id JOIN projects p ON p.id=w.project_id
+     JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id
+     LEFT JOIN hook_events he ON he.project_id=w.project_id AND he.event_key=ws.hook_event_id
+     WHERE pa.invocation_id=? AND p.root=? AND w.run_id=? AND ws.status='running' AND ws.start_publication_status='published'
+       AND w.status IN ('running','paused')`, [row.id, scope.projectRoot, scope.runId])
+        .filter(item => (!target || item.work_id === target || item.work_id.match(/^WRK-\d+/)?.[0] === target));
+    if (!matches.length)
+        return null;
+    if (matches.length !== 1)
+        refuse("ambiguous_packet_owner");
+    const item = matches[0];
+    if (operation !== "stage_resume" && item.daemon_id && item.daemon_id !== scope.daemonId)
+        refuse("work_daemon_changed");
+    const projectId = context.db.get("SELECT id FROM projects WHERE root=?", [scope.projectRoot])?.id;
+    if (!projectId)
+        refuse("assignment_project_missing");
+    const owners = context.db.get("SELECT 1 FROM sqlite_master WHERE name='run_controllers'")
+        ? context.db.all("SELECT controller_id,owner_token,state_json FROM run_controllers WHERE project_id=? AND run_id=? AND generation=? AND status NOT IN ('completed','cancelled','superseded')", [projectId, scope.runId, scope.generation]) : [];
+    if (owners.length > 1)
+        refuse("controller_owner_ambiguous");
+    const controller = owners[0];
+    const controllerState = controller && JSON.parse(controller.state_json);
+    const current = controllerState && controllerState.current_session !== null ? controllerState.sessions[controllerState.current_session] : null;
+    if (controller && (!current || current.retired || current.stopped))
+        refuse("controller_session_retired");
+    if (stage && !context.db.get("SELECT 1 FROM sessions WHERE project_id=? AND session_id=? AND run_id=? AND current_stage=?", [projectId, item.session_id, scope.runId, stage]))
+        refuse("inactive_stage_assignment");
+    if (stage) {
+        const project = context.db.get("SELECT id FROM projects WHERE root=?", [scope.projectRoot]);
+        const graph = stageGraphScope(context, project.id, scope.runId, stage);
+        const packet = context.db.get(`SELECT a.payload_json FROM audit_events a JOIN lifecycle_packet_assignments pa
+      ON pa.packet_sha256=json_extract(a.payload_json,'$.packet_sha256') WHERE a.event_type='lifecycle.coordinator_packet'
+      AND pa.invocation_id=? AND json_extract(a.payload_json,'$.work_session_id')=? ORDER BY a.id DESC LIMIT 1`, [row.id, item.id]);
+        if (!packet || JSON.stringify(JSON.parse(packet.payload_json).stage_scope) !== JSON.stringify(graph))
+            refuse("stage_attempt_changed");
+    }
+    let identity = { source: "controller_assignment", hookEventId: null, harness: item.harness,
+        providerSessionId: item.provider_session_id, nativeSessionId: item.provider_session_id, sessionId: item.session_id,
+        parentSessionId: item.parent_session_id, daemonId: scope.daemonId, agentId: null, turnId: null, transcriptPath: null,
+        provider: null, model: null, reasoning: null, mode: null, agentType: null, cwd: item.cwd };
+    if (operation === "stage_resume") {
+        const retained = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='lifecycle.resume_assignment' AND json_extract(payload_json,'$.invocation_id')=?", [projectId, row.id]);
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id=? AND id=?", [projectId, scope.runId]);
+        const pause = run && JSON.parse(run.index_json).stage_runs.find((entry) => entry.stage === stage)?.pause;
+        if (!retained || JSON.parse(retained.payload_json).pause_id !== pause?.id)
+            refuse("resume_pause_changed");
+        const assignedSession = JSON.parse(retained.payload_json).work_session_id;
+        if (assignedSession !== item.id) {
+            const receipt = JSON.parse(item.start_receipt_json);
+            const recovered = receipt.recovered_from_work_session_id === assignedSession && receipt.recovery_id && context.db.get(`SELECT 1 FROM run_recovery_bindings b JOIN run_recovery_guards g ON g.recovery_id=b.recovery_id
+        WHERE g.project_id=? AND g.run_id=? AND g.generation=? AND g.status='recovered' AND b.status='accepted'
+          AND b.recovery_id=? AND b.prior_work_session_id=? AND b.work_id=? AND b.session_id=?`, [projectId, scope.runId, scope.generation, receipt.recovery_id, assignedSession, item.work_id, item.session_id]);
+            if (!recovered)
+                refuse("resume_session_changed");
+        }
+        if (controller && current) {
+            const harness = runtimeHarness(current.profile), nativeId = scope.rootSessionId;
+            identity = { ...identity, harness, nativeSessionId: nativeId, providerSessionId: nativeId,
+                sessionId: storageSessionId({ harness_id: harness, session_id: nativeId }), parentSessionId: null, cwd: current.cwd };
+        }
+    }
+    return { schema_id: "dd-flow/assigned-lifecycle-admission@1", kind: "managed_assignment", invocation_id: row.id, scope,
+        operation, work_id: item.work_id, work_session_id: item.id, controller_id: controller?.controller_id ?? null, stage, identity,
+        ...(controller && current ? { controller_owner: { token: controller.owner_token, session_id: current.id } } : {}) };
+}
+/** A pause and its current published coordinator packet authorize its exact answer command. */
+export function bindAssignedStageResume(context, row) {
+    const command = parsed(row.command), scope = JSON.parse(row.scope_json);
+    if (command?.operation !== "stage_resume" || !scope.runId)
+        return;
+    const project = context.db.get("SELECT id FROM projects WHERE root=?", [scope.projectRoot]);
+    const stage = commandOption(command, "stage"), work = commandOption(command, "work");
+    const run = project && context.db.get("SELECT index_json FROM runs WHERE project_id=? AND id=?", [project.id, scope.runId]);
+    const entry = run && JSON.parse(run.index_json).stage_runs.find((item) => item.stage === stage);
+    if (!project || !entry?.pause || !work || ![entry.pause.work_id, entry.pause.work_id.match(/^WRK-\d+/)?.[0]].includes(work))
+        return;
+    const links = context.db.all("SELECT ws.id,ws.start_receipt_json FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND w.work_id=? AND w.status='paused' AND ws.status='running' AND ws.start_publication_status='published'", [project.id, scope.runId, entry.pause.work_id]);
+    if (links.length !== 1)
+        return;
+    const link = links[0];
+    const hashes = context.db.all("SELECT json_extract(payload_json,'$.packet_sha256') AS packet FROM audit_events WHERE project_id=? AND event_type='lifecycle.coordinator_packet' AND json_extract(payload_json,'$.work_session_id')=? AND json_extract(payload_json,'$.stage')=?", [project.id, link.id, stage]);
+    const startHash = JSON.parse(link.start_receipt_json).prompt_sha256;
+    for (const hash of new Set([...hashes.map(item => item.packet), ...(startHash ? [startHash] : [])]))
+        context.db.run("INSERT OR IGNORE INTO lifecycle_packet_assignments(packet_sha256,invocation_id) VALUES (?,?)", [hash, row.id]);
+    appendAudit(context, { projectId: project.id, eventType: "lifecycle.resume_assignment", payload: { run_id: scope.runId,
+            invocation_id: row.id, work_session_id: link.id, stage, pause_id: entry.pause.id, answer_file: commandOption(command, "answer-file") ?? null, generation: scope.generation } });
+}
+export function claimAssignedLifecycle(context, row) {
+    const binding = assignedLifecycleBinding(context, row);
+    if (!binding)
+        return null;
+    // Physical observation can spawn ps; never hold the RUN writer while doing it.
+    const executor = { pid: process.pid, birth: processStartedAt(process.pid), cwd: process.cwd() };
+    return context.db.writeTransaction(() => {
+        const current = assignedLifecycleBinding(context, row);
+        if (!current || JSON.stringify(current) !== JSON.stringify(binding))
+            refuse("assignment_changed");
+        assertTerminalSettlementUnreserved(context, row, binding.work_session_id);
+        const admission = { ...binding, executor: { ...executor, admitted_at: context.now() } };
+        if (context.db.run("UPDATE lifecycle_invocations SET status='executing',admission_json=?,updated_at=? WHERE id=? AND status IN ('issued','observed')", [JSON.stringify(admission), admission.executor.admitted_at, row.id]).changes !== 1)
+            return null;
+        let map = owned.get(context.db);
+        if (!map) {
+            map = new Map();
+            owned.set(context.db, map);
+        }
+        map.set(row.id, admission);
+        return admission;
+    });
+}
+/** Both native and assigned claims reserve the same current WorkSession before checks. SQL-only. */
+export function assertTerminalSettlementUnreserved(context, row, assignedSession) {
+    const sessions = (attempt) => {
+        const command = parsed(attempt.command), scope = JSON.parse(attempt.scope_json);
+        if (!command || !scope.runId || !["work_finish", "work_fail", "stage_finish", "stage_pause", "stage_resume"].includes(command.operation))
+            return [];
+        const retained = attempt.admission_json && JSON.parse(attempt.admission_json).work_session_id;
+        if (retained)
+            return [retained];
+        const target = command.operation.startsWith("work_") ? commandPosition(command, 0) : commandOption(command, "work");
+        const stage = commandOption(command, "stage");
+        const identity = context.db.get(`SELECT he.session_id FROM hook_events he JOIN projects p ON p.id=he.project_id
+      JOIN lifecycle_invocations li ON li.event_key=he.event_key WHERE li.id=? AND p.root=?`, [attempt.id, scope.projectRoot]);
+        return context.db.all(`SELECT ws.id,w.work_id,ws.session_id,w.parent_work_id,s.current_stage
+      FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id JOIN projects p ON p.id=w.project_id
+      JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id
+      WHERE p.root=? AND w.run_id=? AND ws.status='running' AND w.status IN ('running','paused')`, [scope.projectRoot, scope.runId])
+            .filter(link => target ? link.work_id === target || link.work_id.match(/^WRK-\d+/)?.[0] === target
+            : Boolean(stage && link.current_stage === stage && (identity ? link.session_id === identity.session_id : link.parent_work_id === null)))
+            .map(link => link.id);
+    };
+    const scope = JSON.parse(row.scope_json);
+    const targets = assignedSession ? [assignedSession] : sessions(row);
+    if (!targets.length)
+        return;
+    const peers = context.db.all("SELECT * FROM lifecycle_invocations WHERE id<>? AND status='executing' AND json_extract(scope_json,'$.projectRoot')=? AND json_extract(scope_json,'$.runId')=?", [row.id, scope.projectRoot, scope.runId]);
+    const busy = peers.find(peer => sessions(peer).some(id => targets.includes(id)));
+    if (busy)
+        throw new AppError("invocation_outcome_pending", "Another settlement of this Work Session is executing; observe that attempt", 1, { invocation_id: busy.id, effect: "no_effect", recoverable: true, reconciliation_required: true });
+}
+export function currentAssignedLifecycle(context) {
+    const id = context.env?.DD_FLOW_CURRENT_INVOCATION;
+    if (!id)
+        return null;
+    const admission = owned.get(context.db)?.get(id);
+    if (!admission || admission.executor.pid !== process.pid || admission.executor.cwd !== process.cwd())
+        return null;
+    const row = context.db.get("SELECT status,admission_json FROM lifecycle_invocations WHERE id=?", [id]);
+    return row?.status === "executing" && row.admission_json === JSON.stringify(admission) ? admission : null;
+}
+/** Result consumers can use launch facts without manufacturing a native Hook. */
+export function assignedSessionIdentity(context) { return currentAssignedLifecycle(context)?.identity ?? null; }
+export function lifecycleSessionIdentity(context, projectId, eventKey) {
+    const assigned = assignedSessionIdentity(context);
+    if (assigned)
+        return assigned;
+    if (!eventKey)
+        refuse("native_or_assigned_identity_required");
+    return hookSessionIdentity(context, projectId, eventKey);
+}
+/** Historical launch custody remains readable without a fresh native event. */
+export function hasAssignedCoordinatorLaunch(context, input) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='stage.coordinator_binding' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.stage')=? AND json_extract(payload_json,'$.work_session_id')=?", [input.projectId, input.runId, input.stage, input.workSessionId]);
+    return rows.some(row => {
+        const payload = JSON.parse(row.payload_json);
+        if (!payload.launch_invocation_id || payload.session_id !== input.sessionId)
+            return false;
+        const invocation = context.db.get("SELECT admission_json,status FROM lifecycle_invocations WHERE id=?", [payload.launch_invocation_id]);
+        if (!invocation?.admission_json || !["executing", "settled"].includes(invocation.status))
+            return false;
+        const admission = JSON.parse(invocation.admission_json);
+        return admission.kind === "managed_assignment" && admission.operation === "stage_start" && admission.identity.sessionId === input.sessionId
+            && admission.scope.runId === input.runId && admission.stage === input.stage
+            && context.db.get("SELECT id FROM projects WHERE root=?", [admission.scope.projectRoot])?.id === input.projectId;
+    });
+}
+export function assertAssignedStageStart(context, input) {
+    const assigned = currentAssignedLifecycle(context);
+    if (assigned) {
+        if (assigned.operation !== "stage_start" || assigned.scope.runId !== input.runId || assigned.stage !== input.stage || assigned.scope.projectRoot !== input.projectRoot)
+            refuse("stage_launch_target");
+        return assigned.identity;
+    }
+    if (!input.eventKey)
+        refuse("stage_launch_identity_missing");
+    return assertStageStartHookEvent(context, { ...input, eventKey: input.eventKey });
+}
+export function claimAssignedStageStart(context, input) {
+    if (currentAssignedLifecycle(context))
+        return assertAssignedStageStart(context, input);
+    if (!input.eventKey)
+        refuse("stage_launch_identity_missing");
+    return claimStageStartHookEvent(context, { ...input, eventKey: input.eventKey });
+}
+export function bindAssignedCoordinatorPacket(context, prompt) {
+    const admitted = currentAssignedLifecycle(context);
+    if (!admitted || !["stage_start", "stage_resume"].includes(admitted.operation))
+        return;
+    const digest = crypto.createHash("sha256").update(prompt).digest("hex");
+    const projectId = context.db.get("SELECT id FROM projects WHERE root=?", [admitted.scope.projectRoot])?.id;
+    if (!projectId)
+        refuse("assignment_project_missing");
+    const links = context.db.all("SELECT ws.id,w.project_id,ws.start_receipt_json FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND ws.session_id=? AND ws.status='running'", [projectId, admitted.scope.runId, admitted.identity.sessionId]);
+    if (links.length !== 1)
+        refuse("coordinator_packet_owner");
+    const link = links[0];
+    // Retain original launch bytes. Later stage/resume packets are independent
+    // immutable publications, not replacements of a Work start receipt.
+    if (!link.start_receipt_json)
+        context.db.run("UPDATE work_sessions SET start_receipt_json=?,start_publication_status='published' WHERE id=? AND status='running' AND start_receipt_json IS NULL", [JSON.stringify({ version: 3, prompt, prompt_sha256: digest, generation: admitted.scope.generation, invocation_id: admitted.invocation_id, source: "controller_assignment" }), link.id]);
+    const prior = context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='lifecycle.coordinator_packet' AND json_extract(payload_json,'$.work_session_id')=? AND json_extract(payload_json,'$.packet_sha256')=?", [link.project_id, link.id, digest]);
+    if (!prior)
+        appendAudit(context, { projectId: link.project_id, eventType: "lifecycle.coordinator_packet", payload: { run_id: admitted.scope.runId,
+                work_session_id: link.id, packet_sha256: digest, generation: admitted.scope.generation, invocation_id: admitted.invocation_id, stage: admitted.stage,
+                controller_id: admitted.controller_id, controller_owner: admitted.controller_owner ?? null,
+                daemon_id: admitted.scope.daemonId, root_session_id: admitted.scope.rootSessionId,
+                stage_scope: admitted.stage ? stageGraphScope(context, link.project_id, admitted.scope.runId, admitted.stage) : null,
+                auxiliary_operations: ["stage_block", ...(admitted.stage === "code" ? ["work_repair_add"] : [])], prompt } });
+}
+/** These two coordinator mutations are scoped permits, not generic shell authority. */
+export function admitAssignedAuxiliary(context, command, scope, projectRoot) {
+    const operation = continuationCommand(command);
+    if (!operation || !scope.runId || projectRoot !== scope.projectRoot)
+        return false;
+    const runTarget = operation.args.options.get("run")?.[0] ?? operation.args.positional[2];
+    const stage = operation.args.options.get("stage")?.[0] ?? (operation.operation === "work_repair_add" ? "code" : undefined);
+    if (!runTarget || !stage)
+        refuse("auxiliary_target_missing");
+    const run = context.db.get("SELECT r.id,r.project_id FROM runs r JOIN projects p ON p.id=r.project_id WHERE p.root=? AND r.id=? AND (r.id=? OR r.short_id=?)", [scope.projectRoot, scope.runId, runTarget, runTarget]);
+    if (!run)
+        refuse("auxiliary_run_changed");
+    const links = context.db.all(`SELECT w.work_id,a.payload_json FROM audit_events a
+    JOIN work_sessions ws ON ws.id=json_extract(a.payload_json,'$.work_session_id') JOIN works w ON w.work_id=ws.work_id
+    JOIN sessions s ON s.project_id=w.project_id AND s.session_id=ws.session_id
+    WHERE a.event_type='lifecycle.coordinator_packet' AND w.project_id=? AND a.project_id=w.project_id AND w.run_id=? AND ws.status='running' AND ws.start_publication_status='published' AND w.status IN ('running','paused')
+      AND s.current_stage=? AND json_extract(a.payload_json,'$.generation')=?`, [run.project_id, scope.runId, stage, scope.generation]);
+    const work = operation.args.options.get("work")?.[0];
+    const matches = links.filter(link => {
+        const packet = JSON.parse(link.payload_json);
+        if (packet.daemon_id !== scope.daemonId || packet.root_session_id !== scope.rootSessionId
+            || JSON.stringify(packet.stage_scope) !== JSON.stringify(stageGraphScope(context, run.project_id, scope.runId, stage)))
+            return false;
+        if (!packet.controller_id || !packet.controller_owner)
+            return false;
+        const controller = context.db.get("SELECT owner_token,status,state_json,generation FROM run_controllers WHERE controller_id=? AND project_id=? AND run_id=?", [packet.controller_id, run.project_id, scope.runId]);
+        const state = controller && JSON.parse(controller.state_json);
+        const active = state && state.current_session !== null ? state.sessions[state.current_session] : null;
+        if (!controller || controller.owner_token !== packet.controller_owner.token || controller.generation !== scope.generation
+            || ["completed", "cancelled", "superseded"].includes(controller.status) || !active || active.id !== packet.controller_owner.session_id || active.retired || active.stopped)
+            return false;
+        return packet.auxiliary_operations?.includes(operation.operation) && (!work || link.work_id === work || link.work_id.match(/^WRK-\d+/)?.[0] === work);
+    });
+    if (new Set(matches.map(item => item.work_id)).size !== 1)
+        refuse("auxiliary_assignment_missing");
+    return true;
+}
+export function assertAssignedSettlementCurrent(context, workSessionId) {
+    const admission = currentAssignedLifecycle(context);
+    if (!admission)
+        return;
+    if (workSessionId && admission.work_session_id && admission.work_session_id !== workSessionId)
+        refuse("settlement_session_changed");
+    const guard = context.db.get("SELECT g.generation,g.status FROM run_recovery_guards g JOIN projects p ON p.id=g.project_id WHERE p.root=? AND g.run_id=? ORDER BY g.generation DESC LIMIT 1", [admission.scope.projectRoot, admission.scope.runId]);
+    if (guard && guard.generation !== admission.scope.generation && !(guard.status === "draining" && guard.generation === admission.scope.generation + 1))
+        refuse("settlement_generation_changed");
+    if (admission.controller_id && admission.controller_owner) {
+        const owner = context.db.get("SELECT owner_token,generation,state_json,status FROM run_controllers WHERE controller_id=?", [admission.controller_id]);
+        const state = owner && JSON.parse(owner.state_json);
+        if (!owner || owner.owner_token !== admission.controller_owner.token || owner.generation !== admission.scope.generation
+            || ["completed", "cancelled", "superseded"].includes(owner.status) || !state || state.current_session === null
+            || state.sessions[state.current_session]?.id !== admission.controller_owner.session_id || state.sessions[state.current_session]?.retired)
+            refuse("settlement_controller_changed");
+    }
+}
+export function inheritAssignedPackets(context, priorId, successorId) {
+    context.db.run("INSERT OR IGNORE INTO lifecycle_packet_assignments(packet_sha256,invocation_id) SELECT packet_sha256,? FROM lifecycle_packet_assignments WHERE invocation_id=?", [successorId, priorId]);
+}
+/** Exact SQL acceptance, independent of stdout or derivative result publication. */
+export function readAcceptedAssignedWork(context, invocationId) {
+    const rows = context.db.all("SELECT project_id,payload_json FROM audit_events WHERE event_type='lifecycle.work_settlement' AND json_extract(payload_json,'$.invocation_id')=? LIMIT 2", [invocationId]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1)
+        throw new AppError("invocation_outcome_pending", "Assigned Work has ambiguous settlement evidence", 1, { effect: "unknown" });
+    const invocation = context.db.get("SELECT admission_json FROM lifecycle_invocations WHERE id=?", [invocationId]);
+    if (!invocation?.admission_json)
+        return null;
+    const admission = JSON.parse(invocation.admission_json);
+    const retained = JSON.parse(rows[0].payload_json);
+    if (admission.work_id !== retained.work_id || admission.work_session_id !== retained.work_session_id || admission.scope.runId !== retained.run_id)
+        refuse("accepted_assignment_changed");
+    const accepted = context.db.get("SELECT w.result,w.status FROM works w JOIN work_sessions ws ON ws.work_id=w.work_id AND ws.status=w.status JOIN projects p ON p.id=w.project_id WHERE p.root=? AND w.project_id=? AND w.run_id=? AND w.work_id=? AND ws.id=?", [admission.scope.projectRoot, rows[0].project_id, retained.run_id, retained.work_id, retained.work_session_id]);
+    if (!accepted || crypto.createHash("sha256").update(accepted.result).digest("hex") !== retained.result_sha256 || accepted.status !== retained.response.status)
+        throw new AppError("invocation_outcome_pending", "Assigned Work settlement no longer matches retained result", 1, { effect: "unknown" });
+    return retained.response;
+}

package/dist/services/branch-context.js

@@ -166,11 +166,11 @@ 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" });
+    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", timeout: 5000 });
     if (branch.status !== 0) {
-        return { status: "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
+        return { status: branch.error || branch.signal ? "observation_unavailable" : "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
     }
-    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8" });
+    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
     return {
         status: "ok",
         actual_branch: branch.stdout.trim() || null,

package/dist/services/canon.js

@@ -1,27 +1,32 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { prepareError } from "../cli/input-preparation.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { readSetupStatus } from "./setup.js";
 const canonRootKey = "canon.root";
-export function registerCanonRoot(context, input) {
+export function prepareCanonRegistration(context, input) {
+    if (typeof input.root !== "string" || !input.root.trim())
+        return prepareError(new AppError("validation", "Canon root must be a non-empty path", 2));
     const resolution = resolveCanonRoot(context, { explicitRoot: input.root, allowRegistered: false });
     if (!resolution.ok || !resolution.canon) {
-        return {
-            ...resolution,
-            action: "register",
-            exit_code: 1
-        };
+        return prepareError(new AppError("validation", "Canon root cannot be registered", 2, { root: input.root, blockers: resolution.blockers, candidates: resolution.candidates, bootstrap: resolution.bootstrap }));
     }
+    return resolution.canon;
+}
+export function registerCanonRoot(context, input, canon = prepareCanonRegistration(context, input)) {
     const now = context.now();
     context.db.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at)
      VALUES (?, ?, ?, ?)
      ON CONFLICT(key) DO UPDATE SET
        value_json = excluded.value_json,
-       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: resolution.canon.root }), now, now]);
+       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: canon.root }), now, now]);
     return {
         ok: true,
         action: "register",
         canon: {
-            ...resolution.canon,
+            ...canon,
             source: "registered"
         },
         db_path: context.db.path
@@ -38,16 +43,21 @@ export function getCanonStatus(context, input = {}) {
 export function resolveCanonRoot(context, input = {}) {
     return resolveCanonCandidates(canonCandidates(context, input));
 }
-/** Read only: resolve an explicit/environment/nearby canon without opening DD_FLOW_HOME. */
+/** Read only: resolve canonical data without opening SQLite or running migrations. */
 export function resolveCanonRootBeforeContext(env, input = {}) {
     const candidates = [];
     if (input.explicitRoot)
         candidates.push(validateCanonCandidate("explicit", input.explicitRoot));
     else if (env.DD_MEMORYBANK)
         candidates.push(validateCanonCandidate("env", env.DD_MEMORYBANK));
-    else
-        for (const known of knownCanonRoots())
-            candidates.push(validateCanonCandidate("known", known));
+    else {
+        const installed = installedCanonCandidate(resolveDdFlowHome(env));
+        if (installed)
+            candidates.push(installed);
+        else
+            for (const known of knownCanonRoots())
+                candidates.push(validateCanonCandidate("known", known));
+    }
     return resolveCanonCandidates(uniqueBy(candidates, (candidate) => `${candidate.source}:${candidate.root}`));
 }
 function resolveCanonCandidates(candidates) {
@@ -64,7 +74,7 @@ function resolveCanonCandidates(candidates) {
         const memorybankRoot = candidate.memorybank_root ?? root;
         const mbbRoot = candidate.mbb_root ?? path.join(memorybankRoot, "mbb");
         const layout = candidate.layout ?? "legacy_root";
-        const metadata = readCanonMetadata(root, flowRoot);
+        const metadata = candidate.metadata ?? readCanonMetadata(root, flowRoot);
         return {
             ok: true,
             canon: {
@@ -111,6 +121,30 @@ function resolveCanonCandidates(candidates) {
         ]
     };
 }
+/** Archive provenance belongs to the selected release, not an ancestor Git
+ * checkout. A damaged installation is not permission to select nearby code. */
+function installedCanonCandidate(home) {
+    if (!fs.existsSync(path.join(home, "installation.json")))
+        return null;
+    const status = readSetupStatus(home), installation = status.installation;
+    const invalid = (root, reason) => ({
+        source: "installed", root, realpath: null, valid: false, blockers: [reason]
+    });
+    if (!installation || status.installation_readiness !== "installed")
+        return invalid(home, "Installed canonical release is degraded; reconcile setup before selecting its canon.");
+    const roots = fs.readdirSync(installation.canon_root);
+    if (roots.length !== 1)
+        return invalid(installation.canon_root, "Installed canonical archive has no unique root.");
+    const candidate = validateCanonCandidate("installed", path.join(installation.canon_root, roots[0]));
+    if (!candidate.valid)
+        return candidate;
+    const version = readTrimmed(path.join(candidate.root, "VERSION"));
+    const flowContract = readFlowContractId(candidate.flow_root);
+    if (version !== installation.manifest.canon.version || !flowContract)
+        return invalid(candidate.root, "Installed canonical metadata differs from its release selection.");
+    return { ...candidate, metadata: { version, commit: installation.manifest.canon.commit,
+            flow_contract: flowContract, status: "present", diagnostics: [] } };
+}
 function canonCandidates(context, input) {
     const candidates = [];
     if (input.explicitRoot) {
@@ -126,8 +160,13 @@ function canonCandidates(context, input) {
             candidates.push(validateCanonCandidate("registered", registered.root));
         }
     }
-    for (const known of knownCanonRoots()) {
-        candidates.push(validateCanonCandidate("known", known));
+    if (!candidates.length) {
+        const installed = installedCanonCandidate(context.ddFlowHome);
+        if (installed)
+            return [installed];
+        for (const known of knownCanonRoots()) {
+            candidates.push(validateCanonCandidate("known", known));
+        }
     }
     return uniqueBy(candidates, (candidate) => `${candidate.source}:${candidate.root}`);
 }

package/dist/services/check-environment.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export function validateCheckEnvironment(value) {
+    if (value === undefined)
+        return undefined;
+    const entries = value && typeof value === "object" && !Array.isArray(value) ? Object.entries(value) : [];
+    if (!entries.length || entries.some(([key, selected]) => !["CODEX_HOME", "PLAYWRIGHT_BROWSERS_PATH"].includes(key)
+        || typeof selected !== "string" || !selected || selected.length > 4096 || selected.includes("\0") || !path.isAbsolute(selected)))
+        throw new AppError("invalid_check_environment", "Owned checks require absolute known resource paths", 2, { effect: "no_effect" });
+    return { ...value };
+}
+export function retainedBrowserEnvironment(environment) {
+    return environment.PLAYWRIGHT_BROWSERS_PATH === undefined ? undefined
+        : validateCheckEnvironment({ PLAYWRIGHT_BROWSERS_PATH: environment.PLAYWRIGHT_BROWSERS_PATH });
+}
+export function ownedCheckEnvironment(environment, requested) {
+    const selected = validateCheckEnvironment(requested), retained = retainedBrowserEnvironment(environment);
+    if (retained?.PLAYWRIGHT_BROWSERS_PATH && selected?.PLAYWRIGHT_BROWSERS_PATH && retained.PLAYWRIGHT_BROWSERS_PATH !== selected.PLAYWRIGHT_BROWSERS_PATH)
+        throw new AppError("invalid_check_environment", "Owned browser resource cannot be rebound", 2, { effect: "no_effect" });
+    return retained || selected ? { ...retained, ...selected } : undefined;
+}