amicus 4.6.3 → 4.7.0

package/src/mcp-server.js

@@ -423,6 +423,10 @@ const handlers = {
     // gate / template pre-render) for parity between the two paths.
     if (packForward.maxCost !== undefined) { args.push('--max-cost', String(packForward.maxCost)); }
     if (packForward.template !== undefined) { args.push('--template', packForward.template); }
+    // v4.7 F8 (D13, errata E-PR3-2): forwarded for the spawn-fallback path
+    // below — DEAD on the shared-server branch (args is never read there);
+    // that branch stamps input.tag directly into its own metadata write instead.
+    if (input.tag) { args.push('--tag', input.tag); }
     args.push('--cwd', cwd);
 
     if (sharedServer.enabled && input.noUi) {
@@ -435,28 +439,30 @@ const handlers = {
         // a fall-through to the spawn-fallback catch must never leak one.
         const inProcessNotices = [...fwd.notices];
         const renderedPrompt = fwd.renderedPrompt !== undefined ? fwd.renderedPrompt : input.prompt;
-        if (packForward.maxCost !== undefined) {
-          // fwd.maxCost is already validated (I2); the ceiling gate itself
-          // stays here (needs resolvedModel/pricing, unavailable to pack-forward.js).
-          const { lookupPricing } = require('./utils/pricing');
-          const { checkBudget, formatBudgetError } = require('./sidecar/budget');
-          const { loadConfig } = require('./utils/config');
-          const cfg = loadConfig() || {};
-          const soloLeg = { modelInput: input.model || resolvedModel, model: resolvedModel, pricing: lookupPricing(resolvedModel) };
-          const budget = checkBudget([soloLeg], {
-            maxCostPerMtok: cfg.maxCostPerMtok, maxCost: fwd.maxCost,
-            promptChars: (renderedPrompt && renderedPrompt.length) || 0,
-          });
-          if (!budget.ok) {
-            const { buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
-            return {
-              isError: true,
-              content: [{ type: 'text', text: JSON.stringify(buildErrorDoc({
-                code: ERROR_CODES.BUDGET_EXCEEDED, message: 'Error: budget gate refused the run',
-                hint: formatBudgetError(budget),
-              })) }],
-            };
-          }
+        // v4.7 PR6: the gate used to hang off `packForward.maxCost !== undefined`,
+        // so a no-pack MCP start skipped it while the CLI (cli-handlers-run.js:90)
+        // gated unconditionally with a cfg.maxCost fallback. Same guard, both doors.
+        // fwd.maxCost is already validated (I2); the ceiling gate itself
+        // stays here (needs resolvedModel/pricing, unavailable to pack-forward.js).
+        const { lookupPricing } = require('./utils/pricing');
+        const { checkBudget, formatBudgetError } = require('./sidecar/budget');
+        const { loadConfig } = require('./utils/config');
+        const cfg = loadConfig() || {};
+        const soloLeg = { modelInput: input.model || resolvedModel, model: resolvedModel, pricing: lookupPricing(resolvedModel) };
+        const budget = checkBudget([soloLeg], {
+          maxCostPerMtok: cfg.maxCostPerMtok,
+          maxCost: fwd.maxCost !== undefined ? fwd.maxCost : cfg.maxCost,
+          promptChars: (renderedPrompt && renderedPrompt.length) || 0,
+        });
+        if (!budget.ok) {
+          const { buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
+          return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(buildErrorDoc({
+              code: ERROR_CODES.BUDGET_EXCEEDED, message: 'Error: budget gate refused the run',
+              hint: formatBudgetError(budget, { kind: 'mcp' }),
+            })) }],
+          };
         }
 
         const { server, client } = await sharedServer.ensureServer();
@@ -500,6 +506,10 @@ const handlers = {
           briefing: renderedPrompt,
           // v4.5 Task 15: additive-only — absent (not null) without a pack.
           ...(packRecord ? { pack: packRecord } : {}),
+          // v4.7 F8 (D13, errata E-PR3-2): THE critical site — this shared-server
+          // branch never spawns a CLI child, so the --tag argv forward above
+          // (dead here) can never reach it. Same additive-only idiom as pack.
+          ...(input.tag ? { tag: input.tag } : {}),
         }, null, 2), { mode: 0o600 });
 
         // Build context from parent conversation (unless --no-context)
@@ -693,6 +703,19 @@ const handlers = {
     // resolved the route in-process above, so surface its notice here.
     const spawnContent = [{ type: 'text', text: body }];
     if (routeResult.notice) { spawnContent.push({ type: 'text', text: routeResult.notice }); }
+    // W1-M6/M7: NOT dead code. This is the same idiom applyPackToMcpInput's
+    // orphan-knob notices always use — amicus_fanout genuinely reaches it today
+    // (FANOUT_PACK_PARAM_MAP has no contextTurns/contextMaxTokens destination;
+    // the fanout handler's own push into waveContent below is covered by
+    // mcp-pack-params.test.js's "notice wording (decision 1b)" test — named,
+    // not line-numbered, because a line citation goes stale the moment anything
+    // is inserted above it, including by its own commit). On THIS solo surface it is
+    // unreachable only while KIND_OPTIONS.solo stays fully covered by
+    // SOLO_PACK_PARAM_MAP destinations + pack-resolve.js's FORWARDABLE_ARG_KEYS
+    // — the invariant tests/pack/mcp-pack-params.test.js guards (the
+    // KIND_OPTIONS.solo round-trip test, mutation-proven against a synthetic
+    // orphaned knob). If that invariant ever breaks, this loop is what turns a
+    // silent drop into a visible notice — never delete it as unreachable.
     for (const n of packNotices) { spawnContent.push({ type: 'text', text: n }); }
     if (isHeadless) {
       spawnContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
@@ -984,37 +1007,11 @@ const handlers = {
     const root = path.join(cwd, '.claude', SESSIONS_DIR);
     if (!fs.existsSync(root)) { return textResult('No amicus sessions found.'); }
 
+    // v4.7 F8 (D14): one enumeration behind both the CLI and MCP list surfaces
+    // — enumerateSessions is the shared core (src/sidecar/read.js).
+    const { enumerateSessions, searchSessions } = require('./sidecar/read');
     const byId = new Map();
-    for (const d of fs.readdirSync(root)) {
-      if (!/^[a-zA-Z0-9_-]{1,64}$/.test(d)) { continue; }
-      if (byId.has(d)) { continue; }
-      const metaPath = path.join(root, d, 'metadata.json');
-      if (!fs.existsSync(metaPath)) { continue; }
-      try {
-        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-        const entry = {
-          id: d, model: meta.model, status: meta.status, agent: meta.agent,
-          briefing: sanitizePreview(String(meta.briefing || ''), 80),
-          createdAt: meta.createdAt,
-          mode: meta.mode
-            || (meta.headless === undefined ? undefined : (meta.headless ? 'headless' : 'interactive')),
-        };
-        // Live-progress enrichment for RUNNING sessions only — readProgress
-        // parses conversation.jsonl, so terminal rows stay cheap.
-        if (meta.status === 'running') {
-          try {
-            const p = readProgress(path.join(root, d));
-            entry.phase = deriveStage(meta.status, p.stage);
-            entry.messageCount = p.messages;
-            entry.lastActivityAt = p.lastActivityAt;
-            entry.latestPreview = p.latestPreview;
-          } catch { /* progress optional */ }
-        }
-        byId.set(d, entry);
-      } catch {
-        // Skip unreadable metadata
-      }
-    }
+    for (const row of enumerateSessions(cwd, {})) { byId.set(row.id, row); }
 
     // v4.0 §8: council runs are pointer files in the same sessions root — merge
     // them as first-class rows (type 'council-run') before sorting/filtering.
@@ -1025,8 +1022,34 @@ const handlers = {
     if (input.status && input.status !== 'all') {
       sessions = sessions.filter(s => s.status === input.status);
     }
+    // v4.7 F8 (D15, errata E-PR3-5): search runs on RAW briefing material —
+    // BEFORE the sanitize/enrich pass below truncates row.briefing to an
+    // 80-char preview. Council rows' material is read straight off disk
+    // inside searchSessions; the `briefing` merged onto them here is already
+    // listCouncilRuns' own sanitized preview and is never used for matching.
+    if (input.search) { sessions = searchSessions(sessions, input.search, { project: cwd }); }
     if (sessions.length === 0) { return textResult('No amicus sessions found.'); }
 
+    // Rows are re-grafted here with the EXACT decorations this handler always
+    // applied: sanitized (not raw) briefing, and running-only live-progress
+    // enrichment. Council rows already carry a sanitized briefing from
+    // listCouncilRuns, so they're left alone.
+    for (const row of sessions) {
+      if (row.type === 'council-run') { continue; }
+      row.briefing = sanitizePreview(String(row.briefing || ''), 80);
+      // Live-progress enrichment for RUNNING sessions only — readProgress
+      // parses conversation.jsonl, so terminal rows stay cheap.
+      if (row.status === 'running') {
+        try {
+          const p = readProgress(path.join(root, row.id));
+          row.phase = deriveStage(row.status, p.stage);
+          row.messageCount = p.messages;
+          row.lastActivityAt = p.lastActivityAt;
+          row.latestPreview = p.latestPreview;
+        } catch { /* progress optional */ }
+      }
+    }
+
     return textResult(JSON.stringify(sessions, null, 2));
   },
 
@@ -1237,6 +1260,17 @@ const handlers = {
     if (fwd.error) { return textResult(fwd.error.message + (fwd.error.hint ? `\n${fwd.error.hint}` : ''), true); }
     packNotices.push(...fwd.notices);
 
+    // ⚠️ v4.7 PR7: the zod schema closes the TYPED door; a pack can push the same values through
+    // the other one (validatePack checks option KEY names, never value types). Both entrances
+    // reach the same spawn, so the check lives here, after pack merge, before any wave dir.
+    if (typeof input.prompt !== 'string' || !input.prompt.trim()) {
+      return textResult('Error: prompt must not be empty.', true);
+    }
+    if (input.timeout !== undefined
+        && (typeof input.timeout !== 'number' || !Number.isFinite(input.timeout) || input.timeout <= 0)) {
+      return textResult('Error: timeout must be a positive number of minutes.', true);
+    }
+
     // Resolve a single effective models list (council OR models), validated
     // BEFORE any wave dir / metadata is written so a bad request never strands
     // a pid-less 'running' orphan wave.
@@ -1270,15 +1304,34 @@ const handlers = {
     const waveDir = getSessionDir(cwd, waveId);
 
     let briefingPath;
+    let childPromptPath;
     try {
       fs.mkdirSync(waveDir, { recursive: true, mode: 0o700 });
       briefingPath = path.join(waveDir, 'briefing.md');
+      // ⚠️ W1-M4 (v4.7 PR7): this default is LOAD-BEARING. Omit it and every non-template wave
+      // spawns with `--prompt-file undefined`.
+      childPromptPath = briefingPath;
       // The prompt goes via file: the spawned command line must NOT carry it,
       // or it re-hits the ~32KB Windows argument cap (F4 spec §4.2).
-      fs.writeFileSync(briefingPath, input.prompt, { mode: 0o600 });
+      // ⚠️ W1-M4: briefing.md is the SEARCH CORPUS — src/sidecar/list-search.js reads it verbatim
+      // — and a child that aborts before fanout.js:145 never re-renders it, leaving the wave
+      // permanently unfindable by the text the user actually sees. Write the RENDERED text here
+      // (parity with the amicus_start path at :441/:506) and hand the child the raw input in a
+      // sibling file, so its own later re-render still produces byte-identical output and
+      // promptMeta.template provenance survives.
+      const briefingText = fwd.renderedPrompt !== undefined ? fwd.renderedPrompt : input.prompt;
+      fs.writeFileSync(briefingPath, briefingText, { mode: 0o600 });
+      if (fwd.renderedPrompt !== undefined) {
+        childPromptPath = path.join(waveDir, 'briefing-input.md');
+        fs.writeFileSync(childPromptPath, input.prompt, { mode: 0o600 });
+      }
+      // ⚠️ W1-M4 rider (owner-approved fold): the `briefing` key below must stay — without it the
+      // `list` BRIEFING column renders EMPTY for an aborted MCP wave, since only fanout.js:147
+      // ever wrote a briefing key and an aborted child never reaches it.
       writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify({
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
         models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
+        briefing: briefingText.slice(0, 200),
         // v4.5 Task 15: additive-only — absent (not null) without a pack.
         ...(packRecord ? { pack: packRecord } : {}),
       }, null, 2), { mode: 0o600 });
@@ -1292,7 +1345,7 @@ const handlers = {
 
     const args = [
       'fanout', '--models', effectiveModels.join(','),
-      '--prompt-file', briefingPath, '--wave-id', waveId,
+      '--prompt-file', childPromptPath, '--wave-id', waveId,
       '--json', '--client', detectClient(mcpServer), '--cwd', cwd,
     ];
     const agent = input.agent || 'Build';
@@ -1317,6 +1370,12 @@ const handlers = {
     // itself is never forwarded, only the two knobs it resolved to).
     if (packForward.maxCost !== undefined) { args.push('--max-cost', String(packForward.maxCost)); }
     if (packForward.template !== undefined) { args.push('--template', packForward.template); }
+    // v4.7 F8 (D13, errata E-PR3-2): argv-only forward — unlike pack, this does
+    // NOT pre-seed the wave metadata (no single-resolution rule forces it here);
+    // the spawned CLI child's own cli-handlers-fanout.js stores the tag on wave
+    // metadata itself (Task 3), so fanout.js's metaTag inherit arm has no MCP
+    // producer and is defense-in-depth only.
+    if (input.tag) { args.push('--tag', input.tag); }
 
     let child;
     try { child = spawnSidecarProcess(args, waveDir); } catch (err) {
@@ -1506,4 +1565,5 @@ async function startMcpServer() {
 
 module.exports = {
   handlers, startMcpServer, getProjectDir, resolveProjectDir, getClientRoot,
+  FANOUT_PACK_PARAM_MAP, SOLO_PACK_PARAM_MAP,
 };

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