@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

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/operator-profiles.js

@@ -0,0 +1,236 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest, validateHybridContract } from "./hybrid-contracts.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+export function operatorSettingsPath(home) { return path.join(home, "profile-settings.json"); }
+function profileError(code, message, exitCode = 2) {
+    return new AppError(code, `${message}; use dd-flow profiles --help`, exitCode, { phase: "profiles", effect: "no_effect", recoverable: true });
+}
+function completeSettings(input) {
+    const value = { ...input, profiles: input.profiles.map(entry => ({ ...entry, revision: hybridDigest(entry.profile) })) };
+    return { ...value, revision: hybridDigest(value) };
+}
+function admittedSettings(input) {
+    const issues = validateHybridContract("profile-settings", input);
+    if (issues.length)
+        throw profileError("profile_settings_invalid", "Profile settings violate the schema or aliases/revision contract");
+    const settings = input;
+    for (const { profile } of settings.profiles) {
+        if ([profile.provider, profile.model, profile.reasoning, profile.mode].some(value => !value.trim())) {
+            throw profileError("profile_settings_invalid", "Profile execution values must not be blank");
+        }
+    }
+    return settings;
+}
+function readRegularJson(file) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(readBoundedReleaseFile(file, 4 * 1024 * 1024)));
+    }
+    catch {
+        // Parser errors can contain submitted secrets. Never retain input text or cause.
+        throw profileError("profile_settings_invalid", "Profile input is unreadable or malformed JSON");
+    }
+}
+/** First successful write imports valid legacy IDs; thereafter the settings file is the sole owner. */
+export function readOperatorProfiles(home) {
+    const file = operatorSettingsPath(home);
+    if (fs.existsSync(file))
+        return admittedSettings(readRegularJson(file));
+    const profiles = [];
+    const legacy = path.join(home, "agent-profiles");
+    if (fs.existsSync(legacy)) {
+        for (const entry of fs.readdirSync(legacy).sort()) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const profile = readRegularJson(path.join(legacy, entry));
+            const id = entry.slice(0, -5);
+            profiles.push({ id, revision: hybridDigest(profile), profile });
+        }
+    }
+    return admittedSettings(completeSettings({ schema_id: "dd-flow/profile-settings@1", profiles,
+        aliases: {}, default_profile: null }));
+}
+export function resolveOperatorProfile(settings, id) {
+    const selected = id ?? settings.default_profile;
+    if (!selected)
+        throw profileError("agent_profile_missing", "Select an explicit profile or configure a default", 1);
+    const target = Object.hasOwn(settings.aliases, selected) ? settings.aliases[selected] : selected;
+    const entry = settings.profiles.find(item => item.id === target);
+    if (!entry)
+        throw profileError("agent_profile_missing", "Selected profile is unavailable", 1);
+    return structuredClone(entry.profile);
+}
+/** Used by explicit files and onboarding alike; extra credential fields fail before any write. */
+export function prepareOperatorProfile(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw profileError("profile_settings_invalid", "Profile must be an object");
+    const sample = input;
+    const value = completeSettings({ schema_id: "dd-flow/profile-settings@1", profiles: [
+            { id: sample?.id, revision: hybridDigest(input), profile: sample }
+        ], aliases: {}, default_profile: null });
+    return admittedSettings(value).profiles[0].profile;
+}
+export function readOperatorProfileInput(file) {
+    return prepareOperatorProfile(readRegularJson(file));
+}
+function changedSettings(current, mutation) {
+    const next = structuredClone(current);
+    if (mutation.action === "create" || mutation.action === "edit") {
+        if (mutation.action === "create" && mutation.setDefault !== undefined && typeof mutation.setDefault !== "boolean") {
+            throw profileError("profile_settings_invalid", "Default selection must be an explicit boolean");
+        }
+        const profile = prepareOperatorProfile(mutation.profile);
+        const index = next.profiles.findIndex(entry => entry.id === profile.id);
+        if (mutation.action === "create" && index >= 0)
+            throw profileError("profile_conflict", "Profile ID already exists", 1);
+        if (mutation.action === "edit" && index < 0)
+            throw profileError("agent_profile_missing", "Cannot edit a missing profile", 1);
+        const entry = { id: profile.id, revision: hybridDigest(profile), profile };
+        if (index >= 0)
+            next.profiles[index] = entry;
+        else
+            next.profiles.push(entry);
+        if (mutation.action === "create" && mutation.setDefault === true)
+            next.default_profile = profile.id;
+    }
+    else if (mutation.action === "remove") {
+        if (!next.profiles.some(entry => entry.id === mutation.id))
+            throw profileError("agent_profile_missing", "Cannot remove a missing profile", 1);
+        if (Object.values(next.aliases).includes(mutation.id) || next.default_profile === mutation.id
+            || next.default_profile !== null && next.aliases[next.default_profile] === mutation.id) {
+            throw profileError("profile_in_use", "Remove aliases and change the default before removing this profile", 1);
+        }
+        next.profiles = next.profiles.filter(entry => entry.id !== mutation.id);
+    }
+    else if (mutation.action === "alias") {
+        if (mutation.target === null) {
+            if (!Object.hasOwn(next.aliases, mutation.alias))
+                throw profileError("profile_alias_missing", "Alias is unavailable", 1);
+            if (next.default_profile === mutation.alias)
+                throw profileError("profile_in_use", "Change the default before removing its alias", 1);
+            delete next.aliases[mutation.alias];
+        }
+        else
+            Object.defineProperty(next.aliases, mutation.alias, { value: mutation.target, enumerable: true, writable: true, configurable: true });
+    }
+    else if (mutation.action === "set-default")
+        next.default_profile = mutation.id;
+    else
+        throw profileError("profile_settings_invalid", "Unknown profile mutation");
+    const { revision: _revision, ...content } = next;
+    void _revision;
+    return admittedSettings(completeSettings(content));
+}
+/** Pure preflight suitable for freezing into an installation request before any effects. */
+export function prepareProfileCreation(settings, profile, setDefault) {
+    if (typeof setDefault !== "boolean")
+        throw profileError("profile_settings_invalid", "Default selection requires explicit consent");
+    const before = admittedSettings(structuredClone(settings)), admitted = prepareOperatorProfile(profile);
+    const after = changedSettings(before, { action: "create", profile: admitted, setDefault });
+    return { schema_id: "dd-flow/profile-creation-intent@1", before, after, profile: structuredClone(admitted), set_default: setDefault };
+}
+/** Exact frozen intent reconciliation: an already-applied write is not applied a second time.
+ * A later edit/default change is a conflict, never a reason to restore old settings.
+ */
+export function validateProfileCreationIntent(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)
+        || Object.keys(input).some(key => !["schema_id", "before", "after", "profile", "set_default"].includes(key))
+        || ["schema_id", "before", "after", "profile", "set_default"].some(key => !Object.hasOwn(input, key))
+        || input.schema_id !== "dd-flow/profile-creation-intent@1")
+        throw profileError("profile_settings_invalid", "Invalid profile creation intent");
+    const expected = prepareProfileCreation(input.before, input.profile, input.set_default);
+    admittedSettings(input.after);
+    if (hybridDigest(expected) !== hybridDigest(input))
+        throw profileError("profile_settings_invalid", "Profile creation intent changed");
+}
+export function readProfileCreationIntent(file) {
+    try {
+        const input = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(readBoundedReleaseFile(file, 4 * 1024 * 1024)));
+        validateProfileCreationIntent(input);
+        return input;
+    }
+    catch {
+        throw profileError("profile_settings_invalid", "Profile creation intent must be a bounded valid regular JSON file");
+    }
+}
+export function commitProfileCreation(home, input) {
+    validateProfileCreationIntent(input);
+    const current = readOperatorProfiles(home);
+    if (current.revision === input.after.revision)
+        return { replayed: true, settings: current };
+    return { replayed: false, settings: mutateOperatorProfiles(home, input.before.revision, { action: "create", profile: input.profile, setDefault: input.set_default }) };
+}
+/** Compare-and-swap under an exclusive owned lock; no dual writer for legacy profile files. */
+export function mutateOperatorProfiles(home, expectedRevision, mutation) {
+    const before = readOperatorProfiles(home);
+    if (before.revision !== expectedRevision)
+        throw profileError("profile_revision_conflict", "Profile settings changed; reread before retrying", 1);
+    const prepared = changedSettings(before, mutation); // Fully validate before creating the home/lock.
+    const serialized = JSON.stringify(prepared, null, 2) + "\n";
+    if (Buffer.byteLength(serialized) > 4 * 1024 * 1024)
+        throw profileError("profile_settings_invalid", "Profile settings exceed the bounded reader limit");
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    const lock = path.join(home, "profile-settings.lock");
+    // Profiles use storage-owner identity, not a setup request ledger. A dead
+    // writer may be recovered by a later CAS mutation, including after commit.
+    let lease;
+    try {
+        lease = acquireInstallationLock(lock, hybridDigest({ resource: "profile-settings", home: path.resolve(home) }));
+    }
+    catch {
+        throw profileError("profile_write_conflict", "Another profile writer or unreconciled lock exists", 1);
+    }
+    const temporary = path.join(home, `.profile-settings-${randomUUID()}.tmp`);
+    let ownsTemporary = false;
+    let renameAttempted = false;
+    let failure;
+    let result;
+    try {
+        if (readOperatorProfiles(home).revision !== expectedRevision)
+            throw profileError("profile_revision_conflict", "Profile settings changed while acquiring the lock", 1);
+        const fd = fs.openSync(temporary, "wx", 0o600);
+        ownsTemporary = true;
+        try {
+            fs.writeFileSync(fd, serialized);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        renameAttempted = true;
+        fs.renameSync(temporary, operatorSettingsPath(home));
+        result = readOperatorProfiles(home);
+    }
+    catch (error) {
+        failure = error instanceof AppError && !renameAttempted ? error : new AppError("profile_write_interrupted", "Profile write requires reconciliation; reread settings before retrying", 1, { phase: "profiles", effect: "unknown", recoverable: true,
+            next_action: "dd-flow profiles list --json" });
+    }
+    finally {
+        let cleanupFailed = false;
+        try {
+            if (ownsTemporary && fs.existsSync(temporary))
+                fs.unlinkSync(temporary);
+        }
+        catch {
+            cleanupFailed = true;
+        }
+        try {
+            lease.release();
+        }
+        catch {
+            cleanupFailed = true;
+        }
+        if (cleanupFailed) {
+            if (failure)
+                failure.details.cleanup = "not_confirmed";
+            else
+                failure = new AppError("profile_cleanup_failed", "Profile writer cleanup requires reconciliation", 1, { phase: "profiles", effect: "unknown", cleanup: "not_confirmed", next_action: "dd-flow profiles list --json" });
+        }
+    }
+    if (failure)
+        throw failure;
+    return result;
+}

package/dist/services/plan-runtime.js

@@ -6,18 +6,24 @@ 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);
-    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]);
+export function prepareCanonicalPlan(context, input, canonical = readCanonicalPlan(input.planPath, input.protocolId)) {
+    const binding = context.db.get("SELECT plan_id, 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, {
             protocol_id: input.protocolId,
@@ -28,10 +34,19 @@ 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_id, 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)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`, [input.projectId, input.protocolId, canonical.revision, canonical.sha256, input.planPath, now, now]);
+        context.db.run(`INSERT INTO plan_bindings (project_id, protocol_id, plan_id, plan_revision, plan_sha256, plan_path, bound_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [input.projectId, input.protocolId, canonical.plan.plan_id, canonical.revision, canonical.sha256, input.planPath, now, now]);
+    }
+    else if (binding.plan_id === null) {
+        // Older bindings are upgraded when their canonical source is validated.
+        context.db.run("UPDATE plan_bindings SET plan_id = ?, updated_at = ? WHERE project_id = ? AND protocol_id = ? AND plan_id IS NULL", [canonical.plan.plan_id, now, input.projectId, input.protocolId]);
     }
     for (const item of canonical.plan.items) {
         context.db.run(`INSERT INTO plan_progress

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { foreignKeyTransaction } from "../storage/foreign-key-transaction.js";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId, slugFromRoot } from "../domain/entity-ids.js";
 import { AppError } from "../shared/errors.js";
 import { projectRuntimeRoot, resolveProjectRoot } from "../storage/paths.js";
@@ -10,9 +11,24 @@ import { loadProjectFlowContract } from "../domain/flow-contract.js";
 import { buildStaticFlowGuidance } from "./flow-guidance.js";
 import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 import { buildProjectSummary, projectRegistrySummary, readPublishedProjectSummary } from "./project-summary.js";
+/** Resolve filesystem identity before entering a composite SQL writer. */
+export class PreparedProjectRegistration {
+    #root;
+    constructor(root) { this.#root = root; Object.freeze(this); }
+    static prepare(input) {
+        return new PreparedProjectRegistration(resolveProjectRoot(input.root));
+    }
+    root() { return this.#root; }
+}
 export function registerProject(context, input) {
-    const root = resolveProjectRoot(input.root);
-    const existing = findProjectByRoot(context, root);
+    return registerPreparedProject(context, PreparedProjectRegistration.prepare(input));
+}
+/** Metadata-only registration; the composite caller owns its SQL transaction. */
+export function registerPreparedProject(context, prepared) {
+    if (!(prepared instanceof PreparedProjectRegistration))
+        throw new AppError("validation", "Project registration must be prepared", 2);
+    const root = prepared.root();
+    const existing = context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
     const now = context.now();
     const project = existing ?? newProjectRecord(context, root, now);
     if (existing) {
@@ -37,8 +53,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 +71,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) {
@@ -139,9 +164,7 @@ export function migrateProjectIds(context, input) {
     if (conflictingProject) {
         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");
-    try {
+    foreignKeyTransaction(context.db, () => {
         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()) {
             context.db.run(`UPDATE ${table} SET project_id = ? WHERE project_id = ?`, [target.id, oldId]);
@@ -153,14 +176,7 @@ export function migrateProjectIds(context, input) {
                 foreign_key_errors: foreignKeyErrors
             });
         }
-        context.db.exec("COMMIT");
-        context.db.exec("PRAGMA foreign_keys = ON");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        context.db.exec("PRAGMA foreign_keys = ON");
-        throw error;
-    }
+    });
     appendAudit(context, {
         projectId: target.id,
         eventType: "project.id_migrated",
@@ -232,9 +248,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;
 }

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 ?? [];
@@ -261,7 +268,9 @@ function assertGitFacts(workspaceRoot, expected, runId) {
     if (!expected?.head && !expected?.branch)
         return;
     const read = (args) => {
-        const result = spawnSync("git", ["-C", workspaceRoot, ...args.split(" ")], { encoding: "utf8" });
+        const result = spawnSync("git", ["-C", workspaceRoot, ...args.split(" ")], { encoding: "utf8", timeout: 5000 });
+        if (result.error || result.signal)
+            throw new AppError("git_observation_unavailable", "Cannot establish RUN workspace identity", 1, { run_id: runId, effect: "unknown" });
         return result.status === 0 ? result.stdout.trim() || null : null;
     };
     const actual = { branch: read("branch --show-current"), head: read("rev-parse HEAD") };
@@ -293,6 +302,8 @@ function renderPrompt(input) {
         `- Acceptance contribution: ${item.semantic_spine?.acceptance_contribution ?? "not_applicable"}`,
         "",
         "## Hard Write Boundary",
+        "Before editing, change into the project workspace shown below (cd -- WORKSPACE) or use its absolute path when the tool cannot persist cwd.",
+        "Write only the project workspace and the named report directory; never write another RUN/native home or Git/worktree control data.",
         `- All project writes must stay under: \`${input.workspaceRoot}\``,
         "- Do not write outside this workspace, to another RUN, or into Git/worktree control data.",
         "- Accepted requirements and non-goals remain binding; planned write areas do not.",