amicus 4.4.0 → 4.4.1

package/src/utils/server-setup.js

@@ -75,10 +75,88 @@ function ensurePortAvailable(port = DEFAULT_PORT) {
   return false;
 }
 
+/**
+ * A start failure that is a LOCK RACE, not a deterministic error.
+ *
+ * OpenCode opens one shared SQLite database (~/.local/share/opencode/opencode.db)
+ * at startup, so two servers starting in the same instant can collide on it and
+ * the loser exits 1 with `database is locked`. Measured: council run v441plan01
+ * lost four of five seats in 736ms to exactly this.
+ *
+ * Deliberately NARROW. A missing binary, a bad key, a busy port and a config
+ * error are all deterministic — retrying them only triples the latency before
+ * the same failure, so they must fall straight through untouched.
+ */
+const LOCK_CLASS_START_FAILURE = /database is locked|database table is locked|SQLITE_BUSY/i;
+
+/**
+ * Backoff between start attempts; 5 attempts total, ≤3.75s of added latency.
+ *
+ * ⚠️ WIDENED from 3 attempts at 250/500ms (≤750ms) by v4.4.1 Step 10.5. 750ms is
+ * thin against a multi-megabyte WAL and any concurrent process touching the same
+ * OpenCode database: run v441plan02 exhausted it, the council degraded to one
+ * server per wave, and then lost four of five seats to the very race the retry
+ * exists to survive. The wait is bounded and paid at most once per acquisition;
+ * the cost of not waiting is a dead bench.
+ *
+ * Still lock-class ONLY — a deterministic failure (missing binary, bad key, busy
+ * port, config error) never sleeps a single millisecond here.
+ */
+const LOCK_RETRY_DELAYS_MS = [250, 500, 1000, 2000];
+
+/**
+ * @param {Error|null} error
+ * @returns {boolean} true only for a lock-class (retryable) start failure
+ */
+function isLockClassStartFailure(error) {
+  if (!error) { return false; }
+  // The real failure arrives as a message with the server's own stdout inlined
+  // ("Server exited with code 1 / Server output: … database is locked"), but
+  // check the usual carriers too so a wrapped/spawn-shaped error still matches.
+  const carriers = [error.message, error.stderr, error.stdout, error.cause && error.cause.message];
+  return carriers.some(c => typeof c === 'string' && LOCK_CLASS_START_FAILURE.test(c));
+}
+
+/**
+ * Run `attempt` with a BOUNDED retry on a lock-class failure only.
+ *
+ * Never fails closed: the final failure is rethrown unchanged, so every caller
+ * that already degrades on a start failure (runFanout writes an error wave; a
+ * council run falls back to per-wave servers) degrades exactly as before —
+ * just later, and far less often. This is the half of the fix that covers what
+ * a per-run shared server cannot: two separate `amicus` processes, or a CLI run
+ * beside a live MCP server, still contend for the same database.
+ *
+ * @param {(attempt: number) => Promise<T>} attempt
+ * @param {{retryDelayMs?: number}} [opts] retryDelayMs: test seam — collapses
+ *   every backoff to this value so a retry test does not sleep for real.
+ * @returns {Promise<T>}
+ * @template T
+ */
+async function retryOnLockRace(attempt, opts = {}) {
+  const delays = opts.retryDelayMs === undefined
+    ? LOCK_RETRY_DELAYS_MS
+    : LOCK_RETRY_DELAYS_MS.map(() => opts.retryDelayMs);
+  for (let i = 0; ; i += 1) {
+    try {
+      return await attempt(i);
+    } catch (error) {
+      if (i >= delays.length || !isLockClassStartFailure(error)) { throw error; }
+      logger.warn('OpenCode server start lost a lock race — retrying', {
+        attempt: i + 1, of: delays.length + 1, delayMs: delays[i], error: error.message,
+      });
+      await new Promise(resolve => setTimeout(resolve, delays[i]));
+    }
+  }
+}
+
 module.exports = {
   DEFAULT_PORT,
+  LOCK_RETRY_DELAYS_MS,
   isPortInUse,
   getPortPid,
   killPortProcess,
-  ensurePortAvailable
+  ensurePortAvailable,
+  isLockClassStartFailure,
+  retryOnLockRace
 };

package/src/utils/spend-ledger.js

@@ -45,7 +45,10 @@ const SPEND_LEDGER_FILE = 'spend-ledger.jsonl';
  * @param {string} [opts.waveId] present for a fanout leg
  * @param {string} opts.model resolved model id (or alias, if that's all the caller has)
  * @param {'headless'|'interactive'|'leg'} opts.mode
- * @param {{tokens:object, cost:{amount:number|null,currency:string,source:string}}|null} opts.usage
+ * @param {{tokens:object, cost:{amount:number|null,currency:string,source:string},
+ *   subtreeUnknown?:boolean}|null} opts.usage `subtreeUnknown` (v4.4.1 CA-2) is
+ *   copied onto the row when truthy — this leg's own cost resolved, but a child
+ *   session it spawned could not be priced, so the row's `cost` is a FLOOR
  * @param {string} [opts.op] 'leg' | 'start' | 'continue' | 'resume'
  * @param {string} [opts.status] terminal status
  * @param {string} [opts.councilRunId] council run id (additive attribution)
@@ -86,18 +89,36 @@ function appendSpend({ taskId, waveId, model, mode, usage,
     if (attempt !== undefined) { row.attempt = attempt; }
     if (substitutedFor !== undefined) { row.substitutedFor = substitutedFor; }
     if (retryOfWaveId !== undefined) { row.retryOfWaveId = retryOfWaveId; }
+    // v4.4.1 CA-2: a leg whose OWN cost is known but which spawned a child
+    // session the walk could not price writes a PRICED row — so `unpricedRows`
+    // never catches it and `amicus spend` reads as a complete measurement while
+    // `council run` says `costExact:false` about the same dollars. Omitted (not
+    // `|| false`) so a pre-4.4.1 row and an ordinary row stay identical, matching
+    // the linkage-field convention above.
+    if (usage.subtreeUnknown) { row.subtreeUnknown = true; }
     fs.appendFileSync(path.join(dir, SPEND_LEDGER_FILE), JSON.stringify(row) + '\n');
   } catch (e) {
     logger.debug('spend-ledger append failed (best-effort, run unaffected)', { taskId, error: e.message });
   }
 }
 
-/** @param {string} [dir] @returns {Array<object>} parsed rows; corrupt lines skipped */
+/**
+ * Read the ledger. Corrupt lines are skipped — and v4.4.1 A2 widens "corrupt"
+ * from "does not parse" to "does not parse AS A ROW". A line that is valid JSON
+ * but not a plain object (`"foo"`, `42`, `[1,2]`) used to survive `filter(Boolean)`
+ * and be treated as a row by every consumer: `aggregateSpend` counted it in
+ * `runs`, scored it into `unpricedRows`/`sourceMix.unknown` off its absent cost
+ * block, and `--rows` echoed it into a published document that says rows are
+ * objects. A scalar in a JSONL ledger of row objects is a corrupt line, so it is
+ * now dropped like any other — one fewer way the totals can be inflated by damage.
+ * @param {string} [dir] @returns {Array<object>} parsed rows; corrupt lines skipped
+ */
 function readSpendRows(dir) {
   const file = path.join(dir || getConfigDir(), SPEND_LEDGER_FILE);
   if (!fs.existsSync(file)) { return []; }
   return fs.readFileSync(file, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean)
-    .map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(r => r !== null && typeof r === 'object' && !Array.isArray(r));
 }
 
 module.exports = { appendSpend, readSpendRows, SPEND_LEDGER_FILE, SPEND_LEDGER_SCHEMA_VERSION };

package/src/workspace/artifact-guard.js

@@ -24,6 +24,9 @@ const FIXED_ARTIFACTS = Object.freeze(['briefing-stage1.md', 'bundle-stage2.md',
 // `artifact not allowed: <name>`. Writers: tally-provisional.json = src/council/run.js:199;
 // revote-bundle.md = run-debate.js:119; debate.json = run-debate.js:261; the per-seat
 // rebuttal-/revote- pair = materializeDebate (run-launch.js:127-136).
+// ⚠️ FIVE KINDS, THREE ENTRIES — that is not a miscount (v4.4.1 DOC-7, re-verified). This const
+// holds only the three RUN-LEVEL names; the last two of the five, the rebuttal-/revote- pair, are
+// per BENCH MODEL and are appended inside artifactAllowlist below, next to review-/judge-.
 const DEBATE_ARTIFACTS = Object.freeze(['tally-provisional.json', 'revote-bundle.md', 'debate.json']);
 const MAX_ARTIFACT_BYTES = 200 * 1024;
 
@@ -167,7 +170,25 @@ function readRunArtifact(project, runId, name, deps = {}) {
 
   let realTarget;
   try { realTarget = realpathSync(path.join(ptr.runDir, name)); }
-  catch { return { error: `not written yet: ${name}` }; }
+  catch (err) {
+    // ⚠️ v4.4.1 RN-10: this catch used to answer `not written yet: <name>` for ANY realpath
+    // failure — ENOENT, EACCES, EPERM, EIO, ELOOP, a dangling symlink — so a permission problem
+    // was indistinguishable from a file the council simply has not produced yet. That is not a
+    // cosmetic conflation: electron/ipc-workspace.js's workspace:fold reads chair-output.md
+    // through this function, and on a permission error it produced a silent CHAIRLESS fold that
+    // still reported {ok: true}. The logger.warn it now emits was the mitigation — but it logged
+    // this string, so the log said "not written yet" about a file that was right there.
+    //
+    // ⚠️ Keep the sanitization. Do NOT re-interpolate `err.message`: a realpath failure's message
+    // embeds the full resolved path it tried to open, which round 4 deliberately stopped handing
+    // back over IPC (see the run.json catch above). `err.code` is a bare symbolic errno with no
+    // path in it, and it is the one piece an operator reading the fold warning actually needs —
+    // whitelisted to the errno character class so nothing else can ever ride out through here.
+    const code = err && typeof err.code === 'string' && /^[A-Z][A-Z0-9_]{1,15}$/.test(err.code)
+      ? err.code : 'unknown';
+    if (code === 'ENOENT') { return { error: `not written yet: ${name}` }; }
+    return { error: `artifact unreadable (${code}): ${name}` };
+  }
   if (!isRealpathContained(realDir, realTarget)) {
     return { error: 'artifact escapes run directory' };
   }

package/src/workspace/fold-format.js

@@ -2,9 +2,16 @@
  * Council Workspace — fold payload builder (v4.4 §7).
  *
  * MIRRORS the shipped fold-header builder `formatFoldOutput`
- * (src/headless.js:775-789, exported at :797, re-exported from src/index.js:20)
- * — byte-for-byte the same 8-line head. src/headless.js is the SOURCE OF
- * TRUTH; keep the head in sync with it. The duplication is deliberate:
+ * (src/headless.js `formatFoldOutput`, exported from src/headless.js and
+ * re-exported from src/index.js) — byte-for-byte the same **7-line** head:
+ * marker, Model, Session, Client, CWD, Mode, `---`. ⚠️ v4.4.1 DOC-5: this said
+ * "8-line" for two releases. Line 8 (`VERDICT:`) is council's OWN addition and
+ * has no counterpart in formatFoldOutput, whose 8th element is the summary
+ * body. Only the first 7 lines are the shared contract; anyone changing the
+ * shared format must sync those and leave `VERDICT:` alone.
+ * src/headless.js is the SOURCE OF TRUTH; keep the head in sync with it.
+ * (Line numbers deliberately omitted — the previous `:775-789`/`:797` citation
+ * had drifted by ~500 lines.) The duplication is deliberate:
  * requiring headless.js transitively pulls opencode-client / progress /
  * conversation-mirror at require time (src/headless.js:8-17), which
  * src/workspace/ must stay free of.
@@ -79,7 +86,29 @@ function buildFoldText(o) {
   } else {
     head.push(`Run: ${run.status || 'unknown'} — ${stageSummary(run)}`);
   }
-  head.push(`Cost: ${formatCost(cost)}${cost && cost.source ? ` (${cost.source})` : ''}`);
+  // ⚠️ v4.4.1 DOC-5: this used to append ` (${cost.source})` for EVERY source,
+  // on top of a glyph formatCost had already spent on the same fact —
+  // `~$0.0100 (estimated)`, `? (unknown)`. formatCost (src/utils/pricing.js)
+  // prefixes `~` for both 'estimated' and 'mixed', and returns a bare `?` when
+  // the source is 'unknown'. So for 'estimated' and 'unknown' the word was pure
+  // repetition and is gone.
+  //
+  // Two sources still spell themselves out, because the glyph vocabulary cannot
+  // express them:
+  //   - `reported` — a plain `$0.4321` is also what an unrecognised/absent
+  //     source renders as, so the absence of a glyph cannot mean "exact".
+  //   - `mixed` — `~` encodes *inexact*, not *which kind of inexact*. Collapsing
+  //     'mixed' into a bare `~$…` makes it indistinguishable from 'estimated',
+  //     and the two are not the same claim: 'mixed' means some legs reported
+  //     real usage and some were estimated, i.e. part of this number is
+  //     measured. That is strictly more information than 'estimated', and this
+  //     is the fold line of a release whose theme is cost truthfulness.
+  // Each thing is still said exactly once — the `~` says "inexact", the word
+  // says "which kind", and neither restates the other.
+  const costSourceLabel = cost && (cost.source === 'reported' || cost.source === 'mixed')
+    ? ` (${cost.source})`
+    : '';
+  head.push(`Cost: ${formatCost(cost)}${costSourceLabel}`);
 
   // Review follow-up #1: strip FIRST, then test emptiness on the STRIPPED
   // result — not the raw one. A chair body consisting solely of a marker

package/src/workspace/live-normalize.js

@@ -20,10 +20,14 @@
 const { formatCost } = require('../utils/pricing');
 const { TERMINAL_STATUSES } = require('./run-detail');
 
+// ⚠️ v4.4.1 RN-7: the `doc.wave.legs` fallback that used to sit here is GONE, deliberately.
+// No producer nests legs under `wave` — the WAVE composed doc (src/mcp-server.js:592-662)
+// carries a TOP-LEVEL `legs`, exactly like the council one, and this file's header already
+// says not to model the wave doc at all. The arm asserted a shape that does not exist, and
+// wsgate01's reviewer believed it. If a nested shape ever appears, add it back WITH a
+// producer to point at.
 function legRowsOf(doc) {
-  if (Array.isArray(doc.legs)) { return doc.legs; }
-  if (doc.wave && Array.isArray(doc.wave.legs)) { return doc.wave.legs; }
-  return [];
+  return Array.isArray(doc.legs) ? doc.legs : [];
 }
 
 function numOrNull(v) { return typeof v === 'number' ? v : null; }
@@ -32,7 +36,9 @@ function seatOf(leg) {
   const usage = leg.usage || null;
   const tokens = usage && usage.tokens ? usage.tokens : null;
   return {
-    id: leg.taskId || leg.legId || null,
+    // ⚠️ v4.4.1 RN-7: `leg.legId` was a second dead fallback here — no leg row, council or
+    // wave, has ever carried it (src/observe/council-legs.js stamps `taskId`). Deleted.
+    id: leg.taskId || null,
     // ⚠️ DE-ROT (F34/F36): `model` and `modelInput` are TWO SEPARATE fields, never collapsed.
     // A live leg's `model` is the resolved executable id (e.g. `google/gemini-2.5`); `modelInput`
     // is the council ALIAS (e.g. `gemini`) that run.json's labelMap and blind mode's labelFor()
@@ -108,19 +114,26 @@ function normalizeLive(doc) {
     view: doc.view || null,
     runId: doc.runId || doc.taskId || null,
     status,
-    // ⚠️ PRE-FLIGHT (P6): the fallback read `doc.stage`, which NO producer emits — the council
-    // payload's field is `currentStage` (src/mcp-council-awareness.js:155). Harmless today only by
-    // coincidence: `currentStage` is computed from the same `stages.find(status === 'running')`
-    // predicate as `active`, so both arms are null in exactly the same cases. But it is the same
-    // read-a-field-nobody-writes class as P5, and this is the arm that would matter if `stages`
-    // ever arrived non-array. Read the field that exists.
-    stageName: active ? active.name : (doc.currentStage || null),
+    // ⚠️ v4.4.1 RN-7 (was PRE-FLIGHT P6): the `|| doc.currentStage` fallback is GONE. P6 had
+    // already corrected it once — from the phantom `doc.stage` to the real `currentStage` — and
+    // its own comment conceded the arm was "harmless today only by coincidence". It is in fact
+    // strictly unreachable: buildCouncilStatusPayload writes `stages` as `(run.stages || []).map(…)`
+    // (always an array) and derives `currentStage` from the SAME
+    // `stages.find(s => s.status === 'running')` predicate `active` uses one line up
+    // (src/mcp-council-awareness.js:155-157), so `active` is null in exactly the cases
+    // `currentStage` is too. Keeping it asserted a divergence between the two fields that no
+    // producer can create.
+    stageName: active ? active.name : null,
     stages,
     seats: legRowsOf(doc).map(seatOf),
-    // The two counters the payload already ships (src/mcp-council-awareness.js:149) — the honest
-    // fallback readout if a seat row is ever unavailable.
-    legsTotal: typeof doc.legsTotal === 'number' ? doc.legsTotal : null,
-    legsComplete: typeof doc.legsComplete === 'number' ? doc.legsComplete : null,
+    // ⚠️ v4.4.1 RN-8 (D1 ruling: delete the promise). `legsTotal`/`legsComplete` used to be
+    // mapped here under a comment promising them as "the honest fallback readout if a seat row
+    // is ever unavailable" — a UI fallback nobody ever wired. Nothing in electron/workspace-ui/
+    // read either field. Documenting a feature that does not exist is worse than not having it,
+    // so the fields and the promise are both gone. ⚠️ The SAME names on the composed doc
+    // (src/mcp-council-awareness.js) and in src/cli-handlers-status.js / src/mcp-wait.js ARE
+    // consumed — this deletion is scoped to the workspace's LiveModel only. If a future task
+    // wants the counters in the GUI, re-add them WITH the renderer that paints them.
     // ⚠️ DE-ROT (F39): these two are ACTIVE-STAGE spend, not the run total.
     // buildCouncilStatusPayload rolls up only the legs of the currently-RUNNING stage's sub-waves
     // (mcp-council-awareness.js:136-146) and omits `usage` entirely until one of those legs flushes

package/src/workspace/run-detail.js

@@ -23,7 +23,13 @@ const { isRealpathContained } = require('../utils/path-fence');
  * ("zero v4.3") and live-doc.js is v4.3. Not to be confused with the shipped
  * src/utils/result-schema.js:13 TERMINAL_STATUSES, which is the LEG set (no 'partial').
  */
-const TERMINAL_STATUSES = ['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'idle-timeout'];
+// ⚠️ v4.4.1 A1: 'timed-out' added alongside 'timeout' — see the long note at
+// src/observe/live-doc.js:18 for why both spellings are real and which producer writes each.
+// Council run.json only ever carries aborted|complete|error|partial (run-finalize.js:38
+// statusForExit), so the new name is inert for THIS module's own reads; it is carried anyway
+// because the drift pin demands byte-identity with the source list, and that pin is the only
+// thing keeping the three copies honest.
+const TERMINAL_STATUSES = ['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'timed-out', 'idle-timeout'];
 
 /** Friendly labels for known v4.0 stage names; unknown names pass through raw
  *  — the graceful-when-present rule (spec §5.2). */