amicus 4.2.1 → 4.4.0

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

@@ -0,0 +1,119 @@
+// src/spend-query.js
+'use strict';
+
+/**
+ * @module spend-query
+ * Pure query/rollup helpers for `amicus spend` (spec §7.3 filters/group-by,
+ * §6.3/resolved Q6 `wasted`). Split out of src/cli-handlers-spend.js (which
+ * re-exports these) to stay under the 300-line size gate — see that file's
+ * module docblock. No I/O, no CLI concerns: everything here is rows-in,
+ * rows/rollup-out and independently testable.
+ */
+
+/**
+ * Valid `--group-by`/`groupBy` dimensions — the SINGLE source of truth shared
+ * by the CLI's validity check (cli-handlers-spend.js), the MCP `amicus_spend`
+ * tool's `groupBy` Zod enum (mcp-tools.js), and rowKey()'s switch below. Do
+ * NOT hand-copy this array elsewhere: a 7th dimension added here must reach
+ * both surfaces automatically, not just the one someone remembered to edit.
+ */
+const GROUP_DIMS = ['model', 'wave', 'council', 'project', 'op', 'day'];
+
+/** Cap on rows returned when a caller opts into raw rows (CLI --rows / MCP rows:true). */
+const ROWS_CAP = 1000;
+
+function emptyTokens() {
+  return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
+function addTokens(into, tokens) {
+  if (!tokens) { return; }
+  for (const k of Object.keys(into)) { into[k] += tokens[k] || 0; }
+}
+
+/** Pure row filter over the additive attribution fields (spec 7.3). */
+function filterRows(rows, f = {}) {
+  const cutoff = (f.since !== undefined && f.since !== null && f.now !== undefined) ? f.now - f.since * 86400000 : null;
+  return rows.filter((r) => {
+    if (f.wave && r.waveId !== f.wave) { return false; }
+    if (f.council && r.councilRunId !== f.council && r.councilName !== f.council) { return false; }
+    if (f.project && r.project !== f.project) { return false; }
+    if (f.model && !String(r.model || '').startsWith(f.model)) { return false; }
+    if (f.op && r.op !== f.op) { return false; }
+    if (f.failed && (r.status === 'complete' || !r.status)) { return false; }
+    if (cutoff !== null) { const t = Date.parse(r.ts); if (!Number.isFinite(t) || t < cutoff) { return false; } }
+    return true;
+  });
+}
+
+/** dimension -> row key. null/absent -> '(unattributed)'. `day` = the ISO date. */
+function rowKey(row, dimension) {
+  switch (dimension) {
+    case 'model': return row.model || '(unattributed)';
+    case 'wave': return row.waveId || '(unattributed)';
+    case 'council': return row.councilRunId || row.councilName || '(unattributed)';
+    case 'project': return row.project || '(unattributed)';
+    case 'op': return row.op || '(unattributed)';
+    case 'day': return typeof row.ts === 'string' ? row.ts.slice(0, 10) : '(unattributed)';
+    default: return '(unattributed)';
+  }
+}
+
+/**
+ * Group rows into {key, amount, tokens, runs, unpricedRows, 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).
+ */
+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, unpricedRows: 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; } else { b.unpricedRows += 1; }
+    const src = (cost.source === 'reported' || cost.source === 'estimated') ? cost.source : 'unknown';
+    b.sourceMix[src] += 1;
+  }
+  return [...map.values()].sort((a, b) => b.amount - a.amount);
+}
+
+/**
+ * Wasted spend = every row with an EXPLICIT non-complete status, bucketed by
+ * status (spec 6.3, resolved Q6). A row with status null/absent (pre-v4.3,
+ * or any row that never reached a terminal status write) is deliberately
+ * EXCLUDED here — not "complete" and not "wasted" — because we cannot know
+ * whether that historical run actually failed; counting it would fabricate
+ * a failure that was never recorded. Contrast with groupRows(), where a null
+ * dimension is a first-class '(unattributed)' bucket (grouping never drops
+ * a row); computeWasted intentionally drops it instead.
+ */
+function computeWasted(rows) {
+  const out = { amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, byStatus: {} };
+  for (const r of rows) {
+    if (r.status === 'complete' || !r.status) { continue; }
+    out.runs += 1;
+    addTokens(out.tokens, r.tokens);
+    // 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).
+    const priced = r.cost && typeof r.cost.amount === 'number';
+    const amt = priced ? r.cost.amount : 0;
+    if (!priced) { out.unpricedRows += 1; }
+    out.amount += amt;
+    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0, unpricedRows: 0 }; }
+    out.byStatus[r.status].amount += amt;
+    out.byStatus[r.status].runs += 1;
+    if (!priced) { out.byStatus[r.status].unpricedRows += 1; }
+  }
+  return out;
+}
+
+module.exports = { filterRows, groupRows, computeWasted, emptyTokens, addTokens, GROUP_DIMS, ROWS_CAP };

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/error-classify.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * @module error-classify
+ * Conservative classification of an OpenCode leg-error string into a trigger
+ * class (spec 6.2). Fallback substitution fires ONLY on capacity signals
+ * (rate-limit|overload). timeout is excluded (resolved Q3: a slow model on a
+ * heavy task is not a capacity signal — --retry-failed covers it); auth /
+ * validation never substitute. Misclassification cost is bounded either way:
+ * one extra cheaper attempt, or status quo.
+ */
+
+const RATE_LIMIT = /429|rate ?limit|too many requests|quota|resource exhausted/i;
+const OVERLOAD = /529|503|overload|capacity|server busy|service unavailable/i;
+const AUTH = /401|403|unauthorized|forbidden|invalid api key|authentication/i;
+const TIMEOUT = /timed? ?out|timeout|deadline exceeded/i;
+
+/** @param {string} message @returns {'rate-limit'|'overload'|'auth'|'timeout'|'other'} */
+function classifyLegError(message) {
+  const m = String(message || '');
+  if (RATE_LIMIT.test(m)) { return 'rate-limit'; }
+  if (OVERLOAD.test(m)) { return 'overload'; }
+  if (AUTH.test(m)) { return 'auth'; }
+  if (TIMEOUT.test(m)) { return 'timeout'; }
+  return 'other';
+}
+
+/** Only capacity signals trigger a cheaper-model substitution. */
+function isRetryable(cls) { return cls === 'rate-limit' || cls === 'overload'; }
+
+module.exports = { classifyLegError, isRetryable };

package/src/utils/model-tiers.js

@@ -117,4 +117,4 @@ function resolveTier(vendor, tier, catalog) {
   return null;
 }
 
-module.exports = { TIERS, resolveTier };
+module.exports = { TIERS, TIER_ORDER, resolveTier };

package/src/utils/path-fence.js

@@ -0,0 +1,82 @@
+/**
+ * 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` and nothing else, no require cycle possible.
+ * 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');
+
+/**
+ * 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);
+  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 };