akm-cli 0.9.14 → 0.9.15-beta.2

package/dist/core/config/schema/embedding.js

@@ -33,10 +33,51 @@ export const EmbeddingConnectionConfigSchema = z
     // `akm index` when ensureSchema rejects it (§24.2 "Semantic" gate).
     dimension: positiveInt.max(4096).optional(),
     localModel: z.string().min(1).optional(),
+    /**
+     * Per-document token cap applied BEFORE batching (default 512,
+     * `DEFAULT_MAX_INPUT_TOKENS` in `src/llm/embedders/remote.ts`, #956).
+     * The materializer truncates a document's embedded text to
+     * this cap (head only, unicode-safe) instead of skipping it outright, so
+     * one oversized entry can no longer fail a whole batch. Distinct from
+     * `maxTokens` below, which bounds a whole HTTP REQUEST (many documents);
+     * this bounds one DOCUMENT.
+     */
+    maxInputTokens: positiveInt.optional(),
+    /**
+     * Client-side per-request token budget — how many documents' estimated
+     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 8000
+     * in `src/llm/embedders/remote.ts`). With the 512-token `maxInputTokens`
+     * cap above, a request carries about 16 documents by default.
+     */
     maxTokens: positiveInt.optional(),
     batchSize: positiveInt.optional(),
     chunkSize: positiveInt.optional(),
+    /**
+     * Ollama's `num_ctx` ONLY (#956) — sent verbatim as
+     * `options.num_ctx` on the native `/api/embed` request. It no longer also
+     * feeds the client-side request token budget (`maxTokens` above): the two
+     * used to share this one field, so setting it for the server's context
+     * window silently changed request batching too.
+     */
     contextLength: positiveInt.optional(),
     ollamaOptions: EmbeddingOllamaOptionsSchema.optional(),
+    /**
+     * Per-request timeout in milliseconds for a remote embedding request
+     * (default 120_000, `DEFAULT_EMBEDDING_TIMEOUT_MS` in
+     * `src/llm/embedders/remote.ts`). The prior fixed 30s cut off a slow
+     * local model server on a large token-bounded batch mid-response, with
+     * no retry — every batch that hit it was silently dropped (#954).
+     */
+    timeoutMs: positiveInt.optional(),
+    /**
+     * Overrides the fixed in-flight request window (#954, added after field
+     * evidence from multi-slot local servers). Bounded 1-16. Unset keeps
+     * today's default: 1 for a loopback endpoint, 2 for a remote one
+     * (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`). Set it
+     * only for an endpoint that genuinely serves parallel requests (llama.cpp
+     * `--parallel N`, vLLM) — request SIZE (`batchSize`, `maxTokens`/
+     * `contextLength`) remains the first throughput lever.
+     */
+    concurrency: positiveInt.max(16).optional(),
 })
     .passthrough();

package/dist/core/env-secret-ref.js

@@ -16,13 +16,60 @@ import path from "node:path";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
-import { assetPathForName } from "./asset/asset-placement.js";
+import { assetPathForName, deriveCanonicalAssetName } from "./asset/asset-placement.js";
 import { displayRef, isFullRefInput, parseRefInput } from "./asset/resolve-ref.js";
 import { isWithin } from "./common.js";
 import { loadConfig } from "./config/config.js";
 import { NotFoundError, UsageError } from "./errors.js";
 import { resolveMutationTarget } from "./mutation-target.js";
+import { sensitiveMarkerPath } from "./sensitive-marker-path.js";
 import { formatRefForMessage, withWriteTargetMutation } from "./write-source.js";
+export { sensitiveMarkerPath } from "./sensitive-marker-path.js";
+/**
+ * Walk each stash's env files and return one entry per `.env` file, using the
+ * env asset spec's canonical-name logic (e.g. `env/team/prod.env` →
+ * `env/team/prod`, `env/team/.env` → `env/team/default`). Moved here from
+ * `commands/env/env-cli.ts` (#950) so `commands/health` can reuse it to name
+ * which env asset supplies a credential's variable — pure move, `akm env
+ * list`'s behaviour is unchanged. `listKeysFn` stays injected (rather than a
+ * static import of `commands/env/env.ts`) so this core module never depends
+ * upward on the commands layer. `config` defaults to the real `loadConfig()`
+ * (unchanged default for `akm env list`); `commands/health` passes its own
+ * injected/resolved config so a test-supplied `loadConfig` seam is honoured
+ * instead of this always re-reading the real config/sources.
+ */
+export function listEnvsRecursive(listKeysFn, config = loadConfig()) {
+    const result = [];
+    for (const source of resolveSourceEntries(undefined, config)) {
+        const root = path.join(source.path, "env");
+        if (!fs.existsSync(root))
+            continue;
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (entry.name !== ".env" && !entry.name.endsWith(".env"))
+                    continue;
+                const canonical = deriveCanonicalAssetName("env", root, full);
+                if (!canonical)
+                    continue;
+                // Skip sensitive envs: a sibling .sensitive marker file suppresses listing.
+                const markerPath = sensitiveMarkerPath(full, "env");
+                if (fs.existsSync(markerPath))
+                    continue;
+                const { keys } = listKeysFn(full);
+                result.push({ ref: makeEnvRef(canonical, source, config), path: full, keys });
+            }
+        };
+        walk(root);
+    }
+    return result;
+}
 /**
  * The `vault` asset type was removed in 0.9.0. The env/secret input path no
  * longer routes through the legacy stored-ref parser (which carries the removal
@@ -91,10 +138,17 @@ export function findEnvSource(origin, type, name) {
     }
     return named;
 }
-export function makeEnvRef(name, source) {
+/**
+ * `config` defaults to the real `loadConfig()`, same as {@link displayDefaultBundle}.
+ * `listEnvsRecursive` threads its own (possibly injected) config through here so a
+ * caller-supplied config governs ref display the same way it governs which stashes
+ * get walked — otherwise this would silently fall back to reading the real config a
+ * second time even when the walk itself honoured an injected one.
+ */
+export function makeEnvRef(name, source, config = loadConfig()) {
     // F4b output-spelling flip: `env/name` in the primary stash, `bundle//env/name`
     // for a slug-clean named source.
-    return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source));
+    return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source, config));
 }
 /**
  * Resolve an env ref to an absolute `.env` path. Accepts the `env/<name>`
@@ -132,8 +186,7 @@ export function makeSecretRef(name, source) {
     // `bundle//secrets/name` for a slug-clean named source.
     return displayRef({ type: "secret", name, bundleId: source?.registryId }, displayDefaultBundle(source));
 }
-function displayDefaultBundle(source) {
-    const config = loadConfig();
+function displayDefaultBundle(source, config = loadConfig()) {
     if (config.defaultBundle || !source)
         return config.defaultBundle;
     const primary = resolveSourceEntries(undefined, config)[0];

package/dist/core/errors.js

@@ -77,7 +77,11 @@ const USAGE_HINTS = {
     WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — a frozen plan this akm cannot execute is not re-executable in place.",
     // P3b (docs/plans/specs/p3b-child-executor.md §4.3).
     WORKFLOW_OUTPUT_INVALID: "Check each `outputs:` entry's `from:` against the step artifact it names, and its `schema:` against the value that step actually promotes.",
+};
+/** Default hint for each TransientErrorCode. */
+const TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
+    STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {
@@ -89,6 +93,7 @@ const NOT_FOUND_HINTS = {
     // for a mistyped id, which points at the wrong thing entirely.
     PROPOSAL_NOT_FOUND: "Run `akm proposal list` to see pending proposals and their ids.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
+    IMPROVE_RUN_NOT_FOUND: "Run `akm improve` first, or `akm improve report --since 30d` to see recent run ids in `runIds`.",
 };
 /**
  * Base class for all akm-thrown, classified errors. Carries the `kind`
@@ -131,6 +136,31 @@ export class UsageError extends AkmError {
         return this._hint ?? USAGE_HINTS[this.code];
     }
 }
+/**
+ * Raised when a condition is ordinary, retryable contention rather than a
+ * bad command line or a genuine failure — another akm process holds a lock
+ * or is writing state.db right now. Distinct from `UsageError` (#948
+ * addendum, dev-team field review 2026-09-09): schedulers classify exit 2 as
+ * "fix the command line", so contention needs its own exit code (75,
+ * sysexits EX_TEMPFAIL) a cron wrapper can branch on to retry instead of
+ * alerting.
+ */
+export class TransientError extends AkmError {
+    kind = "transient";
+    code;
+    _hint;
+    constructor(msg, code, hint) {
+        super(msg);
+        this.name = "TransientError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? TRANSIENT_HINTS[this.code];
+    }
+}
 /** Raised when a requested resource (asset, entry, file) is not found. */
 export class NotFoundError extends AkmError {
     kind = "not-found";

package/dist/core/file-lock.js

@@ -120,9 +120,36 @@ function releaseLockRaw(lockPath) {
 export function tryAcquireLockSync(lockPath, payload) {
     return withLockOperationMutex(lockPath, () => tryAcquireLockRaw(lockPath, payload));
 }
-/** Build a PID-bearing payload with a unique token for one acquisition attempt. */
+/**
+ * Best-effort launcher pid from `AKM_LAUNCHER_PID` (set by
+ * `scripts/node-runtime/akm`/`akm-migrate`, #956) — undefined when unset,
+ * empty, or not a positive integer (never trust an ambient env var blindly
+ * into a lock message). Also the gate the parent-death watchdog
+ * (`core/parent-watchdog.ts`) uses to stay inert outside a launcher-managed
+ * run.
+ */
+export function launcherPidFromEnv() {
+    const raw = process.env.AKM_LAUNCHER_PID;
+    if (!raw)
+        return undefined;
+    const pid = Number.parseInt(raw, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+/**
+ * Build a PID-bearing payload with a unique token for one acquisition attempt.
+ * Adds `launcherPid` (#956) whenever this process is running under the
+ * published launcher, so a lock's holder can be identified by the pid every
+ * process listing and task log actually shows (the launcher's) as well as
+ * the pid that holds the lock (the bun/node child).
+ */
 export function createLockPayload(metadata = {}) {
-    return JSON.stringify({ ...metadata, pid: process.pid, lockId: randomUUID() });
+    const launcherPid = launcherPidFromEnv();
+    return JSON.stringify({
+        ...metadata,
+        pid: process.pid,
+        ...(launcherPid !== undefined ? { launcherPid } : {}),
+        lockId: randomUUID(),
+    });
 }
 /**
  * Inspect an existing sentinel at `lockPath` without modifying it.
@@ -153,17 +180,17 @@ export function probeLock(lockPath, opts) {
         return { state: "absent" };
     const { rawContent, identity } = snapshot;
     const ageMs = Date.now() - identity.mtimeMs;
-    const holderPid = extractHolderPid(rawContent);
+    const { holderPid, launcherPid } = extractLockIdentity(rawContent);
     if (holderPid === undefined) {
         return { state: "stale", reason: "invalid_pid", ageMs, rawContent, identity };
     }
     if (!isProcessAlive(holderPid)) {
-        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent, identity };
+        return { state: "stale", reason: "pid_dead", holderPid, launcherPid, ageMs, rawContent, identity };
     }
     if (opts?.staleAfterMs !== undefined && ageMs > opts.staleAfterMs) {
-        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent, identity };
+        return { state: "stale", reason: "age_exceeded", holderPid, launcherPid, ageMs, rawContent, identity };
     }
-    return { state: "held", holderPid, ageMs, rawContent, identity };
+    return { state: "held", holderPid, launcherPid, ageMs, rawContent, identity };
 }
 /**
  * Revalidate and quarantine the probed sentinel while holding the same operation
@@ -254,25 +281,32 @@ export function releaseLock(ownership) {
     });
 }
 /**
- * Extract a PID from a sentinel body. Accepts the two shapes used across
- * the codebase: a bare numeric string (config-io, vault, lockfile) and
- * a JSON object with a `pid` field (improve). Returns undefined when the
- * body is unparseable or yields a non-positive integer.
+ * Extract a holder pid, and (#956) a launcher pid when the payload recorded
+ * one, from a sentinel body. Accepts the two shapes used across the
+ * codebase: a bare numeric string (config-io, vault, lockfile — never
+ * carries a `launcherPid`) and a JSON object with `pid`/`launcherPid` fields
+ * (`createLockPayload`). `holderPid` is undefined when the body is
+ * unparseable or yields a non-positive integer; `launcherPid` is undefined
+ * whenever the payload has none, independent of whether `holderPid` parsed.
  */
-function extractHolderPid(content) {
+function extractLockIdentity(content) {
     const trimmed = content.trim();
     if (!trimmed)
-        return undefined;
+        return {};
     if (trimmed.startsWith("{")) {
         try {
             const parsed = JSON.parse(trimmed);
             const pid = typeof parsed.pid === "number" ? parsed.pid : Number.NaN;
-            return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+            const rawLauncherPid = typeof parsed.launcherPid === "number" ? parsed.launcherPid : Number.NaN;
+            return {
+                holderPid: Number.isInteger(pid) && pid > 0 ? pid : undefined,
+                launcherPid: Number.isInteger(rawLauncherPid) && rawLauncherPid > 0 ? rawLauncherPid : undefined,
+            };
         }
         catch {
-            return undefined;
+            return {};
         }
     }
     const pid = Number.parseInt(trimmed, 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    return { holderPid: Number.isInteger(pid) && pid > 0 ? pid : undefined };
 }

package/dist/core/improve-result.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { cloneExecutionJsonObject } from "../execution/json.js";
 import { isRecord } from "./common.js";
+import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "./config/engine-semantics.js";
 const COMMON_FIELDS = [
     "schemaVersion",
     "ok",
@@ -17,6 +18,7 @@ const COMMON_FIELDS = [
     "plannedRefs",
     "plan",
     "actions",
+    "skippedProcesses",
     "distillSkipped",
     "validationFailures",
     "schemaRepairs",
@@ -47,6 +49,7 @@ const COMMON_FIELDS = [
     "sync",
     "writtenPaths",
     "terminated",
+    "usageReport",
 ];
 const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
 function fail(message) {
@@ -179,6 +182,50 @@ function validateProactivePlan(value) {
         fail("plan.proactive.selected must equal plan.proactive.selectedRefs.length");
     }
 }
+/** #947 — plan.processes: one row per IMPROVE_PROCESS_ENGINE_CAPABILITIES name, plus an optional "triage.judgment" row. */
+function validateProcessRoutingRows(value) {
+    if (!Array.isArray(value))
+        fail("plan.processes must be an array");
+    const canonicalNames = Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES);
+    const engineKinds = new Set(["llm", "agent", "sdk"]);
+    const seen = new Set();
+    for (const row of value) {
+        if (!isRecord(row))
+            fail("plan.processes entries must be objects");
+        requireExactFields(row, new Set(["process", "enabled", "engine", "model", "engineKind", "notices", "unavailable", "eligibleRefs"]));
+        if (typeof row.process !== "string" ||
+            !(canonicalNames.includes(row.process) || row.process === "triage.judgment")) {
+            fail("plan.processes.process is invalid");
+        }
+        if (seen.has(row.process))
+            fail(`plan.processes must not repeat "${row.process}"`);
+        seen.add(row.process);
+        if (typeof row.enabled !== "boolean")
+            fail("plan.processes.enabled must be a boolean");
+        if (row.engine !== undefined && typeof row.engine !== "string")
+            fail("plan.processes.engine must be a string");
+        if (row.model !== undefined && typeof row.model !== "string")
+            fail("plan.processes.model must be a string");
+        if (row.engineKind !== undefined && (typeof row.engineKind !== "string" || !engineKinds.has(row.engineKind))) {
+            fail("plan.processes.engineKind is invalid");
+        }
+        validateLoweringNotices(row.notices);
+        if (row.unavailable !== undefined) {
+            if (!isRecord(row.unavailable))
+                fail("plan.processes.unavailable must be an object");
+            requireExactFields(row.unavailable, new Set(["configKey", "reason"]));
+            if (typeof row.unavailable.configKey !== "string" || typeof row.unavailable.reason !== "string") {
+                fail("plan.processes.unavailable must contain string configKey and reason");
+            }
+        }
+        if (row.eligibleRefs !== undefined)
+            requireCount(row, "eligibleRefs", "plan.processes entry");
+    }
+    for (const name of canonicalNames) {
+        if (!seen.has(name))
+            fail(`plan.processes must contain exactly one "${name}" row`);
+    }
+}
 function validateImprovePlan(value, dryRun, plannedRefNames) {
     if (!isRecord(value))
         fail("plan must be an object");
@@ -190,6 +237,7 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
         "limits",
         "gates",
         "effectiveRefs",
+        "processes",
         "proactive",
         "consolidation",
         "stages",
@@ -328,6 +376,7 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
     if (value.limits.totalCeiling !== undefined && value.effectiveRefs.length > value.limits.totalCeiling) {
         fail("plan.effectiveRefs cannot exceed plan.limits.totalCeiling");
     }
+    validateProcessRoutingRows(value.processes);
     if (value.proactive !== undefined)
         validateProactivePlan(value.proactive);
     validateConsolidationPlan(value.consolidation);
@@ -392,6 +441,7 @@ function validateCommon(value) {
     }
     for (const field of [
         "actions",
+        "skippedProcesses",
         "validationFailures",
         "schemaRepairs",
         "extract",
@@ -442,6 +492,7 @@ function validateCommon(value) {
         "terminated",
         "plan",
         "deadUrlCoverage",
+        "usageReport",
     ]) {
         if (value[field] !== undefined && !isRecord(value[field]))
             fail(`${field} must be an object`);

package/dist/core/loopback.js

@@ -87,3 +87,20 @@ export function isLoopbackEndpoint(endpoint) {
         return true;
     }
 }
+/**
+ * The lowest-common-denominator concurrency default for an LLM/embedding
+ * endpoint: 1 for a loopback endpoint (a local model server serves one
+ * inference at a time; concurrent requests thrash it — reload thrash, HTTP
+ * 500 "Model reloaded"), 2 for a remote one (enough to overlap request
+ * latency without hammering a rate-limited API). A leaf helper so both
+ * callers — the indexer's LLM enrichment pool (`getDefaultLlmConcurrency`,
+ * `src/indexer/indexer.ts`) and the embedding pool
+ * (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`) — share one
+ * definition instead of mirroring it; `src/llm/embedders/remote.ts` cannot
+ * import `getDefaultLlmConcurrency` directly (`src/indexer/indexer.ts`
+ * already depends on this module transitively through
+ * materialize-embeddings.ts).
+ */
+export function defaultConcurrencyForEndpoint(endpoint) {
+    return isLoopbackEndpoint(endpoint) ? 1 : 2;
+}

package/dist/core/parent-watchdog.js

@@ -0,0 +1,64 @@
+// 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/.
+/**
+ * Parent-death watchdog (#956).
+ *
+ * The published launcher (`scripts/node-runtime/akm`) now forwards SIGTERM to
+ * its child, so a `kill <launcher-pid>` no longer orphans it — but a launcher
+ * that dies WITHOUT delivering a signal (SIGKILL, an out-of-memory kill, a
+ * supervisor that force-removes the process) still reparents the child to
+ * init with nothing to catch. Field evidence: 40 orphaned
+ * `bun …/dist/cli.js` processes over one day, up to 10h old, some created by
+ * a curate hook killing its own launcher on timeout — every akm invocation
+ * under the launcher is exposed to this, not only `akm index`, so this
+ * watchdog runs for every command (wired at the CLI entry point in
+ * `src/cli.ts`), not just index.
+ *
+ * `process.ppid` on POSIX changes the instant the parent exits (the child is
+ * reparented, usually to pid 1) — polling it is the standard orphan-detection
+ * trick when no direct death notification exists. This module owns only the
+ * poll/compare mechanics; the caller's `onOrphaned` decides what "stop"
+ * means. `src/cli.ts` wires it to `process.kill(process.pid, "SIGTERM")`,
+ * reusing the same self-signal every command already has rather than a
+ * second, parallel abort path. Only `akm index`/`improve` register their own
+ * SIGTERM listener (the index command's AbortController in
+ * `commands/sources/stash-cli.ts`) and get a graceful, in-process shutdown
+ * from it. Every other command has no listener of its own, so the runtime's
+ * default disposition terminates it directly — `exit` handlers (lock
+ * release included) do NOT run — and any lock it held is cleared later by
+ * the next acquirer's dead-pid stale-reclaim (`file-lock.ts`), not by
+ * in-process release. Either way the orphaned process stops, which is this
+ * watchdog's actual job.
+ */
+/** Pure comparison seam: true once the observed ppid differs from the one seen at startup. */
+export function isReparented(initialPpid, currentPpid) {
+    return currentPpid !== initialPpid;
+}
+/**
+ * Start polling `getPpid()` every `intervalMs` and invoke `onOrphaned` once,
+ * the first time the observed ppid no longer matches `initialPpid`. The timer
+ * is unref'ed so it never keeps the process alive on its own — a command that
+ * finishes normally still exits promptly.
+ */
+export function startParentDeathWatchdog(options) {
+    const { initialPpid, onOrphaned } = options;
+    const intervalMs = options.intervalMs ?? 2000;
+    const getPpid = options.getPpid ?? (() => process.ppid);
+    const setIntervalFn = options.setIntervalFn ?? setInterval;
+    const clearIntervalFn = options.clearIntervalFn ?? clearInterval;
+    let fired = false;
+    const timer = setIntervalFn(() => {
+        if (fired)
+            return;
+        if (isReparented(initialPpid, getPpid())) {
+            fired = true;
+            onOrphaned();
+        }
+    }, intervalMs);
+    if (typeof timer !== "number")
+        timer.unref?.();
+    return {
+        stop: () => clearIntervalFn(timer),
+    };
+}

package/dist/core/paths.js

@@ -234,6 +234,17 @@ export function getDbPath(env = process.env) {
 export function getIndexWriterLockPath() {
     return path.join(getDataDir(), "index.db.write.lock");
 }
+/**
+ * Path to the opt-in, PID-liveness-only rebuild lock an explicit `akm index`
+ * run acquires (#956). Distinct from {@link getIndexWriterLockPath}'s
+ * `index.db.write.lock`, which is the asset-mutation lease and unrelated to
+ * indexing since #872 — this lock never blocks and is never required, it
+ * only lets a scheduled/opportunistic `akm index --skip-if-locked` step
+ * aside instead of contending with a run already in progress.
+ */
+export function getIndexRebuildLockPath() {
+    return path.join(getDataDir(), "index.rebuild.lock");
+}
 export function getMaintenanceBarrierPath() {
     return path.join(getDataDir(), "maintenance.barrier.lock");
 }

package/dist/core/run-lock.js

@@ -0,0 +1,107 @@
+// 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/.
+/**
+ * PID-liveness-only run lock — the shared mechanics behind `akm improve`'s
+ * whole-run lock (`commands/improve/locks.ts`) and the index rebuild lock
+ * (`indexer/index-rebuild-lock.ts`, #956).
+ *
+ * No `staleAfterMs`: only a verifiably dead holder is ever reclaimed. This is
+ * the #872 lesson encoded at the mechanics layer so every future caller gets
+ * it for free — an age-based stale window let a live-but-wedged holder's
+ * lease survive forever from the holder's own point of view while stranding
+ * every OTHER invocation once the clock passed, which cost one real install
+ * a half-day indexing outage. SQLite's own WAL + busy_timeout + BEGIN
+ * IMMEDIATE already serialize concurrent writers at the correctness layer —
+ * this lock only ever avoids duplicate LOGICAL work or lets a caller choose
+ * to skip instead of contend.
+ *
+ * This module performs exactly one create-or-probe attempt (with the same
+ * absent-race and stale-reclaim retries `improve` established) and reports
+ * whether the caller now owns the lock or, if not, who currently holds it.
+ * It does not decide what "held" means — skip, throw, or warn-and-proceed is
+ * entirely up to the caller — and it does not serialize the attempt itself:
+ * every caller must wrap the call in
+ * `withMaintenanceStartBarrier`/`tryWithMaintenanceStartBarrier`
+ * (`core/maintenance-barrier.ts`) so two racing processes never both create
+ * the sentinel in the same window.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, tryAcquireLockSync } from "./file-lock.js";
+import { describeInaccessiblePath } from "./path-access.js";
+/**
+ * Render a lock holder's pid for a message: `"4242"`, or `"4242 (launcher
+ * 4240)"` when the holder's launcher pid is known (#956) — every process
+ * listing and task log shows the launcher pid, not the bun/node child's, so
+ * naming only the holder pid left an operator unable to connect the two.
+ */
+export function formatLockHolderPid(holder) {
+    if (holder.pid === null)
+        return "unknown";
+    return holder.launcherPid !== null ? `${holder.pid} (launcher ${holder.launcherPid})` : String(holder.pid);
+}
+function parseLockPayload(rawContent) {
+    if (!rawContent)
+        return null;
+    try {
+        return JSON.parse(rawContent);
+    }
+    catch {
+        return null;
+    }
+}
+function holderOf(lock) {
+    return { pid: lock?.pid ?? null, startedAt: lock?.startedAt ?? null, launcherPid: lock?.launcherPid ?? null };
+}
+/**
+ * Attempt to acquire `lockPath`. Returns `{ state: "acquired" }` with an
+ * ownership handle for {@link releaseLock}, or `{ state: "held", holder }`
+ * naming the current holder (best-effort; `pid`/`startedAt` are `null` when
+ * the holder identity could not be determined, e.g. a release-then-reacquire
+ * race). Throws {@link ConfigError} if the sentinel exists but cannot be read
+ * (#791: a lock we cannot see may be genuinely held — never a reclaim
+ * candidate).
+ */
+export function tryAcquireRunLock(lockPath, options) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const lockPayload = () => createLockPayload({ startedAt: new Date().toISOString(), ...options.payloadMetadata });
+    let ownership = tryAcquireLockSync(lockPath, lockPayload());
+    if (ownership)
+        return { state: "acquired", ownership };
+    const probe = probeLock(lockPath);
+    // Race: the holder released between the failed acquire above and this
+    // probe. Retry once rather than falling through with a null-PID "held"
+    // report for a lock nobody actually holds.
+    if (probe.state === "absent") {
+        ownership = tryAcquireLockSync(lockPath, lockPayload());
+        if (ownership)
+            return { state: "acquired", ownership };
+        // Re-grabbed by another racer in this exact window — no holder detail
+        // available without re-probing (which could itself race again).
+        return { state: "held", holder: { pid: null, startedAt: null, launcherPid: null } };
+    }
+    if (probe.state === "inaccessible") {
+        throw new ConfigError(`${options.label} lock exists but is not readable: ${describeInaccessiblePath(lockPath, probe.code)}.`, "DATA_DIR_UNREADABLE");
+    }
+    const lock = parseLockPayload(probe.rawContent);
+    if (probe.state === "stale") {
+        if (!reclaimStaleLock(lockPath, probe)) {
+            return { state: "held", holder: holderOf(lock) };
+        }
+        options.onReclaimed?.({
+            holderPid: lock?.pid ?? probe.holderPid ?? null,
+            lockedAt: lock?.startedAt ?? null,
+            ageMs: probe.ageMs ?? null,
+            reason: probe.reason === "pid_dead" ? "pid_not_alive" : probe.reason,
+        });
+        ownership = tryAcquireLockSync(lockPath, lockPayload());
+        if (ownership)
+            return { state: "acquired", ownership };
+        // Acquired by another racer during stale recovery.
+        return { state: "held", holder: holderOf(lock) };
+    }
+    // probe.state === "held"
+    return { state: "held", holder: holderOf(lock) };
+}

package/dist/core/sensitive-marker-path.js

@@ -0,0 +1,19 @@
+// 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/.
+/**
+ * Path to the sibling marker file that suppresses listing for a sensitive
+ * env/secret asset. Deliberately its own leaf module (no imports) rather than
+ * living on `core/env-secret-ref.ts` (#950 originally put it there): that
+ * module transitively imports the source providers via
+ * `indexer/search/search-source`, and `commands/env/env.ts` is imported back
+ * from `core/adapter/adapters/akm-metadata.ts` (for `scanEnvKeyNames`) — so an
+ * `env.ts` import of the heavier module closes a real cycle through the
+ * adapter registry (`core/adapter/adapters/index.ts`'s `BUILTIN_ADAPTERS`
+ * construction sees `akmAdapter` still TDZ). Keeping this helper leaf-only
+ * lets `commands/env/env.ts` and `core/env-secret-ref.ts` both depend on it
+ * without either pulling the other's heavier graph.
+ */
+export function sensitiveMarkerPath(assetPath, type) {
+    return type === "env" ? assetPath.replace(/\.env$/, ".sensitive") : `${assetPath}.sensitive`;
+}