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

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 ?? "?")}`);

package/dist/scripts/migrate-storage.js

@@ -8888,6 +8888,7 @@ __export(exports_state_db, {
   shouldSkipAlreadyExtractedSession: () => shouldSkipAlreadyExtractedSession,
   runMigrations: () => runMigrations2,
   recordImproveRun: () => recordImproveRun,
+  recordFsProposalsImport: () => recordFsProposalsImport,
   readStateEvents: () => readStateEvents,
   queryTaskHistory: () => queryTaskHistory,
   queryImproveRuns: () => queryImproveRuns,
@@ -8898,9 +8899,12 @@ __export(exports_state_db, {
   proposalRowToProposal: () => proposalRowToProposal,
   openStateDatabase: () => openStateDatabase,
   listStateProposals: () => listStateProposals,
+  listStateProposalIdsByPrefix: () => listStateProposalIdsByPrefix,
   listExistingTableNames: () => listExistingTableNames,
+  insertProposalIfAbsent: () => insertProposalIfAbsent,
   insertEvent: () => insertEvent,
   importEventsJsonl: () => importEventsJsonl,
+  hasImportedFsProposals: () => hasImportedFsProposals,
   getTaskHistoryRuns: () => getTaskHistoryRuns,
   getTaskHistory: () => getTaskHistory,
   getStateProposal: () => getStateProposal,
@@ -8925,7 +8929,7 @@ function openStateDatabase(dbPath) {
   const db = openDatabase(resolvedPath);
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
-  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec("PRAGMA busy_timeout = 30000");
   runMigrations2(db);
   return db;
 }
@@ -8972,7 +8976,10 @@ function proposalRowToProposal(row) {
       content: row.content,
       ...frontmatter !== undefined ? { frontmatter } : {}
     },
-    ...meta.review !== undefined ? { review: meta.review } : {}
+    ...meta.review !== undefined ? { review: meta.review } : {},
+    ...typeof meta.confidence === "number" ? { confidence: meta.confidence } : {},
+    ...meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {},
+    ...typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}
   };
 }
 function proposalToRowValues(proposal, stashDir) {
@@ -8981,6 +8988,12 @@ function proposalToRowValues(proposal, stashDir) {
     metaObj.sourceRun = proposal.sourceRun;
   if (proposal.review !== undefined)
     metaObj.review = proposal.review;
+  if (proposal.confidence !== undefined)
+    metaObj.confidence = proposal.confidence;
+  if (proposal.gateDecision !== undefined)
+    metaObj.gateDecision = proposal.gateDecision;
+  if (proposal.backupContent !== undefined)
+    metaObj.backupContent = proposal.backupContent;
   return {
     id: proposal.id,
     stash_dir: stashDir,
@@ -9074,15 +9087,39 @@ function listStateProposals(db, options = {}) {
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const rows = db.prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
               content, frontmatter_json, metadata_json
-       FROM proposals ${where} ORDER BY created_at ASC`).all(...params);
+       FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`).all(...params);
   return rows.map(proposalRowToProposal);
 }
-function getStateProposal(db, id) {
-  const row = db.prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
+function getStateProposal(db, id, stashDir) {
+  const sql = `SELECT id, stash_dir, ref, status, source, created_at, updated_at,
               content, frontmatter_json, metadata_json
-       FROM proposals WHERE id = ?`).get(id);
+       FROM proposals WHERE id = ?${stashDir ? " AND stash_dir = ?" : ""}`;
+  const row = stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id);
   return row ? proposalRowToProposal(row) : undefined;
 }
+function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
+  const escaped = idPrefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+  const rows = db.prepare(`SELECT id FROM proposals
+       WHERE stash_dir = ? AND status = 'pending' AND id LIKE ? ESCAPE '\\'
+       ORDER BY id ASC`).all(stashDir, `${escaped}%`);
+  return rows.map((r) => r.id);
+}
+function hasImportedFsProposals(db, stashDir) {
+  return Boolean(db.prepare("SELECT 1 FROM proposal_fs_imports WHERE stash_dir = ?").get(stashDir));
+}
+function recordFsProposalsImport(db, stashDir, importedCount) {
+  db.prepare("INSERT OR REPLACE INTO proposal_fs_imports (stash_dir, imported_at, imported_count) VALUES (?, ?, ?)").run(stashDir, new Date().toISOString(), importedCount);
+}
+function insertProposalIfAbsent(db, proposal, stashDir) {
+  const v = proposalToRowValues(proposal, stashDir);
+  const result = db.prepare(`
+      INSERT OR IGNORE INTO proposals
+        (id, stash_dir, ref, status, source, created_at, updated_at, content, frontmatter_json, metadata_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(v.id, v.stash_dir, v.ref, v.status, v.source, v.created_at, v.updated_at, v.content, v.frontmatter_json, v.metadata_json);
+  const changes = result.changes ?? 0;
+  return Number(changes) > 0;
+}
 function upsertTaskHistory(db, row) {
   db.prepare(`
     INSERT OR IGNORE INTO task_history
@@ -9363,7 +9400,9 @@ var init_state_db = __esm(() => {
       --
       -- Extensible (metadata_json) columns:
       --   metadata_json TEXT      \u2014 JSON object for future proposal fields.
-      --                             Current fields stored here: sourceRun, review.
+      --                             Current fields stored here: sourceRun,
+      --                             review, confidence, gateDecision (#577),
+      --                             backupContent.
       --
       -- ADD COLUMN extension points (future migrations):
       --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
@@ -9550,6 +9589,16 @@ var init_state_db = __esm(() => {
       CREATE INDEX IF NOT EXISTS idx_extract_sessions_processed
         ON extract_sessions_seen(processed_at);
     `
+    },
+    {
+      id: "005-proposal-fs-imports",
+      up: `
+      CREATE TABLE IF NOT EXISTS proposal_fs_imports (
+        stash_dir      TEXT    PRIMARY KEY,
+        imported_at    TEXT    NOT NULL,
+        imported_count INTEGER NOT NULL DEFAULT 0
+      );
+    `
     }
   ];
 });
@@ -10238,6 +10287,9 @@ var init_inline_refs = __esm(() => {
 import fs9 from "fs";
 import os from "os";
 import path8 from "path";
+function claudeProjectsDir() {
+  return process.env.AKM_CLAUDE_PROJECTS_DIR ?? path8.join(os.homedir(), ".claude", "projects");
+}
 function parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs) {
   if (!entry || typeof entry !== "object")
     return;
@@ -10294,11 +10346,11 @@ function parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs) {
 class ClaudeCodeProvider {
   name = "claude-code";
   isAvailable() {
-    return fs9.existsSync(CLAUDE_PROJECTS_DIR);
+    return fs9.existsSync(claudeProjectsDir());
   }
   *readEvents(input) {
     try {
-      for (const jsonlPath of this.#walkJsonl(CLAUDE_PROJECTS_DIR)) {
+      for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {
         const stat = fs9.statSync(jsonlPath);
         if (stat.mtimeMs < input.sinceMs)
           continue;
@@ -10326,7 +10378,7 @@ class ClaudeCodeProvider {
     }
   }
   listSessions(input = {}) {
-    const root = input.location ?? CLAUDE_PROJECTS_DIR;
+    const root = input.location ?? claudeProjectsDir();
     const sinceMs = input.sinceMs ?? 0;
     const summaries = [];
     try {
@@ -10466,10 +10518,8 @@ class ClaudeCodeProvider {
     } catch {}
   }
 }
-var CLAUDE_PROJECTS_DIR;
 var init_session_log = __esm(() => {
   init_inline_refs();
-  CLAUDE_PROJECTS_DIR = path8.join(os.homedir(), ".claude", "projects");
 });
 
 // src/integrations/harnesses/claude/index.ts
@@ -15458,6 +15508,7 @@ var init_config_schema = __esm(() => {
     contradictionDetection: exports_external.object({ enabled: exports_external.boolean().optional() }).strict().optional(),
     defaultSince: exports_external.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
+    minContentChars: exports_external.number().int().min(0).optional(),
     maxChunkSize: exports_external.number().int().min(1).max(50).optional(),
     minNewSessions: exports_external.number().int().min(0).optional(),
     indexSessions: exports_external.boolean().optional(),
@@ -16280,7 +16331,7 @@ function openDatabase2(dbPath, options) {
   }
   const db = openDatabase(resolvedPath);
   db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec("PRAGMA busy_timeout = 30000");
   db.exec("PRAGMA foreign_keys = ON");
   loadVecExtension(db);
   const resolvedDim = options?.embeddingDim ?? resolveConfiguredEmbeddingDim();
@@ -16304,7 +16355,7 @@ function openExistingDatabase(dbPath) {
   const resolvedPath = dbPath ?? getDbPath();
   const db = openDatabase(resolvedPath);
   db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec("PRAGMA busy_timeout = 30000");
   db.exec("PRAGMA foreign_keys = ON");
   loadVecExtension(db);
   return db;