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

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/physical-startup.js

@@ -0,0 +1,45 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError } from "../shared/errors.js";
+import { createRenewalState, maintenanceRetryable, renewalDelay, renewalFailure, RENEWAL_POLICY } from "../harness-runtime/lib/lease-renewal.mjs";
+import { processStartedAt } from "./managed-processes.js";
+/** Birth and confirmation share one startup horizon. Retrying observations
+ * neither launches another child nor renews an unconfirmed resource lease. */
+export function physicalStartup(databaseDeadlineAt) {
+    const deadline = performance.now() + RENEWAL_POLICY.startupMs;
+    const episode = createRenewalState();
+    const unavailable = () => new AppError("process_ownership_unknown", "Managed physical identity observation is unavailable", 1, { phase: "process_confirmation", effect: "no_effect", native_dispatch_started: false, reason: "physical_identity_unavailable" });
+    async function observe(operation, assertCurrent, leaseExpiresAt) {
+        let last;
+        const remaining = () => Math.max(0, Math.min(deadline - performance.now(), databaseDeadlineAt === undefined ? Infinity : databaseDeadlineAt - Date.now(), leaseExpiresAt === undefined ? Infinity : Date.parse(leaseExpiresAt) - Date.now() - RENEWAL_POLICY.safetyMs));
+        for (;;) {
+            assertCurrent();
+            if (!(remaining() > 0))
+                throw last ?? unavailable();
+            try {
+                const result = operation();
+                assertCurrent();
+                if (!(remaining() > 0))
+                    throw new AppError("process_startup_expired", "Physical observation completed after its original admission horizon", 1, { phase: "process_confirmation", effect: "unknown", native_dispatch_started: false });
+                return result;
+            }
+            catch (error) {
+                // A stale owner/cancellation wins over a transient observation error.
+                assertCurrent();
+                const details = error instanceof AppError ? error.details : null;
+                if (!(error instanceof AppError) || error.code !== "process_ownership_unknown" || details?.reason !== "physical_identity_unavailable" || !maintenanceRetryable(error))
+                    throw error;
+                last = error;
+                renewalFailure(episode);
+                if (!(remaining() > 0))
+                    throw error;
+                await delay(Math.min(renewalDelay(episode), remaining()));
+            }
+        }
+    }
+    return { observe, birth: (assertCurrent) => observe(() => {
+            const started = processStartedAt(process.pid);
+            if (!started)
+                throw unavailable();
+            return { pid: process.pid, pid_started_at: started };
+        }, assertCurrent) };
+}

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 }) };
 }