amicus 4.6.3 → 4.7.1

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

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/reopen-spend.js

@@ -0,0 +1,32 @@
+/**
+ * @module sidecar/reopen-spend
+ * Spend finalization for a REOPENED session (continue/resume). Split out of
+ * sidecar/continue.js to keep that file under the 300-line gate; resume.js was
+ * already reaching across for it, so the shared home is the honest one.
+ */
+
+'use strict';
+
+/**
+ * Resolve a reopened session's usage, write it onto metadata, and append one
+ * attributed ledger row. Mirrors start.js's finalize (the only sites that
+ * dropped usage - BACKLOG.md:280). Best-effort ledger append; never throws.
+ * @returns {{usage: object|null}}
+ */
+function finalizeSpendForReopen({ taskId, model, mode, op, result, status, project, metadata }, ctx = {}) {
+  const { resolveUsage } = require('../utils/pricing');
+  const usage = result && result.usage ? resolveUsage({ model, usageTotals: result.usage }) : null;
+  if (usage) {
+    metadata.usage = usage; // buildRunResult surfaces metadata.usage into the --json doc for free
+    try {
+      const { appendSpend } = require('../utils/spend-ledger');
+      const gateway = metadata.gateway || (String(model).startsWith('openrouter/') ? 'openrouter' : 'direct');
+      // v4.7.1 Task 7 D16: null-not-absent, the OPPOSITE convention from
+      // metadata.tag's absent-not-null (D13) — same `|| null` idiom as start.js:237.
+      appendSpend({ taskId, model, mode, usage, op, status, project, gateway, tag: metadata.tag || null }, ctx);
+    } catch { /* best-effort */ }
+  }
+  return { usage };
+}
+
+module.exports = { finalizeSpendForReopen };

package/src/sidecar/resume.js

@@ -251,7 +251,7 @@ async function resumeSidecar(options) {
     // v4.3: attribute resume spend (C9/E4). Reload metadata, write usage + append
     // a ledger row (status: statusFromResult, matching start.js — not terminal.status).
     {
-      const { finalizeSpendForReopen } = require('./continue');
+      const { finalizeSpendForReopen } = require('./reopen-spend');
       const { statusFromResult } = require('../utils/result-schema');
       const reloaded = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
       const { usage } = finalizeSpendForReopen({

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: [