akm-cli 0.8.7 → 0.8.14

package/dist/commands/lint/index.js

@@ -4,12 +4,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
-import { resolveStashDir } from "../../core/common";
-import { loadConfig } from "../../core/config";
-import { parseFrontmatter } from "../../core/frontmatter";
-import { resolveSourceEntries } from "../../indexer/search-source";
-import { checkVaultForDangerousKeys } from "./env-key-rules";
-import { getLinterForType } from "./registry";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { resolveStashDir } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { checkEnvForDangerousKeys } from "./env-key-rules.js";
+import { getLinterForType } from "./registry.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 const STASH_SUBDIRS = [
     "agents",
@@ -154,27 +154,21 @@ export function akmLint(options = {}) {
         }
     }
     // ── Env dangerous-key pass ─────────────────────────────────────────────────
-    // Scan every `.env` file under <stashRoot>/env/ (and the deprecated
-    // <stashRoot>/vaults/) across all stash roots for keys that are known to
-    // enable process-execution hijacking. Warn-only — findings go into `flagged`,
-    // never `fixed`.
+    // Scan every `.env` file under <stashRoot>/env/ across all stash roots for
+    // keys that are known to enable process-execution hijacking. Warn-only —
+    // findings go into `flagged`, never `fixed`.
     const envRoots = [stashRoot, ...extraStashRoots];
     for (const root of envRoots) {
-        for (const [subdir, prefix] of [
-            ["env", "env"],
-            ["vaults", "vault"],
-        ]) {
-            const dir = path.join(root, subdir);
-            if (!fs.existsSync(dir))
-                continue;
-            for (const envPath of collectEnvFiles(dir)) {
-                const baseName = path.basename(envPath, ".env");
-                // "default" (or empty) maps to ".env" → <prefix>:default
-                const ref = baseName === "" ? `${prefix}:default` : `${prefix}:${baseName}`;
-                const relPath = path.relative(root, envPath);
-                for (const issue of checkVaultForDangerousKeys(envPath, relPath, ref)) {
-                    flagged.push(issue);
-                }
+        const dir = path.join(root, "env");
+        if (!fs.existsSync(dir))
+            continue;
+        for (const envPath of collectEnvFiles(dir)) {
+            const baseName = path.basename(envPath, ".env");
+            // "default" (or empty) maps to ".env" → env:default
+            const ref = baseName === "" ? "env:default" : `env:${baseName}`;
+            const relPath = path.relative(root, envPath);
+            for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
+                flagged.push(issue);
             }
         }
     }

package/dist/commands/lint/knowledge-linter.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `knowledge/` assets.
  *

package/dist/commands/lint/memory-linter.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
-import { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `memories/` assets.
  *

package/dist/commands/lint/registry.js

@@ -1,14 +1,14 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { AgentLinter } from "./agent-linter";
-import { CommandLinter } from "./command-linter";
-import { DefaultLinter } from "./default-linter";
-import { KnowledgeLinter } from "./knowledge-linter";
-import { MemoryLinter } from "./memory-linter";
-import { SkillLinter } from "./skill-linter";
-import { TaskLinter } from "./task-linter";
-import { WorkflowLinter } from "./workflow-linter";
+import { AgentLinter } from "./agent-linter.js";
+import { CommandLinter } from "./command-linter.js";
+import { DefaultLinter } from "./default-linter.js";
+import { KnowledgeLinter } from "./knowledge-linter.js";
+import { MemoryLinter } from "./memory-linter.js";
+import { SkillLinter } from "./skill-linter.js";
+import { TaskLinter } from "./task-linter.js";
+import { WorkflowLinter } from "./workflow-linter.js";
 // Singleton instances — one per type, shared across all lint runs.
 const LINTERS = [
     new AgentLinter(),

package/dist/commands/lint/skill-linter.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `skills/` assets.
  *

package/dist/commands/lint/task-linter.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `tasks/` assets.
  *

package/dist/commands/lint/workflow-linter.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
-import { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
 /**
  * Linter for `workflows/` assets.

package/dist/commands/lint.js

@@ -1,4 +1,4 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-export { akmLint } from "./lint/index";
+export { akmLint } from "./lint/index.js";

package/dist/commands/observability-cli.js

@@ -0,0 +1,244 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Observability command cluster — `akm log` (events list/tail), `akm lessons`
+ * (coverage), and `akm hints`. Extracted verbatim from src/cli.ts (WS6) so the
+ * God Module shrinks; the `main.subCommands.{log,lessons,hints}` keys and every
+ * subcommand's args/output shape are byte-identical.
+ *
+ * These three surfaces are cohesive read-only "tell me what happened / what to
+ * do" commands: `log` reads the append-only state.db events stream, `lessons
+ * coverage` reports tag-coverage gaps from the index, and `hints` prints the
+ * embedded AGENTS.md guidance. They share no helpers with any command still
+ * inline in cli.ts, so the `loadHints` private helper and the
+ * `formatEventLine` / `EMBEDDED_HINTS*` / db-tag-set imports move with them.
+ *
+ * The leaf handlers whose body is a plain `runWithJsonErrors(...) + output(...)`
+ * (`events list`, `lessons coverage`) are migrated onto `defineJsonCommand`,
+ * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
+ * form. `events tail` (manual streaming console/stderr writes) and `hints`
+ * (direct `process.stdout.write`) keep a plain `defineCommand` wrapping
+ * `runWithJsonErrors` so their byte-for-byte output stays untouched.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { parsePositiveIntFlag } from "../cli/parse-args.js";
+import { defineJsonCommand, output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared.js";
+import { closeDatabase, collectTagSetFromEntries, openExistingDatabase } from "../indexer/db/db.js";
+import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "../output/cli-hints.js";
+import { getHyphenatedArg, getOutputMode, parseDetailLevel } from "../output/context.js";
+import { formatEventLine } from "../output/text.js";
+import { getDirname } from "../runtime.js";
+import { akmEventsList, akmEventsTail } from "./events.js";
+// ── `akm log` ────────────────────────────────────────────────────────────────
+// Append-only events stream surface (#204). `list` reads state.db events
+// with optional --since/--type/--ref filters; `tail` follows the table via
+// a polling loop and prints each event as a single JSONL line.
+const eventsListCommand = defineJsonCommand({
+    meta: { name: "list", description: "List events from the append-only state.db events stream" },
+    args: {
+        since: {
+            type: "string",
+            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
+        },
+        type: { type: "string", description: "Filter by event type (add, remove, remember, feedback, ...)" },
+        ref: { type: "string", description: "Filter by asset ref (type:name)" },
+        "exclude-tags": {
+            type: "string",
+            description: "Exclude events matching these tags (repeatable)",
+        },
+        "include-tags": {
+            type: "string",
+            description: "Only include events with ALL these tags (repeatable)",
+        },
+    },
+    run({ args }) {
+        const excludeTags = parseAllFlagValues("--exclude-tags");
+        const includeTags = parseAllFlagValues("--include-tags");
+        const result = akmEventsList({
+            since: args.since,
+            type: args.type,
+            ref: args.ref,
+            ...(excludeTags.length > 0 ? { excludeTags } : {}),
+            ...(includeTags.length > 0 ? { includeTags } : {}),
+        });
+        output("events-list", result);
+    },
+});
+const eventsTailCommand = defineCommand({
+    meta: { name: "tail", description: "Follow the append-only state.db events stream (polling)" },
+    args: {
+        since: {
+            type: "string",
+            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
+        },
+        type: { type: "string", description: "Filter by event type" },
+        ref: { type: "string", description: "Filter by asset ref (type:name)" },
+        "interval-ms": { type: "string", description: "Polling interval in ms (default: 75)" },
+        "max-duration-ms": { type: "string", description: "Stop after this many ms (default: never)" },
+        "max-events": { type: "string", description: "Stop after observing this many events" },
+        "exclude-tags": {
+            type: "string",
+            description: "Exclude events matching these tags (repeatable)",
+        },
+        "include-tags": {
+            type: "string",
+            description: "Only include events with ALL these tags (repeatable)",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const intervalMs = parsePositiveIntFlag(getHyphenatedArg(args, "interval-ms"), "--interval-ms");
+            const maxDurationMs = parsePositiveIntFlag(getHyphenatedArg(args, "max-duration-ms"), "--max-duration-ms");
+            const maxEvents = parsePositiveIntFlag(getHyphenatedArg(args, "max-events"), "--max-events");
+            const mode = getOutputMode();
+            // In streaming text mode we want each event to print as soon as it
+            // arrives. The polling loop emits via `onEvent`; the final result is
+            // also rendered through the standard output() pipeline so JSON
+            // consumers always get the canonical envelope.
+            const stream = mode.format === "text" || mode.format === "jsonl";
+            const excludeTags = parseAllFlagValues("--exclude-tags");
+            const includeTags = parseAllFlagValues("--include-tags");
+            const result = await akmEventsTail({
+                since: args.since,
+                type: args.type,
+                ref: args.ref,
+                intervalMs,
+                maxDurationMs,
+                maxEvents,
+                ...(excludeTags.length > 0 ? { excludeTags } : {}),
+                ...(includeTags.length > 0 ? { includeTags } : {}),
+                onEvent: stream
+                    ? (event) => {
+                        if (mode.format === "jsonl") {
+                            console.log(JSON.stringify(event));
+                        }
+                        else {
+                            console.log(formatEventLine(event));
+                        }
+                    }
+                    : undefined,
+            });
+            // Emit the canonical envelope last (JSON/YAML modes rely on this;
+            // streaming modes already printed each event but we still emit a
+            // trailer so callers can persist the resumable cursor).
+            if (!stream) {
+                output("events-tail", result);
+            }
+            else if (mode.format === "jsonl") {
+                // Final discriminated trailer row so jsonl consumers can resume.
+                const trailer = {
+                    _kind: "trailer",
+                    schemaVersion: 1,
+                    nextOffset: result.nextOffset,
+                    totalCount: result.totalCount,
+                    reason: result.reason,
+                };
+                console.log(JSON.stringify(trailer));
+            }
+            else {
+                // text mode: keep stdout pristine for line-oriented parsers and
+                // emit the trailer on stderr.
+                process.stderr.write(`[events-tail] reason=${result.reason} nextOffset=${result.nextOffset} total=${result.totalCount}\n`);
+            }
+        });
+    },
+});
+export const logCommand = defineCommand({
+    meta: {
+        name: "log",
+        description: "Read or follow the append-only state.db events stream (mutations, feedback, indexing)",
+    },
+    subCommands: {
+        list: eventsListCommand,
+        tail: eventsTailCommand,
+    },
+});
+// ── lessons subcommands (Phase 7A / Advantage D4c) ──────────────────────────
+const lessonsCoverageCommand = defineJsonCommand({
+    meta: {
+        name: "coverage",
+        description: "Report tags that exist on indexed assets but are NOT yet covered by any lesson.\n\n" +
+            "Useful for spotting topics where the stash has skills/commands/scripts but no\n" +
+            "crystallized lesson — a signal that the team has tacit knowledge worth distilling.\n\n" +
+            "Default output is JSON: { uncoveredTags: string[], lessonTagCount: number, totalTagCount: number }.\n" +
+            "Pass --format text for a plain-text bulleted list.",
+    },
+    args: {},
+    run() {
+        const db = openExistingDatabase();
+        try {
+            const allTagSet = collectTagSetFromEntries(db, undefined);
+            const lessonTagSet = collectTagSetFromEntries(db, "lesson");
+            const uncovered = [];
+            for (const tag of allTagSet) {
+                if (!lessonTagSet.has(tag))
+                    uncovered.push(tag);
+            }
+            uncovered.sort((a, b) => a.localeCompare(b));
+            output("lessons-coverage", {
+                ok: true,
+                uncoveredTags: uncovered,
+                lessonTagCount: lessonTagSet.size,
+                totalTagCount: allTagSet.size,
+            });
+        }
+        finally {
+            closeDatabase(db);
+        }
+    },
+});
+export const lessonsCommand = defineCommand({
+    meta: {
+        name: "lessons",
+        alias: "lesson",
+        description: "Lesson-asset tooling: tag-coverage gaps, strength queries.",
+    },
+    subCommands: {
+        coverage: lessonsCoverageCommand,
+    },
+});
+// ── `akm hints` ──────────────────────────────────────────────────────────────
+export const hintsCommand = defineCommand({
+    meta: {
+        name: "hints",
+        description: "Print agent instructions on how to use akm, use --detail full for a complete guide",
+    },
+    args: {
+        detail: {
+            type: "string",
+            description: "Hints detail level (brief|normal|full). `brief` prints the short guide; `normal`/`full` print the complete guide.",
+            default: "normal",
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            // Let the global parser validate the value so an invalid `--detail`
+            // returns the standard JSON error envelope (exit 2) rather than a raw
+            // stack trace + exit 1. `brief` → short doc; `normal`/`full` → full doc.
+            const detail = parseDetailLevel(args.detail) ?? "normal";
+            process.stdout.write(loadHints(detail === "brief" ? "brief" : "full"));
+        });
+    },
+});
+// ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
+function loadHints(detail = "normal") {
+    // `brief` → the short AGENTS.md guide; `normal`/`full` → the complete guide.
+    const wantFull = detail !== "brief";
+    const filename = wantFull ? "AGENTS.full.md" : "AGENTS.md";
+    const fallback = wantFull ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
+    // Try reading from the docs/ directory (works in dev and when installed via npm)
+    try {
+        const docsPath = path.resolve(getDirname(import.meta.url), `../../docs/agents/${filename}`);
+        if (fs.existsSync(docsPath)) {
+            return fs.readFileSync(docsPath, "utf8");
+        }
+    }
+    catch {
+        // fall through
+    }
+    // Fallback for compiled binary — inline content
+    return fallback;
+}

package/dist/commands/proposal/drain-policies.js

@@ -16,10 +16,10 @@
  */
 import fs from "node:fs";
 import { z } from "zod";
-import { UsageError } from "../../core/errors";
-import { PROPOSAL_SOURCES } from "../../core/proposals";
+import { UsageError } from "../../core/errors.js";
+import { PROPOSAL_SOURCES } from "./validators/proposals.js";
 // Valid `generator` values for a drain rule are exactly the canonical proposal
-// `source` values (see {@link PROPOSAL_SOURCES} in src/core/proposals.ts). The
+// `source` values (see {@link PROPOSAL_SOURCES} in src/commands/proposal/validators/proposals.ts). The
 // engine matches rules via `policy.accept.find(r => r.generator === proposal.source)`,
 // so a generator that is not a real source can never match — it would be a
 // silent permanent no-op. Validate against the closed set to surface typos.

package/dist/commands/proposal/drain.js

@@ -36,16 +36,17 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../../core/asset-ref";
-import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset-spec";
-import { appendEvent } from "../../core/events";
-import { parseFrontmatter } from "../../core/frontmatter";
-import { listProposals } from "../../core/proposals";
-import { info, warn } from "../../core/warn";
-import { runAgent } from "../../integrations/agent";
-import { runOpencodeSdk } from "../../integrations/agent/sdk-runner";
-import { chatCompletion, stripJsonFences } from "../../llm/client";
-import { akmProposalAccept, akmProposalReject } from "../proposal";
+import { assertNever } from "../../core/assert.js";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { appendEvent } from "../../core/events.js";
+import { info, warn } from "../../core/warn.js";
+import { runAgent } from "../../integrations/agent/index.js";
+import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { chatCompletion, stripJsonFences } from "../../llm/client.js";
+import { akmProposalAccept, akmProposalReject } from "./proposal.js";
+import { listProposals, recordGateDecision } from "./validators/proposals.js";
 // ---------------------------------------------------------------------------
 // Content helpers
 // ---------------------------------------------------------------------------
@@ -77,7 +78,7 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
     const content = proposal.payload.content ?? "";
     // Empty / near-empty diffs reject first (the reject-empty floor).
     if (policy.rejectEmpty && isEmptyDiff(proposal)) {
-        return { verdict: "reject", reason: "empty diff" };
+        return { verdict: "reject", reason: "empty diff", gate: { reason: "empty-diff" } };
     }
     const rule = policy.accept.find((r) => r.generator === proposal.source);
     if (rule) {
@@ -86,16 +87,25 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
         // Per-rule and global diff bounds defer large accepts (no silent rewrites).
         const effectiveMax = Math.min(rule.maxDiffLines ?? Number.POSITIVE_INFINITY, maxDiffLines ?? Number.POSITIVE_INFINITY);
         if (lines > effectiveMax) {
-            return { verdict: "defer", reason: "mid-band" };
+            return {
+                verdict: "defer",
+                reason: "mid-band",
+                gate: { reason: "max-diff-lines", measured: lines, thresholds: { maxDiffLines: effectiveMax } },
+            };
         }
         if (rule.minContentLines !== undefined && body < rule.minContentLines) {
             // Too little content to confidently auto-accept — leave for judgment.
-            return { verdict: "defer", reason: "mid-band" };
+            return {
+                verdict: "defer",
+                reason: "mid-band",
+                gate: { reason: "min-content-lines", measured: body, thresholds: { minContentLines: rule.minContentLines } },
+            };
         }
-        return { verdict: "accept" };
+        return { verdict: "accept", gate: { reason: "policy-accept" } };
     }
     if (policy.defer.includes(proposal.source)) {
-        return { verdict: "defer", reason: deferReasonForSource(proposal.source) };
+        const reason = deferReasonForSource(proposal.source);
+        return { verdict: "defer", reason, gate: { reason } };
     }
     // No matching rule — leave pending, untouched.
     return null;
@@ -220,6 +230,10 @@ async function dispatchJudgment(runner, prompt, seams) {
             raw = stdout;
             break;
         }
+        default:
+            // Exhaustiveness arm (H1): a 4th RunnerSpec kind becomes a compile error
+            // here instead of leaving `raw` undefined at runtime.
+            return assertNever(runner);
     }
     return parseJudgmentVerdict(raw);
 }
@@ -342,10 +356,31 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     // First, classify every proposal deterministically.
     const acceptIds = [];
     const rejectTargets = [];
+    const gateLabel = `triage:${opts.policy.name}`;
+    // Items deferred purely because they need a judge (no threshold-based reason)
+    // — these are re-stamped `no-judge-configured` when no runner resolves them.
+    const needsJudge = new Set();
     for (const proposal of pending) {
         const decision = classifyProposal(proposal, opts.policy, opts.maxDiffLines);
         if (decision === null)
             continue;
+        // #577: stamp the gate's verdict onto the proposal so `akm proposal show`
+        // can explain WHY it landed here. A dry-run performs zero writes, so it
+        // records nothing.
+        const outcome = decision.verdict === "accept" ? "auto-accepted" : decision.verdict === "reject" ? "auto-rejected" : "deferred";
+        stampGateDecision(opts, proposal.id, {
+            outcome,
+            reason: decision.gate.reason,
+            ...(decision.gate.measured !== undefined ? { measured: decision.gate.measured } : {}),
+            ...(decision.gate.thresholds ? { thresholds: decision.gate.thresholds } : {}),
+            gate: gateLabel,
+        });
+        // A defer with no threshold (mid-band / possible-dup from the defer list) is
+        // pending only because it needs adjudication — re-stampable to
+        // `no-judge-configured`. A band-based defer keeps its specific reason.
+        if (decision.verdict === "defer" && !decision.gate.thresholds) {
+            needsJudge.add(proposal.id);
+        }
         if (decision.verdict === "accept") {
             acceptIds.push(proposal.id);
         }
@@ -429,14 +464,51 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         if (tier.skippedByCap.length > 0) {
             info(`[triage] accept ceiling reached in judgment tier: ${tier.skippedByCap.length} judged-accept items skipped by cap (maxAccepts=${opts.maxAccepts})`);
         }
+        // #577: re-stamp the gate decision for items the judgment tier resolved so
+        // `akm proposal show` reflects the judge's verdict, not the earlier
+        // deterministic defer.
+        for (const id of tier.promoted) {
+            stampGateDecision(opts, id, { outcome: "auto-accepted", reason: "judgment-accept", gate: gateLabel });
+        }
+        for (const id of tier.rejected) {
+            stampGateDecision(opts, id, { outcome: "auto-rejected", reason: "judgment-reject", gate: gateLabel });
+        }
         // Replace the deferred list with only the items the judgment tier could NOT
         // resolve (verdict "defer", parse failure, or runner error). Staged
         // queue-mode accepts are RESOLVED and tracked in result.staged instead.
         result.deferred = tier.stillDeferred;
     }
+    else if (result.deferred.length > 0) {
+        // #577: no judgment runner configured — items deferred *because they need a
+        // judge* (mid-band / possible-dup, no threshold reason) stay pending solely
+        // for lack of one. Re-stamp those as `no-judge-configured` so the operator
+        // sees a per-proposal reason instead of inferring it from the run-level
+        // triage_deferred aggregate. Band-deferred items keep their specific reason
+        // (e.g. `max-diff-lines`), which is more actionable than "no judge".
+        for (const item of result.deferred) {
+            if (needsJudge.has(item.id)) {
+                stampGateDecision(opts, item.id, { outcome: "deferred", reason: "no-judge-configured", gate: gateLabel });
+            }
+        }
+    }
     emitDrainEvents(opts, result);
     return result;
 }
+/**
+ * Persist a gate decision onto a proposal, honouring the dry-run contract
+ * (a dry run performs zero writes, so it records nothing) and never letting a
+ * persistence failure abort the drain (#577). Best-effort by design.
+ */
+function stampGateDecision(opts, id, decision) {
+    if (opts.dryRun)
+        return;
+    try {
+        recordGateDecision(opts.stashDir, id, decision);
+    }
+    catch (err) {
+        warn(`[triage] failed to record gate decision for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Events
 // ---------------------------------------------------------------------------