akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.8

package/CHANGELOG.md

@@ -6,6 +6,291 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.8] - 2026-09-28
+
+`akm index` now records the links a bundle already declares (`xrefs`,
+`supersededBy`, a `.derived` memory's parent, wiki sources, page links, and
+workflow and task targets) as typed links, with no model. `akm show` lists
+them, and curate's support refs come from them instead of the LLM entity
+graph. The index moves to layout 26 in place on its first writable open;
+0.9.17-alpha.4 through alpha.7 cannot open it. `index.graph.enabled: false`
+now stops graph extraction in `akm improve`, and a partly failed extraction is
+retried. `akm migrate` converts a v2 or v3 task file to v4 in one pass, and
+the launchers no longer lose a signal that arrives before their child starts.
+
+### Added
+
+- **Declared links (#935).** The relations a bundle already declares are now
+  stored as typed links: `xrefs:` (`xref`), `supersededBy:`
+  (`superseded_by`), `contradictedBy:` (`contradicted_by`),
+  `currentBeliefRefs:` (`belief_peer`), a `.derived` memory's parent
+  (`derived_from`), wiki `sources:` that name an asset (`cites`), the page
+  links an llm-wiki or OKF bundle resolves (`links_to`), and a workflow step's
+  or a task's target (`uses`). `akm index` reads them from what it already
+  parses, with no model, so an install without an LLM engine gets them. They
+  live in their own table (`asset_links`), apart from the LLM entity graph:
+  each link belongs to the entry that declares it and is written, replaced
+  and deleted with it, including on incremental and write-path (`akm
+  remember`) indexing. A target resolves when it is indexed, not when its
+  citer was, so a note that cites something added later links to it without
+  being reindexed. Retired spellings convert in memory (`memory:<name>`,
+  `wiki:<wiki>/<page>`, a `.md` suffix), and, as lint already allows (#882),
+  a memory whose own file is gone resolves to its `.derived` child.
+  `akm show` lists an asset's links grouped by kind: `outgoing`, `incoming`
+  and the `unresolved` tokens it names, at most 10 per kind with a `total`.
+  `akm info` reports links per kind with how many are unresolved. Links do
+  not change search ranking, and `related` is unchanged: on the retrieval
+  suite, against 0.9.17-alpha.7 on the same index with two runs per arm,
+  search nDCG@10 moved +0.002 [−0.005, +0.009] (a rerun of alpha.7 alone
+  moved +0.006) and curate P@5 +0.000 [−0.001, +0.001].
+  On the retrieval snapshot of the maintainer's 21 bundles (23,979 entries)
+  there are 14,917 links: 7,393 `contradicted_by`, 4,401 `xref`, 2,577
+  `derived_from`, 540 `cites` and 6 `superseded_by`. 1,801 are unresolved;
+  1,744 of those are `.derived` memories whose parent memory no longer
+  exists. (`src/indexer/links/declared-links.ts`,
+  `src/storage/repositories/index-links-repository.ts`,
+  `src/commands/read/show.ts`, `src/commands/sources/info.ts`)
+
+### Changed
+
+- **`akm migrate` converts a v2 or v3 task file straight to v4 in one pass.**
+  The chain that read every file as v2, converted it to an intermediate v3
+  shape, then converted that to v4 (`src/tasks/source/task-to-v3.ts` ->
+  `task-to-v4.ts`, composed by `scripts/akm-migrate/migrate/task-files.ts`)
+  is now one planner: `task-to-v4.ts` reads a file once and, for v2, builds
+  the v3-shape record in memory — never written to disk or reported as its
+  own outcome — before hoisting it to v4 through the same code path a real
+  v3 file goes through. `akm migrate status`/`apply` output shapes, and
+  every blocked/changed reason code, are unchanged, checked fixture by
+  fixture against the prior two-hop chain's actual output (one exception:
+  a v3 document that fails only the typed pre-check's own "exactly one
+  scheduling source" rule — unreachable through the real chain, which
+  always ran that same pre-check first — now reports `invalid-v3-task`
+  instead of the raw hoist stage's own `ambiguous-scheduling-source`,
+  matching what `akm migrate apply` already returned end to end). The
+  `already-v3` and `pending-v2-to-v3-migration` intermediate states are
+  gone with the generation split that produced them.
+  `src/tasks/source/task-to-v3.ts` (500 lines) is deleted; its logic moved
+  into `task-to-v4.ts`, which also drops the duplicate raw-YAML reader and
+  outcome-base helpers the two files each carried their own copy of.
+  (`src/tasks/source/task-to-v4.ts`, `scripts/akm-migrate/migrate/task-files.ts`)
+- **Curate's support refs come from declared links.** Each curated item's
+  support refs (at most two) are now assets its declared links name: what
+  it links to, then what links to it, in the order `akm show` lists them,
+  skipping assets curate already selected. They no longer come from the LLM
+  entity graph's `related` list. On the retrieval snapshot, `related` offered
+  support refs for 47 of 867 curate items (5.4%) and declared links for 257
+  (29.6%). The retrieval judge graded 157 of those items, asking whether each
+  support ref is worth opening next: 56% of declared support refs were useful
+  against 68% of `related`'s, so curate attaches about 24 useful support refs
+  per 100 items instead of 7. Curate's items are unchanged.
+  (`src/commands/read/curate.ts`)
+- **Index layout 26.** The first writable open of an older index derives
+  every entry's links from its stored `document_json` in place, reading no
+  file: on the 23,979-entry snapshot index that takes 0.8 s and adds 3.5 MB.
+  Earlier layouts never stored a workflow's or a task's targets, so only the
+  directories holding workflows and tasks re-read on the next `akm index`.
+  The open leaves `index_meta.vacuumPending` like every layout migration.
+  0.9.17-alpha.4 through alpha.7 refuse an index at layout 26
+  (`INDEX_SCHEMA_INCOMPATIBLE`, naming the upgrade), for writing as well as
+  reading, so going back to one of them needs a new index: move `index.db`
+  aside and run `akm index` under that release (the LLM graph and enrichment
+  cache it held are not rebuilt by `akm index`).
+  (`src/storage/repositories/index-schema.ts`,
+  `src/storage/repositories/index-entry-schema.ts`)
+
+### Fixed
+
+- **`index.graph.enabled: false` stops graph extraction in `akm improve`.**
+  The switch was read only when improve had no strategy plan, which is never
+  the case in a real run, so the nightly and weekly graph tasks kept
+  extracting with it set. Improve now skips its graph extraction stage
+  whenever `index.graph.enabled` is `false`, whatever the strategy enables.
+  This also makes the graph ablation harness's "graph off" arm, which sets
+  exactly this key, turn extraction off. Improve still does not read
+  `index.defaults` when it picks the engine for graph extraction.
+  (`src/commands/improve/loop-stages.ts`)
+- **Graph extraction never has more calls in flight than the run's
+  concurrency.** Batches run side by side up to the runner's concurrency, and
+  each batch also sent its per-file calls (long bodies, a non-array response)
+  up to that limit at once, so at a concurrency of 2 four calls could be in
+  flight. A batch now makes its per-file calls one at a time. At the default
+  concurrency of 1 nothing changes. (`src/llm/graph-extract.ts`)
+- **A long document whose extraction partly failed is extracted again.** A
+  body over 1,600 characters is extracted in chunks. When some chunks failed
+  (a timeout, an error, an empty response) and others found entities, the
+  file was recorded and cached as extracted, so the failed chunks were never
+  retried. Such a file is now recorded as failed and not cached, and the next
+  run extracts it again, every chunk: partial failures are rare outside
+  provider outages, and keeping per-chunk results to skip the chunks that
+  succeeded would need a second cache. Until then the entities the other
+  chunks found are stored when the file had no graph rows yet; a file with
+  rows keeps them. (`src/llm/graph-extract.ts`)
+- **`scripts/node-runtime/akm` could die from a raw signal instead of
+  forwarding it to its child.** The launcher registered its
+  SIGTERM/SIGINT/SIGHUP forwarding listeners only after spawning the child;
+  under load, a signal could arrive in that window and fall through to the
+  runtime's default (process-terminating) disposition, killing the launcher
+  before the child ever saw it. The listeners now go up before anything else
+  runs, with a small queue for a signal that arrives before the child exists.
+- **`scripts/node-runtime/akm-migrate` carried the same pre-spawn signal
+  race** as `scripts/node-runtime/akm` above, for the same reason (listeners
+  registered only after `spawn()`), with no test covering it. Fixed the same
+  way, and added `tests/integration/akm-migrate-signal-forwarding.test.ts`
+  (modelled on `launcher-signal-forwarding.test.ts`) for its forwarding.
+- **The launcher signal tests failed intermittently because of their own
+  fixture.** The fake child wrote its ready file before it registered its
+  signal handler, so a forwarded signal could reach it in between and kill it,
+  and the launcher then reported that signal. Each fixture now registers its
+  handler first. The launcher's pre-spawn window above could not cause this:
+  the tests signal only after the child is running.
+
+## [0.9.17-alpha.7] - 2026-09-28
+
+A scheduled task is now just a command and a schedule. Each native row
+carries its own `AKM_BUNDLE_DIR` instead of pointing at a descriptor file,
+and the runtime reads only v4 task files; older files convert once with
+`akm migrate apply`. The first `akm task sync` after upgrading rewrites each
+row once, keeping every task and schedule. `akm improve` reworks only assets
+that retrieval returned or that are new, and reflect refuses a rewrite that
+grades worse on the asset's own searches. `--require-engines` no longer
+skips a run because the LLM endpoint is busy.
+
+### Changed
+
+- **akm reads only task source v4.** A `version: 2` or `version: 3` task
+  file, or a `version: 4` file that still carries 0.9.15's retired
+  `schedule[].enabled`, now fails on its own with a message naming
+  `akm migrate apply`, which converts it once, under a backup (`akm upgrade`
+  runs it after an install). Until now every read converted such a file in
+  memory. `akm task sync` reports each one as a failure, leaves its installed
+  row as it is, and keeps reconciling every other task; `akm task run`,
+  `akm lint` and `akm task validate` report it the same way, and
+  `akm task validate`'s `converts` outcome is gone (such a file is
+  `blocked`). `akm migrate apply` now also converts the tasks of the stash
+  `AKM_BUNDLE_DIR` selects when no configured bundle names it, since the
+  runtime reads those too, and a root whose top-level task files are all
+  v2/v3 is still detected as an `akm-task` bundle, so they are found and
+  converted. A host whose task files are all v4 (`akm migrate status`
+  reports `current`) sees no difference.
+  (`src/tasks/source/parse-task-source.ts`, `src/commands/tasks/validate.ts`,
+  `scripts/akm-migrate/task-migrate.ts`,
+  `src/core/adapter/adapters/akm-task-adapter.ts`)
+- **A scheduled row is its command plus its schedule, and carries its own
+  context.** Rows no longer name a `--scheduler-context` descriptor file;
+  they set what it held themselves. Every row sets `AKM_BUNDLE_DIR` to the
+  working stash of the shell that ran `akm task sync`, plus any
+  `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` or `AKM_STATE_DIR` that
+  shell set explicitly: a `VAR=value` prefix in the crontab, an
+  `EnvironmentVariables` entry in a launchd plist, a `$env:VAR='value';`
+  assignment ahead of the command in Task Scheduler (its action has no
+  environment of its own). Scheduled runs see the same environment as
+  before, and sync still tells installations sharing a crontab apart by
+  that path (#846).
+  **What hosts see:** the first `akm task sync` after upgrading rewrites
+  every akm row once. `akm task sync --dry-run` lists each one as an update,
+  never an add or a remove; each keeps its launcher and its schedule, and
+  the `--scheduler-context <file>` argument becomes an inline
+  `AKM_BUNDLE_DIR=<working stash>`. On a host whose working stash is
+  `/home/u/akm` a row changes from
+
+  ```text
+  30 8 * * * /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm --scheduler-context /home/u/.local/share/akm/tasks/context/e898….json task run capture --bundle akm --scheduled > /home/u/.cache/akm/tasks/logs/capture.log 2>&1
+  ```
+
+  to
+
+  ```text
+  30 8 * * * AKM_BUNDLE_DIR=/home/u/akm /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm task run capture --bundle akm --scheduled > /home/u/.cache/akm/tasks/logs/capture.log 2>&1
+  ```
+
+  Rows written by 0.9.0 through 0.9.17-alpha.6 keep firing until that sync:
+  the CLI still accepts `--scheduler-context <file>` and applies the file's
+  environment (PATH included, for a 0.9.16 row). The files under
+  `$DATA/tasks/context/` are no longer written, and the uid, mode, symlink
+  and content-hash checks made on every scheduled run are gone. A sync
+  leaves some rows as they are (one whose task file failed to load, one a
+  `--bundle` sync did not cover), and those still name their file: once
+  `akm task doctor` lists no binding with a `contextPath`, nothing reads
+  them and they can be deleted. `akm task prune` now
+  finds rows whose `AKM_BUNDLE_DIR` names a directory that is gone, and older
+  rows whose descriptor cannot be read; `akm task doctor` lists `contextPath`
+  only for an older row. (`src/tasks/scheduler-invocation.ts`,
+  `src/tasks/backends/cron.ts`, `src/tasks/backends/launchd.ts`,
+  `src/tasks/backends/schtasks.ts`, `src/tasks/scheduler-sync.ts`,
+  `src/commands/tasks/tasks.ts`)
+- **`akm improve` reworks only what gets read (#986).** An asset with fresh
+  feedback, or one you name (`akm improve skills/x`), is handled as before.
+  Every other pick must now be in the retrieval scope. That covers the
+  proactive-maintenance, high-salience and forgetting-safety lanes, and the
+  memories consolidation judges. An asset is in scope if a user `search`,
+  `curate` or `show` returned it, or user `feedback` named it, in the last 90
+  days, which is the usage log's retention. A hit on a `.derived` memory counts
+  for its parent. New material that no improve stage has processed yet is also
+  in scope. There is no new config key.
+
+  Measured with `akm improve --dry-run` on a copy of the maintainer's bundle
+  (19,870 assets), against 0.9.17-alpha.6:
+  - The fallback lanes pick from 6,450 assets instead of 15,686, and 9,236
+    refs are left out. No lane setting can reach the unread tail any more. In
+    July the proactive lane rewrote 3,069 assets, and 3,059 of them had not
+    been retrieved since the usage log began on 1 July.
+  - Consolidation judges 59 memories instead of 69.
+  - The high-salience lane no longer admits distill outputs nobody has read (2
+    today).
+  - Under the scheduled caps, today's nightly work is unchanged. The default
+    strategy selects the same 50 feedback-driven refs, and weekly proactive
+    maintenance selects the same 25, because salience ranking already puts
+    retrieved assets first.
+
+  `akm improve --dry-run` and the run result report the left-out refs as a new
+  `retrieval` gate. Health reports them under the skip reason `not_retrieved`.
+  Improve results stored by earlier releases, which have no such gate, still
+  decode. (`src/commands/improve/retrieval-scope.ts`,
+  `src/commands/improve/preparation.ts`, `src/commands/improve/consolidate.ts`)
+
+- **Reflect refuses a rewrite that makes an asset worse for its own searches
+  (#722).** Before reflect proposes a rewrite of an existing asset, it grades
+  the old and the new content on up to five of the queries that actually
+  retrieved the asset (user `search` and `curate`). It uses the retrieval
+  eval's relevance prompt, which agrees with human grades at kappa 0.83. When
+  the new content grades lower on average, the rewrite is refused the same way
+  a quality-judge rejection is: `quality_rejected`, with the 14-day reflect
+  window. An asset without retrieval queries is not graded.
+
+  This was measured before it was built. Of 60 accepted rewrites since July,
+  judged this way, 14 graded lower (23%, 95% CI 14–35%) and 12 graded higher.
+  The gate was built because the lower bound cleared the 10% threshold set
+  before any judging. It costs two judge calls per query on the engine that
+  already runs the quality judge. On the maintainer's 2026-09-28 nightly run,
+  whose 30 rewrites had 102 usable queries, that is 204 calls, about 6 more
+  minutes on a 73-minute run. (`src/commands/improve/retrieval-gate.ts`,
+  `src/commands/improve/reflect.ts`)
+
+### Fixed
+
+- **A cron row too long for one line is seen by `akm task sync` again.** A
+  command over 1,000 bytes runs from a wrapper script, and sync could not
+  read which task such a row ran: every sync, and every `--dry-run`, showed
+  it as an add and wrote it again. Sync now reads the script, so the row is
+  unchanged or an update like any other. (`src/tasks/backends/cron.ts`)
+- **A `$` or a backslash in a scheduled row's value is kept.** launchd and
+  Task Scheduler rows passed their values through a string replacement that
+  read `$'`, `$&` and `$$` as patterns, so a path such as a Windows admin
+  share (`\\nas\share\akm$`) came out corrupted; reading a crontab row
+  back dropped a backslash inside a single-quoted value.
+  (`src/tasks/backends/launchd.ts`, `src/tasks/backends/schtasks.ts`,
+  `src/tasks/backends/cron.ts`)
+- **`akm improve --require-engines` no longer skips a run because the LLM
+  endpoint is busy.** Its reachability probe, one short completion, gave up
+  after 3 seconds, so a local server busy with another job looked
+  unreachable and the whole scheduled run failed (all four scheduled runs on
+  2026-09-27). The probe now waits up to the engine's own `timeoutMs`, at
+  most two minutes, so a busy server can answer while a hung one still fails
+  fast. The error's hint now says to check the endpoint rather than to run
+  `akm setup`.
+  (`src/commands/improve/improve-cli.ts`)
+
 ## [0.9.17-alpha.6] - 2026-09-27
 
 Graph extraction stops losing and wasting work. A timed-out extraction is

package/STABILITY.md

@@ -281,8 +281,8 @@ CHANGELOG with a migration note.
   print unredacted. `akm task validate <path>` (new in 0.9.11) is the same
   kind of zero-write introspection as `explain`, but takes a bare filesystem
   path rather than a bundle-qualified ref — it reports whether that ONE file
-  would parse cleanly (`valid`), auto-convert from task v2/v3 (`converts`),
-  need a human decision the deterministic migrator can't make (`blocked`),
+  would parse cleanly (`valid`), need `akm migrate apply` first (`blocked`:
+  task v2/v3, or a retired `schedule[].enabled`),
   fail schema validation (`invalid`), or isn't a task source at all
   (`not-a-task`) — exactly the diagnostic `akm task sync` would produce for
   it, before the file is ever wired into a bundle or the scheduler.

package/dist/akm

@@ -6,13 +6,55 @@
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-// `--scheduler-context <descriptor>` passes through untouched: the CLI loads
-// and validates it before anything else (`consumeSchedulerContextArg` in
-// src/cli.ts). The scheduler supplies PATH itself (the crontab's `# akm:env`
-// line, a launchd plist's EnvironmentVariables), so runtime selection below
-// needs nothing from the descriptor. This launcher used to re-validate the
-// descriptor with its own copy of the schema, and that copy rejected every
-// descriptor the CLI writes since 0.9.17.
+// #956 round 3: install the signal-forwarding scaffolding before ANYTHING
+// else in this process — env var setup, the bun-version probe, spawning the
+// child — gets a chance to run. The three `process.once` listeners used to
+// go up only after spawn() (below) returned; a scheduler preemption right
+// after that syscall was enough for a signal to arrive with no listener yet,
+// and the runtime's default (process-terminating) disposition killed the
+// launcher outright, never reaching the child at all. `child` starts
+// unset: a signal that arrives before it exists is queued and flushed the
+// moment it does; if this process ends up never spawning one (the
+// direct-import branch below), the queued signal is re-raised against
+// ourselves once we hand default disposition back, so it behaves exactly
+// like the runtime's own default rather than being silently swallowed.
+let child;
+let childExited = false;
+const pendingSignals = [];
+const forwardHandlers = new Map();
+const forwardSignal = (signal) => {
+  if (childExited) return;
+  if (!child) {
+    pendingSignals.push(signal);
+    return;
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Child exited in the race between the check above and here.
+  }
+};
+// `.once`, not `.on`: Node/Bun suppress a signal's default
+// (process-terminating) disposition for as long as ANY listener stays
+// registered for it. A persistent `.on` listener would still be registered
+// when the `process.kill(process.pid, result.signal)` re-raise below runs at
+// shutdown, swallowing it and leaving this launcher exiting 0 instead of
+// reflecting the child's signal. `.once` consumes only the
+// externally-delivered signal that triggers the forward, so the re-raise
+// correctly falls through to the OS default.
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  const handler = () => forwardSignal(signal);
+  forwardHandlers.set(signal, handler);
+  process.once(signal, handler);
+}
+
+// A scheduled row sets its environment itself (a cron `VAR=value` prefix, a
+// launchd plist's EnvironmentVariables), and the scheduler supplies PATH, so
+// runtime selection below needs nothing from it. A row written by 0.9.0 –
+// 0.9.17-alpha.6 passes `--scheduler-context <descriptor>` instead; it passes
+// through untouched, and the CLI applies it (`consumeSchedulerContextArg` in
+// src/cli.ts). This launcher used to re-validate the descriptor with its own
+// copy of the schema, and that copy rejected every descriptor 0.9.17 wrote.
 
 process.env.AKM_LAUNCHER_NODE = process.execPath;
 process.env.AKM_LAUNCHER_PATH = fileURLToPath(import.meta.url);
@@ -42,13 +84,21 @@ const bunEntry = fileURLToPath(new URL("./cli.js", import.meta.url));
 const nodeEntry = fileURLToPath(new URL("./cli-node.mjs", import.meta.url));
 
 if (!useBun && !process.versions.bun) {
-  await import("./cli-node.mjs");
+  // No child is ever spawned on this path — the imported module runs
+  // in-process, so it IS the work, and the runtime's ordinary default signal
+  // disposition is exactly correct for it. Hand that back (the forwarding
+  // listeners above no longer apply here), re-raising anything that already
+  // arrived so it is not silently swallowed by a listener that now does
+  // nothing.
+  for (const [signal, handler] of forwardHandlers) process.removeListener(signal, handler);
+  if (pendingSignals.length > 0) process.kill(process.pid, pendingSignals[0]);
+  else await import("./cli-node.mjs");
 } else {
   const command = useBun ? (process.versions.bun ? process.execPath : "bun") : "node";
   const entry = useBun ? bunEntry : nodeEntry;
   const runtime = useBun ? "Bun" : "Node.js";
   const result = await new Promise((resolve) => {
-    const child = spawn(command, [entry, ...process.argv.slice(2)], {
+    child = spawn(command, [entry, ...process.argv.slice(2)], {
       stdio: "inherit",
       env: process.env,
       // #956: give the child its OWN process group on POSIX (`setsid()` —
@@ -75,29 +125,12 @@ if (!useBun && !process.versions.bun) {
     // forward once the child has already exited: forwarding to a
     // dead/replaced pid would be at best a no-op and at worst a signal to
     // an unrelated process that reused the pid.
-    let childExited = false;
     child.once("exit", () => {
       childExited = true;
     });
-    const forwardSignal = (signal) => {
-      if (childExited) return;
-      try {
-        child.kill(signal);
-      } catch {
-        // Child exited in the race between the check above and here.
-      }
-    };
-    // `.once`, not `.on`: Node/Bun suppress a signal's default
-    // (process-terminating) disposition for as long as ANY listener stays
-    // registered for it. A persistent `.on` listener would still be
-    // registered when the `process.kill(process.pid, result.signal)`
-    // re-raise below runs at shutdown, swallowing it and leaving this
-    // launcher exiting 0 instead of reflecting the child's signal. `.once`
-    // consumes only the externally-delivered signal that triggers the
-    // forward, so the re-raise correctly falls through to the OS default.
-    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-      process.once(signal, () => forwardSignal(signal));
-    }
+    // Flush whatever arrived in the (now much smaller) window between the
+    // listeners going up and the child existing to receive them.
+    for (const signal of pendingSignals.splice(0)) forwardSignal(signal);
     child.once("error", (error) => resolve({ error }));
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });

package/dist/akm-migrate

@@ -6,6 +6,40 @@
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+// #956 round 3: install the signal-forwarding scaffolding before ANYTHING
+// else in this process — the Node-version check, the bun-version probe,
+// spawning the child — gets a chance to run. See the matching fix and
+// comment in scripts/node-runtime/akm: the three `process.once` listeners
+// used to go up only after spawn() (below) returned; a scheduler preemption
+// right after that syscall was enough for a signal to arrive with no
+// listener yet, and the runtime's default (process-terminating) disposition
+// killed the launcher outright, never reaching the child at all. `child`
+// starts unset: a signal that arrives before it exists is queued and
+// flushed the moment it does.
+let child;
+let childExited = false;
+const pendingSignals = [];
+const forwardSignal = (signal) => {
+  if (childExited) return;
+  if (!child) {
+    pendingSignals.push(signal);
+    return;
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Child exited in the race between the check above and here.
+  }
+};
+// `.once`, not `.on`: see the matching comment in scripts/node-runtime/akm —
+// a persistent `.on` listener would still be registered when the
+// `process.kill(process.pid, result.signal)` re-raise below runs,
+// suppressing the OS default disposition and leaving this launcher exiting
+// 0 instead of reflecting the child's signal.
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  process.once(signal, () => forwardSignal(signal));
+}
+
 if (!process.versions.bun) {
   const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
   if (major < 22) {
@@ -34,7 +68,7 @@ const nodeEntry = fileURLToPath(new URL("./scripts/akm-migrate-node.js", import.
   const command = process.versions.bun ? process.execPath : useBun ? "bun" : process.execPath;
   const entry = process.versions.bun || useBun ? bunEntry : nodeEntry;
   const result = await new Promise((resolve) => {
-    const child = spawn(command, [entry, ...process.argv.slice(2)], {
+    child = spawn(command, [entry, ...process.argv.slice(2)], {
       stdio: "inherit",
       env,
       // #956: own process group on POSIX so the launcher's forward below is
@@ -43,27 +77,12 @@ const nodeEntry = fileURLToPath(new URL("./scripts/akm-migrate-node.js", import.
       // directly — see the matching comment in scripts/node-runtime/akm.
       detached: process.platform !== "win32",
     });
-    let childExited = false;
     child.once("exit", () => {
       childExited = true;
     });
-    const forwardSignal = (signal) => {
-      if (childExited) return;
-      try {
-        child.kill(signal);
-      } catch {
-        // Child exited in the race between the check above and here.
-      }
-    };
-    // `.once`, not `.on`: see the matching comment in
-    // scripts/node-runtime/akm — a persistent `.on` listener would still be
-    // registered when the `process.kill(process.pid, result.signal)`
-    // re-raise below runs, suppressing the OS default disposition and
-    // leaving this launcher exiting 0 instead of reflecting the child's
-    // signal.
-    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-      process.once(signal, () => forwardSignal(signal));
-    }
+    // Flush whatever arrived in the (now much smaller) window between the
+    // listeners going up and the child existing to receive them.
+    for (const signal of pendingSignals.splice(0)) forwardSignal(signal);
     child.once("error", (error) => resolve({ error }));
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });

package/dist/assets/prompts/retrieval-relevance-judge.md

@@ -0,0 +1,6 @@
+You are grading search-and-retrieval results for an AI coding agent's knowledge base (the akm tool). For the given query and ONE candidate asset, grade how useful loading this asset would be, on this scale:
+3 = exactly the asset an agent should load for this query or task; it directly answers or performs the request.
+2 = relevant and clearly useful, though not the single best asset for the query.
+1 = same general topic as the query, but would not actually help complete this specific query or task.
+0 = unrelated to the query.
+Reply with ONLY a JSON object: {"grade": <integer 0-3>, "reason": "<=25 words"}.

package/dist/assets/stash-skeleton/facts/conventions/backlinks.md

@@ -3,7 +3,7 @@ type: fact
 category: convention
 description: How to cross-link assets so retrieval compounds — a provenance xref when derived, sparse real associative xrefs, corrections as new assets, and canonical entity naming.
 when_to_use: Surfaced to authoring agents when they create or revise any asset that derives from, corrects, or relates to another asset.
-updated: 2026-07-28
+updated: 2026-09-28
 ---
 
 <!--
@@ -19,8 +19,10 @@ updated: 2026-07-28
 
 Cross-references are how knowledge compounds instead of being re-derived every
 session. In AKM they are also **indexed**: the strings in an asset's `xrefs:`
-frontmatter fold into its search-hint text, and knowledge/memory bodies feed an
-LLM-extracted entity/relation graph that boosts ranking. So links are a retrieval
+frontmatter fold into its search-hint text and are stored as links that
+`akm show` lists on both assets (with `supersededBy:`, `contradictedBy:` and a
+`.derived` memory's parent), and knowledge/memory bodies feed an LLM-extracted
+entity/relation graph that boosts ranking. So links are a retrieval
 lever — which means both too few and too many hurt.
 
 ```yaml

package/dist/commands/improve/consolidate.js

@@ -26,6 +26,7 @@ import { warn, warnVerbose } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
 import { assertRunnerCredentials } from "../../integrations/agent/runner-dispatch.js";
 import { cosineSimilarity, embedBatch, resolveEmbeddingModelId } from "../../llm/embedder.js";
 import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../storage/repositories/embeddings-repository.js";
@@ -39,6 +40,7 @@ import { sanitizeMergedContent } from "./consolidate/sanitize.js";
 import { contentHash } from "./content-hash.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { isLedgerBlocked, ledgerKey, loadLedgerSnapshot, recordLedgerAttempt } from "./ledger.js";
+import { isInRetrievalScope, loadRetrievalScope } from "./retrieval-scope.js";
 import { callStage, mintProposal, noticeSet, stageRunner } from "./stage.js";
 /** A plan op worth acting on. Retired advisory ops (merge/delete/contradict) are dropped, never thrown on. */
 export function isValidOp(op) {
@@ -428,6 +430,11 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
         });
     }
     const judgedUnchanged = poolSize - memories.length;
+    // Only what retrieval returned or new material improve never processed (#986).
+    const retrievalScope = loadRetrievalScope({ proposalsCtx: opts.proposalsCtx, readOnly }, stashDir);
+    const beforeScope = memories.length;
+    memories = memories.filter((memory) => isInRetrievalScope(retrievalScope, conceptIdFromTypeName("memory", memory.name), memory.filePath));
+    const outsideRetrievalScope = beforeScope - memories.length;
     if (opts.incrementalSince && memories.length > 0) {
         memories = narrowToIncrementalCandidates(memories, opts.incrementalSince, warnings, opts.neighborsPerChanged, readOnly);
     }
@@ -465,6 +472,7 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
         memories,
         prefilteredAlreadyPromoted,
         judgedUnchanged,
+        outsideRetrievalScope,
     };
 }
 const ABORT_MIN_CHUNKS = 4;
@@ -641,6 +649,9 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
     if (pool.judgedUnchanged > 0) {
         warnings.push(`Consolidation: skipped ${pool.judgedUnchanged} ${plural(pool.judgedUnchanged)} judged within the revisit window and unchanged since.`);
     }
+    if (pool.outsideRetrievalScope > 0) {
+        warnings.push(`Consolidation: skipped ${pool.outsideRetrievalScope} ${plural(pool.outsideRetrievalScope)} already judged that retrieval has not returned in the last ${USAGE_EVENT_RETENTION_DAYS} days.`);
+    }
     if (prefilteredAlreadyPromoted > 0) {
         warnings.push(`Consolidation: pre-filtered ${prefilteredAlreadyPromoted} ${plural(prefilteredAlreadyPromoted)} whose body already exists verbatim in knowledge/ before chunking.`);
     }