akm-cli 0.9.7 → 0.9.8-beta.1

package/CHANGELOG.md

@@ -4,6 +4,224 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.8-beta.1] - 2026-09-01
+
+A cleanup and stabilization release: deletion of machinery that policed the
+codebase's shape rather than its behaviour, and — because auditing for that
+machinery meant reading the code closely — a run of real defects it had been
+sitting on top of.
+
+Two security holes, two search-correctness bugs, a locale-dependent hash, a
+deletion shield that failed open, and sixteen places that answered a failure
+with a confident wrong answer instead of an error.
+
+### Fixed
+
+- **Historical state migrations are reachable where akm cannot reinstall
+  itself** (#895). A migration flagged `historical-destructive` is refused
+  during an ordinary open — it needs a verified safety copy, taken under the
+  migration writer lock, so an unattended `akm index` can never quietly drop
+  operator state. That guard is correct and unchanged. Its *remedy* was not:
+  the only code path that admitted the migration ran as a post-install step of
+  `akm upgrade`, behind an npm install. Where akm is installed globally by a
+  container image and the runtime user is unprivileged, that install fails
+  `EACCES` and throws long before the migration is reached, so `akm index
+  --full` was blocked with no supported way out — and the two obvious
+  workarounds are both wrong (upgrading as root installs a *newer* akm than the
+  image ships, which `config-version-shim` then fails closed against; deleting
+  `state.db` destroys task history, proposals, and lessons metadata, none of
+  which is derived). New `akm upgrade --state-only` applies pending state
+  migrations and installs nothing. Nothing about the migration needed the
+  network, root, or a new binary; coupling it to one was the bug. The safety
+  copy is still taken — this changes who may request the migration, not what it
+  does.
+
+- **Two security holes closed.** A failed `git ls-remote` made
+  `verifyClonedRevision` a no-op, silently skipping the R-011 post-clone
+  revision-integrity check — the guard against a compromised mirror — so any
+  network blip disabled it without a word. And `scanExtractedFiles`, the
+  post-extraction TOCTOU path-traversal rescan, returned silently when a
+  directory could not be read: it passed clean in exactly the race it exists
+  to catch. Both now fail loudly.
+
+- **`akm curate --type` ignored the type filter.** A set `--type` bypassed
+  `selectCuratedStashHits` entirely and did a raw slice of the hits as
+  received, which neither filtered by type nor ranked by score — so
+  `--type command` could return a skill, in arbitrary order. It now narrows
+  the candidate pool and runs the full curation pipeline over it. The test
+  that should have caught this passed by accident, because the off-type hit
+  happened to sit past the result limit.
+
+- **Curate silently dropped relevant results.** An undocumented floor excluded
+  any hit scoring below `max(0.35, leader * 0.7)`. Measured against a real
+  3,265-memory bundle, one query went from one result to four once it was
+  removed — the suppressed hits were the ones actually matching. Ordering is
+  unchanged: results were already sorted before the floor ran, so it could
+  only ever hide the tail.
+
+- **A bundle-audit hash depended on the machine's locale.** `canonicalJson`
+  in `installed-stashes.ts` sorted keys with `localeCompare` — ICU-dependent —
+  and fed the result to `sha256Hex`, so the same object could hash differently
+  on two machines. Now codepoint order, matching the other implementations.
+
+- **A deletion shield failed open.** `isHotCapturedMemory` returned false when
+  it could not read or parse a memory, marking exactly the memories it failed
+  to inspect as fair game for consolidate to merge or delete. It now fails
+  closed.
+
+- **Sixteen places returned a confident wrong answer instead of an error.**
+  The pattern (#791) recurred across search, graph, indexing, and scheduling:
+  a corrupt or locked index reported "no matches"; a failed inline rebuild
+  surfaced as "Index is empty. Run 'akm index'" at exit 0; `akm show` reported
+  "0 related files" for an unreadable index; a DB failure in
+  `listProposalsReadOnly` returned `[]`, so dedup could not tell "no prior
+  proposal" from "database unreadable" and could re-mint an already-rejected
+  one; a permission fault on the bundle directory told the user to run
+  `akm bundle create`; and `launchd`'s `list()` returned `[]` when the
+  LaunchAgents directory could not be read, so task reconciliation concluded
+  there was nothing to manage. In each case the failure now surfaces.
+
+- **Drifted copies of shared helpers.** `asNonEmptyString` trimmed in two
+  places and not in four others, so a whitespace-only session id decoded to
+  `" "` in some subsystems and `undefined` in others. `isPlainObject` had two
+  incompatible definitions under one name; the loose form would accept a
+  `Date` or class instance as a plain record. Both consolidated, along with
+  `toPosix` (15 copies, whose "avoid an import cycle" justification was false
+  in every case), `isRecord` (11), `compareCodePoints` (8), and five more
+  families.
+
+- **Pruning a memory no longer leaves dangling belief edges (#885).**
+  `writeContradictEdge` — the hardened, test-covered `contradictedBy` writer —
+  had no production caller; its docstring named three that did not exist. The
+  live pass used a private near-copy that had drifted on exactly the two
+  behaviours the original was hardened for: it read the key with
+  `Array.isArray` only, so a SCALAR edge (live data the indexer accepts and
+  lint never flags) read as "no edges" and was overwritten out of existence;
+  and it set `beliefState: "contradicted"` unconditionally, promoting an
+  `archived` memory back up the ranking. The tests for both behaviours were
+  guarding dead code. The copy is gone.
+
+  `persistBeliefStateTransition` is deliberately NOT routed through the shared
+  primitive: it is a state-transition writer that replaces the edge list
+  wholesale and can clear it, which an append-only, never-weaken primitive
+  cannot express.
+
+- **`git worktree` operations no longer fail on a busy machine (#891).** The
+  module's internal `GIT_TIMEOUT_MS` was a flat 30s with no margin, so a
+  healthy `git worktree remove` on a loaded host returned
+  `{ removed: false, error: "timed out after 30000ms" }`. Anyone running a
+  workflow with `isolation: worktree` alongside other git activity could hit
+  spurious create failures, or have a clean worktree wrongly retained as
+  unremovable. Raised to 120s, matching the existing `GIT_PUSH_TIMEOUT_MS`
+  precedent. Note `scripts/test-integration.sh` had already raised *bun's*
+  per-test timeout for this reason, but that never touched the production
+  subprocess timeout, which fires first.
+
+- **`akm health`'s dead-link check no longer reports an unearned all-clear
+  (#892).** `checkDeadUrls` capped at 20 URLs across the whole bundle, plus an
+  undocumented `slice(0, 3)` per entry, then the caller logged "URL check
+  complete (0 dead)". A bundle with thousands of links got a clean bill of
+  health after twenty were examined. Both caps removed; every URL is checked
+  and a failed request surfaces instead of being swallowed.
+
+- **`akm lint --fix` no longer breaks on gitignored drafts (#887).** The doc
+  linter walked `docs/` with no gitignore awareness, so unpublished drafts
+  under `docs/.pending/` were held to the published-docs contract —
+  `bun run lint` failed locally while CI, which never has those files, stayed
+  green.
+
+### Changed
+
+- **Search no longer truncates long queries (#892).** `MAX_LEXICAL_QUERY_TOKENS
+  = 16` silently dropped every token past the sixteenth, and tokens are
+  collected in order, so the discarded half was the tail — for
+  natural-language input, usually where the discriminating words are. It also
+  fed ranking, so token-overlap scoring ran on the truncated set too. It was
+  unexplained in the code and in the commit that introduced it, and unreachable
+  from any flag, config key, or environment variable. Removed: the planner
+  handles 10,000 tokens in 9ms, so no performance cliff was being protected.
+
+- **Content and memory bodies are no longer silently truncated.**
+  `MAX_CONTENT_CHARS` (100k, duplicated across 8 adapters) cut indexed content
+  so the tail of a long document was unsearchable; `MAX_BODY_CHARS` (4000) cut
+  the text sent for memory inference, so on a large-context engine the model
+  saw a fraction of the input while the derived memory looked complete. Both
+  removed.
+
+- **GitHub Actions are pinned to commit SHAs (#768).** All 29 `uses:` steps
+  across every workflow, with the tag preserved in a trailing comment.
+
+- **Gated CI runs on schedule, dispatch, and candidate tags only.** The
+  `detect-changes` job that selected suites by regex-matching a PR diff is
+  gone — its path patterns had gone stale and still named test files this
+  release moved or deleted, so it was silently under-selecting suites. Release
+  evidence is unchanged; the checklist always required an exact-SHA dispatch.
+
+- **`akm-eval` in CI is now a determinism check only.** Its score gates are
+  removed. Measured before cutting: the baseline scored a perfect 1.0 against
+  a 0.75 gate, and seven of nine case types never ran — CI has no LLM and no
+  run history, so everything the eval exists to measure was skipped while the
+  job reported green. The harness itself is unchanged and remains a genuine
+  quality signal when run against a real bundle.
+
+### Removed
+
+- **`akm health --clean-dead-residue` and every other compensating shim.**
+  A special-purpose flag on `health` that deleted files existed because
+  migrations had not finished their own job. Removing a superseded layout IS
+  migration, so `akm migrate status` now reports it and `akm migrate apply`
+  removes it. Four more of the same class went the same way: the D8
+  `task_history` vocabulary is rewritten once by a state migration instead of
+  re-decided at three read sites; the legacy `extraParams` config lift happens
+  once in `migrate apply` instead of silently on every load forever (an
+  unmigrated config now fails closed, naming the command to run); retired
+  `type:slug` xrefs are rewritten by `lint --fix`; and stale transaction
+  journals are recovered by `migrate apply` rather than reported by an
+  advisory that pointed at documentation while the recovery function it needed
+  sat with zero callers.
+
+- **Dead code with no consumers.** An empty `{}` type threaded through two
+  functions as a parameter neither read, with a `{}` placeholder at the call
+  site; unused helpers, imports, and parameters throughout.
+
+- **14 architecture ratchets, 15 golden/snapshot suites, 12 characterization
+  suites.** Function-size and import-cycle ratchets that failed on refactors
+  harming nothing; byte-for-byte snapshots "fixed" by regenerating; tests that
+  pinned "what the code does today" by definition.
+- **11 of 14 lint scripts (-3,988 lines).** `lint-tests-isolation` alone was
+  717 lines standing in front of `src/core/paths.ts`, which already throws
+  `TEST_ISOLATION_MISSING` at runtime. Also removed: the `gen-config-schema
+  --check` gate (`build` regenerates the schema anyway, so what ships is always
+  current), and `lint-devto-posts` (322 lines that were wired to nothing and
+  duplicated checks `devto-cli` performs itself). The three kept catch
+  user-visible problems: secrets must route through the resolver, no dead refs
+  in shipped assets, no docs teaching commands that do not exist.
+- **Both `MIN_TESTS` floors** — arbitrary numbers whose only job was to fail
+  the suite when test count dropped.
+- **`release-workflow-syntax.yml`** — a workflow that ran actionlint over the
+  other workflows. A broken workflow file already fails at GitHub.
+- **Dead `$STASH/.akm` residue is now reportable (#889).** `akm health` gains a
+  read-only `stash-dead-residue` advisory naming each stale path and its size;
+  deletion is gated behind an explicit `akm health --clean-dead-residue`. On a
+  real bundle 82% of `.akm` (135 MB) was pre-0.9.0 leftovers no code reads.
+
+### Testing
+
+- Test isolation grandfather list drained 58 -> 2 (#785); the two retained
+  entries are the helper-definitions file and a meta-test of the guard itself.
+- The test tree now has a stated unit/integration rule and ~250 files were
+  reclassified by evidence — real DB, network, or process spawn — rather than
+  by filename (#786).
+- 31 status-only `not.toBe(0)` assertions replaced with exact exit codes and
+  machine-readable error codes, every value observed rather than inferred
+  (#787).
+- Near-duplicate clusters drained (#788); real-server timing flakes removed or
+  made deterministic (#789).
+- Kept deliberately: `registry-network-boundary.test.ts`, which enforces that
+  only `pinned-transport.ts` may import `node:http`/`node:https` — the control
+  that stops a raw request bypassing address-pinned fetching. No lint script
+  covers that boundary.
+
 ## [0.9.7] - 2026-08-31
 
 ### Added

package/dist/commands/env/env.js

@@ -48,28 +48,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import dotenv from "dotenv";
-import { writeFileAtomic } from "../../core/common.js";
+import { scanEnvKeyNames, writeFileAtomic } from "../../core/common.js";
 import { sensitiveMarkerPath } from "./marker-path.js";
-/** Matches a KEY=value assignment line, capturing only the key. */
-const ASSIGN_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
-/** Scan lines and return KEY names in file order, without duplicates. */
-export function scanEnvKeyNames(text) {
-    const keys = [];
-    const seen = new Set();
-    for (const line of text.split(/\r?\n/)) {
-        const m = line.match(ASSIGN_RE);
-        if (!m)
-            continue;
-        const key = m[1];
-        if (!key)
-            continue;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        keys.push(key);
-    }
-    return keys;
-}
+export { scanEnvKeyNames };
 /**
  * Read and return ONLY non-secret metadata: key names.
  *

package/dist/commands/health/checks.js

@@ -706,29 +706,4 @@ export const HEALTH_CHECKS = [
             };
         },
     },
-    {
-        // Item 4: stale durable-transaction journals under $DATA/txn (stranded
-        // recovery state seen twice in a real 0.9 migration) had zero health
-        // visibility. `count`/`unreadable` already exclude journals younger than
-        // the sweeper's grace period (a currently-running operation), so any
-        // nonzero count here is a real leftover.
-        name: "stale-txn-journals",
-        channel: "advisory",
-        run: (ctx) => {
-            const s = ctx.staleTxnJournals;
-            const warn = s.count > 0;
-            const unreadablePart = s.unreadable > 0 ? `, ${s.unreadable} unreadable` : "";
-            const agePart = s.oldestAgeMs !== null ? `, oldest ${Math.round(s.oldestAgeMs / 60000)}m old` : "";
-            return {
-                name: "stale-txn-journals",
-                kind: "deterministic",
-                status: warn ? "warn" : "pass",
-                confidence: "high",
-                message: warn
-                    ? `${s.count} stale transaction journal(s) found under ${s.dir}${unreadablePart}${agePart} — see docs/migration/v0.9.0-troubleshooting.md for journal reconciliation steps.`
-                    : "No stale transaction journals found.",
-                evidence: { dir: s.dir, count: s.count, unreadable: s.unreadable, oldestAgeMs: s.oldestAgeMs },
-            };
-        },
-    },
 ];

package/dist/commands/health/improve-metrics.js

@@ -33,42 +33,16 @@ export function taskFailureDetail(row) {
     }
 }
 /**
- * D8 read-boundary predicate (spec docs/plans/specs/p1b-model-extraction.md
- * §5.3) for `akm health`'s `agentFailureRate`: true for a `task_history` row
- * that represents a prepared command (agent/LLM) result, across both
- * vocabularies. Mirrors src/tasks/run/task-history.ts's
- * `taskHistoryRowToResult` read mapping:
- *   - NEW rows mark themselves with metadata `targetVocab: 2` and store
- *     `target_kind: "command"` for the agent/LLM arm.
- *   - LEGACY rows (no marker, written before P1b's F-2 re-code) stored
- *     `target_kind: "prompt"` for the same arm — and `"command"` for the
- *     UNRELATED native shell/script arm, which must NOT be counted here.
- * So an unmarked `"command"` row is a legacy shell/script run, not an
- * agent/LLM one; a marked `"command"` row (or an unmarked `"prompt"` row) is.
+ * `akm health`'s `agentFailureRate` predicate: true for a `task_history` row
+ * that represents a prepared command (agent/LLM) result. `target_kind` is
+ * read in the current (post-D8) vocabulary — the
+ * `025-task-history-vocabulary-backfill` state migration rewrites every
+ * legacy-vocabulary row (which stored the agent/LLM arm as `"prompt"` and
+ * the native shell/script arm as `"command"`) before this ever runs against
+ * it, so a `"command"` row here is unambiguously the agent/LLM arm.
  */
 export function isAgentTaskHistoryRow(row) {
-    // Check target_kind BEFORE decoding metadata: some rows in the wild
-    // (e.g. improve-pipeline task_history rows, target_kind "improve") carry
-    // metadata_json that predates the metadataVersion:2 shape entirely, and
-    // decodeTaskHistoryMetadata throws on that — exactly like the pre-fix
-    // `target_kind === "prompt"` filter, which never called it for a row this
-    // function isn't going to count anyway. Only decode for the two target
-    // kinds this predicate can return true for.
-    if (row.target_kind !== "command" && row.target_kind !== "prompt")
-        return false;
-    // An undecodable metadata_json is by definition unmarked: pre-P1b rows can
-    // carry shapes decodeTaskHistoryMetadata rejects, and `akm health` must
-    // classify them as legacy rather than throw (round-3 review advisory).
-    let marked = false;
-    try {
-        marked = decodeTaskHistoryMetadata(row.metadata_json).targetVocab === 2;
-    }
-    catch {
-        marked = false;
-    }
-    if (row.target_kind === "command")
-        return marked;
-    return !marked;
+    return row.target_kind === "command";
 }
 function createUnknownImproveMetrics() {
     return {

package/dist/commands/health/windows.js

@@ -148,10 +148,6 @@ export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Da
     const failedTaskRows = taskRows.filter((row) => row.status === "failed");
     const activeRows = taskRows.filter((row) => row.status === "active" && row.completed_at === null);
     const stuckActiveRuns = activeRows.filter((row) => now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS).length;
-    // D8 (spec §5.3): a marked "command" row or a legacy (unmarked) "prompt"
-    // row is the agent/LLM arm; an unmarked "command" row is the legacy
-    // native shell/script arm and must not be counted here (see
-    // isAgentTaskHistoryRow's header comment for the full mapping).
     const agentRows = taskRows.filter((row) => isAgentTaskHistoryRow(row));
     const agentFailures = agentRows.filter((row) => {
         const detail = taskFailureDetail(row);

package/dist/commands/health.js

@@ -7,10 +7,9 @@ import { resolveStashDir } from "../core/common.js";
 import { loadConfig } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
-import { listTxnJournalsTolerant, TXN_SWEEP_GRACE_MS } from "../core/fs-txn.js";
 import { openLogsDatabase } from "../core/logs-db.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
-import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
+import { getConfigPath, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
@@ -150,37 +149,6 @@ function gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now) {
         agentFailureRate,
     };
 }
-/**
- * Item 4: leftover durable-transaction journals under `$DATA/txn` (stranded
- * recovery state seen twice in a real 0.9 migration) had zero health
- * visibility. Uses the tolerant scan variant so one corrupt journal.json is
- * counted rather than aborting the whole gather; a journal younger than
- * {@link TXN_SWEEP_GRACE_MS} is presumed to belong to a currently-running
- * operation and is not counted as stale. Best-effort: any unexpected error
- * (e.g. a permissions issue under `$DATA/txn`) degrades to "no signal" rather
- * than aborting the health report.
- */
-function gatherStaleTxnJournalsPhase(now) {
-    const dir = path.join(getDataDir(), "txn");
-    try {
-        const { matches, unreadableMtimes } = listTxnJournalsTolerant(() => true);
-        const nowMs = now();
-        const staleAges = [
-            ...matches.map((m) => nowMs - m.mtimeMs),
-            ...unreadableMtimes.map((mtimeMs) => nowMs - mtimeMs),
-        ].filter((ageMs) => ageMs >= TXN_SWEEP_GRACE_MS);
-        const staleUnreadableCount = unreadableMtimes.filter((mtimeMs) => nowMs - mtimeMs >= TXN_SWEEP_GRACE_MS).length;
-        return {
-            dir,
-            count: staleAges.length,
-            oldestAgeMs: staleAges.length > 0 ? Math.max(...staleAges) : null,
-            unreadable: staleUnreadableCount,
-        };
-    }
-    catch {
-        return { dir, count: 0, oldestAgeMs: null, unreadable: 0 };
-    }
-}
 /**
  * Config fields the surfaces advisory needs. Best-effort: an unloadable
  * config leaves the field undefined and the caller falls back to a generic
@@ -512,7 +480,6 @@ export function akmHealth(options = {}) {
     try {
         const taskHistory = gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now);
         const { tableNames, missingTables, probe } = taskHistory;
-        const staleTxnJournals = gatherStaleTxnJournalsPhase(now);
         const { egressConfigView } = gatherEgressConfigPhase();
         const { improveSummary } = gatherImproveSummaryPhase(db, stateDbPath, since, now);
         advisories.push(...gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView));
@@ -535,7 +502,6 @@ export function akmHealth(options = {}) {
             stuckActiveRuns: taskHistory.stuckActiveRuns,
             stuckActiveTasks: taskHistory.stuckActiveTasks,
             worstTaskFailRate: taskHistory.worstTaskFailRate,
-            staleTxnJournals,
             sessionExtraction: improveSummary.sessionExtraction,
             autoAccept: improveSummary.autoAccept,
             engineProbes,

package/dist/commands/improve/consolidate/eligibility.js

@@ -18,8 +18,8 @@ export function isConsolidationEligibleMemoryName(name) {
  *
  * Reads the file once per check; consolidate runs against ~10 memories per
  * chunk so the IO cost is trivial. Returns false on any read/parse error
- * (fail-safe: an unparseable file is treated as not-hot, but the broader
- * consolidate flow already guards against unparseable memories elsewhere).
+ * (fail-safe: an unreadable or unparseable file is treated as HOT — protected
+ * — because a deletion shield must not fail open; a missing file is not-hot).
  *
  * Defends against four observed defect classes (see
  * `memories/akm-improve-critical-review-2026-05-20`):
@@ -29,14 +29,20 @@ export function isConsolidationEligibleMemoryName(name) {
  *   - Cascade deletes (LLM uses ref:X as `contradictedBy` for ref:Y then deletes both)
  */
 export function isHotCapturedMemory(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
     try {
-        if (!fs.existsSync(filePath))
-            return false;
         const content = fs.readFileSync(filePath, "utf8");
         const parsed = parseFrontmatter(content);
         return hasHotCaptureMode(parsed.data);
     }
     catch {
-        return false;
+        // Fail CLOSED. This predicate is a deletion shield: "hot" memories are
+        // protected from consolidate's merge/delete. Returning false on a read or
+        // parse failure marked exactly the memories we could not inspect as fair
+        // game — the one direction a protection check must never fail. A missing
+        // file stays false (nothing to protect); an unreadable one is protected
+        // until someone can actually read it.
+        return true;
     }
 }

package/dist/commands/improve/extract.js

@@ -632,8 +632,40 @@ function unavailableExtractionResult(args) {
         ...args.notices,
     };
 }
+// #561 — ADDITIVE session indexing. Generate + write the session asset
+// (`sessions/<harness>/<id>.md`). FAIL-OPEN: any failure only returns a
+// warning; it NEVER changes the proposal/skip outcome of extract. Returns the
+// frontmatter fields to merge into the per-session result for state-db
+// correlation. When disabled this makes NO LLM call and writes NOTHING.
+async function maybeWriteSessionAsset(runCtx, session) {
+    const { stashDir, lease, sessionIndexing, dryRun } = runCtx;
+    const { data } = session.gate;
+    if (!sessionIndexing.enabled || dryRun)
+        return {};
+    if (!sessionMeetsDurationGate(data, sessionIndexing.minDurationMinutes))
+        return {};
+    try {
+        const result = await writeSessionAsset(data, stashDir, (summaryData) => sessionIndexing.generate(summaryData, lease));
+        if (result.written) {
+            // Write-path indexing (itself fail-open): standalone `akm extract`
+            // (session-end hook) has no post-loop reindex to pick this file up.
+            if (result.filePath)
+                await indexWrittenAssets(stashDir, [result.filePath]);
+            return {
+                ...(result.ref ? { sessionAssetRef: result.ref } : {}),
+                ...(result.logPath ? { sessionLogPath: result.logPath } : {}),
+            };
+        }
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        return { warning: `session asset write failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    return {};
+}
 async function processSession(runCtx, session) {
-    const { harness, stashDir, config, llmRunner, lease, onNotices, getNotices, chat, ctx, eventsCtx, sourceRun, dryRun, timeoutMs, sessionIndexing, signal, standardsContext, } = runCtx;
+    const { harness, stashDir, config, llmRunner, lease, onNotices, getNotices, chat, ctx, eventsCtx, sourceRun, dryRun, timeoutMs, signal, standardsContext, } = runCtx;
     const { sessionRef, gate } = session;
     const warnings = [];
     const { data, filtered, contentHash } = gate;
@@ -645,36 +677,6 @@ async function processSession(runCtx, session) {
         inlineRefs: data.inlineRefs,
         ...(standardsContext.trim() ? { standardsContext } : {}),
     });
-    // #561 — ADDITIVE session indexing. Generate + write the session asset
-    // (`sessions/<harness>/<id>.md`). FAIL-OPEN: any failure only records a
-    // warning; it NEVER changes the proposal/skip outcome of extract. Returns the
-    // frontmatter fields to merge into the per-session result for state-db
-    // correlation. When disabled this closure makes NO LLM call and writes NOTHING.
-    const maybeWriteSessionAsset = async () => {
-        if (!sessionIndexing.enabled || dryRun)
-            return {};
-        if (!sessionMeetsDurationGate(data, sessionIndexing.minDurationMinutes))
-            return {};
-        try {
-            const result = await writeSessionAsset(data, stashDir, (summaryData) => sessionIndexing.generate(summaryData, lease));
-            if (result.written) {
-                // Write-path indexing (itself fail-open): standalone `akm extract`
-                // (session-end hook) has no post-loop reindex to pick this file up.
-                if (result.filePath)
-                    await indexWrittenAssets(stashDir, [result.filePath]);
-                return {
-                    ...(result.ref ? { sessionAssetRef: result.ref } : {}),
-                    ...(result.logPath ? { sessionLogPath: result.logPath } : {}),
-                };
-            }
-        }
-        catch (err) {
-            if (err instanceof ConfigError)
-                throw err;
-            warnings.push(`session asset write failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        return {};
-    };
     const extraction = await runSessionExtractionLlmCall({
         config,
         llmRunner,
@@ -708,7 +710,9 @@ async function processSession(runCtx, session) {
     const { payload } = extraction;
     const proposalIds = [];
     // Provenance refs are added only after the cited session asset exists.
-    const sessionAsset = await maybeWriteSessionAsset();
+    const sessionAsset = await maybeWriteSessionAsset(runCtx, session);
+    if (sessionAsset.warning)
+        warnings.push(sessionAsset.warning);
     if (payload.candidates.length === 0) {
         appendEvent({
             eventType: "extract_invoked",

package/dist/commands/improve/memory/memory-belief.js

@@ -52,10 +52,17 @@ function readEdgeList(value) {
  * Write `contradictedBy` and `beliefState: contradicted` edges to a memory
  * file's frontmatter (C-3 / #382).
  *
- * This is the shared primitive used by:
- *   - `akmConsolidate` when its LLM plan includes a `contradict` op
- *   - `memory-contradiction-detect.ts` for the M-1 automated contradiction pass
- *   - `resolveFamilyContradictions` in `memory-improve.ts` for SCC resolution
+ * The shared primitive for APPENDING one contradiction edge. Used by
+ * `memory-contradiction-detect.ts`'s automated contradiction pass.
+ *
+ * NOT used by `persistBeliefStateTransition` in `memory-improve.ts`, and that
+ * is deliberate (#885): the SCC resolver is a state-TRANSITION writer, not an
+ * edge appender. It replaces `contradictedBy` wholesale from recomputed
+ * `currentBeliefRefs`, deletes the key when a memory transitions away from
+ * `contradicted`, and moves a memory to any target state including back to
+ * active. An append-only primitive that never weakens a demotion cannot
+ * express those, and routing it through this would break the resolver's
+ * ability to clear an edge.
  *
  * Idempotent: if the `contradictedByRef` is already in `contradictedBy` AND
  * the file already carries the demotion state, the file is not rewritten. The
@@ -72,9 +79,12 @@ function readEdgeList(value) {
  *
  * @param filePath          - Absolute path to the memory markdown file.
  * @param contradictedByRef - The ref that contradicts this memory.
+ * @returns `true` when the file was rewritten, `false` when the edge and the
+ *          demotion were already present (the idempotent no-op). Callers count
+ *          edges written from this.
  */
 export function writeContradictEdge(filePath, contradictedByRef) {
-    mutateFrontmatter(filePath, (parsed) => {
+    return mutateFrontmatter(filePath, (parsed) => {
         const existing = readEdgeList(parsed.data.contradictedBy);
         const currentState = parsed.data.beliefState;
         const nextState = currentState === "archived" ? currentState : "contradicted";

package/dist/commands/improve/memory/memory-contradiction-detect.js

@@ -17,8 +17,19 @@
  *   2. For each family, enumerate candidate pairs.
  *   3. For each pair, call the LLM to judge whether the two memories are in
  *      direct factual conflict.
- *   4. For confirmed contradictions, write `contradictedBy` edges directly to
- *      the losing memory's frontmatter (same mechanism as `persistBeliefStateTransition`).
+ *   4. For confirmed contradictions, append a `contradictedBy` edge to the
+ *      losing memory's frontmatter via `writeContradictEdge`
+ *      (`./memory-belief.ts`).
+ *
+ * That last step used to call a private near-copy of `writeContradictEdge`
+ * living in this file. The copy had drifted (#885): it read `contradictedBy`
+ * with `Array.isArray` only, so a SCALAR edge — live data the indexer accepts
+ * and lint never flags — read as "no edges" and was overwritten out of
+ * existence; and it set `beliefState: "contradicted"` unconditionally,
+ * promoting an `archived` memory back up (archived ranks BELOW contradicted).
+ * Both behaviors had tests, but the tests exercised the shared primitive,
+ * which nothing called — so they guarded dead code while the live path
+ * carried the bugs.
  *
  * # LLM Feature Gate
  *
@@ -36,12 +47,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import contradictionJudgeTemplate from "../../../assets/prompts/contradiction-judge.md" with { type: "text" };
-import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
 import { disposeLoweredExecutionDispatchLease } from "../../../integrations/agent/execution-lowering.js";
 import { callStructured, preflightStructuredLlmRunner } from "../../../llm/structured-call.js";
 import { resolveImproveLlmExecution } from "../execution.js";
 import { isDerivedMemory, memoryIdentityRef, resolveParentRef } from "./derived-ref.js";
+import { writeContradictEdge } from "./memory-belief.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /**
  * Minimum confidence required to write a contradiction edge. Below this
@@ -89,27 +101,6 @@ function toMemoryRef(memoriesDir, filePath) {
     return memoryIdentityRef(name);
 }
 // ── Edge writing ─────────────────────────────────────────────────────────────
-/**
- * Write a `contradictedBy` edge to the losing memory's frontmatter file.
- * Preserves all existing frontmatter keys; only adds/updates `contradictedBy`
- * and `beliefState: contradicted`.
- */
-/** Returns true if the edge was newly written, false if it already existed. */
-function writeContradictedByEdge(filePath, contradictedByRef) {
-    return mutateFrontmatter(filePath, (parsed) => {
-        const existing = Array.isArray(parsed.data.contradictedBy)
-            ? parsed.data.contradictedBy
-            : [];
-        if (existing.includes(contradictedByRef))
-            return null; // Edge already written.
-        const updatedContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
-        return {
-            ...parsed.data,
-            contradictedBy: updatedContradictedBy,
-            beliefState: "contradicted",
-        };
-    });
-}
 /**
  * Deterministically pick, for a confirmed-contradiction pair, the LOSER memory
  * that receives the single directed `contradictedBy` edge (SCC-resolved to
@@ -284,7 +275,7 @@ export async function detectAndWriteContradictions(stashDir, config, chat, strat
             // a 2-cycle that the SCC resolver refreshes back to active, erasing the
             // contradiction every run (see pickContradictionLoser).
             try {
-                const wrote = writeContradictedByEdge(loser.filePath, winnerRef);
+                const wrote = writeContradictEdge(loser.filePath, winnerRef);
                 result.edgesWritten += wrote ? 1 : 0;
             }
             catch (err) {