amicus 4.5.1 → 4.5.3

package/schemas/council-verdict.schema.json

@@ -4,53 +4,207 @@
   "title": "amicus council-verdict document",
   "description": "Verdict record (`council verdict --json`, amicus_verdict, verdict.json). overallVerdict is the chair's parsed VERDICT line — null in every Stage-4 manual path, populated by the headless engine.",
   "type": "object",
-  "required": ["schemaVersion", "type", "runId", "council", "overallVerdict", "findings", "streetCred", "runStats", "tierCounts"],
+  "required": [
+    "schemaVersion",
+    "type",
+    "runId",
+    "council",
+    "overallVerdict",
+    "findings",
+    "streetCred",
+    "runStats",
+    "tierCounts"
+  ],
   "properties": {
-    "schemaVersion": { "const": 2 },
-    "type": { "const": "council-verdict" },
-    "runId": { "type": "string" },
-    "runType": { "type": ["string", "null"] },
-    "date": { "type": ["string", "null"] },
-    "chair": { "type": ["string", "null"] },
-    "council": { "type": "array", "items": { "type": "string" } },
-    "claudeInCouncil": { "type": "boolean" },
+    "schemaVersion": {
+      "const": 2
+    },
+    "type": {
+      "const": "council-verdict"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "runType": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "chair": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "council": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "claudeInCouncil": {
+      "type": "boolean"
+    },
     "overallVerdict": {
       "oneOf": [
-        { "enum": ["Ship it", "Fix these first", "Fundamental rethink"] },
-        { "type": "null" }
+        {
+          "enum": [
+            "Ship it",
+            "Fix these first",
+            "Fundamental rethink"
+          ]
+        },
+        {
+          "type": "null"
+        }
       ]
     },
     "findings": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "tier", "decision", "applied"],
+        "required": [
+          "id",
+          "tier",
+          "decision",
+          "applied"
+        ],
         "properties": {
-          "id": { "type": "string" },
-          "raiser": { "type": ["string", "null"] },
-          "severity": { "type": ["string", "null"] },
-          "tier": { "enum": ["Confirmed", "Contested", "Singleton", "Disputed"] },
-          "basis": { "type": "object" },
-          "confidence": { "enum": ["thin", "solid"] },
-          "tierOverride": { "type": ["object", "null"] },
-          "duplicateOf": { "type": ["string", "null"] },
-          "adjudications": { "type": "array" },
-          "decision": { "type": ["string", "null"] },
-          "applied": { "type": "boolean" },
+          "id": {
+            "type": "string"
+          },
+          "raiser": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "severity": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "tier": {
+            "enum": [
+              "Confirmed",
+              "Contested",
+              "Singleton",
+              "Disputed"
+            ]
+          },
+          "basis": {
+            "type": "object"
+          },
+          "confidence": {
+            "enum": [
+              "thin",
+              "solid"
+            ]
+          },
+          "tierOverride": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "duplicateOf": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "adjudications": {
+            "type": "array"
+          },
+          "decision": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "applied": {
+            "type": "boolean"
+          },
           "debate": {
             "type": "object",
             "properties": {
-              "action": { "enum": ["defended", "amended", "withdrawn", "no-response"] },
-              "previousTier": { "type": ["string", "null"] }
+              "action": {
+                "enum": [
+                  "defended",
+                  "amended",
+                  "withdrawn",
+                  "no-response"
+                ]
+              },
+              "previousTier": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
             },
-            "required": ["action"],
+            "required": [
+              "action"
+            ],
             "additionalProperties": false
           }
         }
       }
     },
-    "streetCred": { "type": "array", "items": { "type": "object" } },
-    "runStats": { "type": "array", "items": { "type": "object" } },
-    "tierCounts": { "type": "object" }
+    "streetCred": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "runStats": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "tierCounts": {
+      "type": "object"
+    },
+    "seatLoss": {
+      "type": "object",
+      "description": "Present only when --critic was requested. Records whether the adversarial seat actually reviewed: a dead critic wave is survivable (the quorum gate guards only the bench), so a run can otherwise reach a full verdict with the critic silently absent.",
+      "properties": {
+        "criticRequested": {
+          "type": "string",
+          "description": "The model asked for as critic."
+        },
+        "criticSeated": {
+          "type": "boolean",
+          "description": "False when the critic wave died before producing legs."
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Why the critic wave died, when it did."
+        },
+        "deadBenchSeats": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Bench models lost to dead waves, excluding the critic."
+        }
+      },
+      "required": [
+        "criticRequested",
+        "criticSeated"
+      ]
+    }
   }
 }

package/src/cli.js

@@ -122,10 +122,12 @@ function parseArgs(argv) {
 }
 
 /**
- * Check if a flag is boolean (doesn't take a value)
+ * Flags that take no value. Module-level (not rebuilt per call) so
+ * `getBooleanFlags()` can hand the same list to src/utils/known-flags.js —
+ * which needs it to tell a real boolean flag from an unknown token, and must
+ * not keep a second copy that can rot out of sync with this one.
  */
-function isBooleanFlag(key) {
-   const booleanFlags = [
+const BOOLEAN_FLAGS = [
      'no-ui',
      'no-mcp',
      'no-context',
@@ -156,8 +158,21 @@ function isBooleanFlag(key) {
      'ui',                   // watch: open the Council Workspace window; v4.4 seam (v4.3 Task 11)
      'follow',               // fanout / council run: stream this run's own events to stderr (v4.3 Task 13)
      'fallback',             // fanout / council run: opt-in cheaper-model substitution (v4.3 Task 18, spec 6.2); --no-fallback negates via the generic no-* catch-all below
-   ];
-  return booleanFlags.includes(key);
+];
+
+/**
+ * Check if a flag is boolean (doesn't take a value)
+ */
+function isBooleanFlag(key) {
+  return BOOLEAN_FLAGS.includes(key);
+}
+
+/**
+ * The boolean-flag names, for the unknown-flag check.
+ * @returns {string[]} copy — callers must not mutate the source list
+ */
+function getBooleanFlags() {
+  return [...BOOLEAN_FLAGS];
 }
 
 /**
@@ -765,5 +780,6 @@ module.exports = {
   validateStartArgs,
   getUsage,
   getCommandNames,
+  getBooleanFlags,
   DEFAULTS
 };

package/src/council/run-assemble.js

@@ -19,7 +19,7 @@
 const fs = require('fs');
 const path = require('path');
 const { writeFileAtomic } = require('../utils/atomic-write');
-const { buildVerdict, writeVerdictAtomic } = require('./verdict');
+const { buildVerdict, summarizeSeatLoss, writeVerdictAtomic } = require('./verdict');
 const { buildReport } = require('./report');
 const { validateFindings } = require('./findings');
 const { toGlobalFindings } = require('./anonymize');
@@ -178,8 +178,12 @@ function writeTallyFiles({ runDir, tallyInput, record }) {
  * buildVerdict's own signature.
  * @returns {object} the verdict written to disk
  */
-function writeVerdictFiles({ runDir, record, overallVerdict, chairText }) {
-  const verdict = buildVerdict(record, []);
+function writeVerdictFiles({ runDir, record, overallVerdict, chairText, critic, deadWaves }) {
+  // v4.5.2 — computed here rather than in run.js so verdict assembly stays in
+  // one place; see summarizeSeatLoss in ./verdict for why a lost critic has to
+  // reach the verdict at all.
+  const seatLoss = summarizeSeatLoss({ runId: record.meta.runId, critic, deadWaves });
+  const verdict = buildVerdict(record, [], { seatLoss });
   verdict.overallVerdict = (overallVerdict === undefined) ? null : overallVerdict;
   writeVerdictAtomic(path.join(runDir, 'verdict.json'), verdict);
   const html = buildReport({ verdict }, { format: 'html' });

package/src/council/run.js

@@ -284,7 +284,8 @@ async function runCouncil(options, deps = {}) {
     runState.updateStage(o.runDir, tallyStage, { status: 'complete', completedAt: now() });
     emitStageStarted(o.runDir, o.runId, tallyStage, null, o.follow);
     emitStageTerminal(o.runDir, o.runId, tallyStage, 'complete', null, o.follow);
-    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
+    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText,
+      critic: o.critic, deadWaves });
     runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
     emitStageStarted(o.runDir, o.runId, 'verdict', null, o.follow);
     emitStageTerminal(o.runDir, o.runId, 'verdict', 'complete', null, o.follow);

package/src/council/verdict.js

@@ -16,6 +16,44 @@ const VERDICT_SCHEMA_VERSION = 2;
  * @param {{overallVerdict?: (string|null)}} [opts] engine hook (Plan B): the
  *   parsed chair `VERDICT:` line; omitted/undefined → null.
  */
+/**
+ * Describe which requested seats actually reviewed, for the verdict's own face.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. The critic is a SOLO wave with one leg,
+ * so losing it loses 100% of the adversarial role — and unlike a dead bench wave
+ * (which trips the quorum gate and fails the run loudly) a dead critic is
+ * survivable, so the run continues to a full verdict, tally and chair synthesis
+ * that never saw the critic's findings. Run `dfb6a692` did exactly that and the
+ * only record was `deadWaves` in run.json, a file nobody opens when the verdict
+ * reads clean. A user who typed `--critic` asked for adversarial review; a
+ * verdict produced without it must say so where the verdict is read.
+ *
+ * Returns null when no critic was requested — there is nothing to report, and an
+ * always-present block would train readers to ignore it.
+ *
+ * @param {{runId: string, critic: ?string,
+ *   deadWaves: Array<{waveId: string, models: string[], reason: string}>}} o
+ * @returns {?{criticRequested: string, criticSeated: boolean, reason: ?string,
+ *   deadBenchSeats: string[]}}
+ */
+function summarizeSeatLoss({ runId, critic, deadWaves = [] } = {}) {
+  if (!critic) { return null; }
+  // Match on EITHER carrier. The `-c1` suffix is the convention run-stages.js
+  // uses, but a wave that names the critic model is the critic wave whatever it
+  // is called — and relying on the id alone would silently under-report if that
+  // convention ever changes.
+  const isCriticWave = w =>
+    w.waveId === `${runId}-c1` || (w.models || []).includes(critic);
+  const dead = deadWaves.find(isCriticWave) || null;
+  return {
+    criticRequested: critic,
+    criticSeated: !dead,
+    reason: dead ? dead.reason : null,
+    deadBenchSeats: deadWaves.filter(w => !isCriticWave(w))
+      .flatMap(w => w.models || []),
+  };
+}
+
 function buildVerdict(record, decisions = [], opts = {}) {
   const byId = new Map(decisions.map(d => [d.id, d]));
   return {
@@ -46,6 +84,9 @@ function buildVerdict(record, decisions = [], opts = {}) {
     streetCred: record.streetCred.map(s => ({ model: s.model, withSelf: s.withSelf, peersOnly: s.peersOnly })),
     runStats: record.runStats,
     tierCounts: record.tierCounts,
+    // Additive and OPTIONAL (schemaVersion stays 2): present only when a critic
+    // was requested, so its absence never has to be interpreted.
+    ...(opts.seatLoss ? { seatLoss: opts.seatLoss } : {}),
   };
 }
 
@@ -93,4 +134,6 @@ function writeVerdictAtomic(filePath, verdict) {
   fs.renameSync(tmp, filePath);
 }
 
-module.exports = { buildVerdict, readOverallVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION };
+module.exports = {
+  buildVerdict, summarizeSeatLoss, readOverallVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION,
+};

package/src/headless.js

@@ -272,6 +272,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       if (options.mcp) {
         serverOptions.mcp = options.mcp;
       }
+      // v4.5.2: explicit per-call override only — see the note at the matching
+      // hop in src/sidecar/session-utils.js. The default and the env knob both
+      // resolve downstream in buildServerOptions.
+      if (options.timeout !== undefined) {
+        serverOptions.timeout = options.timeout;
+      }
       // v4.4.1 fix wave (F5): this is the OTHER server-start site. It calls
       // startServer directly rather than going through startOpenCodeServer, so
       // the lock-class retry added for the concurrent-start race never covered

package/src/opencode-client.js

@@ -402,11 +402,67 @@ async function getSessionStatus(client, sessionId, directory) {
   return result.data || {};
 }
 
+/**
+ * How long to wait for OpenCode to announce it is listening, per platform.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. `@opencode-ai/sdk` defaults this to
+ * 5000ms (`dist/server.js:4-8`) and lets the caller override it; amicus never
+ * passed one, so every start on every platform ran on the SDK's 5s — untunable
+ * and invisible to `amicus doctor`. A reporter's Windows box (project on a
+ * OneDrive-synced volume, Defender active) blew through it on a cold
+ * OpenCode/SQLite open: the council's shared server failed to acquire, the run
+ * degraded to the per-wave configuration `src/council/run-server.js` exists to
+ * eliminate, and the whole Stage-1 bench died (`COUNCIL_QUORUM: Only 0 …`).
+ *
+ * The asymmetry decides the number: a slow start costs LATENCY, a failed start
+ * costs a REVIEW SEAT. win32 gets the widest window because that is where
+ * sync-backed volumes and always-on AV filter drivers are the norm.
+ *
+ * This is a ceiling, not a sleep — a healthy start still resolves in well under
+ * a second and pays none of it.
+ */
+const SERVER_START_TIMEOUT_MS = Object.freeze({ win32: 30000, default: 15000 });
+
+/**
+ * Resolve the start timeout: explicit option → env override → platform default.
+ *
+ * `0` and negatives are REJECTED rather than honored. For most amicus knobs `0`
+ * is a documented disable switch (see src/utils/env-num.js), but a 0ms start
+ * timeout disables nothing — it fails every start instantly. That is an own-goal
+ * an operator can only reach by accident, so it falls back to the default.
+ *
+ * @param {object} [options] - Server options ({timeout} respected if positive)
+ * @param {object} [env] - Environment (test seam; defaults to process.env)
+ * @param {string} [platform] - Platform (test seam; defaults to process.platform)
+ * @returns {number} milliseconds
+ */
+function resolveServerStartTimeoutMs(options = {}, env, platform) {
+  const plat = platform || process.platform;
+  const dflt = SERVER_START_TIMEOUT_MS[plat] || SERVER_START_TIMEOUT_MS.default;
+  const positive = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+  if (options.timeout !== undefined) {
+    const explicit = positive(options.timeout);
+    if (explicit) { return explicit; }
+  }
+  const raw = (env || process.env).AMICUS_SERVER_START_TIMEOUT_MS;
+  if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
+    const fromEnv = positive(raw);
+    if (fromEnv) { return fromEnv; }
+  }
+  return dflt;
+}
+
 /**
  * Build the server options object for createOpencodeServer.
  * Extracted for testability (no SDK dependency).
  *
  * @param {object} [options] - Server options
+ * @param {number} [options.timeout] - Start timeout in ms. Omit to use
+ *   AMICUS_SERVER_START_TIMEOUT_MS or the platform default; NEVER omitted from
+ *   the object handed to the SDK, so the SDK's own 5000ms default is unreachable.
  * @param {number} [options.port] - Port to run on
  * @param {string} [options.hostname='127.0.0.1'] - Hostname to bind to
  * @param {AbortSignal} [options.signal] - Abort signal to stop server
@@ -544,6 +600,9 @@ function buildServerOptions(options = {}) {
 
   const serverOptions = {
     hostname: options.hostname || '127.0.0.1',
+    // ALWAYS set — unlike port/signal below, an omitted timeout is not a
+    // harmless "let the SDK decide", it is the 5000ms that cost a bench.
+    timeout: resolveServerStartTimeoutMs(options),
   };
 
   // Only include port/signal when explicitly set — passing undefined
@@ -660,11 +719,27 @@ async function startServer(options = {}) {
     }
   }
 
-  const createOpencodeServer = await getCreateOpencodeServer();
+  // `_createOpencodeServer` is a test seam, matching `_hasOpencodeBinary` /
+  // `_ensureEngine` / `_opencodeRoots` above: the SDK arrives through a dynamic
+  // `import()`, which `jest.mock` cannot intercept under CommonJS, so the start
+  // path is otherwise unreachable from a unit test.
+  const createOpencodeServer = options._createOpencodeServer
+    || await getCreateOpencodeServer();
   const serverOptions = buildServerOptions(options);
 
+  // Measure the healthy path. The v4.5.2 timeout had to be sized from the
+  // asymmetry of the failure (a slow start costs latency, a failed one costs a
+  // review seat) because nothing recorded how long a GOOD start takes — so the
+  // margin against the ceiling was unmeasurable on exactly the slow boxes that
+  // needed it. Now it is one debug line, not an inference.
+  const startedAt = Date.now();
   const sdkServer = await createOpencodeServer(serverOptions);
-  const client = await createClient(sdkServer.url);
+  const { logger } = require('./utils/logger');
+  logger.debug('OpenCode server started', {
+    startMs: Date.now() - startedAt,
+    timeoutMs: serverOptions.timeout,
+  });
+  const client = await (options._createClient || createClient)(sdkServer.url);
 
   // Capture the Go server PID once so close() can force-kill it cross-platform
   // (F3 #15). Prefer a PID the SDK exposes; fall back to the port listener.
@@ -822,6 +897,8 @@ module.exports = {
   abortSession,
   checkHealth,
   buildServerOptions,
+  resolveServerStartTimeoutMs,
+  SERVER_START_TIMEOUT_MS,
   buildServerHandle,
   startServer,
   loadMcpConfig,

package/src/sidecar/session-utils.js

@@ -253,6 +253,10 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.models) { serverOptions.models = options.models; }
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
+  // Explicit per-call override only. Unset is the normal case and is correct:
+  // buildServerOptions resolves AMICUS_SERVER_START_TIMEOUT_MS / the platform
+  // default downstream, so forwarding `undefined` here would change nothing.
+  if (options.timeout !== undefined) { serverOptions.timeout = options.timeout; }
 
   // v4.4.1 Task 0.5: a LOCK-CLASS start failure is retried (5 attempts,
   // 250/500/1000/2000ms — widened from 3/750ms by Step 10.5, see server-setup).

package/src/sidecar/unzip.js

@@ -173,7 +173,22 @@ async function robustExtract(zip, opts = {}) {
     deps = {},
   } = opts;
   const fs = deps.fs || fsDefault;
-  const extractZip = deps.extractZip || require('extract-zip');
+  // GUARDED (v4.5.2). This `require` used to be bare, and `extract-zip` was
+  // never declared in dependencies — it resolved in the dev tree only because
+  // `puppeteer` (a devDependency) pulls it transitively, so a published install
+  // threw MODULE_NOT_FOUND here and took the WHOLE function with it: the native
+  // fallback below, the bounded idle/max timers, and `doctor --fix` all became
+  // unreachable. The dependency is now declared, so this should never fire —
+  // but Strategy 1 being unavailable is precisely what the native strategies
+  // exist for, so it must degrade into them rather than out of the function.
+  let extractZip = deps.extractZip;
+  if (!extractZip) {
+    try {
+      extractZip = require('extract-zip');
+    } catch (e) {
+      extractZip = () => { throw new Error(`extract-zip unavailable: ${e.message}`); };
+    }
+  }
   const spawn = deps.spawn || spawnSync;
   const setTimer = deps.setTimeout || setTimeout;
   const clearTimer = deps.clearTimeout || clearTimeout;

package/src/utils/known-flags.js

@@ -0,0 +1,90 @@
+// src/utils/known-flags.js
+'use strict';
+
+/**
+ * @module utils/known-flags
+ * The set of `--flags` amicus accepts, and the check that rejects the rest.
+ *
+ * WHY THIS EXISTS. `parseArgs` (src/cli.js) treats ANY `--token` as a flag: an
+ * unrecognized one lands on the parsed object, no handler reads it, and the
+ * command proceeds as if it were never typed. Found in the field while smoke-
+ * testing v4.5.2 — `amicus start -m deepseek --prompt "…" --headless` printed no
+ * error and exited 0, but `start` has no `--headless`. The run silently took the
+ * INTERACTIVE path, ignored `-m`, and left a session running against the default
+ * model. A typo (`--modl`), a flag borrowed from another command, or an invented
+ * one all behave the same way, and an unknown flag followed by a positional
+ * SWALLOWS it as its value.
+ *
+ * amicus already handles an unknown COMMAND correctly — error, "Did you mean",
+ * usage, exit 1. This gives flags the same treatment.
+ *
+ * DERIVED, NOT HAND-MAINTAINED. The bulk of the set is scraped from the usage
+ * text, which is the same source `getCommandNames()` uses and for the same
+ * stated reason: a second hand-maintained list would rot out of sync with the
+ * first. Only flags that are deliberately absent from usage are listed here, and
+ * each says why.
+ */
+
+/**
+ * Real flags that appear in NO usage block. Rejecting any of these would break
+ * working callers, so they are enumerated deliberately rather than derived.
+ *
+ * ⚠️ The first four are spawned by the MCP server onto its own CLI children
+ * (src/mcp-server.js, src/mcp-council-run.js). They are not user-facing and are
+ * intentionally undocumented — but they are on the argv of every MCP-launched
+ * run, so rejecting them would break the entire MCP surface.
+ */
+const INTERNAL_FLAGS = new Set([
+  'task-id',         // MCP → `start`/`continue`: pins the child's task id
+  'run-id',          // MCP → `council run`: pins the child's run id
+  'council-name',    // MCP → `council run`: preset name for ledger attribution
+  'cowork-process',  // MCP → `start`: Cowork process handle for context capture
+
+  // User-facing but undocumented, and read by real handlers today. Listed so the
+  // rejection is a bug fix and not a silent removal of working behaviour; if any
+  // of these should be dropped, that is a separate, deliberate change.
+  'briefing',        // src/cli-handlers-resume-continue.js — alias for --prompt
+  'mode',            // src/cli-handlers-run.js — legacy alias for --agent
+  'quiet',           // src/cli-handlers.js — suppresses the interactive prompt
+  'help',            // handled before dispatch; never reaches a usage block body
+]);
+
+/**
+ * Every flag amicus accepts: usage-derived ∪ boolean flags ∪ INTERNAL_FLAGS.
+ *
+ * Computed on each call rather than cached at module load, because `getUsage()`
+ * is itself composed at call time and a cached copy would pin whatever the first
+ * caller happened to see.
+ *
+ * @returns {Set<string>} kebab-case flag names, without the leading `--`
+ */
+function getKnownFlags() {
+  // Required lazily: src/cli.js is the module that will consume this one, and a
+  // top-level require here would close a cycle.
+  const { getUsage, getBooleanFlags } = require('../cli');
+  const known = new Set(INTERNAL_FLAGS);
+  for (const m of getUsage().matchAll(/--([a-z][a-z0-9-]*)/gi)) {
+    known.add(m[1].toLowerCase());
+  }
+  for (const f of getBooleanFlags()) { known.add(f); }
+  return known;
+}
+
+/**
+ * The unknown flags present on a parsed-argv object, in the order they were
+ * typed.
+ *
+ * Reads `__explicit` — the set parseArgs fills with every key it saw on the
+ * command line — so defaults (which are merged in from DEFAULTS and were never
+ * typed) are correctly ignored.
+ *
+ * @param {object} parsed result of parseArgs()
+ * @returns {string[]} kebab-case flag names, without the leading `--`
+ */
+function unknownFlags(parsed) {
+  if (!parsed || !parsed.__explicit) { return []; }
+  const known = getKnownFlags();
+  return [...parsed.__explicit].filter(f => !known.has(String(f).toLowerCase()));
+}
+
+module.exports = { getKnownFlags, unknownFlags, INTERNAL_FLAGS };