amicus 4.6.2 → 4.7.0

package/src/mcp-tools.js

@@ -121,6 +121,7 @@ function getTools() {
           'left: flush against the left edge. center: centered.'
         ),
       pack: z.string().optional().describe('Policy pack name or path — bench/chair/options/template defaults for this run; explicit params override pack values (recorded either way).'),
+      tag: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/, '1-64 chars, letters/digits/_/- only').optional().describe('Label this session for list/search/spend grouping'),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -211,10 +212,14 @@ function getTools() {
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     description:
       'List all Amicus sessions for the current project. Shows task ID, ' +
-      'model, status, age, and briefing excerpt.',
+      'model, status, tag, createdAt, and briefing excerpt. Use `search` to ' +
+      'filter by id/tag/briefing substring.',
     inputSchema: {
-      status: z.enum(['all', 'running', 'complete']).optional().describe(
-        'Filter by status. Default: show all.'
+      status: z.string().optional().describe(
+        "Filter by status ('all', 'running', 'complete', 'error', 'aborted', …). Default: show all."
+      ),
+      search: z.string().optional().describe(
+        'Case-insensitive substring filter over id, tag, and briefing material (F8 D15).'
       ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
@@ -336,7 +341,7 @@ function getTools() {
         'Routing preference: auto (direct-first, default), direct (require a ' +
         'direct provider key), or openrouter (force OpenRouter).'
       ),
-      prompt: z.string().describe(
+      prompt: z.string().min(1, 'prompt must not be empty').describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
       ),
       agent: z.enum(['Plan', 'Build']).optional().describe(
@@ -345,7 +350,7 @@ function getTools() {
       thinking: z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']).optional().describe(
         'Reasoning effort for every leg. Default: medium.'
       ),
-      timeout: z.number().optional().describe(
+      timeout: z.number().positive('timeout must be a positive number of minutes').optional().describe(
         'Per-leg timeout in minutes (wall-clock ≈ slowest leg). Default: 15.'
       ),
       summaryLength: z.enum(['brief', 'normal', 'verbose']).optional().describe(
@@ -369,6 +374,7 @@ function getTools() {
         'commands are NOT accepted over MCP.'
       ),
       pack: z.string().optional().describe('Policy pack name or path — bench/chair/options/template defaults for this run; explicit params override pack values (recorded either way).'),
+      tag: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/, '1-64 chars, letters/digits/_/- only').optional().describe('Label this session for list/search/spend grouping'),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -509,6 +515,7 @@ function getTools() {
         'commands are NOT accepted over MCP.'
       ),
       pack: z.string().optional().describe('Policy pack name or path — bench/chair/options/template defaults for this run; explicit params override pack values (recorded either way).'),
+      tag: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/, '1-64 chars, letters/digits/_/- only').optional().describe('Label this session for list/search/spend grouping'),
       ui: z.boolean().optional().describe(
         'Auto-open the Council Workspace window on this run. Default: opens when the client is ' +
         'Claude Code (local), Electron is installed, a display exists, and config workspace.autoOpen is ' +

package/src/pack/pack-cli.js

@@ -30,7 +30,7 @@ function applyPackOrExit(args, expectedKind, useJson) {
   if (args.pack === undefined) { return null; }
   const explicit = args.__explicit || new Set();
   const pr = applyPackToArgs({ packRef: args.pack, expectedKind, args, explicit, useJson });
-  if (pr.error) { process.exit(failJson(useJson, pr.error)); }
+  if (pr.error) { return process.exit(failJson(useJson, pr.error)); }
   for (const n of pr.notices) { process.stderr.write(n + '\n'); }
   return pr.packRecord;
 }

package/src/pack/pack-forward.js

@@ -36,10 +36,18 @@
  *    render, so template provenance (`promptMeta.template`) is still
  *    recorded exactly as Wave 1 built it.
  *
- * Callers that only need the pre-spend validation (the two spawn paths)
- * ignore the returned `renderedPrompt`; amicus_start's in-process path
- * (which never spawns a child, so nothing else would render it) reuses it
- * as the actual prompt instead of rendering a second time.
+ * `renderedPrompt` has two different consumers now (W1-M4, v4.7 PR7):
+ * amicus_start's in-process path (which never spawns a child, so nothing
+ * else would render it) reuses it as the actual prompt instead of rendering
+ * a second time; amicus_fanout's spawn path writes it to the wave's
+ * on-disk `briefing.md` — the `--search` corpus (src/sidecar/list-search.js)
+ * — instead of the raw prompt, so a wave whose spawned child aborts before
+ * its own render (src/sidecar/fanout.js) stays findable by the text the
+ * user actually sees. The spawned child itself still gets the RAW prompt
+ * (via a sibling `briefing-input.md`), so its own later render remains the
+ * provenance source for `promptMeta.template`. amicus_start's
+ * spawn-fallback path is the one remaining caller that still only needs the
+ * pre-spend validation and ignores `renderedPrompt`.
  */
 
 const { ERROR_CODES } = require('../utils/error-doc');

package/src/pack/pack-resolve.js

@@ -54,6 +54,9 @@ function resolveBenchKnob(pack, args, explicit) {
     else if (Array.isArray(bench)) { args.models = bench.join(','); }
     return null;
   }
+  // Both-typed names --models here, but every consuming surface — fanout (cli-handlers-fanout.js:77),
+  // council run (cli-council-run-bench.js:45), MCP (mcp-council-bench.js:29) — rejects
+  // --models+--council with BAD_ARGS after pack apply, so a both-typed notice is never actionable.
   const flag = modelsExplicit ? '--models' : '--council';
   return `Notice: ${flag} overrides the bench from pack '${pack.name}'`;
 }

package/src/pack/pack-store.js

@@ -52,7 +52,21 @@ function resolvePackRef(ref) {
 
 function stripBom(text) { return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text; }
 
-/** @returns {{pack, path, source:'dir'|'path', hash}|{error}} */
+/**
+ * @returns {{pack, path, source:'dir'|'path', hash}|{error}}
+ * All SIX `{error}` returns below — malformed name, name-form unreadable,
+ * path-form unreadable, invalid JSON, non-object body, name/filename mismatch —
+ * are mapped to PACK_NOT_FOUND by both callers (pack-resolve.js:76,
+ * cli-handlers-pack.js:225). A new `{error}` added here inherits that code
+ * silently: re-code it deliberately or it lands as "not found".
+ * PACK_NOT_FOUND has a THIRD emit site that never calls readPack — `pack rm`
+ * (cli-handlers-pack.js:242, via rmPack) — unified there by the v4.5 HOLD-gate
+ * decision 3 and pinned by the "rm nonexistent pack -> PACK_NOT_FOUND" describe
+ * in tests/pack/cli-pack-cmd.test.js.
+ * PACK_INVALID is NOT readPack's: it belongs to validatePack
+ * (pack-resolve.js:94, cli-handlers-pack.js:199) and to prepareForward's
+ * maxCost guard (pack-forward.js:68-76), which is not a validatePack call.
+ */
 function readPack(ref) {
   const r = resolvePackRef(ref);
   if (r.error) { return r; }
@@ -66,8 +80,11 @@ function readPack(ref) {
   let pack;
   try { pack = JSON.parse(raw); }
   catch (err) { return { error: `Error: pack ${file} is not valid JSON: ${err.message}` }; }
-  if (r.kind === 'name' && pack && pack.name !== r.name) {
-    return { error: `Error: pack file ${file} declares name '${pack && pack.name}' which does not match its filename — rename one of them` };
+  if (pack === null || typeof pack !== 'object' || Array.isArray(pack)) {
+    return { error: `Error: pack ${file} is not a pack object (found ${pack === null ? 'null' : Array.isArray(pack) ? 'an array' : typeof pack})` };
+  }
+  if (r.kind === 'name' && pack.name !== r.name) {
+    return { error: `Error: pack file ${file} declares name '${pack.name}' which does not match its filename — rename one of them` };
   }
   return { pack, path: file, source: r.kind === 'name' ? 'dir' : 'path', hash: canonicalHash(pack) };
 }

package/src/pack/pack-validate.js

@@ -74,6 +74,11 @@ function validatePack(pack, { mode } = { mode: 'run' }) {
     if (typeof pack.model !== 'string' || !pack.model.trim()) { errors.push('solo pack requires model'); }
     else if (!seatOk(pack.model)) { errors.push(`unresolvable model '${pack.model}'`); }
   } else {
+    // T11-d: bench-independent — a by-name bench used to skip this entirely, so a pack
+    // could carry both and only fail (mis-attributed) at handler time.
+    if (pack.kind === 'council' && pack.critic && pack.lenses) {
+      errors.push('critic and lenses are mutually exclusive');
+    }
     const bench = pack.bench;
     if (typeof bench === 'string') {
       const { members } = getCouncilWithSource(bench, []);
@@ -87,7 +92,6 @@ function validatePack(pack, { mode } = { mode: 'run' }) {
       if (pack.kind === 'council') {
         if (pack.chair && bench.includes(pack.chair)) { errors.push(`chair '${pack.chair}' is a bench seat — the chair must not review`); }
         if (pack.critic && !bench.includes(pack.critic)) { errors.push(`critic '${pack.critic}' must be one of the bench seats`); }
-        if (pack.critic && pack.lenses) { errors.push('critic and lenses are mutually exclusive'); }
         if (Array.isArray(pack.lenses) && pack.lenses.length !== bench.length) {
           errors.push(`lenses needs exactly one lens per seat (${bench.length} seats, got ${pack.lenses.length})`);
         }

package/src/session-manager.js

@@ -22,6 +22,9 @@ const SESSION_STATUS = {
 /** Canonical session dir name — new sessions are written here. */
 const SESSIONS_DIR = 'amicus_sessions';
 
+/** Subagent sessions nest one level under their parent taskId dir. */
+const SUBAGENTS_DIR = 'subagents';
+
 /**
  * Get the canonical session directory path for a task (used for WRITES).
  * Spec Reference: §8.1 Session directory structure
@@ -256,7 +259,7 @@ function saveSummary(projectDir, taskId, summary) {
  * // Returns: '/path/to/project/.claude/amicus_sessions/abc123/subagents/subagent-xyz'
  */
 function getSubagentDir(projectDir, parentTaskId, subagentId) {
-  return path.join(getSessionDir(projectDir, parentTaskId), 'subagents', subagentId);
+  return path.join(getSessionDir(projectDir, parentTaskId), SUBAGENTS_DIR, subagentId);
 }
 
 /**
@@ -355,7 +358,7 @@ function getSubagentSession(projectDir, parentTaskId, subagentId) {
  * @returns {object[]} Array of sub-agent metadata
  */
 function listSubagents(projectDir, parentTaskId, filter = {}) {
-  const subagentsDir = path.join(getSessionDir(projectDir, parentTaskId), 'subagents');
+  const subagentsDir = path.join(getSessionDir(projectDir, parentTaskId), SUBAGENTS_DIR);
 
   if (!fs.existsSync(subagentsDir)) {
     return [];
@@ -412,6 +415,7 @@ module.exports = {
   getSessionDir,
   resolveExistingSessionDir,
   SESSIONS_DIR,
+  SUBAGENTS_DIR,
   SESSION_STATUS,
   // Sub-agent functions
   getSubagentDir,

package/src/sidecar/budget.js

@@ -63,20 +63,54 @@ function checkBudget(legs, opts = {}) {
   return { ok, offending, overCeiling, breakdown: { legs: breakdownLegs, totalEstCost, unpricedCount, maxCostPerMtok: cap, maxCost: opts.maxCost || null } };
 }
 
-/** Human-readable refusal text (also used as the error envelope `hint`). */
-function formatBudgetError(result) {
+/**
+ * Human-readable refusal text (also used as the error envelope `hint`).
+ * @param {object} result checkBudget's return value
+ * @param {{kind:'cli'|'mcp'}} [surface] where the text will be read. Remedies are
+ *   surface-specific: the MCP tool surface has no --flags, and (since v4.7 PR6's
+ *   gate hoist) no per-call override at all. Defaults to 'cli' so the two CLI
+ *   callers stay byte-identical.
+ */
+function formatBudgetError(result, surface = { kind: 'cli' }) {
   const lines = [];
+  const isMcp = surface && surface.kind === 'mcp';
   if (result.offending.length > 0) {
     lines.push('Budget gate: model(s) over the per-$/Mtok threshold:');
     for (const o of result.offending) { lines.push(`  - ${o.modelInput} (${o.model}): ${o.reason}`); }
   }
   if (result.overCeiling) {
-    lines.push(`Budget gate: estimated total $${result.breakdown.totalEstCost.toFixed(4)} exceeds --max-cost $${result.breakdown.maxCost.toFixed(4)} (estimate, not guaranteed).`);
+    // On MCP the ceiling can come from EITHER a pack's `maxCost` option or the
+    // config, and the pack wins (mcp-server.js's fwd.maxCost ?? cfg.maxCost).
+    // Naming only one of them would send the caller to edit the loser — the very
+    // "remedy that cannot work" class this surface split exists to end.
+    lines.push(`Budget gate: estimated total $${result.breakdown.totalEstCost.toFixed(4)} exceeds ${isMcp ? 'the effective maxCost' : '--max-cost'} $${result.breakdown.maxCost.toFixed(4)} (estimate, not guaranteed).`);
   }
   if (result.breakdown.unpricedCount > 0) {
     lines.push(`(${result.breakdown.unpricedCount} unpriced leg(s) — direct provider; cost unknown, not included in the estimate.)`);
   }
-  lines.push('Override: --max-cost <$> to raise the ceiling, or --no-cost-gate to disable both guards (e.g. an intentional o3 run).');
+  // offending and overCeiling are independent (unrelated inputs — see module
+  // header), and either or both may have fired since formatBudgetError is only
+  // called when !ok. Only name a remedy that actually clears every branch that
+  // fired; when both fired, raising just one lever will not clear the run.
+  const hasOffending = result.offending.length > 0;
+  const hasCeiling = result.overCeiling;
+  if (isMcp) {
+    if (hasOffending && hasCeiling) {
+      lines.push("Override: raise maxCostPerMtok in the amicus config AND the effective maxCost (the pack's `maxCost` option if this run used a pack, otherwise the config's), or choose a cheaper model — raising just one will not clear this run.");
+    } else if (hasOffending) {
+      lines.push('Override: raise maxCostPerMtok in the amicus config, or choose a cheaper model.');
+    } else {
+      lines.push("Override: raise the effective maxCost — the pack's `maxCost` option if this run used a pack, otherwise the config's — or choose a cheaper model.");
+    }
+  } else {
+    if (hasOffending && hasCeiling) {
+      lines.push('Override: --no-cost-gate to disable both guards (e.g. an intentional o3 run) — raising just one of maxCostPerMtok or --max-cost will not clear this run.');
+    } else if (hasOffending) {
+      lines.push('Override: --no-cost-gate to disable both guards (e.g. an intentional o3 run), or raise maxCostPerMtok in config.');
+    } else {
+      lines.push('Override: --max-cost <$> to raise the ceiling, or --no-cost-gate to disable both guards (e.g. an intentional o3 run).');
+    }
+  }
   return lines.join('\n');
 }
 

package/src/sidecar/fanout-budget.js

@@ -61,8 +61,7 @@ function preflightBudget(okLegs, options) {
       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.',
+        + 'The run continues with the waves that did launch.',
     };
   }
   return { ok: true, estimate };

package/src/sidecar/fanout-leg-fallback.js

@@ -18,9 +18,12 @@ const { deriveChain } = require('./fallback-chains');
 
 /**
  * Append ONE attributed ledger row for a single attempt (spec 6.2/7.1). At
- * `attempt:0` this is byte-identical to today's pre-fallback appendSpend row
- * (same fields, sourced from `leg.attempt`/`leg.substitutedFor`/
- * `leg.retryOfWaveId`, all undefined -> omitted for a plain leg). A
+ * `attempt:0` this row's LINKAGE fields (attempt/substitutedFor/retryOfWaveId,
+ * all undefined -> omitted for a plain leg) are byte-identical to today's
+ * pre-fallback appendSpend row. v4.7 F8 D16 adds `tag` — a NULLABLE dim, not a
+ * linkage field, so every row now carries it (null-default when the leg was
+ * never tagged) rather than omitting it; the byte-identity claim above applies
+ * only to the linkage-field convention, not to the full row shape. A
  * substitution (`attempt` param > 0, the LOOP's attempt index) overrides
  * `row.attempt`/`row.substitutedFor` with the substitution's own values.
  * Best-effort — never throws, never affects the leg. `deps.spendDir` (tests)
@@ -42,6 +45,7 @@ function recordAttemptSpend({ doc, leg, currentModel, legId, waveId, project, at
       councilRunId: leg && leg.councilRunId, councilName: leg && leg.councilName,
       project, attempt: leg && leg.attempt, substitutedFor: leg && leg.substitutedFor,
       retryOfWaveId: leg && leg.retryOfWaveId,
+      tag: (leg && leg.tag) || null,
     };
     if (attempt > 0) { row.attempt = attempt; row.substitutedFor = originalModel; }
     appendSpend(row, deps.spendDir ? { dir: deps.spendDir } : undefined);

package/src/sidecar/fanout-wave-io.js

@@ -72,4 +72,16 @@ async function finishWave({ wave, waveDir, waveId, project, exitCode, completedA
   return { wave, exitCode };
 }
 
-module.exports = { writeWaveMetadata, writeWaveDoc, finishWave };
+/**
+ * v4.3 §7.2 (moved here v4.7 PR3 Task 1): stamp council attribution onto every
+ * leg — fanout-leg's appendSpend reads it; no-op for every non-council caller.
+ * v4.7 F8 (Task 7) adds tag stamping in the same pass.
+ */
+function stampLegAttribution(legs, options) {
+  if (options.councilRunId || options.councilName) {
+    legs.forEach(l => { l.councilRunId = options.councilRunId; l.councilName = options.councilName; });
+  }
+  if (options.tag) { legs.forEach(l => { l.tag = options.tag; }); }
+}
+
+module.exports = { writeWaveMetadata, writeWaveDoc, finishWave, stampLegAttribution };

package/src/sidecar/fanout.js

@@ -19,7 +19,7 @@ const { ERROR_CODES } = require('../utils/error-doc');
 // Wave-document persistence lives in ./fanout-wave-io (size-gate split, v4.4.1
 // Task 0.5). writeWaveMetadata is re-exported below — fanout-retry.js and the
 // fanout tests import it from here.
-const { writeWaveMetadata, writeWaveDoc, finishWave } = require('./fanout-wave-io');
+const { writeWaveMetadata, writeWaveDoc, finishWave, stampLegAttribution } = require('./fanout-wave-io');
 
 /**
  * Derive leg task IDs: <waveId>-1 .. <waveId>-N (matches TASK_ID_PATTERN).
@@ -86,7 +86,11 @@ async function runFanout(options) {
   // `reason` in metadata.json, no wave.json, and stage1 recorded 'complete'.
   // waveDir is optional (only the post-creation caller has one).
   const errorWave = (waveId, message, waveDir) => {
-    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, pack: options.pack, createdAt, completedAt: new Date().toISOString(), status: 'error' });
+    // v4.7 F8 (D13, T3 review): tag: options.tag || metaTag, TDZ-safe (sole call site runs after `const metaTag` below).
+    // v4.7 PR3 rider: pack got the same `|| metaPack` inherit the other two
+    // buildWaveResult sites have — it was the lone holdout, so an MCP-spawned
+    // wave whose server died dropped its pre-seeded pack while keeping its tag.
+    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, pack: options.pack || metaPack, tag: options.tag || metaTag, createdAt, completedAt: new Date().toISOString(), status: 'error' });
     doc.error = message;
     doc.reason = message; // classifier alias, same as fanout-leg.js's run docs
     // best-effort: an unwritable wave dir must not mask the real error
@@ -119,11 +123,7 @@ async function runFanout(options) {
   });
   if (validated.error) { return failPre(validated.code || 'BAD_ARGS', validated.error); }
   const legs = validated.legs;
-  // v4.3 §7.2: stamp council attribution onto every leg (fanout-leg.js's
-  // existing appendSpend reads it); no-op for every non-council caller.
-  if (options.councilRunId || options.councilName) {
-    legs.forEach(l => { l.councilRunId = options.councilRunId; l.councilName = options.councilName; });
-  }
+  stampLegAttribution(legs, options);
   const okLegs = legs.filter(l => l.ok);
   // FIX 2 (#61 whole-branch review): a leg's migration notice has no CLI
   // stderr to land on — surface it on the wave doc instead, deduped in case
@@ -149,6 +149,7 @@ async function runFanout(options) {
     briefing: String(options.prompt).slice(0, 200),
     promptMeta: options.promptMeta || null,
     ...(options.pack ? { pack: options.pack } : {}), // v4.5 Task 13: absent-not-null.
+    ...(options.tag ? { tag: options.tag } : {}), // v4.7 F8 (D13): absent-not-null, same idiom as pack above.
     pid: process.pid, project, createdAt,
   });
   // v4.5 final-review F2: an MCP-spawned child never gets --pack (single-
@@ -161,6 +162,7 @@ async function runFanout(options) {
   // result-schema-rebuild.js:93, which reads meta.pack off a metadata.json
   // it loaded for an unrelated reason).
   const metaPack = waveMeta.pack;
+  const metaTag = waveMeta.tag; // v4.7 F8 (D13): same pre-seed inherit mechanism as metaPack above.
   emitWaveStarted(waveDir, waveId, legs.map(l => (l.ok ? l.model : l.modelInput)), legIds, follow);
 
   // 2b. All legs failed to route (#61 perf): no leg will ever touch the
@@ -171,7 +173,7 @@ async function runFanout(options) {
     const legDocs = legs.map((leg, i) => buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }));
     const completedAt = new Date().toISOString();
     const wave = buildWaveResult({
-      waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, createdAt, completedAt, notices,
+      waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, tag: options.tag || metaTag, createdAt, completedAt, notices,
     });
     return finishWave({ wave, waveDir, waveId, project, completedAt, follow, emit,
       exitCode: waveExitCode(wave.status),
@@ -282,7 +284,7 @@ async function runFanout(options) {
   const completedAt = new Date().toISOString();
   const signalled = waveAbort.signal();
   const wave = buildWaveResult({
-    waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, createdAt, completedAt,
+    waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, tag: options.tag || metaTag, createdAt, completedAt,
     status: signalled ? 'aborted' : null, notices,
   });
   const exitCode = signalled

package/src/sidecar/list-limit.js

@@ -0,0 +1,50 @@
+/**
+ * @module sidecar/list-limit
+ * The `--limit` core behind `amicus list` (v4.7 PR3 rider).
+ * Split out of read.js on the same relief-extraction rule that produced
+ * list-search.js (T6 review) — read.js was at 293/300 with this inline.
+ * Re-exported from src/sidecar/read.js; nothing outside it needs this file.
+ *
+ * WHY --limit EXISTS. D14 made `--all` real (cross-project via the advisory
+ * sessions-index) with no output cap. Measured on the dev machine at merge
+ * time: 21,145 rows in 8.3s. An unbounded dump is not a listing.
+ */
+
+'use strict';
+
+/**
+ * Normalize `--limit` into a row cap.
+ *
+ * Absent → 0 (unlimited), which keeps an un-limited `list` byte-identical to
+ * its pre-rider output. `0` is also the explicit "no cap" spelling, so a
+ * scripted caller can opt out without omitting the flag.
+ *
+ * @param {number|string|boolean|undefined|null} limit
+ * @returns {number} 0 for unlimited, else a positive integer
+ * @throws {Error} on a valueless, non-integer, or negative value — silently
+ *   listing everything after a typo'd `--limit` is exactly the
+ *   accepted-but-ignored failure src/utils/known-flags.js exists to prevent.
+ */
+function normalizeLimit(limit) {
+  // parseArgs sets `true` for a valueless flag; mirrors models.js:279-281.
+  if (limit === true) { throw new Error('--limit requires a value'); }
+  if (limit === undefined || limit === null || limit === '') { return 0; }
+  const n = Number(limit);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(`--limit must be a non-negative integer (got "${limit}"); 0 means unlimited`);
+  }
+  return n;
+}
+
+/**
+ * The no-silent-caps notice. Names the real total and how to see it all.
+ *
+ * @param {number} cap the applied limit
+ * @param {number} total row count BEFORE slicing
+ * @returns {string}
+ */
+function truncationNotice(cap, total) {
+  return `Showing ${cap} of ${total} sessions (--limit ${cap}). Use --limit 0 for all.`;
+}
+
+module.exports = { normalizeLimit, truncationNotice };

package/src/sidecar/list-search.js

@@ -0,0 +1,69 @@
+/**
+ * @module sidecar/list-search
+ * The `--search` core behind both list surfaces (F8 D15, errata E-PR3-5).
+ * Split out of read.js (T6 review) to keep that file under its line budget.
+ * Re-exported from src/sidecar/read.js, which is what both consumers
+ * (mcp-server.js's amicus_list, the CLI's listSidecars) and the tests already
+ * require — nothing outside read.js needs to know this file exists.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeSessionDir } = require('../utils/validators');
+
+const COUNCIL_MATERIAL_SEPARATOR = '--- MATERIAL / BRIEFING ---';
+
+// Council row search material (MCP-only): runDir/briefing.md when readable
+// (MCP-launched runs write one before the engine spawns), else the portion of
+// briefing-stage1.md after the separator (CLI-launched runs have only this),
+// else null. Re-derives runDir from the pointer and re-fences it with
+// containsOnDisk exactly as mcp-council-awareness.js:214 — never a bare join.
+function councilSearchMaterial(project, runId) {
+  if (!project) { return null; }
+  const { readPointer } = require('../council/run-state');
+  const { containsOnDisk } = require('../utils/path-fence');
+  const ptr = readPointer(project, runId);
+  if (!ptr || !containsOnDisk(project, ptr.runDir)) { return null; }
+  try { return fs.readFileSync(path.join(ptr.runDir, 'briefing.md'), 'utf-8'); } catch { /* try stage1 */ }
+  try {
+    const s1 = fs.readFileSync(path.join(ptr.runDir, 'briefing-stage1.md'), 'utf-8');
+    const idx = s1.indexOf(COUNCIL_MATERIAL_SEPARATOR);
+    return idx === -1 ? null : s1.slice(idx + COUNCIL_MATERIAL_SEPARATOR.length);
+  } catch { return null; }
+}
+
+// Wave material: waveDir/briefing.md (full prompt) when readable, else the
+// 200-char excerpt already on the row (fanout.js:146). safeSessionDir (not a
+// bare path.join) so this gets the same traversal guard every other session
+// path read in the codebase gets.
+function waveSearchMaterial(project, waveId, excerpt) {
+  try { return fs.readFileSync(path.join(safeSessionDir(project, waveId), 'briefing.md'), 'utf-8'); }
+  catch { return String(excerpt || ''); }
+}
+
+// LEG rows (parentWave set) are id/tag ONLY — briefing embeds the parent's material; matching it would hit every leg N+1 times per wave.
+function rowMatchesSearch(row, needle, project) {
+  if (String(row.id || '').toLowerCase().includes(needle)) { return true; }
+  if (String(row.tag || '').toLowerCase().includes(needle)) { return true; }
+  if (row.parentWave) { return false; }
+  // --all rows are stamped with their OWN project (enumerateAllProjects,
+  // read.js) — a cross-project wave/council row's material lives under THAT
+  // project, not the caller's cwd. Using the wrong one doesn't throw; it
+  // silently falls back to the low-fidelity excerpt/id-tag match instead of
+  // the full text, which is worse than a crash because nothing signals it.
+  const proj = row.project || project;
+  const material = row.type === 'council-run' ? councilSearchMaterial(proj, row.id)
+    : row.type === 'wave' ? waveSearchMaterial(proj, row.id, row.briefing) : row.briefing;
+  return String(material || '').toLowerCase().includes(needle);
+}
+
+// Case-insensitive substring filter behind both list surfaces (CLI `amicus list
+// --search`, MCP `amicus_list {search}` — F8 D15, errata E-PR3-5), mirroring
+// the models.js:70-73 idiom. Missing material never throws — it degrades to
+// an id/tag-only match (read.js:58 idiom).
+function searchSessions(rows, q, ctx) {
+  const needle = String(q).toLowerCase();
+  return rows.filter(row => rowMatchesSearch(row, needle, ctx && ctx.project));
+}
+
+module.exports = { searchSessions };