agentera 3.0.0-dev.47 → 3.0.0-dev.51

package/dist/state/planEntities.js

@@ -5,7 +5,8 @@ import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { dumpYamlMapping } from "../core/yaml.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { StateRetrievalFailure } from "./directRetrieval.js";
-import { allocateEntityId, entityExactGetMaxBytes, exactDiscoveredEntityBytes, publishEntity, replaceEntity, replaceEntityUnderLock, validateEntityDiscovery, validateEntityState, withEntityWriterLock } from "./entityStorage.js";
+import { allocateEntityId, canonicalEntityEnvelopeBytes, entityExactGetMaxBytes, exactDiscoveredEntityBytes, publishEntity, replaceEntity, replaceEntityUnderLock, validateEntityDiscovery, validateEntityState, withEntityWriterLock } from "./entityStorage.js";
+import { inspectPendingPlanReplacement, publishPlanReplacement, recoverPendingPlanReplacement } from "./planReplacementTransaction.js";
 import { detectStateModeBinding } from "./stateMode.js";
 import { normalizeAndValidatePlanCreateInput, validatePlanPublicationCandidate } from "./write/planPublication.js";
 import { reject } from "./write/errors.js";
@@ -13,6 +14,7 @@ import { mutatePlanTaskEvaluation, planTaskRecordViolations } from "./write/plan
 import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
 import { entityListSelectorFlags, entityListSelectorKey, projectEntityList, resolveEntityListSelector } from "./entityListProjection.js";
 import { shellQuoteArgument } from "../core/shell.js";
+import { preCutoverCommand } from "../cli/preCutoverCommand.js";
 const ARTIFACT = "plan";
 const PLAN = "plan";
 const TASK = "plan_task";
@@ -34,16 +36,39 @@ function contract(sourceRoot = resolveSourceRoot()) {
             throw new Error(`invalid plan entity ${field} authority`);
         return result;
     };
+    const grammar = mapping(authority.mutation_grammar) ? authority.mutation_grammar : {};
+    const operations = Array.isArray(grammar.operations) ? grammar.operations : [];
+    const lifecycleLimits = ["create", "archive"].map((verb) => {
+        const operation = operations.find((value) => mapping(value) && value.artifact === ARTIFACT && value.verb === verb);
+        const bounds = mapping(operation) && mapping(operation.bounds) ? operation.bounds : {};
+        return number(bounds.max_collection_items, `plan ${verb} max_collection_items`);
+    });
+    if (new Set(lifecycleLimits).size !== 1)
+        throw new Error("invalid plan lifecycle max_collection_items authority");
     if (typeof storage.canonical_root !== "string")
         throw new Error(`invalid plan entity authority '${authorityPath}'`);
-    return { authorityPath, entityRoot: storage.canonical_root, defaultLimit: number(retrieval.default_limit, "default_limit"), maximumLimit: number(retrieval.maximum_limit, "maximum_limit"), maxUtf8Bytes: number(retrieval.max_utf8_bytes, "max_utf8_bytes") };
+    return { authorityPath, entityRoot: storage.canonical_root, defaultLimit: number(retrieval.default_limit, "default_limit"), maximumLimit: number(retrieval.maximum_limit, "maximum_limit"), maxUtf8Bytes: number(retrieval.max_utf8_bytes, "max_utf8_bytes"), openPlanConflictLimit: lifecycleLimits[0] };
 }
-function failure(kind, message, recovery, id) {
+function failure(kind, message, recovery, id, details) {
     const exampleId = id && ID.test(id) ? id : "qjtrmnpvka";
-    return new StateRetrievalFailure({ schemaVersion: "agentera.stateFailure.v1", status: "fail", error: { class: kind, message, syntax: "agentera state plan get --id ID --format json", example: `agentera state plan get --id ${exampleId} --format json`, recovery, artifact: ARTIFACT, ...(id ? { id } : {}) } }, kind === "invalid_request" ? 2 : 1);
+    return new StateRetrievalFailure({ schemaVersion: "agentera.stateFailure.v1", status: "fail", error: { class: kind, message, syntax: "agentera state plan get --id ID --format json", example: `agentera state plan get --id ${exampleId} --format json`, recovery, artifact: ARTIFACT, ...(id ? { id } : {}), ...(details ? { details } : {}) } }, kind === "invalid_request" ? 2 : 1);
 }
 function relative(root, file) { return path.relative(path.resolve(root), file).split(path.sep).join("/"); }
 function all(root, sourceRoot, discovery) {
+    try {
+        const pending = inspectPendingPlanReplacement(root);
+        if (pending) {
+            const recovery = pending.kind === "existing"
+                ? `Retry agentera state plan replace --predecessor ${pending.predecessor} --successor ${pending.successor} --format json to recover the exact pending replacement.`
+                : `Retry the exact original agentera state plan replace --predecessor ${pending.predecessor} --input PLAN.yaml --format json request to recover the pending replacement.`;
+            throw failure("unsupported_state", `plan replacement from '${pending.predecessor}' to '${pending.successor}' is pending durable recovery`, recovery, pending.predecessor);
+        }
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            throw error;
+        throw failure("unsupported_state", `plan replacement recovery state is unavailable: ${error.message}`, "Preserve '.agentera/.entity-recovery/plan-replacement', restore its last valid journal bytes, then retry the exact plan replacement.");
+    }
     const discovered = discovery
         ? validateEntityDiscovery(root, sourceRoot, discovery)
         : validateEntityState(root, sourceRoot);
@@ -57,7 +82,24 @@ function all(root, sourceRoot, discovery) {
     return relevant;
 }
 function planStatus(entity) { return String(mapping(entity.record?.header) ? entity.record.header.status ?? "" : entity.record?.status ?? ""); }
-function selectedPlan(entities, requested) {
+/**
+ * Report competing canonical plans without inferring replacement roles from
+ * list order. The targeted replacement command remains the one recovery seam.
+ */
+export function openPlanConflictDiagnostic(openIds, sourceRoot = resolveSourceRoot()) {
+    const allIds = [...openIds].sort();
+    const sampleIds = allIds.slice(0, contract(sourceRoot).openPlanConflictLimit);
+    const omittedCount = allIds.length - sampleIds.length;
+    return {
+        message: `multiple open plans exist: ${sampleIds.join(", ")} (total=${allIds.length}, omitted=${omittedCount}); canonical state does not assign predecessor or successor roles`,
+        details: { open_plan_candidates: { total: allIds.length, sample_ids: sampleIds, omitted_count: omittedCount } },
+        recovery: preCutoverCommand("state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json"),
+    };
+}
+function multipleOpenPlanConflict(open, sourceRoot) {
+    return openPlanConflictDiagnostic(open.map((entity) => entity.id), sourceRoot);
+}
+function selectedPlan(entities, requested, sourceRoot = resolveSourceRoot()) {
     if (requested !== undefined && !ID.test(requested))
         throw failure("invalid_request", `plan ID '${requested}' must be ten lowercase letters`, "Use a bare plan ID returned by plan create or list.", requested);
     const plans = entities.filter((entity) => entity.boundary === PLAN);
@@ -72,7 +114,94 @@ function selectedPlan(entities, requested) {
         return open[0];
     if (open.length === 0)
         throw failure("not_found", "no open plan exists", "Create a plan, or use agentera state plan get --id ID for completed plan detail.");
-    throw failure("ambiguous", `multiple open plans exist: ${open.map(({ id }) => id).sort().join(", ")}`, "List plans, then use agentera state plan get --id ID or agentera state plan tasks list PLAN_ID.");
+    const conflict = multipleOpenPlanConflict(open, sourceRoot);
+    throw failure("ambiguous", conflict.message, conflict.recovery, undefined, conflict.details);
+}
+function archivedPlanRecord(plan) {
+    const record = structuredClone(plan.record);
+    const header = mapping(record.header) ? record.header : {};
+    header.status = "archived";
+    record.header = header;
+    return record;
+}
+function preservedPlanEffects(plan) {
+    return {
+        id: plan.id,
+        from_status: planStatus(plan),
+        to_status: "archived",
+        preserved: ["task_records", "task_evaluations", "task_completion"],
+    };
+}
+function planLifecycleDecision(entities, intent, sourceRoot) {
+    const plans = entities.filter((entity) => entity.boundary === PLAN);
+    const open = plans.filter((entity) => planStatus(entity) === "open");
+    if (intent.verb === "create") {
+        if (open.length > 1) {
+            const conflict = multipleOpenPlanConflict(open, sourceRoot);
+            reject({
+                class: "conflict",
+                message: `${conflict.message}; implicit plan create cannot choose a predecessor`,
+                diagnosis: conflict.details,
+                recovery: conflict.recovery,
+            });
+        }
+        if (open.length === 1) {
+            const predecessor = open[0];
+            if (!intent.force) {
+                reject({
+                    class: "conflict",
+                    message: `open plan '${predecessor.id}' blocks plan create`,
+                    recovery: `Use agentera state plan create --force --input PLAN.yaml --format json only to archive '${predecessor.id}' unchanged and publish a successor.`,
+                });
+            }
+            return {
+                predecessor,
+                archivedRecord: archivedPlanRecord(predecessor),
+                replay: false,
+                effects: {
+                    lifecycle: "forced_replacement",
+                    force: true,
+                    archived_predecessor: preservedPlanEffects(predecessor),
+                    successor_lineage: { field: "previous_plan_archived", predecessor: predecessor.id },
+                },
+            };
+        }
+        const completed = plans.filter((entity) => planStatus(entity) === "complete");
+        const predecessor = completed.length === 1 ? completed[0] : undefined;
+        return {
+            ...(predecessor ? { predecessor, archivedRecord: archivedPlanRecord(predecessor) } : {}),
+            replay: false,
+            effects: {
+                lifecycle: predecessor ? "completed_predecessor_replacement" : "create",
+                force: intent.force,
+                ...(predecessor ? {
+                    archived_predecessor: preservedPlanEffects(predecessor),
+                    successor_lineage: { field: "previous_plan_archived", predecessor: predecessor.id },
+                } : {}),
+            },
+        };
+    }
+    const target = selectedPlan(entities, intent.plan, sourceRoot);
+    const status = planStatus(target);
+    if (status === "open" && !intent.force) {
+        reject({
+            class: "conflict",
+            message: `open plan '${target.id}' cannot be archived without --force`,
+            recovery: `Complete '${target.id}', or use agentera state plan archive --plan ${target.id} --force --format json to preserve unfinished task history without claiming completion.`,
+        });
+    }
+    const archivedRecord = archivedPlanRecord(target);
+    const replay = canonicalRecordJson(archivedRecord) === canonicalRecordJson(target.record);
+    return {
+        target,
+        archivedRecord,
+        replay,
+        effects: {
+            lifecycle: status === "open" ? "forced_archive" : "archive",
+            force: intent.force,
+            archived_plan: preservedPlanEffects(target),
+        },
+    };
 }
 function taskFor(entities, id, plan) {
     if (!ID.test(id))
@@ -100,6 +229,12 @@ function newId(root, sourceRoot, reserved, candidate) {
     }
     throw new Error("could not allocate unique plan entity IDs");
 }
+function preparedPlanCreateInput(req) {
+    const input = structuredClone(req.input ?? {});
+    normalizeAndValidatePlanCreateInput(input);
+    validatePlanPublicationCandidate(dumpYamlMapping(input));
+    return input;
+}
 export function createPlanEntities(req, options = {}) {
     if (!options.publicationContext) {
         const binding = detectStateModeBinding(req.projectRoot, options.sourceRoot);
@@ -116,9 +251,11 @@ export function createPlanEntities(req, options = {}) {
 }
 function createPlanEntitiesUnderLock(req, options) {
     const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
-    const input = structuredClone(req.input ?? {});
-    normalizeAndValidatePlanCreateInput(input);
-    validatePlanPublicationCandidate(dumpYamlMapping(input));
+    const input = preparedPlanCreateInput(req);
+    const discovery = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
+    const entities = all(options.publicationContext.pinnedPath(), sourceRoot, discovery);
+    const lifecycle = options.lifecycle ?? planLifecycleDecision(entities, { verb: "create", force: req.force }, sourceRoot);
+    const command = options.command ?? "state plan create";
     const tasks = Array.isArray(input.tasks) ? input.tasks.filter(mapping) : [];
     const reserved = new Set();
     const planId = newId(options.publicationContext?.pinnedPath() ?? req.projectRoot, sourceRoot, reserved, options.candidate);
@@ -127,6 +264,7 @@ function createPlanEntitiesUnderLock(req, options) {
     const planRecord = structuredClone(input);
     delete planRecord.tasks;
     delete planRecord.previous_plan_archived;
+    delete planRecord.replacement_input_sha256;
     const header = mapping(planRecord.header) ? planRecord.header : {};
     delete header.id;
     planRecord.header = header;
@@ -134,6 +272,10 @@ function createPlanEntitiesUnderLock(req, options) {
         header.status = "open";
     if (header.status === "completed")
         header.status = "complete";
+    if (lifecycle.predecessor)
+        planRecord.previous_plan_archived = lifecycle.predecessor.id;
+    if (lifecycle.replacementInputSha256)
+        planRecord.replacement_input_sha256 = lifecycle.replacementInputSha256;
     const taskRecords = tasks.map((task, index) => {
         const record = structuredClone(task);
         delete record.number;
@@ -151,23 +293,36 @@ function createPlanEntitiesUnderLock(req, options) {
     });
     const publications = [{ boundary: PLAN, id: planId, record: planRecord }, ...taskRecords.map((record, index) => ({ boundary: TASK, id: taskIds[index], record }))];
     if (req.dryRun)
-        return envelope("state plan create", { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, true, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })) });
-    const discovery = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
-    const entities = all(options.publicationContext.pinnedPath(), sourceRoot, discovery);
-    const openPlans = entities.filter((entity) => entity.boundary === PLAN && planStatus(entity) === "open");
-    const completedPlans = entities.filter((entity) => entity.boundary === PLAN && planStatus(entity) === "complete");
-    const currentPredecessor = openPlans.length === 0 && completedPlans.length === 1 ? completedPlans[0] : undefined;
+        return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, true, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })), effects: lifecycle.effects });
+    if (command === "state plan replace" && lifecycle.predecessor && lifecycle.archivedRecord && lifecycle.replacementInputSha256) {
+        const targets = [
+            {
+                path: relative(req.projectRoot, lifecycle.predecessor.path),
+                before: exactDiscoveredEntityBytes(lifecycle.predecessor),
+                after: canonicalEntityEnvelopeBytes({ id: lifecycle.predecessor.id, artifact: ARTIFACT, record: lifecycle.archivedRecord, migrationProvenance: lifecycle.predecessor.migrationProvenance ?? undefined }),
+            },
+            ...publications.map((item) => ({
+                path: relative(req.projectRoot, entityPath(req.projectRoot, sourceRoot, item.boundary, item.id)),
+                before: null,
+                after: canonicalEntityEnvelopeBytes({ id: item.id, artifact: ARTIFACT, record: item.record }),
+            })),
+        ];
+        publishPlanReplacement(options.publicationContext, sourceRoot, { kind: "create", predecessor: lifecycle.predecessor.id, successor: planId, inputSha256: lifecycle.replacementInputSha256 }, targets, {
+            validate: () => {
+                const validation = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
+                if (!validation.valid)
+                    throw new Error(`targeted plan replacement graph failed state validation: ${validation.issues.map(({ message }) => message).join("; ")}`);
+            },
+        });
+        return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })), effects: lifecycle.effects });
+    }
     const published = [];
     let predecessor;
     try {
-        if (currentPredecessor) {
-            const archivedRecord = structuredClone(currentPredecessor.record);
-            const archivedHeader = mapping(archivedRecord.header) ? archivedRecord.header : {};
-            archivedHeader.status = "archived";
-            archivedRecord.header = archivedHeader;
-            const archived = replaceEntityUnderLock({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: PLAN, id: currentPredecessor.id, expectedRecord: currentPredecessor.record, expectedBytes: exactDiscoveredEntityBytes(currentPredecessor), migrationProvenance: currentPredecessor.migrationProvenance, record: archivedRecord });
+        if (lifecycle.predecessor && lifecycle.archivedRecord) {
+            const archived = replaceEntityUnderLock({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: PLAN, id: lifecycle.predecessor.id, expectedRecord: lifecycle.predecessor.record, expectedBytes: exactDiscoveredEntityBytes(lifecycle.predecessor), migrationProvenance: lifecycle.predecessor.migrationProvenance, record: lifecycle.archivedRecord });
             if (!archived.publishedIdentity || archived.previousBytes === undefined)
-                throw new Error(`completed predecessor '${currentPredecessor.id}' archive did not retain its exact recovery identity and bytes`);
+                throw new Error(`predecessor '${lifecycle.predecessor.id}' archive did not retain its exact recovery identity and bytes`);
             predecessor = { relative: relative(req.projectRoot, archived.path), archivedIdentity: archived.publishedIdentity, bytes: archived.previousBytes };
         }
         for (const item of publications) {
@@ -208,7 +363,291 @@ function createPlanEntitiesUnderLock(req, options) {
             throw new Error(`plan replacement failed: ${error.message}; recovery failed: ${recoveryFailures.join("; ")}`, { cause: error });
         throw error;
     }
-    return envelope("state plan create", { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })) });
+    return envelope(command, { id: planId, path: entityPath(req.projectRoot, sourceRoot, PLAN, planId), replay: false }, planRecord, false, { tasks: taskRecords.map((record, index) => ({ id: taskIds[index], artifact: ARTIFACT, record })), effects: lifecycle.effects });
+}
+function replacementEffects(predecessor, successor) {
+    return {
+        lifecycle: "targeted_replacement",
+        predecessor: {
+            id: predecessor.id,
+            transition: "archived",
+            preserved: ["task_records", "task_evaluations", "task_completion"],
+        },
+        successor: {
+            ...(successor ? { id: successor.id } : {}),
+            created: !successor,
+            lineage: { field: "previous_plan_archived", predecessor: predecessor.id },
+        },
+    };
+}
+function successorForPredecessor(entities, predecessor) {
+    const matches = entities.filter((entity) => entity.boundary === PLAN && entity.record?.previous_plan_archived === predecessor.id);
+    if (matches.length > 1) {
+        reject({
+            class: "conflict",
+            message: `archived predecessor '${predecessor.id}' has multiple canonical successor plans`,
+            recovery: "Repair canonical plan lineage so one archived predecessor has one successor before retrying targeted replacement.",
+        });
+    }
+    return matches[0];
+}
+function assertNoUnselectedOpenPlans(entities, selected, sourceRoot) {
+    const selectedIds = new Set(selected.map((entity) => entity.id));
+    const unselected = entities
+        .filter((entity) => entity.boundary === PLAN && planStatus(entity) === "open" && !selectedIds.has(entity.id))
+        .map((entity) => entity.id)
+        .sort();
+    if (unselected.length > 0) {
+        const conflict = multipleOpenPlanConflict(entities.filter((entity) => entity.boundary === PLAN && planStatus(entity) === "open"), sourceRoot);
+        reject({
+            class: "conflict",
+            message: `${conflict.message}; targeted plan replacement would leave ${unselected.length} unnamed open plan${unselected.length === 1 ? "" : "s"}`,
+            diagnosis: conflict.details,
+            recovery: conflict.recovery,
+        });
+    }
+}
+function existingReplacementDecision(entities, predecessor, successor, sourceRoot) {
+    if (predecessor.id === successor.id) {
+        reject({ class: "schema_violation", message: "targeted plan replacement requires distinct predecessor and successor IDs" });
+    }
+    const derived = successorForPredecessor(entities, predecessor);
+    if (planStatus(predecessor) === "archived") {
+        if (!derived || derived.id !== successor.id) {
+            reject({
+                class: "conflict",
+                message: `archived predecessor '${predecessor.id}' is already replaced by '${derived?.id ?? "no canonical successor"}', not '${successor.id}'`,
+                recovery: "Retry with the derived bare successor ID, or correct the divergent replacement request before any lifecycle mutation.",
+            });
+        }
+        return {
+            predecessor,
+            successor,
+            successorRecord: structuredClone(successor.record),
+            replay: true,
+            effects: replacementEffects(predecessor, successor),
+        };
+    }
+    if (!new Set(["open", "complete"]).has(planStatus(predecessor))) {
+        reject({ class: "conflict", message: `plan '${predecessor.id}' is ${planStatus(predecessor)} and cannot be a replacement predecessor` });
+    }
+    if (derived || successor.record?.previous_plan_archived !== undefined || successor.record?.replacement_input_sha256 !== undefined) {
+        reject({ class: "conflict", message: `successor '${successor.id}' already has canonical plan lineage and cannot be reassigned` });
+    }
+    if (planStatus(successor) !== "open") {
+        reject({ class: "conflict", message: `successor '${successor.id}' must be open for targeted replacement` });
+    }
+    assertNoUnselectedOpenPlans(entities, [predecessor, successor], sourceRoot);
+    const successorRecord = structuredClone(successor.record);
+    const inputSha256 = replacementSuccessorInputSha256(entities, successor);
+    successorRecord.previous_plan_archived = predecessor.id;
+    successorRecord.replacement_input_sha256 = inputSha256;
+    return {
+        predecessor,
+        successor,
+        archivedRecord: archivedPlanRecord(predecessor),
+        successorRecord,
+        inputSha256,
+        replay: false,
+        effects: replacementEffects(predecessor, successor),
+    };
+}
+function replacementPlanRecord(input) {
+    const record = structuredClone(input);
+    delete record.tasks;
+    delete record.previous_plan_archived;
+    delete record.replacement_input_sha256;
+    const header = mapping(record.header) ? record.header : {};
+    delete header.id;
+    if (header.status === "active")
+        header.status = "open";
+    if (header.status === "completed")
+        header.status = "complete";
+    record.header = header;
+    return record;
+}
+function uniqueReplacementTaskNames(tasks, context, failureClass) {
+    const names = new Map();
+    for (const task of tasks) {
+        const name = task.name;
+        if (typeof name !== "string" || name.length === 0) {
+            reject({ class: failureClass, message: `${context} contains a task without a non-empty name` });
+        }
+        if (names.has(name)) {
+            reject({ class: failureClass, message: `${context} contains duplicate task name '${name}', so replacement replay cannot identify a task` });
+        }
+        names.set(name, task);
+    }
+    return names;
+}
+function logicalReplacementTask(record, dependencies, resolveDependency) {
+    const logical = structuredClone(record);
+    for (const field of ["number", "plan", "status", "evaluation", "superseded_by", "superseded_reason"])
+        delete logical[field];
+    logical.depends_on = dependencies.map(resolveDependency);
+    if (!Array.isArray(logical.acceptance))
+        logical.acceptance = [];
+    return logical;
+}
+function replacementInputFingerprint(input) {
+    const tasks = Array.isArray(input.tasks) ? input.tasks.filter(mapping) : [];
+    const names = uniqueReplacementTaskNames(tasks, "replacement input", "schema_violation");
+    const byOrdinal = new Map(tasks.map((task, index) => [String(index + 1), String(task.name)]));
+    const logicalTasks = [...names.entries()].map(([name, task]) => {
+        const dependencies = Array.isArray(task.depends_on) ? task.depends_on : [];
+        const record = logicalReplacementTask(task, dependencies, (dependency) => {
+            const target = byOrdinal.get(String(dependency));
+            if (!target)
+                throw new Error(`replacement input dependency '${String(dependency)}' was not normalized before replay comparison`);
+            return target;
+        });
+        return [name, record];
+    });
+    return { plan: replacementPlanRecord(input), tasks: Object.fromEntries(logicalTasks.sort(([left], [right]) => left.localeCompare(right))) };
+}
+function replacementInputSha256(input) {
+    return createHash("sha256")
+        .update("agentera.planReplacementInput.v1\0")
+        .update(canonicalRecordJson(replacementInputFingerprint(input)))
+        .digest("hex");
+}
+function replacementSuccessorInputSha256(entities, successor) {
+    const tasks = entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === successor.id);
+    const records = tasks.map((task) => structuredClone(task.record));
+    const names = uniqueReplacementTaskNames(records, `successor '${successor.id}'`, "conflict");
+    const namesById = new Map(tasks.map((task) => [task.id, String(task.record.name)]));
+    const logicalTasks = [...names.entries()].map(([name, task]) => {
+        const dependencies = Array.isArray(task.depends_on) ? task.depends_on : [];
+        const record = logicalReplacementTask(task, dependencies, (dependency) => {
+            const target = typeof dependency === "string" ? namesById.get(dependency) : undefined;
+            if (!target)
+                throw new Error(`successor '${successor.id}' has a task dependency outside its canonical task graph`);
+            return target;
+        });
+        return [name, record];
+    });
+    return createHash("sha256")
+        .update("agentera.planReplacementInput.v1\0")
+        .update(canonicalRecordJson({ plan: replacementPlanRecord(successor.record), tasks: Object.fromEntries(logicalTasks.sort(([left], [right]) => left.localeCompare(right))) }))
+        .digest("hex");
+}
+function assertReplacementInputReplay(input, successor) {
+    if (successor.record?.replacement_input_sha256 !== replacementInputSha256(input)) {
+        reject({
+            class: "conflict",
+            message: `replacement input diverges from immutable successor identity '${successor.id}'`,
+            recovery: "Retry the exact logical successor plan input, or start a new targeted replacement from an open predecessor; no state was changed.",
+        });
+    }
+}
+function createReplacementLifecycle(entities, predecessor, inputSha256, sourceRoot) {
+    const successor = successorForPredecessor(entities, predecessor);
+    if (planStatus(predecessor) === "archived") {
+        if (!successor) {
+            reject({
+                class: "conflict",
+                message: `archived predecessor '${predecessor.id}' has no canonical successor to replay`,
+                recovery: "Do not create a second successor for an archived predecessor. Select an open predecessor or repair canonical lineage first.",
+            });
+        }
+        return { replaySuccessor: successor };
+    }
+    if (!new Set(["open", "complete"]).has(planStatus(predecessor))) {
+        reject({ class: "conflict", message: `plan '${predecessor.id}' is ${planStatus(predecessor)} and cannot be a replacement predecessor` });
+    }
+    if (successor) {
+        reject({ class: "conflict", message: `predecessor '${predecessor.id}' already has successor '${successor.id}' before archival` });
+    }
+    assertNoUnselectedOpenPlans(entities, [predecessor], sourceRoot);
+    return {
+        lifecycle: {
+            predecessor,
+            archivedRecord: archivedPlanRecord(predecessor),
+            replacementInputSha256: inputSha256,
+            replay: false,
+            effects: replacementEffects(predecessor),
+        },
+    };
+}
+function publishExistingPlanReplacement(req, options, sourceRoot, decision) {
+    const command = "state plan replace";
+    if (decision.replay)
+        return envelope(command, { id: decision.successor.id, path: decision.successor.path, replay: true }, decision.successorRecord, req.dryRun, { effects: decision.effects });
+    if (req.dryRun)
+        return envelope(command, { id: decision.successor.id, path: decision.successor.path, replay: false }, decision.successorRecord, true, { effects: decision.effects });
+    if (!decision.inputSha256)
+        throw new Error(`successor '${decision.successor.id}' has no immutable replacement input identity`);
+    publishPlanReplacement(options.publicationContext, sourceRoot, { kind: "existing", predecessor: decision.predecessor.id, successor: decision.successor.id, inputSha256: decision.inputSha256 }, [
+        {
+            path: relative(req.projectRoot, decision.predecessor.path),
+            before: exactDiscoveredEntityBytes(decision.predecessor),
+            after: canonicalEntityEnvelopeBytes({ id: decision.predecessor.id, artifact: ARTIFACT, record: decision.archivedRecord, migrationProvenance: decision.predecessor.migrationProvenance ?? undefined }),
+        },
+        {
+            path: relative(req.projectRoot, decision.successor.path),
+            before: exactDiscoveredEntityBytes(decision.successor),
+            after: canonicalEntityEnvelopeBytes({ id: decision.successor.id, artifact: ARTIFACT, record: decision.successorRecord, migrationProvenance: decision.successor.migrationProvenance ?? undefined }),
+        },
+    ], {
+        validate: () => {
+            const validation = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
+            if (!validation.valid)
+                throw new Error(`targeted plan replacement graph failed state validation: ${validation.issues.map(({ message }) => message).join("; ")}`);
+        },
+    });
+    return envelope(command, { id: decision.successor.id, path: decision.successor.path, replay: false }, decision.successorRecord, false, { effects: decision.effects });
+}
+export function replacePlanEntities(req, options = {}) {
+    if (!options.publicationContext) {
+        const binding = detectStateModeBinding(req.projectRoot, options.sourceRoot);
+        if (binding.mode !== "entities")
+            throw new Error("plan entity replacement requires the durable entity-mode marker");
+        try {
+            return replacePlanEntities(req, { ...options, publicationContext: binding.publicationContext });
+        }
+        finally {
+            binding.publicationContext.close();
+        }
+    }
+    return withEntityWriterLock(options.publicationContext, () => replacePlanEntitiesUnderLock(req, options));
+}
+function replacePlanEntitiesUnderLock(req, options) {
+    const command = "state plan replace";
+    const predecessorId = req.values.predecessor;
+    const successorId = req.values.successor;
+    if (typeof predecessorId !== "string")
+        reject({ class: "missing_argument", message: "--predecessor is required for plan replace" });
+    if (successorId !== undefined && typeof successorId !== "string")
+        reject({ class: "schema_violation", message: "--successor must be a bare plan ID when present" });
+    if (successorId !== undefined && req.input !== null)
+        reject({ class: "mutually_exclusive", message: "plan replace accepts either --successor or --input, not both" });
+    if (successorId === undefined && req.input === null)
+        reject({ class: "missing_argument", message: "plan replace requires either --successor ID or --input PLAN.yaml" });
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const input = successorId === undefined ? preparedPlanCreateInput(req) : undefined;
+    const inputSha256 = input ? replacementInputSha256(input) : undefined;
+    recoverPendingPlanReplacement(options.publicationContext, sourceRoot, typeof successorId === "string"
+        ? { predecessor: predecessorId, successor: successorId }
+        : { predecessor: predecessorId, inputSha256 }, {
+        validate: () => {
+            const validation = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
+            if (!validation.valid)
+                throw new Error(`targeted plan replacement graph failed state validation: ${validation.issues.map(({ message }) => message).join("; ")}`);
+        },
+    });
+    const discovery = validateEntityState(options.publicationContext.pinnedPath(), sourceRoot, { kind: "project", projectRoot: options.publicationContext.validatedRoot });
+    const entities = all(options.publicationContext.pinnedPath(), sourceRoot, discovery);
+    const predecessor = selectedPlan(entities, predecessorId, sourceRoot);
+    if (typeof successorId === "string") {
+        const successor = selectedPlan(entities, successorId, sourceRoot);
+        return publishExistingPlanReplacement(req, options, sourceRoot, existingReplacementDecision(entities, predecessor, successor, sourceRoot));
+    }
+    const lifecycle = createReplacementLifecycle(entities, predecessor, inputSha256, sourceRoot);
+    if (lifecycle.replaySuccessor) {
+        assertReplacementInputReplay(input, lifecycle.replaySuccessor);
+        return envelope(command, { id: lifecycle.replaySuccessor.id, path: lifecycle.replaySuccessor.path, replay: true }, lifecycle.replaySuccessor.record, req.dryRun, { effects: replacementEffects(predecessor) });
+    }
+    return createPlanEntitiesUnderLock(req, { ...options, lifecycle: lifecycle.lifecycle, command });
 }
 function taskRecord(req, plan) {
     const input = req.input ?? {};
@@ -342,13 +781,26 @@ function supersedeTask(entities, task, taskId, planId, values) {
     return record;
 }
 export function mutatePlanEntities(req, options = {}) {
-    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
-    const entities = all(req.projectRoot, sourceRoot);
     if (req.spec.verb === "create")
         return createPlanEntities(req, options);
+    if (req.spec.verb === "replace")
+        return replacePlanEntities(req, options);
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const entities = all(req.projectRoot, sourceRoot);
     if (req.spec.verb === "set-plan-status" && req.values.id !== undefined)
         reject({ class: "invalid_request", message: "plan set-plan-status accepts only the --plan selector; --id is a task selector and is not valid for plan lifecycle" });
-    const plan = selectedPlan(entities, typeof req.values.plan === "string" ? req.values.plan : undefined);
+    if (req.spec.verb === "archive") {
+        const lifecycle = planLifecycleDecision(entities, { verb: "archive", force: req.force, ...(typeof req.values.plan === "string" ? { plan: req.values.plan } : {}) }, sourceRoot);
+        const plan = lifecycle.target;
+        const record = lifecycle.archivedRecord;
+        if (lifecycle.replay)
+            return envelope("state plan archive", { id: plan.id, path: plan.path, replay: true }, record, req.dryRun, { effects: lifecycle.effects });
+        if (req.dryRun)
+            return envelope("state plan archive", { id: plan.id, path: plan.path, replay: false }, record, true, { effects: lifecycle.effects });
+        const result = replaceEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: PLAN, id: plan.id, expectedRecord: plan.record, expectedBytes: exactDiscoveredEntityBytes(plan), migrationProvenance: plan.migrationProvenance, record });
+        return envelope("state plan archive", result, record, false, { effects: lifecycle.effects });
+    }
+    const plan = selectedPlan(entities, typeof req.values.plan === "string" ? req.values.plan : undefined, sourceRoot);
     if (req.spec.verb === "append") {
         if (!OPEN.has(planStatus(plan)))
             reject({ class: "conflict", message: `plan '${plan.id}' is ${planStatus(plan)} and cannot accept a new task` });
@@ -364,16 +816,16 @@ export function mutatePlanEntities(req, options = {}) {
         const result = publishEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: TASK, id, record });
         return envelope("state plan append", result, record, false);
     }
-    if (req.spec.verb === "set-plan-status" || req.spec.verb === "archive") {
+    if (req.spec.verb === "set-plan-status") {
         const tasks = entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === plan.id);
-        const requested = req.spec.verb === "archive" ? "archived" : String(req.values.status);
-        if (planStatus(plan) === "archived" && req.spec.verb !== "archive")
+        const requested = String(req.values.status);
+        if (planStatus(plan) === "archived")
             reject({ class: "conflict", message: `archived plan '${plan.id}' is immutable` });
         const record = structuredClone(plan.record);
         const header = mapping(record.header) ? record.header : {};
         header.status = requested;
         record.header = header;
-        const command = req.spec.verb === "archive" ? "state plan archive" : "state plan set-plan-status";
+        const command = "state plan set-plan-status";
         if (canonicalRecordJson(record) === canonicalRecordJson(plan.record))
             return envelope(command, { id: plan.id, path: plan.path, replay: true }, record, req.dryRun);
         if (requested === "complete" && tasks.some((task) => !["complete", "superseded"].includes(String(task.record?.status))))
@@ -513,15 +965,15 @@ function boundedList(root, sourceRoot, selected, allEntities, limit, cursor, ord
     const response = { schemaVersion: "agentera.stateList.v1", command, status: remaining ? "degraded" : "ok", entries: page.map((entity) => entry(root, entity)), counts: { total: selected.length, returned: page.length, remaining }, order, filters: filter, snapshot: { id: snap, first_page: !cursor, has_more: Boolean(remaining), candidate_count: selected.length }, source: { artifact: ARTIFACT, authority: "canonical_entity_files", root: declared.entityRoot }, retrieval: { ...(next ? { continue: `${command.replace("state ", "agentera state ")}${familyIdentifier}${filterFlags}${selectorFlags} --limit ${take} --cursor ${next} --format json` } : {}) }, ...(remaining ? { omitted: true, omitted_count: remaining, omission_reason: "page_limit", next_cursor: next } : {}), ...envelope };
     return projectEntityList(response, selector, projectionOptions);
 }
-export function getPlanEntity(root, id, sourceRoot = resolveSourceRoot()) { const entities = all(root, sourceRoot); const plan = selectedPlan(entities, id); return { schemaVersion: "agentera.stateGet.v1", command: "state plan get", status: "ok", entry: entry(root, plan), tasks: entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === id).sort((a, b) => a.id.localeCompare(b.id)).map((entity) => entry(root, entity)), source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: "full_entities" } }; }
+export function getPlanEntity(root, id, sourceRoot = resolveSourceRoot()) { const entities = all(root, sourceRoot); const plan = selectedPlan(entities, id, sourceRoot); return { schemaVersion: "agentera.stateGet.v1", command: "state plan get", status: "ok", entry: entry(root, plan), tasks: entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === id).sort((a, b) => a.id.localeCompare(b.id)).map((entity) => entry(root, entity)), source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: "full_entities" } }; }
 export function listPlanEntities(root, limit, cursor, options = {}) { const sourceRoot = options.sourceRoot ?? resolveSourceRoot(); const entities = all(root, sourceRoot, options.discovery); const statuses = options.statuses?.length ? new Set(options.statuses) : undefined; const plans = entities.filter((entity) => entity.boundary === PLAN && (!statuses || statuses.has(planStatus(entity)))).sort((a, b) => String(mapping(b.record?.header) ? b.record.header.created ?? "" : "").localeCompare(String(mapping(a.record?.header) ? a.record.header.created ?? "" : "")) || a.id.localeCompare(b.id)); return boundedList(root, sourceRoot, plans, entities, limit, cursor, ORDER, "state plan list", options.statuses ? { status: options.statuses } : {}, options.format, {}, undefined, options.selector); }
 export function getPlanTaskEntity(root, id, planId, sourceRoot = resolveSourceRoot()) { const entities = all(root, sourceRoot); const task = taskFor(entities, id, planId); return { schemaVersion: "agentera.stateGet.v1", command: "state plan tasks get", status: "ok", entry: entry(root, task), source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: "full_entity" } }; }
 export function listPlanTaskEntities(root, planId, limit, cursor, options = {}) { const sourceRoot = options.sourceRoot ?? resolveSourceRoot(); const entities = all(root, sourceRoot, options.discovery); const declared = contract(sourceRoot); const decodedCursor = cursor ? decode(cursor, root, declared.authorityPath) : undefined; const cursorFilter = mapping(decodedCursor?.filter) ? decodedCursor.filter : undefined; const cursorPlan = typeof cursorFilter?.plan === "string" && ID.test(cursorFilter.plan) ? cursorFilter.plan : undefined; if (decodedCursor && !cursorPlan)
-    throw failure("cursor_snapshot_unavailable", "plan state changed after this cursor snapshot", "Omit --cursor to restart from current state."); const plan = selectedPlan(entities, planId ?? cursorPlan); const tasks = entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === plan.id).sort((a, b) => a.id.localeCompare(b.id)); return boundedList(root, sourceRoot, tasks, entities, limit, cursor, TASK_ORDER, "state plan tasks list", { plan: plan.id }, options.format, {}, decodedCursor, options.selector); }
+    throw failure("cursor_snapshot_unavailable", "plan state changed after this cursor snapshot", "Omit --cursor to restart from current state."); const plan = selectedPlan(entities, planId ?? cursorPlan, sourceRoot); const tasks = entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === plan.id).sort((a, b) => a.id.localeCompare(b.id)); return boundedList(root, sourceRoot, tasks, entities, limit, cursor, TASK_ORDER, "state plan tasks list", { plan: plan.id }, options.format, {}, decodedCursor, options.selector); }
 export function currentPlanEntityView(root, limit, cursor, status, options = {}) {
     const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
     const entities = all(root, sourceRoot);
-    const plan = selectedPlan(entities);
+    const plan = selectedPlan(entities, undefined, sourceRoot);
     let tasks = entities.filter((entity) => entity.boundary === TASK && entity.record?.plan === plan.id);
     if (status)
         tasks = tasks.filter((entity) => entity.record?.status === status);