archgen-mcp 0.1.0 → 0.1.2

package/README.md

@@ -62,6 +62,20 @@ Every tool returns the same envelope:
 Call `archgen_help { topic: "<domain>" }` for the full briefing on any tool —
 including when to call it, every action, and its gotchas.
 
+### Fetching, not dumping
+
+Every tool takes `limit` and `offset` (default 50 items) — the bound is the
+caller's, and a bounded answer always reports what it left behind. Every
+collection narrows to **one item**: `taskId`, `skillId`, `file` + `section`,
+`harness`. Each answer's `meta` carries `available` (what else exists),
+`more` (the call that fetches one item) and `next` (the exact call for the
+next slice).
+
+So the agent fetches what it needs instead of taking the whole set: a
+reference topic is fetched **one section** at a time (`section: '*'` asks for
+the whole topic deliberately), and a capability skill is fetched as its
+**normative rules plus an index** — never as the file three times over.
+
 ### The judgment / output split
 
 The archgen **skill** carries the judgment (policy, rules, when-to-use). This

package/assets/briefs/survey.md

@@ -4,7 +4,7 @@ SCOPE: Read-only exploration, writing ONLY `<slug dir>/codebase-map.md`.
 DELIVERABLE: Write `<slug dir>/codebase-map.md` containing EXACTLY these four non-empty sections:
 ## Structure — Top 2 directory levels with 1-line purpose per folder
 ## Modules — Table: `module | responsibility | key entry points`
-## Conventions — Observed file naming, error handling, and test placement patterns
+## Conventions — Observed file naming, error handling, and where the tests live today (the source roots and the test tree)
 ## Affected — Files/modules impacted by the feature, citing exact evidence paths
 
 NAVIGATION & VERIFICATION

package/assets/briefs/verifier.md

@@ -9,7 +9,8 @@ STEP 2 — AUDIT JUDGMENT & CONTRACT COMPLETENESS:
 - Wave boundaries match true dependencies without artificial serialization.
 - Acceptance criteria are objectively verifiable (runnable command or observable output).
 - Edge-case coverage satisfies the scope class (`SMALL` / `MEDIUM` / `LARGE`).
-- Planned structure and naming obey `references/code-standards.md`.
+- Planned structure and naming obey `references/code-standards.md` — including the separate source and test trees: no test tree inside the source tree, and every task that owns source owns the mirrored test path.
+- The repository does not hide archgen artifacts: no `.gitignore` rule covers `.archgen/`, `.agents/skills/archgen`, `.claude/skills/archgen`, `AGENTS.md` or `CLAUDE.md`.
 - **CONTRACT-COMPLETENESS SWEEP** (evaluate every dimension; mark `N/A` only when the system genuinely lacks that surface):
   1. `functional coverage`: Every requirement maps to a task + objective acceptance check.
   2. `security & data protection`: Authn/authz flows, session/credential lifecycle, CSRF/replay defense, encryption/privacy boundaries, boundary input validation.

package/assets/harness-mcp.json

@@ -320,12 +320,21 @@
     "vscode": {
       "label": "VS Code / Copilot",
       "codegraphTarget": null,
-      "detectHome": [],
+      "detectHome": [
+        ".copilot"
+      ],
       "detectProject": [
         ".vscode",
         ".github/copilot-instructions.md"
       ],
       "configs": {
+        "global": {
+          "path": "mcp-config.json",
+          "home": "copilot",
+          "format": "json",
+          "key": "mcpServers",
+          "entry": "stdio"
+        },
         "project": {
           "path": ".vscode/mcp.json",
           "format": "json",

package/assets/platform-capabilities.json

@@ -414,6 +414,17 @@
             "env"
           ],
           "urlField": "url"
+        },
+        "global": {
+          "path": "~/.copilot/mcp-config.json",
+          "key": "mcpServers",
+          "note": "$COPILOT_HOME replaces this location, and VS Code checks only one of them",
+          "stdioFields": [
+            "command",
+            "args",
+            "env"
+          ],
+          "urlField": "url"
         }
       },
       "mcpCli": "copilot mcp add; palette \"MCP: Add Server\"",

package/assets/references/artifact-templates.md

@@ -62,6 +62,7 @@ Adding or omitting files outside the scaffold output is a right-sizing defect. A
 - **Runnable verification commands:** Repo-root-relative (no `../` or `--plan .`), specifying exact commands, flags, sample sizes, and thresholds.
 - **Restricted YAML subset:** Block mappings, block sequences, and single-line flow collections (`["a/**", "b.ts"]`, `{id: A}`) ONLY. **BANNED:** block scalars (`|` / `>`), duplicate keys, and multi-line flow collections.
 - **Targeted `tasks.yaml` edits:** Apply small, surgical edits or a clean full regeneration—never large multi-region patches.
+- **Both trees declared:** `architecture.yaml` `structure:` lists the source tree AND its sibling test tree, and a task that owns source owns the mirrored test path (`references/code-standards.md` owns the rule).
 
 ## Agent workspace & artifact location — the two-tier rule
 
@@ -79,6 +80,27 @@ Adding or omitting files outside the scaffold output is a right-sizing defect. A
   - Source code (`src/...`) and shipped user/operator documentation (`README.md`, API docs, runbooks).
   - *Durable ADRs:* Promote repo-wide architectural decisions from `.archgen/<slug>/decisions/` to the project's canonical ADR directory (`docs/adr/`). Supersede rather than deleting/renumbering accepted ADRs.
 
+Every path under `.archgen/<slug>/` is committed — the `.agent/` run state included, because it is the audit trail of how the work went (`§artifact-tracking`).
+
+## Artifact tracking — every archgen artifact is committed
+
+The plan of record belongs in the repository and in the history, next to the code it plans: `git log` must show what was decided, when it changed, and what shipped.
+
+**Committed — the whole archgen footprint:**
+- `.archgen/<slug>/` — the plan of record: `tasks.yaml`, `plans/`, `docs/`, `architecture.yaml`, `decisions/`, and the `.agent/` run state.
+- `.agents/skills/archgen/` — the canonical installed skill, one copy for the team.
+- `.claude/skills/archgen` — the harness bridge into that store.
+- `AGENTS.md` and `CLAUDE.md` — the registry hub and its pointer.
+- The project MCP config (`.mcp.json`, `.cursor/mcp.json`, `opencode.json`, `.vscode/mcp.json`, …) — the wiring that gives the team the tools.
+
+**Never committed — machine-local state:** `.codegraph/` (the local symbol index), `.archgen/.runtime/` (the legacy heartbeat), the `.archgen-version` deploy stamp.
+
+**Rules:**
+1. **NEVER gitignore an archgen artifact.** A rule covering `.archgen/`, `.agents/`, `.claude/` or `AGENTS.md` is a defect — remove it.
+2. **Commit the plan before the first wave**, then each wave's artifact state (statuses, notes, decisions, reports, snapshot) with that wave's commits.
+3. **Fix the ignore rule before force-adding** — a forced add hides the rule from the next person; if you must force-add, say so in the completion report.
+4. **Never rewrite published history** to hide an artifact — the plan of record is append-only, like the code it plans.
+
 ## architecture.yaml (LARGE scope)
 
 Generated via `archgen_plan{action:'scaffold', scope:'LARGE'}`. Authoring rules for the four anti-hallucination contract blocks:

package/assets/references/mcp-and-skills.md

@@ -4,6 +4,8 @@
 
 `npx archgen-skill init` (or `install`) automatically wires `archgen-mcp` and CodeGraph into every detected harness. Never configure them manually. If `archgen_*` tools are missing, run `npx archgen-skill init` at the repo root and ask the user to reload the harness (`§platforms/mcp-configuration`).
 
+The install writes into the repository — the skill store, the harness bridge, `AGENTS.md`. Those files are **committed to git** (one copy, shared by the team), never gitignored (`§artifact-templates/artifact-tracking`).
+
 The procedures below govern **external** MCP servers (e.g., `context7`) and capability skills.
 
 ## INSTALL-MCP procedure (approval-gated)
@@ -33,7 +35,7 @@ Capability-skill loading is **MANDATORY** whenever planned work matches a regist
    ```
    This invokes `npx -y skills add <repo> --skill <slug> --agent <agent> --yes --json` to install the single matched skill non-interactively (never a full repo bundle) and verifies the resulting file path.
 4. **INTEGRATE (inline into worker contract):** Call `archgen_tasks{action:'contract', tasksYaml, taskId}`. It automatically extracts the normative rules (`MUST` / `SHOULD` / `NEVER`), file path, and section index from every matched required skill and embeds them directly into the worker prompt so workers cannot overlook them.
-   - To inspect a skill manually, call `archgen_skills{action:'load', skillId}` (full rules + index), `{action:'digest', skillId}` (index only), or `{action:'load', skillId, section}` (single section).
+   - To inspect a skill manually, call `archgen_skills{action:'load', skillId}` (the normative rules + the section index — never the whole file), `{action:'digest', skillId}` (index only), or `{action:'load', skillId, section}` (single section).
 5. **AUDIT:** Every worker completion report MUST include an explicit compliance line:
    - `Skill compliance: followed <skill-slug> (<path/to/SKILL.md>)`
    - `Skill compliance: NOT followed — <reason>`

package/assets/references/platforms.md

@@ -34,10 +34,18 @@ Never hand-edit the `AGENTS.md` registry table (`| Feature | Status | Updated |`
 Query `archgen_setup{action:'harness_info'}` for exact per-platform MCP schemas:
 - **Top-level keys vary:**
   - `mcpServers`: Claude Code, Cursor, Windsurf, Gemini CLI, Antigravity, Kiro, Trae
-  - `servers`: VS Code / GitHub Copilot
+  - `servers`: VS Code (the `.vscode/mcp.json` workspace format)
   - `mcp.servers.<id>`: OpenCode (nested under `mcp.servers`, never flat `mcp.<id>`)
   - `context_servers`: Zed
   - `[mcp_servers.<id>]`: Codex CLI (TOML)
+- **VS Code reads TWO formats.** The VS Code format is `servers` in
+  `.vscode/mcp.json`; the PORTABLE format is `mcpServers` in the Copilot
+  user's `mcp-config.json` — `$COPILOT_HOME/mcp-config.json`, or
+  `~/.copilot/mcp-config.json`. Copilot harness sessions read the portable
+  format directly, and `COPILOT_HOME` REPLACES the default (VS Code checks
+  only one of the two). The global wiring therefore goes to the Copilot home
+  in the portable format, so VS Code stable, VS Code Insiders, the Copilot
+  CLI and every workspace see the same server.
 - **Remote URL keys vary:** `url` vs `serverUrl` vs `httpUrl` (check `harness_info`).
 - **Automated wiring:** Use `archgen_setup{action:'install_mcp', approve:true}` rather than hand-editing config files.
 

package/assets/templates/architecture.yaml

@@ -10,39 +10,33 @@ stack:
   database: postgres
 structure: # planned folder tree defined BEFORE coding
   - path: src/features/<feature>/
-    purpose: feature modules (api, internal, colocated tests)
+    purpose: feature modules (api, internal)
   - path: src/shared/
     purpose: cross-feature utilities; MUST NOT import from features/
   - path: src/config/
     purpose: typed env parsing + constants
+  - path: tests/unit/features/<feature>/
+    purpose: unit tests — the test tree, a SIBLING of src/ that mirrors the source path
 naming_conventions: # referenced by every task step and file_ownership entry
   file_naming: kebab-case files; feature folder matches module name
-  dir_layout: "<module>/{api,internal,tests}; shared utilities in src/shared/ only"
+  dir_layout: "<module>/{api,internal}; shared utilities in src/shared/ only; tests mirror the source path under tests/unit/"
   symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env vars
-  test_placement: colocated <name>.test.ts beside unit under test
-modules:
+  test_placement: tests/unit/<path under the source root>/<the language's test file> — the test tree is a SIBLING of the source tree, never inside it
+modules: # one entry per module; repeat per module
   - name: catalog
     responsibility: product browsing + search
     owns: ["src/features/catalog/**"]
     depends_on_modules: [] # DAG; drives task depends_on edges
     key_interfaces: # ONLY exports other modules may import
       - CatalogApi (src/features/catalog/api/index.ts)
-  - name: checkout
-    responsibility: cart -> payment orchestration
-    owns: ["src/features/checkout/**"]
-    depends_on_modules: [catalog]
-    key_interfaces:
-      - CheckoutApi (src/features/checkout/api/index.ts)
-data_contracts:
-  orders:
+data_contracts: # one block per entity; repeat per entity
+  order:
     storage: postgres table orders (migrations/NNNN_orders.sql)
     fields:
       - { field: id, type: uuid, required: true, notes: pk }
-      - { field: session_id, type: uuid, required: true, notes: fk sessions }
       - { field: total_cents, type: integer, required: true, notes: ">= 0" }
       - { field: status, type: "enum(pending,paid,failed)", required: true }
-      - { field: created_at, type: timestamptz, required: true, notes: db default now() }
-api_contracts:
+api_contracts: # one block per operation; repeat per operation
   payments:
     - endpoint: /api/checkout/pay
       method: POST
@@ -52,7 +46,6 @@ api_contracts:
       error_shape: { code: string, message: string, retryable: boolean }
 environment_matrix: # unparsed vars fail fast at startup in src/config/
   - { var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true }
-  - { var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true }
 decisions: # summary index; full records live in decisions/NNNN-title.md
   - id: D1
     title: Postgres over MongoDB

package/assets/templates/tasks.yaml

@@ -7,7 +7,7 @@ tasks:
   - id: C
     title: Scaffold project skeleton + typed config loader
     depends_on: []
-    file_ownership: ["src/config/**", "package.json"] # full repo-root-relative paths ONLY
+    file_ownership: ["src/config/**", "tests/unit/config/**", "package.json"] # full repo-root-relative paths ONLY
     acceptance:
       - "npm run build exits 0"
       - "config loads from env and fails fast on missing required vars"
@@ -37,7 +37,7 @@ tasks:
     parallel_group: wave-payments
     file_ownership:
       - src/features/checkout/internal/capture.ts      # per naming_conventions.dir_layout
-      - src/features/checkout/internal/capture.test.ts # per naming_conventions.test_placement
+      - tests/unit/features/checkout/internal/capture.test.ts # the mirrored test tree
       - docs/payment-retry.md
     artifacts: ["docs/payment-retry.md"]
     acceptance:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap and harness MCP wiring for coding agents.",
   "license": "MIT",
   "type": "module",

package/src/cli.mjs

@@ -204,7 +204,7 @@ export async function runCli(argv, io = {}) {
       codegraph: codegraph ? { bin: codegraph.bin, version: codegraph.version } : null,
       mcpBinary: status.binary,
       mcpTargets: status.targets,
-      harnesses: detectHarnesses(registry, ctx.projectRoot, ctx.home).map((d) => d.id),
+      harnesses: detectHarnesses(registry, ctx.projectRoot, ctx.home, ctx.env).map((d) => d.id),
     };
     if (opts.json) {
       out(JSON.stringify(report, null, 2));
@@ -225,7 +225,7 @@ export async function runCli(argv, io = {}) {
       err('uninstall-mcp needs --yes (nothing was removed)');
       return 2;
     }
-    const res = uninstallArchgenMcp(ctx.projectRoot, ctx.home);
+    const res = uninstallArchgenMcp(ctx.projectRoot, ctx.home, 'both', ctx.env);
     if (opts.json) out(JSON.stringify(res, null, 2));
     else {
       out(`removed ${res.removed.length} config(s)`);

package/src/core/codegraph-manager.mjs

@@ -263,7 +263,7 @@ export async function manageCodegraph(opts) {
 
   /** Wire the MCP server into every detected harness (native + fallback). */
   const wireHarnesses = async (cli) => {
-    const detected = detectHarnesses(registry, projectRoot, home);
+    const detected = detectHarnesses(registry, projectRoot, home, env);
     const wanted = targets ?? detected.map((d) => d.id);
     const selected = detected.filter((d) => wanted.includes(d.id));
 
@@ -428,7 +428,7 @@ export async function manageCodegraph(opts) {
       report.cli.latest = m ? m[1] : null;
     }
     report.telemetry.state = telemetryState(cli?.bin ?? null);
-    const detected = detectHarnesses(registry, projectRoot, home);
+    const detected = detectHarnesses(registry, projectRoot, home, env);
     report.detected = detected.map((d) => d.id);
     for (const d of detected) {
       for (const cfg of Object.values(d.spec.configs ?? {})) {

package/src/core/doc-navigator.mjs

@@ -32,6 +32,7 @@ import { buildGraph, GraphError } from './graph.mjs';
 import { resolveSlugInput, ScopeError } from './scope.mjs';
 import { parseMarkdown, buildSections, findSection, anchorExists } from './docs.mjs';
 import { cycle, invalidInput, notFound } from './errors.mjs';
+import { artifactSpaceMissing } from './guidance.mjs';
 
 // Overview emits at most this many files (sorted); above it, truncated:true.
 export const OVERVIEW_MAX_FILES = 100;
@@ -71,7 +72,10 @@ export function resolveDocScope(input, projectRoot = null) {
     scoped = resolveSlugInput(input, projectRoot);
   } catch (e) {
     if (e instanceof ScopeError) throw invalidInput(`doc-index: ${e.message}`, { input });
-    throw invalidInput(`cannot read ${input} (missing or not a directory)`, { input });
+    // The artifact space does not exist yet. Say WHY, and what to do: the
+    // scaffold tool returns CONTENT and writes nothing, so the caller has to
+    // write it before any artifact tool can read it.
+    throw artifactSpaceMissing(null, input);
   }
   return {
     slugDir: scoped.root,
@@ -572,16 +576,32 @@ export function docIndex(input, opts = {}) {
   if (mode === 'map') {
     if (!token) throw invalidInput('map mode requires a token', {});
     // Section-level retrieval: WHERE is this token mentioned?
+    //
+    // The sections OVERLAP — a parent section's body contains its children's —
+    // so a naive walk reports the same line once per containing section. The
+    // agent then paid for the same sentence three times to learn one fact.
+    // Every hit is reported ONCE, under the DEEPEST section that contains it.
     const re = new RegExp(wholeWordSource(token));
     const hits = [];
     for (const doc of collectDocs().docs) {
-      for (const section of buildSections(doc)) {
+      const sections = buildSections(doc);
+      const ownerOf = (line) => {
+        let owner = null;
+        for (const s of sections) {
+          if (line < s.line || line > s.endLine) continue;
+          if (owner === null || s.level > owner.level) owner = s;
+        }
+        return owner;
+      };
+      for (const section of sections) {
         const bodyLines = doc.lines.slice(section.line - 1, section.endLine);
         const matching = [];
         for (let i = 0; i < bodyLines.length; i++) {
-          if (re.test(bodyLines[i])) {
-            matching.push({ line: section.line + i, text: bodyLines[i].trim().slice(0, 200) });
-          }
+          if (!re.test(bodyLines[i])) continue;
+          const line = section.line + i;
+          const owner = ownerOf(line);
+          if (!owner || owner.slug !== section.slug) continue; // its deepest owner reports it
+          matching.push({ line, text: bodyLines[i].trim().slice(0, 200) });
         }
         if (!matching.length) continue;
         hits.push({
@@ -597,7 +617,10 @@ export function docIndex(input, opts = {}) {
       }
     }
     hits.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
-    return { mode, data: { ref: token, sections: hits, sectionCount: hits.length } };
+    return {
+      mode,
+      data: { ref: token, sections: hits, sectionCount: hits.length, matchCount: hits.reduce((n, h) => n + h.occurrences, 0) },
+    };
   }
 
   // Overview (scale guard): the deduped inventory is always computed in full

package/src/core/docs.mjs

@@ -129,7 +129,22 @@ export function buildSections(doc) {
   return sections;
 }
 
-/** Resolve a section by slug, title, or tolerant slug variant. */
+/**
+ * Resolve a section by slug, title, tolerant slug variant, or PREFIX.
+ *
+ * The PREFIX form matters: the skill's `§` markers use SHORT names
+ * (`§artifact-templates/plan-depth`) while the headings produce longer
+ * slugs (`plan-depth-by-scope-class`). Every `§` shorthand in the skill is
+ * a prefix of a real slug, so accepting a prefix makes the shorthand the
+ * skill teaches actually RESOLVABLE — an agent can pass exactly what it was
+ * told without a discovery round-trip first.
+ *
+ * A prefix that matches MORE THAN ONE section is refused, never guessed:
+ * two sections sharing a prefix means the caller must use the full slug.
+ *
+ * @param {any} doc
+ * @param {string} ref
+ */
 export function findSection(doc, ref) {
   const sections = buildSections(doc);
   const wanted = String(ref).trim();
@@ -142,7 +157,14 @@ export function findSection(doc, ref) {
   // Case-insensitive + collapsed-hyphen comparison: agents type
   // "FR-Catalog-01" or "fr-catalog-01" for the same heading.
   const lower = wanted.toLowerCase();
-  return sections.find((s) => slugsMatch(s.slug.toLowerCase(), lower)) ?? null;
+  const byLoose = sections.find((s) => slugsMatch(s.slug.toLowerCase(), lower));
+  if (byLoose) return byLoose;
+  // The `§` shorthand: a PREFIX of the slug. Only an UNAMBIGUOUS prefix
+  // resolves — a guess would send the agent to the wrong section.
+  const needle = slugifyHeading(wanted).toLowerCase();
+  if (!needle) return null;
+  const byPrefix = sections.filter((s) => s.slug.toLowerCase().startsWith(needle));
+  return byPrefix.length === 1 ? byPrefix[0] : null;
 }
 
 /** Does `anchor` exist in the target document? */

package/src/core/fs-safety.mjs

@@ -18,7 +18,7 @@
 // skill/scripts/set-status.mjs — the MCP server must not be weaker than the
 // scripts it replaces.
 import { lstatSync, mkdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { conflict, permissionDenied } from './errors.mjs';
 
 /** Canonical refusal message — identical wording to the CLI's. */
@@ -41,20 +41,58 @@ export function assertNotSymlink(absPath) {
   if (st.isSymbolicLink()) throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath });
 }
 
+/**
+ * The REAL path of a path, climbing to the nearest existing ancestor when
+ * the leaf does not exist yet — so a symlinked PARENT is caught too.
+ *
+ * Returns null when the chain cannot be resolved at all (a broken symlink,
+ * or a component that is not a directory).
+ *
+ * @param {string} abs
+ * @returns {string|null}
+ */
+function realPathWithTail(abs) {
+  const tail = [];
+  let probe = resolve(abs);
+  for (;;) {
+    try {
+      const real = realpathSync(probe);
+      return tail.length ? join(real, ...tail) : real;
+    } catch (e) {
+      if (!e || e.code !== 'ENOENT') return null;
+      const parent = dirname(probe);
+      if (parent === probe) return null;
+      tail.unshift(basename(probe));
+      probe = parent;
+    }
+  }
+}
+
 /**
  * Realpath-escape guard: refuse anything that lands outside `rootAbs`.
  *
- * TWO CHECKS, IN ORDER.
+ * TWO COMPARISONS, AND THE PATH IS ALLOWED IF EITHER SAYS IT IS INSIDE.
+ *
+ *   1. LEXICAL — the caller's spelling against the root's spelling.
+ *   2. REAL — where the path actually LANDS against where the root actually
+ *      IS. This is the one that catches a symlinked PARENT redirecting a
+ *      write elsewhere, and it is the only one that can answer the question
+ *      when the two paths are spelled differently.
  *
- *   1. LEXICAL. After normalization, the path must be inside the root. This
- *      always applies — it is the primary guard, and it cannot be skipped
- *      because a path does not exist yet.
- *   2. REAL. The nearest existing ancestor is resolved and must also be
- *      inside the root's real path. This is what catches a symlinked
- *      PARENT directory that would redirect the write elsewhere.
+ * They can disagree, and they DO whenever the root and the path are spelled
+ * differently — which is the NORMAL case on macOS (`/tmp`, `/var`) and for
+ * any symlinked project: `process.cwd()` is the REAL path while the caller
+ * passes the LOGICAL one.
  *
- * The guard does NOT fail open: if the root cannot be resolved, only the
- * lexical check stands, and the lexical check is always applied.
+ * The old guard compared the LEXICAL path against the REAL root and refused
+ * on that mismatch, so a perfectly valid path inside the project was
+ * reported as "outside the project" — and the two names the SAME place. The
+ * real comparison is the one that can actually answer the question, and it
+ * must be allowed to.
+ *
+ * The guard does NOT fail open: if the real comparison cannot be made, the
+ * lexical one stands on its own, and a path outside the root by every
+ * measure we could make is always refused.
  *
  * @param {string} rootAbs
  * @param {string} absPath
@@ -62,43 +100,24 @@ export function assertNotSymlink(absPath) {
 export function assertWithinRoot(rootAbs, absPath) {
   const root = resolve(rootAbs);
   const abs = resolve(absPath);
-  if (abs !== root && !abs.startsWith(root + sep)) {
-    throw permissionDenied(
-      `refusing a path outside the project: ${absPath} is not inside ${rootAbs}`,
-      { path: absPath, root: rootAbs },
-    );
-  }
 
-  let rootReal;
-  try {
-    rootReal = realpathSync(root);
-  } catch {
-    return; // the root itself does not exist yet — the lexical check stands
-  }
-  let probe = abs;
-  for (;;) {
-    let exists = true;
-    try {
-      lstatSync(probe);
-    } catch {
-      exists = false;
-    }
-    if (exists) {
-      let real;
-      try {
-        real = realpathSync(probe);
-      } catch {
-        return; // broken chain: nothing writable through it
-      }
-      if (real !== rootReal && !real.startsWith(rootReal + sep)) {
-        throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath, root: rootAbs });
-      }
-      return;
-    }
-    const parent = dirname(probe);
-    if (parent === probe) return;
-    probe = parent;
+  const rootReal = realPathWithTail(root);
+  const pathReal = realPathWithTail(abs);
+
+  const lexicalInside = abs === root || abs.startsWith(root + sep);
+  const realInside =
+    rootReal && pathReal ? pathReal === rootReal || pathReal.startsWith(rootReal + sep) : null;
+
+  if (realInside === true || (realInside === null && lexicalInside)) return;
+
+  if (lexicalInside) {
+    // Lexically inside, but it lands somewhere else: a symlinked parent.
+    throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath, root: rootAbs });
   }
+  throw permissionDenied(
+    `refusing a path outside the project: ${absPath} is not inside ${rootAbs}`,
+    { path: absPath, root: rootAbs },
+  );
 }
 
 /**