amicus 4.9.7 → 4.10.0

package/src/council/run-launch.js

@@ -63,12 +63,16 @@ function createLaunchers(deps = {}) {
   const reserveBudget = deps.reserveBudget || null;
   const onBudgetRefusal = deps.onBudgetRefusal || null;
   const sharedServer = deps.sharedServer || null;
+  // Spec 2026-09-11 §4: getters, like sharedServer — run.js builds the launchers
+  // before it has decided the seat policy.
+  const councilAgents = deps.councilAgents || (() => null);
+  const agentOverride = deps.agentOverride || (() => undefined);
 
   /**
    * @param {{models: string[], prompt: string, project: string, waveId: string,
    *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string,
    *   councilRunId?: string, councilName?: string, tag?: string, seats?: Array<object>,
-   *   fallback?: object, catalog?: Array, noOutputBackstopMs?: number}} opts
+   *   fallback?: object, catalog?: Array, noOutputBackstopMs?: number, role?: 'seat', directory?: string}} opts
    *   councilRunId/councilName (v4.3 Task 3, spec §7.2) are additive attribution
    *   ids forwarded verbatim into the runFanout call so it can stamp them onto
    *   every leg. tag (v4.7 F8 D16) rides the same forward — every call site
@@ -83,6 +87,13 @@ function createLaunchers(deps = {}) {
    *   noOutputBackstopMs (Task 5, #129) is opt-in and spread-guarded on
    *   Number.isFinite (0 is a valid disable value); only run-retry.js sets it,
    *   to escalate the window on a Stage-1 retry.
+   *   role (spec 2026-09-11 §4, P2-R11) is the LAUNCH role, not the per-leg
+   *   value run-stages.js's `roleFor()` returns — every stage-1 leg (seat,
+   *   critic, and lens alike) launches with the literal `role: 'seat'` to get
+   *   the tool-capable agent; a caller must pass that literal, never a leg's
+   *   own `seat.role`. It also gates `directory` (see the comment above that
+   *   option below): only a `role: 'seat'` launch may point tool-exec cwd
+   *   anywhere but `opts.project`.
    * @returns {Promise<{wave: object|null, exitCode: number}>}
    */
   async function launchWave(opts) {
@@ -100,6 +111,13 @@ function createLaunchers(deps = {}) {
     // `serverClient` (see the seam comment in fanout.js). Absent → the wave
     // starts and closes its own server, exactly as before.
     const shared = sharedServer ? sharedServer() : null;
+    const agents = councilAgents();
+    // Spec 2026-09-11 §4: stage-1 seats and their retries run as council-seat,
+    // every other role as council-support; an explicit agent (the --agent
+    // escape hatch) wins. Without council agents (non-council DI, older
+    // callers) the pre-§4 default 'Plan' stands.
+    const agent = opts.agent || agentOverride()
+      || (agents ? (opts.role === 'seat' ? 'council-seat' : 'council-support') : 'Plan');
     const { wave, exitCode, errorDoc } = await fanoutFn({
       ...(typeof remaining === 'number' ? { maxCost: remaining } : {}),
       ...(shared ? { serverClient: shared.serverClient, server: shared.server } : {}),
@@ -112,12 +130,13 @@ function createLaunchers(deps = {}) {
       // onto every leg and its spend-ledger row (v4.3 --retry-failed machinery).
       // Spread-guarded so a normal launch's transport call stays byte-identical.
       ...(opts.retryOfWaveId ? { retryOfWaveId: opts.retryOfWaveId } : {}),
+      ...(agents ? { serverAgents: agents } : {}),
       models: opts.models.join(','),
       prompt: opts.prompt,
       promptMeta: { source: 'council-engine', file: null, chars: opts.prompt.length },
       waveId: opts.waveId,
       project: opts.project,
-      agent: opts.agent || 'Plan',
+      agent,
       timeout: opts.timeout,
       summaryLength: 'verbose',
       includeContext: false,
@@ -160,8 +179,18 @@ function createLaunchers(deps = {}) {
       // own session dir (judges' `project` is `<runDir>/_scratch`, so this
       // scopes them there) and strip inherited MCP servers, so a tool-capable
       // judge can't read the de-anonymized review-*.md files or the plaintext
-      // labelMap in run.json sitting in the parent run dir.
-      directory: opts.project,
+      // labelMap in run.json sitting in the parent run dir. Every launch is
+      // scoped to `opts.project` — the ONLY exception is a stage-1 seat launch
+      // (`opts.role === 'seat'`) that also passes `opts.directory`: a later
+      // task uses that to point a local-tools seat at the real project tree
+      // while the run's own metadata stays in `opts.project` (P2-R11 review).
+      // Judge, debate, and chair legs never set `role: 'seat'`, so `_scratch`
+      // isolation cannot be escaped through this option.
+      // Named mutant DIRGATEDROP: dropping the `opts.role === 'seat' &&`
+      // conjunct below lets ANY caller redirect tool-exec cwd via
+      // `opts.directory` — reddens "a non-seat launch ignores opts.directory"
+      // (tests/council/run-launch.test.js).
+      directory: (opts.role === 'seat' && opts.directory) || opts.project,
       noMcp: true,
     });
     // A ceiling refusal returns `wave: null`, which the council driver's

package/src/council/run-retry-launch.js

@@ -15,13 +15,18 @@
 const briefings = require('./briefings');
 const { bindPaddedWave } = require('./stage1-bind');
 
-/** The briefing a retry unit re-issues — same intent-aware dispatchers Stage 1 used (v4.9 W6). */
+/**
+ * The briefing a retry unit re-issues — same intent-aware dispatchers Stage 1
+ * used (v4.9 W6), now also carrying the run's seat-tools line and any --agent
+ * override (spec 2026-09-11 §4, PR 2): a retry is a Stage-1 leg like any
+ * other, so it gets the same `tools`/`agent` a first attempt would have.
+ */
 function briefingFor(o, unit) {
-  if (unit.unit === 'critic') { return briefings.stage1CriticBriefing(o.intent, { briefing: o.briefing, date: o.date }); }
+  if (unit.unit === 'critic') { return briefings.stage1CriticBriefing(o.intent, { briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent }); }
   if (unit.unit === 'lens') {
-    return briefings.stage1LensBriefing(o.intent, { lens: o.lenses[unit.lensIndex - 1], briefing: o.briefing, date: o.date });
+    return briefings.stage1LensBriefing(o.intent, { lens: o.lenses[unit.lensIndex - 1], briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent });
   }
-  return briefings.stage1SeatBriefing(o.intent, { briefing: o.briefing, date: o.date });
+  return briefings.stage1SeatBriefing(o.intent, { briefing: o.briefing, date: o.date, tools: o.seatTools, agent: o.agent });
 }
 
 /**

package/src/council/run-retry.js

@@ -90,6 +90,9 @@ async function retryStage1Losses(ctx, { deadWaves = [], deadLegs = [],
       councilRunId: o.runId, councilName: o.councilName,
       tag: o.tag, // v4.7 F8 D16: rides the same forward as councilRunId/councilName.
       fallback: o.fallback, catalog: o.catalog,
+      // Spec 2026-09-11 §4: a retry relaunches as role 'seat', scoped like Stage 1's own launch.
+      // Named mutant RETRYROLEDROP: dropping this line reddens run-retry.test.js's "seat tools" describe (review r1).
+      role: 'seat', ...(o.seatToolsLocal ? { directory: o.project } : {}),
       waveId: unit.waveId, retryOfWaveId: unit.retryOfWaveId, prompt: briefingFor(o, unit),
       noOutputBackstopMs: escalatedBackstopMs };
     // Dispatch by UNIT TYPE, not model count (spec §4: bench is always a wave —

package/src/council/run-seat-tools-verify.js

@@ -0,0 +1,296 @@
+/**
+ * @module council/run-seat-tools-verify
+ * The engine-rendering tripwire's pure pieces, plus `verificationDirectories`'
+ * one side effect — the best-effort `_scratch` mkdir it documents — split out
+ * of run-seat-tools.js at council #247 round 3 under the 300-line size gate:
+ * which directories to check (`verificationDirectories`, ruling P2-R39), how
+ * to ask the engine what it registered for one of them (`listEngineAgents`),
+ * whether that answer still matches the allowlist an agent was given
+ * (`verifyAgentRendering`, ruling P2-R40/P2-R42's external_directory
+ * exemption), whether the same agent's non-permission surface was left alone
+ * too (`verifyAgentFields`, ruling P2-R53, round 6), and whether a run
+ * directory's placement holds up against a symlinked ancestor
+ * (`resolvePhysicalPath`/`isPhysicallyInside`, ruling P2-R54, round 6).
+ * `listEngineAgents`, `verifyAgentRendering` and `verifyAgentFields` are
+ * re-exported from run-seat-tools.js so every existing importer keeps
+ * working unchanged.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { SEAT_READ_DENY_PATTERNS } = require('./seat-tools');
+const { isPathInside } = require('../project-root-allowlist');
+
+/**
+ * The unique set of directories the post-registration tripwire checks the
+ * engine's OWN rendering against: the run directory, the project tree too
+ * when a local tool is opted in (a seat's own working directory), and —
+ * ruling P2-R39 (A1, round 3) — `_scratch`, where every SUPPORT leg (judges,
+ * debate, chair) actually runs (`project: <runDir>/_scratch`, run-debate-
+ * revote.js / run-stage2.js). Without it, an attacker's opencode.json sitting
+ * ONLY under `_scratch` renders clean at `o.runDir` and would still reach a
+ * support leg unverified. It does not exist yet at verification time —
+ * run-stage2.js creates it again once Stage 2 actually starts — so it is
+ * created here too, best-effort and with the same `0o700` mode, purely so
+ * the engine has a real directory to answer for.
+ * @param {{runDir: string, project?: string, seatToolsLocal?: boolean}} o
+ * @returns {string[]}
+ */
+function verificationDirectories(o) {
+  const scratchDir = path.join(o.runDir, '_scratch');
+  try {
+    fs.mkdirSync(scratchDir, { recursive: true, mode: 0o700 });
+  } catch {
+    // Best-effort: a directory the engine cannot be asked about either
+    // degrades or refuses exactly like any other unreachable directory below.
+  }
+  return [...new Set([o.runDir, scratchDir, ...(o.seatToolsLocal ? [o.project] : [])])];
+}
+
+/**
+ * The council agents the run's engine actually registered, as rendered rule
+ * lists. Mirrors run-server.js :: listEngineToolIds (same `shared.serverClient`
+ * access, null on anything wrong, `logger.debug` on failure). Ruling P2-R33:
+ * what validateSeatToolsAgainstEngine reads back to catch a tree-supplied
+ * opencode.json/.opencode/agent file that widened a council agent (measured
+ * 2026-09-12, probe-council-agents.js's PROBE_TREE_JSON).
+ * @param {{serverClient: object}|null} shared
+ * @param {string} directory
+ * @returns {Promise<Array<{name: string, mode: string, permission: Array}>|null>}
+ */
+async function listEngineAgents(shared, directory) {
+  const client = shared && shared.serverClient;
+  if (!client || !client.app || typeof client.app.agents !== 'function') { return null; }
+  try {
+    const res = await client.app.agents({ query: { directory } });
+    return (res && Array.isArray(res.data)) ? res.data.slice() : null;
+  } catch (err) {
+    const { logger } = require('../utils/logger');
+    logger.debug('Engine agent list unavailable', { error: err.message });
+    return null;
+  }
+}
+
+/**
+ * Ruling P2-R40 (A2/B2, round 3): is this `external_directory` pattern the
+ * engine's OWN tool-output cache rule, not a tree-supplied allow riding after
+ * the wildcard deny? The pinned engine (opencode 1.18.15) appends exactly one
+ * such rule after the agent block — under its own data directory's
+ * `tool-output/` subdirectory; denying it would break tool output
+ * round-trips, so it (and only it, by directory) is exempted from check (b)
+ * below. ANY other specific `external_directory` allow is treated like any
+ * other widened rule.
+ *
+ * Ruling P2-R45 (round 4, B1/C1): narrowed from "anywhere under the data
+ * root" to "under the data root's `tool-output/` subdirectory only" —
+ * measured T6: a tree's `external_directory: {'<dataroot>/secrets/*':
+ * 'allow'}` on council-seat is replaced WHOLESALE by the server's plain
+ * string `external_directory: 'deny'` (no per-key merge happens for this key
+ * on the pinned engine), so the wider exemption was already unreachable in
+ * practice — this narrowing is defense-in-depth against the exemption ever
+ * covering more than the ONE rule it exists for (the data root also holds
+ * the engine's `auth.json`). Named mutant EXEMPTBROAD: reverting to the bare
+ * data-root prefix (dropping the `tool-output` join below) lets a tree's
+ * `<dataroot>/secrets/*` allow read as this exemption again.
+ *
+ * Ruling P2-R42 (round-3 nits): the data directory is resolved the same
+ * XDG-first way as `src/utils/auth-json.js :: authJsonCandidates` and
+ * `src/utils/engine-log.js :: engineLogDirCandidates` (same engine, same
+ * data root) — `$XDG_DATA_HOME/opencode` when `XDG_DATA_HOME` is set, else
+ * `~/.local/share/opencode`. The original version of this check hard-coded
+ * the home form only, so a machine (or sandbox — see
+ * scripts/run-integration-keyless.js, which sets `XDG_DATA_HOME` itself)
+ * with `XDG_DATA_HOME` actually set would render its tool-output allow
+ * somewhere this check did not recognize, misreading a legitimate engine
+ * default as a widened agent. Compared after normalizing both sides to
+ * forward slashes, case-insensitively on win32; the backslash rewrite itself
+ * is win32-only — `\` is a legal filename character on POSIX, so rewriting
+ * it there could fold two DIFFERENT paths into comparing equal.
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function isEngineToolOutputPattern(pattern) {
+  const forSlash = (p) => (process.platform === 'win32' ? String(p).replace(/\\/g, '/') : String(p));
+  const forCompare = (p) => (process.platform === 'win32' ? forSlash(p).toLowerCase() : forSlash(p));
+  const roots = [];
+  if (process.env.XDG_DATA_HOME) { roots.push(path.join(process.env.XDG_DATA_HOME, 'opencode')); }
+  roots.push(path.join(os.homedir(), '.local', 'share', 'opencode'));
+  const cmp = forCompare(pattern);
+  return roots.some((root) => cmp.startsWith(`${forCompare(path.join(root, 'tool-output'))}/`));
+}
+
+/**
+ * Pure tripwire (ruling P2-R33): does an ENGINE-RENDERED rule list for a
+ * council agent behave the way its allowlist says it should? A reviewed
+ * tree's own opencode.json (or .opencode/agent/<name>.md) merges INTO the
+ * server-registered agent by KEY ORDER (measured 2026-09-12 against opencode
+ * 1.18.15): server values win per key, but a TREE-ONLY key keeps the tree's
+ * position — after the tree's own `"*"`, it renders AFTER the server's
+ * `*=deny` and wins under findLast (`council-support: { tools: { "*": true,
+ * "task": true } }` renders `*=deny task=allow …` — task ALLOWED). A tree
+ * that re-lists a GRANTED key (e.g. `read`) can instead move ITS allow
+ * before `*=deny`, silently losing it. Neither shape is visible from what
+ * this run registered — only from what the engine says it rendered.
+ *
+ * Ruling P2-R44 (round 4, C4): order-verified, not merely existence-verified,
+ * for `read`'s three deny patterns. Measured 2026-09-12 (T1): a tree that
+ * re-lists council-seat's `permission.read` sub-keys (e.g. granting
+ * `*.env`/`*.env.*`/`*.envrc`) keeps the TREE's sub-key order in the merged
+ * rendering — the server's VALUES still win (the three patterns still say
+ * `deny`), but they render BEFORE `read[*]=allow` instead of after it, so
+ * under the engine's findLast evaluation `.env`/`.env.*`/`.envrc` are all
+ * ALLOWED even though every rule this tripwire used to check for
+ * (existence, never position) is present. Step 5 below closes that hole by
+ * checking WHERE each deny sits relative to the seat's own read allow, not
+ * merely whether it exists after the wildcard.
+ * @param {Array<{permission: string, pattern: string, action: string}>} rules
+ * @param {string[]} allowlist ids this agent should have allowed (`o.seatTools`
+ *   for council-seat, `[]` for council-support)
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+function verifyAgentRendering(rules, allowlist) {
+  // Ruling P2-R40/P2-R42/P2-R45 narrow this from "every non-'*' external_directory
+  // rule is exempt" to only the engine's OWN tool-output rule
+  // (isEngineToolOutputPattern) — any other specific pattern (a tree's
+  // `/tmp/*`, say) now falls through to the per-rule check below like any
+  // other widened rule.
+  const list = (Array.isArray(rules) ? rules : [])
+    .filter((r) => !(r.permission === 'external_directory' && r.pattern !== '*' && isEngineToolOutputPattern(r.pattern)));
+  let starIndex = -1;
+  list.forEach((r, i) => { if (r.permission === '*' && r.pattern === '*') { starIndex = i; } });
+  if (starIndex < 0 || list[starIndex].action !== 'deny') { return { ok: false, reason: 'no wildcard deny' }; }
+  // Named mutant TRIPWIREBLIND: dropping this loop leaves an extra allow
+  // OUTSIDE the allowlist (support attack: task=allow after *=deny) undetected.
+  // Named mutant GRANTDENYBLIND: dropping the deny branch below (treating
+  // every deny as harmless, as the pre-round-4 loop did) lets a granted tool
+  // be silently re-denied by a non-`.env` pattern after its own allow (e.g.
+  // `grep[*]=allow` then `grep[*]=deny`) — step 4 below still finds the
+  // earlier allow and never notices the later deny.
+  for (let i = starIndex + 1; i < list.length; i++) {
+    const r = list[i];
+    if (r.action === 'deny') {
+      if (allowlist.includes(r.permission) && !(r.permission === 'read' && SEAT_READ_DENY_PATTERNS.includes(r.pattern))) {
+        return { ok: false, reason: `${r.permission}[${r.pattern}]=deny narrows granted tool ${r.permission} after the wildcard deny` };
+      }
+      continue;
+    }
+    if (r.pattern !== '*' || !allowlist.includes(r.permission) || r.action !== 'allow') {
+      return { ok: false, reason: `${r.permission}[${r.pattern}]=${r.action} is allowed after the wildcard deny` };
+    }
+  }
+  for (const id of allowlist) {
+    const granted = list.slice(starIndex + 1).some((r) => r.permission === id && r.pattern === '*' && r.action === 'allow');
+    if (!granted) { return { ok: false, reason: `granted tool ${id} is not allowed after the wildcard deny` }; }
+  }
+  // Named mutant ENVORDERBLIND: dropping this block lets a tree reorder the
+  // seat's read denies BEFORE its read allow (measured 2026-09-12, T1) go
+  // undetected — every check above only asks whether a rule EXISTS after the
+  // wildcard, never in what order, so this function would still return
+  // {ok: true} while `.env`/`.env.*`/`.envrc` render ALLOWED on the engine.
+  if (allowlist.includes('read')) {
+    const after = list.slice(starIndex + 1);
+    let lastAllow = -1;
+    after.forEach((r, i) => { if (r.permission === 'read' && r.pattern === '*' && r.action === 'allow') { lastAllow = i; } });
+    for (const p of SEAT_READ_DENY_PATTERNS) {
+      let lastDeny = -1;
+      after.forEach((r, i) => { if (r.permission === 'read' && r.pattern === p) { lastDeny = i; } });
+      if (lastDeny < 0 || after[lastDeny].action !== 'deny' || lastDeny <= lastAllow) {
+        return { ok: false, reason: `read[${p}]=deny is missing or does not follow the seat's read allow` };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Ruling P2-R53 (council #247 round 6, B1): does a rendered council agent's
+ * NON-permission surface still look like the one this run registered?
+ * `verifyAgentRendering` above only ever checked `permission` — measured
+ * 2026-09-13 (probe-r6.js) that a reviewed tree's opencode.json can ALSO set
+ * a council agent's system prompt, model and sampling (`prompt`, `model`,
+ * `temperature`, `topP`, `options`), its display metadata (`color`), its
+ * step budget (`steps`), whether it is hidden from the UI (`hidden`), a
+ * prompt variant (`variant`), and even its `mode` (`primary` vs `subagent`)
+ * or whether it is a `native` (built-in) agent — all silently, since the
+ * permission list stayed clean. `mode`/`native`/`model` are checked first
+ * (each already fatal on its own — an agent rendered as anything but the
+ * plain, non-native, model-less primary agent seat-tools.js registers is
+ * suspect regardless of what else is set); the remaining fields are checked
+ * in a fixed order so the reason always names the FIRST offender, not
+ * whichever happens to be enumerated last. Named mutant FIELDSBLIND:
+ * returning `{ ok: true }` unconditionally here restores the blind spot —
+ * every check below (and run-seat-tools.js's own call site) go dark at once.
+ * @param {object} agent a rendered council agent, as returned by listEngineAgents
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+function verifyAgentFields(agent) {
+  if (agent.mode !== 'primary') { return { ok: false, reason: `mode is '${agent.mode}', not primary` }; }
+  if (agent.native === true) { return { ok: false, reason: 'native agent' }; }
+  if (agent.model !== undefined && agent.model !== null) { return { ok: false, reason: 'model is set' }; }
+  for (const field of ['prompt', 'temperature', 'topP', 'variant', 'steps', 'hidden', 'color']) {
+    const value = agent[field];
+    if (value !== undefined && value !== null) { return { ok: false, reason: `${field} is set` }; }
+  }
+  if (agent.options && typeof agent.options === 'object') {
+    const key = Object.keys(agent.options)[0];
+    if (key !== undefined) { return { ok: false, reason: `options has ${key}` }; }
+  }
+  return { ok: true };
+}
+
+/**
+ * Ruling P2-R54 (council #247 round 6, C1): `isPathInside`
+ * (project-root-allowlist.js:37) compares canonicalized STRINGS only — no
+ * realpath anywhere in that fence — and a run directory is created with
+ * `fs.mkdirSync(runDir, { recursive: true, mode: 0o700 })`
+ * (run-state.js:79), which follows a symlinked ancestor. So an `--out-dir`
+ * that is (or sits under) a symlink/junction pointing INTO the project
+ * passes the lexical "outside the tree" rule while the run's records land
+ * PHYSICALLY inside the tree a `read` seat runs in (measured 2026-09-13).
+ * Walks up from `p` to the deepest EXISTING ancestor (the run directory
+ * itself usually does not exist yet), resolves THAT ancestor with
+ * `fs.realpathSync.native` (follows symlinks/junctions), then re-appends the
+ * unresolved tail unchanged. Any throw (a root that never resolves, a
+ * permissions error) returns `p` unchanged, so this can only ever be AS
+ * STRICT as comparing the lexical paths, never less.
+ * @param {string} p
+ * @returns {string}
+ */
+function resolvePhysicalPath(p) {
+  try {
+    let current = p;
+    const tail = [];
+    while (!fs.existsSync(current)) {
+      const parent = path.dirname(current);
+      if (parent === current) { return p; } // a root that does not exist either
+      tail.unshift(path.basename(current));
+      current = parent;
+    }
+    const resolved = fs.realpathSync.native(current);
+    return tail.length ? path.join(resolved, ...tail) : resolved;
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * `isPathInside`, but on PHYSICAL paths (ruling P2-R54): closes the symlink
+ * escape `resolvePhysicalPath`'s docblock describes, alongside (never
+ * instead of) the lexical `isPathInside` check — see run-seat-tools.js ::
+ * preflightSeatTools, where both are consulted. Named mutant SYMLINKBLIND:
+ * dropping this conjunct from that placement check restores the escape.
+ * @param {string} child
+ * @param {string} parent
+ * @returns {boolean}
+ */
+function isPhysicallyInside(child, parent) {
+  return isPathInside(resolvePhysicalPath(child), resolvePhysicalPath(parent));
+}
+
+module.exports = {
+  verificationDirectories, listEngineAgents, verifyAgentRendering, verifyAgentFields,
+  resolvePhysicalPath, isPhysicallyInside,
+};