akm-cli 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.11] - 2026-09-03
+
+### Added
+
+- **`akm task validate <path>` reports what `akm task sync` would say about one
+  task file (#907).** It parses a single file by filesystem path, without a
+  bundle, a concept ref, or a configured engine, and reports `valid`,
+  `converts` (a v2/v3 source the migrator converts deterministically),
+  `blocked` (needs a human decision), `invalid`, or `not-a-task`, with the
+  reason sync would give. It runs the same two gates sync runs before
+  installing a schedule, the defaults-applied schedule input contract and
+  the cron dialect check, which are now shared with `compileTaskSources` so
+  the two commands cannot drift. Exit 0 for valid/converts, 1 for the rest,
+  2 for a missing or unreadable path. `resolved` on success is the compiled
+  task shape (id, version, target, inputs, schedule), never an
+  execution-lowered plan.
+- **`engines.<name>.apiKeyFile` supplies an LLM engine credential from a file
+  (#905).** A host that refuses secrets in the process environment can point
+  an engine at a path instead of a `$VAR` reference: `~` expands, one
+  trailing newline is trimmed, the file is read only at dispatch, and a
+  missing or empty file is a config error naming the engine and path but
+  never the value. Setting both `apiKey` and `apiKeyFile` is rejected;
+  setting neither still falls through to the implicit
+  `AKM_ENGINE_<NAME>_API_KEY` convention. The value is redacted from
+  dispatch output the same way an env-backed credential is, and `akm health`
+  checks the file is present and non-empty.
+
+### Changed
+
+- **`akm improve`'s machine-local writers moved out of `$STASH/.akm` into
+  `$STATE` and `$CACHE` (#890).** `distill-rejected/`, `eval-cases/`,
+  `measurement/verdicts/`, the synthetic `unresolved-sources/` placeholder,
+  and the improve-pipeline lock files never met the "must travel with the
+  content" rule; they now live under `$STATE/improve/…/<stash>/`,
+  `$CACHE/index/unresolved-sources/<stash>/`, and `$STATE/locks/<stash>/`,
+  namespaced by a short hash of the resolved stash path. `akm migrate
+  status` and `apply` gain a relocation step that covers the default stash
+  and every other filesystem-backed bundle (remote sources are skipped
+  without a network call), moves files by rename or copy-then-delete, and
+  deletes an old lock only when the same staleness check `akm improve` uses
+  says its holder is dead; a live lock is left in place and reported. The
+  step is idempotent and `--dry-run` moves nothing. Scripts that read the
+  old paths should switch to the new locations named in
+  `docs/architecture/internals/storage-locations.md`.
+
+### Fixed
+
+- **The dead-link check states its coverage and no longer lies about it
+  (#892).** `akm improve`'s post-loop check scanned at most ten knowledge
+  refs and fired every HEAD request at once with no timeout. It now scans
+  every actionable ref, checks at a bounded concurrency, bounds each request
+  at five seconds and reports a timeout as a dead entry, and counts a DNS or
+  connection failure as skipped rather than as dead or as fine. The result
+  carries `checked`, `total`, and `skipped`, threaded into the improve
+  result, the `improve_completed` event, and `akm health`'s improve summary.
+  The other constants the issue names (`MAX_URLS`, the per-entry slice,
+  `MAX_BODY_CHARS`, the duplicated `MAX_CONTENT_CHARS`) were already removed
+  in 0.9.8, and the curate score floors only decide whether a second search
+  pass runs; they never filter returned results.
+
+## [0.9.10] - 2026-09-02
+
+### Fixed
+
+- **`akm task history <id>` now filters to that task instead of silently
+  ignoring the positional id (#911).** `task run <id>` and `task explain <ref>`
+  take the id positionally, so `task history <id>` was the natural thing to
+  write, and it answered with every task's newest rows while exiting 0. A
+  positional id now means the same as `--id`; passing both with different
+  values is a usage error (exit 2) rather than a silent pick.
+
 ## [0.9.9] - 2026-09-02
 
 ### Changed

package/STABILITY.md

@@ -112,6 +112,7 @@ enumeration of the whole `proposal` noun group.
 | `akm task sync` | Evolving | |
 | `akm task doctor` | Evolving | |
 | `akm task explain` | Evolving | New in 0.9.2; secret-shaped values in provenance output are redacted on a best-effort heuristic basis (not a guarantee). |
+| `akm task validate` | Evolving | New in 0.9.11; read-only, and the only `task` subcommand that takes a bare filesystem path instead of a ref — the file need not belong to any configured bundle. |
 
 ## Stable
 
@@ -256,21 +257,28 @@ CHANGELOG with a migration note.
   `akm improve && akm proposal drain --promote --yes`, or a `triage` block
   with `applyMode: "promote"` in your strategy.
 - **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
-  history | explain`; no alias, no `list`/`remove`/`init`/`enable`/`disable`);
-  task source v4 YAML (typed `inputs:`, optional `schedule:`) is the only
-  accepted version — task v3 and task v2 sources are converted by
-  `akm migrate apply`. Command tasks use named engines and task history
-  metadata is versioned. Schema additions in patch releases; removals only at
-  minor. Bare `akm task` is a usage error naming the subcommands
-  (`akm task doctor` reports scheduler diagnostics). `akm task explain <ref>`
-  (new in 0.9.2) and `akm workflow plan <ref>` are both zero-write
-  provenance surfaces: they show what a task or workflow would do —
-  resolved target, input bindings, child expansion — without starting or
-  publishing a run. `akm workflow plan` is secret-free **by construction**
-  (the excluded data never reaches the command). `akm task explain`
-  instead **redacts** secret-shaped input values on a best-effort
+  history | explain | validate`; no alias, no
+  `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
+  `inputs:`, optional `schedule:`) is the only accepted version — task v3 and
+  task v2 sources are converted by `akm migrate apply`. Command tasks use
+  named engines and task history metadata is versioned. Schema additions in
+  patch releases; removals only at minor. Bare `akm task` is a usage error
+  naming the subcommands (`akm task doctor` reports scheduler diagnostics).
+  `akm task explain <ref>` (new in 0.9.2) and `akm workflow plan <ref>` are
+  both zero-write provenance surfaces: they show what a task or workflow
+  would do — resolved target, input bindings, child expansion — without
+  starting or publishing a run. `akm workflow plan` is secret-free **by
+  construction** (the excluded data never reaches the command). `akm task
+  explain` instead **redacts** secret-shaped input values on a best-effort
   heuristic basis — a value that doesn't match the heuristic can still
-  print unredacted.
+  print unredacted. `akm task validate <path>` (new in 0.9.11) is the same
+  kind of zero-write introspection as `explain`, but takes a bare filesystem
+  path rather than a bundle-qualified ref — it reports whether that ONE file
+  would parse cleanly (`valid`), auto-convert from task v2/v3 (`converts`),
+  need a human decision the deterministic migrator can't make (`blocked`),
+  fail schema validation (`invalid`), or isn't a task source at all
+  (`not-a-task`) — exactly the diagnostic `akm task sync` would produce for
+  it, before the file is ever wired into a bundle or the scheduler.
 - **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
   compile+freeze introspection (the canonical step graph, task/child
   expansion, input bindings, and lowering notices for a workflow, without

package/dist/commands/health/checks.js

@@ -6,13 +6,20 @@ import { loadConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
 import { listPendingStateMigrations } from "../../core/state-db.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
-import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
+import { lookupApiKeyFileValue, resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { executionEngineDefinitionsFromConfig } from "../../integrations/agent/execution-definitions.js";
 import { loadModelMap, mergeModelMapLayers, parseModelMapLayer, readInstalledModelMapText, resolveModelMapAlias, userModelMapPath, } from "../../integrations/agent/model-map.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
 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()));
+function credentialAvailable(credential, env, apiKeyFile) {
+    if (credential?.required)
+        return credential.names.some((name) => Boolean(env[name]?.trim()));
+    // #905: an engine with no env descriptor may still require a file-backed
+    // credential — probe it too, rather than reporting an unreadable/empty
+    // apiKeyFile as available just because it carries no env var names.
+    if (apiKeyFile !== undefined)
+        return lookupApiKeyFileValue(apiKeyFile) !== undefined;
+    return true;
 }
 function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     if (!engineName) {
@@ -57,6 +64,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
         const fallbackEngine = configuredEngine.llmEngine ?? config.defaults?.llmEngine;
         let fallback;
         let fallbackCredential;
+        let fallbackApiKeyFile;
         let sdkRunner;
         const resolve = deps.resolveEngine ?? resolveEngine;
         try {
@@ -70,6 +78,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
         if (sdkRunner?.fallbackConnection && fallbackEngine) {
             fallback = { kind: "llm", engine: fallbackEngine, connection: sdkRunner.fallbackConnection };
             fallbackCredential = sdkRunner.fallbackCredential;
+            fallbackApiKeyFile = sdkRunner.fallbackApiKeyFile;
         }
         else if (fallbackEngine) {
             try {
@@ -77,6 +86,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
                 if (resolved.kind === "llm") {
                     fallback = resolved;
                     fallbackCredential = resolved.credential;
+                    fallbackApiKeyFile = resolved.apiKeyFile;
                 }
             }
             catch {
@@ -85,7 +95,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
         }
         const configuredModel = configuredEngine.model;
         const effectiveModel = sdkRunner?.profile.model ?? configuredModel ?? fallback?.connection.model;
-        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env);
+        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env, fallbackApiKeyFile);
         const missing = [
             !packageAvailable ? "@opencode-ai/sdk package" : undefined,
             !binaryAvailable ? `${binary} binary` : undefined,
@@ -121,7 +131,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     try {
         const runner = (deps.resolveEngine ?? resolveEngine)(engineName, config);
         if (runner.kind === "llm") {
-            const requiredCredentialAvailable = credentialAvailable(runner.credential, env);
+            const requiredCredentialAvailable = credentialAvailable(runner.credential, env, runner.apiKeyFile);
             return {
                 name: checkName,
                 kind: "deterministic",
@@ -287,7 +297,7 @@ export function runActiveImproveStrategyProbe(deps = {}) {
         const unavailableProcesses = Object.entries(plan.processes).flatMap(([name, process]) => {
             if (!process.enabled || !process.runner)
                 return [];
-            return credentialAvailable(process.runner.credential, env) ? [] : [name];
+            return credentialAvailable(process.runner.credential, env, process.runner.apiKeyFile) ? [] : [name];
         });
         if (plan.triageJudgment) {
             const judgmentCredential = plan.triageJudgment.kind === "llm"
@@ -295,8 +305,14 @@ export function runActiveImproveStrategyProbe(deps = {}) {
                 : plan.triageJudgment.kind === "sdk"
                     ? plan.triageJudgment.fallbackCredential
                     : undefined;
-            if (!credentialAvailable(judgmentCredential, env))
+            const judgmentApiKeyFile = plan.triageJudgment.kind === "llm"
+                ? plan.triageJudgment.apiKeyFile
+                : plan.triageJudgment.kind === "sdk"
+                    ? plan.triageJudgment.fallbackApiKeyFile
+                    : undefined;
+            if (!credentialAvailable(judgmentCredential, env, judgmentApiKeyFile)) {
                 unavailableProcesses.push("triage.judgment");
+            }
         }
         return {
             name: "active-improve-strategy",

package/dist/commands/health/improve-metrics.js

@@ -76,6 +76,9 @@ function createUnknownImproveMetrics() {
         coverageGapCount: 0,
         evalCasesWritten: 0,
         deadUrlCount: 0,
+        deadUrlsChecked: 0,
+        deadUrlsTotal: 0,
+        deadUrlsSkipped: 0,
         memorySummary: { eligible: 0, derived: 0 },
         memoryCleanup: {
             pruneCandidates: 0,
@@ -333,6 +336,12 @@ function applyMiscCounters(metrics, result) {
     metrics.evalCasesWritten += toFiniteNumber(result.evalCasesWritten);
     if (Array.isArray(result.deadUrls))
         metrics.deadUrlCount += result.deadUrls.length;
+    const deadUrlCoverage = result.deadUrlCoverage;
+    if (deadUrlCoverage && typeof deadUrlCoverage === "object") {
+        metrics.deadUrlsChecked += toFiniteNumber(deadUrlCoverage.checked);
+        metrics.deadUrlsTotal += toFiniteNumber(deadUrlCoverage.total);
+        metrics.deadUrlsSkipped += toFiniteNumber(deadUrlCoverage.skipped);
+    }
 }
 function applyMemorySummary(metrics, result) {
     const memorySummary = result.memorySummary;
@@ -568,6 +577,9 @@ function mergeImproveMetrics(dst, src) {
     dst.coverageGapCount += src.coverageGapCount;
     dst.evalCasesWritten += src.evalCasesWritten;
     dst.deadUrlCount += src.deadUrlCount;
+    dst.deadUrlsChecked += src.deadUrlsChecked;
+    dst.deadUrlsTotal += src.deadUrlsTotal;
+    dst.deadUrlsSkipped += src.deadUrlsSkipped;
     // NOTE: memorySummary (derived/eligible) is a WHOLE-STASH snapshot recorded on
     // every run, NOT a per-run increment — summing it across the window inflates
     // it ~N× (the 1.2M-eligible bug). It is set from the most recent run in

package/dist/commands/improve/distill/quality-gate.js

@@ -15,6 +15,7 @@ import { timestampForFilename } from "../../../core/common.js";
 import { ConfigError } from "../../../core/errors.js";
 import { appendEvent } from "../../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
+import { getDistillRejectedDir } from "../../../core/paths.js";
 import { withStateDb } from "../../../core/state-db.js";
 import { recordWrittenPath } from "../../../core/write-provenance.js";
 import { callStructured } from "../../../llm/structured-call.js";
@@ -242,8 +243,9 @@ export async function runReflectQualityJudge(config, candidateContent, sourceCon
 }
 // ── Quality-rejection helper ─────────────────────────────────────────────────
 /**
- * Write a rejected lesson to `.akm/distill-rejected/`, append a `distill_invoked`
- * quality-rejected event, and return the `quality_rejected` envelope.
+ * Write a rejected lesson to `$STATE/improve/distill-rejected/<stash>/`
+ * (itlackey/akm#890), append a `distill_invoked` quality-rejected event, and
+ * return the `quality_rejected` envelope.
  *
  * @param stash     - Root stash directory.
  * @param inputRef  - The original input ref (for the event).
@@ -257,13 +259,19 @@ export async function runReflectQualityJudge(config, candidateContent, sourceCon
 export function writeQualityRejection(stash, inputRef, proposalRef, content, score, reason, extraMeta = {}, eligibilitySource, eventsCtx) {
     // D-5 / #388: reviewNeeded flag selects "review_needed" vs "quality_rejected" outcome.
     const outcome = extraMeta.reviewNeeded ? "review_needed" : "quality_rejected";
-    const rejectDir = path.join(stash, ".akm", "distill-rejected");
+    const rejectDir = getDistillRejectedDir(stash);
     fs.mkdirSync(rejectDir, { recursive: true });
     const ts = timestampForFilename();
     const rejectPath = path.join(rejectDir, `${ts}-${proposalRef.replace(/[:/\\]/g, "-")}.md`);
     fs.writeFileSync(rejectPath, `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
-    // #652: the rejection envelope lands under the managed `.akm/` tree, which
-    // the pre-provenance sync swept up by pathspec — journal it explicitly.
+    // #652 / itlackey/akm#890: journal it even though it now lands under
+    // `$STATE`, outside the stash's git repo — `result.writtenPaths` reports
+    // every path a run touched, in or out of the stash (describeRunWrittenPaths
+    // in improve.ts falls back to the absolute path for anything outside the
+    // stash root), and the auto-sync commit's own containment check
+    // (resolveSyncPathSet's `relativeWrittenPath`) already drops anything
+    // outside `repoDir` from what gets staged — recording it here cannot cause
+    // it to be committed.
     recordWrittenPath(rejectPath);
     appendEvent({
         eventType: "distill_invoked",

package/dist/commands/improve/eval-cases.js

@@ -4,9 +4,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../../core/common.js";
+import { getEvalCasesDir } from "../../core/paths.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
 export function writeEvalCase(stashDir, evalCase) {
-    const evalDir = path.join(stashDir, ".akm", "eval-cases");
+    const evalDir = getEvalCasesDir(stashDir);
     fs.mkdirSync(evalDir, { recursive: true });
     const fileName = `${evalCase.slug}.md`;
     const filePath = path.join(evalDir, fileName);
@@ -29,11 +30,17 @@ Use it as a regression test: future improve runs on this ref should not produce
 output that would be rejected for the same reason.
 `;
     writeFileAtomic(filePath, content);
+    // itlackey/akm#890: journal it even though it now lands under `$STATE`,
+    // outside the stash's git repo — `result.writtenPaths` still reports it
+    // (as an absolute path; see describeRunWrittenPaths in improve.ts), and
+    // the auto-sync commit's own containment check already excludes anything
+    // outside the stash from what gets staged, so recording it here cannot
+    // cause it to be committed.
     recordWrittenPath(filePath);
     return filePath;
 }
 export function countEvalCases(stashDir) {
-    const evalDir = path.join(stashDir, ".akm", "eval-cases");
+    const evalDir = getEvalCasesDir(stashDir);
     if (!fs.existsSync(evalDir))
         return 0;
     try {

package/dist/commands/improve/improve.js

@@ -11,7 +11,7 @@ import { ConfigError, rethrowIfTestIsolationError, UsageError } from "../../core
 import { appendEvent, readEvents } from "../../core/events.js";
 import { classifyImproveAction, foldDistillSkipped } from "../../core/improve-types.js";
 import { resolveMutationTarget } from "../../core/mutation-target.js";
-import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
+import { getDbPath, getStashLocksDir, getStateDbPathInDataDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { info, warn, warnVerbose } from "../../core/warn.js";
@@ -481,8 +481,11 @@ function resolveImproveRunSetup(options) {
     // calling test's own at this point; we capture it before yielding the loop.
     const resolvedStateDbPath = getStateDbPathInDataDir();
     // One conservative run lock protects the complete mutation window, including
-    // triage, indexing, proposal work, maintenance, and final stash sync.
-    const lockBaseDir = primaryStashDir ? path.join(primaryStashDir, ".akm") : path.join(options.stashDir ?? ".", ".akm");
+    // triage, indexing, proposal work, maintenance, and final stash sync. Moved
+    // out of `$STASH/.akm` to `$STATE/locks/<stash>/` (itlackey/akm#890): a lock
+    // file is machine-local coordination state, not content that must travel
+    // with the bundle.
+    const lockBaseDir = getStashLocksDir(primaryStashDir ?? options.stashDir ?? ".");
     const resolvedLockPath = improveLockPath(lockBaseDir);
     const effectiveSync = { ...improveProfile.sync, ...options.sync };
     return {
@@ -1146,6 +1149,7 @@ async function runImproveStageSequence(args) {
     // Concatenated arrays.
     const allWarnings = [];
     let deadUrls;
+    let deadUrlCoverage;
     const finalActions = [];
     {
         const runPreparation = () => runImprovePreparationStageImpl({
@@ -1228,6 +1232,9 @@ async function runImproveStageSequence(args) {
         if (postLoopResult.deadUrls !== undefined) {
             deadUrls = [...(deadUrls ?? []), ...postLoopResult.deadUrls];
         }
+        if (postLoopResult.deadUrlCoverage !== undefined) {
+            deadUrlCoverage = postLoopResult.deadUrlCoverage;
+        }
         const maintenanceActions = postLoopResult.maintenanceActions;
         if (maintenanceActions && maintenanceActions.length > 0) {
             finalActions.push(...preparation.actions, ...maintenanceActions);
@@ -1250,6 +1257,7 @@ async function runImproveStageSequence(args) {
         proposalsExpired,
         allWarnings,
         deadUrls,
+        deadUrlCoverage,
         finalActions,
     };
 }
@@ -1261,7 +1269,7 @@ async function runImproveStageSequence(args) {
 function finalizeImproveResult(args) {
     const { guidance, memorySummary, memoryCleanupPlan, strategyFilteredRefs, rawPlannedRefs, indexSnapshot, triageDrain, eventsCtx, } = args;
     const { selectedStrategy, scope, options, primaryStashDir, startMs } = args.run;
-    const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, finalActions, } = args.seq;
+    const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, deadUrlCoverage, finalActions, } = args.seq;
     // C1 (13-bus-factor): fold the per-ref `distill-skipped` rows (~13k/run,
     // ~91% of result_json bytes) into a bounded aggregate BEFORE persistence.
     // The metric total + per-reason breakdown are preserved on `distillSkipped`;
@@ -1326,6 +1334,10 @@ function finalizeImproveResult(args) {
         ...(preparation.extract && preparation.extract.length > 0 ? { extract: preparation.extract } : {}),
         ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
         ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
+        // Present whenever the check ran, unlike `deadUrls` above — a clean run
+        // (zero dead links) still needs to tell the health report how much of
+        // the bundle it actually covered (#892).
+        ...(deadUrlCoverage !== undefined ? { deadUrlCoverage } : {}),
         ...(reflectsWithErrorContext > 0 ? { reflectsWithErrorContext } : {}),
         ...(memoryInference ? { memoryInference } : {}),
         ...(graphExtraction ? { graphExtraction } : {}),
@@ -1501,6 +1513,9 @@ function emitImproveCompletedEvent(result, durations, eventsCtx) {
             coverageGapCount: result.coverageGaps?.length ?? 0,
             evalCasesWritten: result.evalCasesWritten ?? 0,
             deadUrlCount: result.deadUrls?.length ?? 0,
+            deadUrlsChecked: result.deadUrlCoverage?.checked ?? 0,
+            deadUrlsTotal: result.deadUrlCoverage?.total ?? 0,
+            deadUrlsSkipped: result.deadUrlCoverage?.skipped ?? 0,
             memoryEligible: result.memorySummary.eligible,
             memoryDerived: result.memorySummary.derived,
             memoryCleanupPruneCandidates: result.memoryCleanup?.pruneCandidates.length ?? 0,

package/dist/commands/improve/loop-stages.js

@@ -569,8 +569,16 @@ export async function runImprovePostLoopStage(args) {
         resolvedPlan,
     });
     let deadUrls;
+    let deadUrlCoverage;
     if (scope.mode === "all" && primaryStashDir && actionableRefs.length > 0) {
         try {
+            // Every actionable knowledge ref is scanned for URLs — there used to be
+            // a `.slice(0, 10)` here, capping the scan to the first ten refs while
+            // `deadUrlCoverage.total` counted only those, so a real bundle reported
+            // checked === total while most refs were never looked at (#892). URL
+            // extraction (a regex over already-loaded text) is cheap; it is the
+            // network requests that are expensive, and those are bounded by
+            // `checkDeadUrls`'s concurrency limit, not by trimming what gets scanned.
             const knowledgeEntries = actionableRefs
                 .filter((r) => {
                 try {
@@ -580,7 +588,6 @@ export async function runImprovePostLoopStage(args) {
                     return false;
                 }
             })
-                .slice(0, 10)
                 .map((r) => {
                 // The URL scan needs the document body; filePath is pre-resolved on
                 // eligible refs at planning time (#591). Best-effort — an unreadable
@@ -598,8 +605,10 @@ export async function runImprovePostLoopStage(args) {
             });
             if (knowledgeEntries.length > 0) {
                 info(`[improve] checking URLs in ${knowledgeEntries.length} knowledge refs`);
-                deadUrls = await checkDeadUrls(primaryStashDir, knowledgeEntries);
-                info(`[improve] URL check complete (${deadUrls.length} dead/timeout URLs)`);
+                const urlCheck = await checkDeadUrls(primaryStashDir, knowledgeEntries);
+                deadUrls = urlCheck.deadUrls;
+                deadUrlCoverage = urlCheck.coverage;
+                info(`[improve] URL check complete (${deadUrls.length} dead/timeout URLs; checked ${urlCheck.coverage.checked} of ${urlCheck.coverage.total})`);
             }
         }
         catch {
@@ -625,6 +634,7 @@ export async function runImprovePostLoopStage(args) {
     return {
         allWarnings,
         deadUrls,
+        ...(deadUrlCoverage ? { deadUrlCoverage } : {}),
         ...(cycleMetrics ? { cycleMetrics } : {}),
         ...(maintenanceResult.memoryInference ? { memoryInference: maintenanceResult.memoryInference } : {}),
         ...(maintenanceResult.graphExtraction ? { graphExtraction: maintenanceResult.graphExtraction } : {}),

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

@@ -32,6 +32,7 @@ import { UsageError } from "../../core/errors.js";
 import { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS } from "../../tasks/task-run-reserved-flags.js";
 import { akmTaskExplain } from "./explain.js";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksPrune, akmTasksRun, akmTasksSync, akmTasksSyncPlan, } from "./tasks.js";
+import { akmTaskValidate } from "./validate.js";
 /** Shared `--bundle <bundle>` arg wired onto every task subcommand. */
 const bundleArg = {
     bundle: {
@@ -289,9 +290,23 @@ const tasksRunCommand = defineCommand({
         });
     },
 });
+/**
+ * #911: `task run <id>` and `task explain <ref>` take the id positionally, so
+ * `task history <id>` is the natural thing to write — and it used to be
+ * accepted and silently discarded, answering with every task's newest rows.
+ * A positional id now means the same as `--id`; giving both with different
+ * values is a usage error rather than a silent pick.
+ */
+export function resolveTaskHistoryId(positional, flag) {
+    if (positional !== undefined && flag !== undefined && positional !== flag) {
+        throw new UsageError(`\`akm task history\` was given two task ids: "${positional}" and --id "${flag}". Pass one.`, "INVALID_FLAG_VALUE");
+    }
+    return flag ?? positional;
+}
 const tasksHistoryCommand = defineJsonCommand({
     meta: { name: "history", description: "Show recent task run history" },
     args: {
+        task: { type: "positional", description: "Task id to filter to (same as --id)", required: false },
         id: { type: "string", description: "Filter to one task id" },
         limit: { type: "string", description: "Maximum rows to return (default 50)" },
         ...bundleArg,
@@ -299,7 +314,8 @@ const tasksHistoryCommand = defineJsonCommand({
     async run({ args }) {
         rejectRetiredTaskTargetFlag();
         const limit = parsePositiveIntFlag(args.limit ?? undefined);
-        const result = await akmTasksHistory({ id: args.id, limit, target: args.bundle });
+        const id = resolveTaskHistoryId(args.task, args.id);
+        const result = await akmTasksHistory({ id, limit, target: args.bundle });
         output("task-history", result);
     },
 });
@@ -399,6 +415,36 @@ const tasksDoctorCommand = defineJsonCommand({
         output("task-doctor", result);
     },
 });
+/**
+ * #907: `akm task validate`'s exit-code contract — `valid`/`converts` are
+ * successful outcomes (exit 0); `blocked`/`invalid`/`not-a-task` are
+ * diagnosed defects the caller must act on (exit 1, mirroring `task sync`'s
+ * own `failures.length > 0 -> EXIT_CODES.GENERAL`). A missing path or an
+ * unreadable file never reaches this function at all — `akmTaskValidate`
+ * throws a `UsageError` for those, which `defineJsonCommand`'s wrapping
+ * already maps to exit 2.
+ */
+export function taskValidateExitCode(result) {
+    return result.outcome === "valid" || result.outcome === "converts" ? undefined : EXIT_CODES.GENERAL;
+}
+const tasksValidateCommand = defineJsonCommand({
+    meta: {
+        name: "validate",
+        description: "Parse a single task file by filesystem path — not a concept ref, and the file need not live in a " +
+            "configured bundle — and report the same diagnostic `akm task sync` would produce for it. Read-only; " +
+            "never touches the scheduler.",
+    },
+    args: {
+        path: { type: "positional", description: "Filesystem path to a task source YAML file", required: true },
+    },
+    async run({ args }) {
+        const result = await akmTaskValidate(args.path);
+        output("task-validate", result);
+        const exitCode = taskValidateExitCode(result);
+        if (exitCode !== undefined)
+            process.exitCode = exitCode;
+    },
+});
 /**
  * #851: `akm task prune`'s exit-code contract mirrors `task sync --dry-run`'s
  * (`taskSyncDryRunExitCode` above) — non-zero whenever the preview lists
@@ -451,6 +497,7 @@ export const taskCommand = defineGroupCommand({
         add: tasksAddCommand,
         run: tasksRunCommand,
         explain: tasksExplainCommand,
+        validate: tasksValidateCommand,
         history: tasksHistoryCommand,
         sync: tasksSyncCommand,
         prune: tasksPruneCommand,