@sleepy_panda_srl/portulan 0.1.1 → 0.1.2

package/cli/recipe-set.mjs

@@ -61,7 +61,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { resolvePack, rootPlan } from "./compile.mjs";
+// `shadowedCopy` rides along: one carrier for *is this pack shadowed*, per #316.
+import { resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 
 /**
@@ -288,6 +289,46 @@ export function resolverFor({ workspaceDir, manifest, repoRoot = ".", named = []
     if (plan.refusal) throw new Error(`recipe-set: ${plan.refusal}`);
     if (plan.couldNotRun) throw new Error(`recipe-set: ${plan.couldNotRun}`);
     const roots = plan.roots ?? [];
+    const originAt = (r) => (plan.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
+
+    // **A shadowed pack is refused here too** (#318), and this tool's ground is the strongest of the
+    // three. `compile` refuses even an agreeing shadow because its artifact records which root
+    // answered; `index` refuses one although its artifact deliberately does not. Here the answering
+    // root is not merely recorded — **it is spliced into the output**: `${PACK_ROOT}` expands to the
+    // root that answered, so two copies whose manifests are byte-identical still yield different `run`
+    // lines pointing at different files. What CI runs and what a bare local run runs would diverge,
+    // with nothing in either output to say so.
+    //
+    // So the agreeing case is not a carve-out anyone could argue for here, and the honest predicate was
+    // never manifest comparison: it is output equality, computable only by resolving both worlds.
+    // Refusing the ambiguity is what remains.
+    //
+    // **Checked HERE rather than inside the returned closure**, which is where a first cut put it. The
+    // closure runs during `recipeSet`, outside the `try` that wraps this constructor — so the refusal
+    // escaped as an uncaught throw, exit 1 with a stack trace, in a tool whose whole contract is exit 2
+    // for could-not-run. Measured, not reasoned about. Throwing from the constructor puts it on the
+    // path `plan.refusal` already uses and the caller already catches.
+    //
+    // **Only where the caller did not choose** — a named root replaces the derived one, `auto` is
+    // discovery elected — which is `compile`'s guard shape, bound to it deliberately.
+    if (!forced && plan.source !== "named") {
+        const declared = Array.isArray(manifest?.packs) ? manifest.packs : [];
+        for (const ref of declared) {
+            const found = resolvePack(String(ref), roots);
+            if (!found?.dir) continue;
+            // Path-resolved, matching `compile` — see the sibling note in `index.mjs`.
+            const behind = shadowedCopy(String(ref), originAt(found.root), roots, originAt);
+            if (!behind) continue;
+            throw new Error(
+                `recipe-set: \`${ref}\` is SHADOWED — it resolved under ${found.root}, a root discovered on ` +
+                    `this host, while the root ${path.relative(path.resolve(repoRoot), behind.root)} also carries it. ` +
+                    "A composed recipe's ${PACK_ROOT} expands to whichever root answered, so the two compose to " +
+                    "run lines pointing at different files. Refusing to pick: name the root — `--pack-root packs` " +
+                    "for the tree, which is what CI runs, or `--pack-root auto` for the installed copy.",
+            );
+        }
+    }
+
     return (ref) => {
         const found = resolvePack(ref, roots);
         // `resolvePack` returns `manifest` as the PATH to `pack.json`, not as the parsed object —

package/cli/skills-set.mjs

@@ -75,6 +75,33 @@
  *   every manifest in this repository already has. A manifest formatted otherwise is reformatted, and
  *   that is a real cost rather than a hidden one.
  *
+ * ## A pack two roots answer for is refused, not picked
+ *
+ * On a host carrying an installed copy of a composed pack **and** the tree's own, resolution is
+ * discovered-first and first-match-wins, so the installed copy answers. That copy lives outside the
+ * plugin root, containment fails, and this tool concluded the tree's declared skills path belonged to
+ * no composed pack — printing `--write` as the remedy, where `--write` is the mutation that strips a
+ * correct declaration out of a tracked manifest
+ * ([#317](https://github.com/sleepy-panda-srl/portulan/issues/317)).
+ *
+ * So this refuses at RESOLUTION — exit 2 — where `compile` refuses for the same family
+ * ([#316](https://github.com/sleepy-panda-srl/portulan/issues/316)), and for the same reason: the
+ * printer, `--check` and `--write` inherit ONE rule rather than three. Refusing on `--write` alone
+ * would leave `--check` exiting **1**, asserting the *repository* had drifted when it had not — and an
+ * exit code is the machine-read API, so a false 1 is a false verdict about the tree.
+ *
+ * **The predicate is imported, not re-spelled.** `shadowedCopy` and `packDifferences` live in
+ * `./compile.mjs`. That comparison had already been wrong twice in `doctor` before it became one
+ * carrier, and a third copy written inside a fix for its own family is precisely the defect
+ * `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md` names.
+ *
+ * **Where this tool's reason is SHARPER than `compile`'s, and the message says so.** `compile` refuses
+ * a shadow whose manifests agree because `recordedOrigin` writes the answering root into the artifact,
+ * so agreement in the manifests is not agreement in the bytes. Here agreement is beside the point in a
+ * more direct way: the two copies sit on opposite sides of the plugin root, so which one answers
+ * decides whether this pack contributes a `skills` path **at all**. Version parity does not save it,
+ * which is why this fires on hosts where `compile`'s difference-driven half would have nothing to say.
+ *
  * Zero dependencies, no network, no install step — the same constraints as every tool here.
  */
 
@@ -93,7 +120,7 @@ import { pathToFileURL } from "node:url";
 // root wins outright; otherwise discovery is unioned with the derived root, discovered first** — asking
 // only selects the strict degrade. This tool exited **2** on the ordinary drafted workspace until then,
 // which is what the row's "optional where discovery finds a root" was not.)_
-import { resolvePack, rootPlan } from "./compile.mjs";
+import { packDifferences, recordedOrigin, resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 
 /**
@@ -425,6 +452,114 @@ export function declaredFor(set, pluginManifest, pluginRoot) {
     return [...portion.outside, ...set.paths.map((p) => p.path)];
 }
 
+/**
+ * The refusal a shadowed pack earns, or `null` when no declared pack is shadowed.
+ *
+ * Separated from `run` so the sentence a reader gets is testable without a command line, and kept in
+ * this file rather than pushed into `compile.mjs` because the CONSEQUENCE clause is this tool's own:
+ * `compile` talks about emitted policy, and this one talks about whether a `skills` path is derived.
+ * What is shared — *is there a second copy behind the one that answered, and do the two differ* — is
+ * imported, and that split is the point.
+ *
+ * Only the **unasked** path reaches here. `--pack-root <dir>` names a root, which replaces the derived
+ * one and leaves nothing behind it to shadow; `--pack-root auto` is discovery ELECTED, and refusing
+ * somebody for answering the question the refusal asks would be incoherent. Both spellings are offered
+ * in the message for that reason — naming only the tree would make the refusal decide the question it
+ * claims to hand back.
+ */
+export function shadowRefusal({ packs, roots, plan, repoRoot, pluginRoot }) {
+    const originOf = (r) => (plan?.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
+    for (const ref of Array.isArray(packs) ? packs : []) {
+        const found = resolvePack(ref, roots);
+        if (!found?.dir || !found.manifest) continue;
+        const behind = shadowedCopy(found.name, recordedOrigin(found.root, plan, repoRoot), roots, originOf);
+        if (!behind) continue;
+
+        const there = path.relative(repoRoot, behind.root) || behind.root;
+        // **The tree spelling is the root we just named, not the conventional guess.** Both arms below
+        // hard-coded `--pack-root packs`, and the derived root is `path.resolve(workspaceDir, tree,
+        // "packs")` — so a workspace whose `tree` is `../nested/` derives `nested/packs` and was being
+        // told to pass a directory that does not carry the pack. That is this branch's own defect class
+        // one more time: a message prescribing a remedy it had not checked, in the sentence whose whole
+        // job is to hand back an accurate choice. `there` is already the relative spelling of that root,
+        // and for the conventional layout it is exactly `packs`, so the common output is unchanged.
+        //
+        // The `verify/plugin.sh` clause is gated with it, because that rail pins the literal
+        // `--pack-root packs`: claiming the equivalence for `nested/packs` would replace one false
+        // sentence with another. Raised through the promoted suppressed-note channel, which carries
+        // findings the inline round does not.
+        const rail = there === "packs" ? ", which is what `verify/plugin.sh` checks" : "";
+
+        // **Read and parse are two failures with two repairs**, and one sentence for both misdiagnoses
+        // the commoner one — the defect Copilot raised against `run`'s workspace arm on #229, whose
+        // comment sits one screen below this and which the first cut of this block reintroduced
+        // anyway. A `SyntaxError` from `JSON.parse` carries no `.code`, so a collapsed arm reporting
+        // `error.code ?? error.message` under *could not be read* sends somebody with a malformed
+        // manifest to look at permissions. `readManifest` and `resolverFor` both keep the two apart;
+        // so does this. It also names WHICH of the two copies is the broken one, which the collapsed
+        // form could not — with two manifests in play, "one of the two" is half a diagnosis.
+        const load = (file) => {
+            let text;
+            try {
+                text = fs.readFileSync(file, "utf8");
+            } catch (error) {
+                return { why: `could not be read — ${error.code ?? error.message}` };
+            }
+            try {
+                return { value: JSON.parse(text) };
+            } catch (error) {
+                return { why: `does not parse as JSON — ${error.message}` };
+            }
+        };
+        const here = load(found.manifest);
+        const beneath = load(behind.manifest);
+        const broken = here.why ? { at: found.root, why: here.why } : beneath.why ? { at: there, why: beneath.why } : null;
+        if (broken) {
+            // Could-not-run wearing its own sentence rather than the SHADOWED one: with a manifest
+            // unreadable, *what differs* is unanswerable, and a refusal that guessed would be claiming
+            // to have compared two things it could not read. The remedy is the same either way.
+            return (
+                `the pack \`${found.name}\` resolved under the root ${found.root} while the root ${there} also ` +
+                `carries it, and the copy under ${broken.at} ${broken.why} — so which one this would derive ` +
+                `from could not be established. Name the root: \`--pack-root ${there}\` derives from the tree${rail}, ` +
+                "`--pack-root auto` from the installed copy"
+            );
+        }
+        const mine = here.value;
+        const other = beneath.value;
+
+        // **Containment, computed rather than assumed.** The sharp case — one copy inside the plugin
+        // root and one outside — is what makes `--write` destructive, but it is not a law: a
+        // `--plugin-root` pointing elsewhere puts both outside, and the refusal still stands because
+        // the derived path is relative to whichever root answered. Asserting the sharp case
+        // unconditionally would be this message's first lie, in the sentence that exists to be exact.
+        //
+        // Tested against the ROOTS, which is also what `packPortion` partitions on — `resolvePack`
+        // builds `dir` as `<root>/<category>/<pack>`, so the two can never disagree here, and using the
+        // root keeps this predicate spelled the same way as the derivation it is predicting.
+        const differs = packDifferences(mine, other);
+        const split = escapes(pluginRoot, path.resolve(found.root)) !== escapes(pluginRoot, path.resolve(behind.root));
+        // **Both ROOTS by path — the roots, not the pack directories.** The sibling refusal in
+        // `compile` shipped `dir` while calling it a root, which mislabels the thing it names in a
+        // message whose own claim is to name both; the root is also the half a reader types back into
+        // `--pack-root`. Corrected here in the same stroke rather than left to be found twice.
+        return (
+            `the pack \`${found.name}\` is SHADOWED — it resolved under ${found.root}, a root discovered on this ` +
+            `host, while the root ${there} also carries it. ` +
+            (differs.length
+                ? `They differ by ${differs.join(" and ")}, and which root answers decides the derived set anyway: `
+                : "Their manifests agree, and here that changes nothing: ") +
+            (split
+                ? "the two sit on opposite sides of this plugin root, so one of them derives a `skills` path for " +
+                  "this pack and the other derives none — `--write` would act on whichever answered. "
+                : "the two roots derive different `skills` paths, and `--write` would act on whichever answered. ") +
+            `Refusing to pick: name the root instead — \`--pack-root ${there}\` derives from the tree${rail}, ` +
+            "and `--pack-root auto` from the installed copy"
+        );
+    }
+    return null;
+}
+
 /**
  * A resolver over a workspace's declared pack roots.
  *
@@ -545,8 +680,11 @@ function readManifest(file, pluginRoot) {
  * The runnable surface: the printer CI and an adopter's own pipeline call, plus `--check` and
  * `--write`.
  *
- * `options.manifest` and `options.resolve` are injection points for the suite, the way `init` injects
- * its reader. No production caller passes either; every flag below is the real surface.
+ * `options.manifest`, `options.resolve` and `options.discovery` are injection points for the suite, the
+ * way `init` injects its reader. No production caller passes any of them; every flag below is the real
+ * surface. `discovery` is injected as a THUNK like the production one, because the guarantee that a
+ * branch which cannot use the answer never touches the host is a property of the ARGUMENT — a suite
+ * handed a pre-computed value would be testing a shape production never takes.
  */
 export function run(argv = [], options = {}) {
     const { stdout = process.stdout, stderr = process.stderr } = options;
@@ -623,7 +761,7 @@ export function run(argv = [], options = {}) {
         // caller wiring no thunk stays hermetic on every arm.)_
         const plan = rootPlan(workspaceDir, manifest, {
             named: namedRoots,
-            discovery: () => discoverPackRoots(),
+            discovery: options.discovery ?? (() => discoverPackRoots()),
             forced: wantsDiscovery,
         });
         if (plan.refusal || plan.couldNotRun) {
@@ -631,6 +769,30 @@ export function run(argv = [], options = {}) {
             return 2;
         }
         const roots = plan.roots ?? [];
+        // **Refused here, above the mode branches, so the printer, `--check` and `--write` inherit one
+        // rule** (#317). The damage this prevents is specific to the write path — the tool printed
+        // `run with --write` while `--write` would have stripped a correct, tracked `skills` entry on
+        // the strength of what happens to be installed on the machine — but guarding only `--write`
+        // would leave `--check` exiting 1 about a repository that had not drifted, which is a false
+        // verdict handed to a machine. `compile` settled the same question the same way for #316.
+        //
+        // A caller that injected its own `resolve` never reaches this, and that is deliberate rather
+        // than a hole: it chose its own roots, which is the same election `--pack-root` makes.
+        //
+        // **The `named` half of this condition is defence in depth, and it was measured HERE rather
+        // than inherited from `compile`'s note.** Forcing the whole condition to `true` reds exactly
+        // one case — the `--pack-root auto` exemption — while the named-root case goes on passing: a
+        // named root REPLACES the derived one, so the plan carries no discovered root, `shadowedCopy`
+        // finds nothing behind it, and there is no shadow to refuse. The protection is structural, and
+        // no test in this suite binds the clause. It stays because it states the intent at the site
+        // where a future change to `resolutionRoots` could quietly make it load-bearing.
+        if (!wantsDiscovery && plan.source !== "named") {
+            const shadowed = shadowRefusal({ packs: manifest?.packs, roots, plan, repoRoot, pluginRoot });
+            if (shadowed) {
+                stderr.write(`skills-set: ${shadowed}\n`);
+                return 2;
+            }
+        }
         resolve = resolverFor({ workspaceDir, manifest, roots });
         // The same roots stand in as the owned set when nothing resolves — so a workspace that has
         // stopped composing gets its stale entries cleaned wherever its packs WOULD have been, not

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,14 +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() {
+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: REPO, encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 * 1024 });
+    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 {
@@ -387,9 +503,9 @@ function didWork() {
 }
 
 /** Is there a handoff dated today? The doctrine's checkable form: existence and a date, never length. */
-function handoffToday(stamp) {
+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;
     }
@@ -405,16 +521,19 @@ function handoffToday(stamp) {
  * 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`.
  *
- * **This names the tree rather than rescoping the gate to it, and that is a choice with a cost.**
- * #220 offers rescoping as the alternative and it is the more thorough repair — but the tree a
- * removed worktree wrote to no longer exists to be read, so rescoping cannot answer the very
- * incident that produced the issue. What a reader needed, and did not get, was to see that the
- * sentence was true about a tree they were not thinking of.
+ * **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() {
+function treeIdentity(root = REPO) {
     try {
         const run = (args) => execFileSync("git", args, {
-            cwd: REPO, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"],
+            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
@@ -422,10 +541,10 @@ function treeIdentity() {
         // 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 `${REPO} (detached at \`${run(["rev-parse", "--short", "HEAD"])}\`)`;
-        return `${REPO} (on \`${branch}\`)`;
+        if (branch === "HEAD") return `${root} (detached at \`${run(["rev-parse", "--short", "HEAD"])}\`)`;
+        return `${root} (on \`${branch}\`)`;
     } catch {
-        return REPO;
+        return root;
     }
 }
 
@@ -438,17 +557,20 @@ function treeIdentity() {
  * 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) {
+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(REPO, path.join(WORKSPACE, "handoffs")).split(path.sep).join("/");
+        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: REPO, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
+        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`
@@ -477,7 +599,7 @@ function handoffInHistory(stamp) {
  * 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;
@@ -522,7 +644,14 @@ 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}`,
+            });
         }
     }
 
@@ -533,15 +662,38 @@ function collectProblems() {
     // `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);
+    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()) {
+    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).
-        const elsewhere = handoffInHistory(stamp);
+        //
+        // **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 ` +
@@ -551,7 +703,8 @@ function collectProblems() {
         problems.push({
             reason: "handoff",
             text:
-                `no handoff dated ${stamp} in ${path.join(WORKSPACE, "handoffs")}, read from ${treeIdentity()}. ` +
+                `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}`,
@@ -622,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