amicus 4.3.0 → 4.4.0

package/src/sidecar/fanout-budget.js

@@ -0,0 +1,71 @@
+// src/sidecar/fanout-budget.js
+'use strict';
+
+/**
+ * @module sidecar/fanout-budget
+ * runFanout's pre-flight spend gate (§1b), extracted from src/sidecar/fanout.js —
+ * which sits three lines under the 300-line size gate and had no room for the
+ * v4.4 reservation seam. Behaviour of the extracted half is unchanged; the
+ * reservation is the only addition.
+ *
+ * WHY THE RESERVATION EXISTS (v4.4 cost-council finding 1). `checkBudget`
+ * compares the wave's pre-flight ESTIMATE against a `maxCost` NUMBER that the
+ * caller read at some earlier moment. The council driver launches Stage-1's seat
+ * wave and critic wave concurrently under a single `Promise.all`, and each
+ * launcher read `remainingBudget()` before EITHER wave's legs had been recorded
+ * — so both observed the full, unreduced allowance and both could pass a ceiling
+ * that only one of them fits under. The read is not the claim.
+ *
+ * `options.reserveBudget(estimate) -> boolean` closes that: it is a SYNCHRONOUS
+ * read-and-claim against the allowance not already claimed by a sibling wave
+ * that is mid-launch. Being synchronous is the whole guarantee — the event loop
+ * cannot interleave two callers inside it, so the second caller necessarily sees
+ * the first caller's claim. See src/council/run-budget.js for the ledger.
+ *
+ * It is OPT-IN: every non-council caller (the `amicus fanout` CLI, `amicus run`)
+ * omits it and gets the byte-identical pre-v4.4 gate.
+ */
+
+/**
+ * @param {Array<{modelInput,model,pricing}>} okLegs legs that actually routed
+ * @param {object} options runFanout options (maxCost, maxCostPerMtok, noCostGate,
+ *   promptMeta/prompt, and the optional `reserveBudget` claim function)
+ * @returns {{ok:true, estimate?:number}|{ok:false, message:string, hint:string}}
+ */
+function preflightBudget(okLegs, options) {
+  // `--no-cost-gate` is a WHOLE-RUN opt-out of BOTH guards (an intentional
+  // o3-class council), so it must also skip the reservation — otherwise the
+  // council would still serialize its allowance for a ceiling it has disowned.
+  if (options.noCostGate) { return { ok: true }; }
+
+  const { checkBudget, formatBudgetError } = require('./budget');
+  const { loadConfig } = require('../utils/config');
+  const cfg = loadConfig() || {};
+  const maxCostPerMtok = options.maxCostPerMtok !== undefined ? options.maxCostPerMtok : cfg.maxCostPerMtok;
+  const promptChars = (options.promptMeta && options.promptMeta.chars)
+    || (options.prompt ? options.prompt.length : 0);
+  const maxCost = options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost;
+
+  const budget = checkBudget(okLegs, { maxCostPerMtok, maxCost, promptChars });
+  if (!budget.ok) {
+    return { ok: false, message: 'Error: budget gate refused the wave', hint: formatBudgetError(budget) };
+  }
+
+  // Claim AFTER the hard per-$/Mtok threshold has passed: a wave that is going
+  // to be refused for an over-priced model must not consume allowance on its
+  // way out and starve a sibling that would have fit.
+  const estimate = budget.breakdown.totalEstCost;
+  if (typeof options.reserveBudget === 'function' && !options.reserveBudget(estimate)) {
+    return {
+      ok: false,
+      message: 'Error: budget gate refused the wave',
+      hint: `Budget gate: estimated total $${estimate.toFixed(4)} does not fit the --max-cost `
+        + 'allowance still unclaimed by concurrently launching waves (estimate, not guaranteed).\n'
+        + 'The run continues with the waves that did launch. Override: --max-cost <$> to raise the '
+        + 'ceiling, or --no-cost-gate to disable both guards.',
+    };
+  }
+  return { ok: true, estimate };
+}
+
+module.exports = { preflightBudget };

package/src/sidecar/fanout-leg.js

@@ -132,7 +132,25 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
   const status = legStatusFromResult(result);
   const summary = result.summary || null;
   const { resolveUsage } = require('../utils/pricing');
-  const usage = result && result.usage ? resolveUsage({ model: leg.model, usageTotals: result.usage }) : null;
+  // v4.4 Task 2 (B4) + v4.4.1 CA-1: a leg that made a SUBAGENT (`task`) call has
+  // spend in a child OpenCode session that is billed separately and is NOT
+  // rolled into the parent session's cost. runHeadless now WALKS those sessions
+  // (src/sidecar/child-sessions.js), so `subtreeUnknown` narrows from "this leg
+  // called `task`, therefore assume the worst" to what it should always have
+  // meant: the walk could not account for the subtree.
+  //
+  // The walk is authoritative when it ran — including in the direction that
+  // CLEARS the flag, which the name-string proxy could never do (backlog CA-5:
+  // a tool merely NAMED `task` that spawns nothing used to make an exact run
+  // report itself inexact). The proxy survives only as the fallback for a leg
+  // where the walk could not run at all.
+  const walked = result && result.subtree;
+  const subtreeUnknown = walked
+    ? !!walked.unknown
+    : !!(result && result.subagentToolCalls > 0);
+  const usage = result && result.usage
+    ? resolveUsage({ model: leg.model, usageTotals: result.usage, subtreeUnknown, subtree: walked || undefined })
+    : null;
   // If setup threw before the session dir existed, there is nothing on disk to
   // finalize — still resolve to an error run document so the wave aggregates.
   const legPatch = {
@@ -140,6 +158,10 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
     reason: result.error || undefined,
     completedAt: new Date().toISOString(),
     usage: usage || undefined,
+    // v4.4 B4 part 1: the leg completed with tool calls still live, so its
+    // OpenCode session may have kept working (and billing) afterwards. Travels
+    // with the leg so it is readable long after the run's stderr is gone.
+    toolSettleTimedOut: (result && result.toolSettleTimedOut) || undefined,
   };
   let finalMeta = legPatch;
   if (legDir) {

package/src/sidecar/fanout.js

@@ -132,17 +132,10 @@ async function runFanout(options) {
 
   // 1b. Budget gate (pre-creation; refuse before spending). Only legs that
   // will actually run cost anything — a leg that never routed never spends.
-  if (!options.noCostGate) {
-    const { checkBudget, formatBudgetError } = require('./budget');
-    const { loadConfig } = require('../utils/config');
-    const cfg = loadConfig() || {};
-    const maxCostPerMtok = options.maxCostPerMtok !== undefined ? options.maxCostPerMtok : cfg.maxCostPerMtok;
-    const promptChars = (options.promptMeta && options.promptMeta.chars) || (options.prompt ? options.prompt.length : 0);
-    const budget = checkBudget(okLegs, { maxCostPerMtok, maxCost: options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost, promptChars });
-    if (!budget.ok) {
-      return failPre(ERROR_CODES.BUDGET_EXCEEDED, 'Error: budget gate refused the wave', formatBudgetError(budget));
-    }
-  }
+  // Lives in ./fanout-budget so the v4.4 concurrency reservation seam has room;
+  // that module's docblock carries the why.
+  const preflight = require('./fanout-budget').preflightBudget(okLegs, options);
+  if (!preflight.ok) { return failPre(ERROR_CODES.BUDGET_EXCEEDED, preflight.message, preflight.hint); }
 
   // 2. Wave record
   const waveId = options.waveId || generateTaskId();

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,26 @@ function rowKey(row, dimension) {
   }
 }
 
-/** Group rows into {key, amount, tokens, runs, sourceMix}, most-expensive first. */
+/**
+ * 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, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
+    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; }
+    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;
   }
@@ -87,16 +96,22 @@ 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, 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).
+    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 }; }
+    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;
 }

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/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 };