akm-cli 0.9.15-beta.1 → 0.9.15-beta.2

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/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/run-lock.js

@@ -31,6 +31,17 @@ 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;
@@ -42,7 +53,7 @@ function parseLockPayload(rawContent) {
     }
 }
 function holderOf(lock) {
-    return { pid: lock?.pid ?? null, startedAt: lock?.startedAt ?? null };
+    return { pid: lock?.pid ?? null, startedAt: lock?.startedAt ?? null, launcherPid: lock?.launcherPid ?? null };
 }
 /**
  * Attempt to acquire `lockPath`. Returns `{ state: "acquired" }` with an
@@ -69,7 +80,7 @@ export function tryAcquireRunLock(lockPath, options) {
             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 } };
+        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");

package/dist/indexer/index-rebuild-lock.js

@@ -22,7 +22,7 @@
 import { releaseLock } from "../core/file-lock.js";
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../core/maintenance-barrier.js";
 import { getIndexRebuildLockPath } from "../core/paths.js";
-import { tryAcquireRunLock } from "../core/run-lock.js";
+import { formatLockHolderPid, tryAcquireRunLock } from "../core/run-lock.js";
 import { warn, warnVerbose } from "../core/warn.js";
 export function indexRebuildLockPath() {
     return getIndexRebuildLockPath();
@@ -53,18 +53,18 @@ export function tryAcquireIndexRebuildLock(skipIfLocked) {
         const result = tryWithMaintenanceStartBarrier(acquire);
         if (!result) {
             warn("[index] maintenance barrier held; skipping (--skip-if-locked)");
-            return { state: "skipped", holder: { pid: null, startedAt: null } };
+            return { state: "skipped", holder: { pid: null, startedAt: null, launcherPid: null } };
         }
         if (result.state === "acquired")
             return result;
-        warn(`[index] another index run holds the lock (PID ${result.holder.pid}, started ${result.holder.startedAt}); ` +
+        warn(`[index] another index run holds the lock (PID ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
             "skipping (--skip-if-locked)");
         return { state: "skipped", holder: result.holder };
     }
     const result = withMaintenanceStartBarrier(acquire);
     if (result.state === "acquired")
         return result;
-    warn(`[index] another index run is active (pid ${result.holder.pid}, started ${result.holder.startedAt}); ` +
+    warn(`[index] another index run is active (pid ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
         "this run will contend with it — pass --skip-if-locked for scheduled runs");
     return { state: "contended", holder: result.holder };
 }

package/dist/indexer/index-written-assets.js

@@ -27,6 +27,7 @@ import { isDataDirUnreadableError } from "../core/errors.js";
 import { probeLock } from "../core/file-lock.js";
 import { isPathAbsent } from "../core/path-access.js";
 import { getDbPath, getIndexRebuildLockPath } from "../core/paths.js";
+import { formatLockHolderPid } from "../core/run-lock.js";
 import { warn, warnVerbose } from "../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
@@ -75,7 +76,14 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
             // rebuild in progress will pick up the change on its own.
             const rebuildProbe = probeLock(getIndexRebuildLockPath());
             if (rebuildProbe.state === "held") {
-                warn(`index rebuild in progress (pid ${rebuildProbe.holderPid}); the next index pass will index ${filePaths.join(", ")}`);
+                // #956: name the launcher pid alongside the holder pid when known —
+                // every process listing and task log shows the launcher's pid, not
+                // the bun/node child's.
+                const holderLabel = formatLockHolderPid({
+                    pid: rebuildProbe.holderPid,
+                    launcherPid: rebuildProbe.launcherPid ?? null,
+                });
+                warn(`index rebuild in progress (pid ${holderLabel}); the next index pass will index ${filePaths.join(", ")}`);
                 return true;
             }
             const dbPath = getDbPath();

package/dist/indexer/indexer.js

@@ -19,6 +19,7 @@ import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
 import { resolveIndexPassExecution } from "../llm/index-passes.js";
 import { preflightStructuredLlmRunner } from "../llm/structured-call.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
+import { salvageEmbeddingsBeforeDiscard } from "../storage/repositories/embedding-salvage-repository.js";
 import { closeDatabase, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { deleteAllEntries, deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
 import { clearStaleCacheEntries, computeBodyHash, getLlmCacheEntry, } from "../storage/repositories/index-llm-cache-repository.js";
@@ -184,21 +185,54 @@ async function runWalkPhase(ctx) {
     });
     ctx.timing.tLlmEnd = Date.now();
 }
+/**
+ * The ONE embedding-phase implementation (#954): generate and
+ * store vectors for every entry missing one, then compute the `hasEmbeddings`
+ * fact and the semantic-search verification off the result. `akmIndex`'s own
+ * (non-deferred) run calls this from {@link runEmbeddingPhase} below; `akm
+ * bundle update`'s coordinator calls it directly on its own connection AFTER
+ * its unified update transaction commits, since the ambient-transaction drift
+ * guard (and the whole point of per-batch commit, #954) requires `db` to have
+ * no ambient transaction open.
+ */
+export async function runEmbeddingPass(params) {
+    const { db, config, onProgress, signal, reembed } = params;
+    const embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal, undefined, {
+        forceReembed: reembed,
+    });
+    setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
+    const semanticEntryCount = getEmbeddableEntryCount(db);
+    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
+    const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
+    onProgress({ phase: "verify", message: verification.message });
+    return { embeddingResult, verification };
+}
 /**
  * Embedding phase: generate and store vector embeddings for all unembedded
- * entries. Writes `ctx.embeddingResult` for the finalize phase.
+ * entries. Writes `ctx.embeddingResult` and `ctx.verification` for the
+ * finalize phase / caller.
  */
 async function runEmbeddingPhase(ctx) {
-    const { db, config, signal, onProgress, reembed } = ctx;
+    const { db, config, signal, onProgress, reembed, deferredUpdateTransaction } = ctx;
     throwIfAborted(signal);
+    if (deferredUpdateTransaction) {
+        // `akm bundle update`'s deferred pass (#954): the embedding
+        // phase runs AFTER the coordinator's own commit, on its own connection,
+        // via the coordinator's direct `runEmbeddingPass` call — never here,
+        // inside the borrowed transaction (the ambient-transaction drift guard
+        // would reject it anyway). `runFinalizePhase` records semantic state as
+        // "pending".
+        ctx.timing.tEmbedEnd = Date.now();
+        return;
+    }
     // Forward the signal. Without it generateEmbeddingsForDb's abort machinery was
     // inert — its throwIfAborted checks and the signal it threads into embedBatch
     // (which RemoteEmbedder passes to every fetch and LocalEmbedder honours between
     // chunks) never saw a controller. Ctrl-C and the improve budget abort could not
     // stop the embedding phase, the longest phase of an index run.
-    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal, undefined, {
-        forceReembed: reembed,
-    });
+    const { embeddingResult, verification } = await runEmbeddingPass({ db, config, onProgress, signal, reembed });
+    ctx.embeddingResult = embeddingResult;
+    ctx.verification = verification;
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
@@ -206,8 +240,8 @@ async function runEmbeddingPhase(ctx) {
  * usage events, recompute utility scores, update index metadata, and emit the
  * verify event.
  */
-async function runFinalizePhase(ctx, deferredUpdateTransaction) {
-    const { db, config, sources, sourceDirs, stashDir, signal, onProgress } = ctx;
+async function runFinalizePhase(ctx) {
+    const { db, config, sources, sourceDirs, stashDir, signal, onProgress, deferredUpdateTransaction } = ctx;
     ctx.timing.tFinalizeStart = Date.now();
     // `upsertEntry` and every canonical delete own their FTS projection. This is
     // an observation point, not a second materialization pass.
@@ -249,22 +283,37 @@ async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     // An incomplete run preserves the prior freshness watermark. Advancing it
     // could make a recovered source look unchanged even though this run never
     // persisted its files.
-    const embeddingResult = ctx.embeddingResult ?? { success: false };
     if (ctx.scanComplete) {
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
         setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
         setMeta(db, "sourceOwners", JSON.stringify(sourceOwners(sources)));
     }
-    setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
-    const semanticEntryCount = getEmbeddableEntryCount(db);
-    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
-    const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
-    onProgress({ phase: "verify", message: verification.message });
-    // Store verification result and totalEntries on ctx for the caller to use
-    ctx.verification = verification;
+    if (deferredUpdateTransaction) {
+        // #954: the embedding phase was skipped for this borrowed
+        // transaction — record semantic state as pending, never ready, until the
+        // coordinator's own post-commit `runEmbeddingPass` call reports the
+        // truth on a fresh connection.
+        setMeta(db, "hasEmbeddings", "0");
+        const semanticEntryCount = getEmbeddableEntryCount(db);
+        const message = "Semantic index update deferred until after the source-update commit.";
+        onProgress({ phase: "verify", message });
+        ctx.verification = {
+            ok: true,
+            message,
+            semanticSearchEnabled: config.semanticSearchMode === "auto",
+            semanticSearchMode: config.semanticSearchMode,
+            semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
+            embeddingProvider: getEmbeddingProvider(config.embedding),
+            entryCount: semanticEntryCount,
+            embeddingCount: getEmbeddingCount(db),
+            vecAvailable: isVecAvailable(db),
+        };
+    }
+    // Non-deferred: ctx.verification was already populated by runEmbeddingPhase
+    // (via the shared runEmbeddingPass).
     ctx.totalEntries = totalEntries;
     ctx.timing.tFinalizeEnd = Date.now();
     // suppress unused warning — sources was previously used inline
@@ -513,6 +562,11 @@ async function akmIndexReal(options) {
             force: full,
             materialize: options.hydrateSources !== false,
             secrets: storeSecretResolver,
+            // Same progress channel as every other phase (#954) — a
+            // stalled clone/fetch here runs BEFORE index.db is even opened, so
+            // without this it looked identical to "no database open, nothing
+            // written".
+            onProgress: (message) => onProgress({ phase: "preflight", message }),
         });
         const sourceCacheEnd = Date.now();
         const allSourceEntries = resolveSourceEntries(stashDir, config);
@@ -553,6 +607,7 @@ async function akmIndexReal(options) {
                 onProgress,
                 signal,
                 t0,
+                deferredUpdateTransaction: options.deferredUpdateTransaction,
             });
             indexRunContext = ctx;
             onProgress({
@@ -592,7 +647,7 @@ async function akmIndexReal(options) {
             }
             cleanEnd = Date.now();
             await runEmbeddingPhase(ctx);
-            await runFinalizePhase(ctx, options.deferredUpdateTransaction);
+            await runFinalizePhase(ctx);
             // ────────────────────────────────────────────────────────────────────────
             // runFinalizePhase always populates these before returning.
             const verification = ctx.verification;
@@ -1159,6 +1214,14 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
         // transaction so delete and re-insert are atomic — a concurrent reader
         // never observes an empty database between the two operations.
         if (fullDelete) {
+            // #955: copy every (search_text hash, embedding) pair about to be
+            // discarded wholesale into `embedding_salvage`, tagged with the
+            // fingerprint the discarded vectors were generated under, BEFORE the
+            // wipe below — inside the SAME transaction so the copy and the
+            // discard commit or roll back together. The embedding phase later in
+            // this run hands salvaged vectors back to unchanged content instead
+            // of re-embedding the whole corpus.
+            salvageEmbeddingsBeforeDiscard(db);
             // Entries and every child materialization share one deletion authority.
             // Usage events live in state.db and survive so finalize can relink them
             // to the replacement generation's row ids.