akm-cli 0.9.14 → 0.9.15-beta.2

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,133 @@
+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.
+
+`embedding.concurrency` (positive integer, 1-16) overrides the number of
+embedding requests kept in flight at once, which otherwise defaults to 1 for
+a loopback endpoint and 2 for a remote one. Set it only for an endpoint that
+genuinely serves parallel requests — a local model server started with a
+multi-slot flag (llama.cpp's `--parallel N`, vLLM) — since the default
+already protects an ordinary single-slot server from reload-thrash.
+Embedding throughput is still tuned first by `embedding.batchSize`
+(documents per request) and `embedding.maxTokens` (token
+budget per request); the concurrency override is a second lever for a
+server that can actually use it.
+
+`embedding.timeoutMs` bounds each embedding request (default 120s, up from a
+prior fixed 30s that cut off a slow local model server mid-response). It is
+the budget for a request at the full token budget — a smaller request gets a
+proportionally smaller timeout, so a dead endpoint is still detected in
+seconds on the common case of small documents. A request TIMEOUT no longer
+drops its batch immediately: akm now backs off (5s, doubling, capped at 60s)
+and retries the same request once, since field evidence showed the endpoint
+keeps computing an abandoned request regardless of the client giving up; a
+second timeout splits the batch in half and retries each half the same way,
+down to individual documents, and a single document that still times out is
+finally skipped. After 3 consecutive failures at single-document size
+(timeout or network error), or 3 consecutive network errors at any size —
+never a batch rejected only for exceeding the endpoint's context window —
+`akm index`'s embedding phase stops dispatching further requests and reports
+failure instead of grinding through every remaining batch against a dead
+endpoint — batches already committed are kept, and a rerun picks up where it
+left off.
+
+`akm bundle update` now durably commits its embedding pass instead of
+nesting it inside its own transaction: earlier releases ran the embedding
+phase inside the same transaction as content/lock/index/state, so every
+per-batch commit landed as an unobservable SAVEPOINT and a SIGKILL mid-run
+lost every embedding of the update, not just the one in flight. The
+embedding phase now runs on its own connection after the update's own
+commit; a failing pass (provider down) still leaves the update itself
+successful, with the new `index.semanticStatus` field on `akm bundle
+update`'s response the only sign semantic search fell behind.
+
+The published `akm`/`akm-migrate` launchers now forward SIGTERM/SIGINT/
+SIGHUP to their child and exit alongside it, instead of leaving the child
+running as an orphan when only the launcher is signaled. No action needed —
+this is a drop-in fix for anyone running `akm` under a scheduler,
+supervisor, or hook that can time out or kill the launcher process
+directly.
+
+`embedding.maxInputTokens` (default 512) now caps how much of a single
+document's text is sent to the embedding provider, truncating to the head
+instead of ever failing a whole batch over one oversized document.
+
+- An existing install's already-stored vectors are untouched and stay
+  valid — this only changes what happens for entries embedded *after*
+  upgrading.
+- New embeddings (any entry indexed for the first time, or re-indexed after
+  a content change) go through the new 512-token cap by default. If you
+  were relying on documents longer than ~2000 characters being embedded in
+  full, set `embedding.maxInputTokens` higher in `config.json`.
+- `akm index --reembed` re-embeds every entry under the new cap — run it if
+  you want your entire existing index rebuilt against the new default (or a
+  custom `embedding.maxInputTokens` you've set).
+- `embedding.contextLength` is Ollama's `num_ctx` only now; it no longer
+  also sets the per-request token budget (`embedding.maxTokens`). If you had
+  set `contextLength` specifically to control request batching (not your
+  Ollama server's context window), set `embedding.maxTokens` instead.
+
+`akm index --full` and an index-generation bump no longer re-embed
+unchanged content: vectors about to be discarded are salvaged and handed
+back to unchanged entries at the start of the next embedding pass instead
+of every upgrade re-embedding the whole corpus once. No action needed —
+this is automatic; `akm index --reembed` still forces a full re-embed when
+you don't trust the salvaged vectors.
+
+A field report suspected `akm index` was sending embedding requests with no
+`Authorization` header despite `embedding.apiKey` being set to a
+`secret://` reference. Auditing every path that builds an embedding request
+found all of them already resolve `secret://` through the same store
+lookup, now pinned by integration and contract tests — this was not a bug
+in the code as it stands. `akm index` now prints one line before its first
+provider request naming the endpoint, model, and credential SOURCE (never
+the value), e.g. `[embed] endpoint http://.../v1/embeddings, model
+nomic-embed; credential: secret://lab-api-key (store)`. If you run an
+embedding gateway that enforces auth and still see unauthenticated requests
+after upgrading, compare this line's endpoint and credential source against
+what the gateway's own request log shows for the same request — a
+mismatch there (not in this line) is the next place to look.
+
+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,11 @@ 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
+  cross-rebuild vector salvage, launcher signal forwarding, a default
+  per-document embedding cap, 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