akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/core/parse.js

@@ -23,7 +23,10 @@
  * models). Also strips leading/trailing whitespace.
  */
 export function stripThinkBlocks(raw) {
-    return raw.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+    return raw
+        .replace(/<think>[\s\S]*?<\/think>/gi, "")
+        .replace(/^[\s\S]*?<\/think>/i, "")
+        .trim();
 }
 /**
  * Strips markdown code fences (``` or ~~~, with optional language tag).

package/dist/core/path-access.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/.
+/**
+ * Tell "this path is not there" apart from "I am not allowed to look at it"
+ * (issue #791).
+ *
+ * # Why this exists
+ *
+ * `fs.existsSync()` answers `false` for BOTH cases: it swallows every error,
+ * so `ENOENT` (genuinely absent) and `EACCES` (present, unreadable) are
+ * indistinguishable. akm used `existsSync` as its "is there an index?" gate on
+ * the read path, so an index the caller could not read was reported as an index
+ * that did not exist — `akm search` and `akm curate` returned
+ * `hits: []` with the tip *"No search index available. Run 'akm index' to build
+ * one."* at exit 0, for a populated index sitting right there on disk.
+ *
+ * That is the worst possible shape for a failure. A non-zero exit is a problem
+ * the operator can see; an empty-but-successful result is a lie that a
+ * consuming agent will confidently relay to its user. In the report that
+ * prompted this module, exactly that happened: an agent told its user akm's
+ * "vector service is unavailable and its maintenance lock is read-only" — a
+ * story it invented to explain results that claimed to be fine.
+ *
+ * # Contract
+ *
+ * `absent` means the path (or a parent component) genuinely is not there, which
+ * is a legitimate first-run state every caller already handles. `inaccessible`
+ * means the path may well exist and this process cannot determine that or read
+ * it — a caller must NEVER degrade that to an empty-but-successful result.
+ */
+import fs from "node:fs";
+function errnoOf(error) {
+    const code = error?.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Classify `target` as {@link PathAccess}.
+ *
+ * `ENOENT`/`ENOTDIR` are `absent` — the path cannot exist as named. Everything
+ * else that fails is `inaccessible`, carrying its errno: a permission error is
+ * the common case, but a symlink loop or an I/O error are equally "present as
+ * far as anyone knows, and unusable", and silently treating them as "no index"
+ * is the bug this module exists to prevent.
+ *
+ * Statting is not enough — a file can be `stat`-able through a searchable
+ * parent while being unreadable itself — so a successful stat is confirmed with
+ * an `R_OK` access check.
+ */
+export function classifyPathAccess(target) {
+    try {
+        fs.statSync(target);
+    }
+    catch (error) {
+        const code = errnoOf(error);
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { access: "absent" };
+        return { access: "inaccessible", ...(code ? { code } : {}) };
+    }
+    try {
+        fs.accessSync(target, fs.constants.R_OK);
+    }
+    catch (error) {
+        const code = errnoOf(error);
+        return { access: "inaccessible", ...(code ? { code } : {}) };
+    }
+    return { access: "present" };
+}
+/** True when the path is genuinely absent — the ordinary "not built yet" state. */
+export function isPathAbsent(target) {
+    return classifyPathAccess(target).access === "absent";
+}
+/**
+ * A diagnostic line naming everything an operator needs to fix a permission
+ * problem without a second round trip: the path, the errno, the mode and owner
+ * of whatever akm *could* stat along the way, and the uid actually running.
+ *
+ * Deliberately best-effort — this runs on an error path, so a failure to gather
+ * detail must never mask the error being described.
+ */
+export function describeInaccessiblePath(target, code) {
+    const parts = [target];
+    if (code)
+        parts.push(`(${code})`);
+    try {
+        const stat = fs.statSync(target);
+        parts.push(`mode ${(stat.mode & 0o777).toString(8).padStart(3, "0")}, owner uid ${stat.uid}`);
+    }
+    catch {
+        // Cannot stat the file itself — describe the closest parent we CAN see,
+        // which is usually where the missing permission actually is.
+        const parent = target.slice(0, Math.max(0, target.lastIndexOf("/")));
+        if (parent) {
+            try {
+                const stat = fs.statSync(parent);
+                parts.push(`parent ${parent} is mode ${(stat.mode & 0o777).toString(8).padStart(3, "0")}, owner uid ${stat.uid}`);
+            }
+            catch {
+                // Nothing further to say.
+            }
+        }
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid !== undefined)
+        parts.push(`running as uid ${uid}`);
+    return parts.join("; ");
+}

package/dist/core/paths.js

@@ -30,7 +30,7 @@ function isUnderBunTest(env) {
  * Returns true when the given path is in a directory family the OS may
  * reap (or that the user has clearly designated as a sandbox by virtue
  * of placing it under `/tmp` or a macOS per-user temp dir). Used to
- * decide whether `AKM_STASH_DIR=$tmpdir` should also isolate config +
+ * decide whether `AKM_BUNDLE_DIR=$tmpdir` should also isolate config +
  * cache writes (so a test harness's `akm setup --yes --dir .` cannot
  * silently clobber the user's `~/.config/akm/config.json`). See
  * the 2026-05-23 setup-clobbers-user-config incident
@@ -67,7 +67,7 @@ export function getConfigDir(env = process.env, platform = process.platform) {
         return override;
     // Explicit XDG override wins next — tests and operators that pre-arrange
     // an isolated config dir via XDG_CONFIG_HOME (or %APPDATA% on Windows)
-    // must be honored as set, so the AKM_STASH_DIR transient-isolation rule
+    // must be honored as set, so the AKM_BUNDLE_DIR transient-isolation rule
     // below does not silently move config away from where they pointed it.
     if (platform === "win32") {
         const appData = env.APPDATA?.trim();
@@ -79,16 +79,16 @@ export function getConfigDir(env = process.env, platform = process.platform) {
         if (xdgConfigHome)
             return path.join(xdgConfigHome, "akm");
     }
-    // Isolation safety: when AKM_STASH_DIR points at a transient/sandbox path
+    // Isolation safety: when AKM_BUNDLE_DIR points at a transient/sandbox path
     // (/tmp, /var/tmp, /private/var/folders) AND no explicit config dir
-    // override is set, route config writes into `${AKM_STASH_DIR}/.akm`
+    // override is set, route config writes into `${AKM_BUNDLE_DIR}/.akm`
     // instead of the user's host ~/.config/akm. This prevents the documented
     // isolation pattern
-    //   AKM_DATA_DIR=/tmp/x AKM_STASH_DIR=/tmp/x akm setup --yes --dir .
+    //   AKM_DATA_DIR=/tmp/x AKM_BUNDLE_DIR=/tmp/x akm setup --yes --dir .
     // from silently clobbering the host config. See
     // the 2026-05-23 setup-clobbers-user-config incident.
-    // Daily users with a persistent AKM_STASH_DIR=~/my-stash are unaffected.
-    const stashOverride = env.AKM_STASH_DIR?.trim();
+    // Daily users with a persistent AKM_BUNDLE_DIR=~/my-stash are unaffected.
+    const stashOverride = env.AKM_BUNDLE_DIR?.trim();
     if (stashOverride && isTransientStashPath(stashOverride)) {
         return path.join(stashOverride, ".akm");
     }
@@ -122,7 +122,7 @@ export function getCacheDir(env = process.env) {
     // Explicit XDG/platform overrides win before the transient-stash isolation
     // rule below — tests and operators that pre-arrange XDG_CACHE_HOME (or
     // %LOCALAPPDATA% / %USERPROFILE% / %APPDATA% on Windows) must be honored
-    // as set, so the AKM_STASH_DIR transient rule does not silently move cache
+    // as set, so the AKM_BUNDLE_DIR transient rule does not silently move cache
     // writes away from where they pointed them.
     if (IS_WINDOWS) {
         const localAppData = env.LOCALAPPDATA?.trim();
@@ -145,12 +145,12 @@ export function getCacheDir(env = process.env) {
         if (xdgCacheHome)
             return path.join(xdgCacheHome, "akm");
     }
-    // Isolation safety (mirrors getConfigDir): when AKM_STASH_DIR points at a
+    // Isolation safety (mirrors getConfigDir): when AKM_BUNDLE_DIR points at a
     // transient path AND no explicit cache override is set, route cache writes
-    // into `${AKM_STASH_DIR}/.akm/cache` so that config backups, registry-index
+    // into `${AKM_BUNDLE_DIR}/.akm/cache` so that config backups, registry-index
     // cache, and other regenerable artifacts do not pollute the user's host
     // ~/.cache/akm directory.
-    const stashOverride = env.AKM_STASH_DIR?.trim();
+    const stashOverride = env.AKM_BUNDLE_DIR?.trim();
     if (stashOverride && isTransientStashPath(stashOverride)) {
         return path.join(stashOverride, ".akm", "cache");
     }
@@ -184,7 +184,7 @@ export function getDataDir(env = process.env, platform = process.platform) {
     // user's real $XDG_DATA_HOME / ~/.local/share/akm under any condition.
     // Any test that needs a data dir must point it at a mktemp-d directory
     // via XDG_DATA_HOME (or AKM_DATA_DIR). The previous carve-out that only
-    // fired when AKM_STASH_DIR was set was a loophole: tests calling
+    // fired when AKM_BUNDLE_DIR was set was a loophole: tests calling
     // openDatabase() or getDbPath() without overriding any env var silently
     // wrote into ~/.local/share/akm/index.db (observed: 4,183-row
     // registry-cache pollution). Item 5 of the 0.8.x critical-review plan.
@@ -225,9 +225,9 @@ export function getMaintenanceBarrierPath() {
 export function getStateDbPathInDataDir() {
     return path.join(getDataDir(), "state.db");
 }
-/** Path for the task history directory in $DATA. */
-export function getTaskHistoryStateDir() {
-    return path.join(getDataDir(), "tasks", "history");
+/** Content-addressed scheduler runtime descriptors. */
+export function getTaskContextDir(env = process.env) {
+    return path.join(getDataDir(env), "tasks", "context");
 }
 /** Path to the akm.lock file in $DATA. */
 export function getLockfilePath() {
@@ -246,9 +246,6 @@ export function getRegistryCacheDir() {
 export function getRegistryIndexCacheDir() {
     return path.join(getCacheDir(), "registry-index");
 }
-export function getBinDir() {
-    return path.join(getCacheDir(), "bin");
-}
 // ── Scheduled-task runtime directories (logs + history) ──────────────────────
 export function getTaskLogDir() {
     return path.join(getCacheDir(), "tasks", "logs");
@@ -258,7 +255,7 @@ export function getTaskHistoryDir() {
 }
 // ── Default stash directory ──────────────────────────────────────────────────
 export function getDefaultStashDir(env = process.env) {
-    const override = env.AKM_STASH_DIR?.trim();
+    const override = env.AKM_BUNDLE_DIR?.trim();
     if (override)
         return override;
     if (IS_WINDOWS) {
@@ -269,7 +266,7 @@ export function getDefaultStashDir(env = process.env) {
     }
     const home = env.HOME?.trim();
     if (!home) {
-        throw new ConfigError("Unable to determine default stash directory. Set HOME.", "STASH_DIR_NOT_FOUND");
+        throw new ConfigError("Unable to determine default bundle directory. Set HOME.", "STASH_DIR_NOT_FOUND");
     }
     return path.join(home, "akm");
 }

package/dist/core/recognition-util.js

@@ -34,22 +34,20 @@ export const SCRIPT_EXTENSIONS = new Set([
     ".kts",
 ]);
 /**
- * Recognized workflow asset extensions, in resolution-priority order.
- * `.md` (classic linear markdown workflows — the stable contract) stays
- * FIRST for back-compat; `.yaml`/`.yml` hold YAML workflow *programs*
- * (redesign addendum, R1). `workflows/<name>` refs resolve against this list.
+ * Recognized workflow asset extensions. One format now (workflow-format-
+ * unification): orchestration graph in frontmatter, prose in the body.
+ * `workflows/<name>` refs resolve against this list.
  */
-export const WORKFLOW_EXTENSIONS = [".md", ".yaml", ".yml"];
+export const WORKFLOW_EXTENSIONS = [".md"];
 /**
- * Strip a recognized workflow extension (`.md`/`.yaml`/`.yml`) from a workflow
- * asset *name* so `foo`, `foo.yaml`, `foo.yml`, and `foo.md` collapse to one
- * canonical identity — the same collapse `workflowSpec.toCanonicalName`
- * performs on a resolved file path. Callers that turn a `workflows/<name>` ref
- * into run identity (the active-run guard, list/status filters) MUST route the
- * name through this so an aliased spelling (`workflows/foo.yaml`) and the
- * canonical `workflows/foo` cannot start or hide parallel runs of the same
- * workflow. Names without a recognized workflow extension pass through
- * unchanged.
+ * Strip the recognized workflow extension (`.md`) from a workflow asset
+ * *name* so `foo` and `foo.md` collapse to one canonical identity — the same
+ * collapse `workflowSpec.toCanonicalName` performs on a resolved file path.
+ * Callers that turn a `workflows/<name>` ref into run identity (the
+ * active-run guard, list/status filters) MUST route the name through this so
+ * an aliased spelling (`workflows/foo.md`) and the canonical `workflows/foo`
+ * cannot start or hide parallel runs of the same workflow. Names without the
+ * extension pass through unchanged.
  */
 export function canonicalizeWorkflowName(name) {
     const lower = name.toLowerCase();

package/dist/core/redaction.js

@@ -298,8 +298,74 @@ function addMappedMatches(coverageDelta, haystack, needle) {
     }
 }
 /**
- * Replace exact sensitive values in text. Longer values are replaced first so
- * an overlapping prefix cannot expose the suffix of a longer credential.
+ * Mark every occurrence of `needle` in `text` — no encoding normalization, for
+ * text that contains neither `%` nor `+` and so cannot carry an encoded form.
+ *
+ * Matching against the ORIGINAL text (rather than an accumulator being rewritten
+ * in place) is the whole point: see {@link redactSensitiveText}.
+ */
+function addPlainMatches(coverageDelta, text, needle) {
+    if (!needle)
+        return;
+    let offset = 0;
+    while (offset <= text.length - needle.length) {
+        const match = text.indexOf(needle, offset);
+        if (match < 0)
+            break;
+        coverageDelta[match] = coverageDelta[match] + 1;
+        coverageDelta[match + needle.length] = coverageDelta[match + needle.length] - 1;
+        offset = match + needle.length;
+    }
+}
+/**
+ * Redact credential-shaped substrings from arbitrary text by pattern alone —
+ * unlike {@link redactSensitiveText}, which requires the exact secret value
+ * up front, this catches credentials no caller ever knew to list. No
+ * truncation is applied; callers that need a length cap (e.g.
+ * {@link redactErrorBody} in src/llm/client.ts) apply it themselves.
+ *
+ * Targets:
+ *  - `Bearer <token>` headers echoed back by a provider
+ *  - `sk-…` / `sk_…` style API keys (OpenAI / Anthropic-shaped)
+ *  - `key-…` / `key_…` shorthand keys
+ *  - `"api_key": "…"` / `"apiKey": "…"` JSON fields
+ *  - Discord webhook URLs (`discord.com/api/webhooks/<id>/<token>`) — the id
+ *    is kept, only the token segment is redacted
+ *  - Slack incoming-webhook URLs (`hooks.slack.com/services/<team>/<channel>/<token>`)
+ *    — the team/channel ids are kept, only the trailing token is redacted
+ */
+export function redactCredentialPatterns(input) {
+    if (!input)
+        return "";
+    return (input
+        // Bearer tokens (case-insensitive)
+        .replace(/\bBearer\s+[A-Za-z0-9._\-+/=]+/gi, "Bearer [REDACTED]")
+        // sk-/sk_ style keys
+        .replace(/\bsk[-_][A-Za-z0-9._-]{6,}/g, "[REDACTED]")
+        // key-/key_ shorthand keys
+        .replace(/\bkey[-_][A-Za-z0-9._-]{6,}/g, "[REDACTED]")
+        // JSON-style "api_key": "...", "apiKey": "...", "api-key": "..."
+        .replace(/("(?:api[_-]?key|apiKey|authorization|token)"\s*:\s*")([^"]*)(")/gi, "$1[REDACTED]$3")
+        // Discord webhook URLs: keep the webhook id, redact the token segment.
+        .replace(/(discord(?:app)?\.com\/api\/webhooks\/\d+\/)[A-Za-z0-9_-]+/gi, "$1[REDACTED]")
+        // Slack incoming-webhook URLs: keep the team/channel ids, redact the token.
+        .replace(/(hooks\.slack\.com\/services\/[A-Za-z0-9]+\/[A-Za-z0-9]+\/)[A-Za-z0-9]+/gi, "$1[REDACTED]"));
+}
+/**
+ * Replace exact sensitive values in text.
+ *
+ * Every match is located against the ORIGINAL text and the result is emitted
+ * once, so overlapping matches merge into a single `[REDACTED]` and no needle
+ * can ever match inside a token an earlier needle produced.
+ *
+ * That last property is load-bearing. This function used to take a `replaceAll`
+ * fast path that chained over a *mutating* accumulator, which meant any needle
+ * drawn from the letters of `[REDACTED]` re-matched the tokens already injected
+ * and the output grew geometrically: `redactSensitiveText("a".repeat(50),
+ * ["a","E","D","T","C","R"])` returned 32,450 characters — 649x the input. On a
+ * path where the needle set is derived from configuration or the environment,
+ * that is a memory-exhaustion hazard reachable from ordinary command output.
+ * The encoded-form path never had the bug because it always worked this way.
  */
 export function redactSensitiveText(text, sensitiveValues) {
     const values = [...new Set(sensitiveValues)]
@@ -307,22 +373,24 @@ export function redactSensitiveText(text, sensitiveValues) {
         .sort((a, b) => b.length - a.length || a.localeCompare(b));
     if (values.length === 0)
         return text;
-    if (!text.includes("%") && !text.includes("+")) {
-        let redacted = text;
+    const coverageDelta = new Int32Array(text.length + 1);
+    if (text.includes("%") || text.includes("+")) {
+        // Percent-/plus-encoded text: match needle and haystack in their decoded
+        // forms, mapping hits back to source offsets.
+        const addMatchesForMode = (plusAsSpace) => {
+            const haystack = normalizeEncodedText(text, plusAsSpace);
+            for (const value of values) {
+                addMappedMatches(coverageDelta, haystack, normalizeEncodedText(value, plusAsSpace).text);
+            }
+        };
+        addMatchesForMode(false);
+        if (text.includes("+"))
+            addMatchesForMode(true);
+    }
+    else {
         for (const value of values)
-            redacted = redacted.replaceAll(value, "[REDACTED]");
-        return redacted;
+            addPlainMatches(coverageDelta, text, value);
     }
-    const coverageDelta = new Int32Array(text.length + 1);
-    const addMatchesForMode = (plusAsSpace) => {
-        const haystack = normalizeEncodedText(text, plusAsSpace);
-        for (const value of values) {
-            addMappedMatches(coverageDelta, haystack, normalizeEncodedText(value, plusAsSpace).text);
-        }
-    };
-    addMatchesForMode(false);
-    if (text.includes("+"))
-        addMatchesForMode(true);
     let redacted = "";
     let coverage = 0;
     let offset = 0;
@@ -350,7 +418,20 @@ export function redactSensitiveValue(value, sensitiveValues) {
         if (Array.isArray(entry))
             return entry.map(redact);
         if (entry && typeof entry === "object") {
-            return Object.fromEntries(Object.entries(entry).map(([key, child]) => [redactSensitiveText(key, values), redact(child)]));
+            const out = {};
+            for (const [key, child] of Object.entries(entry)) {
+                const redactedKey = redactSensitiveText(key, values);
+                // Two DISTINCT keys can redact to the same string (`{a, b, ab}` under
+                // needles `a`/`b` all collapse toward `[REDACTED]`). Building this with
+                // `Object.fromEntries` kept only the last of each colliding group, so a
+                // field was silently DROPPED rather than redacted — data loss disguised
+                // as redaction. Suffix instead: the value stays, the key stays hidden.
+                let finalKey = redactedKey;
+                for (let n = 2; Object.hasOwn(out, finalKey); n++)
+                    finalKey = `${redactedKey} (${n})`;
+                out[finalKey] = redact(child);
+            }
+            return out;
         }
         return entry;
     };

package/dist/core/spawn-env.js

@@ -0,0 +1,234 @@
+// 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/.
+/**
+ * The ONE allowlist-based child-environment primitive.
+ *
+ * Two akm code paths spawn a child from an explicit list of environment
+ * variable NAMES — the agent-CLI spawn wrapper
+ * (`integrations/agent/spawn.ts`, `profile.envPassthrough`) and the workflow
+ * `exec` unit runner (`workflows/exec/exec-unit.ts`) — and both start from an
+ * EMPTY environment and copy through named entries with
+ * {@link collectAllowlistedEnv}. Keeping that in one leaf module is what makes
+ * "allowlist" a single reviewable mechanism instead of two implementations
+ * that drift apart.
+ *
+ * NOT covered: the opencode-sdk server spawn
+ * (`integrations/harnesses/opencode-sdk/sdk-runner.ts`) keeps its own
+ * hard-coded name list and does not route through here, so it gets neither the
+ * platform floor below nor PATH supplementation.
+ *
+ * A LEAF: node built-ins only, so both the integrations layer and the workflow
+ * engine can import it without opening a cycle.
+ *
+ * @module core/spawn-env
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * The baseline env names every allowlisted akm child receives regardless of
+ * what it runs: process identity (`HOME`, `USER`), tool resolution (`PATH`),
+ * locale (`LANG`, `LC_ALL`), terminal (`TERM`), scratch space (`TMPDIR`), and
+ * akm's own event provenance (`AKM_EVENT_SOURCE` — machine traffic, never a
+ * secret). BOTH allowlists extend it — the agent-CLI profiles'
+ * `COMMON_PASSTHROUGH` (`integrations/agent/profiles.ts`) and the workflow
+ * exec unit's `EXEC_DEFAULT_ENV_PASSTHROUGH` (`workflows/exec/exec-unit.ts`)
+ * — so a baseline name cannot drift into one child-spawn path but not the
+ * other. NOTE: profile `envPassthrough` is frozen into workflow engine
+ * snapshots, so growing this list changes frozen-plan content — extend
+ * deliberately.
+ */
+export const COMMON_SPAWN_ENV_PASSTHROUGH = [
+    "HOME",
+    "PATH",
+    "USER",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "TMPDIR",
+    "AKM_EVENT_SOURCE",
+];
+/**
+ * The names Windows itself requires of ANY child, whatever the caller's
+ * allowlist says. Applied at build time rather than added to
+ * {@link COMMON_SPAWN_ENV_PASSTHROUGH} because profile `envPassthrough` is
+ * frozen into workflow engine snapshots: growing the shared list would change
+ * the bytes — and so the hashes — of every plan already on disk, to express
+ * something that is not a policy choice at all.
+ *
+ * `SystemRoot`, `SystemDrive` and `WINDIR` are what PROCESS CREATION reads;
+ * without them the loader cannot find system DLLs and the spawn fails before
+ * the command runs. Without `PATHEXT` Windows never tries `bun.exe`/`bun.cmd`,
+ * so a `bin: "bun"` profile is unresolvable, and `COMSPEC` is how `.bat`/`.cmd`
+ * targets resolve at all. The rest are the win32 analogues of baseline names
+ * the POSIX side already grants — `HOME` (`USERPROFILE`, `HOMEDRIVE`,
+ * `HOMEPATH`) and `TMPDIR` (`TEMP`, `TMP`). None is a secret.
+ *
+ * Config and install roots (`APPDATA`, `LOCALAPPDATA`, `ProgramFiles`, …) are
+ * deliberately NOT here: a child can be created and can resolve its command
+ * without them, so which allowlist wants them stays a per-caller decision.
+ *
+ * THE definition of the floor. The workflow exec allowlist
+ * (`EXEC_DEFAULT_ENV_PASSTHROUGH`) spreads this constant rather than
+ * re-spelling it, because that list is also consumed on POSIX — where
+ * {@link spawnEnvNamesFor} appends nothing — and the names still have to be
+ * requestable there for a win32 run of the same workflow.
+ */
+export const WIN32_SPAWN_ENV_FLOOR = [
+    "SystemRoot",
+    "SystemDrive",
+    "WINDIR",
+    "COMSPEC",
+    "PATHEXT",
+    "USERPROFILE",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "TEMP",
+    "TMP",
+];
+/**
+ * The effective allowlist for `platform`: the caller's names, plus any floor
+ * the operating system requires of every child regardless of allowlist.
+ * Exported for tests, which must be able to ask for a platform they are not
+ * running on.
+ */
+export function spawnEnvNamesFor(names, platform = process.platform) {
+    const effective = [...names];
+    if (platform !== "win32")
+        return effective;
+    // Deduped by EXACT spelling, never case-folded: {@link collectAllowlistedEnv}
+    // looks each surviving name up with exactly this case, and a `source` that is
+    // a plain object — the agent spawn's `envSource` seam — does not case-fold.
+    // Suppressing `SystemRoot` because the caller happened to write `SYSTEMROOT`
+    // would therefore drop the loader-critical variable the floor exists to
+    // guarantee. Keeping both spellings is harmless: the win32 environment is
+    // itself case-insensitive, so they resolve to the same value.
+    const present = new Set(effective);
+    for (const name of WIN32_SPAWN_ENV_FLOOR) {
+        if (!present.has(name))
+            effective.push(name);
+    }
+    return effective;
+}
+/**
+ * Build a child environment from an allowlist: start EMPTY and copy through
+ * exactly the named variables that exist in `source`. Names absent from the
+ * source are simply absent from the child (never an empty string, which many
+ * tools treat as "set but blank").
+ *
+ * `PATH`, when it comes through, is supplemented for scheduler contexts — see
+ * {@link supplementPathForSchedulerContext}. That happens here rather than in
+ * each caller so a child spawned from cron/launchd/Task Scheduler can find the
+ * user's toolchain no matter which spawn path reached it. On win32 the names
+ * in {@link WIN32_SPAWN_ENV_FLOOR} come through too, for the same reason: the
+ * spawn cannot succeed without them, whichever caller built the list.
+ */
+export function collectAllowlistedEnv(names, source = process.env) {
+    const env = {};
+    for (const name of spawnEnvNamesFor(names)) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    if (env.PATH !== undefined) {
+        env.PATH = supplementPathForSchedulerContext(env.PATH);
+    }
+    return env;
+}
+/**
+ * Answers already computed by {@link supplementPathForSchedulerContext}, keyed
+ * by the input PATH and the home directory it was computed against.
+ *
+ * Correctness envelope: the answer is a pure function of those two, the
+ * platform, and which candidate directories exist on disk. The platform cannot
+ * change under a running process, and the other two are in the key — so the one
+ * thing the memo assumes is that a candidate directory does not APPEAR while
+ * akm runs. Answering the rest of a run the way its start was answered is what
+ * a shell's own command-path caching already does, and the cost of not
+ * memoizing is paid on every child-env build: two PATH splits and up to seven
+ * SYNCHRONOUS `existsSync` probes, on the event loop a 10 000-unit fan-out
+ * shares with the run's lease heartbeat.
+ *
+ * Bounded so a caller that somehow varies its PATH cannot grow it without
+ * limit; a spawn path only ever sees a handful of distinct PATH strings, so
+ * the reset is effectively unreachable in practice.
+ */
+const supplementedPaths = new Map();
+const SUPPLEMENTED_PATH_MEMO_MAX = 64;
+/**
+ * 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.
+ *
+ * Memoized per input PATH — see {@link supplementedPaths} for what that
+ * assumes.
+ */
+export function supplementPathForSchedulerContext(existingPath) {
+    const home = os.homedir();
+    // NUL-joined so no pair of (home, PATH) can collide onto one key: no path
+    // component can contain a NUL.
+    const key = `${home}\u0000${existingPath}`;
+    const memoized = supplementedPaths.get(key);
+    if (memoized !== undefined)
+        return memoized;
+    const supplemented = computeSupplementedPath(existingPath, home);
+    if (supplementedPaths.size >= SUPPLEMENTED_PATH_MEMO_MAX)
+        supplementedPaths.clear();
+    supplementedPaths.set(key, supplemented);
+    return supplemented;
+}
+function computeSupplementedPath(existingPath, home) {
+    // A home of `/` (system crontab, launchd, service accounts) or of `""`
+    // prefixes EVERY entry, so a prefix test would read the most stripped
+    // environments there are as interactive and skip the repair they exist for.
+    const comparableHome = home === "" || home === path.sep ? undefined : home;
+    // If PATH already contains the home directory, we are in an interactive
+    // shell — skip supplementation entirely. Compared on a path boundary: a
+    // sibling home (`/home/alice` next to `/home/al`) is not this user's.
+    const isUnderHome = (dir) => comparableHome !== undefined && (dir === comparableHome || dir.startsWith(comparableHome + path.sep));
+    if (existingPath.split(path.delimiter).some(isUnderHome)) {
+        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",
+    ];
+}