akm-cli 0.9.0-beta.1 → 0.9.0-beta.3

package/dist/indexer/passes/memory-inference.js

@@ -119,6 +119,26 @@ export async function runMemoryInferencePass(ctx) {
         // 2026-05-26).
         if (signal?.aborted)
             return { aborted: true };
+        // Pre-check (#588): when `<parent>.derived.md` is already on disk the
+        // inference is by definition complete — the parent only looks pending
+        // because `markParentProcessed` never ran (process killed between the
+        // child write and the mark) or the child was created externally (e.g.
+        // consolidation). Skip the LLM/cache call entirely and mark the parent
+        // so it never re-pends. Before this check, production measurements
+        // showed ~55% of the pass's LLM budget re-deriving such parents only to
+        // discover the existing child after the fact.
+        if (fs.existsSync(derivedChildPath(record))) {
+            markParentProcessed(record);
+            return {
+                skipped: false,
+                splitParent: false,
+                written: 0,
+                fromCache: false,
+                retryAttempts: 0,
+                childExists: true,
+                precheck: true,
+            };
+        }
         // Incremental cache: skip LLM call when body hash is unchanged and
         // --re-enrich was not requested. The cache ref is the absolute file path.
         const validate = (raw) => {
@@ -171,23 +191,30 @@ export async function runMemoryInferencePass(ctx) {
             return { skipped: false, splitParent: true, written: writeOutcome.written, fromCache, retryAttempts };
         }
         // LLM produced a valid derived draft but no file was written — either
-        // because `<parent>.derived.md` already exists on disk or
-        // `writeAssetToSource` threw. Categorise as `childExists` so the
-        // attempt is accounted for in health metrics rather than vanishing
-        // into the freshAttempts denominator.
+        // because `<parent>.derived.md` appeared on disk after the pre-check
+        // above (a rare mid-flight race) or `writeAssetToSource` threw.
+        // Categorise as `childExists` so the consumed attempt is accounted for
+        // in health metrics rather than vanishing into the freshAttempts
+        // denominator.
         //
-        // When the child already exists on disk the inference is, by definition,
-        // already complete — so mark the parent processed here too (#550).
-        // Without this, `isPendingMemory()` re-queues the same parent every run
-        // (the `written > 0` path was previously the only site that marks it),
-        // causing permanent re-queueing and wasted LLM calls. A genuine write
-        // *failure* (`writeAssetToSource` threw) must NOT mark the parent — it
-        // should be retried next run — so we key off the explicit `childExists`
-        // outcome rather than the conflated `written === 0`.
+        // When the child exists the inference is, by definition, complete — so
+        // mark the parent processed here too (#550), otherwise
+        // `isPendingMemory()` re-queues the same parent every run. A genuine
+        // write *failure* (`writeAssetToSource` threw) must NOT mark the parent
+        // — it should be retried next run — so we key off the explicit
+        // `childExists` outcome rather than the conflated `written === 0`.
         if (writeOutcome.childExists) {
             markParentProcessed(record);
         }
-        return { skipped: false, splitParent: false, written: 0, fromCache, retryAttempts, childExists: true };
+        return {
+            skipped: false,
+            splitParent: false,
+            written: 0,
+            fromCache,
+            retryAttempts,
+            childExists: true,
+            precheck: false,
+        };
     }, 
     // Default concurrency of 4 for cloud APIs. Set `llm.concurrency: 1`
     // in config.json for local model servers (LM Studio, Ollama).
@@ -224,11 +251,16 @@ export async function runMemoryInferencePass(ctx) {
             result.writtenFacts += res.written;
         }
         else if ("childExists" in res && res.childExists) {
-            // LLM call was consumed but the derived file already existed (or the
-            // write threw). Track separately so this category is observable in
-            // health output and stops bleeding into the freshAttempts denominator.
+            // Derived child already on disk. Track separately so this category is
+            // observable in health output and stops bleeding into the
+            // freshAttempts denominator. Pre-check skips (#588) are the routine
+            // self-healing path — no LLM attempt was consumed and the parent has
+            // been marked processed — so only the rare post-LLM case (mid-flight
+            // race or write failure) warrants a per-ref warning.
             result.skippedChildExists += 1;
-            warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+            if (!res.precheck) {
+                warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+            }
         }
         else {
             // The per-record state machine should cover every outcome. A hit here
@@ -324,6 +356,14 @@ function toMemoryName(memoriesDir, filePath) {
     // user has organised under memories/.
     return rel.replace(/\\/g, "/").replace(/\.md$/i, "");
 }
+/**
+ * Absolute path of the derived child for a parent memory. Single source of
+ * truth for the `<parent>.derived.md` naming convention — used both by the
+ * pre-LLM existence check (#588) and the write path.
+ */
+function derivedChildPath(parent) {
+    return path.join(parent.stashRoot, "memories", `${parent.name}.derived.md`);
+}
 async function writeDerivedMemory(parent, derived) {
     const writeTarget = {
         kind: "filesystem",
@@ -338,11 +378,10 @@ async function writeDerivedMemory(parent, derived) {
     };
     const childName = `${parent.name}.derived`;
     const childRefStr = `memory:${childName}`;
-    const childPath = path.join(parent.stashRoot, "memories", `${childName}.md`);
-    if (fs.existsSync(childPath)) {
-        // The derived child is already on disk — inference for this parent is
-        // complete. Report `childExists` so the caller marks the parent processed
-        // (#550) instead of re-queueing it forever.
+    if (fs.existsSync(derivedChildPath(parent))) {
+        // The derived child appeared on disk after the caller's pre-check (#588)
+        // — a rare mid-flight race. Report `childExists` so the caller marks the
+        // parent processed (#550) instead of re-queueing it forever.
         return { written: 0, childExists: true };
     }
     try {

package/dist/integrations/harnesses/claude/session-log.js

@@ -5,7 +5,19 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
-const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+/**
+ * Root directory holding Claude Code's per-project JSONL session logs.
+ *
+ * Resolved per call (not memoized at module load) so the `AKM_CLAUDE_PROJECTS_DIR`
+ * override can be set after import. The override exists so tests — and the
+ * isolated-storage sandbox — can point the scan at an empty fixture directory
+ * instead of the real `~/.claude/projects`, which on an actively-used machine
+ * holds many large session files and would make `akm health` (which scans it
+ * synchronously) slow and non-hermetic.
+ */
+function claudeProjectsDir() {
+    return process.env.AKM_CLAUDE_PROJECTS_DIR ?? path.join(os.homedir(), ".claude", "projects");
+}
 /**
  * Parse a single Claude Code JSONL event into a normalized {@link SessionEvent}.
  * Returns `undefined` for events that don't carry textual content (file
@@ -93,11 +105,11 @@ export class ClaudeCodeProvider {
     // HARNESS_BY_ID.get("claude").runtimeId.
     name = "claude-code";
     isAvailable() {
-        return fs.existsSync(CLAUDE_PROJECTS_DIR);
+        return fs.existsSync(claudeProjectsDir());
     }
     *readEvents(input) {
         try {
-            for (const jsonlPath of this.#walkJsonl(CLAUDE_PROJECTS_DIR)) {
+            for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {
                 const stat = fs.statSync(jsonlPath);
                 if (stat.mtimeMs < input.sinceMs)
                     continue;
@@ -128,7 +140,7 @@ export class ClaudeCodeProvider {
         }
     }
     listSessions(input = {}) {
-        const root = input.location ?? CLAUDE_PROJECTS_DIR;
+        const root = input.location ?? claudeProjectsDir();
         const sinceMs = input.sinceMs ?? 0;
         const summaries = [];
         try {

package/dist/llm/client.js

@@ -14,6 +14,7 @@ import { fetchWithTimeout } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
 import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse.js";
 import { warnVerbose } from "../core/warn.js";
+import { emitLlmUsage, extractUsageTokens } from "./usage-telemetry.js";
 // Re-export shared parse utilities so existing importers of `client.ts` continue
 // to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
 export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse.js";
@@ -179,6 +180,10 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     const responseFormat = options?.responseSchema && config.supportsJsonSchema
         ? { response_format: { type: "json_schema", json_schema: { schema: options.responseSchema, strict: true } } }
         : {};
+    // Wall-clock start for per-call usage telemetry (#576). Captured here so the
+    // emitted duration covers the full request/response/parse cycle of a single
+    // attempt, not the retry-wrapping `chatCompletion`.
+    const requestStartedAt = Date.now();
     let response;
     try {
         response = await fetchWithTimeout(config.endpoint, {
@@ -241,6 +246,16 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     catch {
         throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactErrorBody(rawOkBody)}`, "parse_error", response.status);
     }
+    // Per-call usage telemetry (#576). Best-effort and fully isolated: a missing
+    // or garbled usage block still records duration + model, and a throwing sink
+    // can never fail the call (emitLlmUsage swallows its own errors). The stage
+    // is supplied ambiently by emitLlmUsage; no `stage` param is threaded here.
+    emitLlmUsage({
+        model: typeof json.model === "string" && json.model ? json.model : config.model,
+        durationMs: Date.now() - requestStartedAt,
+        finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
+        ...extractUsageTokens(json.usage),
+    });
     const content = (json.choices?.[0]?.message?.content ?? "").trim();
     const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
     return content || reasoning;

package/dist/llm/usage-persist.js

@@ -0,0 +1,77 @@
+// 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/.
+/**
+ * Bridge per-call LLM usage telemetry (#576) to the events stream.
+ *
+ * `usage-telemetry.ts` stays dependency-free of the events/db layer so the
+ * low-level `client.ts` never imports persistence. This module is the wiring:
+ * it installs a {@link LlmUsageSink} that persists each {@link LlmUsageRecord}
+ * as one `llm_usage` event.
+ *
+ * Why reuse the events table (vs a dedicated table): volume is low (~100
+ * calls/day), the records are append-only and time-windowed exactly like every
+ * other event, and `akm health` already aggregates per-window event reads — a
+ * separate table would duplicate retention (`purgeOldEvents`), reads, and
+ * migration surface for no benefit. See the commit message for #576.
+ *
+ * Every record is written through `appendEvent`, which is itself best-effort
+ * (a write failure logs once and never throws). Combined with the sink-error
+ * swallowing in `emitLlmUsage`, telemetry can never break a real run.
+ */
+import { appendEvent } from "../core/events.js";
+import { clearLlmUsageSink, hasLlmUsageSink, setLlmUsageSink } from "./usage-telemetry.js";
+/** Event type for persisted per-call LLM usage telemetry. */
+export const LLM_USAGE_EVENT = "llm_usage";
+/**
+ * Project a usage record into event metadata, dropping `undefined` token
+ * fields so an absent-usage call records only `{stage, model, durationMs}`.
+ */
+function toEventMetadata(record) {
+    const metadata = { durationMs: record.durationMs };
+    if (record.stage !== undefined)
+        metadata.stage = record.stage;
+    if (record.model !== undefined)
+        metadata.model = record.model;
+    if (record.finishReason !== undefined)
+        metadata.finishReason = record.finishReason;
+    if (record.promptTokens !== undefined)
+        metadata.promptTokens = record.promptTokens;
+    if (record.completionTokens !== undefined)
+        metadata.completionTokens = record.completionTokens;
+    if (record.totalTokens !== undefined)
+        metadata.totalTokens = record.totalTokens;
+    if (record.reasoningTokens !== undefined)
+        metadata.reasoningTokens = record.reasoningTokens;
+    return metadata;
+}
+/**
+ * Install a usage sink that persists each LLM call as an `llm_usage` event via
+ * `appendEvent`. Returns a disposer that clears the sink — call it in a
+ * `finally` block so per-run wiring does not leak across runs (and so the
+ * test-isolation harness sees a clean sink between tests).
+ *
+ * `ctx` should carry the same long-lived `state.db` handle the caller already
+ * opened for its other events; when omitted, `appendEvent` falls back to its
+ * default open-insert-close path.
+ */
+export function installLlmUsagePersistence(ctx) {
+    setLlmUsageSink((record) => {
+        appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, ctx);
+    });
+    return () => {
+        clearLlmUsageSink();
+    };
+}
+/**
+ * Like {@link installLlmUsagePersistence}, but a no-op when a sink is already
+ * installed — used by standalone entry points (`akm consolidate`, `akm drain`)
+ * that may also run as a sub-step of `akm improve`. When invoked inside an
+ * enclosing run the existing per-run sink keeps ownership; the returned
+ * disposer then does nothing, so the enclosing run's `finally` still clears it.
+ */
+export function installLlmUsagePersistenceIfAbsent(ctx) {
+    if (hasLlmUsageSink())
+        return () => { };
+    return installLlmUsagePersistence(ctx);
+}

package/dist/llm/usage-telemetry.js

@@ -0,0 +1,103 @@
+// 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/.
+/**
+ * Per-call LLM usage telemetry (#576).
+ *
+ * `chatCompletion` captures usage + model + finish_reason + wall-time for
+ * EVERY OpenAI-compatible call and emits one {@link LlmUsageRecord} through a
+ * module-level sink. The sink indirection keeps `client.ts` free of any
+ * dependency on the events/db layer: the application wires the sink to
+ * persistence at startup / per improve run, and tests can inspect records in
+ * memory.
+ *
+ * The pipeline *stage* that made the call is ambient, not threaded through
+ * call sites. A param-threading prototype was deliberately discarded in 0.8.5
+ * (every call site would have to forward a `stage` argument it does not care
+ * about). Instead callers wrap a well-delimited phase once with
+ * {@link withLlmStage}; any `chatCompletion` invoked inside that async region —
+ * however deeply nested — is attributed to that stage via `AsyncLocalStorage`.
+ *
+ * EVERYTHING here is best-effort. Telemetry must NEVER break a real LLM call:
+ * a sink that throws, an unset stage, or a malformed usage block all degrade
+ * silently. `emitLlmUsage` swallows sink errors; `currentLlmStage` returns
+ * `undefined` outside any `withLlmStage` scope.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const stageStorage = new AsyncLocalStorage();
+let usageSink;
+/**
+ * Run `fn` with `stage` as the ambient LLM stage. Any `chatCompletion` call
+ * made synchronously or asynchronously within `fn` (including through awaited
+ * helpers and nested `withLlmStage` calls — the innermost wins) is attributed
+ * to `stage`. Returns whatever `fn` returns; never alters control flow.
+ */
+export function withLlmStage(stage, fn) {
+    return stageStorage.run(stage, fn);
+}
+/** The ambient LLM stage for the current async context, or `undefined` outside any {@link withLlmStage} scope. */
+export function currentLlmStage() {
+    return stageStorage.getStore();
+}
+/**
+ * Install the process-wide usage sink. Replaces any previously installed sink.
+ * The application wires this to persistence; tests install an in-memory
+ * collector. Pair with {@link clearLlmUsageSink} in a `finally` block.
+ */
+export function setLlmUsageSink(sink) {
+    usageSink = sink;
+}
+/** Remove the installed sink so subsequent calls emit nowhere. Idempotent. */
+export function clearLlmUsageSink() {
+    usageSink = undefined;
+}
+/**
+ * Whether a usage sink is currently installed. Standalone entry points use
+ * this to avoid clobbering a sink an enclosing run (e.g. `akm improve`) already
+ * installed: they install their own only when none is active.
+ */
+export function hasLlmUsageSink() {
+    return usageSink !== undefined;
+}
+/**
+ * Emit one usage record to the installed sink, stamping the ambient stage.
+ * Best-effort: no sink is a no-op, and a sink that throws is swallowed so
+ * telemetry can never fail the LLM call that produced it.
+ */
+export function emitLlmUsage(record) {
+    const sink = usageSink;
+    if (!sink)
+        return;
+    try {
+        sink({ ...record, stage: record.stage ?? currentLlmStage() });
+    }
+    catch {
+        // Telemetry must never break a real run.
+    }
+}
+function asFiniteNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Project a provider `usage` block into the token fields of an
+ * {@link LlmUsageRecord}. Missing or garbled values are omitted (not zeroed)
+ * so a best-effort record still distinguishes "0 tokens" from "unknown".
+ */
+export function extractUsageTokens(usage) {
+    if (!usage || typeof usage !== "object")
+        return {};
+    const out = {};
+    const prompt = asFiniteNonNegative(usage.prompt_tokens);
+    const completion = asFiniteNonNegative(usage.completion_tokens);
+    const total = asFiniteNonNegative(usage.total_tokens);
+    const reasoning = asFiniteNonNegative(usage.completion_tokens_details?.reasoning_tokens);
+    if (prompt !== undefined)
+        out.promptTokens = prompt;
+    if (completion !== undefined)
+        out.completionTokens = completion;
+    if (total !== undefined)
+        out.totalTokens = total;
+    if (reasoning !== undefined)
+        out.reasoningTokens = reasoning;
+    return out;
+}

package/dist/output/context.js

@@ -12,7 +12,7 @@
  * Initialized from `cli.ts` before `runMain`.
  */
 import { UsageError } from "../core/errors.js";
-export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md"];
+export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
 export const DETAIL_LEVELS = ["brief", "normal", "full"];
 export const SHAPE_MODES = ["human", "agent", "summary"];
 export function parseOutputFormat(value) {
@@ -80,7 +80,8 @@ export function resolveOutputMode(argv, defaults = {}) {
     // use `--shape`. Unknown `--detail` values fall through to the default.
     const detail = parseDetailLevel(rawDetail) ?? defaults?.detail ?? "brief";
     const shape = parseShapeMode(rawShape) ?? "human";
-    return { format, detail, shape, forAgent: shape === "agent" };
+    const outputPath = parseFlagValue(argv, "--output");
+    return { format, detail, shape, forAgent: shape === "agent", ...(outputPath ? { outputPath } : {}) };
 }
 let _mode;
 /**

package/dist/output/html-render.js

@@ -0,0 +1,73 @@
+// 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/.
+/**
+ * `--format html` rendering primitives (#582).
+ *
+ * Templates live in `src/assets/templates/html/` (mirrored to
+ * `dist/assets/templates/html/` by `scripts/copy-assets.ts`). A command with a
+ * bespoke template ships `<command>.html`; every other command falls back to
+ * `default.html`, which renders the command's JSON envelope in a `<pre>`
+ * block. Substitution is plain `%%TOKEN%%` string replacement — no template
+ * engine, by design.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getDirname } from "../runtime.js";
+const TEMPLATES_DIR = path.join(getDirname(import.meta.url), "../assets/templates/html");
+/** Template used by every command without a bespoke `<command>.html`. */
+export const DEFAULT_TEMPLATE = "default";
+/**
+ * Resolve the on-disk template path for a command. `<command>.html` when the
+ * command ships a bespoke template (today: `health`), otherwise
+ * `default.html`. Command names are sanitized to a bare basename so a hostile
+ * command string can never escape the templates directory.
+ */
+export function resolveTemplatePath(command) {
+    const name = path.basename(command.trim());
+    const candidate = path.join(TEMPLATES_DIR, `${name}.html`);
+    if (name !== DEFAULT_TEMPLATE && fs.existsSync(candidate))
+        return candidate;
+    return path.join(TEMPLATES_DIR, `${DEFAULT_TEMPLATE}.html`);
+}
+/** Matches a `%%TOKEN%%` placeholder (uppercase + underscore key). */
+const TOKEN_RE = /%%[A-Z_]+%%/g;
+/**
+ * Read a template and substitute every `%%TOKEN%%` in `replacements` in a
+ * single pass. Substitution is order-independent: a value that happens to
+ * contain another token's literal text is never re-processed (the pass scans
+ * the original template, not the growing output). Unknown tokens in the
+ * template are left in place (the health template is verified token-complete by
+ * tests); replacement keys missing from the template are silently ignored,
+ * matching the skill renderer's behaviour.
+ */
+export function renderHtml(templatePath, replacements) {
+    const html = fs.readFileSync(templatePath, "utf8");
+    return html.replace(TOKEN_RE, (token) => (token in replacements ? replacements[token] : token));
+}
+/**
+ * Minimal HTML entity escaping for text interpolated into templates. Escapes
+ * the single quote as well as the double quote so escaped values are safe in
+ * both `"…"` and `'…'` attribute contexts, not only the double-quoted
+ * attributes the bundled templates use today.
+ */
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * Deliver a rendered document: write to `outputPath` when set (`--output`),
+ * otherwise print to stdout.
+ */
+export function deliverRendered(content, outputPath) {
+    if (outputPath) {
+        fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
+        fs.writeFileSync(outputPath, content.endsWith("\n") ? content : `${content}\n`);
+        return;
+    }
+    console.log(content);
+}

package/dist/output/shapes/helpers.js

@@ -41,7 +41,21 @@ export function shapeProposalEntry(entry, detail) {
         return pickFields(entry, ["id", "ref", "status", "source", "createdAt"]);
     }
     if (detail === "normal") {
-        return pickFields(entry, ["id", "ref", "status", "source", "sourceRun", "createdAt", "updatedAt", "review"]);
+        // `confidence` and `gateDecision` (#577) explain why a proposal is pending,
+        // so they are projected at `normal` for `akm proposal list/show` — both are
+        // optional and absent on legacy proposals.
+        return pickFields(entry, [
+            "id",
+            "ref",
+            "status",
+            "source",
+            "sourceRun",
+            "createdAt",
+            "updatedAt",
+            "confidence",
+            "gateDecision",
+            "review",
+        ]);
     }
     // full: project everything including the payload.
     return pickFields(entry, [
@@ -52,6 +66,8 @@ export function shapeProposalEntry(entry, detail) {
         "sourceRun",
         "createdAt",
         "updatedAt",
+        "confidence",
+        "gateDecision",
         "payload",
         "review",
     ]);

package/dist/output/text/helpers.js

@@ -235,6 +235,50 @@ export function formatProposalProducerPlain(command, r) {
     const status = String(proposal.status ?? "pending");
     return `${command}: queued proposal ${id} (${ref}) [${status}]`;
 }
+/**
+ * Render a one-line gate-decision summary for the proposal list / show surfaces
+ * (#577), e.g. `gate=deferred:below-threshold (0.72 < 0.90)`. Returns the empty
+ * string for a missing or malformed decision so legacy proposals render cleanly.
+ */
+export function formatGateDecisionSummary(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return "";
+    const d = raw;
+    const outcome = typeof d.outcome === "string" ? d.outcome : undefined;
+    if (!outcome)
+        return "";
+    const reason = typeof d.reason === "string" && d.reason.length > 0 ? `:${d.reason}` : "";
+    const cmp = formatGateThresholdComparison(d);
+    return `gate=${outcome}${reason}${cmp ? ` (${cmp})` : ""}`;
+}
+/**
+ * Reconstruct the threshold comparison the gate applied, when both sides are
+ * present (e.g. confidence 0.72 vs. autoAccept 0.90 → "0.72 < 0.90"). Returns
+ * the empty string when the decision lacks the operands.
+ */
+function formatGateThresholdComparison(d) {
+    const thresholds = (typeof d.thresholds === "object" && d.thresholds !== null ? d.thresholds : {});
+    const confidence = typeof d.confidence === "number" ? d.confidence : undefined;
+    const autoAccept = typeof thresholds.autoAccept === "number" ? thresholds.autoAccept : undefined;
+    if (confidence !== undefined && autoAccept !== undefined) {
+        const op = confidence >= autoAccept ? ">=" : "<";
+        return `${confidence.toFixed(2)} ${op} ${autoAccept.toFixed(2)}`;
+    }
+    // Drain bands: when the measured value is present, render the full comparison
+    // ("210 > 200" / "1 < 5"); otherwise fall back to the bound alone (#577).
+    const measured = typeof d.measured === "number" ? d.measured : undefined;
+    if (typeof thresholds.maxDiffLines === "number") {
+        return measured !== undefined
+            ? `${measured} > ${thresholds.maxDiffLines}`
+            : `maxDiffLines=${thresholds.maxDiffLines}`;
+    }
+    if (typeof thresholds.minContentLines === "number") {
+        return measured !== undefined
+            ? `${measured} < ${thresholds.minContentLines}`
+            : `minContentLines=${thresholds.minContentLines}`;
+    }
+    return "";
+}
 export function formatProposalListPlain(r) {
     const proposals = Array.isArray(r.proposals) ? r.proposals : [];
     const total = typeof r.totalCount === "number" ? r.totalCount : proposals.length;
@@ -248,7 +292,11 @@ export function formatProposalListPlain(r) {
         const status = String(p.status ?? "?");
         const source = String(p.source ?? "?");
         const created = String(p.createdAt ?? "?");
-        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}`);
+        // #577: surface the gate verdict inline so the queue explains itself
+        // ("deferred: below-threshold"). Legacy proposals carry no gateDecision.
+        const gate = formatGateDecisionSummary(p.gateDecision);
+        const gateSuffix = gate ? `  ${gate}` : "";
+        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}${gateSuffix}`);
     }
     return lines.join("\n").trimEnd();
 }
@@ -265,6 +313,26 @@ export function formatProposalShowPlain(r) {
         lines.push(`createdAt: ${String(p.createdAt)}`);
     if (p.updatedAt)
         lines.push(`updatedAt: ${String(p.updatedAt)}`);
+    if (typeof p.confidence === "number")
+        lines.push(`confidence: ${p.confidence.toFixed(2)}`);
+    // #577: gate decision (auto-accepted / deferred / auto-rejected + reason +
+    // thresholds). Absent on legacy proposals — render "unknown" so the field is
+    // always present and the operator never sees a silent gap.
+    const gate = p.gateDecision;
+    if (gate && typeof gate.outcome === "string") {
+        lines.push(`gate.decision: ${String(gate.outcome)}`);
+        lines.push(`gate.reason: ${gate.reason ? String(gate.reason) : "unknown"}`);
+        const cmp = formatGateThresholdComparison(gate);
+        if (cmp)
+            lines.push(`gate.thresholds: ${cmp}`);
+        if (gate.gate)
+            lines.push(`gate.by: ${String(gate.gate)}`);
+        if (gate.decidedAt)
+            lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
+    }
+    else {
+        lines.push("gate.decision: unknown");
+    }
     const review = p.review;
     if (review) {
         lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);