akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/feedback-cli.js

@@ -3,20 +3,24 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
+import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
-import { conceptIdFromTypeName, displayRef, parseRefInput } from "../core/asset/resolve-ref.js";
-import { writeFileAtomic } from "../core/common.js";
+import { conceptIdFromTypeName, parseRefInput } from "../core/asset/resolve-ref.js";
+import { isWithin, writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
-import { UsageError } from "../core/errors.js";
+import { NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
+import { resolveMutationTarget } from "../core/mutation-target.js";
 import { getDbPath } from "../core/paths.js";
 import { withStateDb } from "../core/state-db.js";
 import { warn } from "../core/warn.js";
+import { withWriteTargetMutation } from "../core/write-source.js";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { countFeedbackSignals, insertUsageEvent, resolveUsageEventSource } from "../indexer/usage/usage-events.js";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
-import { findEntryIdByRef, getEntryById, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
+import { findEntryIdByRef, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
 import { applyFeedbackToUtilityScore } from "../storage/repositories/index-utility-repository.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
@@ -56,34 +60,68 @@ function validateFeedbackTags(raw) {
  * an existing asset — the same pattern memory-inference uses for
  * `inferenceProcessed`.
  */
-function appendLessonStrength(type, name, feedbackRef) {
-    // Canonical 0.9.0 conceptId (`lessons/<name>`, D-R3) — `findEntryIdByRef`
-    // keys on the stored `item_ref` and parses its argument as the new grammar,
-    // so a `type:name` lookup here would never match.
-    const ref = conceptIdFromTypeName(type, name);
+function appendLessonStrength(refInput, feedbackRef) {
+    // Canonical conceptId (`lessons/<name>`, D-R3): `findEntryIdByRef` keys on
+    // the stored `item_ref`.
+    const conceptId = conceptIdFromTypeName(refInput.type, refInput.name);
+    const config = loadConfig();
     let filePath;
+    let bundleId;
     const db = openExistingDatabase();
     try {
-        const entryId = findEntryIdByRef(db, ref);
-        if (entryId === undefined) {
-            warn(`[feedback] --applied-to: lesson ${ref} is not in the index.`);
-            return null;
+        const entryId = findEntryIdByRef(db, makeBundleRef(refInput.origin, conceptId));
+        if (entryId !== undefined) {
+            const itemRef = getItemRefById(db, entryId);
+            const parsedItemRef = itemRef ? parseBundleRef(itemRef) : undefined;
+            filePath = getEntryFilePathById(db, entryId) ?? undefined;
+            bundleId = parsedItemRef?.bundle;
         }
-        const resolvedPath = getEntryFilePathById(db, entryId);
-        if (!resolvedPath) {
-            warn(`[feedback] --applied-to: cannot resolve file path for ${ref}.`);
-            return null;
-        }
-        filePath = resolvedPath;
     }
     finally {
         closeDatabase(db);
     }
-    if (!filePath || !fs.existsSync(filePath)) {
-        warn(`[feedback] --applied-to: lesson file missing on disk for ${ref}.`);
+    const requestedRef = makeBundleRef(refInput.origin, conceptId);
+    if (!filePath || !bundleId || !fs.existsSync(filePath)) {
+        warn(`[feedback] --applied-to: lesson ${requestedRef} is not in the index or is missing on disk.`);
+        return null;
+    }
+    const resolved = resolveMutationTarget(config, { ...refInput, origin: bundleId });
+    if (!isWithin(filePath, resolved.target.source.path)) {
+        throw new UsageError(`Resolved lesson ${requestedRef} is outside bundle "${bundleId}".`);
+    }
+    fs.lstatSync(filePath);
+    const initialUpdate = buildLessonStrengthUpdate(fs.readFileSync(filePath), feedbackRef);
+    if (!initialUpdate.nextBytes) {
+        return { ref: makeBundleRef(bundleId, conceptId), strength: initialUpdate.strength };
+    }
+    let strength = initialUpdate.strength;
+    let mutationStarted = false;
+    try {
+        withWriteTargetMutation(resolved.target, [filePath], {
+            ignored: "reject",
+            purpose: "feedback-lesson-credit",
+            message: `Update ${makeBundleRef(bundleId, conceptId)}`,
+        }, () => {
+            const stat = fs.lstatSync(filePath);
+            const update = buildLessonStrengthUpdate(fs.readFileSync(filePath), feedbackRef);
+            strength = update.strength;
+            if (!update.nextBytes)
+                return;
+            mutationStarted = true;
+            // Preserve the existing file's permission bits (markdown assets are typically 0o644).
+            writeFileAtomic(filePath, update.nextBytes, stat.mode & 0o777);
+        });
+    }
+    catch (err) {
+        if (mutationStarted)
+            throw err;
+        warn(`[feedback] --applied-to: failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
-    const raw = fs.readFileSync(filePath, "utf8");
+    return { ref: makeBundleRef(bundleId, conceptId), strength };
+}
+function buildLessonStrengthUpdate(rawBytes, feedbackRef) {
+    const raw = rawBytes.toString("utf8");
     const parsed = parseFrontmatter(raw);
     const data = { ...parsed.data };
     const existing = data.lessonStrength;
@@ -93,7 +131,6 @@ function appendLessonStrength(type, name, feedbackRef) {
             ? [existing.trim()]
             : [];
     if (strengthList.includes(feedbackRef)) {
-        // Already credited — idempotent no-op.
         return { strength: strengthList.length };
     }
     strengthList.push(feedbackRef);
@@ -101,29 +138,29 @@ function appendLessonStrength(type, name, feedbackRef) {
     const block = parseFrontmatterBlock(raw);
     const body = block?.content ?? raw;
     const next = assembleAsset(data, body);
-    try {
-        // Preserve the existing file's permission bits (markdown assets are
-        // typically 0o644); writeFileAtomic defaults to 0o600 otherwise.
-        const mode = fs.statSync(filePath).mode & 0o777;
-        writeFileAtomic(filePath, next, mode);
-    }
-    catch (err) {
-        warn(`[feedback] --applied-to: failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
-    }
-    return { strength: strengthList.length };
+    const nextBytes = Buffer.from(next);
+    return rawBytes.equals(nextBytes) ? { strength: strengthList.length } : { strength: strengthList.length, nextBytes };
 }
 /**
  * Persist the feedback usage-event (state.db) and immediately fold it into the
  * entry's MemRL utility score (index.db). Chunk-8 WI-8.3: usage_events lives in
- * state.db; entries + utility_scores stay in `indexDb`. Positive signals raise
- * search ranking on the next read without a full reindex; negatives are durable
- * but take effect at the next `akm index`. Uses the bounded-step EMA policy
- * (F-5 / #386, arXiv:2601.03192). Best-effort: a utility-update failure never
- * fails the feedback record.
+ * state.db; entries + utility_scores stay in `indexDb`. BOTH positive and
+ * negative signals apply the EMA utility update unconditionally and
+ * immediately when the source is user-attributed — no `akm index` run is
+ * required for either signal to affect search ranking. Uses the bounded-step
+ * EMA policy (F-5 / #386, arXiv:2601.03192).
+ *
+ * The update is intentionally SKIPPED for non-`user` event sources (`improve`,
+ * `task`, `audit`, `unknown`) — an anti-self-reinforcement guard that stops an
+ * agent or automated pipeline from boosting its own picks. This is by design
+ * and must not be removed; R-034 only asks that the skip be surfaced to the
+ * caller rather than passing silently. Best-effort: a utility-update failure
+ * never fails the feedback record.
  */
 function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadataStr) {
     let utilityResult;
+    let rankingUpdateApplied = false;
+    let rankingUpdateSkippedReason;
     const eventSource = resolveUsageEventSource();
     withStateDb((stateDb) => {
         insertUsageEvent(stateDb, {
@@ -134,29 +171,33 @@ function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadata
             metadata: metadataStr,
             source: eventSource,
         });
-        if (eventSource !== "user")
+        if (eventSource !== "user") {
+            rankingUpdateSkippedReason =
+                `feedback source is "${eventSource}", not "user" — ranking updates only apply to user-attributed ` +
+                    "feedback (anti-self-reinforcement guard; set AKM_EVENT_SOURCE=user to record as user demand).";
             return;
+        }
         try {
             const { pos, neg } = countFeedbackSignals(stateDb, entryId);
             utilityResult = applyFeedbackToUtilityScore(indexDb, entryId, pos, neg);
+            rankingUpdateApplied = true;
         }
-        catch {
+        catch (err) {
             // best-effort — feedback recording succeeds even if utility update fails
+            rankingUpdateSkippedReason = `utility update failed: ${err instanceof Error ? err.message : String(err)}`;
         }
     });
-    return utilityResult;
+    return { utilityResult, rankingUpdateApplied, rankingUpdateSkippedReason };
 }
 // ── Command definition ────────────────────────────────────────────────────────
 export const feedbackCommand = defineJsonCommand({
     meta: {
         name: "feedback",
-        description: "Record positive or negative feedback for any indexed stash asset.\n\n" +
-            "Positive feedback boosts an asset's EMA utility score, making it rank higher\n" +
-            "in future searches without requiring a full reindex.\n\n" +
-            "Negative feedback records a negative signal in usage_events and state.db events.\n" +
-            "It does NOT immediately lower the asset's ranking — the EMA utility score is\n" +
-            "updated the next time `akm index` runs (incremental or full). Run `akm index`\n" +
-            "after recording negative feedback to have it reflected in search results.",
+        description: "Record positive or negative feedback for any indexed bundle asset.\n\n" +
+            "Both signals adjust the asset's usefulness score right away, in the same\n" +
+            "process: positive feedback raises it, negative lowers it, and recent\n" +
+            "feedback counts for more than old feedback. No reindex is needed — the new\n" +
+            "score affects ranking starting with the very next `akm search`.",
     },
     args: {
         // Optional in citty so run() is invoked even when omitted; we re-validate
@@ -166,8 +207,7 @@ export const feedbackCommand = defineJsonCommand({
         positive: { type: "boolean", description: "Record positive feedback (boosts ranking immediately)", default: false },
         negative: {
             type: "boolean",
-            description: "Record negative feedback (suppresses ranking after next `akm index`). " +
-                "Reindexing is required for the signal to affect search results.",
+            description: "Record negative feedback (lowers ranking immediately, no reindex needed).",
             default: false,
         },
         reason: {
@@ -176,7 +216,7 @@ export const feedbackCommand = defineJsonCommand({
         },
         "failure-mode": {
             type: "string",
-            description: `Structured failure-mode taxonomy for negative feedback (F-3 / #384). ` +
+            description: "Structured failure-mode taxonomy for negative feedback. " +
                 `Accepted values: ${FEEDBACK_FAILURE_MODES.join(", ")}. ` +
                 "Stored alongside --reason in event metadata for aggregation by the distill pipeline.",
         },
@@ -188,7 +228,8 @@ export const feedbackCommand = defineJsonCommand({
             type: "string",
             description: "Credit a lesson that helped resolve this task. Accepts a `lessons/<name>` ref. " +
                 "When combined with --positive, appends this feedback ref to the target lesson's " +
-                "`lessonStrength[]` frontmatter array (dedup, idempotent). Ignored on non-lesson targets.",
+                "`lessonStrength[]` frontmatter array (dedup, idempotent). A non-lesson target or a " +
+                "missing --positive produces a warning rather than silently doing nothing.",
         },
     },
     async run({ args }) {
@@ -196,7 +237,7 @@ export const feedbackCommand = defineJsonCommand({
         if (!ref) {
             throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skills/deploy` and either --positive or --negative.");
         }
-        const parsedRef = parseRefInput(ref);
+        const parsedRef = parseBundleRef(ref);
         if (args.positive && args.negative) {
             throw new UsageError("Specify either --positive or --negative, not both.");
         }
@@ -256,40 +297,42 @@ export const feedbackCommand = defineJsonCommand({
         // background reindex it spawned — now that ensureIndex is removed, holding
         // the lock only causes feedback to block for the full improve run duration.
         let utilityResult;
+        let rankingUpdateApplied = false;
+        let rankingUpdateSkippedReason;
         let durableRef = ref;
         const db = openExistingDatabase();
         try {
             const config = loadConfig();
             const sources = resolveSourceEntries(undefined, config);
-            const requestedSource = parsedRef.origin
-                ? sources.find((source) => source.registryId === parsedRef.origin ||
-                    ((parsedRef.origin === "local" || parsedRef.origin === "stash") && source === sources[0]))
-                : undefined;
-            if (parsedRef.origin && !requestedSource) {
-                throw new UsageError(`Source "${parsedRef.origin}" is not configured.`, "INVALID_FLAG_VALUE");
+            const requestedSource = parsedRef.bundle ? resolveSourcesForOrigin(parsedRef.bundle, sources)[0] : undefined;
+            if (parsedRef.bundle && !requestedSource) {
+                throw new UsageError(`Source "${parsedRef.bundle}" is not configured.`, "INVALID_FLAG_VALUE");
             }
-            const entryId = findEntryIdByRef(db, ref, requestedSource?.path);
+            const lookupRef = makeBundleRef(parsedRef.bundle, parsedRef.conceptId);
+            const entryId = findEntryIdByRef(db, lookupRef, requestedSource?.path);
             if (entryId === undefined) {
-                throw new UsageError(`Ref "${ref}" is not in the index. ` +
-                    "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
+                // NotFoundError (exit 1), not UsageError (exit 2): the flags parsed
+                // fine, the asset just isn't there. The documented exit-code table
+                // reserves 1 for "requested resource missing", and scripts branch on it.
+                throw new NotFoundError(`Ref "${ref}" is not in the index. ` +
+                    "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.", "ASSET_NOT_FOUND");
             }
-            // Persist the feedback signal into usage_events. For positive signals,
-            // the EMA utility score is updated immediately on the next read path.
-            // For negative signals, the score is adjusted the next time `akm index`
-            // runs — the signal is durable in the DB but does NOT suppress ranking
-            // in search results until after reindexing.
-            const indexedEntry = getEntryById(db, entryId);
-            const source = sources.find((candidate) => candidate.path === indexedEntry?.stashDir);
-            const durableOrigin = parsedRef.origin ?? source?.registryId ?? "stash";
+            // Persist the feedback signal into usage_events. Both positive and
+            // negative signals apply the EMA utility update immediately — no
+            // `akm index` run is required for either signal to affect ranking in
+            // search results (see recordFeedbackUsage / applyFeedbackToUtilityScore).
             // WI-8.5b: the `feedback` / `improve_review_needed` events key on the
             // resolved entry's fully-qualified item_ref — the SAME durable key the
             // usage_events row carries and the SAME spelling the signal-delta
             // correlation reads (buildLatestFeedbackTsMap, collapsed to [item_ref]).
-            // The D-R5 display spelling is the fallback only for a NULL-provenance
-            // (pre-cutover) row that the one-time re-key has not yet finalized.
-            const itemRef = getItemRefById(db, entryId) ?? undefined;
-            durableRef = itemRef ?? displayRef({ type: parsedRef.type, name: parsedRef.name, bundleId: durableOrigin });
-            utilityResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
+            const itemRef = getItemRefById(db, entryId);
+            if (!itemRef)
+                throw new UsageError(`Indexed ref "${ref}" has no durable item ref.`, "INVALID_PROPOSAL");
+            durableRef = itemRef;
+            const recordResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
+            utilityResult = recordResult.utilityResult;
+            rankingUpdateApplied = recordResult.rankingUpdateApplied;
+            rankingUpdateSkippedReason = recordResult.rankingUpdateSkippedReason;
         }
         finally {
             closeDatabase(db);
@@ -305,8 +348,8 @@ export const feedbackCommand = defineJsonCommand({
         // the improve loop. Best-effort — failure is logged but does not fail the
         // feedback command.
         // Emit a structured event rather than a proposal so the review-needed
-        // signal is queryable via `akm events list --type improve_review_needed`
-        // without risking accidental asset overwrite if the proposal is accepted.
+        // signal doesn't risk an accidental asset overwrite if the proposal is
+        // accepted.
         if (utilityResult?.crossedReviewThreshold) {
             try {
                 appendEvent({
@@ -327,23 +370,31 @@ export const feedbackCommand = defineJsonCommand({
         // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
         // target is a `lessons/<name>` ref and the signal is positive, append
         // the feedback ref to the target lesson's `lessonStrength[]`
-        // frontmatter array (dedup, idempotent). Non-lesson targets are
-        // ignored. Failures here are warnings — feedback recording is the
-        // primary contract and must not regress on lesson-write errors.
+        // frontmatter array (dedup, idempotent). Non-lesson targets are REJECTED
+        // with a loud warning (R-033b) rather than silently doing nothing.
+        // Failures here are warnings — feedback recording is the primary
+        // contract and must not regress on lesson-write errors.
         const appliedToRaw = args["applied-to"]?.trim();
         let appliedToResult = null;
         if (appliedToRaw && signal === "positive") {
+            let parsedApplied;
             try {
-                const parsedApplied = parseRefInput(appliedToRaw);
+                parsedApplied = parseRefInput(appliedToRaw);
+            }
+            catch (err) {
+                warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (parsedApplied) {
                 if (parsedApplied.type === "lesson") {
-                    const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
+                    const updated = appendLessonStrength(parsedApplied, durableRef);
                     if (updated) {
-                        appliedToResult = { lessonRef: appliedToRaw, strength: updated.strength };
+                        appliedToResult = { lessonRef: updated.ref, strength: updated.strength };
                     }
                 }
-            }
-            catch (err) {
-                warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
+                else {
+                    warn(`[feedback] --applied-to ${appliedToRaw} was ignored: it resolves to a "${parsedApplied.type}" asset, ` +
+                        "not a lesson. Only `lessons/<name>` refs can be credited via --applied-to.");
+                }
             }
         }
         else if (appliedToRaw && signal !== "positive") {
@@ -356,6 +407,9 @@ export const feedbackCommand = defineJsonCommand({
             reason: reason?.trim() ?? null,
             failureMode: failureMode ?? null,
             tags: validatedTags,
+            rankingUpdate: rankingUpdateApplied
+                ? { applied: true }
+                : { applied: false, reason: rankingUpdateSkippedReason ?? "unknown" },
             ...(appliedToResult
                 ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
                 : {}),

package/dist/commands/health/accept-rate.js

@@ -0,0 +1,58 @@
+// 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-proposal-source accept-rate metrics, folded into `akm health --report`
+ * (0.9.0 CLI overhaul, S3).
+ *
+ * Provides the core self-measurement metric for recursive self-improvement:
+ * if reflect proposals are accepted at 20% and distill proposals at 60%,
+ * that guides resource allocation to higher-ROI generators.
+ *
+ * Previously exposed as the removed `akm history --accept-rate-by-source`
+ * flag (src/commands/sources/history.ts, F-4 / #385); `health` already reads
+ * the pending proposal queue for its own `--report` dataset, so this is the
+ * same read extended to the accepted/rejected archive.
+ */
+import { resolveStashDir } from "../../core/common.js";
+import { listProposals } from "../proposal/repository.js";
+/**
+ * Compute accept-rate-per-source metrics from the proposal store. Defaults to
+ * the configured default stash when `stashDir` is omitted (same resolution
+ * `akm health` already uses for the rest of its report).
+ */
+export function computeAcceptRateBySource(stashDir) {
+    const stash = stashDir ?? resolveStashDir();
+    const bySource = new Map();
+    const countProposals = (statuses, includeArchive) => {
+        for (const status of statuses) {
+            const proposals = listProposals(stash, { status, includeArchive });
+            for (const p of proposals) {
+                const src = p.source || "(unknown)";
+                const entry = bySource.get(src) ?? { accepted: 0, rejected: 0, pending: 0 };
+                if (status === "accepted")
+                    entry.accepted++;
+                else if (status === "rejected")
+                    entry.rejected++;
+                else
+                    entry.pending++;
+                bySource.set(src, entry);
+            }
+        }
+    };
+    countProposals(["pending"], false);
+    countProposals(["accepted", "rejected"], true);
+    return Array.from(bySource.entries())
+        .map(([source, counts]) => {
+        const decided = counts.accepted + counts.rejected;
+        return {
+            source,
+            total: decided + counts.pending,
+            accepted: counts.accepted,
+            rejected: counts.rejected,
+            pending: counts.pending,
+            acceptRate: decided > 0 ? counts.accepted / decided : null,
+        };
+    })
+        .sort((a, b) => b.total - a.total); // Most active source first
+}

package/dist/commands/health/advisories.js

@@ -106,8 +106,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
         const latestCycle = getLatestCycleMetrics(db);
         const cycleSummary = latestCycle
             ? `Latest cycle (${latestCycle.ts}, ${latestCycle.pass}): mean canary recall ${latestCycle.mean_recall.toFixed(3)}, ` +
-                `distinct-content ratio ${latestCycle.distinct_content_ratio.toFixed(3)}, ` +
-                `${latestCycle.accepted_actions} accepted action(s).`
+                `distinct-content ratio ${latestCycle.distinct_content_ratio.toFixed(3)}.`
             : "";
         if (collapseAlertEvents.length > 0) {
             const kinds = [...new Set(collapseAlertEvents.map((e) => String(e.metadata?.kind ?? "unknown")))];
@@ -116,8 +115,8 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
                 name: "collapse-churn-detector",
                 status: "warn",
                 kind: "deterministic",
-                // Collapse kinds are measured, not inferred; churn/merge-floor
-                // volume thresholds are still being tuned (design doc §7).
+                // Collapse kinds are measured, not inferred; the merge-floor
+                // volume threshold is still being tuned (design doc §7).
                 confidence: collapseKinds.length > 0 ? "high" : "medium",
                 message: `R5 detector fired ${collapseAlertEvents.length} alert(s) in window (kinds: ${kinds.join(", ")}). ` +
                     `${cycleSummary} See docs/architecture/specs/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,

package/dist/commands/health/checks.js

@@ -2,13 +2,12 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
 import { loadConfig } from "../../core/config/config.js";
+import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { resolveModel } from "../../integrations/agent/model-aliases.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
-import { TASK_FAIL_RATE_WARN, } from "./types.js";
-const ACTIVE_RUN_WARN_MS = 15 * 60 * 1000;
+import { ACTIVE_RUN_WARN_MS, TASK_FAIL_RATE_WARN, } from "./types.js";
 function credentialAvailable(credential, env) {
     return !credential?.required || credential.names.some((name) => Boolean(env[name]?.trim()));
 }
@@ -29,7 +28,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     if (configuredEngine?.kind === "agent" && configuredEngine.platform === "opencode-sdk") {
         let packageAvailable = false;
         try {
-            const resolvePackage = deps.resolvePackage ?? ((name) => createRequire(import.meta.url).resolve(name));
+            const resolvePackage = deps.resolvePackage ?? ((name) => import.meta.resolve(name));
             resolvePackage("@opencode-ai/sdk");
             packageAvailable = true;
         }
@@ -171,7 +170,10 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     }
 }
 export function runDefaultEngineProbe(deps = {}) {
-    const config = deps.loadConfig?.() ?? loadConfig();
+    // Probe the effective view: an install with no `defaults.engine` but a usable
+    // opencode binary DOES have a working default, and reporting otherwise would
+    // contradict what `workflow run` / `task run` actually do.
+    const { config } = withEngineFallback(deps.loadConfig?.() ?? loadConfig(), deps.which);
     return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
 }
 export function runDefaultLlmEngineProbe(deps = {}) {
@@ -289,16 +291,23 @@ export const HEALTH_CHECKS = [
     {
         name: "active-runs",
         channel: "hard",
-        run: (ctx) => ({
-            name: "active-runs",
-            kind: "deterministic",
-            status: ctx.stuckActiveRuns === 0 ? "pass" : "warn",
-            confidence: "high",
-            message: ctx.stuckActiveRuns === 0
-                ? "No active task runs exceeded the stale threshold."
-                : `${ctx.stuckActiveRuns} active task run(s) are older than ${Math.round(ACTIVE_RUN_WARN_MS / 60000)} minutes.`,
-            evidence: { stuckActiveRuns: ctx.stuckActiveRuns },
-        }),
+        run: (ctx) => {
+            // Name the stuck task_ids (deduped, oldest first) so an operator knows
+            // WHICH tasks to investigate, not just how many rows are stale. No
+            // pid/liveness detection — that's out of scope here.
+            const named = [...ctx.stuckActiveTasks].sort((a, b) => b.ageMs - a.ageMs);
+            const detail = named.map((t) => `${t.taskId} (${Math.round(t.ageMs / 60000)}m)`).join(", ");
+            return {
+                name: "active-runs",
+                kind: "deterministic",
+                status: ctx.stuckActiveRuns === 0 ? "pass" : "warn",
+                confidence: "high",
+                message: ctx.stuckActiveRuns === 0
+                    ? "No active task runs exceeded the stale threshold."
+                    : `${ctx.stuckActiveRuns} active task run(s) are older than ${Math.round(ACTIVE_RUN_WARN_MS / 60000)} minutes: ${detail}.`,
+                evidence: { stuckActiveRuns: ctx.stuckActiveRuns, stuckActiveTasks: ctx.stuckActiveTasks },
+            };
+        },
     },
     {
         name: "default-engine",
@@ -320,23 +329,51 @@ export const HEALTH_CHECKS = [
         // in the HTML report but never surfaced as an advisory, so a sustained
         // 15–16% fail rate stayed invisible on `akm health`. Warn at/above the SAME
         // 5% threshold the html-report badge uses (see TASK_FAIL_RATE_WARN).
+        //
+        // Item 6: the aggregate can hide a single consistently-failing task inside
+        // a large, mostly-healthy population (e.g. 1 flaky task at 100 rows total
+        // reads as <5% aggregate). Also warn when the single worst task_id (with
+        // enough rows to be a real signal — see MIN_ROWS_FOR_WORST_TASK_FAIL_RATE)
+        // crosses the same threshold, naming it explicitly.
         name: "task-fail-rate",
         channel: "advisory",
         run: (ctx) => {
             const pctStr = `${(ctx.taskFailRate * 100).toFixed(1)}%`;
             const thresholdPct = `${(TASK_FAIL_RATE_WARN * 100).toFixed(0)}%`;
-            const warn = ctx.taskFailRate >= TASK_FAIL_RATE_WARN;
+            const aggregateWarn = ctx.taskFailRate >= TASK_FAIL_RATE_WARN;
+            const worst = ctx.worstTaskFailRate;
+            const worstWarn = worst !== null && worst.rate >= TASK_FAIL_RATE_WARN;
+            const warn = aggregateWarn || worstWarn;
+            let message;
+            if (ctx.taskRowCount === 0) {
+                message = `No cron tasks ran since ${ctx.since} — no task-fail-rate signal.`;
+            }
+            else if (warn) {
+                const parts = [];
+                if (aggregateWarn) {
+                    parts.push(`aggregate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} ≥ ${thresholdPct}`);
+                }
+                if (worstWarn && worst) {
+                    const worstPctStr = `${(worst.rate * 100).toFixed(1)}%`;
+                    parts.push(`task "${worst.taskId}" fails ${worstPctStr} of its ${worst.rows} run(s) ≥ ${thresholdPct}`);
+                }
+                message = `Cron task fail rate warning: ${parts.join("; ")} — inspect failed runs (ok=false) for early-exit/harness errors.`;
+            }
+            else {
+                message = `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} (below ${thresholdPct} threshold).`;
+            }
             return {
                 name: "task-fail-rate",
                 kind: "deterministic",
                 status: warn ? "warn" : "pass",
                 confidence: "high",
-                message: ctx.taskRowCount === 0
-                    ? `No cron tasks ran since ${ctx.since} — no task-fail-rate signal.`
-                    : warn
-                        ? `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} ≥ ${thresholdPct} threshold — inspect failed runs (ok=false) for early-exit/harness errors.`
-                        : `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} (below ${thresholdPct} threshold).`,
-                evidence: { taskFailRate: ctx.taskFailRate, taskRowCount: ctx.taskRowCount, threshold: TASK_FAIL_RATE_WARN },
+                message,
+                evidence: {
+                    taskFailRate: ctx.taskFailRate,
+                    taskRowCount: ctx.taskRowCount,
+                    threshold: TASK_FAIL_RATE_WARN,
+                    worstTaskFailRate: worst,
+                },
             };
         },
     },
@@ -354,7 +391,7 @@ export const HEALTH_CHECKS = [
             const endpointAdvisory = blocked && remoteReason && ctx.embeddingEndpoint
                 ? `Configured embedding endpoint ${ctx.embeddingEndpoint} is failing ` +
                     `(${ctx.semanticStatus?.reason}${ctx.semanticStatus?.message ? `: ${ctx.semanticStatus.message}` : ""}) ` +
-                    `while semanticSearchMode is "${ctx.semanticSearchMode ?? "auto"}". Searches fall back to keyword-only. ` +
+                    `while semanticSearchMode is "${ctx.semanticSearchMode ?? "off"}". Searches fall back to keyword-only. ` +
                     `Restore the endpoint, or set semanticSearchMode to "off" (or remove embedding.endpoint to use the local model).`
                 : undefined;
             return {
@@ -489,4 +526,29 @@ export const HEALTH_CHECKS = [
             };
         },
     },
+    {
+        // Item 4: stale durable-transaction journals under $DATA/txn (stranded
+        // recovery state seen twice in a real 0.9 migration) had zero health
+        // visibility. `count`/`unreadable` already exclude journals younger than
+        // the sweeper's grace period (a currently-running operation), so any
+        // nonzero count here is a real leftover.
+        name: "stale-txn-journals",
+        channel: "advisory",
+        run: (ctx) => {
+            const s = ctx.staleTxnJournals;
+            const warn = s.count > 0;
+            const unreadablePart = s.unreadable > 0 ? `, ${s.unreadable} unreadable` : "";
+            const agePart = s.oldestAgeMs !== null ? `, oldest ${Math.round(s.oldestAgeMs / 60000)}m old` : "";
+            return {
+                name: "stale-txn-journals",
+                kind: "deterministic",
+                status: warn ? "warn" : "pass",
+                confidence: "high",
+                message: warn
+                    ? `${s.count} stale transaction journal(s) found under ${s.dir}${unreadablePart}${agePart} — see docs/migration/v0.9.0-troubleshooting.md for journal reconciliation steps.`
+                    : "No stale transaction journals found.",
+                evidence: { dir: s.dir, count: s.count, unreadable: s.unreadable, oldestAgeMs: s.oldestAgeMs },
+            };
+        },
+    },
 ];