@sleepy_panda_srl/portulan 0.1.0 → 0.1.2

package/cli/stop-gate.mjs

@@ -43,10 +43,126 @@ import { recipeSet } from "./recipe-set.mjs";
 // The project root is TOLD to this runner rather than derived from where this file sits — see the same
 // paragraph in ./gate.mjs for why. In short: this file used to live inside the workspace it was reading,
 // which is the one layout it could ever work in, and is why it shipped in no artifact an adopter received.
+//
+// **These stay the TOLD values, and since #220's second arm they are no longer the whole answer.** The
+// tree a stop is ABOUT is resolved per invocation by `resolveSessionTree` from the payload's `cwd`,
+// because the told root is the repository this hook governs and not necessarily the working tree the
+// session used. Three things deliberately keep reading the told values whatever the session's cwd is:
+// the refusal COUNTER (a resolution that flips mid-session would rename its file and reset spent
+// counts — a cap weakening nobody chose), and both halves of the recipe — `defaultRecipe()` and the
+// `cwd` its command runs in. That last one is not a nicety: the gate executes the manifest's `run`
+// through `bash -c`, so a recipe read from a workspace found under a payload-supplied path would be
+// arbitrary command execution seeded by stdin. The recipe's jurisdiction is the workspace this hook
+// was wired into.
 const PROJECT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const WORKSPACE = path.resolve(PROJECT, process.env.PORTULAN_WORKSPACE || ".portulan");
 const REPO = PROJECT;
 
+/**
+ * WHICH TREE this stop is about — the session's own, or the one the hook was told.
+ *
+ * The told root is what the hook is wired with (`${CLAUDE_PROJECT_DIR}` in `.claude/settings.json`).
+ * It is not always the tree the session worked in: a session running in a git worktree, or simply
+ * `cd`-ed elsewhere, has both, and #220's second arm is that the gate answered about the told one.
+ * **The failure that arm exists for is a SILENT ALLOW** — told tree clean, session tree carrying
+ * unrecorded work — because `didWork()` reads the clean tree, returns false, and nothing is printed.
+ * The first arm's naming sentences cannot reach it: they live inside the block path.
+ *
+ * `payload.cwd` is the datum. Measured on this host, a real Stop payload carries
+ * `session_id, transcript_path, cwd, prompt_id, permission_mode, effort, hook_event_name,
+ * stop_hook_active, last_assistant_message, background_tasks, session_crons` — recorded because the
+ * record held no measurement of this payload's shape at all, and the whole arm rests on one field.
+ *
+ * **THE SAME-REPOSITORY GUARD, which is the difference between a fix and a bypass.** `cwd` is the one
+ * input the gated agent can steer, so a naive rescope would let a session point the gate at a clean
+ * unrelated clone and be allowed in silence — the very defect, one remove away. A foreign tree's
+ * obligations are also unsatisfiable, which is the shape that gets a rail switched off rather than
+ * fixed. So the session tree answers only when it is the SAME repository, compared by
+ * `--git-common-dir` and through `realpathSync`: worktrees share their common dir with the origin
+ * repository, which is exactly the class this arm exists for, while a foreign clone does not.
+ * Compared resolved, because macOS symlinks `/tmp` to `/private/tmp` and raw strings would disagree
+ * about identical directories.
+ *
+ * **What the same-repository condition does NOT close, said plainly because the sentences around it
+ * could be read as claiming otherwise.** It stops a foreign tree answering; it does not stop steering
+ * *within* this repository. A session whose told root is dirty and unrecorded can name a clean,
+ * recorded sibling worktree in `cwd` and be allowed — measured. That is narrower than the hole this
+ * arm closes and is not closable from here: the gate is told where the session ENDED, never where it
+ * worked, and a `cwd` inside this repository is exactly the datum this arm exists to trust.
+ * **Pinned** — as a recorded gap, not a wanted property — by *THE KNOWN HOLE (#307)* in
+ * `./stop-gate.test.mjs`, whose comment carries the contract for closing it.
+ *
+ * Returns `{ root, workspace, origin, note }`. `note` is a sentence to print when the datum was
+ * offered and could not be used; it is **null when `cwd` is simply absent**, because a host that
+ * never offered the field has degraded nothing and deserves today's behaviour byte for byte.
+ */
+function resolveSessionTree(cwd, told = { root: REPO, workspace: WORKSPACE }) {
+    const fell = (note) => ({ ...told, origin: "told", note });
+    if (typeof cwd !== "string" || cwd.trim() === "") return { ...told, origin: "told", note: null };
+
+    const git = (dir, args) => execFileSync("git", ["-C", dir, ...args], {
+        encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+
+    let root;
+    try {
+        root = git(cwd, ["rev-parse", "--show-toplevel"]);
+    } catch {
+        // Gone, or not a repository. Both exit 128; neither is a tree this gate can ask about.
+        return fell(`the session's directory (${cwd}) is not inside a git repository`);
+    }
+    if (!root) return fell(`the session's directory (${cwd}) yielded no repository root`);
+
+    // Same repository? Worktrees share a common dir with their origin; a foreign clone does not.
+    // **`--path-format` needs git 2.31, so it is TRIED, not required.** Where it is missing the flag
+    // is fatal, and without a fallback this comparison would throw on every stop — sending a correct
+    // worktree down the degraded path with a stderr sentence, on an old git, forever. The arm would
+    // read as shipped and do nothing, which is the shape this repository has been bitten by before.
+    // The bare spelling answers too, but RELATIVELY at a repository root (measured on git 2.50.1:
+    // `.git` there, absolute from a subdirectory or a linked worktree), so it is resolved against the
+    // directory that was asked. Copilot, round 2.
+    const commonDir = (dir) => {
+        let raw;
+        try {
+            raw = git(dir, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+        } catch {
+            raw = path.resolve(dir, git(dir, ["rev-parse", "--git-common-dir"]));
+        }
+        try {
+            return fs.realpathSync(raw);
+        } catch {
+            return raw;
+        }
+    };
+    let mine, theirs;
+    try {
+        mine = commonDir(told.root);
+        theirs = commonDir(root);
+    } catch {
+        return fell("this repository's identity could not be compared with the session's");
+    }
+    if (mine !== theirs) {
+        return fell(
+            `the session's directory (${cwd}) is in a different repository from the one this hook governs — ` +
+                "its obligations are not this repository's to enforce",
+        );
+    }
+
+    let resolved = root;
+    try {
+        resolved = fs.realpathSync(root);
+    } catch { /* the toplevel git just printed; keep it */ }
+    return {
+        root: resolved,
+        // Recomputed against the session tree, never reused from the told root, or the handoff
+        // question is asked correctly in the wrong directory. `path.resolve` leaves an ABSOLUTE
+        // `PORTULAN_WORKSPACE` absolute, so a workspace named absolutely deliberately does not travel.
+        workspace: path.resolve(resolved, process.env.PORTULAN_WORKSPACE || ".portulan"),
+        origin: "session",
+        note: null,
+    };
+}
+
 // The independent reasons this gate refuses a stop for. Each keeps its own consecutive count.
 //
 // Named as data rather than left implicit in the code, because the counters, the reset rule and the
@@ -236,8 +352,14 @@ function defaultRecipe() {
  * handoff gate while local commits sat there unrecorded.** A fail-open in the gate, and a quiet one.
  * Found by review on the pull request.
  */
-function didWork() {
-    const git = (args) => execFileSync("git", args, { cwd: REPO, encoding: "utf8", timeout: 10_000 });
+function didWork(root = REPO) {
+    // `maxBuffer` raised from node's 1 MiB default **for `git cherry`, which cannot be bounded the way
+    // the emptiness probe below can**: it must print a line per compared commit to be read at all,
+    // where the probe only has to answer yes-or-no and so is asked with `--max-count=1`. An overflow
+    // here throws into the outer catch and reads as *cannot tell* on precisely the branches that carry
+    // the most commits. This raise moves that cliff rather than removing it — every buffer is finite —
+    // which is why the probe is bounded instead of merely given more room.
+    const git = (args) => execFileSync("git", args, { cwd: root, encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 * 1024 });
 
     // 1. Uncommitted changes. Portable, and the strongest signal there is.
     try {
@@ -256,10 +378,122 @@ function didWork() {
         // No upstream configured. Ordinary for a branch that has never been pushed — fall through.
     }
 
-    // 3. Commits that are on no remote at all. Works with no upstream, and with no remote either —
-    //    in a repository with no remotes every commit qualifies, which is the correct reading there.
+    // 3. Commits whose PATCHES are on no remote — compared by patch-id, never by reachability.
+    //
+    // **This repository rebase-merges, and that makes reachability the wrong question** (#220). A
+    // rebase-merge rewrites commits, so a merged branch's originals appear on no remote; once the
+    // remote branch is deleted on merge they never will. `HEAD --not --remotes` therefore answers
+    // *yes, there is unrecorded work* **permanently**, for every commit of every merged-and-deleted
+    // branch — and any checkout left on such a branch demanded a handoff from a session that had
+    // done nothing. Measured 2026-08-10: the gate blocked twice over a handoff that was already on
+    // `main`, on the strength of four commits `git cherry` showed as fully upstream.
+    //
+    // The class is named in this repository for a different tool —
+    // `../.portulan/memory/a-branch-syncs-with-main-before-it-merges.md`, *"a rebase-merge leaves the
+    // branch tip an ancestor of nothing"* — and the sanctioned test there is `git cherry`:
+    // comparison by patch-id. This is that record applied at the site that asked the same wrong
+    // question.
     try {
-        return git(["log", "--oneline", "HEAD", "--not", "--remotes"]).trim() !== "";
+        // The coarse reading first, because it is cheap and it BOUNDS the expensive one: nothing on
+        // no remote by reachability means nothing on no remote by patch either, since a rewritten
+        // commit is still a commit that reachability would have found.
+        //
+        // **`rev-list --max-count=1`, not `log --oneline`, and the difference is a fail-open.** This
+        // asks only whether the set is EMPTY, but `log --oneline` answers by printing one line per
+        // commit — and a long-lived checkout on a rebase-merged branch is exactly where that set gets
+        // large, which is the situation this whole signal exists for. Past whatever `maxBuffer` is in
+        // force, `execFileSync` throws `ENOBUFS` (measured against node's 1 MiB default, which is what
+        // this ran on when the defect was found), the outer catch below turns that into `return false`,
+        // and the handoff check disables itself on the repositories most likely to need it.
+        //
+        // **The raised `maxBuffer` above does not make this redundant, and the order matters.** That
+        // raise moves the cliff; it does not remove one, because every buffer is finite and the set
+        // this probe asks about has no bound. Bounding the QUESTION is what removes the failure: one
+        // hash cannot outgrow any buffer. The raise is defence in depth for `git cherry`, which must
+        // print a line per compared commit and so cannot be bounded the same way. Copilot, round 3;
+        // the wording corrected in the same round after the raise made the original rationale stale.
+        if (git(["rev-list", "--max-count=1", "HEAD", "--not", "--remotes"]).trim() === "") return false;
+
+        // No remote at all: every commit qualifies, which is the correct reading there and is what
+        // this signal has always said. Documented rather than degraded, so it reports nothing.
+        const remotes = git(["remote"]).trim();
+        if (remotes === "") return true;
+
+        // A base to compare patches against: the remote's own recorded default head, never a branch
+        // picked by name. `./init.mjs`'s `delete-a-remote-branch` reason settles that — *"a wrong base
+        // answers no-unique-work about a question nobody asked"* — and `main` is not a name this file
+        // may assume, for the same reason signal 2 above stopped hard-coding `origin/main`.
+        // **ONE ordering, used by both the base selection and the sentence that reports its failure.**
+        // `git remote` lists alphabetically, so a repository carrying `backup` beside `origin` offered
+        // `backup/HEAD` first — and this loop takes the first that resolves, which means comparing
+        // patch-ids against a non-canonical remote and reaching a wrong allow/block, not merely a
+        // clumsy message. `origin` is the conventional canonical remote and is preferred where it
+        // exists. Written as one list rather than two matching literals because the first version of
+        // this preferred `origin` in the DEGRADED SENTENCE only, leaving the verdict itself on the
+        // alphabetical remote — a fix that repaired the report of a defect and not the defect.
+        // Copilot, round 3.
+        let base = null;
+        const listed = remotes.split("\n").filter(Boolean);
+        const named = listed.includes("origin") ? ["origin", ...listed.filter((r) => r !== "origin")] : listed;
+        for (const remote of named) {
+            try {
+                base = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", `${remote}/HEAD`]).trim() || null;
+                if (base) break;
+            } catch {
+                // This remote records no default head. Try the next one.
+            }
+        }
+
+        // **The refinement failed, so the coarse reading stands — and it stands as TRUE.**
+        //
+        // This is the fail-CLOSED direction and it is chosen rather than defaulted into. Commits on
+        // no remote is an established fact by the time we are here; only the attempt to excuse them
+        // as already-upstream could not be made. Reading that as *no work* would newly convert a
+        // case that blocks today into a pass — a relaxation, and this gate's own refusal message
+        // says relaxing a check is the change to scrutinise hardest. The asymmetry decides it: a
+        // wrong block is capped at MAX_BLOCKS and speaks, a wrong pass is unbounded and silent.
+        // `../.portulan/memory/verify-preconditions-fail-closed.md` is cited in this file's header
+        // for exactly this direction.
+        // The advice NAMES A COMMAND THE READER CAN RUN. The first draft always said
+        // `git cherry <remote>/HEAD HEAD` — but the commonest way into this branch is that
+        // `<remote>/HEAD` does not resolve, so the suggested check failed for the very reason the
+        // refinement did. Telling someone to re-run the thing that just broke is a diagnosis-shaped
+        // sentence carrying no diagnosis. Copilot, round 1.
+        const degraded = (why, check) => {
+            process.stderr.write(
+                `portulan stop-gate: could not compare by patch-id (${why}), so commits on no remote are ` +
+                    "being read as work. If this branch was rebase-merged the handoff demand may be spurious — " +
+                    `${check} and say so rather than working around the gate.\n`,
+            );
+            return true;
+        };
+        if (!base) {
+            // **The remotes are NAMED, because this runner already knows them** — it just tried every
+            // one. A `<remote>` placeholder in a multi-remote repository invites the reader to run the
+            // repair against whichever they think of first, which is how a diagnosis sends someone to
+            // the wrong ref. Copilot, round 3. `named` is already ordered `origin`-first above, so the
+            // remote this repairs is the same one the loop would have compared against — the two
+            // cannot disagree, which is why the ordering is computed once.
+            const which = named[0];
+            return degraded(
+                `no remote records a default head (tried \`${named.join("`, `")}\`)`,
+                `record one with \`git remote set-head ${which} -a\`, then check with ` +
+                    `\`git cherry ${which}/HEAD HEAD\``,
+            );
+        }
+
+        // **Exit 0 AND zero `+` lines, both required.** `git cherry` against an unknown ref exits 128
+        // and prints NOTHING, so counting `+` alone reads a failed command as *nothing unmerged* —
+        // measured, and already recorded in `../.portulan/gate-map.md` and `./init.mjs`'s
+        // `delete-a-remote-branch` reason as a fail-open closed once before. The exit half is carried
+        // by `git()` itself, which throws on non-zero; the catch below is that half, not decoration.
+        let cherry;
+        try {
+            cherry = git(["cherry", base, "HEAD"]);
+        } catch {
+            return degraded(`\`git cherry ${base} HEAD\` could not run`, `check with \`git cherry ${base} HEAD\``);
+        }
+        return cherry.split("\n").some((line) => line.startsWith("+"));
     } catch {
         // Genuinely cannot tell. Say so rather than inventing an obligation OR silently dropping one:
         // a gate that disables itself without a word is the failure this whole runner exists against.
@@ -269,21 +503,103 @@ function didWork() {
 }
 
 /** Is there a handoff dated today? The doctrine's checkable form: existence and a date, never length. */
-function handoffToday() {
-    const stamp = today();
+function handoffToday(stamp, workspace = WORKSPACE) {
     try {
-        return fs.readdirSync(path.join(WORKSPACE, "handoffs")).some((f) => f.startsWith(stamp) && f.endsWith(".md"));
+        return fs.readdirSync(path.join(workspace, "handoffs")).some((f) => f.startsWith(stamp) && f.endsWith(".md"));
     } catch {
         return false;
     }
 }
 
+/**
+ * WHICH TREE this gate just answered about — the working copy and the branch it is on.
+ *
+ * `handoffToday()` reads the directory under `WORKSPACE`, which is derived from `PROJECT`, which is
+ * whatever the host told this hook or whatever the cwd happens to be. That is deliberate — this file
+ * is TOLD its root rather than deriving one, for the reason its header gives — but it means the gate
+ * can ask a question about one tree and answer it from another. Measured 2026-08-10: a session whose
+ * worktree had been removed had its cwd fall back to the origin repository, parked on an unrelated
+ * branch 84 commits behind, and was told *"no handoff dated 2026-08-10"* while five sat on `main`.
+ *
+ * **Since #220's second arm the gate DOES rescope, and this names whichever tree answered.** An
+ * earlier version of this paragraph argued that naming was sufficient because a removed worktree
+ * cannot be read. That held for the one stop after the removal and failed as an argument about the
+ * arm: for the whole of that session's working phase both trees existed and differed, so every stop
+ * before the removal was already answering about the wrong one. The removal exposed the divergence
+ * rather than creating it. `resolveSessionTree` above now picks the session's tree from the Stop
+ * payload's `cwd` when it belongs to this repository, and falls back here — told root, named — only
+ * where it cannot.
+ */
+function treeIdentity(root = REPO) {
+    try {
+        const run = (args) => execFileSync("git", args, {
+            cwd: root, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        const branch = run(["rev-parse", "--abbrev-ref", "HEAD"]);
+        // **A DETACHED HEAD is the common case here, not the exotic one.** `--abbrev-ref` answers the
+        // literal string `HEAD` when no branch is checked out, and this repository routinely has several
+        // detached worktrees at once — measured: four, on the machine this was written on. Printing
+        // *"on `HEAD`"* would name a branch that does not exist, in the very sentence added so a reader
+        // could identify the tree. The commit is what identifies a detached one. Copilot, round 3.
+        if (branch === "HEAD") return `${root} (detached at \`${run(["rev-parse", "--short", "HEAD"])}\`)`;
+        return `${root} (on \`${branch}\`)`;
+    } catch {
+        return root;
+    }
+}
+
+/**
+ * A handoff dated today somewhere in this repository's history — every ref already on disk — or null.
+ *
+ * **No network, deliberately.** A Stop hook runs on every attempt to end a turn, and a fetch would
+ * put a remote round trip — and an offline host's timeout — inside the gate. So this reads refs that
+ * are already on disk — `--all` is every ref this repository carries, local branches included, not only
+ * remote-tracking ones. The sentence it feeds must not overclaim: *absent from this working tree* is
+ * always true when it fires; *present at `<ref>`* is claimed only where some ref on disk shows one.
+ */
+function handoffInHistory(stamp, tree = { root: REPO, workspace: WORKSPACE }) {
+    // **Root and workspace arrive as ONE pair, never mixed.** A told root beside a session workspace
+    // makes the relative path below start with `..`, the guard returns null, and the elsewhere arm
+    // dies in silence — the same both-must-move-together rule the caller obeys, inside this function.
+    try {
+        // **Separators normalised to `/`, because this becomes a git PATHSPEC.** `path.relative` yields
+        // `\` on Windows and git would match nothing — and the failure is silent: this returns null,
+        // the refusal loses the half that tells a reader their handoff is already recorded, and nothing
+        // says why. The same spelling is used wherever this repository hands git a derived path
+        // (`./librarian.mjs`, `./compile.mjs`). Copilot, round 3.
+        const dir = path.relative(tree.root, path.join(tree.workspace, "handoffs")).split(path.sep).join("/");
+        // A workspace outside the repository is not a question git can answer about this history.
+        if (dir === "" || dir.startsWith("..") || path.isAbsolute(dir)) return null;
+        const git = (args) => execFileSync("git", args, { cwd: tree.root, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
+        // `--all` is every ref already on disk, local and remote-tracking. `-1` because existence is
+        // the whole question — this is the doctrine's checkable form, not a census.
+        // **`:(glob)` magic, because a bare `*` is not reliably a glob.** With `GIT_NOGLOB_PATHSPECS`
+        // set, git reads `*` literally, this matches nothing, and the function returns null — silently
+        // reintroducing the exact "a handoff exists elsewhere and the gate does not say so" gap this
+        // arm exists to close. Measured on git 2.50.1: bare pattern matches 1 normally and **0** under
+        // `GIT_NOGLOB_PATHSPECS=1`; with `:(glob)` it matches 1 under both. _(The neighbouring lever
+        // `core.globPathspec=false` does NOT reproduce it — measured — so the magic is what makes this
+        // deterministic, not a config default.)_ Explicit pathspec magic is the same discipline
+        // `../.portulan/verify/plugin.sh` documents. Copilot, round 3.
+        const commit = git(["log", "--all", "-1", "--format=%H", "--", `:(glob)${dir}/${stamp}*`]).trim();
+        if (!commit) return null;
+        const refs = git(["branch", "--all", "--contains", commit, "--format=%(refname:short)"])
+            .split("\n").map((r) => r.trim()).filter(Boolean);
+        return { commit: commit.slice(0, 7), ref: refs[0] ?? null };
+    } catch {
+        // Cannot look. Say nothing rather than claim an absence — the refusal below is already
+        // correct without this sentence, and a false "nowhere in history either" would be worse
+        // than silence.
+        return null;
+    }
+}
+
 /**
  * Everything this gate refuses a stop for, plus whether the governing recipe was observed GREEN.
  * The two are reported separately because the consecutive-cap reset keys off the recipe alone, while
  * whether to block keys off the whole set.
  */
-function collectProblems() {
+function collectProblems(tree = { root: REPO, workspace: WORKSPACE, origin: "told", note: null }) {
     /** Every problem carries the REASON it belongs to — the key its own counter is kept under. */
     const problems = [];
     let recipeGreen = false;
@@ -328,18 +644,70 @@ function collectProblems() {
             const outcome = CANNOT_RUN.has(code) || code === undefined || code === null
                 ? `could not run (exit ${code ?? "no status"}) — the gate could not judge`
                 : `RED (exit ${code})`;
-            problems.push({ reason: "recipe", text: `verify recipe \`${recipe.id}\` — ${outcome}\n${output}` });
+            // The tree is named here too, now that one verdict can span two: the recipe is always run
+            // in the TOLD root (see the header) while the handoff question may have been answered
+            // about the session's. Without this, two problems in one refusal would read as though
+            // both concerned the same tree. Raised as optional at the session-open checkpoint; taken.
+            problems.push({
+                reason: "recipe",
+                text: `verify recipe \`${recipe.id}\` in ${REPO} — ${outcome}\n${output}`,
+            });
         }
     }
 
-    const handoffPresent = handoffToday();
-    if (didWork() && !handoffPresent) {
+    // **ONE date per Stop event, captured once and threaded through every use.** There were four
+    // independent `today()` calls on this path — the tree check, the history query, and both halves of
+    // the sentence. A stop spanning local midnight (or a host clock that jumps) could therefore CHECK
+    // one date and REPORT another, and worse, search history for a date nobody checked the tree for.
+    // `today()`'s own header records that this file has already produced one false red from a date
+    // disagreement; two dates inside a single verdict is the same class. Copilot, round 3.
+    const stamp = today();
+    const handoffPresent = handoffToday(stamp, tree.workspace);
+    // **`!handoffPresent` first, and the order is load-bearing rather than stylistic.** `didWork()`
+    // shells out to git several times and can print the could-not-compare sentence; ordered the other
+    // way, a session that HAS written its handoff still paid that cost on every Stop event and could
+    // be handed a degradation warning about an obligation it does not owe. Copilot, round 1.
+    if (!handoffPresent && didWork(tree.root)) {
+        // The tree is NAMED, because the sentence was once true about a tree the reader was not
+        // thinking of and read as a verdict about their session (#220).
+        //
+        // **A REFUSAL names both trees where they differ**, because a reader looking at the hook's
+        // configured root would otherwise not find the tree this verdict came from. Only on a refusal:
+        // told ≠ session is the routine worktree case here, so a divergence line on every green stop
+        // would be a metronome, and this gate's sentences are worth reading precisely because they are
+        // rare (#220 second arm).
+        // **Both sides resolved through `realpathSync`, or this sentence invents a divergence.**
+        // `resolveSessionTree` returns a realpathed root, so comparing it against a merely
+        // `path.resolve`d `REPO` makes a symlinked told root — `/tmp` on macOS, or any convenience
+        // link — read as a second tree, and the refusal then names one directory twice as though the
+        // session had worked somewhere else. Measured. It is the same trap the same-repository guard
+        // above already defends against, left unapplied one comparison away, which is why the guard's
+        // own reasoning is repeated here rather than assumed to carry.
+        const real = (dir) => {
+            try {
+                return fs.realpathSync(dir);
+            } catch {
+                return path.resolve(dir);
+            }
+        };
+        const answeredElsewhere = tree.origin === "session" && real(tree.root) !== real(REPO)
+            ? ` — the tree this session worked in, not the one this hook was told (${REPO})`
+            : "";
+        const elsewhere = handoffInHistory(stamp, tree);
+        const found = elsewhere
+            ? ` One dated ${stamp} does exist elsewhere in this repository's refs, at ` +
+              `${elsewhere.commit}${elsewhere.ref ? ` on \`${elsewhere.ref}\`` : ""} — so this working tree may not be ` +
+              "the tree that did the work. Check before writing a second one: a duplicate handoff reds `docs.sh`'s " +
+              "record check, which is the trap the bare sentence used to set."
+            : "";
         problems.push({
             reason: "handoff",
             text:
-                `no handoff dated ${today()} in .portulan/handoffs/. Every session ends with a dated handoff — ` +
-                "five lines is enough, absent is not. The Session log records what landed; the handoff records why, " +
-                "and the why is the part the next session cannot reconstruct from the diff.",
+                `no handoff dated ${stamp} in ${path.join(tree.workspace, "handoffs")}, read from ` +
+                `${treeIdentity(tree.root)}${answeredElsewhere}. ` +
+                "Every session ends with a dated handoff — five lines is enough, absent is not. The Session log " +
+                "records what landed; the handoff records why, and the why is the part the next session cannot " +
+                `reconstruct from the diff.${found}`,
         });
     }
 
@@ -407,7 +775,24 @@ function main() {
     }
 
     const sessionId = payload.session_id ?? "unknown";
-    const { problems, recipeGreen, handoffPresent } = collectProblems();
+
+    // **Resolved ONCE, here, and threaded down** — so every question this stop asks is about the same
+    // tree, and the sentence that reports the answer names that tree rather than another one.
+    const tree = resolveSessionTree(payload.cwd);
+
+    // **Degradation is spoken when the datum was offered and could not be used, and silent when it was
+    // never offered.** A host that sends no `cwd` has degraded nothing: it gets today's behaviour byte
+    // for byte, which is also what makes every pre-existing case a control for this change. A host that
+    // sent one this gate could not use is a different fact, and one a reader needs — printed whatever
+    // the verdict turns out to be, because it explains an allow just as much as a refusal.
+    //
+    // **The honest residue: on this path the silent-allow gap of #220 REMAINS, by construction.** The
+    // told root answers, and if the session's real tree carries unrecorded work this gate cannot see
+    // it. Forcing a block instead would manufacture an obligation from no evidence and leave the
+    // removed-worktree case permanently blocking — the false red the first arm was built to remove.
+    if (tree.note) process.stderr.write(`portulan stop-gate: ${tree.note}; answering about ${REPO} instead.\n`);
+
+    const { problems, recipeGreen, handoffPresent } = collectProblems(tree);
 
     // A reason's condition clearing ends THAT reason's futile-retry episode, whether or not the stop
     // is allowed, and never any other reason's. Done before the bump so a cleared reason cannot be

package/cli/upgrade.mjs

@@ -8,9 +8,8 @@
 //
 // Not here. `spec/migrations/` is the contract — a directory of steps, each a module — because a
 // migration is part of the **Workspace Definition** rather than part of a tool, and `spec/` ships in
-// `package.json`'s `files` so it would reach an `npx` user if the package were published — publishing
-// is Gated and has not happened, so there is no such user today, and whether there ever is remains
-// open (#242). See `../.portulan/identity.md`. This file is the runner: it decides which
+// `package.json`'s `files` so it reaches an `npx` user — the package was published 2026-08-18 at
+// `0.1.0`, closing #242, so that user now exists. See `../.portulan/identity.md`. This file is the runner: it decides which
 // steps a workspace owes, applies them, and grades the result with the real validator.
 //
 // **Two kinds of step**, by the maintainer's ruling of 2026-08-12: a `version` step migrates a