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

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/indexer/walk/matchers.js

@@ -101,7 +101,21 @@ const DIR_TYPE_MAP = [
         test: (ext) => ext === ".md",
     },
 ];
-const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+/**
+ * `$ARGUMENTS` — unambiguous. Nothing else writes it, so finding it in a body
+ * is strong evidence of a command wherever the file lives.
+ */
+const ARGUMENTS_PLACEHOLDER_RE = /\$ARGUMENTS/;
+/**
+ * `$1` / `$2` / `$3` — AMBIGUOUS, because ordinary prose writes money the same
+ * way. The old combined pattern used `\$[123]\b`, and `\b` sits between the
+ * `2` and the comma in `$2,000`, so every note quoting a price read as a
+ * command (#824). Excluding a following digit, or a `.`/`,` that is itself
+ * followed by a digit, rules out `$1,200` / `$2,000` / `$2.50` / `$12` while
+ * still matching `$1.` at the end of a sentence — a period with no digit after
+ * it is not part of a number.
+ */
+const NUMERIC_PLACEHOLDER_RE = /\$[123](?!\d|[.,]\d)/;
 const SMART_MD_FACTS = {
     workflow: { type: "workflow", specificity: 19 },
     toolsAgent: { type: "agent", specificity: 20 },
@@ -141,6 +155,17 @@ function matchDirectoryHint(dirName, ctx, specificity) {
     }
     return null;
 }
+/**
+ * True when some ancestor directory already DECLARES this file's type via
+ * `DIR_TYPE_MAP` — the same walk `classifyByDirectory` performs. Derived from
+ * path fields alone, so `smartMdPathCandidates` can apply it without reading
+ * bytes.
+ */
+function hasDeclaredDirType(ctx) {
+    if (isNestedSkillResource(ctx))
+        return false;
+    return ctx.ancestorDirs.some((dir) => matchDirectoryHint(dir, ctx, 0) !== null);
+}
 function classifyByExtension(ctx) {
     if (ctx.fileName === "SKILL.md") {
         return { type: "skill", specificity: 25 };
@@ -204,7 +229,19 @@ function classifyBySmartMd(ctx) {
             return SMART_MD_FACTS.command;
         }
     }
-    if (COMMAND_PLACEHOLDER_RE.test(body)) {
+    // `$ARGUMENTS` is unambiguous, so it keeps its long-standing precedence: a
+    // command dropped under `knowledge/` is still found as a command.
+    if (ARGUMENTS_PLACEHOLDER_RE.test(body)) {
+        return SMART_MD_FACTS.command;
+    }
+    // A NUMERIC placeholder is a guess, and a typed directory is a declaration.
+    // Where the two disagree the declaration wins — otherwise a note that merely
+    // quotes a price is retyped, which is #824: `memories/*.md` mentioning
+    // `$2,000` were indexed as commands, their refs moved to
+    // `commands/memories/<slug>`, and they left the `memories/` namespace
+    // entirely. Outside a typed directory there is no declaration to defer to,
+    // so the guess still stands.
+    if (NUMERIC_PLACEHOLDER_RE.test(body) && !hasDeclaredDirType(ctx)) {
         return SMART_MD_FACTS.command;
     }
     if (fm && "model" in fm) {

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);
+}