akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/indexer/indexer.js

@@ -7,6 +7,8 @@ import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
 import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
+import { isLoopbackEndpoint } from "../core/loopback.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
 import { withStateDb } from "../core/state-db.js";
@@ -17,7 +19,7 @@ import { closeDatabase, openExistingDatabase, openIndexDatabase } from "../stora
 import { deleteEntriesByDirAndStash, deleteEntriesByDirExceptKeys, deleteEntriesByIds, deleteEntriesByStashDir, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedDirPathsByStashDir, getIndexedStashDirsByDir, relinkUsageEvents, upsertEntry, upsertWorkflowDocument, } from "../storage/repositories/index-entries-repository.js";
 import { rebuildFts } from "../storage/repositories/index-fts-repository.js";
 import { clearStaleCacheEntries } from "../storage/repositories/index-llm-cache-repository.js";
-import { deleteIndexDirState, deleteIndexDirStatesByStashDir, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { deleteIndexDirState, deleteIndexDirStatesByStashDir, deleteMeta, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
 import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
 import { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
@@ -39,23 +41,15 @@ function throwIfAborted(signal) {
 export function getDefaultLlmConcurrency(llmConfig) {
     if (typeof llmConfig?.concurrency === "number")
         return llmConfig.concurrency;
-    if (!llmConfig?.endpoint)
-        return 1;
-    try {
-        const url = new URL(llmConfig.endpoint);
-        // URL.hostname keeps IPv6 brackets ("[::1]") — strip them so the loopback
-        // comparison actually matches.
-        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
-        if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost"))
-            return 1;
-    }
-    catch {
+    // Local model servers stay at 1 (single loaded model; parallel requests
+    // trigger reload thrash); an absent or unparseable endpoint fails safe as
+    // local. ONE classifier decides what "local" means (`core/loopback.ts`,
+    // shared with the workflow engine's frozen concurrency default).
+    if (isLoopbackEndpoint(llmConfig?.endpoint))
         return 1;
-    }
     // Remote endpoints default to a modest 2-wide pool (owner ruling 2026-07-21):
     // enough to overlap request latency without hammering rate-limited APIs.
-    // Local model servers stay at 1 (single loaded model; parallel requests
-    // trigger reload thrash). The explicit-override branch above only fires for
+    // The explicit-override branch above only fires for
     // callers that put `concurrency` on the connection themselves —
     // `engines.<name>.concurrency` is a valid schema field but `resolveLlmEngineUse`
     // does NOT copy it into the resolved connection, so on the enrichment path the
@@ -164,7 +158,12 @@ async function runWalkPhase(ctx) {
 async function runEmbeddingPhase(ctx) {
     const { db, config, signal, onProgress } = ctx;
     throwIfAborted(signal);
-    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress);
+    // 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);
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
@@ -290,12 +289,33 @@ export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
  *
  * Only rows with a non-empty `file_path` are checked — remote/virtual entries
  * that have no local path are always skipped.
+ *
+ * "No longer exists" means ABSENT, never merely unreadable (#791). This pass
+ * DELETES rows, and `fs.existsSync` reported `false` for a file akm lacked
+ * permission to look at exactly as for one that had been removed — so a
+ * bundle temporarily mounted read-restricted (a uid mismatch, a tightened
+ * parent directory) had its whole index wiped, and the run reported the
+ * deletions as a clean success. Unreadable files keep their rows and are
+ * reported instead.
  */
 function runCleanPass(db, dryRun) {
     const allEntries = db.prepare("SELECT id, entry_key AS ref, file_path AS path FROM entries").all();
     // Only check entries that have a non-empty local path (skip remote/virtual).
     const localEntries = allEntries.filter((e) => typeof e.path === "string" && e.path.trim() !== "");
-    const missing = localEntries.filter((e) => !fs.existsSync(e.path));
+    const missing = [];
+    const unreadable = [];
+    for (const entry of localEntries) {
+        const { access, code } = classifyPathAccess(entry.path);
+        if (access === "absent")
+            missing.push(entry);
+        else if (access === "inaccessible")
+            unreadable.push({ path: entry.path, ...(code ? { code } : {}) });
+    }
+    if (unreadable.length > 0) {
+        const shown = unreadable.slice(0, 5).map((u) => describeInaccessiblePath(u.path, u.code));
+        warn(`Index clean pass kept ${unreadable.length} entr${unreadable.length === 1 ? "y" : "ies"} whose file akm cannot ` +
+            `read (unreadable is not deleted): ${shown.join("; ")}${unreadable.length > shown.length ? "; …" : ""}`);
+    }
     if (!dryRun && missing.length > 0) {
         deleteEntriesByIds(db, missing.map((e) => e.id));
     }
@@ -319,6 +339,24 @@ export async function akmIndex(options) {
         return akmIndexOverride(options);
     return akmIndexReal(options);
 }
+let indexTransactionHookForTests;
+/**
+ * TEST-ONLY. Observe the in-flight reindex transaction; `undefined` restores.
+ *
+ * Exists because the delete-then-reinsert atomicity guarantee is, by
+ * construction, invisible from outside the transaction: by the time
+ * `akmIndex()` resolves, the commit has already collapsed both generations
+ * into one observable state. Concurrency tests install a hook that opens a
+ * SECOND connection at these points and asserts it still sees the previous
+ * complete generation. Inert in production (one `undefined?.()` per reindex).
+ */
+export function _setIndexTransactionHookForTests(hook) {
+    indexTransactionHookForTests = hook;
+}
+/** Fire a named in-transaction observation point (no-op outside tests). */
+function indexTransactionHook(point) {
+    indexTransactionHookForTests?.(point);
+}
 /**
  * Detect an adapter for every resolvable source that does not declare one, and
  * persist each detection into `config.json`.
@@ -976,6 +1014,10 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // (cross-DB) nulls entry_ids that no longer resolve to a rebuilt entry and
             // re-resolves the rest by entry_ref — subsuming the old detach.
             db.exec("DELETE FROM entries");
+            // Atomicity observation point: inside the transaction the tables are now
+            // empty, but no other connection may observe that. See
+            // tests/integration/indexer/reindex-generation-atomicity.test.ts.
+            indexTransactionHook("full-delete-applied");
         }
         for (const { dirPath, currentStashDir, files, stash, skip, reason, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
             if (remove) {
@@ -1089,6 +1131,9 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                 }
             }
         }
+        // Atomicity observation point: the new generation is fully written but
+        // uncommitted, so it must still be invisible to other connections.
+        indexTransactionHook("records-persisted");
     });
     insertTransaction();
     deleteUsageEventsByEntryIds([...deletedUsageEntryIds]);
@@ -1317,9 +1362,20 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
     const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
     const storedFingerprint = getMeta(db, "embeddingFingerprint");
     if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        // Model/provider changed → stored vectors are incompatible. Clear them
-        // (same dimension, so keep the vec table); re-embedded by this index run.
-        purgeEmbeddings(db);
+        // Model/provider changed → stored vectors are incompatible. Clear them;
+        // re-embedded by this index run.
+        //
+        // The vec table goes too. "Same dimension, so keep the vec table" only held
+        // for a same-width model swap: entries_vec is a vec0 virtual table declared
+        // at a FIXED width, so after a dimension-changing model change every insert
+        // failed against the old width, and ensureSchema's dim-change rebuild never
+        // fired because it only runs for callers that pass an explicit
+        // embeddingDim. The stale table survived `--full` — the exact remedy the
+        // warning recommended. Clearing the stored dim lets the next ensureSchema
+        // materialize it at the new width; until then the fast-path flag reads
+        // false (no table) and search uses the complete BLOB table.
+        purgeEmbeddings(db, { dropVecTable: true });
+        deleteMeta(db, "embeddingDim");
     }
     try {
         const { embedBatch } = await import("../llm/embedder.js");
@@ -1364,6 +1420,7 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
             let storedCount = 0;
             let skippedCount = 0;
             let vecFailedCount = 0;
+            let vecUnavailableCount = 0;
             db.transaction(() => {
                 for (let i = 0; i < allEntries.length; i++) {
                     const res = upsertEmbedding(db, allEntries[i].id, embeddings[i]);
@@ -1375,6 +1432,8 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
                     }
                     if (res.vec === "failed")
                         vecFailedCount++;
+                    if (res.vec === "unavailable")
+                        vecUnavailableCount++;
                 }
             })();
             if (skippedCount > 0) {
@@ -1384,7 +1443,13 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
             // instead of inferring readiness from stored-BLOB counts. Any failure
             // marks the fast path degraded, routing search to the JS-cosine fallback
             // over the (complete) BLOB table — honest degradation, not a hard failure.
-            setVecFastPathReady(db, vecFailedCount === 0);
+            //
+            // 'unavailable' has to degrade the flag too. It means no vec row was
+            // written at all, so marking the fast path ready left a later open (a
+            // different runtime, or sqlite-vec installed afterwards) trusting an
+            // empty entries_vec and returning zero semantic hits against a fully
+            // populated BLOB table.
+            setVecFastPathReady(db, vecFailedCount === 0 && vecUnavailableCount === 0);
             if (vecFailedCount > 0) {
                 warn(`[embed] ${vecFailedCount} sqlite-vec fast-path insert${vecFailedCount === 1 ? "" : "s"} failed — ` +
                     "semantic search will use the slower JS-cosine fallback over stored embeddings. " +

package/dist/indexer/passes/memory-inference.js

@@ -43,6 +43,7 @@ import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-r
 import { todayIso } from "../../core/common.js";
 import { concurrentMap } from "../../core/concurrent.js";
 import { warn } from "../../core/warn.js";
+import { recordWrittenPath } from "../../core/write-provenance.js";
 import { writeAssetToSource } from "../../core/write-source.js";
 import { isProcessEnabled } from "../../llm/feature-gate.js";
 import { resolveIndexPassLLM } from "../../llm/index-passes.js";
@@ -449,6 +450,9 @@ function markParentProcessed(parent) {
     const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
+        // #652: the parent's `inference_processed` stamp is a real asset mutation
+        // (the documented writeAssetToSource exception above) — journal it.
+        recordWrittenPath(parent.filePath);
     }
     catch (err) {
         warn(`memory inference: failed to mark parent processed ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/indexer/search/db-search.js

@@ -1,27 +1,15 @@
 // 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/.
-/**
- * Database-backed (SQLite + FTS5/vector) source search implementation.
- *
- * Extracted from source-search.ts to break the circular import:
- *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
- *
- * source-search.ts imports this module for the `searchLocal` export.
- * sources/providers/filesystem.ts also imports `searchLocal` from here.
- *
- * Renamed from `local-search.ts` to signal that this is the DB-layer search
- * implementation, not a "local vs. remote" distinction.
- */
-import fs from "node:fs";
 import path from "node:path";
 import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { displayRef } from "../../core/asset/resolve-ref.js";
+import { classifyPathAccess } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { defaultRendererRegistry } from "../../core/type-presentation.js";
 import { warn } from "../../core/warn.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
@@ -98,6 +86,21 @@ export function shouldQueryPositiveFeedbackCounts(utilityDecayRaw) {
     return boost > 1.0;
 }
 // ── Main search entrypoint ───────────────────────────────────────────────────
+/**
+ * Whether an embedding provider is actually configured.
+ *
+ * A remote provider needs BOTH endpoint and model. A LOCAL provider needs
+ * neither — `embedding.localModel` selects a transformers model that runs in
+ * process. Checking only the remote pair told every local-provider user that
+ * "no embedding provider is configured" and pointed them at
+ * `akm config set embedding '{"endpoint":...}'`, which is the wrong remedy and
+ * hid the real diagnostic recorded in the semantic status.
+ */
+function hasConfiguredEmbeddingProvider(config) {
+    if (config.embedding?.localModel)
+        return true;
+    return Boolean(config.embedding?.endpoint && config.embedding?.model);
+}
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
     const filters = input.filters;
@@ -117,7 +120,7 @@ export async function searchLocal(input) {
         if (rawStatus && rawStatus.providerFingerprint !== currentFingerprint) {
             warnings.push("Embedding config changed. Run 'akm index --full' to rebuild the semantic index with the new provider.");
         }
-        else if (!config.embedding?.endpoint || !config.embedding?.model) {
+        else if (!hasConfiguredEmbeddingProvider(config)) {
             // #480: when semantic mode is `auto` but no embedding provider is
             // configured (e.g. `akm setup --yes` ran without picking one), telling
             // the user to "run akm setup" is misleading — they just did. Surface
@@ -132,7 +135,7 @@ export async function searchLocal(input) {
         }
     }
     if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
-        if (!config.embedding?.endpoint || !config.embedding?.model) {
+        if (!hasConfiguredEmbeddingProvider(config)) {
             // F7/A2: same predicate as the `pending` branch above (#480) — a
             // `blocked` status can outlive the provider config that produced it
             // (e.g. the embedding config was later unset). This is not a fault;
@@ -158,7 +161,12 @@ export async function searchLocal(input) {
     // reads serve the existing index as-is.
     await ensureIndex(stashDir);
     const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath)) {
+    // An index we cannot READ is not an index that does not exist (#791). Saying
+    // "No search index available" for a populated index the caller merely lacks
+    // permission on is a lie at exit 0 — and an agent consuming this JSON has no
+    // way to tell it from a genuine empty result, so it relays the lie onward.
+    assertIndexPathReadable(dbPath);
+    if (classifyPathAccess(dbPath).access === "absent") {
         return {
             hits: [],
             tip: "No search index available. Run 'akm index' to build one.",

package/dist/indexer/walk/walker.js

@@ -123,7 +123,12 @@ function walkStashGit(stashRoot, options) {
     for (const relFile of files) {
         const absPath = path.join(stashRoot, relFile);
         try {
-            if (fs.statSync(absPath).isFile()) {
+            // lstat, not stat: a tracked symlink must not be dereferenced. statSync
+            // follows the link, so a target outside stashRoot would be read and
+            // indexed. The manual walk below already skips symlinks for exactly this
+            // reason; the two walkers have to agree regardless of whether the stash
+            // happens to sit inside a git repo.
+            if (fs.lstatSync(absPath).isFile()) {
                 results.push(buildFileContext(stashRoot, absPath));
             }
         }

package/dist/integrations/agent/detect.js

@@ -74,6 +74,16 @@ const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
  * on win32 or when the env supplies PATHEXT (which is also the seam tests use
  * to cover Windows resolution from a POSIX runner).
  */
+/**
+ * Script shims that `child_process.spawn` cannot execute directly on Windows.
+ *
+ * Node refuses to spawn `.bat`/`.cmd` without a shell (the CVE-2024-27980
+ * hardening), so a detection that returns one of these reports an agent as
+ * available that dispatch then fails to launch. They stay in the candidate
+ * list — a shim is better than reporting the CLI as missing — but they sort
+ * last, so a real `.exe` next to `claude.cmd` wins.
+ */
+const NON_SPAWNABLE_SUFFIXES = new Set([".cmd", ".bat"]);
 function executableSuffixes(envSource) {
     const pathext = envSource.PATHEXT ?? envSource.Pathext ?? envSource.pathext;
     if (process.platform !== "win32" && !pathext)
@@ -83,7 +93,9 @@ function executableSuffixes(envSource) {
         .map((ext) => ext.trim())
         .filter(Boolean)
         .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
-    return ["", ...exts];
+    const directlySpawnable = exts.filter((ext) => !NON_SPAWNABLE_SUFFIXES.has(ext.toLowerCase()));
+    const shims = exts.filter((ext) => NON_SPAWNABLE_SUFFIXES.has(ext.toLowerCase()));
+    return ["", ...directlySpawnable, ...shims];
 }
 let detectOverrides;
 /** TEST-ONLY. Swap the detection implementations; pass undefined to restore. */

package/dist/integrations/agent/engine-resolution.js

@@ -43,6 +43,29 @@ function resolveCredential(name, engine, config) {
         ? { names: [specific, "AKM_LLM_API_KEY"], required: false }
         : { names: [specific], required: false };
 }
+/**
+ * Read a credential descriptor's value out of `process.env`: the FIRST
+ * non-empty trimmed value across `names`, in declared order. A `required`
+ * descriptor that resolves to nothing is a config error naming its PRIMARY
+ * variable — the one an operator is told to set.
+ *
+ * The ONE env-credential seam. The live-config dispatch boundary
+ * ({@link materializeLlmConnection}) and the FROZEN workflow dispatch boundary
+ * (`materializeFrozenLlm` in `workflows/exec/unit-dispatch.ts`, whose frozen
+ * snapshots carry a structurally identical descriptor) both read through it, so
+ * lookup order and the failure message cannot drift between them.
+ */
+export function resolveCredentialFromEnv(credential) {
+    for (const name of credential?.names ?? []) {
+        const candidate = process.env[name]?.trim();
+        if (candidate)
+            return candidate;
+    }
+    if (credential?.required) {
+        throw new ConfigError(`Required engine credential ${credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    }
+    return undefined;
+}
 /** Collect materialized engine credentials for output and persistence redaction. */
 export function collectEngineCredentialValues(config, envSource = process.env) {
     const values = new Set();
@@ -112,17 +135,7 @@ export function materializeLlmConnection(resolved) {
             throw new ConfigError(formatExtraParamsIssue(`Engine "${resolved.engine}" extraParams`, issue), "INVALID_CONFIG_FILE");
         }
     }
-    let apiKey;
-    for (const name of resolved.credential?.names ?? []) {
-        const candidate = process.env[name]?.trim();
-        if (candidate) {
-            apiKey = candidate;
-            break;
-        }
-    }
-    if (resolved.credential?.required && !apiKey) {
-        throw new ConfigError(`Required engine credential ${resolved.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
-    }
+    const apiKey = resolveCredentialFromEnv(resolved.credential);
     return {
         ...resolved.connection,
         ...(apiKey ? { apiKey } : {}),

package/dist/integrations/agent/model-aliases.js

@@ -13,7 +13,7 @@
 const BUILTIN_ALIASES = [
     {
         // Anthropic's Mythos-class tier above Opus — the recommended resolution
-        // target for the `deep` workflow tier (see docs/reference/workflows.md).
+        // target for the `deep` workflow tier (see docs/reference/workflow-schema.md).
         alias: "fable",
         platforms: {
             claude: "claude-fable-5",

package/dist/integrations/agent/profiles.js

@@ -1,13 +1,21 @@
 // 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/.
+/**
+ * Built-in profile registry for external agent CLIs (v1 spec §12.1).
+ *
+ * A `AgentProfile` is the minimum metadata required to shell-out to a
+ * coding-agent CLI. Named engines lower canonical harness metadata into this
+ * intentionally small internal shape. The wrapper is in `./spawn.ts`.
+ */
+import { COMMON_SPAWN_ENV_PASSTHROUGH } from "../../core/spawn-env.js";
 // AKM_EVENT_SOURCE carries usage-event provenance (improve/task) so that akm
 // invocations a spawned agent makes are recorded as machine traffic, not user
 // demand (DRIFT-6). Without it in the passthrough whitelist, buildChildEnv drops
 // the stamp at the agent boundary — e.g. `akm wiki ingest` spawns an agent whose
 // `akm curate/show/search` tool-calls then log source='user', silently inflating
 // every lane's read-back (GRR). It is a provenance tag, never a secret.
-const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR", "AKM_EVENT_SOURCE"];
+const COMMON_PASSTHROUGH = COMMON_SPAWN_ENV_PASSTHROUGH;
 /**
  * Built-in profiles for the agent CLIs akm knows out of the box: the five the
  * v1 spec calls out explicitly, plus the P2 harness adapters (copilot, pi,

package/dist/integrations/agent/spawn.js

@@ -14,90 +14,21 @@
  * NEVER imports an LLM SDK. Agents are reachable only via shell-out;
  * this is a pre-emptive guarantee against the #222 invariant.
  */
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { runManagedSubprocess, } from "../../core/subprocess.js";
+import { collectAllowlistedEnv } from "../../core/spawn-env.js";
+import { runManagedSubprocess, streamCaptureFailure, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-/**
- * Supplement `existingPath` with well-known user binary directories when
- * running in a scheduler context (cron/launchd) where PATH is stripped.
- *
- * Detection heuristic: if the current PATH does not contain the user's home
- * directory, we are likely in a stripped scheduler env. In an interactive
- * shell the user's home almost always appears (e.g. ~/.bun/bin, ~/.cargo/bin).
- *
- * Only directories that actually exist on disk are prepended, and only if
- * they are not already present, so interactive-shell PATH ordering is never
- * disturbed.
- */
-export function supplementPathForSchedulerContext(existingPath) {
-    const home = os.homedir();
-    // If PATH already contains the home directory, we are in an interactive
-    // shell — skip supplementation entirely.
-    if (existingPath.split(path.delimiter).some((d) => d.startsWith(home))) {
-        return existingPath;
-    }
-    const candidates = pathCandidatesForCurrentPlatform(home);
-    const existing = new Set(existingPath.split(path.delimiter).filter(Boolean));
-    const toAdd = candidates.filter((d) => !existing.has(d) && fs.existsSync(d));
-    if (toAdd.length === 0)
-        return existingPath;
-    return [...toAdd, existingPath].filter(Boolean).join(path.delimiter);
-}
-function pathCandidatesForCurrentPlatform(home) {
-    if (process.platform === "win32") {
-        // Windows: Bun + Cargo + Scoop + Chocolatey + system tools. Order favors
-        // user-local installs over machine-global so the user's chosen toolchain
-        // wins. These paths are commonly stripped from Task Scheduler / service
-        // environments, mirroring the cron/launchd problem on POSIX.
-        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
-        const userProfile = process.env.USERPROFILE ?? home;
-        const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
-        return [
-            path.join(userProfile, ".bun", "bin"),
-            path.join(localAppData, "Programs", "bun"),
-            path.join(userProfile, ".cargo", "bin"),
-            path.join(localAppData, "Programs", "Git", "cmd"),
-            path.join(userProfile, "scoop", "shims"),
-            path.join(programFiles, "Git", "cmd"),
-            "C:\\ProgramData\\chocolatey\\bin",
-        ];
-    }
-    return [
-        path.join(home, ".bun", "bin"),
-        path.join(home, ".cargo", "bin"),
-        path.join(home, ".local", "bin"),
-        "/opt/homebrew/bin",
-        "/opt/homebrew/sbin",
-        "/usr/local/bin",
-    ];
-}
 /**
  * Build the child env. Starts empty and copies through:
- *   • Every name in `profile.envPassthrough`.
+ *   • Every name in `profile.envPassthrough` (via the shared
+ *     {@link collectAllowlistedEnv}, which also supplements PATH for
+ *     scheduler contexts where the inherited PATH is stripped).
  *   • Every entry in `profile.env`.
  *   • Every entry in `options.env` (highest precedence).
- *
- * PATH is supplemented with well-known user binary directories when running
- * in a scheduler context (cron/launchd) where the inherited PATH is stripped.
- * See {@link supplementPathForSchedulerContext}.
  */
 function buildChildEnv(profile, options) {
-    const source = options.envSource ?? process.env;
-    const env = {};
-    for (const name of profile.envPassthrough) {
-        const value = source[name];
-        if (value !== undefined)
-            env[name] = value;
-    }
-    // Supplement PATH after passthrough so the scheduler-context fix applies to
-    // the value actually coming from the environment source.
-    if (env.PATH !== undefined) {
-        env.PATH = supplementPathForSchedulerContext(env.PATH);
-    }
+    const env = collectAllowlistedEnv(profile.envPassthrough, options.envSource ?? process.env);
     if (profile.env) {
         for (const [k, v] of Object.entries(profile.env))
             env[k] = v;
@@ -108,19 +39,16 @@ function buildChildEnv(profile, options) {
     }
     return env;
 }
+/**
+ * This path's phrasing of the SHARED incomplete-capture verdict
+ * ({@link streamCaptureFailure} in `core/subprocess.ts`). The classification
+ * lives in the primitive so the agent path and the workflow `exec` path cannot
+ * drift apart on what "the capture did not complete" means; only the sentence
+ * naming the profile is local. Message text is unchanged from the inlined copy.
+ */
 function streamFailureMessage(profileName, stdout, stderr) {
-    const failures = [];
-    if (stdout.error)
-        failures.push(`stdout read failed: ${stdout.error instanceof Error ? stdout.error.message : String(stdout.error)}`);
-    if (stderr.error)
-        failures.push(`stderr read failed: ${stderr.error instanceof Error ? stderr.error.message : String(stderr.error)}`);
-    if (stdout.timedOut)
-        failures.push("stdout drain timed out");
-    if (stderr.timedOut)
-        failures.push("stderr drain timed out");
-    if (failures.length === 0)
-        return undefined;
-    return `agent CLI "${profileName}" output capture failed: ${failures.join("; ")}`;
+    const failures = streamCaptureFailure(stdout, stderr);
+    return failures === undefined ? undefined : `agent CLI "${profileName}" output capture failed: ${failures}`;
 }
 /**
  * Spawn the agent CLI described by `profile` with `prompt` (forwarded as

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -118,6 +118,12 @@ let _testServer = null;
 // Test seam replacing the real `createOpencode` import (see __setServerFactory).
 let _serverFactory = null;
 let _exitHookInstalled = false;
+/**
+ * True once `process.on("exit")` has fired. Close paths consult it because an
+ * exit handler runs after the event loop has stopped: no timer scheduled there
+ * will ever fire, so any cleanup that needs to happen must happen inline.
+ */
+let _processExiting = false;
 /**
  * Test-only seam: inject a fake {@link SdkServer} so `runOpencodeSdk` can be
  * exercised without the real `@opencode-ai/sdk` (which would spin up a server).
@@ -424,6 +430,20 @@ async function createManagedOpencode(options) {
         }
         if (childExited())
             return;
+        if (_processExiting) {
+            // During `process.on("exit")` the event loop is finished, so a timer
+            // scheduled here would never fire and the SIGKILL escalation could not
+            // happen at all — a server child that ignores SIGTERM outlived akm.
+            // Exit handlers must be synchronous, so escalate immediately instead of
+            // waiting out a grace period we have no way to wait for.
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                /* already dead */
+            }
+            return;
+        }
         closeEscalation = setTimeout(() => {
             closeEscalation = undefined;
             if (childExited())
@@ -525,6 +545,7 @@ async function startServer(profile, sdkConfig, env, registryKey, startupSignal)
     if (!_exitHookInstalled) {
         _exitHookInstalled = true;
         process.once("exit", () => {
+            _processExiting = true;
             void closeServer();
         });
     }