akm-cli 0.9.1-beta.1 → 0.9.1-beta.3

package/dist/indexer/indexer.js

@@ -19,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";
@@ -158,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();
 }
 /**
@@ -1357,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");
@@ -1404,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]);
@@ -1415,6 +1432,8 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
                     }
                     if (res.vec === "failed")
                         vecFailedCount++;
+                    if (res.vec === "unavailable")
+                        vecUnavailableCount++;
                 }
             })();
             if (skippedCount > 0) {
@@ -1424,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. " +
@@ -1799,7 +1824,12 @@ export function recomputeUtilityScores(db, stateDb) {
              SUM(CASE WHEN u.event_type = 'show'   THEN 1 ELSE 0 END) AS show_count,
              SUM(CASE WHEN u.event_type = 'feedback' AND u.signal = 'positive' THEN 1 ELSE 0 END) AS positive_feedback_count,
              SUM(CASE WHEN u.event_type = 'feedback' AND u.signal = 'negative' THEN 1 ELSE 0 END) AS negative_feedback_count,
-             MAX(u.created_at) AS last_used_at
+             MAX(
+               CASE
+                 WHEN u.event_type IN ('search', 'show', 'curate') THEN u.created_at
+                 ELSE NULL
+               END
+             ) AS last_used_at
       FROM usage_events u
       WHERE u.entry_id IS NOT NULL
         AND u.source = 'user'
@@ -1814,7 +1844,6 @@ export function recomputeUtilityScores(db, stateDb) {
     for (const row of scoreRows) {
         existingScores.set(row.entry_id, { utility: row.utility, lastUsedAt: row.last_used_at ?? undefined });
     }
-    const now = new Date().toISOString();
     const entryIds = new Set([...existingScores.keys(), ...usageByEntry.keys()]);
     for (const entryId of entryIds) {
         const row = usageByEntry.get(entryId) ?? {
@@ -1832,7 +1861,17 @@ export function recomputeUtilityScores(db, stateDb) {
         const existing = existingScores.get(row.entry_id);
         const prevUtility = existing?.utility ?? 0;
         const utility = prevUtility * emaDecay + effectiveRate * emaNew;
-        const lastUsedAt = effectiveRate > 0.5 ? now : (existing?.lastUsedAt ?? undefined);
+        // `utility_scores.last_used_at` is consumed by salience as the timestamp of
+        // the most-recent retrieval. Preserve that meaning by carrying the event's
+        // timestamp through verbatim. The former `effectiveRate > 0.5 ? now : ...`
+        // branch stamped every high-select-rate entry with the index run time,
+        // making unrelated assets look simultaneously fresh and flattening the
+        // recency component of retrieval salience.
+        //
+        // `usage_events` is the source of truth within its retention window. A
+        // missing row therefore clears legacy/index-time stamps on the next index
+        // pass; salience already treats an absent timestamp as long ago.
+        const lastUsedAt = row.last_used_at ?? undefined;
         upsertUtilityScore(db, row.entry_id, {
             utility,
             showCount: row.show_count,

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

@@ -86,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;
@@ -105,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
@@ -120,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;

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/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();
         });
     }

package/dist/integrations/lockfile.js

@@ -126,6 +126,16 @@ function readLockfileOrThrow() {
     if (!Array.isArray(parsed)) {
         throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not a JSON array. Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
     }
+    // Refuse rather than filter. This is the WRITE path's read: everything it
+    // returns is what gets written back, so silently dropping entries that fail
+    // per-entry validation destroyed them on the next write — the same
+    // data-losing overwrite the two refusals above exist to prevent, just at
+    // entry granularity instead of file granularity.
+    const invalid = parsed.filter((entry) => !isValidLockfileEntry(entry));
+    if (invalid.length > 0) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: ${invalid.length} existing entr${invalid.length === 1 ? "y is" : "ies are"} malformed. ` +
+            "Fix or remove the file by hand before retrying — those entries would otherwise be lost.", "INVALID_CONFIG_FILE");
+    }
     return parsed.filter(isValidLockfileEntry);
 }
 /**

package/dist/llm/client.js

@@ -9,34 +9,22 @@
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
+import { ENV_REFERENCE_PATTERN } from "../core/config/schema/primitives.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { parseJsonResponse } from "../core/parse.js";
-import { redactCredentialPatterns, redactSensitiveText } from "../core/redaction.js";
+import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
 import { warnVerbose } from "../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
 import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
-/** Maximum length of an LLM error response body included in thrown errors. */
+/** Maximum length of an upstream response excerpt included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
 /** Stable OpenAI-compatible response-schema name used for every structured call. */
 const JSON_SCHEMA_RESPONSE_NAME = "akm_response";
 /**
- * Redact credential-shaped substrings from an upstream error body before
- * including it in a thrown Error. The body is also trimmed to a fixed length
- * so that a verbose provider response cannot leak large amounts of context.
- *
- * The pattern set itself lives in {@link redactCredentialPatterns}
- * (src/core/redaction.ts) so other output paths (e.g. task run logs) can
- * reuse it without this function's length cap.
+ * Re-exported from src/core/redaction.ts, where it now lives so every HTTP
+ * transport can apply the same hardening — the embeddings client needs it too.
  */
-export function redactErrorBody(input) {
-    if (!input)
-        return "";
-    let out = redactCredentialPatterns(input);
-    if (out.length > ERROR_BODY_MAX_LEN) {
-        out = `${out.slice(0, ERROR_BODY_MAX_LEN)}…`;
-    }
-    return out;
-}
+export { redactErrorBody } from "../core/redaction.js";
 /**
  * Detect a response body that is an HTML document rather than the expected
  * JSON. LM Studio (and similar local providers) can serve their web UI on
@@ -223,7 +211,14 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    const resolvedKey = resolveSecret(config.apiKey);
+    // Resolve ONLY a whole-string env reference. Every live caller already hands
+    // us the materialized credential (materializeLlmConnection / materializeFrozenLlm
+    // resolve `$VAR` upstream, and engine config REQUIRES the symbolic form), so
+    // re-running the substitution over a literal key mangled any credential
+    // containing `$` — `sk-live$ecret` lost everything from the `$` onward, and
+    // the request failed with an opaque 401. The narrow check keeps the symbolic
+    // form working for any direct caller that still passes one.
+    const resolvedKey = ENV_REFERENCE_PATTERN.test(config.apiKey ?? "") ? resolveSecret(config.apiKey) : config.apiKey;
     if (resolvedKey) {
         headers.Authorization = `Bearer ${resolvedKey}`;
     }

package/dist/llm/embedder.js

@@ -65,12 +65,32 @@ export async function embed(text, embeddingConfig, signal) {
     const cached = getCachedEmbedding(key);
     if (cached)
         return cached;
-    const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
-        ? await new RemoteEmbedder(embeddingConfig).embed(text, signal)
-        : await getLocalEmbedder().embed(text, signal);
+    const result = await embedOnce(text, embeddingConfig, signal);
     setCachedEmbedding(key, result);
     return result;
 }
+/**
+ * Resolve a single embedding through the configured provider.
+ *
+ * The local branch must honour `localModel` exactly as {@link embedBatch}
+ * does. The singleton is constructed with no default model, so routing through
+ * `getLocalEmbedder().embed()` silently used DEFAULT_LOCAL_MODEL: queries were
+ * embedded with a different model than the index was built with. Nothing
+ * detected it, because the provider fingerprint keys on `localModel`, so no
+ * purge or "pending" status ever fired — a dimension mismatch made semantic
+ * ranking contribute nothing, and a same-dimension override silently produced
+ * meaningless cross-model scores.
+ */
+async function embedOnce(text, embeddingConfig, signal) {
+    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
+        return new RemoteEmbedder(embeddingConfig).embed(text, signal);
+    }
+    const localModel = embeddingConfig?.localModel;
+    if (localModel) {
+        return getLocalEmbedder().embedWithModel(text, localModel);
+    }
+    return getLocalEmbedder().embed(text, signal);
+}
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).

package/dist/llm/embedders/remote.js

@@ -9,6 +9,7 @@
  */
 import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/common.js";
 import { resolveSecret } from "../../core/config/config.js";
+import { redactErrorBody, redactSensitiveText } from "../../core/redaction.js";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
 export function estimateTokenCount(text) {
@@ -54,7 +55,7 @@ export class RemoteEmbedder {
                     throw err;
                 return "";
             });
-            throw new Error(`Embedding request failed (${response.status}): ${errBody}`);
+            throw new Error(`Embedding request failed (${response.status}): ${this.safeErrorBody(errBody)}`);
         }
         const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
         if (!json.data?.[0]?.embedding) {
@@ -94,7 +95,7 @@ export class RemoteEmbedder {
                         throw err;
                     return "";
                 });
-                throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
+                throw new Error(`Embedding batch request failed (${response.status}): ${this.safeErrorBody(respBody)}`);
             }
             const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
             if (!json.data || json.data.length !== batch.length) {
@@ -119,6 +120,21 @@ export class RemoteEmbedder {
         }
         return headers;
     }
+    /**
+     * Make a provider error body safe to embed in a thrown Error, matching the
+     * hardening llm/client.ts applies on the identical path: pattern-redact
+     * credential shapes, exact-scrub this connection's own key, and clip.
+     *
+     * These messages are durable — generateEmbeddingsForDb surfaces them as
+     * `embeddingResult.message`, which is written to semantic-status.json and
+     * replayed by `akm info` (including `--json`) until the next successful
+     * index, and printed on every vector-search attempt. Raw bodies reached that
+     * far unredacted and uncapped, at readBodyWithByteCap's 10 MB default.
+     */
+    safeErrorBody(body) {
+        const resolvedKey = resolveSecret(this.config.apiKey);
+        return redactSensitiveText(redactErrorBody(body), resolvedKey ? [resolvedKey] : []);
+    }
 }
 /**
  * L2-normalize a vector to unit length.
@@ -144,6 +160,15 @@ export function normalizeEmbeddingEndpoint(endpoint) {
     if (normalizedPath.endsWith("/embeddings")) {
         return parsed.toString();
     }
+    // Ollama's NATIVE embedding route is `/api/embed` (and the older
+    // `/api/embeddings`). Appending "/embeddings" to it produced
+    // `/api/embed/embeddings`, a 404 — so pointing akm at the native endpoint,
+    // which is what its own options like ollamaOptions and contextLength are
+    // for, could never work. An explicit path that is already an embedding route
+    // is left alone.
+    if (normalizedPath.endsWith("/embed")) {
+        return parsed.toString();
+    }
     parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
     return parsed.toString();
 }

package/dist/output/html-render.js

@@ -14,8 +14,28 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import healthTemplate from "../assets/templates/html/health.html" with { type: "text" };
 import { getDirname } from "../runtime.js";
 const TEMPLATES_DIR = path.join(getDirname(import.meta.url), "../assets/templates/html");
+/**
+ * Templates embedded at build time, keyed by command name.
+ *
+ * `bun build --compile` embeds only what is imported `with { type: "text" }`;
+ * a plain `readFileSync` from a path relative to `import.meta.url` resolves
+ * into the virtual `/$bunfs` tree and misses. `akm health --report --format
+ * html` therefore crashed with ENOENT (exit 70) on the standalone binary that
+ * the CLI's own install error and the CHANGELOG promote as the runtime-free
+ * option. The text import works on all three runtimes: natively on Bun, via
+ * scripts/node-runtime/text-import-hook.mjs on Node, and embedded in the
+ * compiled binary.
+ */
+const EMBEDDED_TEMPLATES = {
+    // bun-types declares `*.html` as an `HTMLBundle` (its HTML-bundler entrypoint
+    // feature), which is not what a `type: "text"` import yields — the value is
+    // the file's contents as a string on every runtime. The cast reconciles the
+    // ambient declaration with the actual import attribute.
+    health: healthTemplate,
+};
 /**
  * Resolve the on-disk template path for a command's bespoke `<command>.html`.
  * The command name is sanitized to a bare basename so a hostile command
@@ -37,9 +57,28 @@ const TOKEN_RE = /%%[A-Z_]+%%/g;
  * matching the skill renderer's behaviour.
  */
 export function renderHtml(templatePath, replacements) {
-    const html = fs.readFileSync(templatePath, "utf8");
+    const html = readTemplate(templatePath);
     return html.replace(TOKEN_RE, (token) => replacements[token] ?? token);
 }
+/**
+ * Read a template from disk, falling back to the embedded copy.
+ *
+ * Disk stays primary so an operator (or a test) editing
+ * `src/assets/templates/html/<name>.html` sees the change without a rebuild.
+ * The fallback covers the standalone binary, where the file does not exist on
+ * any real filesystem.
+ */
+function readTemplate(templatePath) {
+    try {
+        return fs.readFileSync(templatePath, "utf8");
+    }
+    catch (err) {
+        const embedded = EMBEDDED_TEMPLATES[path.basename(templatePath, ".html")];
+        if (embedded !== undefined)
+            return embedded;
+        throw err;
+    }
+}
 /**
  * Minimal HTML entity escaping for text interpolated into templates. Escapes
  * the single quote as well as the double quote so escaped values are safe in

package/dist/runtime.js

@@ -78,8 +78,17 @@ function nodeSpawnAdapter(cmd, options) {
         detached: options.detached,
         stdio: [stdioFor(options.stdin), stdioFor(options.stdout), stdioFor(options.stderr)],
     });
+    // Node's 'exit' fires (null, signal) when the child dies from a signal.
+    // Resolving `code ?? 0` reported that as SUCCESS, so an OOM-killed or
+    // segfaulted child came back exit 0 with partial stdout. Bun resolves
+    // 128 + signum for the same case; match it so both runtimes agree and
+    // callers that only check `exitCode !== 0` classify signal deaths correctly.
+    let signalCode = null;
     const exited = new Promise((resolve, reject) => {
-        child.once("exit", (code) => resolve(code ?? 0));
+        child.once("exit", (code, signal) => {
+            signalCode = signal;
+            resolve(code ?? (signal ? 128 + signalNumber(signal) : 0));
+        });
         child.once("error", reject);
     });
     return {
@@ -96,12 +105,25 @@ function nodeSpawnAdapter(cmd, options) {
         get exitCode() {
             return child.exitCode;
         },
+        get signalCode() {
+            return signalCode ?? child.signalCode;
+        },
         pid: child.pid,
         kill(signal) {
             child.kill(signal);
         },
     };
 }
+/**
+ * Map a signal name to its number so a signal death can be reported as the
+ * conventional 128 + signum exit status. Falls back to SIGKILL's 9 for a name
+ * this platform does not define, which still yields a non-zero status — the
+ * property that matters for classifying the run as failed.
+ */
+function signalNumber(signal) {
+    const { constants } = nodeRequire("node:os");
+    return constants.signals[signal] ?? 9;
+}
 // `node:stream`'s Writable.toWeb is available on Node >=17; referenced via the
 // class to avoid a static import that Bun's typings may not expose.
 function Writable_toWeb(w) {