amicus 4.6.3 → 4.7.0

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

package/src/sidecar/read.js

@@ -10,6 +10,11 @@ const path = require('path');
 const { safeSessionDir, TASK_ID_PATTERN } = require('../utils/validators');
 const { SESSIONS_DIR } = require('../session-manager');
 const { fenceSidecarOutput } = require('../utils/untrusted-fence');
+// F8 D15 (errata E-PR3-5) search core — split out (T6 review) to keep this
+// file under its line budget; both list surfaces still reach it through
+// this module's own searchSessions re-export below.
+const { searchSessions } = require('./list-search');
+const { normalizeLimit, truncationNotice } = require('./list-limit');
 
 /**
  * Format a timestamp as relative age
@@ -54,6 +59,8 @@ function enumerateSessions(project, opts = {}) {
           type: meta.type || 'run',
           parentWave: meta.parentWave || null,
           legCount: Array.isArray(meta.legs) ? meta.legs.length : null,
+          mode: meta.mode || (meta.headless ? 'headless' : 'interactive'),
+          ...(meta.tag ? { tag: meta.tag } : {}),
         });
       } catch { /* skip unreadable */ }
     }
@@ -67,29 +74,96 @@ function enumerateSessions(project, opts = {}) {
   return sessions;
 }
 
+/**
+ * Enumerate sessions across every project the global sessions-index
+ * (src/utils/session-index.js) knows about, plus the current project. --all
+ * support (F8 D14): the index is a navigation aid, never authoritative, so a
+ * stale entry pointing at a missing/unreadable project directory is skipped
+ * silently rather than surfaced as an error.
+ *
+ * Dedup is by CANONICAL identity (T5 review fix-wave): the index stores
+ * canonical spellings (canonicalProjectPath — forward slashes, upper-cased
+ * drive letter) while `project` arrives however the caller spelled it
+ * (process.cwd() is backslashed on Windows). A raw string Set treated those
+ * as two different projects, double-counting every row of the current
+ * project whenever it was also present in the index (which it usually is —
+ * every session start records itself). The current project is seeded FIRST
+ * so its rows keep the caller's spelling rather than the index's.
+ * @param {{status?: string, project?: string}} [opts]
+ * @returns {Array<object>} enumerateSessions rows, each stamped with `project`
+ */
+function enumerateAllProjects(opts = {}) {
+  const { status, project = process.cwd() } = opts;
+  const { readIndex } = require('../utils/session-index');
+  const { canonicalProjectPath } = require('../utils/project-path');
+  const index = readIndex();
+
+  const byCanonical = new Map();
+  for (const p of [project, ...Object.values(index)]) {
+    if (!p || typeof p !== 'string') { continue; }
+    const key = canonicalProjectPath(p);
+    if (!byCanonical.has(key)) { byCanonical.set(key, p); }
+  }
+
+  let sessions = [];
+  for (const p of byCanonical.values()) {
+    try {
+      const rows = enumerateSessions(p, {}).map(s => ({ ...s, project: p }));
+      sessions = sessions.concat(rows);
+    } catch { /* unreadable project — skip silently */ }
+  }
+
+  sessions.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+  if (status && status !== 'all') {
+    sessions = sessions.filter(s => s.status === status);
+  }
+  return sessions;
+}
+
 /**
  * List previous sidecar sessions
  * Spec Reference: §4.2
  *
  * @param {object} options
  * @param {string} [options.status] - Filter by status (all, running, complete)
+ * @param {boolean} [options.all] - Cross-project via the global sessions-index (F8 D14)
  * @param {boolean} [options.json] - Output as JSON
  * @param {string} [options.project] - Project directory
+ * @param {string|boolean} [options.search] - id/tag/briefing substring filter (F8 D15); `true` = valueless flag (usage error)
+ * @param {number|string|boolean} [options.limit] - cap printed rows (PR3 rider); 0/absent = unlimited, `true` = valueless flag (usage error)
  */
 async function listSidecars(options) {
-  const { status, json, project = process.cwd() } = options;
+  const { status, all, json, search, limit, project = process.cwd() } = options;
+  // Mirrors models.js:279-281's valueless-flag shape.
+  if (search === true) { throw new Error('--search requires a value'); }
+  const cap = normalizeLimit(limit); // throws on valueless/non-integer/negative
 
-  const sessions = enumerateSessions(project, { status });
+  let sessions = all
+    ? enumerateAllProjects({ status, project })
+    : enumerateSessions(project, { status });
+  if (search) { sessions = searchSessions(sessions, search, { project }); }
   if (sessions.length === 0) {
     console.log('No amicus sessions found.');
     return;
   }
 
+  // v4.7 PR3 rider: cap OUTPUT only — the newest-first sort has already run, so
+  // slicing here yields the N most recent. Enumeration is deliberately NOT
+  // capped: `--all` must still walk every project or the sort would rank rows
+  // it never saw.
+  const total = sessions.length;
+  const truncated = cap > 0 && total > cap;
+  if (truncated) { sessions = sessions.slice(0, cap); }
+
   if (json) {
     console.log(JSON.stringify(sessions, null, 2));
   } else {
-    console.log('ID        MODEL                  STATUS     AGE         BRIEFING');
-    console.log('─'.repeat(80));
+    console.log(
+      'ID'.padEnd(10) + 'MODEL'.padEnd(23) + 'STATUS'.padEnd(11) +
+      'TAG'.padEnd(12) + 'AGE'.padEnd(12) + 'BRIEFING' +
+      (all ? '  PROJECT' : '')
+    );
+    console.log('─'.repeat(all ? 100 : 80));
     sessions.forEach(s => {
       const age = formatAge(s.createdAt);
       const briefingShort = (s.briefing || '').slice(0, 30) +
@@ -98,11 +172,20 @@ async function listSidecars(options) {
         `${(s.id || '').padEnd(10)}` +
         `${(s.type === 'wave' ? `wave(${s.legCount ?? 0} legs)` : (s.model || '')).padEnd(23)}` +
         `${(s.status || 'unknown').padEnd(11)}` +
+        `${(s.tag || '').padEnd(12)}` +
         `${age.padEnd(12)}` +
-        `${briefingShort}`
+        `${briefingShort}` +
+        (all ? `  ${s.project || ''}` : '')
       );
     });
   }
+
+  // No silent caps: say what was elided, and how to see it all. In --json mode
+  // this goes to stderr so stdout stays a single parseable document.
+  if (truncated) {
+    const notice = truncationNotice(cap, total);
+    if (json) { console.error(notice); } else { console.log(notice); }
+  }
 }
 
 /**
@@ -184,6 +267,8 @@ async function readSidecar(options) {
 module.exports = {
   formatAge,
   enumerateSessions,
+  enumerateAllProjects,
+  searchSessions,
   listSidecars,
   readSidecar
 };

package/src/sidecar/start-metadata.js

@@ -0,0 +1,58 @@
+// src/sidecar/start-metadata.js
+'use strict';
+
+/**
+ * @module start-metadata
+ * createSessionMetadata, split out of start.js to keep that file under the
+ * hard size gate (v4.7 PR3 Task 1: F8 relief). Pure move — same writes, same
+ * order, same atomicity. start.js re-exports this so no importer changes.
+ */
+
+const fs = require('fs');
+
+const { writeFileAtomic } = require('../utils/atomic-write');
+const { SessionPaths } = require('./session-utils');
+
+/** Create session directory and save metadata */
+function createSessionMetadata(taskId, project, options) {
+  const { model, prompt, briefing, noUi, headless, agent, thinking, pack, tag } = options;
+
+  const sessionDir = SessionPaths.sessionDir(project, taskId);
+  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+
+  const effectiveBriefing = prompt || briefing;
+  const isHeadless = noUi !== undefined ? noUi : headless;
+
+  // Preserve fields from existing metadata (e.g., pid written by MCP handler)
+  const metaPath = SessionPaths.metadataFile(sessionDir);
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    } catch {
+      // ignore corrupt metadata
+    }
+  }
+
+  const metadata = {
+    ...existing,
+    taskId,
+    model,
+    project,
+    briefing: effectiveBriefing,
+    mode: isHeadless ? 'headless' : 'interactive',
+    agent: agent || (isHeadless ? 'build' : 'chat'),
+    thinking: thinking || 'medium',
+    status: 'running',
+    pid: existing.pid || process.pid,
+    createdAt: existing.createdAt || new Date().toISOString(),
+    ...(pack ? { pack } : {}), // v4.5 Task 13: absent-not-null; ...existing above preserves a prior write when this call omits pack.
+    ...(tag ? { tag } : {}), // v4.7 F8 (D13): absent-not-null, same merge-preserve idiom as pack above.
+  };
+
+  writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+
+  return sessionDir;
+}
+
+module.exports = { createSessionMetadata };

package/src/sidecar/start.js

@@ -27,53 +27,13 @@ const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { discoverParentMcps } = require('../utils/mcp-discovery');
 const { stripSelfMcpEntries } = require('../utils/mcp-self-identity');
 const { generateFoldNonce } = require('../utils/fold-marker');
+const { createSessionMetadata } = require('./start-metadata');
 
 /** Generate a unique 8-character hex task ID */
 function generateTaskId() {
   return crypto.randomBytes(4).toString('hex');
 }
 
-/** Create session directory and save metadata */
-function createSessionMetadata(taskId, project, options) {
-  const { model, prompt, briefing, noUi, headless, agent, thinking, pack } = options;
-
-  const sessionDir = SessionPaths.sessionDir(project, taskId);
-  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
-
-  const effectiveBriefing = prompt || briefing;
-  const isHeadless = noUi !== undefined ? noUi : headless;
-
-  // Preserve fields from existing metadata (e.g., pid written by MCP handler)
-  const metaPath = SessionPaths.metadataFile(sessionDir);
-  let existing = {};
-  if (fs.existsSync(metaPath)) {
-    try {
-      existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-    } catch {
-      // ignore corrupt metadata
-    }
-  }
-
-  const metadata = {
-    ...existing,
-    taskId,
-    model,
-    project,
-    briefing: effectiveBriefing,
-    mode: isHeadless ? 'headless' : 'interactive',
-    agent: agent || (isHeadless ? 'build' : 'chat'),
-    thinking: thinking || 'medium',
-    status: 'running',
-    pid: existing.pid || process.pid,
-    createdAt: existing.createdAt || new Date().toISOString(),
-    ...(pack ? { pack } : {}), // v4.5 Task 13: absent-not-null; ...existing above preserves a prior write when this call omits pack.
-  };
-
-  writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
-
-  return sessionDir;
-}
-
 /**
  * Build MCP configuration from options.
  * Merge priority: CLI --mcp > --mcp-config > file config > discovered parent MCPs
@@ -154,7 +114,7 @@ async function startSidecar(options) {
     contextMaxTokens = 80000, noUi, headless = false, timeout = 15,
     agent, mcp, mcpConfig, summaryLength = 'normal', thinking,
     client, sessionDir, noMcp, excludeMcp, opencodePort, coworkProcess, includeContext = true,
-    position = 'right', json = false, modelInput = null, pack = null
+    position = 'right', json = false, modelInput = null, pack = null, tag
   } = options;
 
   const effectivePrompt = prompt || briefing;
@@ -183,7 +143,7 @@ async function startSidecar(options) {
   );
 
   const sessDir = createSessionMetadata(taskId, effectiveProject, {
-    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking, pack
+    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking, pack, tag
   });
   saveInitialContext(sessDir, systemPrompt, userMessage);
   acquireLock(sessDir, effectiveHeadless ? 'headless' : 'interactive');
@@ -270,6 +230,11 @@ async function startSidecar(options) {
         gateway: String(model).startsWith('openrouter/') ? 'openrouter' : 'direct',
         // (To also attribute v4.2 'local': thread the resolved route gateway — dropped today at
         // cli-handlers-run.js:47 — into createSessionMetadata and read `meta.gateway`, as continue.js:111 does.)
+        // v4.7 F8 D16: same in-scope-value rule as gateway above — `m` is the
+        // just-re-read metadata (line 214), which carries `tag` when
+        // createSessionMetadata stored one (absent otherwise); `|| null` folds
+        // that into spend-ledger.js's null-not-absent dim convention.
+        tag: m.tag || null,
       });
     } catch { /* best-effort */ }
   }

package/src/sidecar/workspace-auto-open.js

@@ -23,7 +23,7 @@
  * @param {'ok'|'package-missing'|'binary-missing'} [options.electronState] - 3-state probe (#76); takes precedence
  * @param {string|null} [options.electronDir] - Resolved electron dir, named in the electron-broken reason
  * @param {string} options.platform - The platform (e.g., 'win32', 'darwin', 'linux')
- * @param {object} options.env - Environment variables object
+ * @param {object} [options.env] - Environment variables object
  * @param {boolean} options.autoOpenConfig - The config.workspace.autoOpen setting
  * @param {boolean|undefined} options.uiParam - Explicit UI parameter (true, false, or undefined)
  * @returns {{open: boolean, reason: string}}
@@ -34,7 +34,7 @@ function shouldAutoOpenWorkspace({
   electronState,
   electronDir,
   platform,
-  env,
+  env = {},
   autoOpenConfig,
   uiParam,
 }) {

package/src/spend-query.js

@@ -17,7 +17,7 @@
  * NOT hand-copy this array elsewhere: a 7th dimension added here must reach
  * both surfaces automatically, not just the one someone remembered to edit.
  */
-const GROUP_DIMS = ['model', 'wave', 'council', 'project', 'op', 'day'];
+const GROUP_DIMS = ['model', 'wave', 'council', 'project', 'op', 'day', 'tag'];
 
 /** Cap on rows returned when a caller opts into raw rows (CLI --rows / MCP rows:true). */
 const ROWS_CAP = 1000;
@@ -55,6 +55,7 @@ function rowKey(row, dimension) {
     case 'project': return row.project || '(unattributed)';
     case 'op': return row.op || '(unattributed)';
     case 'day': return typeof row.ts === 'string' ? row.ts.slice(0, 10) : '(unattributed)';
+    case 'tag': return row.tag || '(unattributed)';
     default: return '(unattributed)';
   }
 }

package/src/template/apply.js

@@ -52,10 +52,10 @@ function applyTemplate({ templateRef, prompt, artifactFile, varList, project })
     try {
       raw = fs.readFileSync(artifactPath);
     } catch (err) {
-      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: cannot read --artifact ${artifactFile}: ${err.message}`, hint: null } };
+      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: cannot read --artifact ${artifactFile}: ${err.message}`, hint: 'Check that the --artifact path exists and is readable — relative paths resolve from the current working directory.' } };
     }
     if (raw.length > ARTIFACT_CAP_BYTES) {
-      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: --artifact ${artifactFile} is ${raw.length} bytes; the cap is 256 KB`, hint: null } };
+      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: --artifact ${artifactFile} is ${raw.length} bytes; the cap is 256 KB`, hint: 'Trim --artifact to under 256 KB, or point it at a smaller excerpt.' } };
     }
     artifact = raw.toString('utf-8');
     if (artifact.charCodeAt(0) === 0xFEFF) { artifact = artifact.slice(1); }
@@ -66,11 +66,14 @@ function applyTemplate({ templateRef, prompt, artifactFile, varList, project })
     artifact,
     artifactPath,
     date: new Date().toISOString().slice(0, 10),
-    project: String(project),
+    project: path.resolve(String(project)),
     vars,
   });
   if (res.error) {
-    return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: res.error, hint: null } };
+    // No variable list here on purpose: renderTemplate's own message already ends
+    // with a knownList()-derived "Known: ..." line. A copy would be a third
+    // hand-maintained KNOWN_VARIABLES mirror, which BACKLOG's T3-m2 hard gate forbids.
+    return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: res.error, hint: 'amicus template show <name>' } };
   }
 
   return {

package/src/template/render.js

@@ -7,8 +7,9 @@
  * happens ONLY in template files (spec carried decision 7) — --prompt text is
  * always literal, so this module never sees non-template input.
  *
- * v4.5 variable set. {{input}} is deliberately ABSENT — it ships with v4.6's
- * --input-from; on v4.5 it fails as an unknown variable, which is accurate.
+ * v4.5 variable set. {{input}} is deliberately ABSENT — it ships with
+ * composable waves (--input-from), a future rev; on v4.5 it fails as an
+ * unknown variable, which is accurate.
  * No {{model}}: prompts are built once per wave, model-independent.
  */
 
@@ -37,6 +38,9 @@ function renderTemplate(text, data) {
   for (const name of used) {
     if (name.startsWith('var.')) {
       const key = name.slice(4);
+      if (key === '') {
+        return { error: `Error: Unknown template variable {{var.}} — {{var.<key>}} requires a key. Known: ${knownList()}` };
+      }
       if (!(key in vars)) {
         return { error: `Error: template uses {{var.${key}}} but no --var ${key}=<value> was given` };
       }

package/src/template/store.js

@@ -18,7 +18,7 @@ function _getConfigDir() { return require('../utils/config').getConfigDir(); }
 
 /**
  * v4.5 ships `review` only. `critique`/`refine` are {{input}}-centric and
- * arrive with v4.6's chaining (--input-from).
+ * arrive with composable waves (--input-from).
  */
 const BUILTIN_TEMPLATES = Object.freeze({
   review: [

package/src/utils/cli-preflight.js

@@ -40,4 +40,30 @@ function requireValidTaskId(args, useJson, commandLabel, usage) {
   return taskId;
 }
 
-module.exports = { requireNoUiForJson, requireValidTaskId };
+/**
+ * `pack save --version <semver>` can never work, and used to fail SILENTLY:
+ * `version` is a global BOOLEAN_FLAG (src/cli.js), so parseArgs sets
+ * `args.version = true` and drops the semver into positionals, then
+ * bin/amicus.js prints the version banner BEFORE command dispatch — so
+ * `handlePack` never runs and no pack is written, at exit 0. `--version=2.0.0`
+ * fails identically (the inline value is discarded at the isBooleanFlag branch,
+ * ahead of the --key=value branch). The pack's own version is `--pack-version`.
+ *
+ * Returns the failure rather than exiting, so bin/amicus.js keeps one exit site
+ * and this stays unit-testable (bin/amicus.js is a script, not a module).
+ *
+ * @param {object} args - parsed CLI args
+ * @returns {{code: string, message: string, hint: string}|null} null when there is no conflict
+ */
+function packSaveVersionConflict(args) {
+  if (!args || !args.version) { return null; }
+  const argv = Array.isArray(args._) ? args._ : [];
+  if (argv[0] !== 'pack' || argv[1] !== 'save') { return null; }
+  return {
+    code: ERROR_CODES.BAD_ARGS,
+    message: "Error: --version is amicus's own global flag, not the saved pack's version",
+    hint: 'Use --pack-version <semver> to set the version of the pack being saved.',
+  };
+}
+
+module.exports = { requireNoUiForJson, requireValidTaskId, packSaveVersionConflict };

package/src/utils/config.js

@@ -419,6 +419,21 @@ function getCouncilWithSource(name, catalog = []) {
  * @returns {{models:string[], dropped:string[], droppedMembers:Array<{member:string, reason:string}>}}
  *   `dropped` is the flat member-ref list (unchanged shape, pre-v4.5-Wave-2
  *   callers keep working); `droppedMembers` additively pairs each with WHY.
+ *
+ *   Standing note (D18, v4.7 PR5): each `droppedMembers` entry is `{member, reason}`
+ *   (that is the real key — BACKLOG.md's description of this shape had drifted to
+ *   `{ref, reason}`). The two `reason` literals are produced below, in the
+ *   alias-miss and catalog-miss branches of `classifyCouncilMembers`; they are
+ *   free text, not a coded enum, and today NO consumer branches on the string. They
+ *   are not display-only: `council/presets-cli.js` (`amicus council show`,
+ *   `:149-150`) renders `${member} (${reason})`, `council/run.js` (`:80-87`) carries
+ *   it verbatim into a degrade-note payload, and `reason` is also persisted into
+ *   `run.json` (`run-state.js`, `mcp-council-run.js`) — not merely shown to a human.
+ *   `cli-council-run-bench.js` (`:74`) only type-checks that `reason` is a string
+ *   when round-tripping `--dropped-members` across the MCP→CLI spawn boundary. The
+ *   tripwire: if a THIRD reason string is ever added here, stop and re-decide
+ *   whether `reason` should become a coded enum instead of free text — this note
+ *   marks that decision point, it does not make it.
  */
 function classifyCouncilMembers(members, catalog = []) {
   const aliases = getEffectiveAliases();

package/src/utils/result-schema-rebuild.js

@@ -91,6 +91,7 @@ function buildWaveResultFromSession(project, waveId) {
     legs,
     promptMeta: meta.promptMeta || null,
     ...(meta.pack ? { pack: meta.pack } : {}), // v4.5 Task 13: absent-not-null, mirrors promptMeta's sourcing above.
+    ...(meta.tag ? { tag: meta.tag } : {}), // v4.7 F8 (D13): absent-not-null, same idiom as pack above.
     createdAt: meta.createdAt || null,
     completedAt: meta.completedAt || null,
   });

package/src/utils/result-schema.js

@@ -47,6 +47,7 @@ function durationBetween(createdAt, completedAt) {
  * @returns {object} run document; `pack` (v4.5 Task 13) is additive — present only when
  *   metadata.pack was recorded (solo session launched via --pack), sourced straight off
  *   `metadata` like `usage`/`opencodeSessionId` already are (no new function parameter needed).
+ *   `tag` (v4.7 F8/D13) is additive the same way — present only when metadata.tag was recorded.
  */
 function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null, usage = null }) {
   const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
@@ -71,6 +72,7 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     opencodeSessionId: metadata.opencodeSessionId || null,
     usage: usage !== null ? usage : (metadata.usage || null),
     ...(metadata.pack ? { pack: metadata.pack } : {}),
+    ...(metadata.tag ? { tag: metadata.tag } : {}),
   };
 }
 
@@ -127,9 +129,11 @@ function waveExitCode(waveStatus) {
  * @param {string[]} [opts.notices] - Advisory per-leg migration notices (#61 FIX 2); never affects status/exitCode.
  * @param {{name: string, version: string, hash: string, source: string}|null} [opts.pack] - v4.5 Task 13:
  *   additive — present only when the wave was launched via --pack (absent, never null, otherwise).
+ * @param {string|null} [opts.tag] - v4.7 F8 (D13): additive — present only when the wave was
+ *   launched via --tag (absent, never null, otherwise).
  * @returns {object} wave document
  */
-function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [], pack = null }) {
+function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [], pack = null, tag = null }) {
   const { sumWaveUsage } = require('./pricing');
   // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
   // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
@@ -157,6 +161,7 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
     usage: sumWaveUsage(legs),
     notices: Array.isArray(notices) ? notices.filter(Boolean) : [],
     ...(pack ? { pack } : {}),
+    ...(tag ? { tag } : {}),
   };
 }
 

package/src/utils/session-index-tmp-sweep.js

@@ -33,9 +33,21 @@ function listSessionIndexTmpFiles() {
   return entries
     .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
     .map((name) => {
-      let mtimeMs = null;
-      try { mtimeMs = fs.statSync(path.join(dir, name)).mtimeMs; } catch { /* raced away — skip below */ }
-      return { name, mtimeMs };
+      let st = null;
+      // statSync (not lstatSync) is a DECIDED policy, not an oversight (owner
+      // ruling, v4.7 PR7 — see BACKLOG.md "session-index-tmp-sweep.js follows
+      // symlinks... where its sibling deliberately does not"). This sweep's
+      // targets are index tmp files directly in the flat config dir, never
+      // traversed through a directory an attacker could redirect — unlike
+      // session-metadata-tmp-sweep.js's walk through per-session directories
+      // (see that file's "Symlink safety" paragraph for why THAT sweep must
+      // never follow). Following here means a symlink named like an orphaned
+      // tmp file is still swept (unlink removes only the link); the one real
+      // consequence is AGE_THRESHOLD_MS reading the TARGET's mtime, so a fresh
+      // link to an old file is swept with no grace window. Filed, not fixed —
+      // see the BACKLOG entry above for the full inclusion/unfiled-delta split.
+      try { st = fs.statSync(path.join(dir, name)); } catch { /* raced away */ }
+      return { name, mtimeMs: st && st.isFile() ? st.mtimeMs : null };
     })
     .filter((f) => f.mtimeMs !== null);
 }
@@ -52,6 +64,9 @@ function unlinkSessionIndexTmp(name) {
  * this in guard() the same way it wires the mcp-legacy check's inspect/migrate.
  * @param {{listSessionIndexTmpFiles: () => Array<{name:string, mtimeMs:number}>,
  *   fix?: boolean, now: () => number, unlinkSessionIndexTmp: (name: string) => void}} d
+ * Its four `message` strings are byte-identical to
+ * session-metadata-tmp-sweep.js's evaluateSessionMetadataTmpSweep by design
+ * (only `id`/`name`/`fixDetail` differ) — reword both or neither.
  */
 function evaluateSessionIndexTmpSweep(d) {
   const id = 'sessions-index-tmp'; const name = 'Session index tmp files';

package/src/utils/session-index.js

@@ -94,4 +94,5 @@ module.exports = {
   INDEX_FILENAME,
   recordSession,
   lookupSessionProject,
+  readIndex,
 };