@agent-plan/core 0.2.29 → 0.3.0

package/dist/plan-store.js

@@ -21,13 +21,32 @@ import { buildHierarchicalDescriptionFreshness } from "./description-freshness.j
 import { loadExtensionRules, PLANNER_EXTENSION_RULES } from "./planner-rules.js";
 import { loadProjectGrillMeSkill, syncProjectGrillMeSkill, syncProjectPlannerSkill } from "./planner-skill.js";
 import { applyLegacyProjectContextMigration, plannerSessionPreparationResult, previewLegacyProjectContextMigration, } from "./project-context-migration.js";
-import { applyHandoffContextSync, auditPhaseHandoff, externalizeOversizedHandoffContent, handoffContentHash, materializeHandoffMetadata, HandoffContractError, TARGET_HANDOFF_CONTENT_CHARS, validateHandoffReadBackVerification, } from "./handoff-context.js";
+import { PROJECT_CONTEXT_DELIVERY_VERSION, createCompleteProjectContextDelivery, createProjectContextSnapshot, projectContextFingerprint, projectContextReadState, verifyProjectContextChunks, ProjectContextDeliveryError, ProjectContextReadStateDocumentSchema, } from "./project-context.js";
+import { applyHandoffContextSync, auditPhaseHandoff, externalizeOversizedHandoffContent, extractHandoffSectionHeadings, handoffContentHash, isAutoExternalizedHandoffDocument, materializeHandoffMetadata, HandoffContractError, retainedHandoffContentNotFoundError, supportingDocumentInvalidError, TARGET_HANDOFF_CONTENT_CHARS, validateHandoffReadBackVerification, } from "./handoff-context.js";
 import { withPlanRootWriteLock } from "./write-coordination.js";
 import { ALLOCATION_REGISTRY_VERSION, PLAN_SCHEMA_VERSION, SUPPORTED_ALLOCATION_KINDS, isSupportedAllocationKind, unsupportedAllocationKindDetails, } from "./runtime-diagnostics.js";
-function nowISO() {
+/** Current timestamp in ISO-8601. The one place that decides "now" for every
+ *  planner write — adapters import this instead of each calling
+ *  `new Date().toISOString()` themselves, so a future need to freeze or mock
+ *  time has one call site to change. */
+export function nowISO() {
     return new Date().toISOString();
 }
 const MAX_SESSION_INFO_ENTRIES = 16;
+const RetainedHandoffDraftSchema = z.object({
+    phaseId: z.string(),
+    token: z.string(),
+    content: z.string(),
+    failureReason: z.string(),
+    retainedAt: z.string(),
+});
+// Bounds for retained handoff drafts, so a run of failed writes cannot grow
+// .local/ without limit: at most this many distinct phase+token entries
+// (oldest evicted first), each expiring after this age, with a defensive
+// per-entry size ceiling far above MAX_HANDOFF_CONTENT_CHARS.
+const MAX_RETAINED_HANDOFF_DRAFTS = 20;
+const RETAINED_HANDOFF_DRAFT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const MAX_RETAINED_HANDOFF_DRAFT_CONTENT_CHARS = 200_000;
 function normalizeAcceptedDecisionCreate(input, acceptedAt) {
     const title = input.title.trim();
     if (!title) {
@@ -114,6 +133,17 @@ function mergeSessionInfo(current, incoming) {
         .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
         .slice(0, MAX_SESSION_INFO_ENTRIES);
 }
+function mergeProjectContextSessionInfo(current, incoming) {
+    const newestBySession = new Map();
+    for (const entry of [...(current ?? []), ...(incoming ?? [])]) {
+        const prior = newestBySession.get(entry.sessionId);
+        if (!prior || entry.createdAt > prior.createdAt)
+            newestBySession.set(entry.sessionId, entry);
+    }
+    return [...newestBySession.values()]
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
+        .slice(0, MAX_SESSION_INFO_ENTRIES);
+}
 function assertSnapshotNotOlder(entity, entityId, incomingUpdatedAt, currentUpdatedAt) {
     if (incomingUpdatedAt < currentUpdatedAt) {
         throw new PlanStaleWriteError({
@@ -687,8 +717,6 @@ async function readJson(path, schema) {
 }
 export class PlanStore {
     root;
-    autoSync = false;
-    syncGuard = false;
     // While true, maybeAutoSync() is a no-op. Used by batch operations
     // (migrateToUuids, ensureStructureOrdering, syncStatuses, repair) so that
     // their internal savePhase/saveFeatures calls do NOT re-trigger a full
@@ -702,7 +730,7 @@ export class PlanStore {
     /** When enabled, status rollup (syncStatuses) runs automatically after every
      *  phase/feature/project save. Used by the pi-adapter so the agent's tool
      *  mutations keep phase/feature statuses derived from task statuses. */
-    enableAutoSync(value) { this.autoSync = value; }
+    enableAutoSync(_value) { }
     /** Run a batch operation with autoSync suspended. Internal saves inside the
      *  batch will NOT re-trigger syncStatuses (which would be O(N^2) on large
      *  planners). The caller is responsible for triggering any needed final
@@ -1028,6 +1056,9 @@ export class PlanStore {
     activityPath() {
         return join(this.localRoot(), "activity.json");
     }
+    projectContextReadsPath() {
+        return join(this.localRoot(), "project-context-reads.json");
+    }
     localRoot() {
         // Worktree-local, git-ignored runtime state. The shared-vs-local boundary
         // and the invariants every harness relies on are documented in
@@ -1063,6 +1094,9 @@ export class PlanStore {
     handoffArchiveDir() {
         return join(this.localRoot(), "handoff-archive");
     }
+    handoffDraftsPath() {
+        return join(this.localRoot(), "handoff-drafts.json");
+    }
     /** One-time migration for plans created before .planner/.local/ existed.
      *  Moves a legacy root-level file into .local/ if the legacy file exists and
      *  the .local/ counterpart does not. Safe to call on every load. */
@@ -1677,7 +1711,6 @@ export class PlanStore {
     /** Migrate legacy non-feature-scoped phase ids to feature-scoped ids and repair
      *  dangling feature.phaseIds references. Idempotent. */
     async migratePhaseIds() {
-        const { readdir, unlink } = await import("node:fs/promises");
         const phases = await this.loadAllPhases();
         const features = await this.loadFeatures();
         // Infer missing featureId from feature.phaseIds references (legacy back-link).
@@ -2122,6 +2155,13 @@ export class PlanStore {
         const phase = await this.loadPhase(phaseId);
         let cleared = null;
         const terminalReason = this.terminalHandoffReason(phase);
+        if (terminalReason) {
+            // A terminal phase can never receive another handoff write, so any
+            // draft retained against a stale/failed prepare token for it is dead
+            // weight — discard it here regardless of whether there was an active
+            // handoff body to archive below.
+            await this.discardRetainedHandoffDrafts(phaseId);
+        }
         if (terminalReason && phase.handoff !== "") {
             await this.clearPhaseHandoff(phaseId, terminalReason);
             const features = await this.loadFeatures();
@@ -2531,6 +2571,118 @@ export class PlanStore {
             return { phase, ...(feature ? { feature } : {}), requirements, createdAt };
         });
     }
+    async loadProjectContextReadStateDocument() {
+        try {
+            await access(this.projectContextReadsPath());
+        }
+        catch {
+            return ProjectContextReadStateDocumentSchema.parse({});
+        }
+        return readJson(this.projectContextReadsPath(), ProjectContextReadStateDocumentSchema);
+    }
+    /**
+     * Read project.json and requirements.json as one coherent pair with no
+     * lock. A concurrent writer could otherwise interleave the two reads into
+     * a torn pair (half old, half new); instead of blocking behind the plan
+     * root write lock like a mutation, read twice and compare fingerprints,
+     * retrying until two consecutive reads agree (bounded, so a pathological
+     * writer cannot spin this forever).
+     */
+    async readCoherentProjectAndRequirements() {
+        const maxAttempts = 5;
+        const readOnce = async () => {
+            const [project, requirements] = await Promise.all([
+                readJson(this.projectPath(), ProjectSchema),
+                readJson(this.requirementsPath(), RequirementsDocumentSchema),
+            ]);
+            return { project, requirements };
+        };
+        let current = await readOnce();
+        for (let attempt = 1; attempt < maxAttempts; attempt++) {
+            const currentFingerprint = projectContextFingerprint(createProjectContextSnapshot(current.project, current.requirements));
+            const next = await readOnce();
+            const nextFingerprint = projectContextFingerprint(createProjectContextSnapshot(next.project, next.requirements));
+            if (nextFingerprint === currentFingerprint)
+                return next;
+            current = next;
+        }
+        return current;
+    }
+    async loadProjectContextDelivery(maxChars) {
+        const { project, requirements } = await this.readCoherentProjectAndRequirements();
+        return createCompleteProjectContextDelivery(project, requirements, maxChars);
+    }
+    async projectContextReadStateForSession(sessionId) {
+        const { project, requirements } = await this.readCoherentProjectAndRequirements();
+        const readState = await this.loadProjectContextReadStateDocument();
+        return projectContextReadState(createProjectContextSnapshot(project, requirements), readState.sessionInfo, sessionId);
+    }
+    /**
+     * Persist a worktree-local project-context read only after receiving the exact
+     * complete chunk sequence for the current project and Requirements revisions.
+     */
+    /**
+     * Governance decision (P102(F005) accepted decision): a project-context
+     * read stamps sessionInfo on every requirement, the same way it stamps
+     * every project Accepted Decision's parent (project.json) and Project
+     * Guidelines — because the delivery this attests to is lossless and always
+     * contains every requirement in full. This intentionally lets a
+     * project-context read satisfy phase-scoped REQUIREMENTS_READ_REQUIRED
+     * gates: the agent has genuinely seen the requirement, whichever surface
+     * delivered it. `recordContextRead` stamps only the requirement ids it was
+     * given because that call is scoped to one task's linked requirements, not
+     * a full-project delivery.
+     */
+    async recordProjectContextRead(input) {
+        const sessionId = input.sessionId.trim();
+        if (!sessionId)
+            throw new PlanStoreError("Project-context attestation requires a non-empty sessionId.");
+        const delivery = verifyProjectContextChunks(input.chunks);
+        const createdAt = TimestampSchema.parse(input.createdAt ?? nowISO());
+        const result = await this.runAsBatch(async () => {
+            const project = await readJson(this.projectPath(), ProjectSchema);
+            const requirements = await readJson(this.requirementsPath(), RequirementsDocumentSchema);
+            const currentSnapshot = createProjectContextSnapshot(project, requirements);
+            const currentFingerprint = projectContextFingerprint(currentSnapshot);
+            if (delivery.evidence.fingerprint !== currentFingerprint) {
+                throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_STALE", "Project context changed after delivery; reload every project-context chunk before attesting the read.");
+            }
+            let nextProject = project;
+            if (project.projectGuidelines.content.trim()) {
+                nextProject = {
+                    ...project,
+                    projectGuidelines: upsertSessionInfo(project.projectGuidelines, sessionId, createdAt).entity,
+                };
+            }
+            // saveProject bumps touchTimestamp(), strips workDeviations, and merges
+            // projectGuidelines.sessionInfo against the on-disk copy the same way
+            // every other project write does.
+            if (nextProject !== project)
+                await this.saveProject(nextProject);
+            let requirementsChanged = false;
+            const nextRequirements = {
+                requirements: requirements.requirements.map((requirement) => {
+                    const updated = upsertSessionInfo(requirement, sessionId, createdAt);
+                    requirementsChanged ||= updated.changed;
+                    return updated.entity;
+                }),
+            };
+            // saveRequirements applies the stale-write guard and merges sessionInfo
+            // per requirement against the on-disk copy, same as recordContextRead.
+            if (requirementsChanged)
+                await this.saveRequirements(nextRequirements);
+            // The complete-read attestation is the commit marker and is written
+            // last, after both save calls above have durably landed.
+            const previousReadState = await this.loadProjectContextReadStateDocument();
+            const nextReadState = ProjectContextReadStateDocumentSchema.parse({
+                version: PROJECT_CONTEXT_DELIVERY_VERSION,
+                sessionInfo: mergeProjectContextSessionInfo(previousReadState.sessionInfo, [{ sessionId, createdAt, fingerprint: currentFingerprint }]),
+            });
+            await atomicWriteJson(this.projectContextReadsPath(), nextReadState, this.root);
+            return { project: nextProject, requirements: nextRequirements };
+        });
+        return { ...result, delivery, createdAt };
+    }
     async recordProjectGuidelinesRead(input) {
         const sessionId = input.sessionId.trim();
         if (!sessionId)
@@ -2742,7 +2894,7 @@ export class PlanStore {
     /** Field-scoped task mutation against the lock-reloaded canonical phase. */
     async updateTask(phaseId, taskId, updater, options = {}) {
         let persisted;
-        const phase = await this.updatePhase(phaseId, (currentPhase) => {
+        await this.updatePhase(phaseId, (currentPhase) => {
             const index = currentPhase.tasks.findIndex((task) => task.id === taskId);
             if (index < 0)
                 throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`);
@@ -3042,31 +3194,111 @@ export class PlanStore {
     async getPhaseHandoff(phaseId) {
         return (await this.loadPhase(phaseId)).handoff;
     }
-    async validateHandoffSupportingDocuments(documents) {
+    async loadRetainedHandoffDrafts() {
+        try {
+            return await readJson(this.handoffDraftsPath(), RetainedHandoffDraftSchema.array());
+        }
+        catch {
+            return [];
+        }
+    }
+    async saveRetainedHandoffDrafts(drafts) {
+        await atomicWriteJson(this.handoffDraftsPath(), drafts, this.root);
+    }
+    isRetainedHandoffDraftFresh(draft) {
+        const retainedAtMs = Date.parse(draft.retainedAt);
+        return Number.isFinite(retainedAtMs) && Date.now() - retainedAtMs < RETAINED_HANDOFF_DRAFT_MAX_AGE_MS;
+    }
+    /** Persist the exact body submitted to refreshPhaseHandoff() against its
+     * phase + prepare token, so a retry can omit `content` and reuse it
+     * instead of resending a capsule up to MAX_HANDOFF_CONTENT_CHARS. Called
+     * from refreshPhaseHandoff() on any write failure except a terminal phase
+     * (nothing to retry there — see discardRetainedHandoffDrafts).
+     *
+     * Worktree-local only: .local/handoff-drafts.json, per the shared-vs-local
+     * boundary (P069(F005)/T298, see localRoot()). A retained body must never
+     * reach shared .planner/ state. It is a plain file, so it survives a
+     * process restart in the same worktree — the failure and the retry can be
+     * separated by a context compaction.
+     *
+     * Bounded so a run of failed writes cannot grow .local/ without limit:
+     * one entry per phase+token (a new failure for the same token replaces
+     * it), entries older than RETAINED_HANDOFF_DRAFT_MAX_AGE_MS are dropped,
+     * and the total is capped at MAX_RETAINED_HANDOFF_DRAFTS (oldest evicted
+     * first). A defensive per-entry size ceiling skips retention entirely for
+     * runaway input rather than writing it to disk. */
+    async retainHandoffDraft(phaseId, token, content, failureReason) {
+        if (content.length > MAX_RETAINED_HANDOFF_DRAFT_CONTENT_CHARS)
+            return;
+        const drafts = (await this.loadRetainedHandoffDrafts())
+            .filter((draft) => this.isRetainedHandoffDraftFresh(draft))
+            .filter((draft) => !(draft.phaseId === phaseId && draft.token === token));
+        drafts.push({ phaseId, token, content, failureReason, retainedAt: nowISO() });
+        drafts.sort((a, b) => Date.parse(a.retainedAt) - Date.parse(b.retainedAt));
+        while (drafts.length > MAX_RETAINED_HANDOFF_DRAFTS)
+            drafts.shift();
+        await this.saveRetainedHandoffDrafts(drafts);
+    }
+    /** Look up the retained draft for one phase + expectedHandoffUpdatedAt
+     * token. An expired entry is treated as absent (and pruned on the next
+     * retainHandoffDraft/discardRetainedHandoffDrafts write). */
+    async getRetainedHandoffDraft(phaseId, token) {
+        const draft = (await this.loadRetainedHandoffDrafts())
+            .find((candidate) => candidate.phaseId === phaseId && candidate.token === token);
+        if (!draft || !this.isRetainedHandoffDraftFresh(draft))
+            return null;
+        return draft;
+    }
+    /** Discard retained draft(s) for a phase. Pass `token` to discard exactly
+     * the entry a successful write consumed; omit it to discard every draft
+     * retained for the phase, regardless of token — used on handoff_clear and
+     * when the phase reaches a terminal status (a terminal phase can never
+     * receive another handoff write, so nothing retained for it is ever
+     * useful again). */
+    async discardRetainedHandoffDrafts(phaseId, token) {
+        const drafts = await this.loadRetainedHandoffDrafts();
+        const next = drafts.filter((draft) => draft.phaseId !== phaseId || (token !== undefined && draft.token !== token));
+        if (next.length !== drafts.length)
+            await this.saveRetainedHandoffDrafts(next);
+    }
+    /** Resolve a `.planner/docs/*.md` path to an absolute on-disk target,
+     * enforcing the same format-and-containment rule everywhere a supporting
+     * document path is trusted: it must look like a Markdown path under
+     * `.planner/docs/` with no `..` segment, and must resolve inside the
+     * docs directory. Shared by validateHandoffSupportingDocuments (strict:
+     * throws on any defect) and readExternalizedHandoffDocument (lenient:
+     * treats any defect, including one it did not have to make itself, as
+     * "unavailable" — a persisted path is never re-trusted blindly). */
+    resolveDocsTarget(rawPath) {
+        const normalizedPath = rawPath.trim().replace(/\\/g, "/");
+        if (!/^\.planner\/docs\/.+\.md$/i.test(normalizedPath) || normalizedPath.includes("/../")) {
+            throw supportingDocumentInvalidError(`Supporting document path must be a Markdown file under .planner/docs/: ${rawPath}`, { path: rawPath });
+        }
         const docsRoot = resolve(this.root, "docs");
+        const target = resolve(this.root, normalizedPath.slice(".planner/".length));
+        if (!target.startsWith(`${docsRoot}${sep}`)) {
+            throw supportingDocumentInvalidError(`Supporting document escapes .planner/docs/: ${normalizedPath}`, { path: normalizedPath });
+        }
+        return target;
+    }
+    async validateHandoffSupportingDocuments(documents) {
         const metadata = [];
         const contents = [];
         const seen = new Set();
         for (const document of documents) {
             const normalizedPath = document.path.trim().replace(/\\/g, "/");
-            if (!/^\.planner\/docs\/.+\.md$/i.test(normalizedPath) || normalizedPath.includes("/../")) {
-                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document path must be a Markdown file under .planner/docs/: ${document.path}`, { path: document.path });
-            }
             if (seen.has(normalizedPath)) {
-                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document appears more than once: ${normalizedPath}`, { path: normalizedPath });
+                throw supportingDocumentInvalidError(`Supporting document appears more than once: ${normalizedPath}`, { path: normalizedPath });
             }
             seen.add(normalizedPath);
-            const target = resolve(this.root, normalizedPath.slice(".planner/".length));
-            if (!target.startsWith(`${docsRoot}${sep}`)) {
-                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document escapes .planner/docs/: ${normalizedPath}`, { path: normalizedPath });
-            }
+            const target = this.resolveDocsTarget(document.path);
             const fileStat = await lstat(target).catch(() => null);
             if (!fileStat || fileStat.isSymbolicLink() || !fileStat.isFile()) {
-                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document must be a regular file under .planner/docs/ (symlinks rejected): ${normalizedPath}`, { path: normalizedPath });
+                throw supportingDocumentInvalidError(`Supporting document must be a regular file under .planner/docs/ (symlinks rejected): ${normalizedPath}`, { path: normalizedPath });
             }
             const content = await readFile(target, "utf8").catch(() => null);
             if (content === null || !content.trim()) {
-                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document is missing or empty: ${normalizedPath}`, { path: normalizedPath });
+                throw supportingDocumentInvalidError(`Supporting document is missing or empty: ${normalizedPath}`, { path: normalizedPath });
             }
             metadata.push({
                 path: normalizedPath,
@@ -3078,98 +3310,228 @@ export class PlanStore {
         }
         return { metadata, contents };
     }
-    /** Audit one exact phase before preparing a handoff refresh. */
-    async preparePhaseHandoff(phaseId) {
+    /** Read back one document a previous handoff refresh auto-externalized,
+     * for handoff_prepare to surface (see PhaseHandoffAudit.externalizedHandoffDocuments).
+     * Unlike validateHandoffSupportingDocuments this never throws: a stale
+     * path, a deleted file, a symlink, or any other defect is reported to the
+     * caller as "missing" rather than failing the whole prepare call — the
+     * document being gone is itself one of the edge cases this exists to
+     * surface, not a reason to hide that it was ever there. */
+    async readExternalizedHandoffDocument(rawPath) {
+        try {
+            const target = this.resolveDocsTarget(rawPath);
+            const fileStat = await lstat(target).catch(() => null);
+            if (!fileStat || fileStat.isSymbolicLink() || !fileStat.isFile())
+                return null;
+            const content = await readFile(target, "utf8").catch(() => null);
+            return content && content.trim() ? content : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The full prior capsule's `##` headings for validateHandoffSectionReconciliation
+     * (P104(F005)/T416): the live phase's own compact-capsule headings, plus —
+     * when there is a live handoff to reconcile against — the headings of
+     * every document its own auto-externalization moved out, read back fresh
+     * here (never the elided copy, matching PhaseHandoffAudit.priorSectionHeadings
+     * as preparePhaseHandoff derives it). Empty when phase.handoff is "": a
+     * first handoff has nothing prior, and a handoff already archived by
+     * handoff_clear has nothing live left to reconcile even though stale
+     * handoffAudit.supportingDocuments may still name an old externalized
+     * file — this is what makes an archived-then-superseded write behave like
+     * a first write instead of demanding dispositions for content that is
+     * already gone. */
+    async priorHandoffSectionHeadings(phase) {
+        if (!phase.handoff.trim())
+            return [];
+        const headings = extractHandoffSectionHeadings(phase.handoff);
+        const autoExternalizedDocuments = (phase.handoffAudit?.supportingDocuments ?? []).filter(isAutoExternalizedHandoffDocument);
+        for (const document of autoExternalizedDocuments) {
+            const content = await this.readExternalizedHandoffDocument(document.path);
+            if (content)
+                headings.push(...extractHandoffSectionHeadings(content));
+        }
+        return [...new Set(headings)];
+    }
+    /** Audit one exact phase before preparing a handoff refresh. When a
+     * supporting-document manifest is already known (it is optional — most
+     * handoffs need none), validate it here so every defect that does not
+     * depend on the drafted body (bad path, missing file, symlink, duplicate,
+     * empty file) fails before a token is issued and before any content is
+     * drafted or transmitted. The same validation runs again at write time
+     * (refreshPhaseHandoff), which stays the authority: it also catches a
+     * document that was valid here but got deleted before the write, and the
+     * one check that genuinely needs the drafted body (the content must link
+     * each document's path). */
+    async preparePhaseHandoff(phaseId, supportingDocuments) {
         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);
+        if (supportingDocuments && supportingDocuments.length > 0) {
+            await this.validateHandoffSupportingDocuments(supportingDocuments);
+        }
+        const audit = auditPhaseHandoff(phase, feature);
+        // The active handoff's own auto-externalized documents are the elided
+        // content this task exists to surface (see HANDOFF_AUTO_EXTERNALIZED_DOCUMENT_DESCRIPTION).
+        // A document the agent linked deliberately has a different description
+        // and is already named in the persisted capsule's own text; only the
+        // tooling's own silent moves are read back here. Skipped entirely (no
+        // I/O) when there is no prior handoff or nothing was ever externalized
+        // from it — the common case.
+        const autoExternalizedDocuments = (phase.handoffAudit?.supportingDocuments ?? [])
+            .filter(isAutoExternalizedHandoffDocument);
+        if (autoExternalizedDocuments.length === 0)
+            return audit;
+        const externalizedHandoffDocuments = await Promise.all(autoExternalizedDocuments.map(async (document) => {
+            const content = await this.readExternalizedHandoffDocument(document.path);
+            return {
+                path: document.path,
+                description: document.description,
+                headings: content ? extractHandoffSectionHeadings(content) : [],
+                content,
+                contentLength: content?.length ?? document.contentLength,
+                missing: content === null,
+            };
+        }));
+        // A handoff already archived (handoff_clear) has phase.handoff === "" but
+        // may still carry stale handoffAudit.supportingDocuments referencing its
+        // old externalized file(s) — nothing left to reconcile against once
+        // archived, so priorSectionHeadings stays whatever auditPhaseHandoff
+        // already derived from the (empty) compact capsule: [].
+        const priorSectionHeadings = phase.handoff.trim()
+            ? [...new Set([...audit.priorSectionHeadings, ...externalizedHandoffDocuments.flatMap((document) => document.headings)])]
+            : audit.priorSectionHeadings;
+        return { ...audit, externalizedHandoffDocuments, priorSectionHeadings };
     }
     /** 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(). */
+     * handoffUpdatedAt token returned by preparePhaseHandoff().
+     *
+     * `content` is optional. When omitted, the body submitted on the last
+     * failed write against this exact phase + expectedHandoffUpdatedAt token
+     * is reused (throws HANDOFF_RETAINED_CONTENT_NOT_FOUND when none is
+     * retained). This is what makes a retry after any late write failure —
+     * stale token, unresolved placeholders, a deleted supporting document, a
+     * persisted read-back hash mismatch, or anything else — cheap instead of
+     * resending a capsule up to MAX_HANDOFF_CONTENT_CHARS: the body is sent
+     * once, and every other field on a retry is already small. On any failure
+     * below (other than the terminal-phase check, which discards instead —
+     * a terminal phase can never accept a retry) the content actually used is
+     * retained again for the next attempt; on success the entry for this
+     * token is discarded. */
     async refreshPhaseHandoff(phaseId, input) {
         return this.runAsBatch(async () => {
             const originalPhase = await this.loadPhase(phaseId);
             if (this.terminalHandoffReason(originalPhase)) {
+                await this.discardRetainedHandoffDrafts(phaseId);
                 throw new PlanStoreError(`Cannot write a handoff on ${originalPhase.status} phase ${phaseId}; terminal phases have no pending handoff.`);
             }
             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 existingCreatedAt = originalPhase.handoff.match(/^Created at:\s*(\S+)\s*$/im)?.[1] ?? timestamp;
-            const materializedContent = materializeHandoffMetadata(input.content, input.reason, existingCreatedAt, timestamp);
-            let effectiveInput = { ...input, content: materializedContent };
-            if (materializedContent.length > TARGET_HANDOFF_CONTENT_CHARS) {
-                const stamp = timestamp.replace(/[:.]/g, "-");
-                const autoPath = `.planner/docs/handoff-p${String(originalPhase.number).padStart(3, "0")}-${stamp}.md`;
-                const externalized = externalizeOversizedHandoffContent(materializedContent, autoPath);
-                if (externalized.externalized) {
-                    const docsDir = resolve(this.root, "docs");
-                    await mkdir(docsDir, { recursive: true });
-                    const target = resolve(this.root, autoPath.slice(".planner/".length));
-                    if (!target.startsWith(`${docsDir}${sep}`)) {
-                        throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Auto-externalized supporting document escapes .planner/docs/: ${autoPath}`, { path: autoPath });
-                    }
-                    await writeFile(target, externalized.extendedContent, "utf8");
-                    const autoDoc = externalized.supportingDocument;
-                    effectiveInput = {
-                        ...input,
-                        content: externalized.content,
-                        supportingDocuments: [...(input.supportingDocuments ?? []), autoDoc],
-                    };
-                }
+            const submittedContent = input.content?.trim() ? input.content : undefined;
+            let content;
+            if (submittedContent !== undefined) {
+                content = submittedContent;
+            }
+            else {
+                const retained = await this.getRetainedHandoffDraft(phaseId, input.expectedHandoffUpdatedAt);
+                if (!retained)
+                    throw retainedHandoffContentNotFoundError(phaseId, input.expectedHandoffUpdatedAt);
+                content = retained.content;
             }
-            const verifiedSupportingDocuments = await this.validateHandoffSupportingDocuments(effectiveInput.supportingDocuments ?? []);
-            const verifiedInput = {
-                ...effectiveInput,
-                verifiedSupportingDocuments: verifiedSupportingDocuments.metadata,
-                verifiedSupportingDocumentContents: verifiedSupportingDocuments.contents,
-            };
-            const originalFeature = originalFeatures.features[featureIndex];
-            const applied = applyHandoffContextSync(originalPhase, originalFeature, verifiedInput, timestamp);
             try {
-                // Keep the transaction granular: only the parent feature and target phase
-                // belong to this handoff refresh. Rewriting the whole feature document can
-                // disturb unrelated feature containment metadata.
-                await this.saveFeature(applied.feature);
-                await this.savePhase(applied.phase);
-                const phase = await this.loadPhase(phaseId);
-                const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
-                const persistedHash = handoffContentHash(phase.handoff);
-                if (phase.handoff !== applied.phase.handoff
-                    || !phase.handoffAudit
-                    || phase.handoffAudit.contentHash !== persistedHash
-                    || phase.handoffAudit.contentLength !== phase.handoff.length) {
-                    throw new HandoffContractError("HANDOFF_PERSISTENCE_VERIFICATION_FAILED", "The persisted handoff did not match the verified content. The write was rolled back.", { expectedHash: applied.phase.handoffAudit?.contentHash ?? "", actualHash: persistedHash });
+                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 existingCreatedAt = originalPhase.handoff.match(/^Created at:\s*(\S+)\s*$/im)?.[1] ?? timestamp;
+                const materializedContent = materializeHandoffMetadata(content, input.reason, existingCreatedAt, timestamp);
+                let effectiveInput = { ...input, content: materializedContent };
+                if (materializedContent.length > TARGET_HANDOFF_CONTENT_CHARS) {
+                    const stamp = timestamp.replace(/[:.]/g, "-");
+                    const autoPath = `.planner/docs/handoff-p${String(originalPhase.number).padStart(3, "0")}-${stamp}.md`;
+                    const externalized = externalizeOversizedHandoffContent(materializedContent, autoPath);
+                    if (externalized.externalized) {
+                        const docsDir = resolve(this.root, "docs");
+                        await mkdir(docsDir, { recursive: true });
+                        const target = resolve(this.root, autoPath.slice(".planner/".length));
+                        if (!target.startsWith(`${docsDir}${sep}`)) {
+                            throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Auto-externalized supporting document escapes .planner/docs/: ${autoPath}`, { path: autoPath });
+                        }
+                        await writeFile(target, externalized.extendedContent, "utf8");
+                        const autoDoc = externalized.supportingDocument;
+                        effectiveInput = {
+                            ...input,
+                            content: externalized.content,
+                            // The agent linked its documents in the body it submitted; this
+                            // rewrite may have moved those links into the external file. Carry
+                            // the original so validation judges the author's own linking.
+                            submittedContent: materializedContent,
+                            supportingDocuments: [...(input.supportingDocuments ?? []), autoDoc],
+                        };
+                    }
                 }
-                return {
-                    phase,
-                    feature,
-                    updatedTaskIds: applied.updatedTaskIds,
-                    handoffUpdatedAt: phase.handoffUpdatedAt,
-                    handoffAudit: phase.handoffAudit,
+                const verifiedSupportingDocuments = await this.validateHandoffSupportingDocuments(effectiveInput.supportingDocuments ?? []);
+                // Derived from the live originalPhase, not a copy captured at
+                // prepare time — see priorHandoffSectionHeadings for why that is
+                // exactly what "the prior capsule the author was shown" means even
+                // across an intervening handoff_clear.
+                const priorSectionHeadings = await this.priorHandoffSectionHeadings(originalPhase);
+                const verifiedInput = {
+                    ...effectiveInput,
+                    verifiedSupportingDocuments: verifiedSupportingDocuments.metadata,
+                    verifiedSupportingDocumentContents: verifiedSupportingDocuments.contents,
+                    priorSectionHeadings,
                 };
+                const originalFeature = originalFeatures.features[featureIndex];
+                const applied = applyHandoffContextSync(originalPhase, originalFeature, verifiedInput, timestamp);
+                try {
+                    // Keep the transaction granular: only the parent feature and target phase
+                    // belong to this handoff refresh. Rewriting the whole feature document can
+                    // disturb unrelated feature containment metadata.
+                    await this.saveFeature(applied.feature);
+                    await this.savePhase(applied.phase);
+                    const phase = await this.loadPhase(phaseId);
+                    const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
+                    const persistedHash = handoffContentHash(phase.handoff);
+                    if (phase.handoff !== applied.phase.handoff
+                        || !phase.handoffAudit
+                        || phase.handoffAudit.contentHash !== persistedHash
+                        || phase.handoffAudit.contentLength !== phase.handoff.length) {
+                        throw new HandoffContractError("HANDOFF_PERSISTENCE_VERIFICATION_FAILED", "The persisted handoff did not match the verified content. The write was rolled back.", { expectedHash: applied.phase.handoffAudit?.contentHash ?? "", actualHash: persistedHash });
+                    }
+                    await this.discardRetainedHandoffDrafts(phaseId, input.expectedHandoffUpdatedAt);
+                    return {
+                        phase,
+                        feature,
+                        updatedTaskIds: applied.updatedTaskIds,
+                        handoffUpdatedAt: phase.handoffUpdatedAt,
+                        handoffAudit: phase.handoffAudit,
+                    };
+                }
+                catch (error) {
+                    const rollbackErrors = [];
+                    // Restore the exact parsed snapshots directly. Going through saveFeature /
+                    // savePhase would restamp description freshness against the failed write.
+                    await atomicWriteJson(this.featurePath(originalFeature.id), FeatureSchema.parse(originalFeature), this.root)
+                        .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                    await atomicWriteJson(this.phasePath(originalPhase.id), PhaseSchema.parse(originalPhase), this.root)
+                        .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                    if (rollbackErrors.length > 0) {
+                        throw new AggregateError([error, ...rollbackErrors], "Handoff refresh failed and rollback was incomplete.");
+                    }
+                    throw error;
+                }
             }
             catch (error) {
-                const rollbackErrors = [];
-                // Restore the exact parsed snapshots directly. Going through saveFeature /
-                // savePhase would restamp description freshness against the failed write.
-                await atomicWriteJson(this.featurePath(originalFeature.id), FeatureSchema.parse(originalFeature), this.root)
-                    .catch((rollbackError) => rollbackErrors.push(rollbackError));
-                await atomicWriteJson(this.phasePath(originalPhase.id), PhaseSchema.parse(originalPhase), this.root)
-                    .catch((rollbackError) => rollbackErrors.push(rollbackError));
-                if (rollbackErrors.length > 0) {
-                    throw new AggregateError([error, ...rollbackErrors], "Handoff refresh failed and rollback was incomplete.");
-                }
+                const failureReason = error instanceof Error ? error.message : String(error);
+                await this.retainHandoffDraft(phaseId, input.expectedHandoffUpdatedAt, content, failureReason);
                 throw error;
             }
         });
@@ -3261,6 +3623,9 @@ export class PlanStore {
      *  "manual" | "superseded" | "imported". */
     async clearPhaseHandoff(phaseId, reason = "manual") {
         await this.migrateLegacyHandoffArchive();
+        // Any draft retained against a failed write for this phase is now moot,
+        // whether or not there was an active handoff body to archive below.
+        await this.discardRetainedHandoffDrafts(phaseId);
         const phase = await this.loadPhase(phaseId).catch(() => null);
         if (!phase || phase.handoff === "")
             return; // nothing to archive
@@ -3291,7 +3656,14 @@ export class PlanStore {
         let archived = 0;
         for (const phase of phases) {
             const reason = this.terminalHandoffReason(phase);
-            if (reason && phase.handoff) {
+            if (!reason)
+                continue;
+            // clearPhaseHandoff() already discards retained drafts, but only runs
+            // below when there is a body to archive; a terminal phase that never
+            // had a successful write (failed attempts only) still needs its
+            // retained draft swept here.
+            await this.discardRetainedHandoffDrafts(phase.id);
+            if (phase.handoff) {
                 await this.clearPhaseHandoff(phase.id, reason);
                 archived += 1;
             }