akm-cli 0.9.17-alpha.5 → 0.9.17-alpha.7

package/CHANGELOG.md

@@ -6,6 +6,287 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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
+retried instead of cached as empty. Long documents are extracted once, and
+per-file calls respect the run's concurrency. `akm improve` honors
+`index.graph`. `akm curate` returns nothing for harness and tool envelopes,
+and search and curate show identical content once. Lazy graph extraction,
+which never ran under Bun, is removed.
+
+### Changed
+
+- **`akm curate` returns nothing, on purpose, for input that is not a task.**
+  A harness or tool envelope (input that starts with an XML-style tag and
+  contains a closing tag, such as `<task-notification>…</task-notification>`,
+  `<system-reminder>…` or `<cross-session-message …>…`) and the stash README
+  line each used to get `--limit` unrelated assets. Every caller of
+  `akm curate` (the CLI, the OpenCode plugin, other harnesses) now gets an
+  empty `items` list with a `summary` that starts with `Curate abstained` and
+  names the reason, and a `tip`. On the retrieval suite curate abstains on 57
+  of 60 recorded non-task inputs and on none of the 221 real queries (nor on
+  any of 5,725 mined task queries). Length is not a reason to abstain: the
+  other 3 are task prompts of 2,431–5,531 characters, and in a judged sample
+  of 30 inputs over 2,000 characters the top 5 held a relevant asset for 24
+  of them (P@5 0.42, against 0.46 for prompts of 400–2,000 characters).
+  (`src/commands/read/curate.ts`)
+- **Search and curate return identical content once.** Of entries whose
+  indexed content is identical (the same body saved under another name, as
+  both a memory and a knowledge doc, or in another bundle), only the
+  highest-ranked is kept, and the next candidate takes the freed slot. On the
+  retrieval suite such copies filled 7.5% of curate's top 5. Unique
+  precision@5, where a copy of a higher-ranked result earns nothing, rises
+  from 0.467 to 0.514 (+0.046, 95% CI [+0.028, +0.067]), and the share of
+  top-5 slots that repeat a higher-ranked result falls from 0.131 to 0.055.
+  Plain P@5 (0.553 → 0.551) and nDCG@10 stay within noise: they counted each
+  copy as another relevant result. Latency is unchanged.
+  (`src/indexer/search/db-search.ts`)
+
+### Removed
+
+- **The unused `utility_scores_scoped` index table is gone.** It shipped in
+  0.9.17-alpha.5 for per-project scoped utility scores, but no code ever read
+  or wrote a row. An index database drops it on its next writable open, the
+  same way other retired derived tables are dropped, with no layout-version
+  change. (`src/storage/repositories/index-schema.ts`)
+- **Lazy graph extraction in `akm show` and `akm curate`.** With
+  `index.graph.lazyGraphExtraction: true`, `show` extracted an asset's graph
+  after building its response, so only the next `show` saw it. `curate`
+  queued assets for a later pass, which drained only the working bundle's
+  queue, and extractions made this way wrote no cache entry. Under Bun neither
+  path ever ran: the "already has a graph" check read a missing row as
+  present. Graph extraction now runs only in `akm improve`. The
+  `graph_extraction_queue` table is dropped the next time the index is opened
+  for writing. A config that still sets the key loads, and the key is named
+  once as unknown. (`src/commands/read/show.ts`,
+  `src/commands/read/curate.ts`, `src/indexer/graph/graph-extraction.ts`,
+  `src/storage/repositories/index-schema.ts`)
+
+### Fixed
+
+- **`index.metadataEnhance`'s default is no longer contradicted by dead
+  code.** Metadata enhancement has always defaulted to off
+  (`isLlmFeatureEnabled`); a second, unreachable code path in
+  `isProcessEnabled` claimed the opposite default and had no caller. Removed,
+  so one default remains. (`src/llm/feature-gate.ts`)
+- **Eval tooling and docs catch up to the current config and index shape.**
+  `scripts/akm-eval/src/curate-bench.ts` wrote the retired `sources` config
+  key and called a nonexistent `akm index --dir`; it now seeds its sandbox
+  the same way the other akm-eval scripts and integration tests do, and
+  drops `--dir`. The graph A/B ablation harness
+  (`scripts/akm-eval/src/graph-ablation.ts`) planted its "graph off" config
+  where the sandboxed `akm` never read it, with config keys that didn't gate
+  anything (one of them a type error); it now writes
+  `index.graph.enabled: false` to the sandbox's actual `AKM_CONFIG_DIR`.
+  Updated `scripts/akm-eval/README.md` and `docs/maintainers/eval.md` to
+  match, and corrected stale `docs/architecture/architecture.md` references
+  to `db-backup`, `staleness-detect`, and `src/commands/graph/`.
+- **Scheduled graph extraction reads `index.graph`.** `akm improve` passed
+  graph extraction a batch size of 4 and the `memory` and `knowledge` types
+  whenever the strategy's `processes.graphExtraction` did not set them, so
+  `index.graph.graphExtractionBatchSize` and `graphExtractionIncludeTypes`
+  never applied. It did not read `index.graph`'s `engine`, `model`,
+  `timeoutMs` or `llm` either, so a setting such as
+  `index.graph.llm.enableThinking: false` had no effect on improve runs. A
+  value in the strategy's `processes.graphExtraction` still wins. A setting it
+  leaves unset now comes from `index.graph`, then from the built-in default.
+  Where `index.graph` asks for something improve did not use before, the
+  extractor changes and cached extractions stop applying, so those files are
+  extracted again. (`src/commands/improve/loop-stages.ts`,
+  `src/commands/improve/execution.ts`,
+  `src/commands/improve/improve-strategies.ts`)
+- **A graph extraction that times out is retried, not cached as empty.** A
+  call that ran past the engine's `timeoutMs` was recorded as "no entities"
+  and cached, so the file was never extracted again. It is now recorded as
+  failed, and the next run retries it; timeouts also count toward the run's
+  failure-rate abort. A batch that times out fails its files without then
+  calling the model once per file. An empty response is likewise recorded as
+  failed. (`src/llm/graph-extract.ts`)
+- **Long bodies are extracted once after batching turns itself off.** Two
+  non-array batch responses turn batching off for the rest of a run. From
+  then on, a body over 1,600 characters was extracted on its own and then
+  again with the rest of its batch. Each body is now extracted once.
+  (`src/llm/graph-extract.ts`)
+- **A batch's per-file calls respect the run's concurrency.** When a batch
+  fell back to one call per file (long bodies, a non-array response, batching
+  turned off), those calls all went out at once, up to the batch size. Local
+  endpoints serve one or two requests at a time. The calls now run within the
+  limit the run applies to its batches, one at a time by default.
+  (`src/llm/graph-extract.ts`)
+- **`related` counts a shared entity once.** `akm show`'s `related` list,
+  and curate's support refs taken from it, ranked files by the number of
+  matching entity rows. A file holding two case forms of one entity, as rows
+  from older extractors can, counted it twice and could outrank a file that
+  shared two entities. `related` now counts distinct entities. Extraction also
+  keeps one form of each entity before writing. The stored key `related`
+  matches on is now the one extraction deduplicates on, which also drops
+  surrounding quotes and backticks.
+  (`src/indexer/graph/graph-related.ts`,
+  `src/indexer/graph/graph-extraction.ts`, `src/indexer/db/graph-db.ts`)
+- **A config change that re-extracts the graph says so.** Cached graph
+  extractions are keyed by extractor: model, batch size, included asset types
+  and prompt version. Changing any of them made every cached file extract
+  again without a word. The first run after such a change now warns once,
+  naming the change and the number of cached files it will extract again, and
+  records the warning in the run's result.
+  (`src/indexer/graph/graph-extraction.ts`)
+- **Graph extraction reports what its parser filtered.** A run's graph
+  telemetry, part of `akm improve`'s result, now carries
+  `filteredGenericEntities`, `filteredInvalidRelations`,
+  `filteredLowConfidenceRelations` and `contextBatchRetries`. The pass
+  computed them and dropped them, and did not count batch responses at all.
+  (`src/indexer/graph/graph-extraction.ts`, `src/llm/graph-extract.ts`)
+- **An unknown key under `index.<pass>` is kept and named once.** It was
+  dropped from the loaded config and named twice. It is now handled like an
+  unknown key anywhere else in config. (`src/core/config/schema/index-config.ts`)
+
 ## [0.9.17-alpha.5] - 2026-09-27
 
 `akm show` works again for a memory that has a `.derived.md` child (835 of them

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,13 @@
 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.
+// 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);

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/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.`);
     }

package/dist/commands/improve/execution.js

@@ -20,19 +20,19 @@ function mergeDefaults(farther, nearer) {
     return deepMergeConfig(farther, nearer);
 }
 /**
- * Resolve improve-owned model work through the canonical execution cascade.
- * The legacy improve precedence is preserved exactly:
- * defaults.llmEngine -> strategy -> process -> current invocation.
+ * Resolve improve-owned model work through the canonical execution cascade:
+ * defaults.llmEngine -> strategy -> index.<pass> -> process -> current invocation.
  */
 export function resolveImproveExecution(options) {
     const defaultEngine = options.config.defaults?.llmEngine;
     const profileDefaults = cascadeDefaults(options.profile);
+    const indexDefaults = cascadeDefaults(options.index);
     const processDefaults = cascadeDefaults(options.process);
     const currentDefaults = cascadeDefaults(options.current);
-    const selectedEngine = currentDefaults.engine ?? processDefaults.engine ?? profileDefaults.engine ?? defaultEngine;
+    const selectedEngine = currentDefaults.engine ?? processDefaults.engine ?? indexDefaults.engine ?? profileDefaults.engine ?? defaultEngine;
     if (selectedEngine === undefined || selectedEngine === null)
         return null;
-    const invocationDefaults = mergeDefaults(defaultEngine ? { engine: defaultEngine } : {}, profileDefaults);
+    const invocationDefaults = mergeDefaults(mergeDefaults(defaultEngine ? { engine: defaultEngine } : {}, profileDefaults), indexDefaults);
     const current = mergeDefaults(processDefaults, currentDefaults);
     const prepared = resolveExecution({
         content: `improve ${options.processName} execution selection`,

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

@@ -14,6 +14,7 @@ import { getCacheDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
@@ -77,25 +78,44 @@ function collectRequiredEngineTargets(plan) {
     const targets = [];
     for (const [processName, process] of Object.entries(plan.processes)) {
         if (process.runner) {
-            targets.push({ process: processName, engine: process.runner.engine, connection: process.runner.connection });
+            targets.push({
+                process: processName,
+                engine: process.runner.engine,
+                connection: probeConnection(process.runner),
+            });
         }
     }
     if (plan.triageJudgment?.kind === "llm") {
         targets.push({
             process: "triage.judgment",
             engine: plan.triageJudgment.engine,
-            connection: plan.triageJudgment.connection,
+            connection: probeConnection(plan.triageJudgment),
         });
     }
     return targets;
 }
+/** The resolved engine keeps its request timeout beside the connection (the runtime merges it in); the probe needs it on the connection. */
+function probeConnection(runner) {
+    return runner.timeoutMs !== undefined ? { ...runner.connection, timeoutMs: runner.timeoutMs } : runner.connection;
+}
+/**
+ * The bound on `--require-engines`' probe: the connection's own request
+ * timeout, at most two minutes. A local server busy with another job queues
+ * the probe behind that job, and a fixed 3s bound failed every scheduled
+ * improve run on 2026-09-27 against a reachable endpoint; the cap still ends a
+ * hung endpoint (#957) long before a run's own multi-minute calls would.
+ */
+export function requiredEngineProbeTimeoutMs(connection) {
+    return Math.min(connection.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS, REQUIRED_ENGINE_PROBE_MAX_MS);
+}
+const REQUIRED_ENGINE_PROBE_MAX_MS = 120_000;
 /**
  * `--require-engines`, live: probe each connection's real completion path
- * (a gateway can list a model whose completion route is dead, #980) with a 3s
- * bound, once per endpoint + model. Returns each target's latency for the run
- * result (R17); an unreachable one fails the run.
+ * (a gateway can list a model whose completion route is dead, #980), once per
+ * endpoint + model, within {@link requiredEngineProbeTimeoutMs}. Returns each
+ * target's latency for the run result (R17); an unreachable one fails the run.
  */
-export async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, 3_000)) {
+export async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, requiredEngineProbeTimeoutMs(connection))) {
     const targets = collectRequiredEngineTargets(plan);
     if (targets.length === 0)
         return [];
@@ -117,7 +137,7 @@ export async function assertRequiredEnginesReachable(plan, probeReachable = (con
     const unreachable = probed.filter((item) => !item.reach.reachable);
     if (unreachable.length > 0) {
         const lines = unreachable.map((item) => `  - ${item.process} (engine "${item.engine}", ${item.connection.endpoint}): ${item.reach.error ?? "did not respond"}`);
-        throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
+        throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED", "Check that each listed endpoint is up and serves its model. The probe is one short completion, bounded by the engine's timeoutMs (at most two minutes).");
     }
     return probed.map((item) => ({
         process: item.process,

package/dist/commands/improve/improve-strategies.js

@@ -10,6 +10,7 @@ import quick from "../../assets/improve-strategies/quick.json" with { type: "jso
 import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
 import thorough from "../../assets/improve-strategies/thorough.json" with { type: "json" };
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { getIndexPassConfig, } from "../../core/config/config.js";
 import { ImproveProfileConfigSchema } from "../../core/config/config-schema.js";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES, } from "../../core/config/engine-semantics.js";
@@ -211,6 +212,8 @@ function buildImprovePlan(strategy, config, options) {
                 profile: strategy.config,
                 process: sourceProcessConfig,
                 processName,
+                // Graph extraction's standing engine, model, timeout and llm settings (GR-D15).
+                ...(processName === "graphExtraction" ? { index: getIndexPassConfig(config.index, "graph") } : {}),
             });
             runner = resolved?.runner ?? null;
             notices = resolved?.notices ?? [];

package/dist/commands/improve/ledger.js

@@ -82,13 +82,17 @@ export function recordLedgerAttempt(access, inputs) {
 export function ledgerKey(source, ref) {
     return `${source}\0${ref}`;
 }
+/** Read state.db through `fn` without creating it: `undefined` when there is none yet. */
+export function readLedgerDb(access, fn) {
+    if (!access?.eventsCtx?.db && !fs.existsSync(ledgerDbPath(access) ?? getStateDbPath()))
+        return undefined;
+    return withLedgerDb(access, fn);
+}
 /** Every ledger row for `sources` in one query; no state.db yet means nothing was attempted. */
 export function loadLedgerSnapshot(access, stashDir, sources) {
     const out = new Map();
-    if (!access?.eventsCtx?.db && !fs.existsSync(ledgerDbPath(access) ?? getStateDbPath()))
-        return out;
     try {
-        withLedgerDb(access, (db) => {
+        readLedgerDb(access, (db) => {
             for (const row of listImproveLedgerRows(db, stashDir, sources))
                 out.set(ledgerKey(row.source, row.ref), row);
         });

package/dist/commands/improve/loop-stages.js

@@ -6,14 +6,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { daysToMs } from "../../core/common.js";
-import { DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE, loadConfig, } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { openLogsDatabase, purgeOldTaskLogs } from "../../core/logs-db.js";
 import { getDbPath, getTaskLogDir } from "../../core/paths.js";
 import { withStateDb } from "../../core/state-db.js";
 import { info } from "../../core/warn.js";
-import { DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES, runGraphExtractionPass, } from "../../indexer/graph/graph-extraction.js";
+import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveWritableBundleIds } from "../../indexer/installations.js";
 import { collectPendingMemories, runMemoryInferencePass, } from "../../indexer/passes/memory-inference.js";
@@ -514,8 +514,9 @@ export async function runGraphExtractionMaintenancePass(ctx, dbCell, args) {
             },
             options: {
                 candidatePaths,
-                includeTypes: settings?.includeTypes ?? [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES],
-                batchSize: settings?.batchSize ?? DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE,
+                // Only what the strategy sets: the pass falls back to index.graph, then its defaults (GR-D15).
+                ...(settings?.includeTypes ? { includeTypes: settings.includeTypes } : {}),
+                ...(settings?.batchSize != null ? { batchSize: settings.batchSize } : {}),
                 ...(settings?.topN != null ? { topN: settings.topN } : {}),
                 ...(settings?.maxChunksPerAsset != null ? { maxChunksPerAsset: settings.maxChunksPerAsset } : {}),
             },