create-claude-cabinet 0.45.0 → 0.47.0

package/templates/scripts/watchtower-queue.mjs

@@ -4,15 +4,33 @@
 // All writes use atomic temp+rename per watchtower-contracts.md.
 // Queue uses directory listing, not index files (no-index convention).
 
-import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, renameSync } from 'fs';
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, renameSync, unlinkSync, realpathSync } from 'fs';
 import { join } from 'path';
 import { randomBytes } from 'crypto';
+import { pathToFileURL } from 'url';
 
 const WATCHTOWER_DIR = process.env.WATCHTOWER_DIR
   || join(process.env.HOME, '.claude-cabinet', 'watchtower');
 
 const QUEUE_DIR = join(WATCHTOWER_DIR, 'queue', 'items');
 
+// mux's dispatch queue (bin/mux `qa` verbs — the single desk-dispatch path,
+// carrying qa-handoffs AND routine dispatches). Descriptors are routing
+// convenience keyed <desk>/<item_id>.json (plus <desk>/in-flight/ once
+// drained); the inbox item is the durable record. Terminal exits here must
+// clear the matching descriptor or the two stores drift (act:796fe6dc —
+// resolved ghosts get re-offered by `mux qa drain`). The dir name is legacy.
+const MUX_QA_DIR = process.env.MUX_QA_DIR
+  || join(process.env.HOME, '.local', 'share', 'mux', 'qa-handoff');
+
+// Categories whose items are pushed to a desk via the mux dispatch queue.
+// Every terminal exit (resolve / dismiss / supersede / expire) on an item in
+// one of these categories clears its dispatch descriptor(s). Exported so
+// consumers (e.g. the /session-handoff epilogue drain) exclude dispatched
+// items by importing this set rather than re-listing categories in prose —
+// a hand-maintained copy would drift the moment a third category is added.
+export const DISPATCHED_CATEGORIES = new Set(['qa-handoff', 'routine']);
+
 // --- Helpers ---
 
 function ensureDir(dir) {
@@ -42,6 +60,27 @@ function generateId() {
   return 'dec-' + randomBytes(4).toString('hex');
 }
 
+// Best-effort removal of the mux dispatch-queue descriptor(s) for an item —
+// both the queued copy and the in-flight copy, across every desk dir (desk
+// names differ from project names, so we sweep rather than guess). Never
+// throws: a routing-cleanup failure must not block a gate exit. The ·N badge
+// is recomputed by mux on its next mutation/desk-open, so a deletion here is
+// picked up without tmux involvement.
+function clearDispatchEntries(item) {
+  try {
+    if (!existsSync(MUX_QA_DIR)) return;
+    for (const desk of readdirSync(MUX_QA_DIR, { withFileTypes: true })) {
+      if (!desk.isDirectory()) continue;
+      for (const sub of ['.', 'in-flight']) {
+        const fp = join(MUX_QA_DIR, desk.name, sub, `${item.id}.json`);
+        try {
+          if (existsSync(fp)) unlinkSync(fp);
+        } catch { /* best-effort per file */ }
+      }
+    }
+  } catch { /* best-effort overall */ }
+}
+
 // Urgency sort order: urgent < normal < low (urgent first)
 const URGENCY_ORDER = { urgent: 0, normal: 1, low: 2 };
 
@@ -55,8 +94,26 @@ const URGENCY_ORDER = { urgent: 0, normal: 1, low: 2 };
 // sin, a silent stamp with no coverage look, is impossible rather than
 // discouraged. Keep all qa-handoff domain knowledge fenced here; the CRUD
 // functions below only call into it.
+//
+// merge_state (evidence.merge_state): a handoff is normally filed AFTER the
+// worktree branch merged ('merged' — the original and default contract). A
+// handoff filed BEFORE the merge (the operator is gating the merge on an
+// in-flight staging deploy) carries 'merge-pending': the skill defers stage-2
+// dispatch and the pickup prompt says "merge then QA" instead of asserting a
+// merge — no more hand-flagging merged_into: "PENDING". The recipient gate is
+// unchanged: a merge-pending handoff still resolves only through a stamped
+// qa_verdict, cited against the post-merge commit once the merge has happened.
 
 const QA_CATEGORY = 'qa-handoff';
+
+// Categories whose items carry a structural recipient gate: they may never be
+// included in a batch disposition — each leaves the queue only through its own
+// gate (per-item resolve with a validated verdict, or a typed per-item
+// dismissal). Distinct from DISPATCHED_CATEGORIES: 'routine' is dispatched but
+// NOT gated — stale routines are legal batch fodder. Future gated categories
+// join this set and inherit batch refusal for free.
+export const GATED_CATEGORIES = new Set([QA_CATEGORY]);
+
 const QA_TERMINAL_VERDICTS = ['runtime-verified', 'blocked'];
 // The parameterized token. Canonical form uses U+00B7 (·); input tolerates
 // common separator drift (-, –, —, *, •) because sessions retype labels.
@@ -82,6 +139,28 @@ export function normalizeQaVerdictToken(raw) {
   return null;
 }
 
+// The two legal merge states for a qa-handoff item.
+export const QA_MERGE_STATES = ['merged', 'merge-pending'];
+
+/**
+ * Normalize a qa-handoff merge_state token to canonical form.
+ * Absent (null/undefined) defaults to 'merged' — the original contract, where
+ * a handoff was always filed AFTER the worktree branch merged. A handoff filed
+ * before the merge carries 'merge-pending'. Tolerates separator/case drift
+ * (merge_pending, "merge pending", pending, unmerged); returns null only for a
+ * present-but-illegal token, so a typo cannot silently read as 'merged'.
+ * @param {*} raw
+ * @returns {'merged'|'merge-pending'|null}
+ */
+export function normalizeMergeState(raw) {
+  if (raw == null) return 'merged';
+  if (typeof raw !== 'string') return null;
+  const t = raw.normalize('NFKC').trim().toLowerCase().replace(/[\s_]+/g, '-');
+  if (t === 'merged') return 'merged';
+  if (['merge-pending', 'mergepending', 'pending', 'unmerged'].includes(t)) return 'merge-pending';
+  return null;
+}
+
 function gateError(item, message) {
   // Never echo resolution/notes content back — name fields only.
   return new Error(`qa-handoff gate: cannot close ${item.id} — ${message}`);
@@ -238,6 +317,82 @@ export function emitPatternPromotion({
   });
 }
 
+// --- High-confidence sign-off predicate (bulk-triage batching) ---
+//
+// Most pending items are knowledge-extraction items the rings already DRAFTED
+// (Ring 3 mints a memory `draft_artifact` from the session transcript). These
+// aren't judgment calls — they're SIGN-OFFS on work the system already did.
+// Because each is uniquely titled, title-grouping degrades bulk triage to a
+// per-item walk, burning the same decision fuel on a sign-off as on a hard
+// choice. The predicate below isolates that class so bulk triage can offer it
+// as ONE explicit batch sign-off (still human-confirmed — never auto-resolved;
+// the frozen-at-propose invariant holds because the operator approves the
+// whole batch before any applyBatch write).
+//
+// The signal reuses the SAME "drafts ready" cue the SessionStart context
+// builder already counts (watchtower-build-context.mjs: knowledge-extraction +
+// non-empty draft_artifact) — single source for "the system pre-authored this".
+// An item is held back for individual attention (NOT signed off in a batch)
+// when it is urgent, low-confidence, or carries no pre-drafted artifact —
+// those are the ones that actually want a human look. Gated categories
+// (qa-handoff) are never high-confidence sign-off by construction: they exit
+// only through their own recipient gate.
+
+// Categories whose pre-drafted, normal-priority items are sign-off-shaped.
+// Today only knowledge-extraction (Ring 3's memory drafts). A future
+// pre-drafted category joins here and inherits batch sign-off for free.
+const SIGNOFF_CATEGORIES = new Set(['knowledge-extraction']);
+
+/**
+ * True when an item is a high-confidence SIGN-OFF — pre-drafted work the
+ * system already did, safe to approve as part of an explicit one-shot batch
+ * rather than as its own micro-decision. False for anything that wants an
+ * individual human look (urgent, low-confidence, or no pre-drafted artifact)
+ * and for any gated-category item (those leave only through their own gate).
+ *
+ * Conservative by design: when in doubt the item is surfaced individually.
+ * The operator still confirms the whole batch before any write — this only
+ * decides WHICH items are eligible to ride in a batch sign-off.
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function isHighConfidenceSignoff(item) {
+  if (!item || typeof item !== 'object') return false;
+  if (item.status && item.status !== 'pending') return false;
+  if (GATED_CATEGORIES.has(item.category)) return false;
+  if (!SIGNOFF_CATEGORIES.has(item.category)) return false;
+  // The system must have actually drafted something — a non-empty artifact is
+  // the proof the work is done and only needs a sign-off.
+  if (typeof item.draft_artifact !== 'string' || !item.draft_artifact.trim()) return false;
+  // Urgent items want eyes, not a batch nod.
+  if (item.urgency === 'urgent') return false;
+  // An explicit low-confidence stamp means "look at this one".
+  if (item.confidence === 'low') return false;
+  return true;
+}
+
+/**
+ * Partition pending items into the high-confidence sign-off set (eligible for
+ * a one-shot batch approval) and the individual set (everything that wants a
+ * human look — unusual / low-confidence items AND every gated item). Gated
+ * items are ALWAYS individual: the predicate excludes them, so they can never
+ * leak into the batch, and applyBatch would reject them anyway.
+ *
+ * Pure read helper — no writes, no I/O. Bulk triage uses it to decide what to
+ * offer as a batch vs. one by one; the operator still approves the batch.
+ * @param {Array} items - pending inbox items (e.g. from listPending())
+ * @returns {{signoff: Array, individual: Array}}
+ */
+export function partitionForBatchSignoff(items) {
+  const signoff = [];
+  const individual = [];
+  for (const item of Array.isArray(items) ? items : []) {
+    if (isHighConfidenceSignoff(item)) signoff.push(item);
+    else individual.push(item);
+  }
+  return { signoff, individual };
+}
+
 // --- Exports ---
 
 /**
@@ -265,6 +420,38 @@ export function createItem({
   desk = null,
 }) {
   ensureDir(QUEUE_DIR);
+  // qa-handoff merge_state is structural: a present-but-illegal token is
+  // rejected at the boundary (it can't silently read as 'merged'), and a legal
+  // one is canonicalized. Absent stays absent — readers default to 'merged'
+  // via normalizeMergeState (additive-field discipline, like desk/project_
+  // unresolved). Only qa-handoff items carry it; other categories are untouched.
+  if (category === QA_CATEGORY && evidence && evidence.merge_state !== undefined) {
+    const ms = normalizeMergeState(evidence.merge_state);
+    if (!ms) {
+      throw new Error(`createItem: illegal qa-handoff merge_state ${JSON.stringify(evidence.merge_state)} — must be one of: ${QA_MERGE_STATES.join(' | ')}`);
+    }
+    evidence = { ...evidence, merge_state: ms };
+  }
+  // A 'merged' handoff must reference work actually on main. merge_state
+  // replaced the old hand-flagged `merged_into: "PENDING — not yet merged"`
+  // antipattern, but a producer can still free-text a not-yet-merged marker
+  // into merged_into/merged_commit while leaving merge_state at its 'merged'
+  // default — handing off UNMERGED work the drain is then told to merge
+  // (field incident 2026-06-17). Reject it at the boundary: a pending marker
+  // means the merge has not happened, so the honest state is
+  // merge_state:'merge-pending' (which defers stage-2 dispatch), never a
+  // 'merged' handoff. Pure string check; the drain's Step 0 does the
+  // git-ancestry verification of merged_commit. (act:e859b3a3)
+  if (category === QA_CATEGORY && evidence
+      && normalizeMergeState(evidence.merge_state) === 'merged') {
+    const NOT_YET_MERGED = /\b(pending|unmerged|not[\s-]*yet[\s-]*merged|to[\s-]*be[\s-]*merged|will[\s-]*merge)\b/i;
+    for (const k of ['merged_into', 'merged_commit']) {
+      const v = evidence[k];
+      if (typeof v === 'string' && NOT_YET_MERGED.test(v)) {
+        throw new Error(`createItem: qa-handoff filed as 'merged' but evidence.${k} flags the merge as not yet done (${JSON.stringify(v.slice(0, 60))}) — merge the branch first, or file with merge_state:'merge-pending' (which defers stage-2 dispatch). A 'merged' handoff must reference work actually on main.`);
+      }
+    }
+  }
   const id = generateId();
   const item = {
     schema_version: 1,
@@ -326,6 +513,7 @@ export function resolveItem(id, { resolution, resolution_notes = null, resolutio
   item.resolution_type = resolution_type;
   item.resolution_notes = resolution_notes;
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
@@ -349,6 +537,7 @@ export function dismissItem(id, { notes = null, resolution_type = null } = {}) {
   item.resolution_type = resolution_type;
   item.resolution_notes = notes;
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
@@ -368,6 +557,7 @@ export function supersedeItem(id, { reason = null } = {}) {
   item.status = 'superseded';
   item.resolution_notes = reason;
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
@@ -386,9 +576,64 @@ export function expireItem(id) {
   item.status = 'expired';
   item.resolution_notes = 'Auto-expired by age policy';
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
+/**
+ * Apply ONE disposition to a batch of ungated items — the single bulk path,
+ * used by /briefing's batch dispositions and /inbox's bulk triage. A batch is one
+ * operator decision applied to many items, so the typed reason is REQUIRED:
+ * it lands on every item as its audit trail.
+ *
+ * All-or-nothing pre-validation: throws BEFORE any write when (a) any id is
+ * unknown, (b) any item is in a GATED_CATEGORIES category — gated items never
+ * batch; each goes through its own gate — or (c) the typed reason is absent.
+ * A batch that would hit a gate fails whole, never half-applies.
+ * Non-pending items are not an error (another session may have raced the
+ * disposition); they are skipped and reported.
+ * @param {string[]} ids
+ * @param {object} params
+ * @param {'dismiss'|'resolve'} params.disposition
+ * @param {string} params.resolution_type - typed reason (e.g. 'stale',
+ *   'noise', 'captured-to-memory', 'acted-on') — required
+ * @param {string} params.notes - plain-language reason — required
+ * @param {string} [params.resolution] - resolve batches: the resolution
+ *   value stamped on each item (defaults to resolution_type)
+ * @returns {{applied: string[], skipped_not_pending: string[]}}
+ */
+export function applyBatch(ids, { disposition, resolution_type, notes, resolution = null } = {}) {
+  if (!Array.isArray(ids) || ids.length === 0) {
+    throw new Error('applyBatch: ids must be a non-empty array');
+  }
+  if (disposition !== 'dismiss' && disposition !== 'resolve') {
+    throw new Error("applyBatch: disposition must be 'dismiss' or 'resolve'");
+  }
+  if (typeof resolution_type !== 'string' || !resolution_type.trim()
+      || typeof notes !== 'string' || !notes.trim()) {
+    throw new Error('applyBatch: a typed resolution_type AND notes are required — a batch is one decision applied to many items, and the reason lands on every one');
+  }
+  const items = ids.map((id) => {
+    const item = getItem(id);
+    if (!item) throw new Error(`applyBatch: unknown item ${id} — batches pre-validate whole; nothing was applied`);
+    return item;
+  });
+  const gated = items.filter((i) => GATED_CATEGORIES.has(i.category));
+  if (gated.length > 0) {
+    throw new Error(`applyBatch: ${gated.map((i) => `${i.id} (${i.category})`).join(', ')} carr${gated.length === 1 ? 'ies' : 'y'} a recipient gate — gated items never batch; handle each through its own gate. Nothing was applied`);
+  }
+  const applied = [];
+  const skipped_not_pending = [];
+  for (const item of items) {
+    const result = disposition === 'dismiss'
+      ? dismissItem(item.id, { notes, resolution_type })
+      : resolveItem(item.id, { resolution: resolution ?? resolution_type, resolution_notes: notes, resolution_type });
+    if (result) applied.push(item.id);
+    else skipped_not_pending.push(item.id);
+  }
+  return { applied, skipped_not_pending };
+}
+
 /**
  * List pending inbox items with optional filters.
  * @param {object} filters
@@ -425,6 +670,46 @@ export function listPending({ project, category, urgency, maxAge } = {}) {
   return items;
 }
 
+/**
+ * List inbox items across ALL statuses with optional filters — the single
+ * source for "read non-pending items". Ring 2's private readAllQueueItems
+ * fork (which predated this helper) was deleted and now reads through this
+ * helper (act:3975348f).
+ * @param {object} filters
+ * @param {string} [filters.project] - exact match on item.project
+ * @param {string} [filters.category] - exact match on item.category
+ * @param {string[]} [filters.statuses] - keep items whose status is in the
+ *   array (omit = all statuses)
+ * @param {string} [filters.since] - ISO date; keep items whose
+ *   `resolved_at || filed_at` >= since (bounds corpus growth for dedup callers)
+ * @returns {Array} items sorted newest first by (resolved_at || filed_at)
+ */
+export function listItems({ project, category, statuses, since } = {}) {
+  if (!existsSync(QUEUE_DIR)) return [];
+  const sinceMs = since ? new Date(since).getTime() : null;
+  const entries = readdirSync(QUEUE_DIR, { withFileTypes: true });
+  const items = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    try {
+      const item = readItem(join(QUEUE_DIR, entry.name));
+      if (project && item.project !== project) continue;
+      if (category && item.category !== category) continue;
+      if (Array.isArray(statuses) && !statuses.includes(item.status)) continue;
+      if (sinceMs != null) {
+        const ts = new Date(item.resolved_at || item.filed_at).getTime();
+        if (!(ts >= sinceMs)) continue;
+      }
+      items.push(item);
+    } catch {
+      // Skip unparseable items
+    }
+  }
+  items.sort((a, b) =>
+    new Date(b.resolved_at || b.filed_at) - new Date(a.resolved_at || a.filed_at));
+  return items;
+}
+
 /**
  * Get a single inbox item by id.
  * @param {string} id
@@ -490,6 +775,7 @@ export function runExpiry({ warnDays = 14, expireDays = 30 } = {}) {
       item.status = 'expired';
       item.resolution_notes = `Auto-expired after ${expireDays} days. If still relevant, re-file with updated context.`;
       atomicWrite(itemPath(item.id), item);
+      if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
       expired.push(item);
     } else if (age >= warnMs) {
       warned.push(item);
@@ -498,3 +784,200 @@ export function runExpiry({ warnDays = 14, expireDays = 30 } = {}) {
 
   return { warned, expired };
 }
+
+// --- CLI ---
+//
+// watchtower-queue.mjs is primarily a LIBRARY (every other caller `import`s it).
+// It also exposes ONE operator-invoked subcommand — `resolve` — so a qa-handoff
+// verdict can be stamped from a JSON file instead of an inline
+// `node -e '<...>'` whose single-quoted string the shell breaks on apostrophes
+// in justification text (that hazard hit the drain station EVERY time;
+// act:00030e1d). The verdict file is the FULL resolveItem params object
+// {resolution, resolution_type, resolution_notes, qa_verdict} — apostrophes
+// live in resolution_notes AND qa_verdict.confessed_gap.deferred[].justification,
+// so a verdict-only file would leave notes inline and the hazard would survive.
+// The qa_verdict SHAPE itself is single-sourced in the qa-handoff skill's
+// "The recipient gate"; this CLI adds no validation — it reuses resolveItem
+// (and its validateQaVerdict gate) verbatim.
+//
+// Exit policy (operator-invoked → fail LOUD; the INVERSE of the hook-invoked
+// watchtower-snapshot.mjs, which swallows everything with exit 0):
+//   0  resolved (or resolved-but-could-not-read-back-to-confirm)
+//   1  well-formed call could not proceed: item not found, item not pending,
+//      or the recipient gate rejected the verdict (item left pending)
+//   2  malformed INVOCATION: bad args, missing/unreadable/non-JSON/non-object
+//      verdict file, or an unknown top-level key
+// NOTE: this 1/2 mapping is the OPPOSITE of the sibling watchtower-lib.mjs CLI
+// (there 1=usage, 2=operational). The taxonomy here follows the sysexits /
+// argparse convention — 2 means the invocation itself is malformed — and the
+// divergence from watchtower-lib is deliberate, not an oversight.
+
+const RESOLVE_PARAM_KEYS = ['resolution', 'resolution_type', 'resolution_notes', 'qa_verdict'];
+
+class UsageError extends Error {}
+
+/**
+ * Parse `resolve <id> --verdict-file <path>` argv into {id, verdictFile}.
+ * Pure (no I/O) so it is unit-testable. Throws UsageError on any malformed
+ * form — a missing value, an id that looks like a flag, a repeated or unknown
+ * flag, or an extra positional — so the CLI maps every one to exit 2 rather
+ * than silently consuming it and failing later. Accepts both
+ * `--verdict-file <path>` and `--verdict-file=<path>`.
+ * @param {string[]} argv  full process.argv ([node, script, 'resolve', ...])
+ * @returns {{id: string, verdictFile: string}}
+ */
+export function parseResolveArgs(argv) {
+  const args = argv.slice(3); // drop [node, script, 'resolve']
+  let id = null;
+  let verdictFile = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--verdict-file' || a.startsWith('--verdict-file=')) {
+      if (verdictFile !== null) throw new UsageError('--verdict-file given more than once');
+      if (a.startsWith('--verdict-file=')) {
+        verdictFile = a.slice('--verdict-file='.length);
+      } else {
+        verdictFile = args[i + 1];
+        i++;
+      }
+      if (typeof verdictFile !== 'string' || verdictFile === '' || verdictFile.startsWith('-')) {
+        throw new UsageError('--verdict-file requires a path argument');
+      }
+    } else if (a.startsWith('-')) {
+      throw new UsageError(`unknown flag: ${a}`);
+    } else if (id === null) {
+      id = a;
+    } else {
+      throw new UsageError(`unexpected extra argument: ${a}`);
+    }
+  }
+  if (id === null || id.trim() === '') throw new UsageError('missing <id> (the inbox item id, e.g. dec-abcd1234)');
+  if (verdictFile === null) throw new UsageError('missing --verdict-file <path>');
+  return { id, verdictFile };
+}
+
+/**
+ * Run the `resolve` subcommand: read the verdict-params JSON file, call
+ * resolveItem, then read the item back from disk to confirm the stamp. Returns
+ * the process exit code per the policy above; never throws (each failure mode
+ * is mapped to a code with a distinct, non-misleading message).
+ * @param {string[]} argv  full process.argv
+ * @returns {number} exit code
+ */
+export function runResolveCli(argv) {
+  let id;
+  let verdictFile;
+  try {
+    ({ id, verdictFile } = parseResolveArgs(argv));
+  } catch (err) {
+    process.stderr.write(`resolve: ${err.message}\n`);
+    process.stderr.write('usage: watchtower-queue.mjs resolve <id> --verdict-file <path.json>\n');
+    return 2;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(verdictFile, 'utf8');
+  } catch (err) {
+    process.stderr.write(err.code === 'ENOENT'
+      ? `resolve: verdict file not found: ${verdictFile}\n`
+      : `resolve: cannot read verdict file ${verdictFile}: ${err.message}\n`);
+    return 2;
+  }
+
+  let params;
+  try {
+    params = JSON.parse(raw);
+  } catch (err) {
+    process.stderr.write(`resolve: invalid JSON in ${verdictFile}: ${err.message}\n`);
+    return 2;
+  }
+
+  // typeof null === 'object' AND typeof [] === 'object' — guard both explicitly,
+  // or an array/null file would reach resolveItem and mis-resolve (exit 1)
+  // instead of being caught here as a malformed invocation (exit 2).
+  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+    process.stderr.write(`resolve: ${verdictFile} must be a JSON object of resolve params {${RESOLVE_PARAM_KEYS.join(', ')}}\n`);
+    return 2;
+  }
+
+  // resolveItem destructures exactly the 4 RESOLVE_PARAM_KEYS and JSON.stringify
+  // drops undefined — so a typo'd key (e.g. resolution_note) would be SILENTLY
+  // dropped, leaving the item resolved with a missing note and no warning. The
+  // non-qa path has no gate at all. Reject unknown keys here so a typo fails
+  // loud instead of vanishing.
+  const unknown = Object.keys(params).filter((k) => !RESOLVE_PARAM_KEYS.includes(k));
+  if (unknown.length > 0) {
+    process.stderr.write(`resolve: unknown key(s) in ${verdictFile}: ${unknown.join(', ')} — allowed: ${RESOLVE_PARAM_KEYS.join(', ')} (an unrecognized key is silently dropped, so this is rejected)\n`);
+    return 2;
+  }
+
+  let item;
+  try {
+    item = resolveItem(id, params);
+  } catch (err) {
+    // Three distinct throw sources, and only the gate's message is safe to echo:
+    if (err.code === 'ENOENT') {
+      // missing item file — friendly, and never leak the absolute queue path.
+      process.stderr.write(`resolve: item ${id} not found\n`);
+    } else if (typeof err.message === 'string' && err.message.startsWith('qa-handoff gate:')) {
+      // recipient-gate rejection (gateError) — names the offending field and
+      // embeds NO item content or path, so surface it verbatim. The item is
+      // left pending (validateQaVerdict throws before the atomicWrite).
+      process.stderr.write(`resolve: ${err.message}\n`);
+    } else {
+      // anything else — a corrupt/wrong-schema item file (readItem) or a write
+      // failure (atomicWrite) — embeds the ABSOLUTE queue path in err.message.
+      // Do NOT echo it; name only the id and the error code.
+      process.stderr.write(`resolve: could not resolve item ${id} (${err.code || 'unexpected error'})\n`);
+    }
+    return 1;
+  }
+
+  if (item === null) {
+    let status = 'not pending';
+    try {
+      const cur = getItem(id);
+      if (cur && cur.status) status = cur.status;
+    } catch { /* best-effort status lookup for the message only */ }
+    process.stderr.write(`resolve: ${id} is not pending (status: ${status}) — an earlier stamp is intact, nothing to do\n`);
+    return 1;
+  }
+
+  // Verify the write by re-reading from disk, not trusting the in-memory return
+  // (verify-your-own-writes). A read-back failure must NOT read as a resolve
+  // failure — the stamp already landed (resolveItem's atomicWrite returned).
+  try {
+    const stored = getItem(id);
+    const token = stored && stored.qa_verdict && stored.qa_verdict.verdict
+      ? stored.qa_verdict.verdict
+      : (stored && stored.resolution) || '(resolved)';
+    const notes = stored && stored.resolution_notes ? 'present' : 'absent';
+    process.stdout.write(`resolved ${id} — verdict: ${token}; resolution_notes: ${notes}\n`);
+  } catch (err) {
+    process.stdout.write(`resolved ${id}, but could not read it back to confirm: ${err.message}\n`);
+  }
+  return 0;
+}
+
+// Entry guard — importing this module must NOT run the CLI (mirrors the ring
+// scripts and watchtower-snapshot.mjs so tests can import the pure functions).
+const isMain = (() => {
+  try {
+    return process.argv[1]
+      && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  const sub = process.argv[2];
+  if (sub === 'resolve') {
+    process.exit(runResolveCli(process.argv));
+  } else {
+    process.stderr.write(`watchtower-queue.mjs: unknown command ${sub ? `'${sub}'` : '(none)'}\n`);
+    process.stderr.write('usage: watchtower-queue.mjs resolve <id> --verdict-file <path.json>\n');
+    process.exit(2);
+  }
+}