akm-cli 0.10.261005-beta → 0.10.261007-beta

package/dist/cli.js

@@ -85,6 +85,7 @@ import { renderMigrationHelp } from "./commands/sources/migration-help.js";
 import { cloneCommand, syncCommand, upgradeCommand } from "./commands/sources/sources-cli.js";
 import { importKnowledgeCommand, indexCommand, infoCommand } from "./commands/sources/stash-cli.js";
 import { taskCommand } from "./commands/tasks/tasks-cli.js";
+import { uiCommand } from "./commands/ui/ui-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
 import { DEFAULT_CONFIG, loadConfig } from "./core/config/config.js";
 import { UsageError } from "./core/errors.js";
@@ -448,6 +449,7 @@ const commands = {
     index: indexCommand,
     health: healthCommand,
     metrics: metricsCommand,
+    ui: uiCommand,
     info: infoCommand,
     bundle: bundleCommand,
     upgrade: upgradeCommand,
@@ -778,6 +780,7 @@ const HELP_SECTIONS = [
             "lint",
             "health",
             "metrics",
+            "ui",
             "config",
             "models",
             "registry",

package/dist/commands/health/checks.js

@@ -902,9 +902,11 @@ export const HEALTH_CHECKS = [
             kind: "deterministic",
             status: ctx.probe.ok ? "pass" : "fail",
             confidence: "high",
-            message: ctx.probe.ok
-                ? "state.db append/read round-trip succeeded."
-                : `state.db round-trip failed: ${ctx.probe.error}`,
+            message: ctx.probe.skipped
+                ? "state.db append/read round-trip skipped: this run is read-only."
+                : ctx.probe.ok
+                    ? "state.db append/read round-trip succeeded."
+                    : `state.db round-trip failed: ${ctx.probe.error}`,
             evidence: { path: ctx.stateDbPath, durationMs: ctx.probe.durationMs },
         }),
     },

package/dist/commands/health/egress.js

@@ -8,6 +8,7 @@
  * configured, matching the `stash-git-exposure` / `binary-config-skew`
  * advisories' pattern.
  */
+import { redactCredentialPatterns } from "../../core/redaction.js";
 import { formatRegistryUrl } from "../../core/registry-url.js";
 /**
  * `egress-endpoints` (08 surfaces 3/9): the full list of remote destinations
@@ -42,6 +43,9 @@ export function collectEgressAdvisory(config) {
         endpoints.push(`embedding: ${config.embedding.endpoint}`);
     if (endpoints.length === 0)
         return undefined;
+    // A configured URL can carry a credential (`?token=…`, `user:pass@`); the list is for eyeballing destinations, so
+    // print the host and path and never the secret.
+    const safe = endpoints.map(redactCredentialPatterns);
     return {
         name: "egress-endpoints",
         kind: "deterministic",
@@ -49,6 +53,6 @@ export function collectEgressAdvisory(config) {
         confidence: "high",
         message: `${endpoints.length} remote endpoint(s) in the effective config (registries/sources/LLM/embedding) — ` +
             "review the evidence list for unexpected destinations.",
-        evidence: { endpoints },
+        evidence: { endpoints: safe },
     };
 }

package/dist/commands/health/engine-usage.js

@@ -28,9 +28,9 @@ export function engineLastUsedSince(now) {
  * `engine` field (pre-#576 rows, or a call outside any resolved engine) is
  * skipped rather than bucketed under a synthetic key.
  */
-export function readLastEngineUsage(stateDbPath, now) {
+export function readLastEngineUsage(stateDbPath, now, readOnly = false) {
     const since = engineLastUsedSince(now);
-    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath }).events;
+    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath, readOnly }).events;
     const lastUsed = new Map();
     for (const event of events) {
         const record = decodeLlmUsageRecord(event.metadata);

package/dist/commands/health/llm-usage.js

@@ -59,8 +59,8 @@ export function summarizeLlmUsage(events) {
     }
     return aggregate;
 }
-export function readLlmUsageAggregate(stateDbPath, since, until) {
-    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath }).events.filter((event) => {
+export function readLlmUsageAggregate(stateDbPath, since, until, readOnly = false) {
+    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath, readOnly }).events.filter((event) => {
         if (until === undefined)
             return true;
         return new Date(event.ts ?? since).getTime() < new Date(until).getTime();

package/dist/commands/health/windows.js

@@ -151,9 +151,9 @@ export function computeTaskWindowRates(taskRows, now) {
  * stats from the same per-run rows, and accepted-proposal coverage, all over
  * one `[since, until)`.
  */
-export function buildImproveWindowSummary(db, stateDbPath, since, until) {
+export function buildImproveWindowSummary(db, stateDbPath, since, until, readOnly = false) {
     const untilMs = new Date(until).getTime();
-    const eventsBeforeUntil = (type) => readEvents({ since, type }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < untilMs);
+    const eventsBeforeUntil = (type) => readEvents({ since, type }, { dbPath: stateDbPath, readOnly }).events.filter((event) => new Date(event.ts ?? since).getTime() < untilMs);
     const { metrics: improve, runCount } = summarizeImproveRuns(db, since, until);
     improve.invoked = eventsBeforeUntil("improve_invoked").length;
     improve.completed = eventsBeforeUntil(IMPROVE_COMPLETED_EVENT).length;
@@ -167,20 +167,20 @@ export function buildImproveWindowSummary(db, stateDbPath, since, until) {
     improve.coverage = computeWindowProposalCoverage(db, since, until);
     return { improve, runCount, perRunSummaries };
 }
-export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now()) {
+export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now(), readOnly = false) {
     const untilMs = new Date(until).getTime();
     const taskRows = queryTaskHistory(db, { since }).filter((row) => {
         const startMs = new Date(row.started_at).getTime();
         return !Number.isFinite(untilMs) || startMs < untilMs;
     });
     const rates = computeTaskWindowRates(taskRows, now);
-    const { improve, runCount } = buildImproveWindowSummary(db, stateDbPath, since, until);
+    const { improve, runCount } = buildImproveWindowSummary(db, stateDbPath, since, until, readOnly);
     const metrics = {
         taskFailRate: roundRate(rates.taskFailRate),
         agentFailureRate: roundRate(rates.agentFailureRate),
         agentFailureReasonCounts: rates.agentFailureReasonCounts,
         stuckActiveRuns: rates.stuckActiveRuns,
-        llmUsage: readLlmUsageAggregate(stateDbPath, since, until),
+        llmUsage: readLlmUsageAggregate(stateDbPath, since, until, readOnly),
     };
     return { improve, metrics, runs: runCount };
 }

package/dist/commands/health.js

@@ -11,12 +11,14 @@ import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from ".
 import { listExistingTableNames, listPendingStateMigrations, openStateDatabaseWithReport, withStateDb, } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { probeLlmEndpoint } from "../llm/client.js";
+import { openDatabase } from "../storage/database.js";
 import { insertEvent } from "../storage/repositories/events-repository.js";
 import { getExtractOutcomeCountsSince } from "../storage/repositories/extract-sessions-repository.js";
 import { countImproveRunsSince } from "../storage/repositories/improve-runs-repository.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
 import { queryTaskHistory } from "../storage/repositories/task-history-repository.js";
+import { applyReadonlyPragmas } from "../storage/sqlite-pragmas.js";
 import { getStateDbFreelistInfo, runStateDbIntegrityCheck } from "../storage/state-db-integrity.js";
 import { pkgVersion } from "../version.js";
 import { collectArchiveUsageAdvisory } from "./health/archive-usage.js";
@@ -176,12 +178,12 @@ function computeWorstTaskFailRate(rows) {
     return worst;
 }
 /** Table presence, the state.db round-trip probe, and task_history-derived rates. */
-function gatherTaskHistoryPhase(db, since, stateDbPath, now) {
+function gatherTaskHistoryPhase(db, since, stateDbPath, now, readOnly) {
     const tables = listExistingTableNames(db, ["events", "task_history", "proposals", "schema_migrations"]);
     const tableNames = tables.map((row) => row.name).sort();
     const requiredTables = ["events", "proposals", "schema_migrations", "task_history"];
     const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
-    const probe = probeStateDbRoundTrip(stateDbPath);
+    const probe = readOnly ? { ok: true, durationMs: null, skipped: true } : probeStateDbRoundTrip(stateDbPath);
     // R0: read-only, independent of the round-trip probe above — integrity_check
     // catches corruption a successful append/read cannot (out-of-order rowids,
     // bad index entry counts), and the freelist reading is purely informational.
@@ -440,7 +442,7 @@ function resolveWindowComparePhase(options, db, stateDbPath, now) {
         windowResults = windowSpecs.map((spec) => {
             const winSince = parseHealthSince(spec.since);
             const winUntil = spec.until ? parseHealthSince(spec.until) : new Date(now()).toISOString();
-            const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil, now);
+            const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil, now, options.readOnly === true);
             return {
                 name: spec.name,
                 since: winSince,
@@ -508,6 +510,25 @@ function unreadableStateDbCheck(detail) {
         evidence: { detail },
     };
 }
+/**
+ * Why a read-only health run cannot use `stateDbPath`, as the failing check to
+ * report: the file is missing, or it is behind on migrations (a read-only open
+ * must not apply them). `undefined` when it can be read as it is.
+ */
+function readOnlyStateDbUnavailable(stateDbPath) {
+    if (!fs.existsSync(stateDbPath)) {
+        return {
+            name: "state-db-readable",
+            kind: "deterministic",
+            status: "fail",
+            confidence: "high",
+            message: `state.db does not exist at ${stateDbPath}; a read-only health run does not create it. Run any akm command that records state, such as \`akm health\`.`,
+            evidence: { path: stateDbPath },
+        };
+    }
+    const pending = runPendingStateMigrationsCheck(stateDbPath, { listPendingStateMigrations });
+    return pending.status === "fail" ? pending : undefined;
+}
 export async function akmHealth(options = {}) {
     validateAkmHealthOptions(options);
     const now = options.now ?? (() => Date.now());
@@ -521,9 +542,20 @@ export async function akmHealth(options = {}) {
     // to find out why everything else is behaving oddly. Report it as a finding
     // instead of dying before any check runs. The open itself applies every
     // pending migration; `state-db-migrations` reports what it applied.
+    const readOnly = options.readOnly === true;
     let opened;
     try {
-        opened = openStateDatabaseWithReport(stateDbPath);
+        if (readOnly) {
+            const unavailable = readOnlyStateDbUnavailable(stateDbPath);
+            if (unavailable)
+                return degradedStateDbReport(unavailable, options);
+            const db = openDatabase(stateDbPath, { readonly: true, create: false });
+            applyReadonlyPragmas(db);
+            opened = { db, applied: [] };
+        }
+        else {
+            opened = openStateDatabaseWithReport(stateDbPath);
+        }
     }
     catch (error) {
         const { access, code } = classifyPathAccess(stateDbPath);
@@ -561,14 +593,14 @@ export async function akmHealth(options = {}) {
             cliVersion: pkgVersion,
         });
         schedulerBinaryDriftPromise.catch(() => undefined);
-        const taskHistory = gatherTaskHistoryPhase(db, since, stateDbPath, now);
+        const taskHistory = gatherTaskHistoryPhase(db, since, stateDbPath, now, readOnly);
         const { tableNames, missingTables, probe } = taskHistory;
         const { egressConfigView, thinkingOffEngines } = gatherEgressConfigPhase();
         // Same window bundle `--window-compare` builds per-window (windows.ts) —
         // reused here for the main `--since` window's improve summary and for
         // `--group-by run`, so neither re-reads `improve_runs`.
         const until = new Date(now()).toISOString();
-        const { improve: improveSummary, perRunSummaries } = buildImproveWindowSummary(db, stateDbPath, since, until);
+        const { improve: improveSummary, perRunSummaries } = buildImproveWindowSummary(db, stateDbPath, since, until, readOnly);
         advisories.push(...gatherAncillaryAdvisories(db, options, egressConfigView));
         const sessionExtractionLedger = gatherSessionExtractionLedgerPhase(db, now);
         // #950: computed once (no IO beyond config/env, same as gatherEgressConfigPhase)
@@ -578,14 +610,14 @@ export async function akmHealth(options = {}) {
         // #950: `engine-last-used` reads a fixed lookback window independent of
         // `--since` (mirrors sessionExtractionLedger's independent window above).
         const engineLastUsedSinceIso = engineLastUsedSince(now);
-        const engineLastUsed = readLastEngineUsage(stateDbPath, now);
+        const engineLastUsed = readLastEngineUsage(stateDbPath, now, readOnly);
         const improveRunsInLookbackWindow = countImproveRunsSince(db, engineLastUsedSinceIso);
         const engineProbes = await engineProbesPromise;
         const versionDrift = await versionDriftPromise;
         const schedulerBinaryDrift = await schedulerBinaryDriftPromise;
         // Read once, shared by the `thinking-control` check (#949) and the
         // `metrics.llmUsage` report field below — same window, same aggregate.
-        const llmUsage = readLlmUsageAggregate(stateDbPath, since);
+        const llmUsage = readLlmUsageAggregate(stateDbPath, since, undefined, readOnly);
         // Run the ordered health-check registry. Each check projects the shared
         // context computed above into one HealthCheckResult; `channel` routes it to
         // hardChecks or advisories. Declaration order in HEALTH_CHECKS is the

package/dist/commands/improve/reflect-noise.js

@@ -158,6 +158,10 @@ export function splitFrontmatter(raw) {
     const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
     return m ? { fmText: m[1] ?? "", body: m[2] ?? "" } : { fmText: null, body: raw };
 }
+/** A level-1 heading line (`# text`) anywhere in a body: what reflect's title adds only when none is there. */
+export function bodyHasH1(body) {
+    return /^#[ \t]+\S/m.test(body);
+}
 /** Frontmatter text, fenced code blocks, and prose lines (an unclosed fence counts as prose). */
 function parseSections(text) {
     const { fmText, body } = splitFrontmatter(normalizeTrailingWhitespace(text));

package/dist/commands/improve/reflect.js

@@ -44,7 +44,7 @@ import { contentHash } from "./content-hash.js";
 import { findAssetFilePath } from "./eligibility.js";
 import { resolveImproveExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
-import { classifyReflectChange, findReflectDefect, splitFrontmatter } from "./reflect-noise.js";
+import { bodyHasH1, classifyReflectChange, findReflectDefect, splitFrontmatter, } from "./reflect-noise.js";
 import { callStageOnce, errMessage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
@@ -151,10 +151,17 @@ function firstProseSentence(body) {
     }
     return "";
 }
+/** The body with `# title` and one blank line inserted at its first non-blank line; the rest is untouched. */
+function withH1(body, title) {
+    const eol = body.match(/\r?\n/)?.[0] ?? "\n";
+    const leading = body.match(/^(?:\r?\n)*/)?.[0] ?? "";
+    return `${leading}# ${title}${eol}${eol}${body.slice(leading.length)}`;
+}
 /**
  * The asset with the patch applied, or `undefined` when the patch changes
  * nothing (or there is no asset to patch). The body is the source's own, byte
- * for byte; the one thing akm adds to it is a `# title` heading it lacks. A
+ * for byte; the one thing akm adds to it is a `# title` heading it lacks, with
+ * one blank line after it (#1183). A
  * required description that neither the source nor the patch has is derived
  * from the asset's own text (#636). Only the changed keys' frontmatter lines are
  * rewritten: every other line is kept as it is, so a source whose YAML the
@@ -170,8 +177,10 @@ export function applyReflectPatch(patch, sourceContent, targetRef) {
         return undefined;
     const sourceFm = fmText !== null ? parseFrontmatter(sourceContent).data : {};
     const { title, ...changes } = patch;
-    const addTitle = title !== undefined && !/^#[ \t]+\S/m.test(sourceBody);
-    const body = addTitle ? `# ${title}\n\n${sourceBody.replace(/^(\r?\n)+/, "")}` : sourceBody;
+    const addTitle = title !== undefined && !bodyHasH1(sourceBody);
+    // The heading and one blank line go in at the body's first non-blank line, in
+    // the body's own line ending; every other byte of the body stays where it was.
+    const body = addTitle ? withH1(sourceBody, title) : sourceBody;
     // Only a source that already has frontmatter but no description gets one:
     // injecting a whole block, or overwriting an authored one, is out of scope.
     const refType = lenientRefType(targetRef);
@@ -198,7 +207,7 @@ export function applyReflectPatch(patch, sourceContent, targetRef) {
         const content = `---\n${serializeFrontmatter(changes)}\n---\n\n${body}`;
         return { content, frontmatter: parseFrontmatter(content).data };
     }
-    const content = `---\n${patchFrontmatterLines(fmText, changes)}\n---\n${addTitle ? "\n" : ""}${body}`;
+    const content = `---\n${patchFrontmatterLines(fmText, changes)}\n---\n${body}`;
     return { content, frontmatter: parseFrontmatter(content).data };
 }
 /** The frontmatter text with each changed key's lines (the key line and its indented continuation) replaced, or appended. */

package/dist/commands/metrics/metrics-cli.js

@@ -53,7 +53,7 @@ export function metricsIncludeRows(mode) {
  * `bundle//conceptId`; resolving here keeps one asset from showing as two rows.
  * A ref that does not resolve (registry results, removed assets) is kept as is.
  */
-async function durableSelects(selects) {
+async function durableSelects(selects, indexSnapshot = true) {
     const unqualified = [];
     for (const ref of new Set(selects.map((select) => select.ref))) {
         try {
@@ -65,7 +65,7 @@ async function durableSelects(selects) {
             // Not a local bundle ref: keep the ref as recorded.
         }
     }
-    const entries = await lookupBundleRefsReadonly(unqualified.map(({ parsed }) => parsed));
+    const entries = await lookupBundleRefsReadonly(unqualified.map(({ parsed }) => parsed), { isolatedSnapshot: indexSnapshot });
     const resolved = new Map(unqualified.map(({ ref }, i) => [ref, entries[i]?.itemRef ?? ref]));
     return selects.map((select) => ({ ts: select.ts, ref: resolved.get(select.ref) ?? select.ref }));
 }
@@ -190,7 +190,7 @@ export async function akmMetrics(options = {}) {
     finally {
         stateDb.close();
     }
-    input.selects = await durableSelects(selects);
+    input.selects = await durableSelects(selects, options.indexSnapshot ?? true);
     return buildMetricsResult(input);
 }
 export const metricsCommand = defineJsonCommand({

package/dist/commands/proposal/propose-cli.js

@@ -47,6 +47,10 @@ export const proposeCommand = defineCommand({
         },
         task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
         file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
+        bundle: {
+            type: "string",
+            description: "Configured writable bundle to queue the proposal for and draw convention facts from (default: the working bundle)",
+        },
         engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
         "timeout-ms": { type: "string", description: "Override the engine timeout in milliseconds" },
     },
@@ -73,6 +77,7 @@ export const proposeCommand = defineCommand({
                 name: proposedName,
                 task: taskText,
                 engine: getStringArg(args, "engine"),
+                bundle: getStringArg(args, "bundle"),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             });
             output("proposal-new", result);

package/dist/commands/proposal/propose.js

@@ -23,6 +23,7 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { runStructured } from "../../core/structured.js";
 import { warn } from "../../core/warn.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
 import { deriveEntryProvenance } from "../../indexer/installations.js";
 import { fallbackAnnouncement } from "../../integrations/agent/engine-fallback.js";
 import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
@@ -144,10 +145,13 @@ export async function akmPropose(options) {
     if (!stashDirFor(options.type)) {
         throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${[...placementTypes()].sort().join(", ")}.`, "INVALID_FLAG_VALUE");
     }
-    const stash = options.stashDir ?? resolveStashDir();
     // 1. Resolve the write target. Engine/model/inference resolution happens
-    // exactly once below through the shared execution cascade.
+    // exactly once below through the shared execution cascade. `--bundle` names a
+    // configured, writable bundle (same resolver and errors as `akm remember
+    // --bundle`); its root becomes the stash the proposal is queued for and the
+    // prompt's standards are read from.
     const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
+    const stash = options.stashDir ?? (options.bundle ? resolveWriteTarget(config, options.bundle).source.path : resolveStashDir());
     const target = resolveProposalQueueTarget(stash, config);
     // 2. Build terminal user content.
     // Standards "rulebook" for this target — wiki schema (wiki page) or stash

package/dist/commands/proposal/repository.js

@@ -436,34 +436,36 @@ function requireProposal(db, stashDir, id) {
  * proposal (then most recent archived); else by a unique pending id prefix.
  */
 export function resolveProposalId(stashDir, idOrRef, ctx) {
-    return withProposalsDb(ctx, (db) => {
-        const exact = getStateProposal(db, idOrRef, stashDir);
-        if (exact)
-            return exact;
-        if (idOrRef.includes(":") || idOrRef.includes("/")) {
-            const wantRef = filterRefIdentity(idOrRef);
-            // Should-fix 7: by-ref resolution never picks a retire proposal — the
-            // newest pending proposal for a ref could be a `consolidate-pair`
-            // retirement rather than the reflect/distill edit a person typed the
-            // ref to accept, and accepting it archives the asset instead. A retire
-            // is reached by its own proposal id, or by the explicit generator
-            // `consolidate-pair` (bulk accept/reject).
-            const newest = (status) => listStateProposals(db, { stashDir, ...(status !== undefined ? { status } : {}) })
-                .filter((p) => proposalMatchesRef(p.ref, wantRef) && !isRetireProposal(p))
-                .sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
-            const found = newest("pending") ?? newest();
-            if (found)
-                return found;
-            throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "PROPOSAL_NOT_FOUND");
-        }
-        const prefixMatches = listStateProposalIdsByPrefix(db, stashDir, idOrRef);
-        if (prefixMatches.length === 1)
-            return requireProposal(db, stashDir, prefixMatches[0]);
-        if (prefixMatches.length > 1) {
-            throw new UsageError(`Ambiguous prefix "${idOrRef}" — matches: ${prefixMatches.join(", ")}`, "INVALID_FLAG_VALUE");
-        }
-        throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "PROPOSAL_NOT_FOUND");
-    });
+    return withProposalsDb(ctx, (db) => resolveProposalIdIn(db, stashDir, idOrRef));
+}
+/** {@link resolveProposalId} over a connection the caller holds (`akm ui` reads state.db read-only). */
+export function resolveProposalIdIn(db, stashDir, idOrRef) {
+    const exact = getStateProposal(db, idOrRef, stashDir);
+    if (exact)
+        return exact;
+    if (idOrRef.includes(":") || idOrRef.includes("/")) {
+        const wantRef = filterRefIdentity(idOrRef);
+        // Should-fix 7: by-ref resolution never picks a retire proposal — the
+        // newest pending proposal for a ref could be a `consolidate-pair`
+        // retirement rather than the reflect/distill edit a person typed the
+        // ref to accept, and accepting it archives the asset instead. A retire
+        // is reached by its own proposal id, or by the explicit generator
+        // `consolidate-pair` (bulk accept/reject).
+        const newest = (status) => listStateProposals(db, { stashDir, ...(status !== undefined ? { status } : {}) })
+            .filter((p) => proposalMatchesRef(p.ref, wantRef) && !isRetireProposal(p))
+            .sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+        const found = newest("pending") ?? newest();
+        if (found)
+            return found;
+        throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "PROPOSAL_NOT_FOUND");
+    }
+    const prefixMatches = listStateProposalIdsByPrefix(db, stashDir, idOrRef);
+    if (prefixMatches.length === 1)
+        return requireProposal(db, stashDir, prefixMatches[0]);
+    if (prefixMatches.length > 1) {
+        throw new UsageError(`Ambiguous prefix "${idOrRef}" — matches: ${prefixMatches.join(", ")}`, "INVALID_FLAG_VALUE");
+    }
+    throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "PROPOSAL_NOT_FOUND");
 }
 /**
  * The ledger outcome of a decision. A procedural refusal (retention expiry, a
@@ -1869,7 +1871,10 @@ export function reopenProposals(stashDir, config, ids, options = {}, ctx) {
 }
 /** The proposal against the asset its accept would overwrite (same target resolution as accept). */
 export function diffProposal(stashDir, config, id, options = {}, ctx) {
-    const proposal = getProposal(stashDir, id, ctx);
+    return diffLoadedProposal(config, getProposal(stashDir, id, ctx), options);
+}
+/** {@link diffProposal} for a proposal the caller already read (`akm ui` reads state.db read-only). */
+export function diffLoadedProposal(config, proposal, options = {}) {
     const target = resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget);
     const targetPath = resolveAssetFilePathSafe(target.source, parseRefInput(proposal.ref));
     const existing = targetPath && fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null;

package/dist/commands/read/search.js

@@ -123,6 +123,7 @@ export async function akmSearch(input) {
             // would leak hits from sources the caller did not request.
             restrictToSources: namedSourceName !== undefined,
             includeExcludedTypes: input.includeSessions === true,
+            readOnly: input.readOnly,
         });
     const registryResult = source === "local"
         ? undefined
@@ -201,7 +202,7 @@ function usageSearchMode(mode) {
     return mode === "semantic" ? "semantic" : "keyword";
 }
 function maybeLogSearchEvent(input, query, response, mode) {
-    if (input.skipLogging)
+    if (input.skipLogging || input.readOnly)
         return;
     logSearchEvent(query, response, mode, input.eventSource, input.attributionProjection);
 }

package/dist/commands/read/show.js

@@ -33,7 +33,7 @@ import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { warn, warnOnce } from "../../core/warn.js";
-import { lookupBundleRef, lookupBundleRefWithResolution } from "../../indexer/indexer.js";
+import { lookupBundleRef, lookupBundleRefWithResolution, lookupBundleRefWithResolutionReadonly, } from "../../indexer/indexer.js";
 import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries, } from "../../indexer/search/search-source.js";
@@ -65,7 +65,7 @@ export async function akmShowUnified(input) {
     {
         const metaRef = parseMetaRef(ref);
         if (metaRef)
-            return showStashMeta(metaRef);
+            return showStashMeta(metaRef, input.readOnly === true);
     }
     // Env/secret bodies have no safe fragment surface, and a fragment cannot
     // widen what the env/secret renderers expose: both always omit the body
@@ -77,7 +77,7 @@ export async function akmShowUnified(input) {
     // safe substrate below is its source of truth. Friendly heading selectors
     // intentionally retain the normal source-live read behavior.
     const parsedRef = parseBundleRef(ref);
-    if (!parsedRef.fragment?.startsWith("akm-fragment-")) {
+    if (!input.readOnly && !parsedRef.fragment?.startsWith("akm-fragment-")) {
         const { primarySource } = resolveReadSources();
         await ensurePrimaryIndexForRead(primarySource);
     }
@@ -91,7 +91,7 @@ export async function akmShowUnified(input) {
         enforceScopeOrThrow(result.path, ref, input.scope);
     }
     // Count prior shows of this ref before logging the current one.
-    if (!input.skipLogging) {
+    if (!input.skipLogging && !input.readOnly) {
         const consumedRef = result.ref ?? makeBundleRef(undefined, parseBundleRef(ref).conceptId);
         const priorShowCount = recentShowCount(consumedRef);
         recordShowUsage(consumedRef, result.type, result.name, input.eventSource, result.path);
@@ -110,7 +110,7 @@ export async function akmShowUnified(input) {
  * to that stash; an uninstalled origin yields an actionable "not installed"
  * error. The file is read directly from disk — `.meta/` is never indexed.
  */
-async function showStashMeta(metaRef) {
+async function showStashMeta(metaRef, readOnly = false) {
     const allSources = resolveSourceEntries();
     const sources = resolveSourcesForOrigin(metaRef.origin, allSources);
     if (metaRef.origin && sources.length === 0) {
@@ -123,7 +123,9 @@ async function showStashMeta(metaRef) {
         if (!metaFile)
             continue;
         const editable = isEditable(metaFile.path, config, allSources);
-        appendEvent({ eventType: "show", ref: `meta:${metaRef.name}`, metadata: { type: "meta", name: metaRef.name } });
+        if (!readOnly) {
+            appendEvent({ eventType: "show", ref: `meta:${metaRef.name}`, metadata: { type: "meta", name: metaRef.name } });
+        }
         return {
             type: "meta",
             name: metaRef.name,
@@ -211,7 +213,9 @@ export async function showLocal(input) {
     const allSources = resolveSourceEntries(input.stashDir);
     const searchSources = resolveSourcesForOrigin(parsed.bundle, allSources);
     const allSourceDirs = searchSources.map((s) => s.path);
-    const resolution = await lookupBundleRefWithResolution(parsed);
+    const resolution = input.readOnly
+        ? await lookupBundleRefWithResolutionReadonly(parsed)
+        : await lookupBundleRefWithResolution(parsed);
     if (resolution.indexError !== undefined)
         throw resolution.indexError;
     const indexedEntry = resolution.entry;
@@ -260,7 +264,9 @@ export async function showLocal(input) {
     // Only resolve the indexed-safe revision when the selector itself is opaque,
     // or when the caller explicitly opts into indexed-safe contextual output.
     const indexedFragment = parsed.fragment && (opaqueFragmentSelector || input.contextMode === "lead")
-        ? withIndexDb((db) => getIndexedMarkdownFragment(db, indexedEntry.itemRef, parsed.fragment))
+        ? withIndexDb((db) => getIndexedMarkdownFragment(db, indexedEntry.itemRef, parsed.fragment), {
+            readOnly: input.readOnly === true,
+        })
         : undefined;
     const indexedFragmentContent = opaqueFragmentSelector ? indexedFragment?.content : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
@@ -364,9 +370,9 @@ export async function showLocal(input) {
         origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(canonicalRef) } : {}),
-        ...showLinks(indexedEntry.itemRef, displayDefaultBundle),
+        ...showLinks(indexedEntry.itemRef, displayDefaultBundle, input.readOnly === true),
     };
-    const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
+    const activeRun = input.readOnly ? null : await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
@@ -385,10 +391,10 @@ const LINKS_PER_KIND = 10;
  * authored order, incoming by ref, and unresolved tokens as authored. Empty
  * parts are omitted, and the field when nothing links either way.
  */
-function showLinks(itemRef, defaultBundle) {
+function showLinks(itemRef, defaultBundle, readOnly = false) {
     let rows;
     try {
-        rows = withIndexDb((db) => readEntryLinks(db, itemRef));
+        rows = withIndexDb((db) => readEntryLinks(db, itemRef), { readOnly });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);