akm-cli 0.9.14 → 0.9.15-beta.1

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-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-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).

package/dist/workflows/exec/child-workflow.js

@@ -53,7 +53,7 @@
  * `driveRun` itself is never exported (B-N5's "no second executor" holds).
  */
 import { randomUUID } from "node:crypto";
-import { UsageError } from "../../core/errors.js";
+import { TransientError } from "../../core/errors.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
 import { validateWorkflowParams } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
@@ -76,7 +76,7 @@ function errorMessage(err) {
 }
 /** `acquireRunLease`'s exact refusal shape (run-workflow.ts) — matched by text, since this module cannot import that private helper. */
 function isLeaseBusyError(err) {
-    return err instanceof UsageError && err.message.includes("is already being driven by engine");
+    return err instanceof TransientError && err.message.includes("is already being driven by engine");
 }
 /** §3.4's exact `child_workflow_failed` message. */
 function childWorkflowFailedMessage(input) {

package/dist/workflows/exec/dispatch-redaction.js

@@ -15,23 +15,24 @@
  * @module workflows/exec/dispatch-redaction
  */
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
-import { lookupApiKeyFileValue } from "../../integrations/agent/engine-resolution.js";
+import { lookupApiKeyFileValue, lookupApiKeySecretRefValue } from "../../integrations/agent/engine-resolution.js";
 /**
  * Every exact value that must never survive into the journal from ONE frozen
  * dispatch: the resolved `env` bindings injected into the child, the selected
- * engine's (and its SDK fallback's) credential — an env value, or a
- * file-backed one (#905) — and any `envPassthrough` value the redaction
- * policy does not consider safe to expose.
+ * engine's (and its SDK fallback's) credential — an env value, a file-backed
+ * one (#905), or a secret-store-backed one (#953) — and any `envPassthrough`
+ * value the redaction policy does not consider safe to expose.
  *
  * Shared by the unit path and the gate-judge path. There is deliberately ONE
  * collector: a second, parallel implementation is exactly how a dispatch path
  * silently loses the scrub.
  *
- * The credential values are read from `process.env` (or disk, for a file-
- * backed one) AT CALL TIME, so a caller must collect no earlier than the
- * dispatch whose outcome it scrubs. A snapshot taken when the dispatch was
- * merely *planned* can predate a credential the dispatch then resolves live,
- * leaving the exact value it must remove out of the set.
+ * The credential values are read from `process.env` (or disk / the secret
+ * store, for a file- or store-backed one) AT CALL TIME, so a caller must
+ * collect no earlier than the dispatch whose outcome it scrubs. A snapshot
+ * taken when the dispatch was merely *planned* can predate a credential the
+ * dispatch then resolves live, leaving the exact value it must remove out of
+ * the set.
  */
 export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
     const values = new Set([...Object.values(env ?? {}), ...(dispatch.sensitiveValues ?? [])]);
@@ -51,6 +52,12 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
                 if (value)
                     values.add(value);
             }
+            // #953: secret-store-backed credential — same best-effort rationale.
+            if (runner.apiKeySecretRef) {
+                const value = lookupApiKeySecretRefValue(runner.apiKeySecretRef);
+                if (value)
+                    values.add(value);
+            }
             return;
         }
         for (const name of runner.profile.envPassthrough ?? []) {
@@ -69,6 +76,11 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
                 if (value)
                     values.add(value);
             }
+            if (runner.fallbackApiKeySecretRef) {
+                const value = lookupApiKeySecretRefValue(runner.fallbackApiKeySecretRef);
+                if (value)
+                    values.add(value);
+            }
         }
     };
     addCredential(dispatch.runner);

package/dist/workflows/exec/run-workflow.js

@@ -15,7 +15,7 @@
  * full design history behind each of these invariants.
  */
 import { randomUUID } from "node:crypto";
-import { UsageError } from "../../core/errors.js";
+import { TransientError, UsageError } from "../../core/errors.js";
 import { withMaintenanceStartBarrierAsync } from "../../core/maintenance-barrier.js";
 import { disposeDispatchResources } from "../../integrations/agent/runner-dispatch.js";
 import { withWorkflowRunsConnection, withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
@@ -183,16 +183,17 @@ function leaseExpiry() {
     return new Date(Date.now() + RUN_LEASE_TTL_MS).toISOString();
 }
 /**
- * Atomically claim the run lease or refuse with a UsageError naming the
- * current holder + expiry. The single-UPDATE claim in the repository is the
- * arbiter — two racing invocations cannot both win.
+ * Atomically claim the run lease or refuse with a TransientError naming the
+ * current holder + expiry (#948 addendum — moved off UsageError, exit 75).
+ * The single-UPDATE claim in the repository is the arbiter — two racing
+ * invocations cannot both win.
  */
 async function acquireRunLease(runId, holder) {
     await withMaintenanceStartBarrierAsync(() => withWorkflowRunsRepo((repo) => {
         if (repo.acquireEngineLease(runId, holder, leaseExpiry(), new Date().toISOString()))
             return;
         const row = repo.getRunById(runId);
-        throw new UsageError(`Workflow run ${runId} is already being driven by engine ${row?.engine_lease_holder ?? "(unknown)"} ` +
+        throw new TransientError(`Workflow run ${runId} is already being driven by engine ${row?.engine_lease_holder ?? "(unknown)"} ` +
             `(run lease expires ${row?.engine_lease_until ?? "(unknown)"}). 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/workflows/runtime/runs.js

@@ -4,7 +4,7 @@
 import { randomUUID } from "node:crypto";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
-import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { ConfigError, NotFoundError, TransientError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
 import { insertEventOnce } from "../../storage/repositories/events-repository.js";
@@ -127,6 +127,25 @@ export async function startWorkflowRun(ref, params = {}, options) {
         // per the workflow-agent check-in ADR) so a stalled run can be
         // re-targeted with a `continue` directive. The agent harness + session id
         // are already resolved above (agentHarness/agentSessionId, from #501).
+        // #942: an active run of this ref may already exist in a DIFFERENT
+        // scope — the incident this issue reports (a scheduled task's cwd and a
+        // human's shell hash to different scope keys, so each believed it held
+        // no active run and each started one). The scope-local uniqueness guard
+        // stays scope-local (a documented, deliberate per-project partition —
+        // see storage-locations.md); this only warns, once, so the operator can
+        // resume or abandon the other run instead of silently accumulating a
+        // second one. `findActiveRunOutsideScope` excludes the caller's own
+        // scope IN SQL (never merely post-filtered) so the caller's own active
+        // run can never sort first under `LIMIT 1` and mask a genuinely different
+        // scope's run — the failure mode a same-scope-inclusive query plus a
+        // post-filter has with `--new`/`--force`.
+        const crossScopeActive = repo.findActiveRunOutsideScope(workflowRefs, scopeKey);
+        const crossScopeWarning = crossScopeActive
+            ? `Workflow ${asset.ref} already has an active run in another scope ` +
+                `(id ${crossScopeActive.id}, started ${crossScopeActive.created_at}, scope ${crossScopeActive.scope_key ?? "unknown"}); ` +
+                `starting a separate run here. Resume it from anywhere with "akm workflow run ${crossScopeActive.id}" ` +
+                `or free it with "akm workflow abandon ${crossScopeActive.id}".`
+            : undefined;
         repo.publishWorkflowRunV4({
             workflowRefs,
             ...(options?.force ? { force: true } : {}),
@@ -157,6 +176,8 @@ export async function startWorkflowRun(ref, params = {}, options) {
             revalidateSources: () => frozen.sourceCollector.revalidate(),
         });
         const result = await getWorkflowStatus(runId);
+        if (crossScopeWarning)
+            result.warnings = [...(result.warnings ?? []), crossScopeWarning];
         // #13: params are declared non-secret (they are copied verbatim into every
         // unit prompt and hashed into the unit identity, so they cannot be redacted
         // without breaking replay determinism). Surface a loud, best-effort warning
@@ -193,7 +214,7 @@ export async function getWorkflowStatus(runId, opts) {
     });
 }
 export async function listWorkflowRuns(input) {
-    const scopeKey = getCurrentWorkflowScopeKey();
+    const scopeKey = input?.allScopes === true ? null : getCurrentWorkflowScopeKey();
     const activeOnly = input?.activeOnly === true;
     const includeChildren = input?.includeChildren === true;
     if (input?.workflowRef === undefined) {
@@ -205,6 +226,7 @@ export async function listWorkflowRuns(input) {
                 ...(includeChildren ? { includeChildren: true } : {}),
             })
                 .map(toWorkflowRunSummary),
+            scopeKey,
         }));
     }
     const exactRef = input.workflowRef.trim();
@@ -227,6 +249,7 @@ export async function listWorkflowRuns(input) {
                 throw error;
             return {
                 runs: exactRows.filter((row) => !activeOnly || row.status === "active").map(toWorkflowRunSummary),
+                scopeKey,
             };
         }
         if (!(error instanceof NotFoundError))
@@ -241,6 +264,7 @@ export async function listWorkflowRuns(input) {
             ...(includeChildren ? { includeChildren: true } : {}),
         })
             .map(toWorkflowRunSummary),
+        scopeKey,
     }));
 }
 export async function getNextWorkflowStep(specifier, params, options) {
@@ -558,7 +582,8 @@ async function resolveRunSpecifier(repo, specifier, params, parameterFlags, forc
     catch (error) {
         if (detached) {
             if (hasParameters) {
-                throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active.`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${detached.id}" to free up ${specifier} first.`);
+                throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active ` +
+                    `(id ${detached.id}, scope ${scopeKey}).`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${detached.id}" to free up ${specifier} first.`);
             }
             return { run: detached, autoStarted: false, resumed: true };
         }
@@ -570,7 +595,8 @@ async function resolveRunSpecifier(repo, specifier, params, parameterFlags, forc
     const active = forceNew ? undefined : repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
     if (active) {
         if (hasParameters) {
-            throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active.`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${active.id}" to free up ${ref} first.`);
+            throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active ` +
+                `(id ${active.id}, scope ${scopeKey}).`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${active.id}" to free up ${ref} first.`);
         }
         return { run: active, autoStarted: false, resumed: true };
     }
@@ -808,7 +834,9 @@ function assertLeaseAllowsSpineAdvance(run, leaseHolder) {
         return;
     if (run.engine_lease_until < new Date().toISOString())
         return; // expired ⇒ claimable, not live
-    throw new UsageError(`Workflow run ${run.id} is being driven by engine ${run.engine_lease_holder} ` +
+    // #948 addendum: moved off UsageError (exit 75, not exit 2) — a held lease
+    // is ordinary contention, not a bad command line.
+    throw new TransientError(`Workflow run ${run.id} is being driven by engine ${run.engine_lease_holder} ` +
         `(run lease expires ${run.engine_lease_until}). The engine owns the step spine while it runs — ` +
         `wait for it to finish or for the lease to expire before advancing steps manually.`, "RUN_LEASE_HELD");
 }

package/docs/migration/release-notes/0.9.15.md

@@ -0,0 +1,52 @@
+Migration notes for akm v0.9.15
+
+`RUN_LEASE_HELD` (a workflow run-lease refusal) and the new
+`STATE_DB_CONTENDED` (state.db write contention) now exit 75 (`EX_TEMPFAIL`)
+instead of exit 2 and exit 70 respectively. Both are unrelated to a bad command
+line — they mean "another akm process is using this database or lease right
+now, retry shortly." If a script or scheduler wrapper special-cases exit 2 to
+detect a held lease, switch it to exit 75, or read the JSON envelope's `code`
+field instead.
+
+The six shipped scheduled `improve` task templates now run with
+`--require-engines`, which aborts (exit 78) before any index work when a
+process's engine or credential cannot be resolved in the task's own
+environment, instead of silently skipping that process. This only affects new
+installs and new `akm setup` task seeding — an existing install's
+already-materialized task files are not rewritten. To get the same protection
+on an existing scheduled task, add `--require-engines` to its `run:` command
+yourself, then run `akm task sync`.
+
+`akm health --no-probe` now also skips the `cli-version` update check (a GitHub
+release lookup), alongside the engine-reachability checks it already skipped.
+An air-gapped or offline host's existing `--no-probe` habit now suppresses both
+network calls with no config change needed.
+
+Thinking-control wire forms (`chat_template_kwargs.enable_thinking` and
+`enable_thinking`) are now sent for every provider whenever `enableThinking`
+resolves to a value, not only when `provider: "vllm"` is set. If your engine
+sits behind Bifrost and the gateway does not honor either form, also set
+`reasoningEffort: "none"` on that engine. If your engine talks to a strict
+hosted API that rejects unknown request keys, leave `enableThinking` unset on
+that engine so neither wire form is sent.
+
+An `embedding.model` rename no longer forces a full re-embed by itself: `akm
+index` re-embeds a small sample first and keeps the existing vectors when they
+still verify against the endpoint. `akm index --reembed` forces a full re-embed
+when you don't trust that verdict. `akm index --skip-if-locked` lets a
+scheduled or opportunistic run step aside instead of contending with a rebuild
+already in progress; the shipped `index-refresh` scheduled task already passes
+it.
+
+There is no `embedding.concurrency` config field. Embedding throughput is
+tuned by `embedding.batchSize` (documents per request) and
+`embedding.maxTokens`/`contextLength` (token budget per request); the number of
+requests in flight is fixed (1 for a loopback endpoint, 2 for a remote one).
+
+A config file can now inherit a shared base via `extends: <path|bundle//path>`,
+deep-merging under the local file so local keys always win. `akm config diff
+<path|bundle//path>` prints every leaf that differs between this instance's
+effective config and another config file or bundle-relative file. `akm config
+unset` now refuses to unset a key whose value comes only from an
+`extends`-inherited base, naming the source, since there would be nothing local
+to remove.

package/docs/migration/release-notes/README.md

@@ -7,6 +7,10 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
+- [0.9.15](0.9.15.md) — exit-code 75 for lease/state.db contention,
+  `--require-engines` scheduled task templates, `--no-probe` cli-version
+  skip, thinking-control wire forms, embedding re-embed safety, and
+  `extends` config inheritance
 - [0.9.14](0.9.14.md) — index v22-to-v23 derived-cache rebuild, lexical
   fragments, and collapse-detector canary re-minting
 - [0.9.2](0.9.2.md) — task source v4 migration, workflow source IR v1 and