akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/improve/eligibility.js

@@ -4,9 +4,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { conceptIdFromTypeName, parseRefInput, resolveRef } from "../../core/asset/resolve-ref.js";
+import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { readEvents } from "../../core/events.js";
+import { getDbPath } from "../../core/paths.js";
+import { deriveInstallations } from "../../indexer/installations.js";
 import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
@@ -19,6 +22,17 @@ import { improveStateReadRefs } from "./source-identity.js";
 // Eligibility / candidate-selection predicates for improve. Free functions
 // (no akmImprove closure state) extracted from improve.ts to shrink the
 // orchestrator and make candidate selection independently testable.
+/**
+ * Open the index for eligibility queries, or `undefined` when no index exists
+ * yet. `openExistingDatabase` refuses to create a missing `index.db` (see
+ * index-connection.ts) — for eligibility, "no index" simply means nothing is
+ * eligible, exactly like the readOnly arm's `undefined`.
+ */
+function openEligibilityDb(readOnly) {
+    if (readOnly)
+        return openReadonlyExistingDatabase();
+    return fs.existsSync(getDbPath()) ? openExistingDatabase() : undefined;
+}
 export function resolveImproveScope(scope) {
     const trimmed = scope?.trim();
     if (!trimmed)
@@ -28,9 +42,8 @@ export function resolveImproveScope(scope) {
         return { mode: "ref", value: trimmed };
     }
     catch (err) {
-        // Open type token (chunk 1.5, D1.5-1): a bare word with no `type:name`
-        // shape (no colon) is a `--scope <type>` filter attempt, not a ref — ANY
-        // such word is now accepted, including foreign/unknown type strings,
+        // A bare word with no ref separator is a `--scope <type>` filter attempt,
+        // not a ref. Any such word is accepted, including foreign/unknown type strings,
         // which simply match zero entries downstream (a read-only query filter,
         // not a data-acceptance gate, so no deny-list is needed here: an
         // unrecognized type just matches nothing, since nothing is ever indexed
@@ -42,7 +55,7 @@ export function resolveImproveScope(scope) {
         // deliberately-removed type like tool/vault, D1.5-6) — that must still
         // surface as a real error, not be silently absorbed into a type filter
         // that will never match anything.
-        if (!trimmed.includes(":")) {
+        if (!/[/:#]/.test(trimmed)) {
             return { mode: "type", value: trimmed };
         }
         const message = err instanceof Error ? err.message : String(err);
@@ -50,7 +63,8 @@ export function resolveImproveScope(scope) {
     }
 }
 /**
- * Dedupe a list of eligible refs by `ref`, preserving first-seen order. Used to
+ * Dedupe eligible refs by their durable item ref when available, preserving
+ * the first candidate and its display ref. Used to
  * merge the eligibility sources (feedback-signal, Layer-2 proactive-maintenance,
  * high-salience) without admitting a ref into the loop twice.
  */
@@ -58,44 +72,76 @@ export function dedupeRefs(refs) {
     const seen = new Set();
     const out = [];
     for (const r of refs) {
-        if (seen.has(r.ref))
+        const key = r.itemRef ?? r.ref;
+        if (seen.has(key))
             continue;
-        seen.add(r.ref);
+        seen.add(key);
         out.push(r);
     }
     return out;
 }
-export async function collectEligibleRefs(scope, stashDir, improveProfile) {
-    return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, false);
+export async function collectEligibleRefs(scope, stashDir, improveProfile, config) {
+    return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, false, config);
 }
 /** Dry-run planner path: query an existing index without creating or mutating it. */
-export async function collectEligibleRefsReadOnly(scope, stashDir, improveProfile) {
-    return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, true);
+export async function collectEligibleRefsReadOnly(scope, stashDir, improveProfile, config) {
+    return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, true, config);
 }
-async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, readOnly) {
+async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, readOnly, configOverride) {
+    const config = configOverride ?? loadConfig();
     if (scope.mode === "ref" && scope.value) {
-        const parsed = parseRefInput(scope.value);
-        const writableDirs = new Set(getWritableStashDirs(stashDir).map((dir) => path.resolve(dir)));
-        const filePath = await findAssetFilePath(scope.value, stashDir, writableDirs);
-        if (!filePath) {
+        const writableDirs = new Set(getWritableStashDirs(stashDir, config).map((dir) => path.resolve(dir)));
+        let db;
+        try {
+            db = openEligibilityDb(readOnly);
+            if (!db) {
+                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+            }
+            const entries = getAllEntries(db);
+            const entriesByItemRef = new Map(entries.flatMap((entry) => entry.bundleId && entry.conceptId ? [[`${entry.bundleId}//${entry.conceptId}`, entry]] : []));
+            const installations = deriveInstallations(resolveSourceEntries(stashDir, config));
+            const resolved = resolveRef(scope.value, {
+                defaultBundle: config.defaultBundle,
+                bundles: installations.map((installation) => ({
+                    id: installation.id,
+                    hasConcept: (conceptId) => entriesByItemRef.has(`${installation.id}//${conceptId}`),
+                })),
+            });
+            const indexed = entriesByItemRef.get(`${resolved.bundle}//${resolved.conceptId}`);
+            if (!indexed?.bundleId || !indexed.conceptId || !fs.existsSync(indexed.filePath)) {
+                if (await findAssetFilePath(scope.value, stashDir)) {
+                    return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+                }
+                throw new NotFoundError(`Asset not found in the selected writable source: ${scope.value}`, "ASSET_NOT_FOUND");
+            }
+            if (!isEntryInScope(indexed.stashDir, indexed.filePath, stashDir) ||
+                !isEntryInWritableSource(indexed.stashDir, indexed.filePath, writableDirs)) {
+                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+            }
+            const itemRef = `${indexed.bundleId}//${indexed.conceptId}`;
             return {
-                plannedRefs: [],
-                memorySummary: { eligible: 0, derived: 0 },
+                plannedRefs: [{ ref: indexed.conceptId, itemRef, reason: "scope-ref", filePath: indexed.filePath }],
+                memorySummary: {
+                    eligible: indexed.entry.type === "memory" ? 1 : 0,
+                    derived: indexed.entry.type === "memory" && indexed.entry.name.endsWith(".derived") ? 1 : 0,
+                },
                 strategyFilteredRefs: [],
             };
         }
-        return {
-            plannedRefs: [{ ref: scope.value, reason: "scope-ref", filePath }],
-            memorySummary: {
-                eligible: parsed.type === "memory" ? 1 : 0,
-                derived: parsed.type === "memory" && parsed.name.endsWith(".derived") ? 1 : 0,
-            },
-            strategyFilteredRefs: [],
-        };
+        catch (error) {
+            if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
+                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+            }
+            throw error;
+        }
+        finally {
+            if (db)
+                closeDatabase(db);
+        }
     }
     let sources;
     try {
-        sources = resolveSourceEntries(stashDir);
+        sources = resolveSourceEntries(stashDir, config);
     }
     catch {
         return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
@@ -107,7 +153,7 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
     // or remote stashes that the user did not mark writable.
     let writableDirs;
     try {
-        writableDirs = getWritableStashDirs(stashDir);
+        writableDirs = getWritableStashDirs(stashDir, config);
     }
     catch {
         writableDirs = sources.slice(0, 1).map((s) => s.path); // fallback: primary only
@@ -115,7 +161,7 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
     const writableDirSet = new Set(writableDirs.map((d) => path.resolve(d)));
     let db;
     try {
-        db = readOnly ? openReadonlyExistingDatabase() : openExistingDatabase();
+        db = openEligibilityDb(readOnly);
         if (!db) {
             return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
         }
@@ -127,7 +173,7 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             return isEntryInWritableSource(indexed.stashDir, indexed.filePath, writableDirSet);
         });
         const planned = new Map();
-        const profileFiltered = new Map();
+        const strategyFiltered = new Map();
         let memoryEligible = 0;
         let memoryDerived = 0;
         for (const indexed of entries) {
@@ -136,11 +182,16 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             // xrefs, and `displayRef` output spelling. `.itemRef` below stays the
             // fully-qualified durable key.
             const ref = conceptIdFromTypeName(indexed.entry.type, indexed.entry.name);
-            // Chunk-5 flip F5d (Step 4): the durable `item_ref` (`<bundle>//<concept-id>`),
-            // reconstructed from the mapper-unlocked provenance columns with ZERO extra
-            // queries (D-R3 — derived from the resolved index entry, never raw input).
-            // `undefined` for a NULL-provenance (pre-flip / write-back) row; the durable
-            // writers then fall back to the legacy `type:name` key.
+            try {
+                parseRefInput(ref);
+            }
+            catch (error) {
+                if (error instanceof UsageError || error instanceof NotFoundError)
+                    continue;
+                throw error;
+            }
+            // Derive the durable item_ref from indexed provenance without another query.
+            // A provenance-free row uses the short conceptId ref for improve state.
             const itemRef = indexed.bundleId && indexed.conceptId ? `${indexed.bundleId}//${indexed.conceptId}` : undefined;
             const isDerived = indexed.entry.name.endsWith(".derived");
             // `.derived` memories are LLM-inferred and intentionally skip reflect
@@ -150,16 +201,16 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             // 2026-05-21: 11 derived refs re-planned every hour during idle periods.
             // The cleanup phase (analyzeMemoryCleanup) inspects derived memories
             // independently of `plannedRefs`, so dropping them here loses nothing.
-            if (!isDerived && !planned.has(ref) && !profileFiltered.has(ref)) {
-                // 2026-05-27: extend the .derived precedent to profile-incompatible
+            if (!isDerived && !planned.has(ref) && !strategyFiltered.has(ref)) {
+                // 2026-05-27: extend the .derived precedent to strategy-incompatible
                 // refs. If every per-ref pass (reflect + distill) on the active
-                // profile would refuse this ref, drop it from `plannedRefs`. The
+                // strategy would refuse this ref, drop it from `plannedRefs`. The
                 // caller emits `improve_skipped { reason: strategy_filtered_all_passes }`
                 // once `eventsCtx` is available so the audit trail is preserved in a
                 // single event per ref instead of 2× synthetic actions per run.
                 // Background: see /tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md
                 if (improveProfile && isStrategyFilteredForAllPasses(ref, improveProfile)) {
-                    profileFiltered.set(ref, {
+                    strategyFiltered.set(ref, {
                         ref,
                         reason: "strategy_filtered_all_passes",
                         filePath: indexed.filePath,
@@ -184,13 +235,13 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
         return {
             plannedRefs: [...planned.values()],
             memorySummary: { eligible: memoryEligible, derived: memoryDerived },
-            strategyFilteredRefs: [...profileFiltered.values()],
+            strategyFilteredRefs: [...strategyFiltered.values()],
         };
     }
     catch (error) {
-        // The bun-test isolation guard must never be downgraded to "empty plan".
+        // Empty-stash setup paths can open index.db before its schema exists.
         rethrowIfTestIsolationError(error);
-        if (error instanceof NotFoundError || error instanceof Error) {
+        if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
             return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
         }
         throw error;
@@ -247,9 +298,8 @@ export function memoryCleanupParentRef(scope, stashDir) {
             continue;
         const raw = fs.readFileSync(candidate, "utf8");
         const fm = parseFrontmatter(raw).data;
-        // The `source:` backref (the `derived_from` channel) is read through the
-        // legacy-tolerant parseMemoryRef, whose NORMALISED output is now the 0.9.0
-        // `memories/<name>` conceptId (Group-C item 2). That is exactly what
+        // The `source:` backref is normalized to the `memories/<name>` conceptId.
+        // That is exactly what
         // analyzeMemoryCleanup's parentRef filter compares against — resolveParentRef
         // emits the same conceptId — so the two sites stay in lockstep.
         const parent = parseMemoryRef(typeof fm.source === "string" ? fm.source : undefined);
@@ -282,7 +332,7 @@ export function isLessonCandidate(ref) {
  * which was true *only* for `lesson:*` refs — exactly the set distill refuses.
  * The result: every hourly run re-queued the same lesson refs, the same skip
  * message returned, and no work was ever done. See
- * `tests/commands/improve-distill-planner-skip-lessons.test.ts`.
+ * `tests/integration/commands/improve-distill-planner-skip-lessons.test.ts`.
  */
 export function isDistillCandidateRef(ref, stashDir) {
     const parsed = parseRefInput(ref);
@@ -325,13 +375,12 @@ export function shouldDistillMemoryRef(ref, stashDir) {
  * metadata events are ignored so a stray `akm feedback <ref>` invocation
  * without a flag doesn't trigger downstream re-processing.
  */
-export function buildLatestFeedbackTsMap(refs, sinceIso, sourceName, includeLegacyBare = false, itemRefByRef) {
+export function buildLatestFeedbackTsMap(refs, sinceIso, itemRefByRef) {
     const out = new Map();
     if (refs.length === 0)
         return out;
-    // Chunk-5 flip F5e — dual-arm on [item_ref, durable, bare] so an item_ref-
-    // keyed feedback event resolves once the writers emit it. // Chunk-8: [item_ref].
-    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, sourceName, includeLegacyBare, itemRefByRef?.get(ref)).map((key) => [key, ref])));
+    // Correlate item_ref-keyed events and conceptId-keyed direct invocations.
+    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, itemRefByRef?.get(ref)).map((key) => [key, ref])));
     const { events } = readEvents({ type: "feedback", since: sinceIso });
     for (const e of events) {
         const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
@@ -351,18 +400,17 @@ export function buildLatestFeedbackTsMap(refs, sinceIso, sourceName, includeLega
  * Latest proposal timestamp per input-ref, filtered by source ('reflect' or
  * 'distill'). Reads the corresponding `*_invoked` events from state.db —
  * these events are emitted at proposal creation time and carry the *input*
- * asset ref (memory:foo, skill:bar, etc.) directly. We use them rather than
+ * asset ref (`memories/foo`, `skills/bar`, etc.) directly. We use them rather than
  * `listProposals` because distill proposals are keyed by the derived
  * lesson/knowledge ref, not the source memory — joining back through the
  * payload would be fragile.
  */
-export function buildLatestProposalTsMap(refs, source, sourceName, includeLegacyBare = false, itemRefByRef) {
+export function buildLatestProposalTsMap(refs, source, itemRefByRef) {
     const out = new Map();
     if (refs.length === 0)
         return out;
-    // Chunk-5 flip F5e — dual-arm on [item_ref, durable, bare] so an item_ref-
-    // keyed *_invoked event resolves once the writers emit it. // Chunk-8: [item_ref].
-    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, sourceName, includeLegacyBare, itemRefByRef?.get(ref)).map((key) => [key, ref])));
+    // Correlate item_ref-keyed events and conceptId-keyed direct invocations.
+    const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, itemRefByRef?.get(ref)).map((key) => [key, ref])));
     const eventType = source === "reflect" ? "reflect_invoked" : "distill_invoked";
     const { events } = readEvents({ type: eventType });
     for (const e of events) {
@@ -479,6 +527,6 @@ export async function findAssetFilePath(ref, stashDir, writableDirSet) {
         writableDirSet,
         directoryIndexNames: ["SKILL.md"],
         preserveDirectNameFallback: true,
-        honorOrigin: false,
+        honorOrigin: true,
     });
 }

package/dist/commands/improve/extract-cli.js

@@ -2,31 +2,30 @@
 // 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/.
 /**
- * CLI surface for `akm extract`.
+ * CLI surface for `akm proposal extract` (formerly the top-level `akm
+ * extract`, moved under the `proposal` group in the 0.9 CLI overhaul, S8 —
+ * see src/commands/proposal/proposal-cli.ts for its registration).
  *
  * Examples:
- *   akm extract --type claude-code --session-id <id>
- *   akm extract --type claude-code --since 24h
- *   akm extract --type opencode --since 7d --dry-run
- *   akm extract --auto                 # iterate all available harnesses
- *   akm extract --type claude-code --location /custom/path --session-id <id>
+ *   akm proposal extract --type claude-code --session-id <id>
+ *   akm proposal extract --type claude-code --since 24h
+ *   akm proposal extract --type opencode --since 7d --dry-run
+ *   akm proposal extract --auto                 # iterate all available harnesses
+ *   akm proposal extract --type claude-code --location /custom/path --session-id <id>
  *
  * Output is the AkmExtractResult JSON envelope (or an aggregated one when
  * `--auto` runs multiple harnesses).
  */
-import fs from "node:fs";
-import path from "node:path";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineJsonCommand, EXIT_CODES, output } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
-import { getAvailableHarnesses, getWatchTargets } from "../../integrations/session-logs/index.js";
-import { akmExtract, resolveStandaloneExtractPlan, } from "./extract.js";
-import { akmExtractWatch } from "./extract-watch.js";
+import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
+import { akmExtract, resolveStandaloneExtractPlan } from "./extract.js";
 export const extractCommand = defineJsonCommand({
     meta: {
         name: "extract",
-        description: "Extract durable insights from native session files (claude-code, opencode) and queue them as proposals. Replaces the legacy session-checkpoint hook.",
+        description: "Extract durable insights from native session files (claude-code, opencode) and queue them as proposals.",
     },
     args: {
         type: {
@@ -72,15 +71,6 @@ export const extractCommand = defineJsonCommand({
             type: "string",
             description: "Improve strategy supplying extract behavior and engine. Mutually exclusive with --engine.",
         },
-        watch: {
-            type: "boolean",
-            description: "Watch harness session-log directories and run extract on change (debounced). Stays alive until SIGINT/SIGTERM.",
-            default: false,
-        },
-        "debounce-ms": {
-            type: "string",
-            description: "Debounce window in ms for --watch (default 2000).",
-        },
     },
     async run({ args }) {
         const type = getStringArg(args, "type") ?? "";
@@ -101,17 +91,10 @@ export const extractCommand = defineJsonCommand({
         if (engine && strategy) {
             throw new UsageError("--engine and --strategy are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
         }
-        const watch = args.watch === true;
-        const debounceMs = typeof args["debounce-ms"] === "string" && args["debounce-ms"] !== ""
-            ? Number.parseInt(args["debounce-ms"], 10)
-            : 2000;
-        if (watch && (!Number.isFinite(debounceMs) || debounceMs <= 0)) {
-            throw new UsageError(`--debounce-ms must be a positive integer (got "${args["debounce-ms"]}").`, "INVALID_FLAG_VALUE");
-        }
-        if (!watch && auto && type) {
+        if (auto && type) {
             throw new UsageError("--auto and --type are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
         }
-        if (!watch && !auto && !type) {
+        if (!auto && !type) {
             throw new UsageError("--type is required (or pass --auto to try every available harness).", "MISSING_REQUIRED_ARGUMENT");
         }
         const config = loadConfig();
@@ -120,10 +103,6 @@ export const extractCommand = defineJsonCommand({
             ...(strategy ? { strategy } : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         });
-        if (watch) {
-            await runWatchMode({ debounceMs, dryRun, force, config, resolvedPlan, ...(since ? { since } : {}) });
-            return;
-        }
         const commonOptions = Object.freeze({
             ...(sessionId ? { sessionId } : {}),
             ...(location ? { location } : {}),
@@ -164,7 +143,7 @@ export const extractCommand = defineJsonCommand({
             // Signal failure to callers/schedulers when every harness failed. output()
             // only renders; without this a scheduled run exits 0 on a total failure
             // and the breakage is invisible to exit-code monitoring. process.exitCode
-            // (not process.exit) lets stdout flush and the watcher/timers settle.
+            // (not process.exit) lets stdout flush before the process exits.
             if (!ok)
                 process.exitCode = EXIT_CODES.GENERAL;
             return;
@@ -175,101 +154,3 @@ export const extractCommand = defineJsonCommand({
             process.exitCode = EXIT_CODES.GENERAL;
     },
 });
-/**
- * A thin {@link WatchEventSource} over `fs.watch` for each configured root.
- * This adapter is the ONLY place a real `fs.watch` is created (the core stays
- * injectable + fully unit-tested); it is intentionally not unit-covered.
- *
- * `fs.watch(dir, { recursive: true })` is unreliable for recursive mode on some
- * Node/Bun/Linux combinations. A root that cannot be watched is skipped while
- * successfully-created watchers continue running.
- */
-function createFsWatchEventSource(roots) {
-    return {
-        subscribe(listener) {
-            const watchers = [];
-            for (const root of roots) {
-                try {
-                    const watcher = fs.watch(root, { recursive: true }, (_event, filename) => {
-                        if (!filename)
-                            return;
-                        const filePath = path.isAbsolute(filename.toString())
-                            ? filename.toString()
-                            : path.join(root, filename.toString());
-                        listener({ path: filePath });
-                    });
-                    watchers.push(watcher);
-                }
-                catch {
-                    // A root that can't be watched is skipped.
-                }
-            }
-            return () => {
-                for (const w of watchers) {
-                    try {
-                        w.close();
-                    }
-                    catch {
-                        // best-effort teardown
-                    }
-                }
-            };
-        },
-    };
-}
-/** Snapshot the CLI-resolved watch options once and reuse them for every debounced trigger. */
-export function createExtractWatchTrigger(options, extractFn = akmExtract) {
-    const snapshot = Object.freeze({ ...options });
-    return async (harnessName) => {
-        await extractFn({ type: harnessName, ...snapshot });
-    };
-}
-/**
- * Run `akm extract --watch`: watch every available harness's session-log
- * roots and run extract (debounced, per-harness) on change. Stays alive until
- * SIGINT/SIGTERM, then stops cleanly. PROCESS-HYGIENE: stop() removes every
- * watcher + pending timer before the process exits.
- */
-async function runWatchMode(opts) {
-    const targets = getWatchTargets();
-    if (targets.length === 0) {
-        output("extract", {
-            schemaVersion: 1,
-            ok: false,
-            shape: "extract-watch-started",
-            warnings: ["no watchable harness session-log directories found on this machine"],
-            watching: [],
-        });
-        return;
-    }
-    const allRoots = targets.flatMap((t) => t.roots);
-    const eventSource = createFsWatchEventSource(allRoots);
-    const onTrigger = createExtractWatchTrigger({
-        dryRun: opts.dryRun,
-        force: opts.force,
-        config: opts.config,
-        resolvedPlan: opts.resolvedPlan,
-        ...(opts.since ? { since: opts.since } : {}),
-    });
-    const handle = akmExtractWatch({
-        roots: targets,
-        eventSource,
-        debounceMs: opts.debounceMs,
-        onTrigger,
-    });
-    output("extract", {
-        schemaVersion: 1,
-        ok: true,
-        shape: "extract-watch-started",
-        debounceMs: opts.debounceMs,
-        watching: allRoots,
-    });
-    await new Promise((resolve) => {
-        const shutdown = () => {
-            handle.stop();
-            resolve();
-        };
-        process.once("SIGINT", shutdown);
-        process.once("SIGTERM", shutdown);
-    });
-}