akm-cli 0.9.2-alpha.3 → 0.9.2-alpha.4

package/CHANGELOG.md

@@ -6,6 +6,207 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2-alpha.4] - 2026-08-26
+
+### Added
+
+- **`akm health`: flag assets whose resolved type disagrees with their
+  directory** (#837). Adds a `type-directory-disagreement` advisory that
+  compares every indexed asset's resolved type against the type its
+  `DIR_TYPE_MAP` directory declares (`memories/`, `knowledge/`, `commands/`,
+  `agents/`, `workflows/`, `facts/`, `lessons/`, `sessions/`,
+  `instructions/`, `scripts/`, `env/`, `secrets/`, `tasks/`). This is the
+  diagnostic that would have caught #824 (three `memories/` files silently
+  indexed as commands) the day it was introduced. Since `knowledge/` +
+  `$ARGUMENTS` and `agents/` + `agent:` frontmatter are deliberate command
+  overrides, the check never hard-fails: every disagreement is reported as a
+  warning naming the winning classifier signal, with a `knownGoodOverride`
+  flag so a sanctioned override reads differently from an unexplained one.
+- **`akm health`: report the Claude harness plugin's version and warn when
+  it's stale or out of range** (#838). Adds a `plugin-version` advisory that
+  reports each installed Claude Code `akm` plugin's version, warns when a
+  newer tag is published upstream (naming the update command), and warns
+  when the plugin's own declared `AKM_VERSION_RANGE` no longer admits the
+  running CLI — meaning the plugin has silently disabled itself. Makes an
+  outbound `git ls-remote` when network is available to check for a newer
+  tag; per owner decision, this is read-only and degrades to a benign pass
+  (no plugin, no marketplace clone, unreadable manifest, malformed range, or
+  a failed remote lookup) rather than crashing or blocking offline use.
+
+### Changed
+
+- **Extract: LLM prompt is now built from parent-origin events only —
+  "harvest-without-prompting hybrid" (#840).** #830 folds a session's
+  subagent transcripts into its event stream for hashing and inline-ref
+  harvesting; the prompt sent to the extraction LLM previously included that
+  folded subagent content too, competing with the parent's own transcript
+  for the 80,000-char pre-filter budget. #840's design-determination doc
+  (`docs/plans/subagent-extraction-design.md`) measured that this "fold"
+  approach evicts up to 28.6% of parent-origin content on real sessions to
+  make room for subagent noise that mostly gets evicted anyway, while a
+  "harvest-without-prompting hybrid" — keep folding for hashing/inline-ref
+  purposes, but filter the prompt down to `data.events` whose `filePath`
+  matches the session's own (`data.ref.filePath`) — matches or beats the
+  folded prompt's size with zero eviction on every session measured, and
+  recovers the exact same inline refs (`akm remember`/`akm feedback` calls
+  the agent made inside a subagent), because that harvesting already runs on
+  the raw stream independent of what reaches the prompt. Only
+  `runPreLlmSessionGates`'s call into `preFilterSession` changed; folding
+  (`session-log.ts`) and `buildExtractPrompt` are untouched.
+  - **No forced re-extraction wave.** `hashSessionContent` still hashes the
+    full folded `data` (parent + subagents), computed before the
+    parent-origin view is built — no previously-computed session hash
+    changes, so no session already extracted under the fold prompt shape is
+    automatically re-processed. Use `--force` to re-process a specific
+    session under the new, parent-only prompt shape.
+  - **`processes.extract.maxTotalChars` is unchanged in meaning and default**
+    — it still caps the single-call prompt built from parent-origin events;
+    it simply no longer has to compete against subagent-origin noise for
+    that budget.
+  - **`minContentChars`** (the raw-size skip gate, #595/#596) is still
+    measured on the FULL folded `data.events` (parent + subagents),
+    deliberately left unchanged: narrowing it to parent-origin chars would
+    newly skip delegation-heavy sessions with a thin parent transcript
+    before extraction runs at all, even though their subagent-origin work is
+    still fully harvested via inline refs. The full-stream measurement is
+    today's existing behavior; the worst case it preserves is an LLM call
+    over a small parent-only prompt, not a missed extraction.
+  - #839's task-notification dedupe (which stubs a parent's
+    `<task-notification>` only when the matching subagent's own event ALSO
+    survives into the same kept prompt set) composes safely with this
+    change without modification: subagent-origin events never reach
+    `preFilterSession` on this path, so the dedupe's own scoping check
+    naturally makes it a no-op — the parent's notification (the only
+    remaining trace of delegated work in the prompt) survives untouched.
+
+### Fixed
+
+- **`akm remember` synthesizes a description when the caller doesn't supply
+  one** (#835). Both the zero-flag hot path and the structured-args path
+  (e.g. `--tag`-only, with no `--description`/`--enrich`) previously wrote
+  memories with no `description:` and no `tags:`. akm's indexer covers only
+  synthesized frontmatter/headings, never body prose, so those memories were
+  retrievable only by whatever words survived into the auto-generated
+  filename — effectively write-only. Verified on a real stash: 272/3169
+  memories lacked a description, 100% of those written via `akm remember`.
+  The new `synthesizeMemoryDescription` (ported from akm-eval's
+  `firstSentencesCapped` rule, which independently arrived at the same fix)
+  is deterministic and makes no LLM call: it accumulates whole sentences
+  from the body up to `DESCRIPTION_MAX_CHARS`, skipping a leading markdown
+  heading so the description doesn't just repeat the title. Wired into both
+  write paths as a fallback only — a caller-supplied `--description` (or one
+  derived by `--enrich`) is never overwritten. Closes the write-only-memories
+  gap on 0.9.1 indexes.
+- **Extract: deduped the doubled subagent conclusion in the extraction prompt**
+  (#839). After #830 folded a session's subagent transcripts into its event
+  stream, a completed subagent's final report could appear twice in the same
+  extraction prompt: once as the subagent's own folded final message, once as
+  the parent's `<task-notification>` record of that same call (#836 measured
+  ~92-99% textual overlap on a real pair; reproduced here as a byte-identical
+  match after decoding the XML entities Claude Code escapes into `<result>`).
+  The parent's notification copy is now stubbed to `[subagent <agentId>
+  completed: <description>]` when its `<result>` is a near-duplicate
+  (Dice-bigram similarity ≥ 0.9) of a folded subagent transcript's own text;
+  the subagent's original is untouched, per #839's owner-decided direction
+  (the inverse — dropping the subagent's own terminal event — was evaluated
+  and rejected in #836 because some subagent transcripts consist only of
+  that one event). Matching is scoped by `<task-id>` to the one subagent
+  transcript it names and still requires content similarity, so an earlier
+  notification for a *resumed* agent (Claude Code re-notifies the same
+  task-id on each stop) that carries a genuinely different, intermediate
+  result is left alone.
+  **Scoped to the final, post-budget kept set — not the raw stream** (#840's
+  design-determination doc flagged this as a hazard while this PR was in
+  flight): the dedupe only fires when the subagent's own event ALSO survives
+  into the same kept set as the notification. #840 measured that today's
+  recency-biased 80k budget already evicts one side of nearly every raw
+  duplicate pair before dedupe would matter (0 of 89 raw pairs across four
+  real sessions had both sides survive); an unconditional raw-stream stub
+  would, under that same eviction pattern, sometimes delete a parent's
+  notification whose subagent copy never made the cut in the first place —
+  and would unconditionally delete the *only* surviving trace of delegated
+  work under #840's recommended future design (prompting from parent-origin
+  events only). Verified against the real session #836 and #839 both cite
+  (`4a0d9e9b…`): under the actual 80,000-char budget, 0 notifications are
+  stubbed today (consistent with #840's finding) because the cited pair's
+  subagent copy doesn't survive the budget; with the budget cap lifted,
+  1 of 10 raw duplicate pairs in that session both survive AND still exceed
+  the 0.9 similarity bar after the pre-filter's independent per-event
+  2000-char truncation (the other 9 exceed that per-event cap and truncate
+  down far enough to fall below the bar — a conservative miss, never a wrong
+  stub). The fix is real and correct for sessions/pairs small enough to avoid
+  both eviction and truncation, and is structurally inert wherever it would
+  be unsafe to fire.
+  Implemented in the pre-filter (`preFilterSession`), which runs AFTER
+  `hashSessionContent` — so **no `contentHash` moves and no re-extraction
+  wave is triggered** (unlike #830's own folding change, which changed the
+  raw event stream #602's hash covers).
+- **Extract: regression-tested the no-double-extraction guarantee** (#839).
+  Discovery-mode extraction over a project with a parent + subagent
+  transcripts now has an explicit end-to-end test proving exactly one
+  session is processed, that `--session-id agent-<hash>` resolves to the
+  not-found result rather than an extraction, and that folded subagent
+  content is attributed only to the parent's session/contentHash. Pins
+  behavior already true since #830 (`listSessions()` excludes `subagents/`
+  dirs for both discovery and `--session-id` lookup); nothing tested it
+  end-to-end before.
+
+### Documentation
+
+- **Measured whether subagent-transcript folding (#830) duplicates the
+  parent's own summary, and disclosed the one-time re-extraction cost
+  (#833).** Using the actual reader/pre-filter/prompt-builder code against 3
+  real sessions on this machine — no LLM calls; `contentHash`,
+  `preFilterSession`, and `buildExtractPrompt` are deterministic:
+  - Raw event counts grow 2x-12x once subagent transcripts are folded in
+    (measured: 1209 -> 14224; 1583 -> 6738, the exact session cited in
+    #829/#833's "1583 -> 6738" figure; 155 -> 2408). `contentHash` is
+    computed over that stream, so every previously-extracted session's hash
+    changes and the next `--since` run re-extracts all of them once, each
+    with a larger prompt (+1.2% to +5.2% prompt chars across the 3 sessions,
+    since the 80,000-char pre-filter budget caps how much of the growth
+    actually reaches the LLM).
+  - The result is a genuine tradeoff, not a clean win or loss. **Benefit:**
+    inline `akm remember`/`akm feedback` calls made *by subagents* are
+    recovered regardless of the budget cap (inline-ref extraction runs on
+    the raw event stream, not the pre-filtered one) — up to 162 refs
+    recovered on the largest session measured (was 2 without folding),
+    fixing #829's "delegated work is never harvested" defect. **Cost:** on
+    sessions whose raw content is near or under the pre-filter's character
+    budget, folding evicts a large share of the parent's own kept content to
+    make room for subagent tool-call trace — parent-origin kept events
+    dropped 27% and 71% respectively on the two smaller sessions measured.
+    On the largest session the budget was already saturated by the parent's
+    own tail, so folding changed nothing there. Duplication is real, not
+    hypothetical: on the smallest session, one subagent's conclusion appears
+    twice in the same prompt sent to the extraction LLM — once via its own
+    folded final message, once via the parent's own record of that
+    delegated call's result, which independently already captured ~92% of
+    the same text verbatim.
+  - A narrowing that drops a subagent transcript's terminal event (its
+    apparent "final report") to avoid this specific duplication was
+    considered and rejected: the existing #830 regression fixture has a
+    subagent transcript whose *only* event is that terminal turn (a single
+    delegated `akm remember` call) — the same rule would drop the only
+    content in short single-step delegations, undoing the harvesting #830
+    added.
+  - **Decision: keep folding as shipped.** The data does not cleanly favor
+    removing or narrowing it, and the one narrowing considered would cost
+    more than it fixes. #829's phantom-session exclusion is unaffected
+    either way.
+- Recorded the fold-vs-link subagent-extraction design determination in
+  `docs/plans/subagent-extraction-design.md` (#840). Measured four candidates
+  (fold+dedupe as shipped, link-only, a harvest-without-prompting hybrid, and
+  chunked map-reduce extraction) on the same real sessions #836 used plus one
+  added for scale. Headline: the hybrid recovers 100% of #830's inline-ref
+  harvesting (162/162, 38/38, 1/1, 8/8 across the four sessions) with zero
+  parent-content eviction (vs 27.5%/28.6% evicted under fold on two of the
+  four), and #839's dedupe was measured to have zero effect on the actual
+  LLM prompt on all four sessions (the flagged duplicate content is already
+  evicted by the recency-biased budget before dedupe would matter). Chunked
+  extraction was measured at 9x-229x more LLM calls per session on real
+  data and is not recommended. No behavior changes shipped in this PR.
+
 ## [0.9.2-alpha.3] - 2026-08-26
 
 ### Fixed

package/dist/commands/health/plugin-staleness.js

@@ -0,0 +1,219 @@
+// 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/.
+/**
+ * `plugin-version` advisory for `akm health` (itlackey/akm#832).
+ *
+ * #828 was filed as a CLI bug — session extraction failing on 232/234 runs —
+ * and took a full investigation to resolve. The actual cause: the harness
+ * plugin (`akm@akm-plugins`, installed in Claude Code's plugin cache) was
+ * three days stale relative to the fix, and its own `AKM_VERSION_RANGE` gate
+ * had nothing to do with it — the plugin was simply running old code. Every
+ * fact needed to reach that conclusion in one step was already on disk:
+ *
+ *   - installed plugin version: `~/.claude/plugins/cache/<marketplace>/akm/<version>/.claude-plugin/plugin.json`
+ *   - the plugin's own akm-cli compatibility contract: `<pluginDir>/shared/akm-version.ts`'s `AKM_VERSION_RANGE`
+ *   - the running CLI's version: `../../version.ts`'s `pkgVersion`
+ *
+ * Nothing correlated them, so a stale plugin was indistinguishable from a
+ * broken CLI. This module closes that gap with three checks, one per
+ * detected plugin:
+ *
+ *   1. report the installed version;
+ *   2. compare it against the newest tag published to the plugin's git
+ *      remote, and warn (naming the update command) when behind;
+ *   3. the sharp one — check whether the *installed plugin's* declared
+ *      `AKM_VERSION_RANGE` admits the *running* CLI version. When it does
+ *      not, the plugin has silently disabled itself (both surfaces log
+ *      `version_out_of_range` / `akm_version_mismatch` and degrade quietly)
+ *      and there was previously no way to know that from the CLI side.
+ *
+ * Read-only: this never fetches, writes, or mutates the plugin cache or
+ * marketplace clone. Check 2 is the one deliberate exception to "`akm
+ * health` makes no network call" (see `./health-advisories.md`): a plugin's
+ * local marketplace clone is not proof of what is newest upstream — the
+ * incident above involved a clone that hadn't seen the fix's tag at all — so
+ * the only way to ever detect drift is to ask the remote what tags exist.
+ * That query is a `git ls-remote --tags` (lists refs; fetches nothing,
+ * writes nothing) with a short timeout, and any failure (offline, no
+ * remote, timeout) degrades to "installed version reported, no staleness
+ * claim" rather than a false positive or a hang.
+ *
+ * Every collector here is best-effort and silent on missing/unreadable
+ * input: no Claude plugin installed, no marketplace clone, an unreadable
+ * manifest, or a malformed version range must never crash `akm health` and
+ * must never produce a false "stale" or "inactive" warning.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isExactSemver, isSemverRange, maxSatisfying, satisfiesRange } from "../../registry/semver.js";
+/**
+ * Root directory holding Claude Code's plugin cache + marketplace clones.
+ * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
+ * after import — the override exists so tests point this at an empty
+ * fixture directory instead of the real `~/.claude/plugins`, matching
+ * `AKM_CLAUDE_PROJECTS_DIR` in `../../integrations/harnesses/claude/session-log.ts`.
+ */
+function claudePluginsDir() {
+    return process.env.AKM_CLAUDE_PLUGINS_DIR ?? path.join(os.homedir(), ".claude", "plugins");
+}
+/**
+ * Scan `<pluginsRoot>/cache/<marketplace>/akm/<version>/` for every
+ * `akm` plugin cache entry, picking the highest cached version per
+ * marketplace when more than one is present. Returns `[]` (never throws)
+ * when the cache directory is absent, empty, or unreadable — that is the
+ * ordinary "no Claude plugin installed" case, not an error.
+ */
+function detectInstalledPlugins(pluginsRoot) {
+    const cacheDir = path.join(pluginsRoot, "cache");
+    let marketplaces;
+    try {
+        marketplaces = fs.readdirSync(cacheDir);
+    }
+    catch {
+        return [];
+    }
+    const detected = [];
+    for (const marketplace of marketplaces) {
+        const pluginDir = path.join(cacheDir, marketplace, "akm");
+        let versions;
+        try {
+            versions = fs.readdirSync(pluginDir).filter(isExactSemver);
+        }
+        catch {
+            continue;
+        }
+        if (versions.length === 0)
+            continue;
+        const latest = maxSatisfying(versions, "*") ?? versions.sort().at(-1);
+        if (!latest)
+            continue;
+        const versionDir = path.join(pluginDir, latest);
+        const manifestPath = path.join(versionDir, ".claude-plugin", "plugin.json");
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+            if (typeof manifest.version !== "string")
+                continue;
+            detected.push({
+                harness: "claude",
+                marketplace,
+                pluginName: "akm",
+                version: manifest.version,
+                pluginDir: versionDir,
+            });
+        }
+        catch {
+            // Unreadable/malformed manifest — skip this entry rather than crash.
+        }
+    }
+    return detected;
+}
+/**
+ * Extract `AKM_VERSION_RANGE` from the installed plugin's vendored
+ * `shared/akm-version.ts`. Returns `undefined` when the file is missing,
+ * unreadable, or does not contain the expected declaration — callers must
+ * treat that as "compatibility unknown", never as a mismatch.
+ */
+function readVersionRange(pluginDir) {
+    const versionFilePath = path.join(pluginDir, "shared", "akm-version.ts");
+    let text;
+    try {
+        text = fs.readFileSync(versionFilePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const match = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/);
+    return match?.[1];
+}
+const LS_REMOTE_TIMEOUT_MS = 5_000;
+/**
+ * `git ls-remote --tags origin` against the marketplace clone's configured
+ * remote — lists refs only, fetches no objects, writes no local refs.
+ * Returns `undefined` (never throws) when the directory is not a git
+ * checkout, has no `origin` remote, or the command fails/times out (e.g.
+ * offline) — all "cannot determine availability", not "up to date".
+ */
+const realListRemoteTags = (marketplaceDir) => {
+    let result;
+    try {
+        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--tags", "origin"], {
+            encoding: "utf8",
+            timeout: LS_REMOTE_TIMEOUT_MS,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (result.status !== 0 || !result.stdout)
+        return undefined;
+    const tags = result.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.split("\t")[1])
+        .filter((ref) => typeof ref === "string" && ref.startsWith("refs/tags/"))
+        .map((ref) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, ""))
+        .map((tag) => tag.replace(/^v/, ""))
+        .filter(isExactSemver);
+    return [...new Set(tags)];
+};
+/**
+ * Build one `plugin-version` advisory per detected `akm` harness plugin.
+ * Returns `[]` when no plugin is installed — the benign, common case.
+ */
+export function collectPluginStalenessAdvisories(options) {
+    const pluginsRoot = options.pluginsRoot ?? claudePluginsDir();
+    const listRemoteTags = options.listRemoteTags ?? realListRemoteTags;
+    const plugins = detectInstalledPlugins(pluginsRoot);
+    return plugins.map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags));
+}
+function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags) {
+    const pluginRef = `${plugin.pluginName}@${plugin.marketplace}`;
+    // Point 2: newest available vs. installed, via the marketplace clone's remote.
+    const marketplaceDir = path.join(pluginsRoot, "marketplaces", plugin.marketplace);
+    let availableVersion;
+    try {
+        const tags = fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
+        availableVersion = tags && tags.length > 0 ? maxSatisfying(tags, "*") : undefined;
+    }
+    catch {
+        availableVersion = undefined;
+    }
+    const stale = availableVersion !== undefined &&
+        plugin.version !== availableVersion &&
+        maxSatisfying([plugin.version, availableVersion], "*") === availableVersion;
+    // Point 3: does the plugin's own declared range admit the running CLI?
+    const versionRange = readVersionRange(plugin.pluginDir);
+    const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);
+    const admitted = rangeKnown ? satisfiesRange(cliVersion, versionRange) : undefined;
+    const messageParts = [`${pluginRef}: installed ${plugin.version}`];
+    if (availableVersion !== undefined) {
+        messageParts.push(stale ? `available ${availableVersion} (STALE)` : `available ${availableVersion} (up to date)`);
+    }
+    if (stale)
+        messageParts.push(`-> claude plugin update ${pluginRef}`);
+    if (rangeKnown && admitted === false) {
+        messageParts.push(`installed plugin requires akm-cli ${versionRange}; running ${cliVersion} -> NOT ADMITTED (plugin is inactive)`);
+    }
+    return {
+        name: "plugin-version",
+        kind: "deterministic",
+        status: stale || admitted === false ? "warn" : "pass",
+        confidence: "high",
+        message: messageParts.join(" — "),
+        evidence: {
+            harness: plugin.harness,
+            marketplace: plugin.marketplace,
+            plugin: plugin.pluginName,
+            installedVersion: plugin.version,
+            availableVersion: availableVersion ?? null,
+            stale,
+            versionRange: versionRange ?? null,
+            cliVersion,
+            admitted: admitted ?? null,
+        },
+    };
+}

package/dist/commands/health/type-directory-check.js

@@ -0,0 +1,167 @@
+// 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/.
+/**
+ * `type-directory-disagreement` advisory for `akm health` (#831).
+ *
+ * The invariant "a file's directory declares its type" is load-bearing for
+ * refs, namespace listings, and `akm show` paths (see #824: three files
+ * written to `memories/` were indexed as `type: command`, moved their refs
+ * under `commands/memories/<slug>`, and silently vanished from the
+ * `memories/` namespace — nothing on any normal surface said so). This
+ * advisory re-checks that invariant against every currently indexed entry.
+ *
+ * Legitimate disagreements exist by design — a `knowledge/` file containing
+ * `$ARGUMENTS` is deliberately a `command`, and an `agents/` file with an
+ * `agent:` frontmatter key is deliberately a `command` (both asserted in
+ * `tests/integration/commands/show.test.ts`). So this is never a hard
+ * failure: every disagreement is reported with a `winner` naming which
+ * classifier signal produced the resolved type, so a deliberate override
+ * reads differently from an unexplained one.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+/**
+ * Directory → declared-type map, mirroring `DIR_TYPE_MAP` in
+ * `src/indexer/walk/matchers.ts` minus its per-directory extension test —
+ * this check only needs "which type does this directory declare", not which
+ * extensions it accepts. Keep in sync if `DIR_TYPE_MAP` gains, renames, or
+ * removes a directory.
+ */
+const DECLARED_DIR_TYPES = {
+    memories: "memory",
+    knowledge: "knowledge",
+    commands: "command",
+    agents: "agent",
+    workflows: "workflow",
+    facts: "fact",
+    lessons: "lesson",
+    sessions: "session",
+    instructions: "instruction",
+    scripts: "script",
+    env: "env",
+    secrets: "secret",
+    tasks: "task",
+};
+const realReadFile = (absPath) => {
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The type a file's directory declares, mirroring the `classifyByDirectory` /
+ * `classifyByParentDirHint` precedence in matchers.ts: the immediate parent
+ * directory wins when it is itself typed (parentDirHint, specificity 15);
+ * otherwise the outermost typed ancestor wins (directoryMatcher, specificity
+ * 10, which walks root-to-leaf and returns on the first hit).
+ */
+function declaredTypeForPath(absPath) {
+    const segments = path
+        .dirname(absPath)
+        .split(path.sep)
+        .filter((seg) => seg.length > 0);
+    const immediateParent = segments.at(-1);
+    if (immediateParent) {
+        const parentType = DECLARED_DIR_TYPES[immediateParent];
+        if (parentType)
+            return { dir: immediateParent, type: parentType };
+    }
+    for (const seg of segments) {
+        const type = DECLARED_DIR_TYPES[seg];
+        if (type)
+            return { dir: seg, type };
+    }
+    return undefined;
+}
+/**
+ * Best-effort explanation for why `classifyBySmartMd` (matchers.ts) would
+ * have produced `resolvedType` for this content, in the SAME precedence
+ * order the real function checks them. Returns `undefined` when no known
+ * override signal is found — that absence is itself the accident signal:
+ * nothing in the file explains why its type disagrees with its directory.
+ *
+ * The numeric-placeholder branch is flagged `knownGoodOverride: false` on
+ * purpose: since #826, that heuristic is guarded to never fire when the file
+ * sits under a declared-type directory, so seeing it win here would mean the
+ * guard regressed, not that this is a sanctioned override.
+ */
+function explainOverride(resolvedType, content) {
+    const fm = parseFrontmatter(content).data;
+    if (fm.type === "workflow" && resolvedType === "workflow") {
+        return { winner: "smart-md:workflow-frontmatter", knownGoodOverride: true };
+    }
+    if ("tools" in fm && resolvedType === "agent") {
+        return { winner: "smart-md:tools-frontmatter", knownGoodOverride: true };
+    }
+    if ("agent" in fm && resolvedType === "command") {
+        return { winner: "smart-md:agent-frontmatter", knownGoodOverride: true };
+    }
+    if (resolvedType === "command" && content.includes("$ARGUMENTS")) {
+        return { winner: "smart-md:$ARGUMENTS", knownGoodOverride: true };
+    }
+    if (resolvedType === "command" && /\$[123](?!\d|[.,]\d)/.test(content)) {
+        return { winner: "smart-md:numeric-placeholder", knownGoodOverride: false };
+    }
+    if ("model" in fm && resolvedType === "agent") {
+        return { winner: "smart-md:model-frontmatter", knownGoodOverride: true };
+    }
+    return undefined;
+}
+/**
+ * Compare every indexed entry's resolved type against the type its
+ * directory declares (see {@link DECLARED_DIR_TYPES}), and return one
+ * {@link TypeDirectoryDisagreement} per mismatch, sorted by path. Entries
+ * outside any declared-type directory are not checked — this is only the
+ * "directory declares type" invariant.
+ */
+export function collectTypeDirectoryDisagreements(entries, readFile = realReadFile) {
+    const disagreements = [];
+    for (const entry of entries) {
+        const declared = declaredTypeForPath(entry.filePath);
+        if (!declared || declared.type === entry.type)
+            continue;
+        const content = readFile(entry.filePath);
+        const explanation = content === undefined ? undefined : explainOverride(entry.type, content);
+        disagreements.push({
+            path: entry.filePath,
+            resolved: entry.type,
+            expected: declared.type,
+            winner: explanation?.winner ?? "unknown",
+            knownGoodOverride: explanation?.knownGoodOverride ?? false,
+        });
+    }
+    return disagreements.sort((a, b) => a.path.localeCompare(b.path));
+}
+const MAX_DETAIL_LINES = 10;
+/**
+ * Build the `type-directory-disagreement` advisory, or `undefined` when
+ * every indexed entry agrees with its directory. Always `status: "warn"`
+ * (never `"fail"`) — a deliberate override is still a disagreement worth
+ * seeing, just not a gate.
+ */
+export function buildTypeDirectoryAdvisory(entries, readFile = realReadFile, displayPath = (p) => p) {
+    const disagreements = collectTypeDirectoryDisagreements(entries, readFile);
+    if (disagreements.length === 0)
+        return undefined;
+    const lines = disagreements.slice(0, MAX_DETAIL_LINES).map((d) => {
+        const note = d.knownGoodOverride ? " (known-good override)" : "";
+        return `${displayPath(d.path)} resolved=${d.resolved} expected=${d.expected} winner=${d.winner}${note}`;
+    });
+    if (disagreements.length > MAX_DETAIL_LINES) {
+        lines.push(`+${disagreements.length - MAX_DETAIL_LINES} more`);
+    }
+    return {
+        name: "type-directory-disagreement",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "high",
+        message: `${disagreements.length} indexed asset(s) have a resolved type that disagrees with the type their directory declares: ${lines.join("; ")}`,
+        evidence: {
+            disagreements: disagreements.map((d) => ({ ...d, path: displayPath(d.path) })),
+        },
+    };
+}

package/dist/commands/health.js

@@ -15,15 +15,19 @@ import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
+import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
 import { queryTaskHistory } from "../storage/repositories/task-history-repository.js";
+import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS, runHealthEngineProbes } from "./health/checks.js";
 import { buildImproveSkipSummary, computeWallTimeStats, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
+import { collectPluginStalenessAdvisories } from "./health/plugin-staleness.js";
 import { collectStashExposureAdvisory } from "./health/stash-exposure.js";
 import { collectSurfacesAdvisories } from "./health/surfaces.js";
 import { buildPerRunSummaries } from "./health/task-runs.js";
+import { buildTypeDirectoryAdvisory } from "./health/type-directory-check.js";
 import { ACTIVE_RUN_WARN_MS, IMPROVE_COMPLETED_EVENT, MIN_ROWS_FOR_WORST_TASK_FAIL_RATE, } from "./health/types.js";
 import { buildWindowMetrics, computeDeltas, partitionLogBackedRows, resolveWindowCompare } from "./health/windows.js";
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
@@ -227,11 +231,12 @@ function gatherImproveSummaryPhase(db, stateDbPath, since, now) {
     return { improveSummary, perRunSummaries };
 }
 /**
- * The three best-effort advisory groups beyond the health-check registry:
- * improve advisories, the `stash-git-exposure` probe, and the 08 surfaces
- * group (binary-config-skew, egress-endpoints). Order matches emission order in
- * the returned array. A probe/filesystem failure in either try/catch must not
- * abort the health report — each group degrades to "no advisory" independently.
+ * The four best-effort advisory groups beyond the health-check registry:
+ * improve advisories, the `stash-git-exposure` probe, the 08 surfaces group
+ * (binary-config-skew, egress-endpoints), and `plugin-version` (itlackey/akm#832).
+ * Order matches emission order in the returned array. A probe/filesystem
+ * failure in any try/catch must not abort the health report — each group
+ * degrades to "no advisory" independently.
  */
 function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView) {
     const advisories = [...collectImproveAdvisories(db, stateDbPath, since, improveSummary)];
@@ -269,8 +274,61 @@ function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, optio
     catch {
         // Non-fatal.
     }
+    // #831: flag indexed assets whose resolved type disagrees with the type
+    // their containing directory declares (see health/type-directory-check.ts).
+    // Best-effort — an unreadable index must not abort the health report.
+    try {
+        const typeDirMismatch = detectTypeDirectoryDisagreements(options.stashDir ?? resolveStashDir());
+        if (typeDirMismatch)
+            advisories.push(typeDirMismatch);
+    }
+    catch {
+        // Non-fatal.
+    }
+    // itlackey/akm#832: report installed Claude Code harness plugin version(s)
+    // and warn when stale or when the plugin's own akm-cli version range no
+    // longer admits this CLI. Best-effort — no plugin installed, an unreadable
+    // manifest, or a network failure while checking the newest tag must not
+    // abort the health report.
+    try {
+        advisories.push(...collectPluginStalenessAdvisories({ cliVersion: pkgVersion }));
+    }
+    catch {
+        // Non-fatal.
+    }
     return advisories;
 }
+/**
+ * Open index.db read-only, project every entry to `{ filePath, type }`, and
+ * build the `type-directory-disagreement` advisory. `stashRoot` is used only
+ * to shorten displayed paths (relative to the stash) when it's an ancestor of
+ * the entry's path; falls back to the absolute path otherwise. Returns
+ * `undefined` when the index is absent/unreadable or nothing disagrees —
+ * mirrors {@link detectIndexStateGenerationMismatch}'s best-effort shape.
+ */
+function detectTypeDirectoryDisagreements(stashRoot) {
+    let indexDb;
+    try {
+        indexDb = openReadonlyExistingDatabase(getDbPath());
+        if (!indexDb)
+            return undefined;
+        const entries = getAllEntries(indexDb).map((entry) => ({ filePath: entry.filePath, type: entry.type }));
+        return buildTypeDirectoryAdvisory(entries, undefined, (absPath) => absPath.startsWith(stashRoot) ? path.relative(stashRoot, absPath) : absPath);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (indexDb) {
+            try {
+                closeDatabase(indexDb);
+            }
+            catch {
+                // Best-effort advisory: a close failure must not abort health.
+            }
+        }
+    }
+}
 /**
  * Detect the durable signature of an interrupted cross-database update.
  *

package/dist/commands/improve/extract.js

@@ -377,7 +377,20 @@ function runPreLlmSessionGates(args) {
     if (!force && shouldSkipAlreadyExtractedSession(prior, contentHash)) {
         return { skip: alreadyExtractedResult(harness.name, sessionRef.sessionId, prior, contentHash) };
     }
-    const filtered = preFilterSession(data, {
+    // #840 — harvest-without-prompting hybrid: the LLM prompt is built only from
+    // parent-origin events (folding stays as infrastructure for hashing above
+    // and inline-ref harvesting on `data.inlineRefs`, both of which still see
+    // the FULL folded stream). Subagent-origin events never reach
+    // `preFilterSession`, so #839's `dedupeTaskNotifications` naturally becomes
+    // a no-op on this path — a subagent's own event can no longer be in the
+    // kept set for a notification to be deduped against, leaving the parent's
+    // `<task-notification>` (the only surviving trace of that delegated work)
+    // untouched. See docs/plans/subagent-extraction-design.md §6.
+    const parentOriginData = {
+        ...data,
+        events: data.events.filter((e) => e.filePath === data.ref.filePath),
+    };
+    const filtered = preFilterSession(parentOriginData, {
         ...(typeof maxTotalChars === "number" ? { maxTotalChars } : {}),
     });
     // #595/#596 — minContentChars gate: skip the LLM call for sessions whose RAW
@@ -388,6 +401,14 @@ function runPreLlmSessionGates(args) {
     // fix gated on `filtered.stats.inputCount`, which is an EVENT count, not a
     // char count — this port measures actual raw chars so the threshold matches
     // the config key's documented unit.
+    // #840 — deliberately measured on the FULL folded `data.events` (parent +
+    // subagents), not the parent-origin view above: narrowing this to
+    // parent-origin chars would newly skip delegation-heavy sessions with a
+    // thin parent transcript before extraction runs at all, even though their
+    // subagent work is still fully harvested via `data.inlineRefs` above. The
+    // full-stream measurement is today's unchanged behavior, so the worst case
+    // this preserves is an LLM call over a small parent-only prompt, not a
+    // missed extraction.
     const rawContentChars = data.events.reduce((sum, event) => sum + event.text.length, 0);
     if (minContentChars > 0 && rawContentChars < minContentChars) {
         return {

package/dist/commands/read/remember-cli.js

@@ -7,7 +7,7 @@ import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich } from "../remember.js";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich, synthesizeMemoryDescription, } from "../remember.js";
 import { assertFlatAssetName, inferAssetName, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "./knowledge.js";
 import { akmSearch } from "./search.js";
 // ── Helper: similar memory search ────────────────────────────────────────────
@@ -189,7 +189,9 @@ export const rememberCommand = defineJsonCommand({
             // Phase 1B / Rec 7: even the zero-flag hot-path emits
             // `captureMode: hot` + `beliefState: asserted` so user-supplied
             // memories outrank background-derived ones during ranking.
+            // #834: `description` is synthesized deterministically (see synthesizeMemoryDescription) so the memory is indexable.
             const frontmatterBlock = buildMemoryFrontmatter({
+                description: synthesizeMemoryDescription(body),
                 captureMode: "hot",
                 beliefState: "asserted",
             });
@@ -264,6 +266,9 @@ export const rememberCommand = defineJsonCommand({
                 observed_at = enriched.observed_at;
             executionNotices = enriched.notices;
         }
+        // #834: no --description and no --enrich-derived one — synthesize deterministically (see zero-flag path above).
+        if (!description)
+            description = synthesizeMemoryDescription(body);
         // ── Required-field check (before any write) ───────────────────────────
         // Tags remain required when the user explicitly asked for tag-bearing
         // metadata (--tag / --enrich / --description / --source / --expires).

package/dist/commands/remember.js

@@ -9,6 +9,7 @@
  * CLI entry point stays focused on argument parsing + output routing.
  */
 import { serializeFrontmatter } from "../core/asset/asset-serialize.js";
+import { DESCRIPTION_MAX_CHARS } from "../core/authoring-rules.js";
 import { toErrorMessage, tryReadStdinText } from "../core/common.js";
 import { loadConfig } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
@@ -96,6 +97,75 @@ export function readMemoryContent(contentArg) {
     }
     return content;
 }
+/**
+ * Split `text` into sentence-shaped chunks on `.`/`!`/`?`, swallowing any
+ * immediately-trailing closing quotes/brackets/repeated terminators into the
+ * same sentence (so `Alice said, "hi there."` ends the sentence at the
+ * closing quote, not the period).
+ *
+ * Ported from akm-eval's memory backend (`splitIntoSentences` /
+ * `firstSentencesCapped` in akm-eval/src/memory/backends/akm.ts), which
+ * independently arrived at this exact synthesis rule after measuring that
+ * akm indexes only frontmatter/heading text, never body prose — the same gap
+ * this fixes at the source.
+ */
+function splitIntoSentences(text) {
+    const sentences = [];
+    let start = 0;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text.charAt(i);
+        if (ch === "." || ch === "!" || ch === "?") {
+            let end = i + 1;
+            while (end < text.length && /["'”’)\]!?.]/.test(text.charAt(end)))
+                end += 1;
+            sentences.push(text.slice(start, end));
+            while (end < text.length && /\s/.test(text.charAt(end)))
+                end += 1;
+            start = end;
+            i = end;
+            continue;
+        }
+        i += 1;
+    }
+    if (start < text.length)
+        sentences.push(text.slice(start));
+    return sentences;
+}
+/**
+ * Deterministically synthesize a `description` from a memory body when the
+ * caller didn't supply one (#834): `akm remember`'s hot-capture path used to
+ * write memories with no `description:` and no `tags:`, and akm's indexer
+ * covers only synthesized frontmatter/headings — never body prose — so those
+ * memories were retrievable only by whatever words survived into the
+ * auto-generated filename. This closes that gap at write time.
+ *
+ * Skips a leading markdown heading line (if any) so the description reads as
+ * prose rather than repeating the title, then accumulates whole sentences
+ * from the body until the next one would exceed `capChars`, hard-truncating
+ * only if the very first sentence alone is over the cap. Pure, deterministic,
+ * no LLM call — `akm remember` must stay a fast local write.
+ */
+export function synthesizeMemoryDescription(body, capChars = DESCRIPTION_MAX_CHARS) {
+    const withoutHeading = body.replace(/^\s*#{1,6}\s+.*(?:\r?\n)?/, "");
+    const trimmed = withoutHeading.trim() || body.trim();
+    if (!trimmed)
+        return "";
+    let out = "";
+    for (const raw of splitIntoSentences(trimmed)) {
+        const sentence = raw.trim();
+        if (!sentence)
+            continue;
+        const candidate = out ? `${out} ${sentence}` : sentence;
+        if (candidate.length > capChars) {
+            if (!out)
+                return `${candidate.slice(0, Math.max(0, capChars - 1)).trimEnd()}…`;
+            break;
+        }
+        out = candidate;
+    }
+    return out;
+}
 /**
  * Run heuristic analysis on memory body text. Returns derived metadata
  * fields without modifying any files. Pure TS, zero network, zero latency.

package/dist/integrations/harnesses/claude/session-log.js

@@ -19,6 +19,37 @@ import { AbstractSessionLogProvider } from "../../session-logs/provider-base.js"
 function claudeProjectsDir() {
     return process.env.AKM_CLAUDE_PROJECTS_DIR ?? path.join(os.homedir(), ".claude", "projects");
 }
+/**
+ * Directory Claude Code writes a session's subagent transcripts into, as
+ * `<project>/<parent-session-id>/subagents/agent-<agentId>.jsonl` (sometimes a
+ * level deeper, under a `workflows/<workflowId>/` subdirectory). These
+ * are not sessions of their own — every record inside carries the *parent's*
+ * `sessionId` — so they are excluded from `listSessions` and folded into the
+ * parent by `readSession`.
+ */
+const SUBAGENTS_DIR = "subagents";
+/**
+ * Provenance prefix for events read out of a subagent transcript, built from
+ * the `agent-<agentId>.meta.json` sidecar Claude Code writes next to it.
+ * Stamped onto the event text because {@link SessionEvent} has no dedicated
+ * field for it, and per-event (not once per transcript) so the provenance
+ * survives the extractor's per-event pre-filter.
+ */
+function subagentProvenance(jsonlPath) {
+    let agentType;
+    let description;
+    try {
+        const meta = JSON.parse(fs.readFileSync(jsonlPath.replace(/\.jsonl$/, ".meta.json"), "utf8"));
+        if (typeof meta.agentType === "string")
+            agentType = meta.agentType;
+        if (typeof meta.description === "string")
+            description = meta.description;
+    }
+    catch {
+        // missing / unreadable sidecar — fall back to an untyped marker
+    }
+    return `[subagent:${agentType ?? "unknown"}]${description ? ` ${description}` : ""}`;
+}
 /**
  * Parse a single Claude Code JSONL event into a normalized {@link SessionEvent}.
  * Returns `undefined` for events that don't carry textual content (file
@@ -120,13 +151,46 @@ export class ClaudeCodeProvider extends AbstractSessionLogProvider {
     }
     readSession(ref) {
         const stat = fs.statSync(ref.filePath);
-        const lines = fs.readFileSync(ref.filePath, "utf8").split("\n").filter(Boolean);
+        const projectHint = path.basename(path.dirname(ref.filePath));
+        const parent = this.#readTranscript(ref.filePath, ref.sessionId, stat.mtimeMs);
+        const events = parent.events;
+        const inlineRefs = parent.inlineRefs;
+        // Fold in this session's subagent transcripts: they record work delegated
+        // *during* this session and every record inside carries this session's id,
+        // so they are harvested under the parent's identity.
+        for (const subagentPath of this.walkFiles(path.join(path.dirname(ref.filePath), path.basename(ref.filePath, ".jsonl"), SUBAGENTS_DIR), (name) => name.endsWith(".jsonl"))) {
+            const subagent = this.#readTranscript(subagentPath, ref.sessionId, stat.mtimeMs, subagentProvenance(subagentPath));
+            events.push(...subagent.events);
+            inlineRefs.push(...subagent.inlineRefs);
+        }
+        // Merge chronologically rather than appending: the delegated work happened
+        // during the parent session, consumers document events as time-ordered,
+        // and the pre-filter's budget pass drops from the head (oldest first),
+        // which only samples sensibly on a time-ordered stream.
+        events.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+        return {
+            ref: this.sessionRef({
+                sessionId: ref.sessionId,
+                filePath: ref.filePath,
+                startedAt: events[0]?.ts ?? stat.ctimeMs,
+                endedAt: events[events.length - 1]?.ts ?? stat.mtimeMs,
+                projectHint,
+                title: parent.title,
+            }),
+            events,
+            inlineRefs,
+        };
+    }
+    /**
+     * Parse one JSONL transcript (a session's own, or one of its subagents')
+     * into normalized events plus the inline `akm` invocations they contain.
+     * `provenance`, when given, is prefixed to every event's text.
+     */
+    #readTranscript(filePath, sessionId, fallbackTsMs, provenance) {
         const events = [];
         const inlineRefs = [];
         let title;
-        let firstTsMs;
-        let lastTsMs;
-        const projectHint = path.basename(path.dirname(ref.filePath));
+        const lines = fs.readFileSync(filePath, "utf8").split("\n").filter(Boolean);
         for (const line of lines) {
             let entry;
             try {
@@ -141,29 +205,14 @@ export class ClaudeCodeProvider extends AbstractSessionLogProvider {
                 title = entry.customTitle;
                 continue;
             }
-            const parsed = parseClaudeEvent(entry, ref.sessionId, ref.filePath, stat.mtimeMs);
+            const parsed = parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs);
             if (!parsed)
                 continue;
-            events.push(parsed);
-            if (firstTsMs === undefined || (parsed.ts ?? 0) < firstTsMs)
-                firstTsMs = parsed.ts;
-            if (lastTsMs === undefined || (parsed.ts ?? 0) > lastTsMs)
-                lastTsMs = parsed.ts;
+            events.push(provenance ? { ...parsed, text: `${provenance}\n${parsed.text}` } : parsed);
             // Extract inline akm-remember/feedback invocations from this event's text.
             inlineRefs.push(...extractInlineRefMentions(parsed.text, parsed.ts));
         }
-        return {
-            ref: this.sessionRef({
-                sessionId: ref.sessionId,
-                filePath: ref.filePath,
-                startedAt: firstTsMs ?? stat.ctimeMs,
-                endedAt: lastTsMs ?? stat.mtimeMs,
-                projectHint,
-                title,
-            }),
-            events,
-            inlineRefs,
-        };
+        return { events, inlineRefs, ...(title ? { title } : {}) };
     }
     /**
      * Cheap metadata peek — reads the first ~4KB to grab the `custom-title`
@@ -234,8 +283,19 @@ export class ClaudeCodeProvider extends AbstractSessionLogProvider {
         }
         return result;
     }
-    /** Session JSONL files under `dir`, excluding the shared journal file. */
-    #walkJsonl(dir) {
-        return this.walkFiles(dir, (name) => name.endsWith(".jsonl") && name !== "journal.jsonl");
+    /**
+     * Session JSONL files under `dir`, excluding the shared journal file and
+     * subagent transcripts (folded into their parent by {@link readSession}).
+     * Only the directories *between* the project directory and the file are
+     * tested for {@link SUBAGENTS_DIR}, so a session file — which always sits
+     * directly in its project directory — can never be excluded.
+     */
+    *#walkJsonl(dir) {
+        for (const filePath of this.walkFiles(dir, (name) => name.endsWith(".jsonl") && name !== "journal.jsonl")) {
+            const segments = path.relative(dir, filePath).split(path.sep);
+            if (segments.slice(1, -1).includes(SUBAGENTS_DIR))
+                continue;
+            yield filePath;
+        }
     }
 }

package/dist/integrations/session-logs/pre-filter.js

@@ -90,12 +90,155 @@ function classifyEvent(event, akmReadOnlyOps, maxLen) {
     }
     return { keep: true, event, truncated: false };
 }
+/**
+ * A parent-side `<task-notification>` event, as Claude Code writes it into a
+ * session's own transcript: a `role: "user"` event whose text is (or wraps)
+ * `<task-notification>...<task-id>ID</task-id>...<result>TEXT</result>...</task-notification>`.
+ * Matched on the tags themselves (not a dedicated field) because
+ * {@link SessionEvent} carries no structural provenance beyond `text`/`role`/
+ * `filePath` — the same constraint #830 (subagent provenance) worked within.
+ */
+const TASK_NOTIFICATION_RE = /<task-notification>[\s\S]*<\/task-notification>/;
+const TASK_ID_RE = /<task-id>([^<]+)<\/task-id>/;
+const RESULT_RE = /<result>([\s\S]*)<\/result>/;
+const SUMMARY_RE = /<summary>([^<]*)<\/summary>/;
+/** Claude Code's own `<summary>` phrasing for a finished agent: `Agent "<description>" finished`. */
+const AGENT_SUMMARY_DESCRIPTION_RE = /^Agent "(.*)" finished$/;
+/** Provenance {@link subagentProvenance} stamps on every folded subagent event; stripped before comparison. */
+const PROVENANCE_PREFIX_RE = /^\[subagent:[^\]]*\][^\n]*\n/;
+/** Claude Code's own agentId file naming: `<...>/subagents/<...>agent-<agentId>.jsonl`. */
+const SUBAGENT_FILEPATH_RE = /agent-([^/\\]+?)\.jsonl$/;
+/** Dice (bigram) similarity at/above this counts as "the same content" (#839). */
+const DEDUPE_SIMILARITY_THRESHOLD = 0.9;
+/** A handful of named-entity decodes — enough for what Claude Code escapes when it wraps `<result>` text in XML. */
+function decodeXmlEntities(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/** Sørensen–Dice coefficient over character bigrams — a cheap, symmetric textual-overlap measure. */
+function diceSimilarity(a, b) {
+    if (a.length < 2 || b.length < 2)
+        return a === b ? 1 : 0;
+    const bigrams = (s) => {
+        const counts = new Map();
+        for (let i = 0; i < s.length - 1; i++) {
+            const bg = s.slice(i, i + 2);
+            counts.set(bg, (counts.get(bg) ?? 0) + 1);
+        }
+        return counts;
+    };
+    const bigramsA = bigrams(a);
+    const bigramsB = bigrams(b);
+    let intersection = 0;
+    let totalA = 0;
+    let totalB = 0;
+    for (const count of bigramsA.values())
+        totalA += count;
+    for (const count of bigramsB.values())
+        totalB += count;
+    for (const [bg, count] of bigramsA) {
+        const other = bigramsB.get(bg);
+        if (other)
+            intersection += Math.min(count, other);
+    }
+    return totalA + totalB === 0 ? 1 : (2 * intersection) / (totalA + totalB);
+}
+/**
+ * Stub out a parent's `<task-notification>` event when its `<result>` is a
+ * near-duplicate of a subagent transcript's own event that ALSO survived
+ * into this same kept set (#839).
+ *
+ * After #830 folds a session's subagent transcripts into its event stream,
+ * a completed subagent's report can appear twice: once as the subagent's own
+ * folded final event, once as the parent's `<task-notification>` record of
+ * that same call — the notification wraps the subagent's own text almost
+ * verbatim (Claude Code XML-escapes `<`/`>`/`&`/quotes in the `<result>`
+ * body, which {@link decodeXmlEntities} reverses before comparing). Direction
+ * is owner-decided (#839): drop the parent's copy, keep the subagent's
+ * original — the inverse was evaluated and rejected in #836 because some
+ * subagent transcripts consist ONLY of their terminal event, so dropping it
+ * would destroy the harvesting #830 added.
+ *
+ * **Runs on `kept` — the FINAL post-budget list — not the raw stream**, and
+ * only stubs a notification when a matching subagent event is ALSO present
+ * in that same `kept` list. This is required, not incidental: the recency-
+ * biased budget already evicts one side of most raw duplicate pairs before
+ * dedupe would matter (#840's design doc measured zero pairs where both
+ * copies reached the pre-dedupe prompt across four real sessions), and any
+ * future prompt-composition design that stops including subagent-origin
+ * events in the prompt at all (#840's recommended "harvest-without-
+ * prompting hybrid") makes the parent's `<task-notification>` the ONLY
+ * surviving trace of that delegated work. An unconditional raw-stream stub
+ * would delete that sole copy the moment the subagent's own event is absent
+ * for ANY reason — evicted by budget today, or never present by design
+ * tomorrow. Scoping to "both sides survived into the same kept set" makes
+ * this dedupe a no-op whenever there is only one copy left to dedupe
+ * against, which is exactly the case where deleting it would be a bug, not
+ * a fix.
+ *
+ * Matching is scoped by `<task-id>` (which is the subagent's agentId) to the
+ * SPECIFIC subagent transcript it names, via the `agent-<agentId>.jsonl`
+ * filename #830's folding already stamps onto every folded event's
+ * `filePath` — then requires the decoded `<result>` to be a near-duplicate
+ * (Dice similarity ≥ {@link DEDUPE_SIMILARITY_THRESHOLD}) of that subagent's
+ * text, not merely a same-agent match. This matters because a task-notification
+ * fires every time an agent stops (Claude Code's own note in the event: "the
+ * same task-id may notify more than once") — an EARLIER notification for a
+ * resumed agent can carry a genuinely different (intermediate) result that
+ * must NOT be stubbed just because the ids line up.
+ *
+ * The event is kept (not dropped) so event counts/timestamps stay stable and
+ * the parent's narrative — *why* it delegated — survives as a short stub:
+ * `[subagent <agentId> completed: <description>]`.
+ */
+function dedupeTaskNotifications(kept) {
+    // Index the KEPT subagent events by the agentId embedded in their
+    // transcript's filename, so a notification's <task-id> narrows the
+    // comparison to the ONE subagent it reports on — and so an agentId with no
+    // surviving event here means "nothing to dedupe against", not "assume it
+    // exists upstream".
+    const byAgentId = new Map();
+    for (const event of kept) {
+        const agentId = event.filePath?.match(SUBAGENT_FILEPATH_RE)?.[1];
+        if (!agentId)
+            continue;
+        const list = byAgentId.get(agentId);
+        if (list)
+            list.push(event);
+        else
+            byAgentId.set(agentId, [event]);
+    }
+    if (byAgentId.size === 0)
+        return kept; // no folded subagent survived the budget — nothing to dedupe
+    return kept.map((event) => {
+        if (event.role !== "user" || !TASK_NOTIFICATION_RE.test(event.text))
+            return event;
+        const taskId = event.text.match(TASK_ID_RE)?.[1];
+        const resultRaw = event.text.match(RESULT_RE)?.[1];
+        if (!taskId || !resultRaw)
+            return event; // no <result> (e.g. a background-command notification) — nothing to compare
+        const candidates = byAgentId.get(taskId);
+        if (!candidates || candidates.length === 0)
+            return event; // that subagent's own event didn't survive into this kept set
+        const decodedResult = decodeXmlEntities(resultRaw);
+        const isDuplicate = candidates.some((c) => diceSimilarity(decodedResult, c.text.replace(PROVENANCE_PREFIX_RE, "")) >= DEDUPE_SIMILARITY_THRESHOLD);
+        if (!isDuplicate)
+            return event;
+        const summary = event.text.match(SUMMARY_RE)?.[1]?.trim();
+        const description = (summary && (summary.match(AGENT_SUMMARY_DESCRIPTION_RE)?.[1] ?? summary)) || "completed";
+        return { ...event, text: `[subagent ${taskId} completed: ${description}]` };
+    });
+}
 export function preFilterSession(data, options = {}) {
     const akmReadOnlyOps = options.akmReadOnlyOps ?? DEFAULT_AKM_READONLY_OPS;
     const maxLen = options.maxEventTextLength ?? DEFAULT_MAX_EVENT_LENGTH;
     const maxTotalChars = options.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
     const droppedByRule = {};
-    const kept = [];
+    let kept = [];
     let truncatedCount = 0;
     const candidates = [];
     for (const event of data.events) {
@@ -138,6 +281,13 @@ export function preFilterSession(data, options = {}) {
         if (c.truncated)
             truncatedCount += 1;
     }
+    // Post-pass (#839): dedupe a task-notification against a subagent event
+    // ONLY when both survived into this exact kept set — see
+    // dedupeTaskNotifications's doc for why that scoping is required. Recompute
+    // totalChars afterward since stubbing can only shrink kept text, never move
+    // anything across the budget boundary already decided above.
+    kept = dedupeTaskNotifications(kept);
+    const finalTotalChars = kept.reduce((sum, e) => sum + e.text.length, 0);
     return {
         events: kept,
         stats: {
@@ -145,7 +295,7 @@ export function preFilterSession(data, options = {}) {
             outputCount: kept.length,
             droppedByRule,
             truncatedCount,
-            totalChars,
+            totalChars: finalTotalChars,
             budgetDroppedCount,
         },
     };

package/dist/registry/semver.js

@@ -41,3 +41,7 @@ export function isSemverRange(input) {
 export function maxSatisfying(versions, range) {
     return semver.maxSatisfying(versions, range) ?? undefined;
 }
+/** True when `version` satisfies `range` (both real semver forms). False for an invalid version or range. */
+export function satisfiesRange(version, range) {
+    return semver.satisfies(version, range);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.2-alpha.3",
+  "version": "0.9.2-alpha.4",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [