akm-cli 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -4,6 +4,166 @@ 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.5] - 2026-08-30
+
+### Action required after upgrading
+
+- **Run `akm index --full` once (#862).** Search ranking previously counted
+  every search *hit* as a small win for that entry's utility score, whether
+  or not you ever opened it — a plain impression, not a selection. Over
+  enough repeat searches this compounded into a real feedback loop: appear
+  in results -> score goes up -> rank higher next time -> appear again. On
+  the install this was diagnosed against, one entry had been searched 19
+  times, opened 0 times, and still carried a utility score of 0.83 — on par
+  with entries a user had actually picked every time; the single
+  highest-utility entry in the whole table had an 8% select rate. That bias
+  is baked into every existing install's stored scores and does not go away
+  on its own — the live bump has been removed (search impressions no longer
+  write utility scores at all; only an actual `akm show`/select or explicit
+  `akm feedback` feeds the offline recompute now), but the already-inflated
+  numbers stay in `utility_scores`/`utility_scores_scoped` until you
+  recompute them. Run `akm index --full` once after upgrading to rebuild
+  scores purely from selection rate and feedback. **Search result order will
+  change after that rebuild — that is intended**, not a regression.
+- **The first `akm task sync` after upgrading may report a large number of
+  updates.** This is a backlog of reconciles that were being silently
+  refused, not new changes to your tasks. Two independent bugs combined to
+  make `sync` refuse work it should have done: (1) an installed scheduler
+  entry written by a pre-`--bundle` akm release couldn't prove ownership
+  under the newer, stricter check and was reported `(unproven owner)`,
+  which made `sync` refuse the *entire* run rather than reconcile everything
+  else; (2) separately, one task or workflow source that failed to compile
+  (e.g. a task still on schema v2 in a shape the shim can't convert) also
+  blocked every other, unrelated task from reconciling. Both are fixed —
+  ownership is now re-derived from the entry's own akm markers instead of
+  requiring a literal `--bundle` token, and a source that fails to compile
+  is now excluded and reported in `failed`/`failures` while every source
+  that DID compile still reconciles. On the install this was diagnosed
+  against, all 18 scheduled tasks showed up as updates on the first `sync`
+  after the fix — that is the backlog, not a sign your tasks changed.
+
+### Added
+
+- **`akm task prune` reclaims orphaned scheduler entries `sync` cannot reach
+  (#851).** `akm task sync` only ever reconciles entries that resolve to a
+  desired task/workflow definition in a live bundle; an entry whose own
+  `--scheduler-context` descriptor is corrupt/missing, or whose owning
+  bundle directory has since been deleted, was permanently invisible to it
+  and had to be removed by hand-editing the crontab/launchd plist/Task
+  Scheduler. `akm task prune` finds those and nothing else: it never
+  touches an entry that still resolves to a live bundle, and there is no
+  `--force`/"remove everything silently" mode. Defaults to a dry-run
+  preview that makes zero scheduler writes and exits non-zero when it finds
+  removal candidates (usable as a CI/health-check guard, mirroring `task
+  sync --dry-run`'s exit-code convention); `--yes` executes the printed
+  plan; `--id a,b` narrows a run to specific binding ids and refuses (with
+  no writes) any id that isn't a current orphan candidate — including a
+  live entry, which cannot be pruned even if you name it explicitly.
+- **`configVersion` read shim (#863).** Config loading now tolerates a
+  known older `configVersion` by upgrading the parsed document in memory
+  (never rewriting the file), with a one-line stderr warning naming the old
+  and new versions. The upgrade is silenced the next time any command
+  writes the config (`akm config set`, etc.), since every config write
+  already stamps the current version. Anything else — unknown, newer, or
+  malformed `configVersion` — still fails closed with the same actionable
+  error as before. No current release needed this shim yet (akm has only
+  ever shipped `configVersion: "0.9.0"`); it's in place now so the next
+  real bump doesn't break every existing config on upgrade.
+- **Truncated indexed content is no longer silent.** The two indexer caps
+  that truncate an entry's content before it's written to the search index
+  (a markdown-body cap and a search-text cap) previously truncated without
+  any signal. Indexed entries now carry a `contentTruncated: true` flag
+  when either cap fired, and truncation logs a `--verbose` diagnostic
+  naming the entry, so an unexpectedly-worse search match on a very large
+  file has a visible cause instead of a silent one. The cap sizes
+  themselves are unchanged.
+
+### Fixed
+
+- **`akm health --report` and `akm proposal list --status accepted` no
+  longer crash, and `improve`'s accepted-proposal counts are no longer
+  silently zero, on proposals written before every optional envelope field
+  existed (#859).** A prior fix already tolerated a missing `changes` key;
+  this closes the same gap for `proposedTarget`, which was still hard-required
+  at decode and — on the real archive this was checked against — absent
+  from 93% of accepted rows. Decoding a proposal now tolerates a genuinely
+  *absent* `proposedTarget` (accept-time resolution already had a
+  ref-derived fallback for this case, previously unreachable because decode
+  threw first); a *present but malformed* value still throws, so real
+  corruption is never silently accepted. Writing a new (`pending`) proposal
+  still requires the full envelope — this only widens what can be *read*,
+  not what akm will *write*.
+- **`akm task sync` no longer refuses to reconcile an entry it can't fully
+  re-prove ownership of, and no longer lets one broken task/workflow source
+  block every other source (#867, plus the scheduler-ownership fix
+  described above).** The v2 task-source shim also no longer hard-fails a
+  command wrapped in `env NAME=value... cmd`, a shape that's common for
+  cron entries (e.g. `env AKM_BIN=/path/akm bash script.sh`) — the shim now
+  looks past a leading `env` and its assignments to the real command before
+  deciding whether the conversion to v3/v4 is safe, instead of checking
+  `env` itself.
+- **`akm task sync --dry-run` no longer crashes on a real install with a
+  pre-`--bundle` cron entry.** The reconcile fix above made those entries
+  reachable for the first time, and the dry-run preview's frozen result
+  object was then mutated in place while stamping output metadata, throwing
+  "Attempting to define property on object that is not extensible" (exit
+  70). Output stamping now copies instead of mutating, so it tolerates a
+  frozen (or any) result uniformly.
+- **`akm migrate apply` no longer aborts an entire batch because one file in
+  it is blocked (#866).** The task v2->v3 and v3->v4 migrators refused to
+  write *any* file — including files with no problem at all — the moment a
+  single file in the batch was classified `blocked`. Both migrators now
+  skip and report the blocked file(s) and still migrate everything else;
+  the run still exits non-zero whenever anything was skipped.
+- Two flaky integration/unit tests fixed at the root cause rather than
+  quarantined (#864): a `state.db` byte-identity assertion that raced
+  SQLite's own WAL checkpoint timing (now forces a checkpoint before
+  comparing, so the assertion reflects real durable mutations only), and a
+  "resolveProjectContext when cwd is the home directory" test that did
+  real, un-mocked filesystem walks against the actual `$HOME` (now isolates
+  `os.homedir()` and the stash/XDG dirs like the rest of the suite).
+
+### Changed
+
+- **`test:integration` is green-by-default (#861).** Verified there is no
+  CI mechanism silently swallowing a failing test (no `continue-on-error`,
+  no lost exit codes, no allowlist of "expected" failures) — the fixes in
+  this release were the actual cause of the prior red baseline. Raised the
+  integration suite's minimum-test-count floor (`AKM_MIN_INTEGRATION_TESTS`,
+  5500 -> 5700) so a large silent test loss is still caught with headroom
+  for ordinary future deletions, and documented in `AGENTS.md` that `TMPDIR`
+  must be a real `/tmp`-family path for the suite to pass — some guards
+  (stash-path safety, `akm-eval`'s Docker twin) intentionally hardcode that
+  assumption rather than reading `TMPDIR`.
+- Simplified several areas flagged in the #866 complexity review without
+  behavior changes: `improve_runs.result_json`'s `schemaVersion` decoding is
+  now an explicit, extensible table instead of one large inline
+  conditional, ready for a future schema bump to add a case rather than
+  restructure the function.
+
+### Removed
+
+- **Three defensive checks that only ever refused work a human explicitly
+  asked for, with no evidence (via telemetry) they ever caught a real
+  problem, were removed:**
+  - The 1 MiB hard cap on reading a bundle file (command/agent/script/task/
+    workflow source, or a frozen workflow secret/env source) into memory.
+    Reads remain exact and integrity-checked (hashed, CAS-verified, fail-
+    closed on read-time mutation) — there is simply no longer a size ceiling
+    that refuses to read a file you put in your own bundle.
+  - The task migrator's inode/hard-link-count/change-time identity
+    fencing on top of its existing lockfile + backup-before-write +
+    byte-for-byte drift check. The extra fencing modeled a multi-tenant
+    race that doesn't apply to a single-user CLI holding an exclusive lock,
+    and its failure mode (refusing to migrate a file that's byte-identical
+    to what was already previewed, or refusing to touch a file merely
+    because it has a hard link elsewhere) was worse than the risk it
+    guarded against. Symlink/path-escape rejection — a real hazard — is
+    unchanged.
+  - Dead anti-collapse "hard refusal" guard functions
+    (`checkGenerationGuard`, `checkMergeInformationFloor`) that had zero
+    production callers.
+
 ## [0.9.4] - 2026-08-30
 
 ### Changed

package/dist/commands/improve/anti-collapse.js

@@ -4,11 +4,11 @@
 /**
  * WS-3b Step 8 — Anti-collapse merge guards.
  *
- *   (a) Generation counter: merged.generation = max(sources)+1; refuse merge
- *       of two assets both above generation N (default 2); merges cite sources.
+ *   (a) Generation counter: merged.generation = max(sources)+1; merges cite
+ *       sources. `over_generation_count` (collapse-detector.ts) tracks assets
+ *       above the generation threshold as an advisory metric only — there is
+ *       no merge-refusal path wired in.
  *   (b) Lexical-diversity check: low n-gram diversity ⇒ raise merge threshold.
- *   (c) Merge-information floor (R5 §4.2): provenance union must not shrink and
- *       the merged body must retain a minimum fraction of the source tokens.
  *   (d) Occasional random non-similar cluster in the pool.
  *
  * @module anti-collapse
@@ -37,93 +37,6 @@ export function computeMergedGeneration(sourceGenerations) {
         return 1;
     return Math.max(...sourceGenerations) + 1;
 }
-/**
- * Check whether a merge of the given assets should be refused due to the
- * anti-collapse generation guard.
- *
- * Returns `{ refused: true, reason }` when BOTH assets have generation > maxGeneration.
- * Returns `{ refused: false }` when the merge is allowed.
- *
- * @param sourceGenerations - Generation values for all merge participants.
- * @param config - Anti-collapse config.
- */
-export function checkGenerationGuard(sourceGenerations, config) {
-    // R5: default ON — only an explicit opt-out disables the guard.
-    if (config.enabled === false)
-        return { refused: false };
-    const maxGen = config.maxGeneration ?? DEFAULT_MAX_GENERATION;
-    const highGenCount = sourceGenerations.filter((g) => g > maxGen).length;
-    if (highGenCount >= 2) {
-        return {
-            refused: true,
-            reason: `Anti-collapse: ${highGenCount} merge participants have generation > ${maxGen} (${sourceGenerations.join(", ")}); refusing to merge over-consolidated assets.`,
-        };
-    }
-    return { refused: false };
-}
-/** Distinct-token retention floor default (R5 §4.2). */
-export const DEFAULT_MIN_SPECIFICITY_RETENTION = 0.6;
-function distinctTokens(text) {
-    // Same lowercase whitespace tokenization computeBigramDiversity uses.
-    return new Set(text
-        .toLowerCase()
-        .split(/\s+/)
-        .filter((w) => w.length > 0));
-}
-/**
- * A merge must strictly increase information (R5 §4.2):
- *  1. Provenance: the merged asset's `xrefs` must be a superset of the union of
- *     all participants' `xrefs` plus the participant refs
- *     themselves — provenance never shrinks through a merge.
- *  2. Specificity: distinctTokens(mergedBody) ≥ minSpecificityRetention ×
- *     |union(distinctTokens(participant bodies))| — a merge that only
- *     shortens/genericizes fails.
- *
- * Pure and deterministic; ADVISORY in v1 (the caller counts violations, it
- * does not refuse the merge). Returns `passed: true` immediately when the
- * anti-collapse suite or the floor itself is opted out.
- */
-export function checkMergeInformationFloor(mergedBody, mergedSourceRefs, participants, config) {
-    if (config.enabled === false || config.mergeInformationFloor === false || participants.length === 0) {
-        return { passed: true, provenanceBefore: 0, provenanceAfter: 0, specificityRetention: 1 };
-    }
-    // 1. Provenance union: participants + everything they already cited.
-    const required = new Set();
-    for (const p of participants) {
-        required.add(p.ref);
-        for (const xref of p.xrefs)
-            required.add(xref);
-    }
-    const after = new Set(mergedSourceRefs);
-    const missing = [...required].filter((r) => !after.has(r));
-    // 2. Specificity retention over the union of source tokens.
-    const sourceTokens = new Set();
-    for (const p of participants) {
-        for (const t of distinctTokens(p.body))
-            sourceTokens.add(t);
-    }
-    const mergedTokens = distinctTokens(mergedBody);
-    // Clamped at computation so the pass/fail decision, the reason string, and
-    // the reported field all describe the same value.
-    const specificityRetention = Math.min(1, sourceTokens.size === 0 ? 1 : mergedTokens.size / sourceTokens.size);
-    const minRetention = config.minSpecificityRetention ?? DEFAULT_MIN_SPECIFICITY_RETENTION;
-    const provenanceOk = missing.length === 0;
-    const specificityOk = specificityRetention >= minRetention;
-    const reasons = [];
-    if (!provenanceOk) {
-        reasons.push(`provenance shrank: merged xrefs missing ${missing.length} ref(s) (e.g. ${missing[0]})`);
-    }
-    if (!specificityOk) {
-        reasons.push(`specificity retention ${specificityRetention.toFixed(2)} < ${minRetention} (merge genericized/shortened)`);
-    }
-    return {
-        passed: provenanceOk && specificityOk,
-        provenanceBefore: required.size,
-        provenanceAfter: after.size,
-        specificityRetention,
-        ...(reasons.length > 0 ? { reason: reasons.join("; ") } : {}),
-    };
-}
 /**
  * Compute the bigram n-gram diversity of a text string.
  * Returns a value in [0, 1] where 0 = all identical bigrams, 1 = all unique.

package/dist/commands/proposal/validators/proposal-validators.js

@@ -67,6 +67,18 @@ const canonicalProposalValidators = {
         const content = proposalContent(proposal);
         if (!content.trim())
             return [];
+        // #859: proposedTarget is absent on legacy archived rows, but this
+        // validator only ever runs on a proposal about to be minted or promoted
+        // (both always carry proposedTarget — see the Proposal.proposedTarget
+        // doc comment) — so hitting this is a genuine defect, not a legacy gap.
+        if (!proposal.proposedTarget) {
+            return [
+                {
+                    kind: "invalid-workflow-structure",
+                    message: `Workflow proposal ${proposal.id} (${proposal.ref}) is missing proposedTarget and cannot be validated.`,
+                },
+            ];
+        }
         const sourcePath = proposal.changes[0]?.path || proposal.ref;
         const result = compileWorkflowSource(content, {
             path: sourcePath,

package/dist/commands/read/search.js

@@ -14,13 +14,10 @@
 import { getSources, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { isTransientStashPath } from "../../core/paths.js";
 import { resolveReadSources } from "../../indexer/read-preflight.js";
 import { searchLocal } from "../../indexer/search/db-search.js";
 import { getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
 import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
-import { bumpUtilityScoresBatch } from "../../storage/repositories/index-utility-repository.js";
-import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
 import "../../sources/providers/index.js";
@@ -188,7 +185,7 @@ function usageSearchMode(mode) {
 function maybeLogSearchEvent(input, query, response, mode) {
     if (input.skipLogging)
         return;
-    logSearchEvent(query, response, mode, input.eventSource, input.disableScopedUtility === true, input.attributionProjection);
+    logSearchEvent(query, response, mode, input.eventSource, input.attributionProjection);
 }
 /**
  * Resolve entry IDs by file_path lookup (exact match, not LIKE).
@@ -229,7 +226,7 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, mode = "keyword", eventSource = "user", disableScopedUtility = false, attributionProjection = "full") {
+function logSearchEvent(query, response, mode = "keyword", eventSource = "user", attributionProjection = "full") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
@@ -276,25 +273,18 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
                     source: eventSource,
                 });
             }, TELEMETRY_BUSY_TIMEOUT_MS);
-            // Bump utility scores for all resolved entries (MemRL retrieval signal).
-            // The indexer overwrites these at next reindex; bumps are temporary hints.
-            // Gated to user-sourced events: pipeline searches (improve probes, task
-            // runner) must not feed the utility signal (meta-review 05 DRIFT-6 —
-            // the bump previously fired unconditionally, so even correctly-tagged
-            // machine traffic inflated utility). utility_scores stays in index.db.
-            const resolvedIds = eventSource === "user" ? resolved.map((r) => r.entryId).filter((id) => id !== undefined) : [];
-            if (resolvedIds.length > 0) {
-                let scopeKey;
-                try {
-                    const stashPath = response.bundleDir;
-                    const disabled = disableScopedUtility || (stashPath && isTransientStashPath(stashPath));
-                    scopeKey = disabled ? undefined : getCurrentWorkflowScopeKey();
-                }
-                catch {
-                    // Non-fatal — fall back to global-only bumps on any error.
-                }
-                bumpUtilityScoresBatch(db, resolvedIds, 1.0, 0.1, scopeKey);
-            }
+            // No live utility_scores/utility_scores_scoped write here (#862): a
+            // search result is an impression, not a signal that the asset was
+            // useful. Rewarding every returned hit created a feedback loop where
+            // merely appearing in results inflated future ranking — assets
+            // surfaced because they'd surfaced before, not because a user acted
+            // on them. Retrieval counts are still recorded above via
+            // insertUsageEvent (search_count) and rolled into utility_scores by
+            // the offline `recomputeUtilityScores` pass (`akm index`), which uses
+            // the show/search *select rate* — a ratio that requires an actual
+            // `show`/select event, not raw impressions. Explicit signal comes
+            // from `akm feedback` (applyFeedbackToUtilityScore) and from
+            // selection (recordShowUsage / the `select` event derived from it).
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {

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

@@ -31,7 +31,7 @@ import { defineGroupCommand, defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS,
 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, akmTasksRun, akmTasksSync, akmTasksSyncPlan } from "./tasks.js";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksPrune, akmTasksRun, akmTasksSync, akmTasksSyncPlan, } from "./tasks.js";
 /** Shared `--bundle <bundle>` arg wired onto every task subcommand. */
 const bundleArg = {
     bundle: {
@@ -307,10 +307,13 @@ const tasksHistoryCommand = defineJsonCommand({
  * #849: `task sync --dry-run`'s exit-code contract, "non-zero when the plan
  * contains removals" — factored out as a pure function (rather than left
  * inline in the command's `run()`) so it's directly unit-testable without
- * driving the whole CLI through a real scheduler backend.
+ * driving the whole CLI through a real scheduler backend. #867: also
+ * non-zero when any source failed to parse/prepare — sync degrades (still
+ * reconciles the tasks/workflows that DID parse) rather than rejecting the
+ * whole set, but a dropped source must still surface as a failing exit.
  */
 export function taskSyncDryRunExitCode(preview) {
-    return preview.hasRemovals ? EXIT_CODES.GENERAL : undefined;
+    return preview.hasRemovals || (preview.failures?.length ?? 0) > 0 ? EXIT_CODES.GENERAL : undefined;
 }
 const tasksSyncCommand = defineJsonCommand({
     meta: {
@@ -345,6 +348,12 @@ const tasksSyncCommand = defineJsonCommand({
         }
         const result = await akmTasksSync({}, args.bundle, { rebind });
         output("task-sync", result);
+        // #867: sync degrades — sources that failed to parse/prepare are
+        // excluded from reconciliation and reported in `result.failed` rather
+        // than poisoning the whole sync, but their presence must still fail
+        // the command's exit code so the breakage stays visible.
+        if (result.failed.length > 0)
+            process.exitCode = EXIT_CODES.GENERAL;
     },
 });
 // ── `akm task explain` — read-only introspection (P2b Lane B, spec
@@ -389,6 +398,49 @@ const tasksDoctorCommand = defineJsonCommand({
         output("task-doctor", result);
     },
 });
+/**
+ * #851: `akm task prune`'s exit-code contract mirrors `task sync --dry-run`'s
+ * (`taskSyncDryRunExitCode` above) — non-zero whenever the preview lists
+ * removals the invocation didn't (or couldn't, without `--yes`) execute, so
+ * `akm task prune` is usable as a CI/health check the same way `sync
+ * --dry-run` is.
+ */
+export function taskPruneExitCode(result) {
+    return result.dryRun && result.preview.hasRemovals ? EXIT_CODES.GENERAL : undefined;
+}
+const tasksPruneCommand = defineJsonCommand({
+    meta: {
+        name: "prune",
+        description: "Remove installed scheduler entries `sync` can never reclaim because their own descriptor no longer " +
+            "resolves to a live bundle (corrupt/missing --scheduler-context, or the owning bundle directory is " +
+            "gone). Defaults to a dry-run preview — zero scheduler writes. Requires --yes to remove anything; " +
+            "--id narrows removal to specific binding ids (comma-separated).",
+    },
+    args: {
+        yes: {
+            type: "boolean",
+            description: "Execute removal of every currently-computed orphan (the plan is still printed first)",
+            default: false,
+        },
+        id: {
+            type: "string",
+            description: "Comma-separated scheduler binding id(s) to limit pruning to (must already be orphan candidates)",
+        },
+    },
+    async run({ args }) {
+        const id = args.id
+            ? args.id
+                .split(",")
+                .map((value) => value.trim())
+                .filter(Boolean)
+            : undefined;
+        const result = await akmTasksPrune({}, { yes: args.yes === true, id });
+        output("task-prune", result);
+        const exitCode = taskPruneExitCode(result);
+        if (exitCode !== undefined)
+            process.exitCode = exitCode;
+    },
+});
 export const taskCommand = defineGroupCommand({
     meta: {
         name: "task",
@@ -400,6 +452,7 @@ export const taskCommand = defineGroupCommand({
         explain: tasksExplainCommand,
         history: tasksHistoryCommand,
         sync: tasksSyncCommand,
+        prune: tasksPruneCommand,
         doctor: tasksDoctorCommand,
     },
     // Bare `akm task` reports scheduler diagnostics. Inspection of individual

package/dist/commands/tasks/tasks.js

@@ -35,8 +35,8 @@ import { exitCodeForStatus } from "../../tasks/run/task-result.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
 import { assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "../../tasks/scheduler-binding.js";
 import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
-import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
-import { renderSchedulerSyncPlanPreview } from "../../tasks/scheduler-sync-preview.js";
+import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, buildSchedulerRemoveOperation, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
+import { renderSchedulerPlanPreview, renderSchedulerSyncPlanPreview, } from "../../tasks/scheduler-sync-preview.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
 import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
 import { TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
@@ -417,6 +417,7 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
         unchanged: [...plan.unchanged],
         skipped: [],
         backend: sched.name,
+        failed: plan.failures.map((failure) => ({ ...failure })),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -434,6 +435,92 @@ export async function akmTasksSyncPlan(deps = {}, bundleTarget, options = {}) {
     const { sched, plan } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
     return renderSchedulerSyncPlanPreview(sched.name, plan);
 }
+/**
+ * Classify one installed scheduler binding as a prune candidate (#851), using
+ * the same two signals `doctor`'s `inspectInstalledBinding` already computes
+ * — deliberately narrower than that function's full `status` set. Only an
+ * entry whose ownership can NEVER be resolved (`invalid-context`) or whose
+ * resolved owner no longer exists on disk (`dead-bundle-path`) is a
+ * candidate; `missing-path` (e.g. the akm binary itself moved) is a
+ * different failure mode and is intentionally NOT folded in here, per the
+ * scoping in #851 — an entry that still resolves to a live bundle is never a
+ * candidate, full stop.
+ */
+function classifyPruneCandidate(entry) {
+    let ownerBundlePath;
+    try {
+        ownerBundlePath = validateSchedulerContextDescriptor(entry.contextPath).environment.AKM_BUNDLE_DIR;
+    }
+    catch {
+        return "invalid-context";
+    }
+    if (ownerBundlePath !== undefined && !fs.existsSync(ownerBundlePath))
+        return "dead-bundle-path";
+    return undefined;
+}
+async function buildTaskPrunePlan(deps = {}, options = {}) {
+    const sched = deps.backend ?? selectBackend();
+    if (!sched.inspectBindings) {
+        throw new ConfigError(`Scheduler backend "${sched.name}" cannot provide one coherent inspection for prune.`, "INVALID_CONFIG_FILE");
+    }
+    const inspection = await sched.inspectBindings({});
+    const candidates = new Map();
+    for (const entry of inspection.installed) {
+        const reason = classifyPruneCandidate(entry);
+        if (reason)
+            candidates.set(entry.id, reason);
+    }
+    const requestedIds = options.id?.filter((id) => id.length > 0) ?? [];
+    for (const id of requestedIds) {
+        if (!candidates.has(id)) {
+            throw new UsageError(`Scheduler binding ${JSON.stringify(id)} is not an orphaned prune candidate ` +
+                "(either not installed, or it still resolves to a live bundle) — refusing to prune it.", "INVALID_FLAG_VALUE");
+        }
+    }
+    const idFilter = requestedIds.length > 0 ? new Set(requestedIds) : undefined;
+    const resolved = resolveTaskReadBundle(undefined, undefined);
+    const bundleContext = {
+        adapterId: resolved.source.adapterId ?? detectAdapterId(resolved.source.path),
+        bundleName: resolved.source.name,
+    };
+    const operations = [];
+    for (const entry of inspection.installed) {
+        const reason = candidates.get(entry.id);
+        if (!reason)
+            continue;
+        if (idFilter && !idFilter.has(entry.id))
+            continue;
+        const operation = buildSchedulerRemoveOperation(entry.id, entry, inspection.artifacts, bundleContext);
+        operations.push(Object.freeze({ ...operation, reason }));
+    }
+    return { sched, operations: Object.freeze(operations) };
+}
+/**
+ * `akm task prune` (#851): remove installed scheduler bindings `sync` can
+ * never reclaim because their own `--scheduler-context` descriptor doesn't
+ * resolve to a live bundle. Defaults to dry-run — no `--yes` and no `--id`
+ * means zero backend calls that could mutate anything, matching
+ * `akmTasksSyncPlan`'s zero-write guarantee. `--id` (one or more) narrows
+ * execution to exactly those bindings; `--yes` alone executes every
+ * currently-computed candidate. Both still return the full preview so the
+ * plan is never silent about what it did.
+ */
+export async function akmTasksPrune(deps = {}, options = {}) {
+    const { sched, operations } = await buildTaskPrunePlan(deps, options);
+    const preview = renderSchedulerPlanPreview(sched.name, operations);
+    if (!options.yes) {
+        return { backend: sched.name, dryRun: true, preview, removed: [] };
+    }
+    await applySchedulerTransaction(sched, operations, {
+        initialExpectations: operations.map((operation) => operation.expected),
+    });
+    return {
+        backend: sched.name,
+        dryRun: false,
+        preview,
+        removed: operations.map((operation) => operation.id),
+    };
+}
 export async function akmTasksDoctor(deps = {}) {
     const warnings = [];
     let invocation = {

package/dist/core/adapter/adapters/akm-adapter.js

@@ -223,6 +223,8 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.tags = entry.tags;
     if (entry.content !== undefined)
         doc.content = entry.content;
+    if (entry.contentTruncated !== undefined)
+        doc.contentTruncated = entry.contentTruncated;
     if (entry.aliases !== undefined)
         doc.aliases = entry.aliases;
     if (entry.searchHints !== undefined)