amicus 4.3.0 → 4.4.1

package/src/sidecar/tool-part.js

@@ -0,0 +1,196 @@
+// src/sidecar/tool-part.js
+'use strict';
+
+/**
+ * @module sidecar/tool-part
+ * OpenCode's TOOL-PART shape and its status vocabulary (v4.4 B4 part 1).
+ *
+ * WHY THIS EXISTS. The mirror used to model a tool call as an Anthropic-style
+ * `tool_use` part cleared by a matching `tool_result` part carrying
+ * `tool_use_id`. **OpenCode has no such part type.** Established empirically
+ * before designing against it (see tests/sidecar/tool-part-status.test.js for
+ * the full derivation):
+ *
+ *   - 5,129 persisted parts in this machine's OpenCode database resolve to
+ *     exactly six `type` values: text, step-start, reasoning, step-finish,
+ *     tool, patch. No `tool_result`. No `tool_use`.
+ *   - The 35 recorded legs of `council-wsgate01/`..`council-wsgate04/` wrote
+ *     **36 `tool_use` records and ZERO `tool_result` records**. So the
+ *     diagnosis's proposed `pendingToolCalls.length === 0` gate, keyed on a
+ *     `tool_result` that never arrives, would have hung every tool-using leg
+ *     to its full `--timeout`.
+ *
+ * THE REAL SHAPE (@opencode-ai/sdk `ToolPart`):
+ *   `{id, sessionID, messageID, type:'tool', callID, tool:<name>, state}`
+ * where `state` is the `ToolState` union.
+ *
+ * STATUS VOCABULARY:
+ *   - DECLARED by the SDK's `ToolState` union: 'pending' | 'running' |
+ *     'completed' | 'error'.
+ *   - OBSERVED across all 1,307 persisted tool parts: completed 1148,
+ *     error 150, running 9. 'pending' is declared but never persisted — it is
+ *     the pre-execution transient (`{input, raw}`, no `time` at all).
+ *   - TERMINAL is 'completed' | 'error', verified structurally: all 1,298
+ *     terminal parts carry `state.time.end`; all 9 non-terminal parts carry
+ *     `state.time.start` and no `end`. Disjoint and exhaustive.
+ *
+ * The 9 `running` parts are LEFTOVERS — `time_updated` within milliseconds of
+ * `time_created`, all from three killed sessions that never wrote a terminal
+ * status. A stale non-terminal status can therefore persist forever, which is
+ * why any wait keyed on this vocabulary MUST be bounded (headless.js's
+ * TOOL_SETTLE_GRACE_MS).
+ */
+
+/**
+ * The statuses that mean "this tool call is finished and its session is no
+ * longer working on it". Anything else — including an unrecognised or absent
+ * status — is treated as still live: terminality is never INVENTED, it must be
+ * positively observed.
+ * @type {Set<string>}
+ */
+const TERMINAL_TOOL_STATUSES = new Set(['completed', 'error']);
+
+/**
+ * The statuses that POSITIVELY tell us OpenCode is still working on a tool call.
+ *
+ * This is deliberately NOT `!TERMINAL` — the difference is the anti-hang
+ * guarantee. A tool part carrying no `state` at all (the legacy `tool_use`
+ * shape, which the repo's own fixtures still emit) gives us no evidence in
+ * either direction, and deferring a leg's completion on an ABSENCE of evidence
+ * is precisely how a completion gate hangs. So:
+ *
+ *   - `getPendingToolCalls` = not-yet-terminal, INCLUDING unknown shape.
+ *     Feeds B53's wedge detector, whose whole job is the no-evidence case, and
+ *     whose semantics are therefore unchanged.
+ *   - `getLiveToolCalls`    = positively observed 'pending' or 'running'.
+ *     Feeds the v4.4 completion gate: it will only ever hold a leg open on
+ *     evidence that the session really is still working.
+ * @type {Set<string>}
+ */
+const LIVE_TOOL_STATUSES = new Set(['pending', 'running']);
+
+/**
+ * Is this part a tool call at all? Accepts OpenCode's real `'tool'` type and
+ * the legacy `'tool_use'` shape that older fixtures/providers emit.
+ * @param {object} part
+ * @returns {boolean}
+ */
+function isToolPart(part) {
+  return !!part && (part.type === 'tool' || part.type === 'tool_use');
+}
+
+/**
+ * The tool's name. Reads OpenCode's real field (`part.tool`) and falls back to
+ * the legacy `part.name`. The mirror previously read ONLY `part.name`, which
+ * the real shape never has — which is why all 36 recorded tool records carry an
+ * id and nothing else, and why headless.js's `Task`-subagent summary log was
+ * permanently empty.
+ * @param {object} part
+ * @returns {string|undefined}
+ */
+function toolPartName(part) {
+  if (!part) { return undefined; }
+  return part.tool !== undefined ? part.tool : part.name;
+}
+
+/**
+ * The tool's input. Real shape carries it on `state.input`; the legacy shape on
+ * `part.input`.
+ * @param {object} part
+ * @returns {object|undefined}
+ */
+function toolPartInput(part) {
+  if (!part) { return undefined; }
+  if (part.state && part.state.input !== undefined) { return part.state.input; }
+  return part.input;
+}
+
+/**
+ * Has this tool call reached a TERMINAL status? A part with no `state` (the
+ * legacy shape) is NOT settled — unknown status must never read as "finished",
+ * which is what keeps B53's wedge detection working on legacy fixtures.
+ * @param {object} part
+ * @returns {boolean}
+ */
+function isToolPartSettled(part) {
+  const status = toolPartStatus(part);
+  return typeof status === 'string' && TERMINAL_TOOL_STATUSES.has(status);
+}
+
+/**
+ * The observed `state.status`, or undefined when the part carries no state
+ * (legacy shape) — "unknown", which is NOT the same as either terminal or live.
+ * @param {object} part
+ * @returns {string|undefined}
+ */
+function toolPartStatus(part) {
+  const status = part && part.state && part.state.status;
+  return typeof status === 'string' && status !== '' ? status : undefined;
+}
+
+/**
+ * Is this tool call POSITIVELY observed as still executing? See
+ * LIVE_TOOL_STATUSES for why this is not simply `!isToolPartSettled`.
+ * @param {object} part
+ * @returns {boolean}
+ */
+function isToolPartLive(part) {
+  const status = toolPartStatus(part);
+  return status !== undefined && LIVE_TOOL_STATUSES.has(status);
+}
+
+/**
+ * Is this a SUBAGENT (child-session) tool call? OpenCode names it `task`
+ * (lowercase — the pre-existing `t.name === 'Task'` comparison in headless.js
+ * could never match, a second bug on top of the missing `part.tool` read).
+ *
+ * This is the signal for B4: a `task` call spawns a CHILD OpenCode session
+ * whose spend is billed separately and is NOT rolled into the parent session's
+ * cost, so a leg that made one has cost we cannot claim to know. Verified 1:1
+ * on the recorded corpus — exactly 2 `task` calls across 37 sessions, and
+ * exactly 2 child sessions, each parented by the calling leg's session
+ * (wsgate01-s1-2 → $0.021460, wsgate02-s1-3 → $0.471046).
+ * @param {{name?: string}} toolCall a recorded {id,name,input} entry
+ * @returns {boolean}
+ */
+function isSubagentToolCall(toolCall) {
+  const name = toolCall && toolCall.name;
+  return typeof name === 'string' && name.toLowerCase() === 'task';
+}
+
+/**
+ * Tool calls that have NOT reached a terminal `state.status` — as far as we can
+ * observe, OpenCode may still be working on them and the session may still be
+ * billing. INCLUDES the unknown-shape case (no `state` at all). Feeds the
+ * headless poll loop's B53 wedge detector, whose whole purpose is that case.
+ *
+ * v4.4 B4 part 1: this used to clear only on a `tool_result` part carrying
+ * `tool_use_id` — a part type OpenCode never emits (0 of 36 recorded tool
+ * records) — so it never cleared for any real leg. It is now driven by the real
+ * `state.status` vocabulary, with the legacy `tool_result` path kept for
+ * back-compat. Returns a fresh array; `state.pendingToolCalls` is the live
+ * source of truth.
+ * @param {{pendingToolCalls: Map}} state from createMirrorState()
+ * @returns {Array<{id:string,name:string,status:string|undefined,firstSeenAt:string}>}
+ */
+function getPendingToolCalls(state) {
+  return Array.from(state.pendingToolCalls.values());
+}
+
+/**
+ * Tool calls POSITIVELY observed as still executing. A strict SUBSET of
+ * getPendingToolCalls — see LIVE_TOOL_STATUSES for why the difference is the
+ * anti-hang guarantee. This is what the v4.4 completion gate reads.
+ * @param {{pendingToolCalls: Map}} state from createMirrorState()
+ * @returns {Array<{id:string,name:string,status:string,firstSeenAt:string}>}
+ */
+function getLiveToolCalls(state) {
+  return getPendingToolCalls(state)
+    .filter((t) => t.status !== undefined && LIVE_TOOL_STATUSES.has(t.status));
+}
+
+module.exports = {
+  TERMINAL_TOOL_STATUSES, LIVE_TOOL_STATUSES, isToolPart, toolPartName, toolPartInput,
+  toolPartStatus, isToolPartSettled, isToolPartLive, isSubagentToolCall,
+  getPendingToolCalls, getLiveToolCalls,
+};

package/src/sidecar/workspace-window.js

@@ -0,0 +1,62 @@
+/**
+ * Council Workspace launcher (v4.4 §4.3/§4.4) — setup-window.js pattern:
+ * ensureElectron() (the one place provisioning is allowed, #55) → spawn
+ * electron/main.js in council-workspace mode. Unlike setup (which buffers),
+ * this RELAYS child stdout live — the nonced fold block must reach the
+ * launching terminal's command output verbatim. Exit code propagates
+ * (0 on fold-then-close and on plain close).
+ */
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const { logger } = require('../utils/logger');
+const { getElectronPath } = require('./interactive-process');
+const { ensureElectron } = require('./electron-ensure');
+const { generateFoldNonce } = require('../utils/fold-marker');
+
+/**
+ * @param {{project: string, runId?: string}} opts
+ * @param {{ensureElectron?: Function, spawn?: Function, nonce?: string}} [deps] test injection
+ * @returns {Promise<{code: number, error?: string}>}
+ */
+async function launchWorkspaceWindow({ project, runId = '' }, deps = {}) {
+  const ensure = deps.ensureElectron || ensureElectron;
+  const spawnFn = deps.spawn || spawn;
+  const ensured = await ensure();
+  if (!ensured.ok) {
+    return { code: 1, error: ensured.reason || 'Electron not installed' };
+  }
+  return new Promise((resolve) => {
+    const electronPath = ensured.path || getElectronPath();
+    const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
+    const env = {
+      ...process.env,
+      AMICUS_MODE: 'council-workspace',
+      AMICUS_PROJECT: project,
+      AMICUS_RUN_ID: runId || '',
+      AMICUS_FOLD_NONCE: deps.nonce || generateFoldNonce(),
+    };
+    const debugPort = process.env.AMICUS_DEBUG_PORT;
+    const args = debugPort ? [`--remote-debugging-port=${debugPort}`, mainPath] : [mainPath];
+    logger.info('Launching council workspace', { runId: runId || '(run list)', debugPort: debugPort || 'disabled' });
+
+    const proc = spawnFn(electronPath, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+
+    proc.stdout.setEncoding('utf-8');
+    proc.stdout.on('data', (chunk) => { process.stdout.write(chunk); }); // fold relay — live, verbatim
+    proc.stderr.setEncoding('utf-8');
+    proc.stderr.on('data', (chunk) => { logger.debug('Workspace stderr', { data: String(chunk).trim() }); });
+
+    proc.on('error', (err) => {
+      logger.error('Workspace failed to spawn', { error: err.message });
+      resolve({ code: 1, error: `Failed to start workspace: ${err.message}` });
+    });
+    proc.on('close', (code) => {
+      logger.info('Workspace closed', { code });
+      resolve({ code: code === null ? 1 : code });
+    });
+  });
+}
+
+module.exports = { launchWorkspaceWindow };

package/src/spend-query.js

@@ -59,17 +59,33 @@ function rowKey(row, dimension) {
   }
 }
 
-/** Group rows into {key, amount, tokens, runs, sourceMix}, most-expensive first. */
+/**
+ * Group rows into {key, amount, tokens, runs, unpricedRows,
+ * unattributedSubtreeRows, sourceMix}, most-expensive first.
+ *
+ * v4.4: `amount` deliberately stays a plain number — the published
+ * spend.schema.json pins `groups[].amount` to `type: "number"` — so
+ * `unpricedRows` is how a group says "this figure omits N rows we cannot
+ * price". Without it, a group of entirely unpriced rows was indistinguishable
+ * from a group that genuinely cost $0 (diagnosis §8).
+ *
+ * v4.4.1 CA-2: `unattributedSubtreeRows` is the SECOND way a figure can be a
+ * floor, and `unpricedRows` structurally cannot see it — such a row IS priced,
+ * lands in the `r` source bucket, and contributes its own cost to `amount`; what
+ * is missing is the child session it spawned. The two counters are incremented
+ * BESIDE each other, never instead of: a row can be both.
+ */
 function groupRows(rows, dimension) {
   const map = new Map();
   for (const r of rows) {
     const key = rowKey(r, dimension);
-    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
+    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
     const b = map.get(key);
     b.runs += 1;
     addTokens(b.tokens, r.tokens);
     const cost = r.cost || {};
-    if (typeof cost.amount === 'number') { b.amount += cost.amount; }
+    if (typeof cost.amount === 'number') { b.amount += cost.amount; } else { b.unpricedRows += 1; }
+    if (r.subtreeUnknown) { b.unattributedSubtreeRows += 1; }
     const src = (cost.source === 'reported' || cost.source === 'estimated') ? cost.source : 'unknown';
     b.sourceMix[src] += 1;
   }
@@ -87,16 +103,27 @@ function groupRows(rows, dimension) {
  * a row); computeWasted intentionally drops it instead.
  */
 function computeWasted(rows) {
-  const out = { amount: 0, tokens: emptyTokens(), runs: 0, byStatus: {} };
+  const out = { amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, byStatus: {} };
   for (const r of rows) {
     if (r.status === 'complete' || !r.status) { continue; }
     out.runs += 1;
     addTokens(out.tokens, r.tokens);
-    const amt = (r.cost && typeof r.cost.amount === 'number') ? r.cost.amount : 0;
+    // v4.4: null→0 here is arithmetic, not a claim. `unpricedRows` records how
+    // many failed rows we could not price so "wasted $X" is never mistaken for
+    // the whole loss (see groupRows for why `amount` stays a number).
+    // v4.4.1 CA-2: `unattributedSubtreeRows` is the other half of the same
+    // understatement — a failed leg that DID resolve its own cost but left a
+    // child session unpriced. Counted beside `unpricedRows`, never instead of.
+    const priced = r.cost && typeof r.cost.amount === 'number';
+    const amt = priced ? r.cost.amount : 0;
+    if (!priced) { out.unpricedRows += 1; }
+    if (r.subtreeUnknown) { out.unattributedSubtreeRows += 1; }
     out.amount += amt;
-    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0 }; }
+    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0 }; }
     out.byStatus[r.status].amount += amt;
     out.byStatus[r.status].runs += 1;
+    if (!priced) { out.byStatus[r.status].unpricedRows += 1; }
+    if (r.subtreeUnknown) { out.byStatus[r.status].unattributedSubtreeRows += 1; }
   }
   return out;
 }

package/src/utils/env-num.js

@@ -0,0 +1,42 @@
+// src/utils/env-num.js
+'use strict';
+
+/**
+ * @module utils/env-num
+ * Numeric environment override that HONORS an explicit `0`.
+ *
+ * WHY THIS EXISTS. The idiom `Number(process.env.X) || DEFAULT` is wrong for any
+ * knob whose "off" value is `0`, because `0` is falsy and is therefore rewritten
+ * back into `DEFAULT`. v4.4 shipped four such knobs — `AMICUS_USAGE_SETTLE_POLLS`,
+ * `AMICUS_USAGE_SETTLE_INTERVAL_MS`, `AMICUS_USAGE_SETTLE_CALL_TIMEOUT_MS` and
+ * `AMICUS_TOOL_SETTLE_GRACE_MS` — each documenting `0` as the disable switch in
+ * its docblock and (for the last one) in the CHANGELOG, while making that switch
+ * unreachable from the environment. The operator could read the escape hatch and
+ * not use it.
+ *
+ * SEMANTICS. An explicit, finite numeric value always wins, `0` included. Unset,
+ * blank/whitespace-only, and non-finite values fall back to the default:
+ *   - blank matters because `Number('') === 0`, so a bare `export AMICUS_X=` would
+ *     otherwise read as an intentional disable rather than the accident it is;
+ *   - non-finite matters because `Number('Infinity')` would otherwise be fed
+ *     straight into `setTimeout`/comparison arithmetic.
+ *
+ * NOT A BLANKET REPLACEMENT. Several older knobs (`AMICUS_POLL_INTERVAL_MS`,
+ * `AMICUS_STABLE_*_POLLS`, `AMICUS_TOOL_CALL_STALL_MS`, `AMICUS_MAX_SESSIONS`, …)
+ * deliberately keep `||`: `0` is not a documented escape hatch for any of them and
+ * honoring it would busy-loop a poller or silently disable a stall guard. Migrate a
+ * knob to this helper only when `0` is a value its call site actually understands.
+ *
+ * @param {string} name environment variable name
+ * @param {number} dflt value used when unset / blank / non-finite
+ * @param {object} [env] environment object (test seam; defaults to process.env)
+ * @returns {number}
+ */
+function envNumber(name, dflt, env) {
+  const raw = (env || process.env)[name];
+  if (raw === undefined || raw === null || String(raw).trim() === '') { return dflt; }
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+module.exports = { envNumber };

package/src/utils/lifecycle.js

@@ -41,4 +41,40 @@ function armExitWatchdog(code = 0, ms = 1500, deps = {}) {
   return t;
 }
 
-module.exports = { isOneShotCommand, armExitWatchdog, ONE_SHOT_COMMANDS };
+/**
+ * An `exit` hook for armExitWatchdog that REAPS an OpenCode server this process
+ * is using but does not own, on its way out (v4.4.1 fix wave, finding F3).
+ *
+ * The force-exit path is the one place where "not ours to close" stops being the
+ * safe answer. A wave running on an injected server deliberately never closes it
+ * — the owner does, once, in its own finalize. But if the watchdog fires first
+ * the parent dies anyway, and the Go server survives it: an orphan still holding
+ * the OpenCode SQLite lock that the per-run shared server exists to stop
+ * contending on. Before the external-server seam, fanout's own close() covered
+ * this by accident; this restores it deliberately.
+ *
+ * SIGTERM only, and synchronous: process.exit cannot await server.close()'s
+ * escalation, so this sends the one signal that fits in the window and gets out
+ * of the way. Never signals this process, and never lets a dead/absent pid throw
+ * — the exit must happen regardless.
+ *
+ * @param {{goPid?: number|null}|null} server the injected server handle
+ * @param {{kill?: Function, exit?: Function}} [deps] test seams
+ * @returns {(code: number) => void}
+ */
+function exitReaping(server, deps = {}) {
+  return (code) => {
+    // Resolved at CALL time, not creation time: this hook is built the instant a
+    // signal lands and invoked up to 10s later, so binding process.kill/exit
+    // early would freeze whatever was installed at signal time.
+    const kill = deps.kill || ((p, sig) => process.kill(p, sig));
+    const exit = deps.exit || ((c) => process.exit(c));
+    const pid = server && server.goPid;
+    if (pid && pid !== process.pid) {
+      try { kill(pid, 'SIGTERM'); } catch { /* already gone: nothing to reap */ }
+    }
+    exit(code);
+  };
+}
+
+module.exports = { isOneShotCommand, armExitWatchdog, exitReaping, ONE_SHOT_COMMANDS };

package/src/utils/path-fence.js

@@ -0,0 +1,120 @@
+/**
+ * Shared realpath-containment fence.
+ *
+ * Single source of truth for "is this resolved path inside that resolved
+ * directory" — the primitive that defeats symlink escapes AND tampered/stale
+ * pointer files (a `council-<id>.json` pointer's `runDir` is validated only
+ * for truthiness by src/council/run-state.js's readPointer, so nothing
+ * upstream of this check guarantees it stays inside the project).
+ *
+ * It is a LEAF: `fs` + `path` at load time and nothing else, no require cycle
+ * possible. (SEC-3's debug-mode diagnostic requires src/utils/logger.js lazily,
+ * inside the flag branch — logger.js has zero requires of its own, so even that
+ * cannot introduce a cycle, and nothing is loaded at all with the flag unset.)
+ * That was first needed inside the v4.4 workspace layer —
+ * src/workspace/artifact-guard.js requires src/workspace/run-scan.js for
+ * readPointer, so if run-scan.js also required artifact-guard.js for this
+ * helper, the two would require each other and one side's destructured import
+ * would silently resolve to undefined depending on load order.
+ *
+ * It lives in src/utils/ rather than src/workspace/ because its consumers are
+ * no longer all workspace modules: the shipped v4.3 surfaces
+ * (src/mcp-council-awareness.js behind amicus_status / amicus_abort /
+ * amicus_list, src/cli-handlers-watch.js and src/observe/watch-render.js behind
+ * `amicus watch`) fence the same pointer with the same check. Keeping it under
+ * src/workspace/ would have made three stable shipped surfaces depend on a
+ * feature directory added in v4.4 — the only inverted require in the tree, and
+ * one that would turn any future reorganisation of that layer into a breaking
+ * change for those tools. src/utils/ is the neutral layer src/workspace/
+ * already depends on (formatCost, fold-marker), so the arrow now points one way.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * ⚠️ SEC-3: isRealpathContained is a pure string-prefix comparison, and it is only SOUND
+ * if both arguments were already resolved through realpathSync. Nothing enforced that, so
+ * a caller who forgot got a silently WEAKER check rather than an error — a raw
+ * (unresolved) path containing a symlink can prefix-match a directory it does not
+ * physically live under.
+ *
+ * This is a DIAGNOSTIC, opt-in via `AMICUS_DEBUG_FENCE=1`, and it MUST NEVER THROW: the
+ * fence must never become the failure it exists to prevent. Every step is wrapped, and a
+ * non-existent path is a legitimate argument here (callers fence paths before probing
+ * them), so it is not reported. The logger is required lazily so this module keeps its
+ * `fs` + `path` load-time surface (see the header) for the 99.99% of calls that run with
+ * the flag unset.
+ * @param {string} dir already-stringified dirRealPath
+ * @param {string} target already-stringified targetRealPath
+ */
+function assertResolvedArgs(dir, target) {
+  try {
+    const { logger } = require('./logger');
+    for (const [name, p] of [['dirRealPath', dir], ['targetRealPath', target]]) {
+      if (!path.isAbsolute(p)) {
+        logger.warn('path-fence: argument is not absolute', { arg: name, value: p });
+        continue;
+      }
+      try {
+        if (fs.existsSync(p) && fs.realpathSync(p) !== p) {
+          logger.warn('path-fence: argument is not realpath-resolved', { arg: name, value: p });
+        }
+      } catch { /* unreadable / dangling: not this diagnostic's business */ }
+    }
+  } catch { /* a broken logger must never break the fence */ }
+}
+
+/**
+ * True when `targetRealPath` is exactly `dirRealPath` or a proper descendant
+ * of it. Both arguments MUST already be resolved through realpathSync — this
+ * is a pure string-prefix check.
+ * @param {string} dirRealPath
+ * @param {string} targetRealPath
+ * @returns {boolean}
+ */
+function isRealpathContained(dirRealPath, targetRealPath) {
+  const dir = String(dirRealPath);
+  const target = String(targetRealPath);
+  // SEC-3: debug-mode contract check only — never a gate, never a throw (see above).
+  if (process.env.AMICUS_DEBUG_FENCE === '1') { assertResolvedArgs(dir, target); }
+  if (target === dir) { return true; }
+  // ⚠️ COUNCIL REVIEW R2 (A6): when dirRealPath IS a filesystem root, it already
+  // ends in a separator ('/' on POSIX, 'C:\\' on Windows) — blindly appending
+  // another (the old `dirRealPath + path.sep`) doubles it ('//' / 'C:\\\\'), and
+  // no real path ever starts with that, so containment silently returned false
+  // for every path under a root dirRealPath. Only append the separator when it
+  // isn't already there.
+  const base = dir.endsWith(path.sep) ? dir : dir + path.sep;
+  // The separator-qualified prefix (not a bare `startsWith(dir)`) is what defeats
+  // the sibling-prefix trap: '/foobar' must not be considered inside '/foo'.
+  return target.startsWith(base);
+}
+
+/**
+ * Fail-closed, disk-resolving form of isRealpathContained: resolves BOTH
+ * arguments through realpathSync and applies the same containment test.
+ * Returns false when either side cannot be resolved — a missing directory, a
+ * dangling symlink, a permission error, or a non-string `targetPath` straight
+ * out of a hand-edited pointer file — so an unresolvable path is REFUSED
+ * rather than trusted.
+ *
+ * The v4.4 workspace consumers keep calling isRealpathContained directly
+ * because each has to tell "unreadable" apart from "escapes" in the error row
+ * it renders. The v4.3 CLI/MCP consumers (src/mcp-council-awareness.js,
+ * src/cli-handlers-watch.js, src/observe/watch-render.js) collapse every
+ * failure into one outcome — no payload / skip the row / kind 'unknown' — so
+ * they take this boolean form instead of repeating the two try/catch blocks at
+ * four more call sites.
+ * @param {string} dirPath
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+function containsOnDisk(dirPath, targetPath) {
+  try {
+    return isRealpathContained(fs.realpathSync(dirPath), fs.realpathSync(targetPath));
+  } catch { return false; }
+}
+
+module.exports = { isRealpathContained, containsOnDisk };