@agent-plan/core 0.2.22 → 0.2.23-next.0

package/dist/plan-store.js

@@ -14,12 +14,26 @@ const PLANNER_GITIGNORE = [
     "generated/",
     "",
 ].join("\n");
-import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskPauseSnapshotSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, } from "./schema.js";
+import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskPauseSnapshotSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, WorkDeviationSchema, } from "./schema.js";
 import { createFeatureId, createPhaseId, createRequirementId, createShortId, createStatusLogEntryId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
 import { deriveParentDisplay, fromCanonicalStatus } from "./display-status.js";
+import { loadExtensionRules, PLANNER_EXTENSION_RULES } from "./planner-rules.js";
+import { applyHandoffContextSync, auditPhaseHandoff, } from "./handoff-context.js";
 function nowISO() {
     return new Date().toISOString();
 }
+const MAX_SESSION_INFO_ENTRIES = 16;
+function upsertSessionInfo(entity, sessionId, createdAt) {
+    const nextInfo = [
+        ...entity.sessionInfo.filter((entry) => entry.sessionId !== sessionId),
+        { sessionId, createdAt },
+    ]
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
+        .slice(0, MAX_SESSION_INFO_ENTRIES);
+    const changed = nextInfo.length !== entity.sessionInfo.length
+        || nextInfo.some((entry, index) => entry.sessionId !== entity.sessionInfo[index]?.sessionId || entry.createdAt !== entity.sessionInfo[index]?.createdAt);
+    return changed ? { entity: { ...entity, sessionInfo: nextInfo }, changed: true } : { entity, changed: false };
+}
 function resolveStoredFeatureId(features, ref) {
     const raw = ref?.trim();
     if (!raw)
@@ -417,6 +431,41 @@ export async function migrateToGlobalSequence(store) {
         return { migrated: true, phases: newPhases.length, tasks: numberedTasks.length, features: newFeatures.length };
     });
 }
+/** Map legacy/removed status strings to their canonical replacements before
+ * schema validation. Canonical task status "paused" was removed from the
+ * domain; persisted entities (tasks, statusLog entries) may still carry it.
+ * Rewriting on read keeps legacy data loadable without a one-time migration
+ * pass, and the normalized value is persisted on the next save. Scoped to
+ * status-bearing fields so unrelated string values are never touched. */
+function migrateLegacyStatuses(value) {
+    if (Array.isArray(value))
+        return value.map(migrateLegacyStatuses);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if ((key === "status" || key === "fromStatus" || key === "toStatus") && child === "paused") {
+                out[key] = "planned";
+            }
+            else {
+                out[key] = migrateLegacyStatuses(child);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+/** Walk up from `path` to find the owning `.planner` root, so crash-recovery
+ *  can locate `.local/backups/<rel>.bak` without every readJson caller threading
+ *  `root`. Returns undefined if no `.planner` ancestor exists. */
+function findPlannerRoot(path) {
+    let dir = dirname(path);
+    while (dir !== dirname(dir)) {
+        if (basename(dir) === ".planner")
+            return dir;
+        dir = dirname(dir);
+    }
+    return undefined;
+}
 async function readJson(path, schema) {
     let backupTried = false;
     let backupFailed = false;
@@ -424,20 +473,36 @@ async function readJson(path, schema) {
     try {
         const raw = await readFile(path, "utf-8");
         rawPreview = raw.slice(0, 240);
-        return schema.parse(JSON.parse(raw));
+        return schema.parse(migrateLegacyStatuses(JSON.parse(raw)));
     }
     catch (cause) {
-        // Try the .bak backup before giving up (recover from external-write corruption).
+        // Recover from the previous-version backup before giving up:
+        //  1) legacy inline `<file>.bak` (next to the source), then
+        //  2) the relocated `.planner/.local/backups/<rel>.bak` (P043).
         backupTried = true;
-        try {
-            const bak = await readFile(`${path}.bak`, "utf-8");
-            rawPreview = bak.slice(0, 240);
-            return schema.parse(JSON.parse(bak));
-        }
-        catch {
-            backupFailed = true;
-            // fall through to original error
-        }
+        const tryBackup = async (bakPath) => {
+            try {
+                const bak = await readFile(bakPath, "utf-8");
+                rawPreview = bak.slice(0, 240);
+                return schema.parse(migrateLegacyStatuses(JSON.parse(bak)));
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const inline = await tryBackup(`${path}.bak`);
+        if (inline !== undefined)
+            return inline;
+        let local;
+        const plannerRoot = findPlannerRoot(path);
+        if (plannerRoot) {
+            const rel = path.slice(plannerRoot.length).replace(/^\//, "");
+            local = await tryBackup(join(plannerRoot, ".local", "backups", rel + ".bak"));
+        }
+        if (local !== undefined)
+            return local;
+        backupFailed = true;
+        // fall through to original error
         const details = {
             path,
             operation: "readJson",
@@ -518,11 +583,43 @@ export class PlanStore {
     normalizeTasks(tasks) {
         // Numbers are a STABLE global sequence (assigned once at create from project.nextTaskNumber).
         // Do NOT renumber here — renumbering would break references after deletions.
-        const normalized = tasks.map((task) => task.description && !task.descriptionUpdatedAt
-            ? { ...task, descriptionUpdatedAt: task.createdAt }
-            : task);
+        const normalized = tasks.map((task) => {
+            const descriptionUpdatedAt = task.description && !task.descriptionUpdatedAt
+                ? task.createdAt
+                : task.descriptionUpdatedAt;
+            const normalizedStatus = task.status === "paused" ? "planned" : task.status;
+            const pauseSnapshot = this.isTerminalTaskStatus(normalizedStatus) ? null : task.pauseSnapshot;
+            const statusLog = (task.statusLog ?? []).map((entry) => ({
+                ...entry,
+                fromStatus: entry.fromStatus === "paused" ? "planned" : entry.fromStatus,
+                toStatus: entry.toStatus === "paused" ? "planned" : entry.toStatus,
+            }));
+            if (descriptionUpdatedAt !== task.descriptionUpdatedAt
+                || normalizedStatus !== task.status
+                || pauseSnapshot !== task.pauseSnapshot
+                || statusLog.some((entry, index) => entry !== task.statusLog[index])) {
+                return { ...task, descriptionUpdatedAt, status: normalizedStatus, pauseSnapshot, statusLog };
+            }
+            return task;
+        });
         return { tasks: normalized, changed: normalized.some((task, index) => task !== tasks[index]) };
     }
+    isTerminalTaskStatus(status) {
+        return status === "done" || status === "canceled" || status === "rejected";
+    }
+    async pruneObsoleteWorkDeviations() {
+        const phases = await this.loadAllPhases();
+        const taskStatusById = new Map(phases.flatMap((phase) => phase.tasks.map((task) => [task.id, task.status])));
+        const current = await this.loadWorkDeviations();
+        const next = current.filter((deviation) => {
+            const resumeStatus = taskStatusById.get(deviation.resumeTaskId);
+            return Boolean(resumeStatus) && !this.isTerminalTaskStatus(resumeStatus);
+        });
+        if (next.length === current.length)
+            return;
+        await this.saveWorkDeviations(next);
+        await this.refreshResume();
+    }
     /** Stamp description edits independently from generic entity mutations.
      * Legacy entities cannot reveal their historical description-edit time, so
      * their creation time is the earliest truthful fallback. */
@@ -734,8 +831,28 @@ export class PlanStore {
         return join(this.localRoot(), "activity.json");
     }
     localRoot() {
+        // Worktree-local, git-ignored runtime state. The shared-vs-local boundary
+        // and the invariants every harness relies on are documented in
+        // packages/plan-core/docs/runtime-boundaries.md.
         return join(this.root, ".local");
     }
+    deviationsPath() {
+        return join(this.localRoot(), "deviations.json");
+    }
+    /** Runtime work deviations, persisted in worktree-local `.local/deviations.json`
+     *  (never in shared `project.json`). Falls back to `[]` on a missing/corrupt file. */
+    async loadWorkDeviations() {
+        try {
+            return await readJson(this.deviationsPath(), WorkDeviationSchema.array());
+        }
+        catch {
+            return [];
+        }
+    }
+    async saveWorkDeviations(deviations) {
+        await atomicWriteJson(this.deviationsPath(), deviations, this.root);
+        await this.maybeAutoSync();
+    }
     timestampPath() {
         return join(this.localRoot(), "timestamp.json");
     }
@@ -822,6 +939,9 @@ export class PlanStore {
         };
         await atomicWriteJson(this.manifestPath(), manifest, this.root);
         await atomicWriteJson(this.timestampPath(), { updatedAt: manifest.updatedAt }, this.root);
+        // Seed the worktree-local runtime-deviation store (T299). Empty for new
+        // projects; migrateWorkDeviations (loadProject) backfills legacy data.
+        await atomicWriteJson(this.deviationsPath(), [], this.root);
         await this.saveProject({
             name: projectName,
             goal: "",
@@ -860,6 +980,11 @@ export class PlanStore {
             guardBypassUntil: "",
         });
         await this.writeGenerated();
+        // Write the STATIC planner extension rules. Content is fixed (no timestamps,
+        // no dynamic data) so the file is identical across worktrees/branches and
+        // never causes git conflicts. The canonical source is plan-core; this file
+        // is the per-project copy / override point, loaded at planner startup.
+        await writeFile(join(this.root, "rules.json"), JSON.stringify({ extensionRules: PLANNER_EXTENSION_RULES }, null, 2), "utf-8");
         // Write a README stub
         const readme = [
             "# Project Plan",
@@ -884,6 +1009,15 @@ export class PlanStore {
         // - generated/: auto-regenerated markdown views (derived from JSON; churn)
         await writeFile(join(this.root, ".gitignore"), PLANNER_GITIGNORE, "utf-8");
     }
+    /**
+     * Planner extension rules — the agent-behavior contract for every project
+     * using the extension. Loaded from the static .planner/rules.json if present,
+     * otherwise the canonical code set. Static (no timestamps), safe across
+     * worktrees/branches.
+     */
+    async extensionRules() {
+        return loadExtensionRules(this.root);
+    }
     /** Idempotently ensure `.planner/.gitignore` ignores `.local/` (and the
      *  canonical transient/derived patterns). Projects initialized before the
      *  `.local/` move either have no `.planner/.gitignore` or one with stale
@@ -924,7 +1058,19 @@ export class PlanStore {
         return timestamp ? { ...manifest, updatedAt: timestamp.updatedAt } : manifest;
     }
     async loadProject() {
-        return readJson(this.projectPath(), ProjectSchema);
+        const project = await readJson(this.projectPath(), ProjectSchema);
+        // One-time migration (T299): move runtime workDeviations from the shared
+        // project.json into worktree-local .local/deviations.json, then clear them
+        // in project.json so runtime state never churns shared metadata.
+        // Idempotent: a non-empty .local file is never overwritten.
+        if (project.workDeviations.length > 0 && (await this.loadWorkDeviations()).length === 0) {
+            await this.saveWorkDeviations(project.workDeviations);
+            await atomicUpdateJson(this.projectPath(), ProjectSchema, (p) => ({ ...p, workDeviations: [] }), this.root);
+        }
+        // Read-view merge: readers keep using `project.workDeviations`, but the
+        // values now come from worktree-local storage.
+        const deviations = await this.loadWorkDeviations();
+        return { ...project, workDeviations: deviations };
     }
     /**
      * Reserve immutable human identifiers without touching tracked `project.json`.
@@ -1144,12 +1290,13 @@ export class PlanStore {
     async refreshResume(notes, lastSessionSummary) {
         const workspace = await this.loadAll();
         const inProgressPhases = workspace.phases.filter((p) => p.status === "in-progress");
+        const activePhase = workspace.phases.find((phase) => phase.tasks.some((task) => task.status === "in-progress"));
         const inProgressTasks = workspace.phases.flatMap((p) => p.tasks.filter((t) => t.status === "in-progress"));
         const blockedTasks = workspace.phases.flatMap((p) => p.tasks.filter((t) => t.status === "blocked"));
         const existing = await this.loadResume();
         const resume = {
             updatedAt: nowISO(),
-            currentPhaseId: inProgressPhases[0]?.id ?? existing?.currentPhaseId ?? "",
+            currentPhaseId: activePhase?.id ?? (existing?.currentPhaseId || inProgressPhases[0]?.id || ""),
             inProgressTaskIds: inProgressTasks.map((t) => t.id),
             nextSteps: existing?.nextSteps ?? [],
             nextStepsUpdatedAt: existing?.nextStepsUpdatedAt ?? "",
@@ -1362,6 +1509,45 @@ export class PlanStore {
                     catch { /* ignore */ }
                 }
             }
+            const backupsRoot = join(this.root, ".local", "backups");
+            const walkBackups = async (dir) => {
+                let entries = [];
+                try {
+                    entries = await readdir(dir);
+                }
+                catch {
+                    return;
+                }
+                for (const name of entries) {
+                    const full = join(dir, name);
+                    let st;
+                    try {
+                        st = await stat(full);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (st.isDirectory()) {
+                        await walkBackups(full);
+                        continue;
+                    }
+                    if (!name.endsWith(".json.bak"))
+                        continue;
+                    const rel = full.slice(backupsRoot.length).replace(/^\//, "");
+                    const mainPath = join(this.root, rel.slice(0, -".bak".length));
+                    try {
+                        await stat(mainPath);
+                    }
+                    catch {
+                        try {
+                            await unlink(full);
+                            removed += 1;
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            };
+            await walkBackups(backupsRoot);
         }
         catch { /* best-effort */ }
         return { removed };
@@ -1592,18 +1778,13 @@ export class PlanStore {
             return "done";
         const hasDone = meaningful.some((s) => s === "done");
         const hasActive = meaningful.some((s) => s === "in-progress");
-        const hasPaused = meaningful.some((s) => s === "paused");
         const hasPlanned = meaningful.some((s) => s === "planned");
         const hasBlocked = meaningful.some((s) => s === "blocked");
         const hasWaiting = meaningful.some((s) => s === "waiting");
         const hasDeferred = meaningful.some((s) => s === "deferred");
         if (hasActive)
             return "in-progress";
-        // If completed work exists and the ONLY remaining meaningful work is paused
-        // or deferred, do not imply active execution.
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasDeferred && hasPaused)
-            return "paused";
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasPaused && hasDeferred)
+        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
             return "deferred";
         // Partial completion with remaining planned/blocked/waiting work still means
         // the phase has genuinely started and is not terminal yet.
@@ -1616,8 +1797,6 @@ export class PlanStore {
             return "waiting";
         if (hasDeferred)
             return "deferred";
-        if (hasPaused)
-            return "paused";
         return "planned";
     }
     deriveFeatureStatus(featureId, phases) {
@@ -1633,17 +1812,13 @@ export class PlanStore {
             return "done";
         const hasDone = meaningful.some((s) => s === "done");
         const hasActive = meaningful.some((s) => s === "discovery" || s === "in-progress");
-        const hasPaused = meaningful.some((s) => s === "paused");
         const hasPlanned = meaningful.some((s) => s === "planned");
         const hasBlocked = meaningful.some((s) => s === "blocked");
         const hasWaiting = meaningful.some((s) => s === "waiting");
         const hasDeferred = meaningful.some((s) => s === "deferred");
         if (hasActive)
             return "in-progress";
-        // Same rule as phases: done + paused/deferred-only remainder is non-active.
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasDeferred && hasPaused)
-            return "paused";
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasPaused && hasDeferred)
+        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
             return "deferred";
         if (hasDone)
             return "in-progress";
@@ -1654,8 +1829,6 @@ export class PlanStore {
             return "waiting";
         if (hasDeferred)
             return "deferred";
-        if (hasPaused)
-            return "paused";
         return "planned";
     }
     async syncStatuses() {
@@ -1740,24 +1913,23 @@ export class PlanStore {
     }
     /** Persist an explicitly approved work deviation without coupling it to a harness. */
     async addWorkDeviation(deviation) {
-        return this.updateProject((project) => ({
-            ...project,
-            workDeviations: [...project.workDeviations, deviation],
-        }));
+        const deviations = [...(await this.loadWorkDeviations()), deviation];
+        await this.saveWorkDeviations(deviations);
+        return this.loadProject();
     }
     /** Advance a deviation while retaining its complete audit and return stack. */
     async setWorkDeviationState(id, state, timestamp = nowISO()) {
-        return this.updateProject((project) => ({
-            ...project,
-            workDeviations: project.workDeviations.map((deviation) => deviation.id !== id ? deviation : {
-                ...deviation,
-                state,
-                activatedAt: state === "active" ? timestamp : deviation.activatedAt,
-                resumeRequiredAt: state === "resume-required" ? timestamp : deviation.resumeRequiredAt,
-                resolvedAt: state === "resolved" || state === "canceled" ? timestamp : deviation.resolvedAt,
-                resumedAt: state === "resumed" ? timestamp : deviation.resumedAt,
-            }),
-        }));
+        const deviations = await this.loadWorkDeviations();
+        const next = deviations.map((deviation) => deviation.id !== id ? deviation : {
+            ...deviation,
+            state,
+            activatedAt: state === "active" ? timestamp : deviation.activatedAt,
+            resumeRequiredAt: state === "resume-required" ? timestamp : deviation.resumeRequiredAt,
+            resolvedAt: state === "resolved" || state === "canceled" ? timestamp : deviation.resolvedAt,
+            resumedAt: state === "resumed" ? timestamp : deviation.resumedAt,
+        });
+        await this.saveWorkDeviations(next);
+        return this.loadProject();
     }
     async updateFeatures(updater) {
         const updated = await this.withFeaturesLock(async () => {
@@ -1783,8 +1955,94 @@ export class PlanStore {
         await this.maybeAutoSync();
         return updated;
     }
+    /**
+     * Persist completion of one full task → phase → feature → requirements read
+     * sequence. Session metadata is deliberately the only changed entity field:
+     * semantic updatedAt/descriptionUpdatedAt values are preserved exactly.
+     */
+    async recordContextRead(input) {
+        const sessionId = input.sessionId.trim();
+        if (!sessionId)
+            throw new PlanStoreError("Context-read attestation requires a non-empty sessionId.");
+        const createdAt = TimestampSchema.parse(input.createdAt ?? nowISO());
+        const requirementIds = [...new Set((input.requirementIds ?? []).map((id) => id.trim()).filter(Boolean))];
+        return this.runAsBatch(async () => {
+            const originalPhase = await this.loadPhase(input.phaseId);
+            const taskIndex = originalPhase.tasks.findIndex((task) => task.id === input.taskId);
+            if (taskIndex < 0)
+                throw new PlanStoreError(`Task ${input.taskId} does not belong to phase ${input.phaseId}.`);
+            const originalFeatures = await this.loadFeatures();
+            const featureId = input.featureId?.trim() || originalPhase.featureId;
+            const featureIndex = featureId
+                ? originalFeatures.features.findIndex((feature) => feature.id === featureId)
+                : -1;
+            if (featureId && featureIndex < 0)
+                throw new PlanStoreError(`Feature ${featureId} was not found for context-read attestation.`);
+            const originalRequirements = await this.loadRequirements();
+            const missingRequirement = requirementIds.find((id) => !originalRequirements.requirements.some((requirement) => requirement.id === id));
+            if (missingRequirement)
+                throw new PlanStoreError(`Requirement ${missingRequirement} was not found for context-read attestation.`);
+            const nextPhase = structuredClone(originalPhase);
+            const nextTask = upsertSessionInfo(nextPhase.tasks[taskIndex], sessionId, createdAt);
+            nextPhase.tasks[taskIndex] = nextTask.entity;
+            const nextPhaseInfo = upsertSessionInfo(nextPhase, sessionId, createdAt);
+            const phaseChanged = nextTask.changed || nextPhaseInfo.changed;
+            let nextFeature;
+            let featureChanged = false;
+            if (featureIndex >= 0) {
+                const featureResult = upsertSessionInfo(structuredClone(originalFeatures.features[featureIndex]), sessionId, createdAt);
+                nextFeature = featureResult.entity;
+                featureChanged = featureResult.changed;
+            }
+            const nextRequirements = structuredClone(originalRequirements);
+            let requirementsChanged = false;
+            for (const requirement of nextRequirements.requirements) {
+                if (!requirementIds.includes(requirement.id))
+                    continue;
+                const result = upsertSessionInfo(requirement, sessionId, createdAt);
+                if (result.changed) {
+                    Object.assign(requirement, result.entity);
+                    requirementsChanged = true;
+                }
+            }
+            if (!phaseChanged && !featureChanged && !requirementsChanged) {
+                return {
+                    phase: originalPhase,
+                    ...(featureIndex >= 0 ? { feature: originalFeatures.features[featureIndex] } : {}),
+                    requirements: originalRequirements.requirements.filter((requirement) => requirementIds.includes(requirement.id)),
+                    createdAt,
+                };
+            }
+            try {
+                if (featureChanged && nextFeature)
+                    await this.saveFeature(nextFeature);
+                if (phaseChanged)
+                    await this.savePhase(nextPhaseInfo.entity);
+                if (requirementsChanged)
+                    await this.saveRequirements(nextRequirements);
+            }
+            catch (error) {
+                const rollbackErrors = [];
+                if (featureChanged && nextFeature)
+                    await this.saveFeature(originalFeatures.features[featureIndex]).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                if (phaseChanged)
+                    await this.savePhase(originalPhase).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                if (requirementsChanged)
+                    await this.saveRequirements(originalRequirements).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                if (rollbackErrors.length > 0)
+                    throw new AggregateError([error, ...rollbackErrors], "Context-read attestation failed and rollback was incomplete.");
+                throw error;
+            }
+            const phase = await this.loadPhase(input.phaseId);
+            const feature = featureIndex >= 0 ? (await this.loadFeatures()).features.find((candidate) => candidate.id === featureId) : undefined;
+            const requirements = (await this.loadRequirements()).requirements.filter((requirement) => requirementIds.includes(requirement.id));
+            return { phase, ...(feature ? { feature } : {}), requirements, createdAt };
+        });
+    }
     async saveProject(project) {
-        const parsed = ProjectSchema.parse(project);
+        // Runtime workDeviations live in .local/deviations.json (T299); never
+        // persist them here so shared project.json stays stable across worktrees.
+        const parsed = ProjectSchema.parse({ ...project, workDeviations: [] });
         await atomicWriteJson(this.projectPath(), parsed, this.root);
         await this.touchTimestamp();
         await this.maybeAutoSync();
@@ -1896,11 +2154,12 @@ export class PlanStore {
                 ? { ...timestamped, featureId: resolvedFeatureId }
                 : timestamped;
             return this.normalizePhaseDocument(normalizedInput).phase;
-        });
+        }, this.root);
+        await this.pruneObsoleteWorkDeviations();
         await this.maybeAutoSync();
         return { ...raw, status: this.derivePhaseStatus(raw.tasks) };
     }
-    /** Pause active work with a mandatory durable checkpoint. */
+    /** Save a durable resume checkpoint without introducing a separate canonical task status. */
     async pauseTask(phaseId, taskId, input) {
         const snapshot = TaskPauseSnapshotSchema.parse(input);
         let paused;
@@ -1909,7 +2168,7 @@ export class PlanStore {
             if (!task)
                 throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`);
             if (task.status !== "in-progress") {
-                throw new PlanStoreError(`Task ${taskId} cannot be paused from ${task.status}; only in-progress work can be paused.`);
+                throw new PlanStoreError(`Task ${taskId} cannot be checkpointed from ${task.status}; only in-progress work can capture a pause snapshot.`);
             }
             const description = [
                 `Reason: ${snapshot.reason}`,
@@ -1919,15 +2178,15 @@ export class PlanStore {
             ].join("\n");
             paused = {
                 ...task,
-                status: "paused",
+                status: "planned",
                 pauseSnapshot: snapshot,
                 pauseHistory: [...task.pauseHistory, snapshot],
                 statusLog: [...task.statusLog, {
                         id: createStatusLogEntryId(),
                         date: snapshot.pausedAt,
                         fromStatus: "in-progress",
-                        toStatus: "paused",
-                        title: "in-progress → paused",
+                        toStatus: "planned",
+                        title: "in-progress → planned (checkpoint saved)",
                         description,
                     }],
                 updatedAt: snapshot.pausedAt,
@@ -1937,15 +2196,18 @@ export class PlanStore {
         });
         return paused;
     }
-    /** Resume a paused task without resetting its original startedAt. */
+    /** Resume a checkpointed task without resetting its original startedAt. */
     async resumeTask(phaseId, taskId, timestamp = nowISO()) {
         let resumed;
         await this.updatePhase(phaseId, (phase) => {
             const task = phase.tasks.find((candidate) => candidate.id === taskId);
             if (!task)
                 throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`);
-            if (task.status !== "paused") {
-                throw new PlanStoreError(`Task ${taskId} cannot be resumed from ${task.status}; only paused work can be resumed.`);
+            if (!task.pauseSnapshot) {
+                throw new PlanStoreError(`Task ${taskId} has no saved checkpoint to resume.`);
+            }
+            if (task.status === "done" || task.status === "canceled" || task.status === "rejected") {
+                throw new PlanStoreError(`Task ${taskId} cannot be resumed from ${task.status}.`);
             }
             const snapshot = task.pauseSnapshot;
             resumed = {
@@ -1956,12 +2218,10 @@ export class PlanStore {
                 statusLog: [...task.statusLog, {
                         id: createStatusLogEntryId(),
                         date: timestamp,
-                        fromStatus: "paused",
+                        fromStatus: task.status,
                         toStatus: "in-progress",
-                        title: "paused → in-progress",
-                        description: snapshot
-                            ? `Resumed from ${snapshot.resumeLocation}. ${snapshot.howToResume}`
-                            : "Paused task resumed.",
+                        title: `${task.status} → in-progress (resume checkpoint)`,
+                        description: `Resumed from ${snapshot.resumeLocation}. ${snapshot.howToResume}`,
                     }],
                 updatedAt: timestamp,
             };
@@ -1975,6 +2235,51 @@ export class PlanStore {
     async getPhaseHandoff(phaseId) {
         return (await this.loadPhase(phaseId)).handoff;
     }
+    /** Audit one exact phase before preparing a handoff refresh. */
+    async preparePhaseHandoff(phaseId) {
+        const phase = await this.loadPhase(phaseId);
+        if (!phase.featureId)
+            throw new PlanStoreError(`Phase ${phaseId} has no parent feature; durable handoff context cannot be synchronized.`);
+        const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === phase.featureId);
+        if (!feature)
+            throw new PlanStoreError(`Parent feature ${phase.featureId} not found for phase ${phaseId}.`);
+        return auditPhaseHandoff(phase, feature);
+    }
+    /** Refresh the single active handoff and synchronize durable task/phase/feature
+     * context. Unlike setPhaseHandoff(), this deliberately does not archive the
+     * previous active body: callers must reconcile it using the optimistic
+     * handoffUpdatedAt token returned by preparePhaseHandoff(). */
+    async refreshPhaseHandoff(phaseId, input) {
+        return this.runAsBatch(async () => {
+            const originalPhase = await this.loadPhase(phaseId);
+            if (!originalPhase.featureId)
+                throw new PlanStoreError(`Phase ${phaseId} has no parent feature; durable handoff context cannot be synchronized.`);
+            const originalFeatures = await this.loadFeatures();
+            const featureIndex = originalFeatures.features.findIndex((candidate) => candidate.id === originalPhase.featureId);
+            if (featureIndex < 0)
+                throw new PlanStoreError(`Parent feature ${originalPhase.featureId} not found for phase ${phaseId}.`);
+            const timestamp = nowISO();
+            const applied = applyHandoffContextSync(originalPhase, originalFeatures.features[featureIndex], input, timestamp);
+            const nextFeatures = structuredClone(originalFeatures);
+            nextFeatures.features[featureIndex] = applied.feature;
+            try {
+                await this.saveFeatures(nextFeatures);
+                await this.savePhase(applied.phase);
+            }
+            catch (error) {
+                const rollbackErrors = [];
+                await this.saveFeatures(originalFeatures).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                await this.savePhase(originalPhase).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                if (rollbackErrors.length > 0) {
+                    throw new AggregateError([error, ...rollbackErrors], "Handoff refresh failed and rollback was incomplete.");
+                }
+                throw error;
+            }
+            const phase = await this.loadPhase(phaseId);
+            const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
+            return { phase, feature, updatedTaskIds: applied.updatedTaskIds, handoffUpdatedAt: phase.handoffUpdatedAt };
+        });
+    }
     /** Set the handoff text for a phase + stamp handoffUpdatedAt. A completed or
      * canceled phase cannot receive a new operational handoff. Replacing an
      * existing handoff archives the previous content as `superseded` first. */
@@ -2186,16 +2491,16 @@ export class PlanStore {
         await this.unlinkPhaseFiles(phaseId);
         await this.touchTimestamp();
     }
-    /** Remove a phase file AND its inline .bak backup. atomicUpdateJson (used by
-     *  updatePhase without root) writes the backup inline at phases/<id>.json.bak,
-     *  and readJson falls back to `${path}.bak` on a missing main file — so a
-     *  delete that leaves the .bak behind would RESURRECT the deleted phase on
-     *  the next read. Feature backups (written with root) live under
-     *  .local/backups/ and are never read by readJson, so only the inline .bak
-     *  needs removing here. */
+    /** Remove a phase file and BOTH of its previous-version backups: the legacy
+     *  inline `phases/<id>.json.bak` (kept for backward compat) and the relocated
+     *  `.local/backups/phases/<id>.json.bak` (written once updatePhase passes root,
+     *  per P043). Leaving either behind would RESURRECT the deleted phase on the
+     *  next read, since readJson falls back to both locations. */
     async unlinkPhaseFiles(phaseId) {
-        await unlink(this.phasePath(phaseId)).catch(() => { });
-        await unlink(`${this.phasePath(phaseId)}.bak`).catch(() => { });
+        const phaseFile = this.phasePath(phaseId);
+        await unlink(phaseFile).catch(() => { });
+        await unlink(`${phaseFile}.bak`).catch(() => { });
+        await unlink(join(this.root, ".local", "backups", "phases", `${phaseId}.json.bak`)).catch(() => { });
     }
     // ── Workspace-level operations ─────────────────────────────────────
     /** Load the full workspace (manifest + phases + project + requirements + features) */