@tacuchi/agent-workflow-cli 25.7.0 → 25.9.0

package/dist/application/flow/internal-actions.js

@@ -25,34 +25,42 @@
  */
 import { join } from "node:path";
 import { dispositionOf } from "../../domain/flow/route.js";
-import { withPlanExecBatch, withPlanExecBatchLoop, withSettlement, } from "../../domain/flow/run-state.js";
-import { sealProposal } from "../../domain/proposal.js";
+import { legacyPlanExecCommits, withPlanExecBatch, withPlanExecBatchBase, withPlanExecBatchLoop, withPlanExecBatchUpdate, withSettlement, } from "../../domain/flow/run-state.js";
+import { approvedValidationOnly } from "../../domain/flow/unchanged-phase.js";
+import { canonicalEol, sealProposal } from "../../domain/proposal.js";
 import { obligationExit } from "../../domain/reconciliation.js";
 import { runArtifactsCommand } from "../artifacts-service.js";
-import { appendClaimEvent, claimKey, claimShapedAmong, completedClaimsIn, ledgerPath, openClaimsOf, readClaimEvents, revokedAmong, } from "../claims-ledger.js";
+import { appendClaimEvent, claimKey, claimShapedAmong, completedClaimsIn, ledgerPath, readClaimEvents, revokedAmong, } from "../claims-ledger.js";
 import { applyLocalProposal } from "../local-proposal.js";
 import { parseMdSectionBilingual } from "../markdown.js";
 import { parsePhases } from "../parsers/phases.js";
-import { parseTasks } from "../parsers/tasks.js";
 import { resolveWorkspaceRoot } from "../paths-service.js";
-import { inferPlanExecBatch, preparePlanExecDoneSeal, publishPlanExecBatch, } from "../plan-exec-batch-service.js";
+import { inferNextPlanExecBatch, preparePlanExecDoneSeal, publishPlanExecBatch, } from "../plan-exec-batch-service.js";
 import { settlePlanExecObligations } from "../plan-exec-decision-service.js";
+import { sealedPlanPath } from "../plan-exec-plan-diff.js";
 import { readSessionArtifacts } from "../release-data/artifacts.js";
 import { canonicalJson } from "../semantic-operation/protocol.js";
+import { canonicalArtifactPath } from "../session-artifacts.js";
 import { runSessionClose } from "../session-close-service.js";
 import { recordPublication } from "../session-custody-recorder.js";
+import { readCustody } from "../session-custody-service.js";
 import { runStatusCommand } from "../status-service.js";
 import { buildWorklineIndex } from "../workline-index-service.js";
-import { runWorktree } from "../worktree-service.js";
+import { runWorkspaceCommit } from "../workspace-commit-service.js";
+import { classifyListedUnits, runWorktree } from "../worktree-service.js";
+import { commitBatch, verifyBatchGitState } from "./batch-commit.js";
+import { observeScopedFingerprints, resolveCheckoutCandidates } from "./checkout-observation.js";
+import { preserveBoundaryClose } from "./close-artifacts.js";
+import { closeDocumentGuidance } from "./close-document-guidance.js";
 import { projectRun } from "./run-projection.js";
 import { applyUnderLock, locateRun, readRun } from "./run-state-service.js";
 export function internalActionExecutor(deps) {
     return async (plan, run) => {
         switch (plan.operation) {
             case "workspace.board":
-                return board(deps);
+                return board(deps, run);
             case "session.artifacts":
-                return artifacts(deps, run, plan.dump ?? null);
+                return artifacts(deps, run, plan.dump ?? null, run.session.endsWith("-plan-refine"));
             case "session.close":
                 return close(deps, run);
             case "worktree.ensure":
@@ -63,6 +71,8 @@ export function internalActionExecutor(deps) {
                 return inferBatch(deps, run);
             case "plan-exec.batch-close":
                 return closeBatch(deps, run);
+            case "plan-exec.batch-commit":
+                return commitBatch(deps, run);
             case "plan-exec.plan-done":
                 return sealPlanDone(deps, run);
             case "plan-exec.settlement-publish":
@@ -90,7 +100,7 @@ async function ensureUnits(deps, run) {
         return refusal("worktree.ensure", "la corrida no fijó qué fuentes edita: no hay unidad que adquirir", canonicalJson({ scope: null }));
     }
     const acquired = [];
-    for (const alias of scope.sources) {
+    for (const alias of scope.isolation === "in-place" ? [] : scope.sources) {
         // `workspace` is the documentary/control checkout itself. It is a valid
         // source-bounded proof surface, but never a source repository that needs a
         // per-session Git worktree.
@@ -108,16 +118,125 @@ async function ensureUnits(deps, run) {
         }
         acquired.push(result);
     }
+    const based = await recordBatchBase(deps, run, scope.sources);
+    if (!based.ok) {
+        return refusal("worktree.ensure", `${based.failure.message} — ${based.failure.action}`, canonicalJson({ failure: based.failure, acquired }));
+    }
     return {
         ok: true,
-        summary: `unidades de ${run.session}: ${acquired.map((unit) => `${unit.alias} → ${unit.branch}`).join(", ")}`,
+        summary: scope.isolation === "in-place"
+            ? "in-place: sin unidad"
+            : `unidades de ${run.session}: ${acquired.map((unit) => `${unit.alias} → ${unit.branch}`).join(", ")}`,
         output: canonicalJson({ plan: scope.plan, units: acquired }),
         // The tree IS there, however it got there — the same reading `proposal.publish`
         // makes of a re-entry that finds the bytes already written. Crediting nothing
         // when `created` is false would refuse the resumption this row is idempotent for.
-        effects: ["local_additive"],
+        effects: ["local_additive", "mutate_overwrite"],
+        ...(based.state === null ? {} : { state: based.state }),
     };
 }
+/** The batch this iteration walks, while it still has no base. */
+function batchAwaitingBase(state) {
+    const iteration = state.batch_loop?.iteration ?? null;
+    const batch = (state.batches ?? []).find((entry) => entry.iteration === iteration);
+    return batch?.base === undefined ? batch : undefined;
+}
+/**
+ * Seal, on the batch this iteration walks, what each of its sources looked like
+ * before its work — the base it will have to have changed to be credited.
+ *
+ * Taken here because this row runs once per iteration, after the previous
+ * batch's close and commit: comparing against the previous CREDIT instead would
+ * let the plan that close published, or the review's fixes, pass as the next
+ * batch's work. The first batch's base is the run's start.
+ */
+async function recordBatchBase(deps, run, sources) {
+    // Measuring hashes whole trees, so it happens only when a batch is waiting for
+    // its base; the lock below re-checks, and a run that moved fails its CAS.
+    const live = await readRun(deps.fs, locateRun(deps.paths, run.session));
+    if (live.ok && batchAwaitingBase(live.state) === undefined)
+        return { ok: true, state: null };
+    const observed = await observeScopedFingerprints(deps.fs, deps.git, deps.paths, run.session, sources);
+    if (!observed.ok)
+        return observed;
+    const legacy = live.ok && legacyPlanExecCommits(live.state);
+    const candidates = legacy
+        ? []
+        : await resolveCheckoutCandidates(deps.fs, deps.paths, run.session);
+    const snapshot = {};
+    for (const alias of legacy ? [] : sources) {
+        if (alias === "workspace")
+            continue;
+        const root = candidates.find((candidate) => candidate.source === alias)?.root;
+        if (root === undefined)
+            return {
+                ok: false,
+                failure: {
+                    code: "PLAN_EXEC_BATCH_UNIT_MISSING",
+                    message: `falta la unidad de ${alias}`,
+                    action: "adquirí la unidad antes de iniciar el lote",
+                },
+            };
+        try {
+            const [head, branch, dirty] = await Promise.all([
+                deps.git.head(root),
+                deps.git.currentBranch(root),
+                deps.git.dirtyPaths(root),
+            ]);
+            if (head === null ||
+                branch === undefined ||
+                (run.scope?.isolation !== "in-place" && dirty.length > 0)) {
+                return {
+                    ok: false,
+                    failure: {
+                        code: "PLAN_EXEC_BATCH_UNIT_DIRTY",
+                        message: `${alias}: no puede iniciar el lote con HEAD/rama ausente o rutas sucias: ${dirty.map((entry) => entry.path).join(", ")}`,
+                        action: "cerrá los cambios del lote anterior antes de iniciar éste",
+                    },
+                };
+            }
+            snapshot[alias] = { head, branch, dirty };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                failure: {
+                    code: "PLAN_EXEC_BATCH_GIT_UNOBSERVABLE",
+                    message: `${alias}: ${String(error)}`,
+                    action: "restaurá la lectura de git y reintentá la adquisición",
+                },
+            };
+        }
+    }
+    const recorded = await applyUnderLock(deps.fs, locateRun(deps.paths, run.session), (current) => {
+        if (current === null) {
+            return {
+                ok: false,
+                failure: {
+                    code: "FLOW_RUN_ABSENT",
+                    message: "la corrida desapareció antes de sellar la base del batch",
+                    action: "reanudá la corrida con 'aw flow advance'",
+                },
+            };
+        }
+        const batch = batchAwaitingBase(current);
+        // Outside plan-exec, before any batch was inferred, or with its base already
+        // sealed, there is nothing to seal.
+        if (batch === undefined)
+            return { ok: true, state: current, value: null, persist: false };
+        // A reseated run already holds the work of the batches it re-infers: their
+        // base is the one the archived run sealed before that work, not today's tree.
+        const inherited = current.inherited_bases?.find((entry) => entry.phases.length === batch.phases.length &&
+            entry.phases.every((phase, index) => phase === batch.phases[index]));
+        let next = withPlanExecBatchBase(current, batch.id, inherited?.base ?? observed.base);
+        if (batch.snapshot === undefined && !legacyPlanExecCommits(current))
+            next = withPlanExecBatchUpdate(next, batch.id, (item) => ({ ...item, snapshot }));
+        return { ok: true, state: next, value: null, persist: next !== current };
+    }, run.state_digest === undefined ? {} : { expectDigest: run.state_digest });
+    if (!recorded.ok)
+        return recorded;
+    return { ok: true, state: recorded.state };
+}
 /**
  * Write the run's approved proposal — all of it, or none of it.
  *
@@ -158,7 +277,7 @@ async function publish(deps, run) {
         ok: true,
         summary: result.already_applied
             ? `la propuesta ya estaba aplicada: ${destinations.join(", ")} sin cambios`
-            : `publicado: ${result.written.join(", ")}`,
+            : `publicado: ${result.written.join(", ")}${result.notice === undefined ? "" : `; aviso: ${result.notice}`}`,
         output: canonicalJson({ ...result, digest: proposal.digest, destinations, claims }),
         // Only what really landed. A re-entry that found the bytes already there
         // credits the same classes — the effect IS applied — and the summary is what
@@ -176,8 +295,8 @@ async function publish(deps, run) {
  * never held up by a ledger it does not depend on — an unreadable ledger must not
  * stop every loop in the system from saving.
  */
-async function revokedFence(deps, owner, destinations) {
-    const read = await readClaimEvents(deps.fs, deps.paths);
+export async function revokedFence(deps, owner, destinations) {
+    const read = await readClaimEvents(deps.fs, deps.paths, { lockHeld: true });
     const blocked = revokedAmong(read.events, owner, destinations);
     if (blocked.length > 0) {
         return {
@@ -187,13 +306,10 @@ async function revokedFence(deps, owner, destinations) {
         };
     }
     if (read.unreadable > 0) {
-        // Scoped to claims this owner ACTUALLY holds in the ledger, not to every
-        // numbered destination. Otherwise one unparseable line — and this file is a
-        // committed append-only JSONL, so a merge conflict produces exactly that —
-        // would refuse every SPEC, PLAN and QUICK save in the workspace, which is a
-        // workspace-wide outage rather than the narrow fail-closed this needs to be.
-        const mine = new Set(openClaimsOf(read.events, owner).map((claim) => claimKey(claim)));
-        const atRisk = claimShapedAmong(owner, destinations).filter((claim) => mine.has(claimKey(claim)));
+        // An illegible revoked row may have removed the very open claim a narrowed
+        // check would rely on. Every numbered destination is at risk; loose files
+        // outside the claim namespace remain unaffected.
+        const atRisk = claimShapedAmong(owner, destinations);
         if (atRisk.length > 0) {
             return {
                 code: "CLAIM_LEDGER_UNREADABLE",
@@ -229,6 +345,8 @@ async function recordCompletedClaims(deps, owner, result, destinations) {
     const recorded = [];
     try {
         const read = await readClaimEvents(deps.fs, deps.paths);
+        if (read.unreadable > 0)
+            return { recorded, ledger_unreadable: read.unreadable };
         const completed = completedClaimsIn(read.events, owner, {
             written: result.written,
             already_applied: result.already_applied,
@@ -255,13 +373,23 @@ async function recordCompletedClaims(deps, owner, result, destinations) {
         };
     }
 }
-async function board(deps) {
+async function board(deps, run) {
     const data = await runStatusCommand(deps.fs, deps.env, deps.paths, { git: deps.git });
     const counts = data.counts;
+    const custody = run.session.endsWith("-plan-new")
+        ? await readCustody(deps.fs, locateRun(deps.paths, run.session).dir)
+        : null;
+    const superseded = custody?.status === "present"
+        ? data.specs.find((spec) => spec.status === "superseded" &&
+            custody.custody.artifacts.some((artifact) => artifact.role === "input" && artifact.path === spec.file))
+        : undefined;
+    const warning = superseded === undefined
+        ? null
+        : `la spec ${superseded.number} fue reemplazada${superseded.superseded_by ? ` por ${superseded.superseded_by}` : ""}: plan-new debe usar el reemplazo`;
     return {
         ok: true,
-        summary: `tablero: ${counts.specs} specs, ${counts.plans} planes, ${counts.sessions_active} sesiones activas, ${counts.pending} pendientes`,
-        output: canonicalJson(data),
+        summary: `tablero: ${counts.specs} specs, ${counts.plans} planes, ${counts.sessions_active} sesiones activas, ${counts.pending} pendientes${warning ? `; aviso: ${warning}` : ""}`,
+        output: canonicalJson(warning ? { ...data, spec_readiness_warning: warning } : data),
         effects: ["read_only"],
     };
 }
@@ -275,10 +403,13 @@ async function board(deps) {
  * says the specific artifacts have content. A dump alone would pass a session
  * whose criteria were never seeded.
  */
-async function artifacts(deps, run, dump) {
+async function artifacts(deps, run, dump, planRefine = false) {
     // The presence report, without the narrative: this operation checks that the
     // artifacts are THERE, and projecting the session's whole reading to answer
     // that would be work nobody asked for on every advance.
+    if (dump?.includes("objetivo") && dump.includes("checkpoint")) {
+        await seedMissingCheckpoint(deps, run);
+    }
     const report = await runArtifactsCommand(deps.fs, deps.env, deps.paths, {
         code: run.code,
         noNarrative: true,
@@ -289,22 +420,27 @@ async function artifacts(deps, run, dump) {
     if (report.artifacts.session === null) {
         return refusal("session.artifacts", `la sesión '${report.session}' no tiene su SESSION.md`, canonicalJson(report));
     }
+    const destination = planRefine ? await refineDestination(deps, run, canonicalJson(report)) : "";
+    if (typeof destination !== "string")
+        return destination;
+    const legacyWarning = destination;
     if (dump === null) {
         return {
             ok: true,
-            summary: `sesión ${report.session}: SESSION.md presente, ${report.artifacts.session.criterios_count} criterios, ${report.artifacts.decisiones_count} decisiones`,
+            summary: `sesión ${report.session}: SESSION.md presente, ${report.artifacts.session.criterios_count} criterios, ${report.artifacts.decisiones_count} decisiones${legacyWarning}`,
             output: canonicalJson(report),
             effects: SEEDED_EFFECTS,
         };
     }
     const dumped = await readSessionArtifacts(deps.fs, deps.paths, run.code, [...dump], deps.runtime);
-    const output = canonicalJson({ report, dump: dumped });
+    const script = dump.includes("scripts") ? await rootScript(deps, run) : null;
+    const output = canonicalJson({ report, dump: dumped, root_script: script });
     if (dumped.error !== undefined) {
         return refusal("session.artifacts", String(dumped.hint ?? dumped.error), output);
     }
-    const empty = dump.filter((kind) => !hasContent(dumped[kind]));
+    const empty = dump.filter((kind) => !hasContent(dumped[kind]) && !(kind === "scripts" && hasContent(script)));
     if (empty.length > 0) {
-        return refusal("session.artifacts", `sin contenido: ${empty.join(", ")}`, output);
+        return refusal("session.artifacts", `sin contenido: ${empty.join(", ")}${empty.includes("scripts") ? " (SCRIPTS.sql o scripts/*.sql)" : ""}`, output);
     }
     // `objetivo` is the artifact that carries the success criteria, so demanding it
     // is demanding them: a SESSION.md with a criteria heading and nothing under it
@@ -316,11 +452,46 @@ async function artifacts(deps, run, dump) {
     }
     return {
         ok: true,
-        summary: `sesión ${report.session}: ${dump.join(", ")} con contenido, ${report.artifacts.session.criterios_count} criterios`,
+        summary: `sesión ${report.session}: ${dump.join(", ")} con contenido, ${report.artifacts.session.criterios_count} criterios${legacyWarning}`,
         output,
         effects: SEEDED_EFFECTS,
     };
 }
+async function seedMissingCheckpoint(deps, run) {
+    const folder = join(deps.paths.cwdSessionsDir(), run.session);
+    const checkpoint = canonicalArtifactPath(folder, "checkpoint");
+    if (await deps.fs.exists(checkpoint))
+        return;
+    const session = canonicalArtifactPath(folder, "session");
+    if (!(await deps.fs.exists(session)))
+        return;
+    const objective = parseMdSectionBilingual(await deps.fs.readText(session), "Objective")?.trim();
+    if (!objective || objective.includes("_[AI:"))
+        return;
+    await deps.fs.publishTextExclusive(checkpoint, `# CHECKPOINT\n\n## Completed\n\n## Pending / Next\n\n${objective}\n`);
+}
+/** Only this evidence reader accepts the root script; exports keep their dump. */
+async function rootScript(deps, run) {
+    const path = canonicalArtifactPath(join(deps.paths.cwdSessionsDir(), run.session), "scripts_sql");
+    return (await deps.fs.exists(path)) ? { path, content: await deps.fs.readText(path) } : null;
+}
+/** A new refine must be bound to an existing plan; only pre-custody sessions degrade. */
+async function refineDestination(deps, run, report) {
+    const custody = await readCustody(deps.fs, locateRun(deps.paths, run.session).dir);
+    if (custody.status === "unreadable") {
+        return refusal("session.artifacts", `custodia ilegible: ${custody.reason}`, report);
+    }
+    if (custody.status === "absent") {
+        return "; sesión legada sin custodia: no se puede verificar su plan destino";
+    }
+    for (const artifact of custody.custody.artifacts) {
+        if (artifact.role !== "input" || !/^docs\/plans\/\d{3,}-plan-[^/]+\.md$/.test(artifact.path))
+            continue;
+        if (await deps.fs.exists(join(deps.paths.workspaceDir(), artifact.path)))
+            return "";
+    }
+    return refusal("session.artifacts", "plan-refine exige un plan destino existente: creá la sesión con --input docs/plans/PPP-plan-<slug>.md o el descriptor <slug>-plan-refine, del que session-create deriva el plan", canonicalJson({ report, custody: custody.custody.artifacts.map((artifact) => artifact.path) }));
+}
 /**
  * What a satisfied artifact reading really attests.
  *
@@ -399,6 +570,16 @@ async function inferBatch(deps, run) {
         }
         const active = (current.batches ?? []).find((batch) => batch.published_plan_digest === undefined);
         if (active !== undefined) {
+            if (active.commit_result !== undefined && Object.keys(active.commit_result).length > 0) {
+                return {
+                    ok: false,
+                    failure: {
+                        code: "PLAN_EXEC_BATCH_REINFER_COMMITTED",
+                        message: `${active.id} ya tiene recibos de commit y no puede re-inferirse`,
+                        action: `revisá los recibos; para reabrir su trabajo usá aw flow annul --session ${run.session} --from ${active.id}`,
+                    },
+                };
+            }
             return {
                 ok: true,
                 state: current,
@@ -420,7 +601,7 @@ async function inferBatch(deps, run) {
                 },
             };
         }
-        const next = inferNextBatch(text, current);
+        const next = inferNextPlanExecBatch(text, current);
         if (!next.ok) {
             if (next.failure.code !== "PLAN_EXEC_BATCH_NONE_OPEN") {
                 return { ok: false, failure: next.failure };
@@ -437,6 +618,27 @@ async function inferBatch(deps, run) {
                 value: { batch: null, created: false, no_work: true },
             };
         }
+        // Store the exact plan text BEFORE publishing the inferred state. A retry
+        // either sees the same addressed copy or refuses rather than losing its base.
+        try {
+            const snapshot = sealedPlanPath(location.dir, next.batch.plan_digest);
+            await deps.fs.mkdirp(join(location.dir, ".plan-seals"));
+            const saved = await deps.fs.publishTextExclusive(snapshot, text);
+            if (!saved.created &&
+                canonicalEol(await deps.fs.readText(snapshot)) !== canonicalEol(text)) {
+                throw new Error("la copia direccionada no coincide con el plan inferido");
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                failure: {
+                    code: "PLAN_EXEC_BATCH_SNAPSHOT_UNAVAILABLE",
+                    message: `no se pudo guardar la copia sellada: ${String(error)}`,
+                    action: "revisá el almacenamiento de la sesión y reintentá la inferencia",
+                },
+            };
+        }
         return {
             ok: true,
             state: withPlanExecBatch(current, next.batch),
@@ -451,7 +653,7 @@ async function inferBatch(deps, run) {
         summary: inferred.value.no_work
             ? "el plan ya no tiene tareas abiertas: se omite el batch vacío y se expone la validación final"
             : inferred.value.created
-                ? `batch ${inferred.value.batch?.id ?? "nuevo"} inferido y sellado antes de implementar`
+                ? `batch ${inferred.value.batch?.id ?? "nuevo"} inferido y sellado antes de implementar; partición ${canonicalJson(inferred.value.batch?.partition ?? null)}`
                 : `batch ${inferred.value.batch?.id ?? "actual"} ya estaba inferido; se conserva su snapshot sellado`,
         output: canonicalJson({ batch: inferred.value.batch, created: inferred.value.created }),
         effects: [],
@@ -585,7 +787,27 @@ async function closeBatch(deps, run) {
     if (batch === undefined) {
         return refusal("plan-exec.batch-close", "no hay un batch inferido para cerrar: la corrida no puede acreditar tareas que no selló antes de implementarlas", canonicalJson({ code: "PLAN_EXEC_BATCH_NOT_INFERRED", plan: run.scope.plan }));
     }
+    // A batch born with a base was meant to be credited at its phase validation.
+    if (validationOnlyCloseMissing(live.state, batch)) {
+        return refusal("plan-exec.batch-close", "el lote de sólo validación carece de aprobación o de evidencia acreditada", canonicalJson({ code: "PLAN_VALIDATION_ONLY_NOT_APPROVED", batch: batch.id }));
+    }
+    // Reaching the close without that credit — an exhausted validation degraded
+    // past, a route that skipped it — would publish its tasks as done on no proof.
+    if (batch.base !== undefined && batch.credit === undefined) {
+        return refusal("plan-exec.batch-close", `el batch ${batch.id} no tiene acreditación: su validación de fase nunca aceptó una prueba propia del checkout de sus fuentes`, canonicalJson({ code: "PLAN_EXEC_BATCH_UNCREDITED", batch: batch.id, plan: run.scope.plan }));
+    }
     const phaseUpdates = phaseUpdatesForClosedBatch(text, batch);
+    if (batch.review === undefined && batch.published_plan_digest === undefined) {
+        return refusal("plan-exec.batch-close", `el batch ${batch.id} no tiene revisión registrada; completá review-findings con un revisor distinto y las correcciones revisadas`, canonicalJson({ code: "PLAN_EXEC_BATCH_REVIEW_MISSING", batch: batch.id }));
+    }
+    if (!legacyPlanExecCommits(live.state) && batch.commit_result === undefined) {
+        return refusal("plan-exec.batch-close", `el batch ${batch.id} no tiene resultado de commits verificado`, canonicalJson({ code: "PLAN_EXEC_BATCH_COMMIT_MISSING", batch: batch.id }));
+    }
+    if (!legacyPlanExecCommits(live.state)) {
+        const gitFailure = await verifyBatchGitState(deps, run, batch, run.scope?.isolation === "in-place");
+        if (gitFailure !== null)
+            return refusal("plan-exec.batch-close", gitFailure.message, canonicalJson(gitFailure));
+    }
     if (!phaseUpdates.ok) {
         return refusal("plan-exec.batch-close", `${phaseUpdates.failure.message} — ${phaseUpdates.failure.action}`, canonicalJson({ failure: phaseUpdates.failure }));
     }
@@ -613,11 +835,12 @@ async function closeBatch(deps, run) {
         ok: true,
         summary: published.already_applied
             ? `batch ${published.batch.id} ya estaba publicado en ${run.scope.plan}`
-            : `batch ${published.batch.id} publicado: ${published.written.join(", ")}`,
+            : `batch ${published.batch.id} publicado: ${published.written.join(", ")}${published.notice === undefined ? "" : `; aviso: ${published.notice}`}`,
         output: canonicalJson({
             batch: published.batch,
             written: published.written,
             already_applied: published.already_applied,
+            ...(published.notice === undefined ? {} : { notice: published.notice }),
         }),
         effects: ["mutate_overwrite"],
         state,
@@ -634,6 +857,10 @@ async function closeBatch(deps, run) {
  * already names the NEXT batch — or nothing, when it was the last one. The
  * publisher then confirms it through its own already-applied path.
  */
+function validationOnlyCloseMissing(state, batch) {
+    return (batch.kind === "validation-only" &&
+        (!approvedValidationOnly(state, batch) || batch.credit === undefined));
+}
 function batchToClose(state) {
     const batches = state.batches ?? [];
     const open = batches.find((batch) => batch.published_plan_digest === undefined);
@@ -693,11 +920,21 @@ async function sealPlanDone(deps, run) {
         return refusal("plan-exec.plan-done", "la corrida cambió mientras se preparaba el sello final", canonicalJson({ expected: run.state_digest, actual: live.state.digest }));
     }
     const missing = PLAN_DONE_REQUIRED_TRANSITIONS.filter((transition) => {
+        if (transition === "plan-exec.final-validation") {
+            return (!live.state.applied.includes(transition) ||
+                live.state.skipped.includes(transition) ||
+                (live.state.degraded ?? []).some((item) => item.transition === transition) ||
+                dispositionOf(live.state.route_decisions, transition)?.disposition === "substitute");
+        }
         if (live.state.applied.includes(transition))
             return false;
         const disposition = dispositionOf(live.state.route_decisions, transition)?.disposition;
         return disposition !== "omit" && disposition !== "substitute";
     });
+    if (!legacyPlanExecCommits(live.state) &&
+        (live.state.batches ?? []).some((batch) => batch.commit_result === undefined)) {
+        return refusal("plan-exec.plan-done", "hay lotes sin recibo o resultado de commit", canonicalJson({ code: "PLAN_EXEC_DONE_BATCH_COMMIT_MISSING" }));
+    }
     if (missing.length > 0) {
         return refusal("plan-exec.plan-done", `todavía falta evidencia de ${missing.join(", ")}`, canonicalJson({ code: "PLAN_EXEC_DONE_PREREQUISITE", missing }));
     }
@@ -765,6 +1002,12 @@ async function sealPlanDone(deps, run) {
 }
 /** The plan seal says exactly which evidence was absent or substituted. */
 function planDoneClosure(state, session) {
+    const destination = state.scope?.isolation === "in-place"
+        ? `commits en el checkout (${(state.batches ?? [])
+            .flatMap((batch) => Object.values(batch.commit_result ?? {}).map((receipt) => receipt.branch))
+            .filter((branch) => branch !== null)
+            .join(", ")}); sin integración`
+        : "commits e integración";
     const decisions = state.route_decisions ?? [];
     const controls = new Map((state.route_proposal?.controls ?? []).map((control) => [control.transition, control]));
     const omitted = decisions
@@ -778,15 +1021,15 @@ function planDoneClosure(state, session) {
         .map((decision) => decision.substitution)
         .filter((substitution) => substitution !== null);
     if (state.assurance === "unverified_accepted") {
-        return `evidencia omitida en la propuesta aceptada (${omitted.join("; ") || "sin detalle"}); commits e integración acreditados por la corrida ${session}; no se afirma que la validación pasó`;
+        return `evidencia omitida en la propuesta aceptada (${omitted.join("; ") || "sin detalle"}); ${destination} acreditados por la corrida ${session}; no se afirma que la validación pasó`;
     }
     if (state.assurance === "partially_verified") {
-        return `validación sustituta pendiente (${substitutions.map((substitution) => substitution.validation).join(", ") || "sin detalle"}); riesgo aceptado: ${substitutions.map((substitution) => substitution.risk).join(", ") || "assurance parcial"}; commits e integración acreditados por la corrida ${session}`;
+        return `validación sustituta pendiente (${substitutions.map((substitution) => substitution.validation).join(", ") || "sin detalle"}); riesgo aceptado: ${substitutions.map((substitution) => substitution.risk).join(", ") || "assurance parcial"}; ${destination} acreditados por la corrida ${session}`;
     }
     if (substitutions.length > 0) {
-        return `validación sustituta ejecutada (${substitutions.map((substitution) => substitution.validation).join(", ")}); commits e integración acreditados por la corrida ${session}`;
+        return `validación sustituta ejecutada (${substitutions.map((substitution) => substitution.validation).join(", ")}); ${destination} acreditados por la corrida ${session}`;
     }
-    return `validación final, commits e integración acreditados por la corrida ${session}`;
+    return `validación final, ${destination} acreditados por la corrida ${session}`;
 }
 /** The documentary checks that must pass in the same critical section as done. */
 export async function planDonePrecondition(deps, path, session) {
@@ -895,40 +1138,6 @@ function phaseUpdatesForClosedBatch(text, batch) {
         updates: batch.phases.map((phase) => ({ phase, state: "validada" })),
     };
 }
-function inferNextBatch(text, state) {
-    // `inferPlanExecBatch` itself validates that the phase has real, uniquely
-    // labelled Tn.m tasks. We only choose the first still-open phase from the
-    // document, which is a deterministic batch boundary rather than a claimed one.
-    const openPhase = parseTasks(text).items.find((task) => task.status === "open" && task.phase !== undefined)?.phase;
-    if (openPhase === undefined) {
-        const unresolved = parsePhases(text).items.find((phase) => phase.state !== "validada");
-        if (unresolved !== undefined) {
-            return {
-                ok: false,
-                failure: {
-                    code: "PLAN_EXEC_BATCH_PHASE_UNRESOLVED",
-                    message: `F${unresolved.n} sigue '${unresolved.state}' pero no tiene tareas abiertas acreditables`,
-                    action: "normalizá la fase con plan-refine; no se salta a la validación final sobre una fase no validada",
-                },
-            };
-        }
-        return {
-            ok: false,
-            failure: {
-                code: "PLAN_EXEC_BATCH_NONE_OPEN",
-                message: "el plan no tiene una fase con tareas abiertas que este batch pueda acreditar",
-                action: "el batch ya está cerrado: reanudá la corrida para que exponga la validación final",
-            },
-        };
-    }
-    const iteration = Math.max(0, ...(state.batches ?? []).map((batch) => batch.iteration)) + 1;
-    return inferPlanExecBatch(text, {
-        id: `batch-${iteration}`,
-        iteration,
-        mode: "continuous",
-        phases: [openPhase],
-    });
-}
 /**
  * Close the run's session — and refuse to, while it still holds a unit.
  *
@@ -940,14 +1149,74 @@ function inferNextBatch(text, state) {
  * notice behind a `.closed` marker that also makes the remedy stop resolving.
  */
 async function close(deps, run) {
-    const result = await runSessionClose(deps.fs, deps.paths, { code: run.code, requireIntegrated: true }, async () => {
-        const listed = await runWorktree({ fs: deps.fs, env: deps.env, git: deps.git, paths: deps.paths }, { action: "list" });
-        // A list that did not come back is NOT "no units": the close refuses on it,
-        // which is the whole point of asking before writing the marker.
-        if (!("units" in listed))
-            throw new Error(JSON.stringify(listed));
-        return listed.units;
-    });
+    const read = await readRun(deps.fs, locateRun(deps.paths, run.session));
+    if (!read.ok && read.failure.code !== "FLOW_RUN_ABSENT") {
+        return refusal("session.close", read.failure.message, canonicalJson(read.failure));
+    }
+    const boundaryClose = read.ok && read.state.reentries?.at(-1)?.kind === "close";
+    const listed = await runWorktree({ fs: deps.fs, env: deps.env, git: deps.git, paths: deps.paths }, { action: "list" });
+    if (!("units" in listed)) {
+        return refusal("session.close", "no se pudieron leer las unidades; revisá 'aw worktree list' y reintentá con 'aw flow advance'", canonicalJson(listed));
+    }
+    const classified = await classifyListedUnits(deps, listed.units);
+    const pending = boundaryClose
+        ? await preserveBoundaryClose(deps.fs, deps.paths, deps.git, read.state, classified, listed.unreadable ?? [])
+        : [];
+    const documents = read.ok ? await closeDocumentGuidance(deps.fs, deps.paths, read.state) : [];
+    const result = await runSessionClose(deps.fs, deps.paths, {
+        code: run.code,
+        withEvidence: read.ok &&
+            read.state.events.some((event) => event.kind === "executed" && event.operation === "workspace.evidence-approved"),
+        // `Cerrar` and a consented QUICK escalation are explicit human exits:
+        // incomplete criteria travel in BACKLOG, not as an invented completion.
+        force: boundaryClose ||
+            (read.ok &&
+                read.state.flow === "quick" &&
+                read.state.applied.includes("quick.escalation-destination") &&
+                !read.state.skipped.includes("quick.escalation-destination")),
+        requireIntegrated: !boundaryClose,
+        final: !boundaryClose,
+        preserveReservations: boundaryClose
+            ? (read.state.proposal?.artifacts.filter((a) => a.reserved).map((a) => a.path) ?? [])
+            : [],
+    }, async () => ({ units: classified, unreadable: listed.unreadable ?? [] }), deps.git, undefined, (alias, folder) => releaseClassifiedUnit(deps, alias, folder));
+    if ("sessionClose" in result) {
+        const approval = read.ok
+            ? [...read.state.events]
+                .reverse()
+                .find((event) => event.kind === "executed" && event.operation === "workspace.commit-approved")
+            : undefined;
+        if (approval?.kind === "executed") {
+            if (result.sessionClose.archive_error !== undefined ||
+                result.sessionClose.history_error !== undefined) {
+                result.sessionClose.commit_error = `no se ejecutó el commit: ${result.sessionClose.archive_error ?? result.sessionClose.history_error}`;
+            }
+            else {
+                try {
+                    const accepted = JSON.parse(approval.summary);
+                    if (typeof accepted === "object" &&
+                        accepted !== null &&
+                        "approval" in accepted &&
+                        typeof accepted.approval === "string") {
+                        const commit = await runWorkspaceCommit(deps.fs, deps.git, undefined, deps.paths, {
+                            code: run.session,
+                            approval: accepted.approval,
+                            withEvidence: read.ok &&
+                                read.state.events.some((event) => event.kind === "executed" && event.operation === "workspace.evidence-approved"),
+                        });
+                        if ("committed" in commit && commit.committed)
+                            result.sessionClose.commit_receipt = commit.committed;
+                        else
+                            result.sessionClose.commit_error =
+                                "error" in commit ? commit.error : "el commit aprobado no se produjo";
+                    }
+                }
+                catch (error) {
+                    result.sessionClose.commit_error = error instanceof Error ? error.message : String(error);
+                }
+            }
+        }
+    }
     if ("sessionHeld" in result) {
         const held = result.sessionHeld;
         return refusal("session.close", `${held.reason} — integralas con '${held.integrate}'`, canonicalJson(result));
@@ -957,15 +1226,27 @@ async function close(deps, run) {
         return refusal("session.close", `la sesión no cerró: ${why}`, canonicalJson(result));
     }
     const closed = result.sessionClose;
+    if (documents.length > 0)
+        closed.outdated_documents = documents;
+    if (boundaryClose) {
+        closed.pending_work = pending;
+        closed.reopen = `aw session-resume --code ${run.session} --reopen`;
+    }
     return {
         ok: closed.closed,
-        summary: `sesión ${closed.folder} cerrada${closed.history === undefined ? " (sin fila de HISTORY)" : ` · HISTORY ${closed.history.action}`}`,
+        summary: `sesión ${closed.folder} cerrada${closed.history === undefined ? " (sin fila de HISTORY)" : ` · HISTORY ${closed.history.action}`}${closed.sql_pending_export === undefined ? "" : ` · sql_pending_export: ${closed.sql_pending_export.files.join(", ")} → ${closed.sql_pending_export.command}`}${pending.length === 0 ? "" : ` · ${pending.join(" ")} · ${closed.reopen}`}${documents.length === 0 ? "" : ` · ${documents.join(" · ")}`}${!boundaryClose && closed.unverifiable_sources?.length ? ` · no verificable: ${closed.unverifiable_sources.map((item) => `${item.alias}: ${item.reason}`).join("; ")}` : ""}${closed.empty_units?.length ? ` · vacías conservadas: ${closed.empty_units.map((item) => item.alias).join(", ")}` : ""}${closed.preserved_units?.length ? ` · preservadas conservadas: ${closed.preserved_units.map((item) => item.alias).join(", ")}` : ""}${closed.released_empty?.length ? ` · vacías liberadas: ${closed.released_empty.map((item) => item.alias).join(", ")}` : ""}${closed.released_preserved?.length ? ` · preservadas liberadas: ${closed.released_preserved.map((item) => item.alias).join(", ")}` : ""}${closed.released_integrated?.length ? ` · integradas liberadas: ${closed.released_integrated.map((item) => item.alias).join(", ")}` : ""}${closed.commit_receipt ? ` · commit ${closed.commit_receipt.after}` : closed.commit_error ? ` · commit pendiente: ${closed.commit_error}` : ""}`,
         output: canonicalJson(result),
         // Closing ensures the CHECKPOINT exists and rewrites the session's marker plus
         // its HISTORY row: additive and overwriting, both real.
         effects: closed.closed ? ["local_additive", "mutate_overwrite"] : [],
     };
 }
+async function releaseClassifiedUnit(deps, alias, folder) {
+    const result = await runWorktree({ fs: deps.fs, env: deps.env, git: deps.git, paths: deps.paths }, { action: "release", alias, sessionCode: folder });
+    if ("error" in result || "released" in result)
+        return result;
+    return { error: "unit_unresolved", message: `no se pudo liberar ${alias} de ${folder}` };
+}
 function refusal(operation, message, output) {
     return { ok: false, summary: `${operation}: ${message}`, output, effects: [] };
 }