in2-agent-server 0.20260821.185429

package/dist/core/resume.js

@@ -0,0 +1,233 @@
+// RECONSTRUCT WHERE A RUN GOT TO, from the ledger plus the artifacts it left behind.
+//
+// A session directory has always held everything a run produced — the brief, one plan.json per
+// requirement, the wave bundles with their verdicts, the question rounds with their answers, the
+// authored trees. All of it is session-scoped and none of it needed changing for this. What was
+// missing was the one fact none of those artifacts states: WHERE THE RUN HAD GOT TO.
+//
+// That is not recoverable by inference, and the failure is asymmetric in the direction that costs
+// most. A chapter entered but not finished looks exactly like a chapter never entered: a session
+// with plans on disk and no wave bundles is either mid-clarification, or approved-and-about-to-
+// deploy, or rejected at the approval card and abandoned. Guess "about to deploy" on a run the
+// operator actually rejected and the resumed session deploys work nobody approved.
+//
+// So the ledger states position and the artifacts state substance, and this module reads both:
+// position from `phases.jsonl`, substance from the session directory, and the two are reported
+// separately rather than reconciled into one confident story. A disagreement between them is
+// itself the most useful thing a resumed session can be told.
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import { readQuestionRounds, statusFor } from "./operatorQa.js";
+import { chapterIndex, describeStall, ledgerHead, readPhaseLedger } from "./phases.js";
+import { gradeWaves, readWaveBundles } from "../direct/waveGrade.js";
+import { listDirs, sessionDir } from "./workspace.js";
+/**
+ * Read everything, tolerantly. Every step is guarded on its own: this runs against a session some
+ * other process died in the middle of writing, so a half-written artifact is the expected input
+ * rather than an exceptional one, and one unreadable file must never cost the report the other
+ * eleven facts it could have carried.
+ */
+export async function reconstruct(sessionId, now = new Date()) {
+    const root = sessionDir(sessionId);
+    const ledger = await readPhaseLedger(sessionId);
+    const chapter = ledgerHead(ledger);
+    let session = {};
+    try {
+        session = JSON.parse(await fs.readFile(path.join(root, "session.json"), "utf8"));
+    }
+    catch {
+        // A session with no readable session.json still has artifacts worth reporting on.
+    }
+    const requirements = await readRequirementStates(root);
+    const rounds = (await readQuestionRounds(sessionId).catch(() => []))
+        .map((r) => ({ round: r.round, status: statusFor(r.questions), questions: r.questions.length }))
+        .sort((a, b) => a.round - b.round);
+    const bundles = readWaveBundlesSafely(path.join(root, "direct"));
+    const waves = bundles.map((b) => ({ wave: b.wave, verdict: b.verdict, practice: b.dryRunOnly }));
+    const waveGrade = bundles.length > 0 ? safeGrade(bundles) : null;
+    const hasBrief = existsSync(path.join(root, "analysis", "brief.md"));
+    const evidence = { hasBrief, requirements, rounds, waves };
+    const { resumeInto, reason } = decideResume(chapter, evidence);
+    return {
+        sessionId,
+        chapter,
+        ledger,
+        lastMovedAgo: describeStall(ledger, now),
+        resumeInto,
+        resumeReason: reason,
+        orgAlias: session.targetOrg?.alias ?? null,
+        orgId: session.targetOrg?.orgId ?? null,
+        batchId: session.batchId ?? null,
+        hasBrief,
+        requirements,
+        rounds,
+        waves,
+        waveGrade,
+        discrepancies: findDiscrepancies(chapter, evidence)
+    };
+}
+/**
+ * WHICH CHAPTER TO RESUME INTO — the ledger's chapter, RE-ENTERED rather than advanced past.
+ *
+ * The rule is one line and the reasoning is the whole point: a boundary is crossed when a chapter
+ * FINISHES, so the last entry says which chapter the run was IN when it died, and that chapter is
+ * by construction incomplete. Resuming into the next one would skip whatever was left of it.
+ *
+ * With no ledger at all, the position is inferred from artifacts and SAID TO BE an inference. The
+ * inference is deliberately CONSERVATIVE — it never lands on `delivery` or later, because the two
+ * states artifacts genuinely cannot distinguish (approved-and-paused versus rejected-and-abandoned)
+ * differ precisely in whether deploying is allowed, and the safe reading of that ambiguity is the
+ * one that re-asks. A resumed run that re-confirms an approval costs the operator one card; one
+ * that assumes an approval it never had deploys unapproved work.
+ */
+export function decideResume(chapter, evidence) {
+    if (chapter !== null) {
+        return {
+            resumeInto: chapter,
+            reason: `the phase ledger records ${chapter} as entered and never completed — a boundary is crossed when a chapter FINISHES, so that chapter is where the run stopped, not the one after it`
+        };
+    }
+    const inferred = inferChapter(evidence);
+    return {
+        resumeInto: inferred,
+        reason: `this session has NO phase ledger, so ${inferred} is INFERRED from the artifacts on disk, not recorded. Treat it as a starting point to confirm with the operator rather than as a fact about the run`
+    };
+}
+/** Artifact-only inference, capped at `scope-approval`. See `decideResume` for why it stops there. */
+function inferChapter(evidence) {
+    if (evidence.waves.length > 0)
+        return "scope-approval";
+    if (evidence.rounds.some((r) => r.status !== "ANSWERED"))
+        return "clarification";
+    if (evidence.rounds.length > 0)
+        return "clarification";
+    if (evidence.requirements.some((r) => r.hasPlan))
+        return "clarification";
+    if (evidence.hasBrief)
+        return "parallel-analysis";
+    if (evidence.requirements.length > 0)
+        return "intake";
+    return "activation";
+}
+/**
+ * Where the artifacts and the ledger disagree.
+ *
+ * REPORTED, NEVER RESOLVED. Both sources are honest and neither is authoritative over the other:
+ * the ledger records what the supervisor SAID it had finished, the artifacts record what actually
+ * reached disk, and a gap between them is a fact about the run — usually that it died between doing
+ * the work and announcing it. Picking a winner here would throw away exactly the signal a resumed
+ * session most needs, so each mismatch is named and left for the reader.
+ */
+export function findDiscrepancies(chapter, evidence) {
+    const out = [];
+    if (chapter === null)
+        return out;
+    const at = chapterIndex(chapter);
+    const missingPlans = evidence.requirements.filter((r) => !r.hasPlan);
+    if (at > chapterIndex("parallel-analysis") && missingPlans.length > 0) {
+        out.push(`the ledger is past analysis, but ${missingPlans.length} requirement(s) have no plan.json: ${missingPlans.map((r) => r.extId).join(", ")}. Either those analyzers never finished, or the batch was analyzed inline — which is legal, and in that case their Configuration Item ownership must be passed explicitly at writeback.`);
+    }
+    const unmerged = evidence.requirements.filter((r) => r.unmergedFragments > 0);
+    if (unmerged.length > 0) {
+        out.push(`${unmerged.length} requirement(s) have UNMERGED plan fragments: ${unmerged.map((r) => `${r.extId} (${r.unmergedFragments})`).join(", ")}. plan_waves will refuse with PLAN_FRAGMENTS_UNRESOLVED until they are merged into the one canonical plan.json.`);
+    }
+    const open = evidence.rounds.filter((r) => r.status !== "ANSWERED");
+    if (open.length > 0) {
+        out.push(`${open.length} question round(s) are still open: ${open.map((r) => `round ${r.round} (${r.status})`).join(", ")}. The operator was asked and the answers were never recorded — re-put those questions before acting on any assumption about them.`);
+    }
+    if (at < chapterIndex("delivery") && evidence.waves.length > 0) {
+        out.push(`the ledger has not reached delivery, but ${evidence.waves.length} wave bundle(s) exist in the org's evidence directory. Waves reached the org before the ledger recorded the boundary — read their verdicts before planning anything new, because the org has already moved.`);
+    }
+    if (at >= chapterIndex("delivery") && evidence.waves.length === 0) {
+        out.push("the ledger reached delivery but no wave bundle exists, so nothing has reached the org. That is the state of a run approved and then interrupted before its first apply.");
+    }
+    return out;
+}
+async function readRequirementStates(root) {
+    const dir = path.join(root, "requirements");
+    let index = [];
+    try {
+        index = JSON.parse(await fs.readFile(path.join(dir, "index.json"), "utf8"));
+    }
+    catch {
+        // No index: fall back to the directories, which is what the requirement tree looks like anyway.
+        index = (await listDirs(dir)).map((extId) => ({ extId }));
+    }
+    const states = [];
+    for (const entry of index) {
+        const reqDir = path.join(dir, entry.extId);
+        let fragments = 0;
+        try {
+            fragments = (await fs.readdir(reqDir)).filter((n) => /^plan\.fragment-.+\.json$/.test(n)).length;
+        }
+        catch {
+            // A requirement directory that vanished is reported as having no plan, which it does not.
+        }
+        const hasPlan = existsSync(path.join(reqDir, "plan.json"));
+        states.push({
+            extId: entry.extId,
+            title: entry.title ?? entry.extId,
+            hasPlan,
+            // Fragments beside a canonical plan.json are ARCHIVE MATERIAL the supervisor should have
+            // moved, not an unresolved merge. Only fragments with no plan.json beside them are the state
+            // plan_waves refuses on, so only those are counted.
+            unmergedFragments: hasPlan ? 0 : fragments
+        });
+    }
+    return states.sort((a, b) => a.extId.localeCompare(b.extId));
+}
+function readWaveBundlesSafely(directDir) {
+    try {
+        return readWaveBundles(directDir);
+    }
+    catch {
+        return [];
+    }
+}
+function safeGrade(bundles) {
+    try {
+        return gradeWaves(bundles).result;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The reconstruction as prose the supervisor relays and acts on.
+ *
+ * Ordered by what a resumed run has to decide FIRST: where it stands, whether it can still touch
+ * the org, what it must not assume, and only then the inventory. The auth question leads the
+ * "can it act" half because it is the one that fails at the worst moment — a run that starts
+ * planning and discovers at wave one that its token died an hour ago has spent the operator's time
+ * on work it cannot deliver.
+ */
+export function renderReconstruction(r, auth) {
+    const lines = [
+        `RESUMING SESSION ${r.sessionId}`,
+        "",
+        r.chapter
+            ? `WHERE THE RUN STANDS: ${r.chapter}${r.lastMovedAgo ? `, last moved ${r.lastMovedAgo}` : ""}.`
+            : "WHERE THE RUN STANDS: no phase ledger — this session predates chapter tracking, or never crossed a boundary.",
+        `  Re-enter: ${r.resumeInto} — ${r.resumeReason}.`,
+        ""
+    ];
+    lines.push("ORG ACCESS:", `  ${auth.summary}`);
+    if (!auth.usable) {
+        lines.push("  You cannot deploy, project or read the org until this is fixed, and you must NOT fix it yourself.", "  Card the operator with exactly one ask, then stop. Do not plan around a dead org — a plan built", "  on a projection you could not take is a plan built on the requirement text alone.");
+    }
+    lines.push("");
+    if (r.batchId) {
+        lines.push(auth.telemetryRebound
+            ? `EVIDENCE: this batch's grant is still valid, so this session ships its own events and transcript, and close_batch will close the batch normally.`
+            : `EVIDENCE: this machine has NO usable grant for batch ${r.batchId} any more, so nothing from this resumed session reaches the IN2 ledger — including close_batch. The delivery itself is unaffected; say so plainly rather than reporting a close that did not ship.`, "");
+    }
+    lines.push("WHAT IS ON DISK:", `  requirements: ${r.requirements.length}${r.requirements.length > 0 ? ` (${r.requirements.filter((q) => q.hasPlan).length} with a plan.json)` : ""}`, `  analysis brief: ${r.hasBrief ? "written" : "NOT written"}`, `  question rounds: ${r.rounds.length > 0 ? r.rounds.map((q) => `round ${q.round} ${q.status}`).join(", ") : "none"}`, `  waves delivered to the org: ${r.waves.length > 0 ? r.waves.map((w) => `${w.wave} ${w.verdict}${w.practice ? " (practice)" : ""}`).join(", ") : "none"}`, ...(r.waveGrade ? [`  the bundles currently grade ${r.waveGrade} — that is what the evidence supports, NOT a batch that was closed`] : []), "");
+    if (r.requirements.length > 0) {
+        lines.push("REQUIREMENTS:", ...r.requirements.map((q) => `  ${q.extId}  ${q.hasPlan ? "planned" : "NO plan.json"}  ${q.title}`), "");
+    }
+    if (r.discrepancies.length > 0) {
+        lines.push("READ THESE BEFORE DOING ANYTHING — the ledger and the artifacts do not agree, and neither is", "authoritative over the other:", ...r.discrepancies.map((d) => `  - ${d}`), "");
+    }
+    lines.push("HOW TO PICK THIS UP:", "  1. Read the artifacts before re-deriving anything. The brief, the plans and the wave verdicts are", "     this run's own decisions; re-deriving them produces a second, differently-worded batch model and", "     silently discards what the operator already agreed to.", "  2. THE ORG HAS MOVED if any wave landed. Re-`project_org` the scope you are about to touch rather", "     than trusting a projection taken before those waves.", "  3. Tell the operator where the run stands and what you are about to do, in one message, before you", "     do it. They were present for the first half of this run and are owed the join.", "  4. NEVER re-confirm an approval you cannot see. An approval card lives in the transcript of the", "     dead session, not on disk — if this run is at or past scope-approval and you did not watch them", "     approve it, put the plan to them again.", "  5. Call `advance_phase` at each boundary from here on, and `close_batch` at the end. A resumed run", "     that is never closed reads as ABANDONED exactly like the one it resumed.");
+    return lines.join("\n");
+}

package/dist/core/revisionChain.js

@@ -0,0 +1,351 @@
+import { entryRef } from "./planFile.js";
+export function deriveRevisionChains(entries, exists) {
+    const revisionEntries = [];
+    const routes = [];
+    for (const entry of entries) {
+        // A ROUTE is work leaving by another path — a Deployment Task, a facet update on someone else's
+        // component. It owns no authored file and deploys through no wave, so it is not a state of the
+        // component and cannot be a link in its chain. Counting it as one is how a one-node "cycle"
+        // gets manufactured (`waves.ts:203-208` fixed the same mistake on the ownership side).
+        //
+        // A DELETE IS NOT A ROUTE, however it is marked. It carries no file and rides the destructive
+        // path, which is what tempts an author to write `deployable: false` beside it — the live
+        // workaround did exactly that — but a route carries no ORDER, and the whole reason a deletion
+        // belongs in the chain is that it must follow whatever this batch does to the component first.
+        // So `delete` wins over `deployable` here, and the old habit lands in the right place.
+        (entry.intent === "delete" || entry.deployable ? revisionEntries : routes).push(entry);
+    }
+    const byKey = new Map();
+    for (const entry of revisionEntries) {
+        const group = byKey.get(entry.key) ?? [];
+        group.push(entry);
+        byKey.set(entry.key, group);
+    }
+    const reaches = requirementReachability(revisionEntries);
+    const existence = memoizedExistence(exists);
+    const chains = [];
+    const refusals = [];
+    const hazards = [];
+    const inferences = [];
+    for (const [key, group] of byKey) {
+        const first = group[0];
+        if (!first)
+            continue;
+        // 1. INTENT. Declared wins; otherwise infer from positive evidence only.
+        const resolved = [];
+        const unverifiable = [];
+        for (const entry of group) {
+            if (entry.intent !== null) {
+                resolved.push({ entry, intent: entry.intent, intentSource: "declared" });
+                continue;
+            }
+            const state = existence(first);
+            if (state === "unknown") {
+                unverifiable.push(entry);
+                continue;
+            }
+            const intent = state === "present" ? "update" : "create";
+            inferences.push({ key, extId: entry.extId, index: entry.index, intent, from: state });
+            resolved.push({ entry, intent, intentSource: "inferred" });
+        }
+        if (unverifiable.length > 0) {
+            // No chain for this key. An entry that could be either a create or an update leaves the
+            // ORDER undefined, not merely the entry — emitting a partial chain would order the rest
+            // around a revision whose position nobody established.
+            hazards.push({
+                code: "INTENT_UNVERIFIABLE",
+                reason: "intent",
+                key,
+                message: [
+                    `${key}: ${unverifiable.length} entr${unverifiable.length === 1 ? "y" : "ies"} declare no intent, and this session has not observed the component, so none can be inferred.`,
+                    "Declare `intent: \"create\" | \"update\"` on them, or run project_org over this component first.",
+                    ...unverifiable.map((e) => `  ${e.extId} entry ${e.index}`)
+                ].join("\n"),
+                entries: unverifiable.map(entryRef)
+            });
+            continue;
+        }
+        const creates = resolved.filter((r) => r.intent === "create");
+        const updates = resolved.filter((r) => r.intent === "update");
+        const deletes = resolved.filter((r) => r.intent === "delete");
+        /** The revisions that leave a component behind — everything a delete would be destroying. */
+        const survivors = [...creates, ...updates];
+        // 2. ROOT. Exactly one, and only three things can be one (R4).
+        if (creates.length > 1) {
+            // The REAL ownership conflict, and the one the model deliberately keeps. Legalising
+            // create-then-update does not legalise creating the same component twice.
+            refusals.push({
+                code: "DOUBLE_CREATE",
+                key,
+                message: [
+                    `${key} is created twice in this batch. A component has exactly one create; a later state of it is an \`update\`.`,
+                    ...creates.map((c) => `  ${c.entry.extId} entry ${c.entry.index}: intent=create (${c.intentSource})${c.entry.authoredFile ? ` file=${c.entry.authoredFile}` : ""}`),
+                    "If one of these is meant to be a later state of the component, declare it `intent: \"update\"`."
+                ].join("\n"),
+                entries: creates.map((c) => entryRef(c.entry))
+            });
+            continue;
+        }
+        // A component is destroyed once. Two requirements each declaring the deletion is not a chain
+        // with two terminal links, it is two requirements that have not agreed who owns the removal —
+        // and a destructive package naming the same member twice is what neither of them meant.
+        if (deletes.length > 1) {
+            refusals.push({
+                code: "DOUBLE_DELETE",
+                key,
+                message: [
+                    `${key} is deleted twice in this batch. A component has at most one deletion, and nothing follows it.`,
+                    ...deletes.map((d) => `  ${d.entry.extId} entry ${d.entry.index}: intent=delete (${d.intentSource})`),
+                    "Decide which requirement owns the removal and drop the other entry; the second deletion has nothing left to delete."
+                ].join("\n"),
+                entries: deletes.map((d) => entryRef(d.entry))
+            });
+            continue;
+        }
+        const deletion = deletes[0];
+        const state = existence(first);
+        let root;
+        if (creates.length === 1) {
+            root = "create";
+        }
+        else if (survivors.length === 0) {
+            // Delete-only: nothing in this batch builds the component, so the ORG is what grounds it.
+            // A DIFFERENT refusal from the update case on purpose, because the remedies are opposites:
+            // an update with no target should probably have been a create, while a delete with no target
+            // is a component that is already gone and the fix is to drop the entry.
+            if (state === "absent") {
+                refusals.push({
+                    code: "DELETE_WITHOUT_TARGET",
+                    key,
+                    message: [
+                        `${key} is deleted in this batch, and this session's projection covered it and found it absent — there is nothing to delete.`,
+                        "It is already gone, or the fullName is wrong. Drop the entry or correct the name; do not submit a destructive",
+                        "package for a member the org does not have.",
+                        ...deletes.map((d) => `  ${d.entry.extId} entry ${d.entry.index}: intent=delete (${d.intentSource})`)
+                    ].join("\n"),
+                    entries: deletes.map((d) => entryRef(d.entry))
+                });
+                continue;
+            }
+            root = "brownfield-delete";
+        }
+        else {
+            // Update-only: the root has to be grounded in the ORG. Only demonstrated absence refuses.
+            if (state === "absent") {
+                refusals.push({
+                    code: "UPDATE_WITHOUT_ROOT",
+                    key,
+                    message: [
+                        `${key} is only updated in this batch, and this session's projection covered it and found it absent — there is nothing to update.`,
+                        "Either the first revision should be `intent: \"create\"`, or the component belongs to a requirement that is not in this batch.",
+                        ...updates.map((u) => `  ${u.entry.extId} entry ${u.entry.index}: intent=update (${u.intentSource})`)
+                    ].join("\n"),
+                    entries: updates.map((u) => entryRef(u.entry))
+                });
+                continue;
+            }
+            root = "brownfield-update";
+        }
+        // 3. ORDER. Updates chain linearly, or the ambiguity is named rather than guessed at.
+        //
+        // Checked BEFORE the unverified-root hazard is emitted: a chain that gets refused here is not
+        // going to be planned, and a hazard asking the operator to widen the projection for it would be
+        // one more thing to read on the way to the refusal that actually blocks them.
+        const ordering = orderUpdates(updates, reaches);
+        if ("unordered" in ordering) {
+            refusals.push({
+                code: "UNORDERED_UPDATES",
+                key,
+                message: [
+                    `${key} has ${updates.length} update revisions with no derivable order between them — nothing says which state comes first.`,
+                    "Add a `dependsOn` edge so one requirement's revision follows the other's (the supervisor derives revision order",
+                    "from cross-requirement dependencies, the same way it orders waves). Entries needing an edge:",
+                    ...ordering.unordered.map((u) => `  ${u.entry.extId} entry ${u.entry.index}${u.entry.authoredFile ? ` file=${u.entry.authoredFile}` : ""}`)
+                ].join("\n"),
+                entries: ordering.unordered.map((u) => entryRef(u.entry))
+            });
+            continue;
+        }
+        // 4. NOTHING FOLLOWS A DELETE. The deletion is terminal by construction — placed last below —
+        // so a contradiction is only visible in the requirement graph: an entry whose requirement the
+        // batch's own dependencies put strictly AFTER the deleting requirement is asking to deploy a
+        // component that no longer exists. Named rather than silently resequenced, because either the
+        // edge or the deletion is wrong and only the author knows which.
+        if (deletion) {
+            const stranded = survivors.filter((r) => strictlyAfter(r, deletion, reaches));
+            if (stranded.length > 0) {
+                refusals.push({
+                    code: "REVISION_AFTER_DELETE",
+                    key,
+                    message: [
+                        `${key} is deleted by ${deletion.entry.extId}, and ${stranded.length} revision(s) of it are ordered AFTER that deletion by this batch's own dependencies.`,
+                        "A component cannot be created or updated once it has been destroyed. Either the deletion belongs later than",
+                        "these revisions (remove the dependency edge that puts them after it), or they belong to a component this batch",
+                        "is not deleting. Entries stranded after the deletion:",
+                        ...stranded.map((r) => `  ${r.entry.extId} entry ${r.entry.index}: intent=${r.intent} (${r.intentSource})`)
+                    ].join("\n"),
+                    entries: stranded.map((r) => entryRef(r.entry))
+                });
+                continue;
+            }
+        }
+        if (root !== "create" && state === "unknown") {
+            // The chain's ORDER is derivable; only whether anything grounds it is not. So the chain
+            // stands and the open question is surfaced beside it — the alternative is refusing every
+            // brownfield edit the supervisor has not happened to project, which is most of them.
+            const grounded = root === "brownfield-delete" ? deletes : updates;
+            hazards.push({
+                code: "INTENT_UNVERIFIABLE",
+                reason: "root",
+                key,
+                message: [
+                    root === "brownfield-delete"
+                        ? `${key} is deleted in this batch and this session has not observed it, so nothing confirms it exists to be deleted.`
+                        : `${key} is only updated in this batch and this session has not observed it, so nothing confirms it exists to be updated.`,
+                    root === "brownfield-delete"
+                        ? "Run project_org over this component to confirm it. A destructive package naming a member the org does not have fails the whole package, taking every other member down with it."
+                        : "Run project_org over this component to confirm it, or declare the first revision as `intent: \"create\"` if it does not exist yet.",
+                    ...grounded.map((r) => `  ${r.entry.extId} entry ${r.entry.index}`)
+                ].join("\n"),
+                entries: grounded.map((r) => entryRef(r.entry))
+            });
+        }
+        // The deletion goes LAST, always. It is the one revision whose position needs no derivation:
+        // whatever else this batch does to the component, it does it before the component is gone.
+        const sequence = [...creates, ...ordering.ordered, ...(deletion ? [deletion] : [])];
+        const revisions = sequence.map((link, at) => ({
+            entry: link.entry,
+            intent: link.intent,
+            intentSource: link.intentSource,
+            // Predecessor by KEY: the batch's create, or the prior update in this chain (R2). No ordinals
+            // anywhere — analyzers author plan.json independently per requirement, so "who is @2" would
+            // demand cross-plan coordination nothing provides.
+            predecessor: at === 0 ? null : (sequence[at - 1]?.entry ?? null)
+        }));
+        chains.push({ key, typeName: first.typeName, fullName: first.fullName, root, existence: state, revisions });
+    }
+    return { chains, refusals, hazards, inferences, routes };
+}
+/**
+ * "Does `a`'s requirement come after `b`'s, and unambiguously so?"
+ *
+ * The `!reaches(b, a)` half is what makes it strict: in a requirement cycle both directions are
+ * reachable, and reading that as an order would sequence entries nothing sequenced. Two entries
+ * from the SAME requirement are never strictly after each other — one plan.json's own entries carry
+ * no cross-requirement edge to derive from.
+ */
+const strictlyAfter = (a, b, reaches) => a.entry.extId !== b.entry.extId && reaches(a.entry.extId, b.entry.extId) && !reaches(b.entry.extId, a.entry.extId);
+/**
+ * Put a key's update revisions in order, or say which ones cannot be ordered.
+ *
+ * `dependsOn` names COMPONENT KEYS, so two updates of the same key cannot point at each other
+ * directly — they share the key. What they can point at is each other's REQUIREMENTS: the
+ * supervisor already derives cross-requirement ordering by matching each `dependsOn` key to
+ * whichever requirement owns that component (the analyzer skill states this as the one dependency
+ * mechanism), and revision order is that same relation read per key.
+ *
+ * Two updates authored by the same requirement therefore have no derivable order, and neither do
+ * two whose requirements are unrelated. Both are named, not guessed at.
+ */
+function orderUpdates(updates, reaches) {
+    if (updates.length < 2)
+        return { ordered: [...updates] };
+    const unordered = new Set();
+    const afterCount = new Map(updates.map((u) => [u, 0]));
+    for (let i = 0; i < updates.length; i++) {
+        for (let j = i + 1; j < updates.length; j++) {
+            const a = updates[i];
+            const b = updates[j];
+            if (!a || !b)
+                continue;
+            if (strictlyAfter(a, b, reaches)) {
+                afterCount.set(a, (afterCount.get(a) ?? 0) + 1);
+            }
+            else if (strictlyAfter(b, a, reaches)) {
+                afterCount.set(b, (afterCount.get(b) ?? 0) + 1);
+            }
+            else {
+                unordered.add(a);
+                unordered.add(b);
+            }
+        }
+    }
+    if (unordered.size > 0) {
+        return { unordered: updates.filter((u) => unordered.has(u)) };
+    }
+    return { ordered: [...updates].sort((a, b) => (afterCount.get(a) ?? 0) - (afterCount.get(b) ?? 0)) };
+}
+/**
+ * "Does requirement A come after requirement B?", transitively, from the batch's own dependsOn keys.
+ *
+ * Cycle-safe on purpose: a genuine requirement cycle is `plan_waves`' diagnostic to report, not
+ * this module's to crash on. A cycle simply makes both directions reachable, which `strictlyAfter`
+ * reads as no order — so the entries get named rather than silently sequenced.
+ */
+function requirementReachability(entries) {
+    const owners = new Map();
+    for (const entry of entries) {
+        // A DELETION DOES NOT OWN THE COMPONENT FOR ORDERING PURPOSES. `dependsOn: X` means "X must
+        // exist first", and the requirement that answers that is the one that BUILDS X — a deletion is
+        // the opposite claim. Counting it here manufactures an edge from every requirement that depends
+        // on X to the requirement removing X, which then reads as "your create comes after my delete"
+        // and refuses a perfectly ordinary create-then-delete pair (caught by the cycle fixture in
+        // `tools/planWaves.test.ts`, where it swallowed a genuine cycle by refusing its chain first).
+        if (entry.intent === "delete")
+            continue;
+        const set = owners.get(entry.key) ?? new Set();
+        set.add(entry.extId);
+        owners.set(entry.key, set);
+    }
+    const edges = new Map();
+    for (const entry of entries) {
+        const out = edges.get(entry.extId) ?? new Set();
+        for (const dep of entry.dependsOn) {
+            // An entry depending on its OWN key is the late-facet shape (`waves.ts:106-118` strips
+            // exactly this today), and under the revision model it reads "after the previous revision of
+            // me" — a statement about the chain, not about requirements. Feeding it to the requirement
+            // graph is worse than useless: with three revisions of one key it points at every OTHER
+            // owner at once, making two updates mutually reachable and destroying an order that other
+            // edges did establish.
+            if (dep === entry.key)
+                continue;
+            for (const owner of owners.get(dep) ?? []) {
+                if (owner !== entry.extId)
+                    out.add(owner);
+            }
+        }
+        edges.set(entry.extId, out);
+    }
+    const closures = new Map();
+    const closure = (node) => {
+        const done = closures.get(node);
+        if (done)
+            return done;
+        const reached = new Set();
+        closures.set(node, reached); // seeded before recursing, so a cycle terminates
+        const stack = [...(edges.get(node) ?? [])];
+        while (stack.length > 0) {
+            const next = stack.pop();
+            if (next === undefined || reached.has(next))
+                continue;
+            reached.add(next);
+            for (const onward of edges.get(next) ?? [])
+                if (!reached.has(onward))
+                    stack.push(onward);
+        }
+        return reached;
+    };
+    return (from, to) => closure(from).has(to);
+}
+/** One predicate call per key — the caller's may read a projection off disk. */
+function memoizedExistence(exists) {
+    const cache = new Map();
+    return (component) => {
+        const hit = cache.get(component.key);
+        if (hit !== undefined)
+            return hit;
+        const state = exists({ typeName: component.typeName, fullName: component.fullName, key: component.key });
+        cache.set(component.key, state);
+        return state;
+    };
+}

package/dist/core/richText.js

@@ -0,0 +1,61 @@
+/**
+ * Escaping and decoding for Salesforce RICH TEXT fields.
+ *
+ * A rich-text field stores HTML, and Salesforce runs a sanitizer over it on save. An unescaped `<`
+ * in a VALUE is read as the start of a tag, and everything through the next `>` is dropped as
+ * markup — silently. The write returns success; the stored text is short a clause.
+ *
+ * LIVE-CAUGHT 2026-08-02 (PV corpus, Arm A, REQ-15736): a deployment note carrying the validation
+ * rule `PV_Value__c <= 0` lost the formula's tail AND the `<br/>` that followed it. Nothing in the
+ * API response said so. It was found by the supervisor's read-back mismatch, and because
+ * Deployment_Notes__c APPENDS, it could not be repaired by re-running — a correction block had to be
+ * appended by hand.
+ *
+ * Salesforce config work is exactly the content that trips this: validation-rule formulas, SOQL
+ * comparisons, `&&`, and raw metadata XML are what a deployment note is FOR. So every caller-supplied
+ * string that becomes part of a rich-text body goes through `escapeRichText` here, and the markup the
+ * tools add (`<b>`, `<br/>`) is composed afterwards, around the escaped text.
+ *
+ * This lives in core/ rather than beside its callers because both a writer (tools/campfire.ts) and a
+ * reader (tools/session.ts) need the decoder, and the two must agree — a value that escapes one way
+ * and decodes another is a read-back mismatch waiting to happen.
+ */
+/**
+ * Caller text -> safe rich-text content.
+ *
+ * `&` is replaced FIRST, or the rule would re-escape the ampersands the `<`/`>` rules just
+ * introduced and `a < b` would store as `a &amp;lt; b` — visible entity soup instead of a `<`.
+ *
+ * Only these three. `"` and `'` are legal in HTML text content and reach the field intact (the Arm A
+ * report noted quotes and `->` surviving), and escaping them only makes the stored note harder for a
+ * human to read in Campfire. They are still DECODED below, because Salesforce may normalize them on
+ * its own — escape narrowly, decode generously.
+ */
+export function escapeRichText(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+const ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    "#39": "'",
+    nbsp: " "
+};
+/**
+ * Stored rich text -> the characters it means.
+ *
+ * ONE pass, deliberately. A chain of `.replace(/&amp;/, "&")` then `.replace(/&lt;/, "<")` decodes
+ * twice: a stored `&amp;lt;` (which MEANS the literal five characters `&lt;`) loses its ampersand to
+ * the first rule and is then eaten by the second, arriving as `<`. That collapses the difference
+ * between a value containing `<` and one containing the text `&lt;` — the exact distinction the
+ * read-back check exists to police, so a real corruption could compare equal and pass.
+ */
+export function decodeHtmlEntities(value) {
+    return value.replace(/&(amp|lt|gt|quot|apos|#39|nbsp);/gi, (match, name) => ENTITIES[name.toLowerCase()] ?? match);
+}
+/** Caller text -> a rich-text fragment: escaped, with newlines as the line breaks the field renders. */
+export function richTextFragment(text) {
+    return escapeRichText(text).replace(/\n/g, "<br/>");
+}