akm-cli 0.7.5 → 0.8.0-rc2

package/dist/integrations/agent/index.js

@@ -13,5 +13,7 @@
 export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config";
 export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
-export { buildProposePrompt, buildReflectPrompt, parseAgentProposalPayload, stripJsonFences } from "./prompts";
+export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, parseAgentProposalPayload, stripJsonFences, } from "./prompts";
+export { runWithAgentRunner, selectAgentRunner } from "./runners";
+export { runAgentSdk } from "./sdk-runner";
 export { runAgent } from "./spawn";

package/dist/integrations/agent/pipeline.js

@@ -0,0 +1,39 @@
+/**
+ * Shared proposal-agent pipeline for `akm propose` and `akm reflect`.
+ *
+ * Both commands share the same core spawn step: resolve a profile, build a
+ * prompt, run the agent, and return a structured result. This module extracts
+ * that shared step so the two command implementations stay focused on their
+ * own pre-processing (prompt building) and post-processing (proposal creation).
+ */
+import { runWithAgentRunner } from "./runners";
+/**
+ * Run the agent for a proposal-producing command (propose or reflect).
+ *
+ * When `profile.sdkMode` is true, routes to {@link runAgentSdk} (no CLI
+ * binary required). Otherwise, when `draftFilePath` is set the agent is
+ * spawned in interactive mode so it can use its file tools to write the draft
+ * directly. When no draft path is provided the agent is spawned in captured
+ * mode and output is read from stdout.
+ */
+export async function runProposalAgentPipeline(opts) {
+    const result = await runWithAgentRunner({
+        profile: opts.profile,
+        prompt: opts.prompt,
+        llmConfig: opts.llmConfig,
+        runOptions: {
+            stdio: opts.draftFilePath ? "interactive" : "captured",
+            parseOutput: "text",
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        },
+    });
+    return {
+        ok: result.ok,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        durationMs: result.durationMs,
+        exitCode: result.exitCode,
+        error: result.error,
+        reason: result.reason,
+    };
+}

package/dist/integrations/agent/profiles.js

@@ -3,6 +3,8 @@ const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "T
  * Built-in profiles for the five agent CLIs the v1 spec calls out
  * explicitly. The fields here are conservative defaults — every value is
  * overridable from user config.
+ *
+ * For headless/automation use (propose, reflect, tasks), use the '-headless' variant.
  */
 const BUILTINS = {
     opencode: {
@@ -46,15 +48,75 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
-/** Names of every built-in profile. Stable, sorted. */
+/**
+ * Headless variants of the five base profiles for automation use (propose, reflect, tasks).
+ *
+ * These profiles use `stdio: "captured"` and `parseOutput: "json"` so the
+ * agent's response can be read from stdout. They share the same `bin` and
+ * `envPassthrough` as the corresponding base profile but are intentionally
+ * kept out of `BUILTIN_AGENT_PROFILE_NAMES` (and therefore out of CLI
+ * detection/enumeration) to avoid showing up as separate installable profiles.
+ *
+ * Users may reference them by name via `--profile opencode-headless` or by
+ * setting `agent.default: "opencode-headless"` in config.json.
+ */
+const HEADLESS_BUILTINS = {
+    "opencode-headless": {
+        name: "opencode-headless",
+        bin: "opencode",
+        args: ["run"],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
+        parseOutput: "json",
+    },
+    "claude-headless": {
+        name: "claude-headless",
+        bin: "claude",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "ANTHROPIC_API_KEY", "CLAUDE_CONFIG"],
+        parseOutput: "json",
+    },
+    "codex-headless": {
+        name: "codex-headless",
+        bin: "codex",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "CODEX_CONFIG"],
+        parseOutput: "json",
+    },
+    "gemini-headless": {
+        name: "gemini-headless",
+        bin: "gemini",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "GEMINI_API_KEY", "GOOGLE_API_KEY"],
+        parseOutput: "json",
+    },
+    "aider-headless": {
+        name: "aider-headless",
+        bin: "aider",
+        args: ["--no-auto-commits"],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+        parseOutput: "json",
+    },
+};
+/**
+ * Names of the five primary built-in profiles. Stable, sorted. Does NOT
+ * include the `-headless` variants (those are resolvable by name but are
+ * excluded from detection/enumeration flows).
+ */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
-/** Returns the built-in profile by name, or `undefined` if not built-in. */
+/** Returns the built-in profile by name (including headless variants), or `undefined` if not found. */
 export function getBuiltinAgentProfile(name) {
-    return BUILTINS[name];
+    return BUILTINS[name] ?? HEADLESS_BUILTINS[name];
 }
 /**
- * Return a deep copy of every built-in profile keyed by name. Callers
- * should not assume reference equality with subsequent calls.
+ * Return a deep copy of every primary built-in profile keyed by name.
+ * Headless variants are NOT included — use `getBuiltinAgentProfile(name)`
+ * to look them up by name. Callers should not assume reference equality with
+ * subsequent calls.
  */
 export function listBuiltinAgentProfiles() {
     const out = {};

package/dist/integrations/agent/prompts.js

@@ -23,13 +23,14 @@
  * during validation. We carry it through if the agent supplies it.
  */
 import { TYPE_DIRS } from "../../core/asset-spec";
+import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
  * the agent can produce content that passes proposal validation. Kept tiny:
  * full schema docs live in `docs/` — these are nudges, not contracts.
  */
 const TYPE_HINTS = {
-    lesson: "lesson assets MUST start with frontmatter containing `description` and `when_to_use` keys (both non-empty). Body should be 1–3 short paragraphs of practical guidance.",
+    lesson: "lesson assets MUST start with frontmatter containing `description` and `when_to_use` keys (both non-empty). Body: 1–3 short paragraphs of practical guidance. A lesson is NOT a restatement of the source asset — it answers: When should I reach for this? What goes wrong without it? What did real use reveal that the asset itself doesn't say?",
     skill: "skill assets are stored as `skills/<name>/SKILL.md`. Frontmatter typically includes `name`, `description`, and `when_to_use`.",
     command: "command assets are markdown with optional frontmatter (`name`, `description`). The body is the prompt template the user invokes.",
     agent: "agent assets are markdown with frontmatter describing the agent role (`name`, `description`, optional `tools`, `model`).",
@@ -80,7 +81,15 @@ function fileWriteContract(draftFilePath) {
 export function buildReflectPrompt(input) {
     const sections = [];
     if (input.ref && input.type && input.name) {
-        sections.push(`You are reviewing an akm stash asset (${input.type}) called "${input.name}" and proposing an improved version.`);
+        // Change 2 — type-conditioned goal framing
+        const isLesson = input.type === "lesson";
+        const isSkill = input.type === "skill";
+        const goalSentence = isLesson
+            ? `Your task is to distill what usage signals reveal about this ${input.type} asset — when to reach for it, what goes wrong without it, and what real use has revealed that the asset itself does not say. Do not reproduce the source content; your proposal must add information the source does not contain.`
+            : isSkill
+                ? "Your task is to review this skill asset, identify what the feedback and related distilled lessons show is broken, missing, unclear, or durable enough to promote into long-term documentation, and produce a single improved proposal. If the strongest evidence points to companion reference material rather than the main SKILL.md, you may instead propose a skill-adjacent knowledge doc such as `knowledge:skills/<skill>/references/<topic>`."
+                : `Your task is to review this ${input.type} asset, identify what the feedback signals as broken, missing, or unclear, and produce an improved version. Do not reproduce the source content unchanged; your proposal must correct or add something the source lacks.`;
+        sections.push(goalSentence);
         sections.push(`Target ref: ${input.ref}`);
         sections.push(`Asset-type guidance: ${hintForType(input.type)}`);
     }
@@ -92,6 +101,23 @@ export function buildReflectPrompt(input) {
     if (input.task?.trim()) {
         sections.push(`Task / focus: ${input.task.trim()}`);
     }
+    // Change 3 & 4 — feedback moved before asset content; missing else branch added
+    if (input.feedback && input.feedback.length > 0) {
+        sections.push("Recent feedback / signals:");
+        for (const line of input.feedback)
+            sections.push(`- ${line}`);
+    }
+    else if (!input.ref) {
+        sections.push("Recent feedback / signals:");
+        sections.push("- (no feedback events recorded)");
+    }
+    else if (input.type === "skill" && input.relatedLessons && input.relatedLessons.length > 0) {
+        sections.push("No direct feedback events were recorded. Limit substantive changes to what is justified by the related distilled lessons below; do not speculate beyond that evidence.");
+    }
+    else {
+        // ref is set but no feedback — explicitly constrain scope to schema compliance
+        sections.push("No usage feedback recorded. Limit your proposal to schema and structural improvements only: missing required frontmatter fields, unclear `when_to_use`, ambiguous description, or broken formatting. Do not speculate about runtime weaknesses you have not observed.");
+    }
     if (input.assetContent?.trim()) {
         sections.push("Current asset content (verbatim):");
         sections.push("```");
@@ -104,21 +130,27 @@ export function buildReflectPrompt(input) {
     else {
         sections.push("(No existing asset content was supplied.)");
     }
-    if (input.feedback && input.feedback.length > 0) {
-        sections.push("Recent feedback / signals:");
-        for (const line of input.feedback)
-            sections.push(`- ${line}`);
-    }
-    else if (!input.ref) {
-        sections.push("Recent feedback / signals:");
-        sections.push("- (no feedback events recorded)");
-    }
     if (input.schemaHints && input.schemaHints.length > 0) {
         sections.push("Schema / lint hints to address:");
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
-    sections.push("Produce a single proposal that addresses the feedback and respects the asset-type contract.");
+    if (input.relatedLessons && input.relatedLessons.length > 0) {
+        sections.push("Related distilled lessons to evaluate for consolidation:");
+        for (const lesson of input.relatedLessons) {
+            sections.push(`Lesson ref: ${lesson.ref}`);
+            sections.push("```");
+            sections.push(lesson.content.trimEnd());
+            sections.push("```");
+        }
+        sections.push("Evaluate whether these lessons contain strong evidence of factual, repeatable guidance that should be promoted into long-term skill documentation.");
+        sections.push("Promote only guidance that is durable, generally applicable, and supported by repeated evidence. Do not copy anecdotal details, one-off incidents, or duplicate wording verbatim.");
+        sections.push("If the guidance belongs in the main skill instructions, update the skill proposal. If it belongs in a companion reference document, return a `knowledge:skills/<skill>/references/<topic>` proposal instead.");
+    }
+    if (input.avoidPatterns && input.avoidPatterns.length > 0) {
+        sections.push(`## Avoid These Patterns\nPrevious assets in this run produced these errors — do not repeat them:\n${input.avoidPatterns.map((e) => `- ${e}`).join("\n")}`);
+    }
+    sections.push("Produce a single proposal that addresses the feedback and respects the asset-type contract. If the proposal's frontmatter is missing `when_to_use`, you MUST generate one — a one-line trigger sentence describing exactly when a user should reach for this asset.");
     sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
 }
@@ -141,6 +173,33 @@ export function buildProposePrompt(input) {
     sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
 }
+/**
+ * Build the prompt for the schema repair pass in `akm improve`. Asks the
+ * agent to add the minimal required frontmatter to an asset that failed
+ * validation — without rewriting the body.
+ */
+export function buildSchemaRepairPrompt(input) {
+    const sections = [];
+    sections.push(`This ${input.type} asset failed schema validation with the error: "${input.reason}". ` +
+        `Your task is to fix the schema issue by adding or correcting the missing/invalid field(s) ` +
+        `while preserving all existing content.`);
+    sections.push(`Target ref: ${input.ref}`);
+    sections.push(`Schema requirements for ${input.type} assets: ${hintForType(input.type)}`);
+    const CONTENT_CAP = 3000;
+    const body = input.assetContent.trimEnd();
+    const truncated = body.length > CONTENT_CAP;
+    sections.push("Current asset content (first 3000 chars — sufficient to generate missing frontmatter):");
+    sections.push("```");
+    sections.push(truncated ? `${body.slice(0, CONTENT_CAP)}\n... [truncated]` : body);
+    sections.push("```");
+    sections.push("Produce the minimal fix: add ONLY the missing required frontmatter field(s). " +
+        "Do not rewrite the body unless it is empty. " +
+        "If `description` is missing, generate a concise one-sentence description from the content. " +
+        "If `when_to_use` is missing, generate a one-line trigger sentence. " +
+        "Preserve all existing frontmatter keys and the full body verbatim.");
+    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
+    return sections.join("\n\n");
+}
 /**
  * Parse agent stdout into a proposal payload. The agent contract requires a
  * single JSON object; anything else is reported as a parse error so callers
@@ -151,7 +210,8 @@ export function buildProposePrompt(input) {
  *  2. Prose preamble / postamble around the JSON object (handled by `extractEmbeddedJson`).
  */
 export function parseAgentProposalPayload(stdout) {
-    const trimmed = stripJsonFences(stdout).trim();
+    // Strip <think> blocks and fences, then attempt full parse with embedded fallback.
+    const trimmed = stripCodeFences(stripThinkBlocks(stdout)).trim();
     if (!trimmed)
         throw new Error("agent produced empty output");
     let parsed;
@@ -162,7 +222,7 @@ export function parseAgentProposalPayload(stdout) {
         // Agent output contains prose before/after the JSON object (e.g. a local
         // LLM that narrates before responding). Try extracting the first balanced
         // top-level `{…}` from the text rather than failing immediately.
-        const embedded = extractEmbeddedJson(trimmed);
+        const embedded = parseEmbeddedJsonResponse(trimmed);
         if (!embedded)
             throw directErr;
         parsed = embedded;
@@ -182,66 +242,11 @@ export function parseAgentProposalPayload(stdout) {
     }
     return out;
 }
-/**
- * Extract the first balanced top-level `{…}` object from `text`. Used as a
- * fallback when direct `JSON.parse` fails due to surrounding prose. Kept
- * local to `agent/` (mirrors `parseEmbeddedJsonResponse` in `src/llm/client.ts`
- * without importing across the one-way boundary — v1 spec §9.7).
- */
-function extractEmbeddedJson(text) {
-    for (let start = 0; start < text.length; start++) {
-        if (text[start] !== "{")
-            continue;
-        let depth = 0;
-        let inString = false;
-        let escaped = false;
-        for (let i = start; i < text.length; i++) {
-            const ch = text[i];
-            if (inString) {
-                if (escaped) {
-                    escaped = false;
-                }
-                else if (ch === "\\") {
-                    escaped = true;
-                }
-                else if (ch === '"') {
-                    inString = false;
-                }
-                continue;
-            }
-            if (ch === '"') {
-                inString = true;
-                continue;
-            }
-            if (ch === "{")
-                depth++;
-            if (ch === "}") {
-                depth--;
-                if (depth === 0) {
-                    try {
-                        return JSON.parse(text.slice(start, i + 1));
-                    }
-                    catch {
-                        break;
-                    }
-                }
-            }
-        }
-    }
-    return undefined;
-}
 /**
  * Strip `\`\`\`json … \`\`\`` fences and `<think>…</think>` reasoning blocks
- * from agent output. Mirrors `client.ts` but kept local to `agent/` per v1
- * spec §9.7 (one-way boundary — `agent/` does not import from `llm/`).
+ * from agent output. Thin wrapper around `core/parse` helpers, kept exported
+ * for backward compatibility (re-exported from `integrations/agent/index.ts`).
  */
 export function stripJsonFences(text) {
-    const stripped = text
-        .trim()
-        .replace(/<think>[\s\S]*?<\/think>/gi, "")
-        .trim();
-    const fenced = stripped.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
-    if (fenced)
-        return fenced[1] ?? stripped;
-    return stripped;
+    return stripCodeFences(stripThinkBlocks(text));
 }

package/dist/integrations/agent/runners.js

@@ -0,0 +1,31 @@
+import { runAgentSdk } from "./sdk-runner";
+import { runAgent } from "./spawn";
+const spawnAgentRunner = {
+    name: "spawn-agent-runner",
+    supports(profile) {
+        return profile.sdkMode !== true;
+    },
+    run(request) {
+        return runAgent(request.profile, request.prompt, request.runOptions ?? {});
+    },
+};
+const sdkAgentRunner = {
+    name: "sdk-agent-runner",
+    supports(profile) {
+        return profile.sdkMode === true;
+    },
+    run(request) {
+        return runAgentSdk(request.profile, request.prompt ?? "", request.runOptions ?? {}, request.llmConfig);
+    },
+};
+export const defaultAgentRunners = [spawnAgentRunner, sdkAgentRunner];
+export function selectAgentRunner(profile, runners = defaultAgentRunners) {
+    const runner = runners.find((candidate) => candidate.supports(profile));
+    if (!runner) {
+        throw new Error(`No agent runner available for profile "${profile.name}".`);
+    }
+    return runner;
+}
+export async function runWithAgentRunner(request, runners = defaultAgentRunners) {
+    return selectAgentRunner(request.profile, runners).run(request);
+}

package/dist/integrations/agent/sdk-runner.js

@@ -0,0 +1,120 @@
+/**
+ * OpenCode SDK agent runner — uses embedded @opencode-ai/sdk instead of
+ * Bun.spawn. Requires no agent CLI binary to be installed. The user provides
+ * an OpenAI-compatible endpoint (or inherits from config.llm) for the SDK.
+ */
+// Singleton server — started once per process, reused across calls
+let _server = null;
+/**
+ * Close the singleton OpenCode SDK server and reset the handle.
+ * Primarily for use in tests to ensure clean teardown between test runs.
+ */
+export function closeServer() {
+    try {
+        _server?.server.close();
+    }
+    catch {
+        /* ignore */
+    }
+    _server = null;
+}
+async function getOrStartServer(profile, llmConfig) {
+    if (_server)
+        return _server;
+    const { createOpencode } = await import("@opencode-ai/sdk").catch(() => {
+        throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
+    });
+    // Resolve endpoint and model: profile fields take precedence over config.llm
+    const endpoint = profile.endpoint ?? llmConfig?.endpoint;
+    const apiKey = profile.apiKey ?? llmConfig?.apiKey;
+    const model = profile.model;
+    const sdkConfig = {};
+    if (model)
+        sdkConfig.model = model;
+    if (endpoint || apiKey) {
+        // Configure a custom OpenAI-compatible provider
+        sdkConfig.provider = {
+            "akm-custom": {
+                npm: "@ai-sdk/openai-compatible",
+                options: {
+                    baseURL: endpoint?.replace(/\/chat\/completions$/, "").replace(/\/$/, ""),
+                    ...(apiKey ? { apiKey } : {}),
+                },
+            },
+        };
+        // Use the custom provider's model if not already qualified
+        if (model && !model.includes("/")) {
+            sdkConfig.model = `akm-custom/${model}`;
+        }
+    }
+    _server = (await createOpencode(Object.keys(sdkConfig).length > 0 ? { config: sdkConfig } : {}));
+    process.once("exit", () => {
+        closeServer();
+    });
+    if (!_server)
+        throw new Error("Failed to initialise OpenCode SDK server.");
+    return _server;
+}
+export async function runAgentSdk(profile, prompt, _opts = {}, llmConfig) {
+    const start = Date.now();
+    let client;
+    try {
+        ({ client } = await getOrStartServer(profile, llmConfig));
+    }
+    catch (e) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: String(e),
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "spawn_failed",
+            error: String(e),
+        };
+    }
+    // One session per call — do NOT reuse (history accumulates, token costs grow)
+    const sessionRes = await client.session.create({ body: { title: "akm" } });
+    const sessionId = sessionRes.data?.id;
+    if (!sessionId) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: "Failed to create session",
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "spawn_failed",
+            error: "Failed to create OpenCode session",
+        };
+    }
+    try {
+        const result = await client.session.prompt({
+            path: { id: sessionId },
+            body: { parts: [{ type: "text", text: prompt }] },
+        });
+        const parts = result.data?.parts ?? [];
+        const textPart = parts.find((p) => p.type === "text");
+        const stdout = textPart?.text ?? "";
+        return {
+            ok: true,
+            stdout,
+            stderr: "",
+            durationMs: Date.now() - start,
+            exitCode: 0,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: String(e),
+            durationMs: Date.now() - start,
+            exitCode: 1,
+            reason: "non_zero_exit",
+            error: String(e),
+        };
+    }
+    finally {
+        // Clean up session to prevent disk accumulation in ~/.local/share/opencode/
+        await client.session.delete({ path: { id: sessionId } }).catch(() => { });
+    }
+}

package/dist/integrations/agent/spawn.js

@@ -11,6 +11,9 @@
  * 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 { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
 /**
  * Kill the process group of `proc` with `signal`, falling back to
@@ -39,6 +42,39 @@ export function killGroup(proc, signal) {
     }
 }
 const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
+/**
+ * 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 = [
+        path.join(home, ".bun", "bin"),
+        path.join(home, ".cargo", "bin"),
+        path.join(home, ".local", "bin"),
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+    ];
+    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 resolveSpawnFn(options) {
     if (options.spawn)
         return options.spawn;
@@ -54,6 +90,10 @@ function resolveSpawnFn(options) {
  *   • Every name in `profile.envPassthrough`.
  *   • 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;
@@ -63,6 +103,11 @@ function buildChildEnv(profile, options) {
         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);
+    }
     if (profile.env) {
         for (const [k, v] of Object.entries(profile.env))
             env[k] = v;
@@ -109,7 +154,8 @@ async function readStream(stream, opts) {
  */
 export async function runAgent(profile, prompt, options = {}) {
     const stdioMode = options.stdio ?? profile.stdio;
-    const timeoutMs = options.timeoutMs ?? profile.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // null = explicitly disabled (no kill timer). undefined = inherit from profile/default.
+    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : (profile.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
@@ -153,26 +199,34 @@ export async function runAgent(profile, prompt, options = {}) {
     // BUG-M3: only flag `timedOut` when the child has not already exited. A
     // timer firing in the same microtask as `proc.exited` resolving could
     // otherwise label a clean exit as a timeout.
+    //
+    // When timeoutMs is null the kill timer is skipped entirely — the task runs
+    // until the process exits naturally. Intended for long-running local-model
+    // tasks where wall-clock time is unpredictable.
     let timedOut = false;
-    const timer = setTimeoutImpl(() => {
-        if (proc.exitCode !== null)
-            return;
-        timedOut = true;
-        killGroup(proc, "SIGTERM");
-        // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
-        setTimeoutImpl(() => {
+    let timer;
+    if (timeoutMs !== null) {
+        timer = setTimeoutImpl(() => {
             if (proc.exitCode !== null)
                 return;
-            killGroup(proc, "SIGKILL");
-        }, 5000);
-    }, timeoutMs);
+            timedOut = true;
+            killGroup(proc, "SIGTERM");
+            // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
+            setTimeoutImpl(() => {
+                if (proc.exitCode !== null)
+                    return;
+                killGroup(proc, "SIGKILL");
+            }, 5000);
+        }, timeoutMs);
+    }
     // Stream-drain timeout: the overall wall-clock budget plus a 2 s grace
     // period. When a process is killed via SIGTERM/SIGKILL (from our timeout
     // handler or from outside) some runtimes keep the pipe write-end open in
     // background threads, which would cause `Response.text()` to block forever.
-    // Capping stream draining at `timeoutMs + 2 000 ms` ensures the caller
-    // never hangs past the wall budget regardless of subprocess pipe behaviour.
-    const streamDrainTimeoutMs = timeoutMs + 2_000;
+    // Capping stream draining ensures the caller never hangs past the wall
+    // budget regardless of subprocess pipe behaviour.
+    // When there is no kill timer, allow up to 30 s for streams to drain.
+    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
     const stdoutPromise = stdioMode === "captured"
         ? readStream(proc.stdout ?? null, { timeoutMs: streamDrainTimeoutMs })
         : Promise.resolve("");
@@ -209,7 +263,8 @@ export async function runAgent(profile, prompt, options = {}) {
         exitCode = await proc.exited;
     }
     catch (err) {
-        clearTimeoutImpl(timer);
+        if (timer !== undefined)
+            clearTimeoutImpl(timer);
         // BUG-H2: drain stream readers before the early return so they don't
         // surface as unhandled rejections after the function resolves.
         // The streams already carry a built-in drain timeout so this allSettled
@@ -237,7 +292,7 @@ export async function runAgent(profile, prompt, options = {}) {
             stderr,
             durationMs,
             reason: "timeout",
-            error: `agent CLI "${profile.name}" timed out after ${timeoutMs}ms`,
+            error: `agent CLI "${profile.name}" timed out after ${timeoutMs ?? 0}ms`,
         };
     }
     if (exitCode !== 0) {