akm-cli 0.9.14 → 0.9.15-beta.2

package/dist/storage/repositories/embedding-salvage-repository.js

@@ -0,0 +1,184 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `index.db` embedding salvage (#955) — a transient, self-emptying table
+ * that lets a full rebuild or an index-generation bump reuse vectors instead
+ * of re-embedding a corpus whose content did not change.
+ *
+ * Zero steady-state cost by design: this is NOT a second embedding cache.
+ * Rows are copied aside only at the moment they would otherwise be discarded
+ * wholesale — a full-index wipe (`persistDirRecords`) or a generation bump
+ * (`rebuildIncompatibleIndexGeneration`) — and are consumed by the very next
+ * embedding pass (`generateEmbeddingsForDb`). A pass that completes without
+ * abort or circuit-break purges whatever is left; an interrupted pass leaves
+ * the table for the next attempt to pick up.
+ *
+ * Reuse is keyed on `sha256(search_text)` plus the fingerprint the vector was
+ * generated under — a fingerprint mismatch or a single-byte content change
+ * both correctly fall through to a real provider call. `content_hash` is the
+ * PRIMARY KEY (not `(content_hash, fingerprint)`) so relabeling a whole
+ * generation's fingerprint after a canary "keep" verdict is one UPDATE, and a
+ * hash colliding across two discards simply keeps the most recent copy —
+ * salvage is a best-effort optimization, not a durable multi-generation
+ * archive.
+ */
+import { createHash } from "node:crypto";
+import { blobToEmbedding } from "./embeddings-repository.js";
+import { getMeta } from "./index-meta-repository.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+/**
+ * Create the salvage table. Additive-only DDL: it carries no bearing on the
+ * `entries` generation fingerprint (`hasCanonicalEntrySchema`), so adding it
+ * does not require an index-generation bump.
+ */
+export function ensureEmbeddingSalvageTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS embedding_salvage (
+      content_hash TEXT PRIMARY KEY,
+      fingerprint  TEXT NOT NULL,
+      embedding    BLOB NOT NULL,
+      salvaged_at  TEXT NOT NULL
+    );
+  `);
+}
+/** The one hash function salvage writes and reuse lookups must agree on. */
+export function hashEmbeddableText(searchText) {
+    return createHash("sha256").update(searchText, "utf8").digest("hex");
+}
+function tableExists(db, name) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name) != null;
+}
+function tableHasColumn(db, table, column) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    return columns.some((c) => c.name === column);
+}
+/**
+ * Copy every (hash of search_text, embedding) pair about to be discarded
+ * wholesale into `embedding_salvage`, tagged with the `embeddingFingerprint`
+ * the discarded vectors were generated under. The caller MUST run this
+ * inside the same transaction as the discard that follows it, so the copy
+ * and the delete commit or roll back together.
+ *
+ * Streams `entries JOIN embeddings` in id-ordered pages of
+ * {@link SQLITE_CHUNK_SIZE} instead of loading every row into memory before
+ * hashing anything — a full rebuild of a large stash otherwise held the
+ * entire corpus's search text and vectors in memory at once just to copy
+ * them aside (#955, field-report follow-up).
+ *
+ * A no-op (returns 0) when there is no stored `embeddingFingerprint` to tag
+ * rows with (nothing was ever verified against a provider, so there is
+ * nothing worth reusing later) or the generation being discarded predates
+ * the `entries.search_text` column or has no `embeddings` table at all — an
+ * older generation than that has nothing this can safely read.
+ */
+export function salvageEmbeddingsBeforeDiscard(db) {
+    const fingerprint = getMeta(db, "embeddingFingerprint");
+    if (!fingerprint)
+        return 0;
+    if (!tableExists(db, "entries") || !tableExists(db, "embeddings"))
+        return 0;
+    if (!tableHasColumn(db, "entries", "search_text"))
+        return 0;
+    const page = db.prepare("SELECT e.id AS id, e.search_text AS searchText, em.embedding AS embedding " +
+        "FROM entries e JOIN embeddings em ON em.id = e.id WHERE e.id > ? ORDER BY e.id LIMIT ?");
+    const insert = db.prepare("INSERT OR REPLACE INTO embedding_salvage (content_hash, fingerprint, embedding, salvaged_at) VALUES (?, ?, ?, ?)");
+    const salvagedAt = new Date().toISOString();
+    let lastId = 0;
+    let total = 0;
+    for (;;) {
+        const rows = page.all(lastId, SQLITE_CHUNK_SIZE);
+        if (rows.length === 0)
+            break;
+        for (const row of rows) {
+            insert.run(hashEmbeddableText(row.searchText), fingerprint, row.embedding, salvagedAt);
+        }
+        total += rows.length;
+        lastId = rows[rows.length - 1]?.id ?? lastId;
+        if (rows.length < SQLITE_CHUNK_SIZE)
+            break;
+    }
+    return total;
+}
+/**
+ * Remove every salvage row. Called after an embedding pass completes without
+ * abort or circuit-break (the salvaged generation has now either been reused
+ * or superseded), and by `--reembed` / a canary "rebuild" verdict (the
+ * salvaged vectors belong to a different model and are never reusable).
+ */
+export function purgeEmbeddingSalvage(db) {
+    db.exec("DELETE FROM embedding_salvage");
+}
+/**
+ * A canary "keep" verdict means the model did not actually change — only its
+ * fingerprint STRING did (e.g. a gateway rename). Salvage rows tagged with
+ * the old string are still valid vectors; rewrite them to the new string so
+ * they remain reusable instead of silently going stale.
+ */
+export function relabelEmbeddingSalvageFingerprint(db, fromFingerprint, toFingerprint) {
+    db.prepare("UPDATE embedding_salvage SET fingerprint = ? WHERE fingerprint = ?").run(toFingerprint, fromFingerprint);
+}
+/**
+ * Reuse salvaged vectors for `entries` whose `searchText` hash matches a
+ * salvage row tagged with the CURRENT `fingerprint` — never across
+ * fingerprints, and never when `search_text` differs by even one byte (the
+ * hash is exact-match only, by design). Matches are written via
+ * `writeReused` in chunks of {@link SQLITE_CHUNK_SIZE}, each its own
+ * transaction, mirroring the main pass's per-batch commit (#955) so an
+ * interruption partway through the reuse step keeps whatever already wrote.
+ *
+ * The steady state of every ordinary run is an EMPTY salvage table (nothing
+ * was just discarded), so this checks that first with one indexed lookup —
+ * `SELECT 1 ... LIMIT 1` — before hashing a single pending entry. Hashing
+ * every entry up front to look up a table that is empty 100% of the time
+ * outside a rebuild was pure wasted work on the common path (#955,
+ * field-report follow-up).
+ */
+export function reuseSalvagedEmbeddings(db, entries, fingerprint, writeReused) {
+    if (entries.length === 0)
+        return { reusedCount: 0, remaining: [] };
+    const anySalvageForFingerprint = db
+        .prepare("SELECT 1 FROM embedding_salvage WHERE fingerprint = ? LIMIT 1")
+        .get(fingerprint);
+    if (!anySalvageForFingerprint)
+        return { reusedCount: 0, remaining: [...entries] };
+    const hashes = entries.map((entry) => hashEmbeddableText(entry.searchText));
+    const salvageByHash = new Map();
+    const uniqueHashes = [...new Set(hashes)];
+    for (let offset = 0; offset < uniqueHashes.length; offset += SQLITE_CHUNK_SIZE) {
+        const chunk = uniqueHashes.slice(offset, offset + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT content_hash AS contentHash, embedding FROM embedding_salvage WHERE fingerprint = ? AND content_hash IN (${placeholders})`)
+            .all(fingerprint, ...chunk);
+        for (const row of rows)
+            salvageByHash.set(row.contentHash, row.embedding);
+    }
+    if (salvageByHash.size === 0)
+        return { reusedCount: 0, remaining: [...entries] };
+    let reusedCount = 0;
+    const remaining = [];
+    for (let offset = 0; offset < entries.length; offset += SQLITE_CHUNK_SIZE) {
+        const end = Math.min(offset + SQLITE_CHUNK_SIZE, entries.length);
+        const chunkMatches = [];
+        for (let i = offset; i < end; i++) {
+            const entry = entries[i];
+            const blob = salvageByHash.get(hashes[i]);
+            if (blob)
+                chunkMatches.push({ entry, blob });
+            else
+                remaining.push(entry);
+        }
+        if (chunkMatches.length === 0)
+            continue;
+        db.transaction(() => {
+            for (const { entry, blob } of chunkMatches) {
+                if (writeReused(entry, blobToEmbedding(blob)))
+                    reusedCount++;
+                else
+                    remaining.push(entry);
+            }
+        })();
+    }
+    return { reusedCount, remaining };
+}

package/dist/storage/repositories/improve-runs-repository.js

@@ -102,6 +102,40 @@ export function queryImproveRuns(db, since, until) {
         : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, strategy, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
     return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
 }
+const IMPROVE_RUN_ROW_COLUMNS = "id, started_at, completed_at, stash_dir, dry_run, strategy, scope_mode, scope_value, guidance, ok, result_json, metrics_json, metadata_json";
+/**
+ * Look up a single `improve_runs` row by its id (#944 — `akm improve report --run <id>`).
+ * `id` is the PRIMARY KEY, so at most one row matches. Returns `undefined`
+ * for an unknown id rather than throwing — the caller decides how to report
+ * "no such run".
+ */
+export function getImproveRunById(db, id) {
+    return db.prepare(`SELECT ${IMPROVE_RUN_ROW_COLUMNS} FROM improve_runs WHERE id = ?`).get(id);
+}
+/**
+ * Look up the most recent real (non-dry-run) `improve_runs` row (#944 —
+ * `akm improve report`'s default target, and `--last`). Same `dry_run = 0`
+ * filter as {@link queryImproveRuns} so a dry-run preview never becomes the
+ * implicit "last run" a report reads.
+ */
+export function getLatestImproveRun(db) {
+    return db
+        .prepare(`SELECT ${IMPROVE_RUN_ROW_COLUMNS} FROM improve_runs WHERE dry_run = 0 ORDER BY started_at DESC LIMIT 1`)
+        .get();
+}
+/**
+ * #950: count real (non-dry-run) improve_runs rows whose `started_at` falls
+ * in `[since, now)` — same filter as {@link queryImproveRuns}, but a `SELECT
+ * COUNT(*)` for a caller (the `engine-last-used` gate) that only needs to
+ * know whether any run happened, not the rows themselves (which would pull
+ * every `result_json` blob in the window just to test for zero).
+ */
+export function countImproveRunsSince(db, since) {
+    const row = db
+        .prepare("SELECT COUNT(*) AS cnt FROM improve_runs WHERE started_at >= ? AND dry_run = 0")
+        .get(since);
+    return row.cnt;
+}
 /**
  * Delete improve_runs rows older than `retentionDays` (default: 90). Mirrors
  * {@link purgeOldEvents} — same default, same return shape (number of rows

package/dist/storage/repositories/index-fts-repository.js

@@ -7,7 +7,7 @@
  * Owns the `entries_fts` full-text query path, per-entry projections, and the
  * explicit full recovery rebuild.
  */
-import { fragmentForSelector, splitMarkdownFragments } from "../../core/asset/markdown-fragments.js";
+import { splitMarkdownFragments } from "../../core/asset/markdown-fragments.js";
 import { stableFtsScore } from "../../core/lexical-score.js";
 import { warn } from "../../core/warn.js";
 import { buildLexicalQueryPlan } from "../../indexer/search/fts-query.js";
@@ -87,11 +87,54 @@ export function searchFts(db, query, limit, entryType, excludeTypes) {
  * file edit; the next index refresh atomically publishes the new revision.
  */
 export function getIndexedMarkdownFragment(db, itemRef, fragmentId) {
-    const row = db
-        .prepare("SELECT s.safe_markdown FROM entry_fragments_fts f JOIN entry_fragments s ON s.entry_id = f.entry_id JOIN entries e ON e.id = f.entry_id WHERE e.item_ref = ? AND f.fragment_id = ?")
-        .get(itemRef, fragmentId);
-    const fragment = row ? fragmentForSelector(row.safe_markdown, fragmentId) : undefined;
-    return fragment ? { content: fragment.text } : undefined;
+    return getIndexedMarkdownFragments(db, [{ itemRef, fragmentId }])[0];
+}
+/**
+ * Batch the selected-hit projection read. Search commonly enriches several
+ * fragment hits at once; reading all indexed-safe parents in chunks avoids an
+ * N-query loop, while grouping selectors by parent ensures each safe revision
+ * is split at most once.
+ */
+export function getIndexedMarkdownFragments(db, selections) {
+    if (selections.length === 0)
+        return [];
+    const itemRefs = [...new Set(selections.map((selection) => selection.itemRef))];
+    const sourceByRef = new Map();
+    for (let offset = 0; offset < itemRefs.length; offset += SQLITE_CHUNK_SIZE) {
+        const chunk = itemRefs.slice(offset, offset + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT e.item_ref, s.safe_markdown FROM entry_fragments s JOIN entries e ON e.id = s.entry_id WHERE e.item_ref IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows)
+            sourceByRef.set(row.item_ref, row.safe_markdown);
+    }
+    const fragmentsByRef = new Map();
+    for (const [itemRef, safeMarkdown] of sourceByRef) {
+        fragmentsByRef.set(itemRef, splitMarkdownFragments(safeMarkdown));
+    }
+    return selections.map((selection) => {
+        const safeMarkdown = sourceByRef.get(selection.itemRef);
+        const fragments = fragmentsByRef.get(selection.itemRef);
+        if (safeMarkdown === undefined || !fragments)
+            return undefined;
+        const fragment = fragments.find((candidate) => candidate.fragmentId === selection.fragmentId || candidate.headingSlug === selection.fragmentId);
+        return fragment ? materializeIndexedMarkdownFragment(fragment, fragments, safeMarkdown.length) : undefined;
+    });
+}
+function materializeIndexedMarkdownFragment(fragment, fragments, parentChars) {
+    return {
+        content: fragment.text,
+        ordinal: fragment.ordinal,
+        count: fragments.length,
+        startLine: fragment.startLine,
+        endLine: fragment.endLine,
+        previousFragmentId: fragments[fragment.ordinal - 1]?.fragmentId,
+        nextFragmentId: fragments[fragment.ordinal + 1]?.fragmentId,
+        fragmentChars: fragment.text.length,
+        parentChars,
+        fragments,
+    };
 }
 function runFtsQuery(db, ftsQuery, lexicalMatch, limit, entryType, excludeTypes) {
     // Preserve the repository's ordinary limit contract for direct callers.

package/dist/storage/repositories/index-schema.js

@@ -12,6 +12,7 @@
  */
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
+import { ensureEmbeddingSalvageTable, salvageEmbeddingsBeforeDiscard } from "./embedding-salvage-repository.js";
 import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration, } from "./index-entry-schema.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
 import { isVecAvailable, purgeEmbeddings } from "./index-vec-repository.js";
@@ -196,6 +197,13 @@ function rebuildIncompatibleIndexGeneration(db) {
         vecResetPending = true;
     }
     db.transaction(() => {
+        // #955: copy embeddings about to be discarded wholesale into
+        // `embedding_salvage` (keyed by content hash + the fingerprint they were
+        // generated under) BEFORE dropping `embeddings`, in the same transaction
+        // as the drop, so the copy and the discard commit or roll back together.
+        // The next embedding pass hands salvaged vectors back to unchanged
+        // content instead of re-embedding the whole corpus after this bump.
+        salvageEmbeddingsBeforeDiscard(db);
         db.exec("DROP TABLE IF EXISTS graph_file_relations");
         db.exec("DROP TABLE IF EXISTS graph_file_entities");
         db.exec("DROP TABLE IF EXISTS graph_files");
@@ -212,6 +220,9 @@ function rebuildIncompatibleIndexGeneration(db) {
         db.exec("DROP TABLE IF EXISTS index_dir_state");
         db.exec("DROP TABLE IF EXISTS entries");
         db.exec("DELETE FROM index_meta");
+        // embedding_salvage is deliberately absent from the drop list above —
+        // it is the ONE piece of derived state a generation rebuild must not
+        // discard.
     })();
     if (vecResetPending)
         setMeta(db, "vecResetPending", "1");
@@ -224,6 +235,11 @@ export function ensureSchema(db, embeddingDim) {
       value TEXT NOT NULL
     );
   `);
+    // #955: created before the generation-rebuild check below so a discard
+    // has somewhere to copy vectors to. Additive-only — it carries no bearing
+    // on the `entries` generation fingerprint (`hasCanonicalEntrySchema`), so
+    // adding it does not require a `CANONICAL_INDEX_DB_VERSION` bump.
+    ensureEmbeddingSalvageTable(db);
     rebuildIncompatibleIndexGeneration(db);
     db.exec(CANONICAL_ENTRY_SCHEMA_SQL);
     // Workflow source is compiled directly into source IR at each command

package/dist/storage/repositories/index-vec-repository.js

@@ -333,3 +333,33 @@ export function getEmbeddingCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
     return row.cnt;
 }
+/**
+ * Sample up to `limit` already-embedded entries (id, search text, and the
+ * stored vector) for the embedding-fingerprint canary check: re-embedding
+ * these texts with the CURRENT config and comparing against `vector` is how
+ * a model-string rename is told apart from a genuine model/dimension change
+ * (#955), without trusting the config string alone.
+ *
+ * Ordered by `id` for a deterministic, cheap sample (no `ORDER BY RANDOM()`)
+ * — the canary only needs "some" already-verified vectors, not a
+ * statistically representative one. A corrupt stored BLOB (see
+ * `bufferToFloat32`) is skipped rather than failing the whole sample.
+ */
+export function sampleEmbeddedEntriesForCanary(db, limit) {
+    const rows = db
+        .prepare(`
+      SELECT e.id, e.search_text AS searchText, em.embedding AS embedding
+      FROM entries e
+      JOIN embeddings em ON em.id = e.id
+      ORDER BY e.id
+      LIMIT ?
+    `)
+        .all(limit);
+    const samples = [];
+    for (const row of rows) {
+        const vector = bufferToFloat32(row.embedding, Math.floor(row.embedding.byteLength / 4));
+        if (vector)
+            samples.push({ id: row.id, searchText: row.searchText, vector });
+    }
+    return samples;
+}

package/dist/storage/repositories/workflow-runs-repository.js

@@ -2,8 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { randomUUID } from "node:crypto";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
+import { NotFoundError, TransientError, UsageError } from "../../core/errors.js";
+import { isSqliteContentionError, openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
 import { borrowScopedStateDb, withStateDbScope } from "../../core/state-db-scope.js";
 import { sleepSync } from "../../runtime.js";
 import { escapeLikePattern } from "../like-pattern.js";
@@ -25,22 +25,21 @@ function assertAttemptReservationLease(input, run) {
 /**
  * Whether `error` is one of the specific SQLite conditions a run-lease
  * statement can throw under real cross-process contention on the same row:
- * `SQLITE_BUSY`/`SQLITE_LOCKED` (both drivers), or the message text a
- * transient contention blip has been observed producing, "database is
- * locked", "disk I/O error", or "database disk image is malformed".
- * Matching on this set alone is never sufficient to call something lease
- * contention — see {@link WorkflowRunsRepository.acquireEngineLease}, which
- * additionally requires a fresh read confirming a live lease before
- * substituting the lease-held message for the original error.
+ * the shared {@link isSqliteContentionError} classifier (SQLITE_BUSY/LOCKED,
+ * "database is locked", "database table is locked", the phantom-BEGIN
+ * marker) plus two corruption-shaped message texts a transient contention
+ * blip has been observed producing on this specific race, "disk I/O error"
+ * and "database disk image is malformed". Matching on this set alone is
+ * never sufficient to call something lease contention — see
+ * {@link WorkflowRunsRepository.acquireEngineLease}, which additionally
+ * requires a fresh read confirming a live lease before substituting the
+ * lease-held message for the original error.
  */
 function isLeaseContentionSqliteError(error) {
-    const code = error?.code;
-    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+    if (isSqliteContentionError(error))
         return true;
     const message = error instanceof Error ? error.message : String(error);
-    return (message.includes("database is locked") ||
-        message.includes("disk I/O error") ||
-        message.includes("database disk image is malformed"));
+    return message.includes("disk I/O error") || message.includes("database disk image is malformed");
 }
 const LEASE_RETRY_ATTEMPTS = 4;
 const LEASE_RETRY_BASE_DELAY_MS = 15;
@@ -110,6 +109,9 @@ export class WorkflowRunsRepository {
      * operator to `akm workflow abandon` a child a parent is actively driving.
      * For any database with no child rows the result is byte-identical, same
      * as the other three B-N10 sites below.
+     *
+     * Always scope-local: `scopeKey` is a real scope, never "every scope" — see
+     * {@link findActiveRunOutsideScope} for the cross-scope warning's query.
      */
     findActiveRunForScope(workflowRefs, scopeKey) {
         const refs = typeof workflowRefs === "string" ? [workflowRefs] : [...workflowRefs];
@@ -119,6 +121,26 @@ export class WorkflowRunsRepository {
             .prepare(`SELECT id, current_step_id FROM workflow_runs WHERE workflow_ref IN (${refs.map(() => "?").join(", ")}) AND scope_key = ? AND status = 'active' AND parent_run_id IS NULL ORDER BY updated_at DESC, created_at DESC LIMIT 1`)
             .get(...refs, scopeKey);
     }
+    /**
+     * The cross-scope start warning's query (#942): the most recently active
+     * run of these refs OUTSIDE `scopeKey` — i.e. `scope_key IS NULL OR
+     * scope_key != scopeKey`, not merely "the most recent active run of these
+     * refs anywhere". A same-scope active row must never win the `LIMIT 1` and
+     * mask a DIFFERENT scope's run: with `--new`/`--force`, the caller's own
+     * active run could otherwise sort first (most recently updated) and hide a
+     * third scope's run entirely, so `startWorkflowRun` silently warned about
+     * nothing while a genuinely stale run in another scope went unreported.
+     * `findActiveRunForScope` deliberately stays scope-local and is never used
+     * for this purpose.
+     */
+    findActiveRunOutsideScope(workflowRefs, scopeKey) {
+        const refs = typeof workflowRefs === "string" ? [workflowRefs] : [...workflowRefs];
+        if (refs.length === 0)
+            return undefined;
+        return (this.db
+            .prepare(`SELECT * FROM workflow_runs WHERE workflow_ref IN (${refs.map(() => "?").join(", ")}) AND (scope_key IS NULL OR scope_key != ?) AND status = 'active' AND parent_run_id IS NULL ORDER BY updated_at DESC, created_at DESC LIMIT 1`)
+            .get(...refs, scopeKey) ?? undefined);
+    }
     getRunById(runId) {
         return (this.db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId) ??
             undefined);
@@ -130,6 +152,9 @@ export class WorkflowRunsRepository {
      * to directly through this path — a parent-driven child would then have
      * TWO drivers. For any database with no child rows the result is
      * byte-identical.
+     *
+     * Always scope-local: `scopeKey` is a real scope, never "every scope" — see
+     * {@link findActiveRunOutsideScope} for the cross-scope warning's query.
      */
     getActiveRunRowForScope(workflowRefs, scopeKey) {
         const refs = typeof workflowRefs === "string" ? [workflowRefs] : [...workflowRefs];
@@ -159,8 +184,13 @@ export class WorkflowRunsRepository {
     listRuns(filter) {
         const filters = [];
         const params = [];
-        filters.push("scope_key = ?");
-        params.push(filter.scopeKey);
+        // `scopeKey: null` (#942) is "every scope" — the predicate is omitted
+        // rather than bound as SQL NULL (which would match nothing, since a real
+        // `scope_key` column value is never NULL for a fresh run).
+        if (filter.scopeKey !== null) {
+            filters.push("scope_key = ?");
+            params.push(filter.scopeKey);
+        }
         if (filter.workflowRef) {
             filters.push("workflow_ref = ?");
             params.push(filter.workflowRef);
@@ -282,10 +312,17 @@ export class WorkflowRunsRepository {
         this.immediateTransaction((db) => {
             input.revalidateSources();
             if (!input.force) {
+                // The uniqueness guard must never silently skip its scope predicate
+                // (#942) — every real caller (`startWorkflowRun`) stamps a concrete
+                // scope key, so a null one here means the caller is misusing this
+                // top-level guard, not that scoping should be waived.
+                if (input.run.scopeKey === null) {
+                    throw new Error("publishWorkflowRunV4: run.scopeKey must not be null for the scope uniqueness guard.");
+                }
                 const existing = this.findActiveRunForScope(input.workflowRefs, input.run.scopeKey);
                 if (existing) {
                     throw new UsageError(`Workflow ${input.run.workflowRef} already has an active run in this scope ` +
-                        `(id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
+                        `(id=${existing.id}, scope=${input.run.scopeKey}, step=${existing.current_step_id ?? "—"}). ` +
                         `Use 'akm workflow run ${input.run.workflowRef}' to resume it or ` +
                         `'akm workflow abandon ${existing.id}' to give up on it.`, "RESOURCE_ALREADY_EXISTS");
                 }
@@ -443,7 +480,7 @@ export class WorkflowRunsRepository {
                 throw error;
             const row = this.tryReadLeaseColumns(runId);
             if (row?.engine_lease_holder && row.engine_lease_until && row.engine_lease_until >= now) {
-                throw new UsageError(`Workflow run ${runId} is already being driven by engine ${row.engine_lease_holder} ` +
+                throw new TransientError(`Workflow run ${runId} is already being driven by engine ${row.engine_lease_holder} ` +
                     `(run lease expires ${row.engine_lease_until}). A second \`akm workflow run\` would race it — ` +
                     `wait for that invocation to finish or for the lease to expire.`, "RUN_LEASE_HELD");
             }

package/dist/tasks/backends/cron.js

@@ -7,7 +7,7 @@
 // its other lines untouched:
 //
 //     # akm:task <id> BEGIN
-//     [SCHED] /abs/akm task run <id> >> /home/.../tasks/logs/<id>.log 2>&1
+//     [SCHED] /abs/akm task run <id> > /home/.../tasks/logs/<id>.log 2>&1
 //     # akm:task <id> END
 //
 // The backend reads/writes the user's crontab via `crontab -l` and
@@ -58,9 +58,9 @@ export function CRON_BACKEND(options = {}) {
         install(task, opts, expected) {
             if (expected)
                 assertSchedulerExpectationIdentity(expected, task);
-            // Create the log directory before writing the crontab line — cron
-            // appends with `>>` and the surrounding shell will fail the entire
-            // entry if the parent directory doesn't exist.
+            // Create the log directory before writing the crontab line — the
+            // redirect target's parent directory must exist or the surrounding
+            // shell will fail the entire entry.
             const cronLineParts = buildCronLineParts(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
             const cronLine = cronLineParts.line;
             assertPortableCronLine(cronLine);
@@ -260,14 +260,17 @@ function buildCronLineParts(task, akmArgv, logDir, contextPath, _target) {
     const logPath = path.join(logDir, `${nativeId}.log`);
     const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
     const cmd = invocation.argv.map((part) => quoteForCron(part)).join(" ");
-    const directLine = `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+    // #951: truncate (not append) so this bootstrap safety-net file always
+    // holds exactly the latest run's raw output rather than growing forever.
+    // akm's own per-run log (src/tasks/run/task-log.ts) already keeps history.
+    const directLine = `${cronExpr} ${cmd} > ${quoteForCron(logPath)} 2>&1`;
     if (Buffer.byteLength(directLine, "utf8") <= PORTABLE_CRON_LINE_LIMIT) {
         return { line: directLine };
     }
     const content = cronWrapperScriptContent(invocation.argv);
     const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
     const wrapperPath = path.join(logDir, `${CRON_WRAPPER_PREFIX}${nativeId}-${contentHash}.sh`);
-    const line = `${cronExpr} sh ${quoteForCron(wrapperPath)} >> ${quoteForCron(logPath)} 2>&1`;
+    const line = `${cronExpr} sh ${quoteForCron(wrapperPath)} > ${quoteForCron(logPath)} 2>&1`;
     return { line, wrapper: { path: wrapperPath, content } };
 }
 const CRON_WRAPPER_PREFIX = ".akm-cron-wrapper-";
@@ -360,7 +363,11 @@ export function extractCronInvocation(body) {
     let commandStart = 5;
     while (commandStart < fields.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(fields[commandStart]))
         commandStart += 1;
-    const redirectIndex = fields.indexOf(">>", commandStart);
+    // #951: newly-installed rows redirect with `>` (truncate); tolerate `>>`
+    // (append) too, since that's what every row written before this change —
+    // including ones a still-running older akm binary installs during a
+    // rolling upgrade — looks like on disk.
+    const redirectIndex = fields.findIndex((field, index) => index >= commandStart && (field === ">" || field === ">>"));
     if (redirectIndex === -1)
         return undefined;
     const tail = fields.slice(commandStart, redirectIndex);

package/dist/tasks/run/run-native-task.js

@@ -145,6 +145,23 @@ export async function runNativeTask(input) {
     const logLines = [header];
     const dbLines = [{ line: header }];
     let exitCode = null;
+    // #956: the task runner's OWN process (`akm task run`, launched by cron /
+    // launchd / schtasks, or forwarded a SIGTERM by the published launcher)
+    // had no way to end its detached, own-process-group
+    // child (spawned by `runManagedSubprocess` for the group-kill guarantee
+    // above) — a timeout or SIGTERM to the direct child would reap the whole
+    // group, but nothing tied THIS process's own termination to that same
+    // ladder, so a signal to the runner left its child running as an orphan.
+    // Aborting `runManagedSubprocess` here runs its normal SIGTERM→SIGKILL
+    // kill ladder against the child's process group.
+    const abortController = new AbortController();
+    const forwardTerminationSignal = (signal) => {
+        abortController.abort(new Error(`task runner received ${signal}`));
+    };
+    const onSigterm = () => forwardTerminationSignal("SIGTERM");
+    const onSigint = () => forwardTerminationSignal("SIGINT");
+    process.once("SIGTERM", onSigterm);
+    process.once("SIGINT", onSigint);
     try {
         // Re-resolve the authored root/cwd immediately before spawn so a
         // symlink, ancestor, bundle-root, or directory/file swap cannot redirect
@@ -159,7 +176,9 @@ export async function runNativeTask(input) {
         }
         // Managed spawn (src/core/subprocess.ts): process-GROUP kill so a timeout
         // reaps the whole command tree (no orphans), and a SIGTERM→SIGKILL ladder
-        // so a child that ignores SIGTERM can't wedge the run forever.
+        // so a child that ignores SIGTERM can't wedge the run forever. `signal`
+        // ties that same ladder to a termination signal received by this
+        // process itself (#956), not only to the timeout.
         const result = await runManagedSubprocess(cmd, {
             capture: true,
             cwd: task.cwd,
@@ -178,6 +197,7 @@ export async function runNativeTask(input) {
             // layer on top and break any resolved path containing a space.
             windowsVerbatimArguments: task.kind === "shell" && task.shell === "cmd",
             timeoutMs,
+            signal: abortController.signal,
             ...(input.spawnFn ? { spawnFn: input.spawnFn } : {}),
             ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
             ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
@@ -221,6 +241,8 @@ export async function runNativeTask(input) {
         exitCode = 1;
     }
     finally {
+        process.off("SIGTERM", onSigterm);
+        process.off("SIGINT", onSigint);
         if (materialized)
             cleanupFrozenScript(materialized);
     }

package/dist/tasks/run/run-workflow-task.js

@@ -187,6 +187,22 @@ export async function runWorkflowTask(input) {
  * here is a *compile* error rather than silently collapsing to "completed".
  * The previous silent `default: "completed"` is preserved only for the
  * `undefined` (no-detail) case, which is handled up front.
+ *
+ * #943: is `undefined` reachable from a timeout (i.e. can a wedged/killed run
+ * produce `status: "completed"`)? No. This function is only ever called as
+ * `mapWorkflowStatus(detail?.status)` behind `failure ? "failed" : ...` in
+ * {@link runWorkflowTask} — `failure` is `error ?? gateError ?? timeoutError`,
+ * and `detail` is left `undefined` only in the `catch` branch that also sets
+ * `error` (making `failure` truthy). So whenever this function runs, either
+ * `failure` already short-circuited the caller to `"failed"` without
+ * consulting it, or the run awaited successfully and `detail` (thus
+ * `detail.status`) is guaranteed set by `RunWorkflowResult["run"]`, a
+ * required field. `status === undefined` is therefore unreachable today; it
+ * stays mapped to `"completed"` defensively rather than thrown on, since a
+ * literal `undefined` can only mean "the runtime told us nothing went
+ * wrong" — never observed from `runWorkflowStepsImpl`, but if some future
+ * caller ever passes it, failing loudly on "no evidence of failure" would be
+ * a worse trade than the status quo.
  */
 function mapWorkflowStatus(status) {
     // No run detail → treat as completed (unchanged from the prior silent default).