akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/indexer/walk/matchers.js

@@ -10,9 +10,6 @@
  */
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
-import { looksLikeWorkflow } from "../../workflows/parser.js";
-import { looksLikeWorkflowProgram } from "../../workflows/program/parser.js";
-import { WORKFLOW_PROGRAM_RENDERER_NAME } from "../../workflows/program/project.js";
 // ---------------------------------------------------------------------------
 // Private data
 // ---------------------------------------------------------------------------
@@ -37,6 +34,18 @@ const DIR_TYPE_MAP = [
         type: "knowledge",
         test: (ext) => ext === ".md",
     },
+    {
+        // R-045 / Q-18 second half (owner ruling 11) — stash-resident `instruction`
+        // assets live under `instructions/`, mirroring the `knowledge` rule. This
+        // is a walker discovery rule for FILES ON DISK under a stash's
+        // `instructions/` dir; it is unrelated to the adapter-emitted root
+        // CLAUDE.md/AGENTS.md instruction docs (`tool-dir-shared.ts`), which are
+        // synthesized by format-family adapters, carry `ownsPresentation: true`,
+        // and never pass through this matcher at all.
+        dir: "instructions",
+        type: "instruction",
+        test: (ext) => ext === ".md",
+    },
     {
         dir: "workflows",
         type: "workflow",
@@ -102,6 +111,9 @@ const TYPED_DIR_DOC_FILES = new Set(["readme.md"]);
 function isTypedDirDocFile(fileName) {
     return TYPED_DIR_DOC_FILES.has(fileName.toLowerCase());
 }
+function isNestedSkillResource(ctx) {
+    return ctx.ancestorDirs[0] === "skills" && ctx.ancestorDirs.length > 1 && ctx.fileName !== "SKILL.md";
+}
 // ---------------------------------------------------------------------------
 // Private helpers
 // ---------------------------------------------------------------------------
@@ -132,6 +144,8 @@ function classifyByExtension(ctx) {
     return null;
 }
 function classifyByDirectory(ctx) {
+    if (isNestedSkillResource(ctx))
+        return null;
     for (const dir of ctx.ancestorDirs) {
         const result = matchDirectoryHint(dir, ctx, 10);
         if (result)
@@ -141,6 +155,8 @@ function classifyByDirectory(ctx) {
 }
 function classifyByParentDirHint(ctx) {
     const { parentDir, ext, fileName } = ctx;
+    if (isNestedSkillResource(ctx))
+        return null;
     if (parentDir === "skills" && (fileName === "SKILL.md" || ext === ".md")) {
         return { type: "skill", specificity: 15 };
     }
@@ -162,12 +178,19 @@ function classifyBySmartMd(ctx) {
         return { type: "knowledge", specificity: 5 };
     }
     const body = ctx.content();
-    if (looksLikeWorkflow(body)) {
+    const fm = ctx.frontmatter();
+    // Recognition is frontmatter `type: workflow` or residence under `workflows/`
+    // (workflow-format-unification, spec §2.5) — no content sniffing. The
+    // directory rule is `classifyByDirectory`/`classifyByParentDirHint`'s job;
+    // this only catches a workflow living OUTSIDE `workflows/` that still
+    // declares its type explicitly.
+    if (fm && fm.type === "workflow") {
         return { type: "workflow", specificity: 19 };
     }
-    const fm = ctx.frontmatter();
     if (fm) {
-        if ("toolPolicy" in fm || "tools" in fm) {
+        // `tools` is the one authoring key for an agent's tool grant. Recognition
+        // covers only the key the renderer honors.
+        if ("tools" in fm) {
             return { type: "agent", specificity: 20 };
         }
         if ("agent" in fm) {
@@ -182,35 +205,6 @@ function classifyBySmartMd(ctx) {
     }
     return { type: "knowledge", specificity: 5 };
 }
-/** YAML workflow *programs* (redesign addendum, R1): `.yaml`/`.yml` files. */
-const WORKFLOW_PROGRAM_EXTENSIONS = new Set([".yaml", ".yml"]);
-/**
- * Classify YAML workflow programs. Two claims, mirroring the markdown rules:
- *
- *   - any `.yaml`/`.yml` under a `workflows/` dir (the directory rule —
- *     specificity 15 when `workflows` is the immediate parent, 10 for a
- *     deeper ancestor, same ladder as `matchDirectoryHint`);
- *   - anywhere else, a content probe via `looksLikeWorkflowProgram`
- *     (`version: 1` + `steps:` at column 0) at specificity 19, the same
- *     level as `classifyBySmartMd`'s `looksLikeWorkflow` claim.
- *
- * The fact does NOT go through `toMatchResult` — the workflow TYPE maps to
- * the markdown renderer by default, so this classifier names the
- * `workflow-program-yaml` renderer on its result directly.
- */
-function classifyByWorkflowProgram(ctx) {
-    if (!WORKFLOW_PROGRAM_EXTENSIONS.has(ctx.ext))
-        return null;
-    if (isTypedDirDocFile(ctx.fileName))
-        return null;
-    if (ctx.parentDir === "workflows")
-        return { type: "workflow", specificity: 15 };
-    if (ctx.ancestorDirs.includes("workflows"))
-        return { type: "workflow", specificity: 10 };
-    if (looksLikeWorkflowProgram(ctx.content()))
-        return { type: "workflow", specificity: 19 };
-    return null;
-}
 // ---------------------------------------------------------------------------
 // Adapter: MatchFact → MatchResult
 // ---------------------------------------------------------------------------
@@ -246,14 +240,7 @@ export function parentDirHintMatcher(ctx) {
 export function smartMdMatcher(ctx) {
     return toMatchResult(ctx, classifyBySmartMd);
 }
-export function workflowProgramMatcher(ctx) {
-    const fact = classifyByWorkflowProgram(ctx);
-    if (!fact)
-        return null;
-    // Named directly (not via rendererNameFor) — see classifyByWorkflowProgram.
-    return { type: fact.type, specificity: fact.specificity, renderer: WORKFLOW_PROGRAM_RENDERER_NAME };
-}
-// The five matcher functions above are consumed directly by the akm adapter's
+// The four matcher functions above are consumed directly by the akm adapter's
 // synchronous `recognizeMatch()` (`core/adapter/adapters/akm-adapter.ts`, which
 // holds the same registration-order array for tie-breaking). The chunk-3 cutover
 // removed the file-context matcher registry, so there is no `registerBuiltinMatchers`

package/dist/indexer/walk/path-resolver.js

@@ -10,11 +10,16 @@ import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { lookup } from "../indexer.js";
 import { resolveSourceEntries } from "../search/search-source.js";
 function normalizeRef(ref) {
-    // Stored/resolved refs may still be in the legacy spelling → dual parser.
+    // String inputs use the current `[bundle//]conceptId` grammar.
     return typeof ref === "string" ? parseRefInput(ref) : ref;
 }
 function buildDiskCandidates(sourcePath, ref, preserveDirectNameFallback) {
-    const typeDir = path.join(sourcePath, stashDirFor(ref.type) ?? `${ref.type}s`);
+    const placementStashDir = stashDirFor(ref.type);
+    // Opaque adapter conceptIds are index-resolved. Core cannot infer their
+    // adapter-owned serialization or path extension before indexing.
+    if (placementStashDir === undefined)
+        return [];
+    const typeDir = path.join(sourcePath, placementStashDir);
     const candidates = [
         assetPathForName(ref.type, typeDir, ref.name),
         path.join(sourcePath, ref.type, `${ref.name}.md`),

package/dist/indexer/walk/walker.js

@@ -13,7 +13,8 @@ import path from "node:path";
 import { isRelevantAssetFile } from "../../core/asset/asset-placement.js";
 import { spawnSync } from "../../runtime.js";
 import { buildFileContext } from "./file-context.js";
-const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
+const ALWAYS_SKIP_DIRS = new Set([".git"]);
+const AKM_SKIP_DIRS = new Set(["node_modules", "bin", ".cache"]);
 /**
  * Walk a type root directory and return files grouped by their parent directory.
  *
@@ -62,21 +63,24 @@ export function walkStash(typeRoot, assetType) {
  * Otherwise falls back to a manual walk that skips .git, node_modules, bin,
  * .cache, dot-directories, and the legacy metadata sidecar.
  */
-export function walkStashFlat(stashRoot) {
+export function walkStashFlat(stashRoot, options = {}) {
+    return walkStashFlatWithStatus(stashRoot, options).files;
+}
+export function walkStashFlatWithStatus(stashRoot, options = {}) {
     if (!fs.existsSync(stashRoot))
-        return [];
+        return { files: [], complete: false };
     // Try git-based walk first (respects .gitignore)
-    const gitResult = walkStashGit(stashRoot);
+    const gitResult = walkStashGit(stashRoot, options);
     if (gitResult)
         return gitResult;
     // Fallback: manual walk
-    return walkStashManual(stashRoot);
+    return walkStashManual(stashRoot, options);
 }
 /**
  * Walk using `git ls-files` to respect .gitignore.
  * Returns null if the directory is not a git repo or git fails.
  */
-function walkStashGit(stashRoot) {
+function walkStashGit(stashRoot, options) {
     // Quick check: is this a git repo? Look for .git in this dir or parents.
     if (!isInsideGitRepo(stashRoot))
         return null;
@@ -87,6 +91,15 @@ function walkStashGit(stashRoot) {
     // result.success is false if the process exited non-zero OR git was not found
     if (!result.success)
         return null;
+    // `--cached` includes tracked files deleted from the worktree. They are not
+    // scan failures and must not make an otherwise complete snapshot look stale.
+    const deletedResult = spawnSync(["git", "ls-files", "--deleted", "-z", "--", "."], { cwd: stashRoot });
+    if (!deletedResult.success)
+        return null;
+    const deletedStdout = Buffer.isBuffer(deletedResult.stdout)
+        ? deletedResult.stdout.toString("utf8")
+        : String(deletedResult.stdout ?? "");
+    const deletedFiles = new Set(deletedStdout.split("\0").filter(Boolean));
     // Data-hygiene filename skips: the legacy metadata sidecar (never indexed as
     // content — Chunk-8 folds it into the bundle format) plus git dot-files.
     const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
@@ -94,16 +107,19 @@ function walkStashGit(stashRoot) {
     const files = stdout
         .split("\0")
         .filter((f) => f.length > 0)
+        .filter((f) => !deletedFiles.has(f))
         .filter((f) => !f.startsWith("..") && !path.isAbsolute(f))
         .filter((f) => {
         const dirParts = path
             .dirname(f)
             .split(/[\\/]+/)
             .filter(Boolean);
-        return !dirParts.some((part) => SKIP_DIRS.has(part) || part.startsWith("."));
+        return !dirParts.some((part) => ALWAYS_SKIP_DIRS.has(part) ||
+            (!options.includeAllDirectories && (AKM_SKIP_DIRS.has(part) || part.startsWith("."))));
     })
         .filter((f) => !SKIP_FILES.has(path.basename(f)));
     const results = [];
+    let complete = true;
     for (const relFile of files) {
         const absPath = path.join(stashRoot, relFile);
         try {
@@ -113,9 +129,10 @@ function walkStashGit(stashRoot) {
         }
         catch {
             // File may have been deleted since git ls-files ran
+            complete = false;
         }
     }
-    return results;
+    return { files: results, complete };
 }
 /**
  * Check if a directory is inside a git repository by walking up to find .git.
@@ -176,14 +193,22 @@ export function* walkMarkdownFiles(root) {
     }
 }
 /** Manual walk for non-git directories. */
-function walkStashManual(stashRoot) {
+function walkStashManual(stashRoot, options) {
     const results = [];
+    let complete = true;
     const stack = [stashRoot];
     while (stack.length > 0) {
         const current = stack.pop();
         if (!current)
             continue;
-        const entries = fs.readdirSync(current, { withFileTypes: true });
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            complete = false;
+            continue;
+        }
         for (const entry of entries) {
             if (entry.name === ".stash.json")
                 continue;
@@ -193,7 +218,8 @@ function walkStashManual(stashRoot) {
                 continue;
             }
             if (entry.isDirectory()) {
-                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                if (ALWAYS_SKIP_DIRS.has(entry.name) ||
+                    (!options.includeAllDirectories && (AKM_SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))))
                     continue;
                 stack.push(fullPath);
             }
@@ -202,5 +228,5 @@ function walkStashManual(stashRoot) {
             }
         }
     }
-    return results;
+    return { files: results, complete };
 }

package/dist/integrations/agent/builders.js

@@ -14,12 +14,6 @@
  */
 import { ConfigError } from "../../core/errors.js";
 import { HARNESS_REGISTRY } from "../harnesses/index.js";
-export { assertNotFlag, normalizeTools } from "./builder-shared.js";
-// ── Platform builders ─────────────────────────────────────────────────────────
-// The OpenCode builder was migrated to its harness directory in #564
-// (`harnesses/opencode/agent-builder.ts`) and the Claude Code builder in #563
-// (`harnesses/claude/agent-builder.ts`). Both are imported back into
-// BUILTIN_BUILDERS below so platform routing is unchanged.
 // ── Registry ──────────────────────────────────────────────────────────────────
 /**
  * DERIVED from `HARNESS_REGISTRY` (P0.5 registry-drift fix): each harness that

package/dist/integrations/agent/config.js

@@ -1,7 +1,7 @@
 // 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/.
-/** Default hard timeout for an agent CLI when neither engine nor call overrides it. */
-export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
+/** Default agent CLI timeout; null means agents run until they finish. */
+export const DEFAULT_AGENT_TIMEOUT_MS = null;
 /** Default hard timeout for direct LLM calls when no engine/use override exists. */
 export const DEFAULT_LLM_TIMEOUT_MS = 600_000;

package/dist/integrations/agent/detect.js

@@ -15,26 +15,34 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getBuiltinAgentProfile, listBuiltinAgentProfiles } from "./profiles.js";
+import { getBuiltinAgentProfile, listBuiltinAgentProfiles, OPENCODE_SDK_SERVER_BIN, } from "./profiles.js";
 /**
  * Default PATH lookup. Walks `process.env.PATH` and returns the first
  * existing executable file. Returns `undefined` when the bin is not on
  * PATH or the env is empty.
  *
- * `process.env.PATH` is split on the platform-correct delimiter; on
- * Windows the binary may have an executable extension, but for v1 we
- * keep this Unix-flavoured (Bun's primary target) and look for an exact
- * match.
+ * `process.env.PATH` is split on the platform-correct delimiter. On Windows
+ * agent CLIs install as extension-bearing shims (`claude.cmd`, `q.exe`), so
+ * each PATH entry is probed for the bare name AND for `<bin><ext>` over
+ * PATHEXT — an exact-match-only probe reports every agent CLI as missing
+ * there, which silently hides the "installed CLI agent" option during setup.
  */
 export function defaultWhich(bin, envSource = process.env) {
+    // Computed once per call — not per PATH entry — since it never varies.
+    const suffixes = executableSuffixes(envSource);
     if (!bin || bin.includes("/") || bin.includes("\\")) {
         // Absolute / relative paths: caller already specified location.
-        try {
-            return fs.statSync(bin).isFile() ? bin : undefined;
-        }
-        catch {
-            return undefined;
+        for (const suffix of suffixes) {
+            const candidate = bin + suffix;
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                /* try the next extension */
+            }
         }
+        return undefined;
     }
     const pathVar = envSource.PATH ?? envSource.Path ?? envSource.path ?? "";
     if (!pathVar)
@@ -43,18 +51,40 @@ export function defaultWhich(bin, envSource = process.env) {
     for (const dir of pathVar.split(sep)) {
         if (!dir)
             continue;
-        const candidate = path.join(dir, bin);
-        try {
-            const st = fs.statSync(candidate);
-            if (st.isFile())
-                return candidate;
-        }
-        catch {
-            /* keep walking */
+        const base = path.join(dir, bin);
+        for (const suffix of suffixes) {
+            const candidate = base + suffix;
+            try {
+                const st = fs.statSync(candidate);
+                if (st.isFile())
+                    return candidate;
+            }
+            catch {
+                /* keep walking */
+            }
         }
     }
     return undefined;
 }
+/** Windows PATHEXT default, used when the env carries no explicit list. */
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/**
+ * Executable suffixes to try for each candidate path, bare name (`""`) first
+ * so POSIX resolution is byte-for-byte unchanged. Extensions are appended only
+ * on win32 or when the env supplies PATHEXT (which is also the seam tests use
+ * to cover Windows resolution from a POSIX runner).
+ */
+function executableSuffixes(envSource) {
+    const pathext = envSource.PATHEXT ?? envSource.Pathext ?? envSource.pathext;
+    if (process.platform !== "win32" && !pathext)
+        return [""];
+    const exts = (pathext ?? DEFAULT_PATHEXT)
+        .split(";")
+        .map((ext) => ext.trim())
+        .filter(Boolean)
+        .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
+    return ["", ...exts];
+}
 let detectOverrides;
 /** TEST-ONLY. Swap the detection implementations; pass undefined to restore. */
 export function _setAgentDetectForTests(fakes) {
@@ -79,7 +109,7 @@ export function detectAgentCliProfiles(agent, whichFn = defaultWhich) {
         profilesByName.set(name, {
             name,
             platform: engine.platform,
-            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? "opencode" : engine.platform),
+            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? OPENCODE_SDK_SERVER_BIN : engine.platform),
             args: engine.args ?? builtin?.args ?? [],
             stdio: "captured",
             envPassthrough: builtin?.envPassthrough ?? [],

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

@@ -0,0 +1,76 @@
+// 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/.
+import { defaultWhich } from "./detect.js";
+import { OPENCODE_SDK_SERVER_BIN } from "./profiles.js";
+/**
+ * Engine name used for the synthesized entry. Matches the platform id so it
+ * reads correctly in `akm workflow status`, frozen plans, and error messages.
+ * A user-configured engine of the same name is preferred over synthesizing.
+ */
+export const FALLBACK_ENGINE_NAME = "opencode-sdk";
+/** Announcement text, surfaced once per run/dispatch. */
+export const FALLBACK_ANNOUNCEMENT = `No engine is configured; falling back to \`${FALLBACK_ENGINE_NAME}\` via the ` +
+    `\`${OPENCODE_SDK_SERVER_BIN}\` binary on PATH — provider, model, and auth come ` +
+    "from opencode's own configuration. " +
+    "Run `akm setup`, or set `defaults.engine`, to choose explicitly.";
+/**
+ * Failure suffix for every surface that needs an engine and found none.
+ * Owned HERE, beside the probe whose outcome it describes: the probe follows a
+ * configured `bin` when one is pinned, so a consumer restating "not on PATH"
+ * would misdescribe a missing absolute path.
+ */
+export const NO_ENGINE_MESSAGE_SUFFIX = `has no selected engine, and no usable \`${OPENCODE_SDK_SERVER_BIN}\` binary was found to fall back to.`;
+/**
+ * Guidance used when the fallback itself is unavailable.
+ *
+ * The opencode route names a BINARY install, not `npm i @opencode-ai/sdk`:
+ * that package is an HTTP client with no dependencies and cannot serve
+ * anything on its own (see the module doc).
+ */
+export const NO_ENGINE_REMEDY = "Run `akm setup` to detect an installed agent, or set one explicitly: " +
+    '`akm config set engines.claude \'{"kind":"agent","platform":"claude"}\'` ' +
+    "then `akm config set defaults.engine claude`. " +
+    `Installing the \`${OPENCODE_SDK_SERVER_BIN}\` binary also works ` +
+    "(`npm i -g opencode-ai`) — akm falls back to it automatically.";
+/**
+ * Return a config whose `defaults.engine` resolves, applying the implicit
+ * `opencode-sdk` fallback when it does not and an opencode binary is present.
+ *
+ * Pure with respect to the input: never mutates `config`. Returns the input
+ * object identity unchanged when no fallback is needed, so callers can cheaply
+ * detect the common case.
+ */
+export function withEngineFallback(config, whichFn = defaultWhich) {
+    if (config.defaults?.engine)
+        return { config };
+    // An operator-configured engine of this name wins over a synthesized one —
+    // theirs may carry a model, an llmEngine fallback, or a pinned bin. Probe
+    // THAT bin rather than the bare command: a configured absolute path outside
+    // PATH is still a usable engine, and reporting it as missing would contradict
+    // the operator-configured-wins rule.
+    const existing = config.engines?.[FALLBACK_ENGINE_NAME];
+    if (!whichFn(existing?.bin ?? OPENCODE_SDK_SERVER_BIN))
+        return { config };
+    const engines = existing
+        ? config.engines
+        : { ...(config.engines ?? {}), [FALLBACK_ENGINE_NAME]: { kind: "agent", platform: "opencode-sdk" } };
+    return {
+        config: {
+            ...config,
+            engines,
+            defaults: { ...(config.defaults ?? {}), engine: FALLBACK_ENGINE_NAME },
+        },
+        fallbackEngineName: FALLBACK_ENGINE_NAME,
+    };
+}
+/**
+ * The announcement, but only when the fallback candidate is the engine that
+ * actually won selection. Returns `undefined` otherwise, so an explicitly
+ * selected engine never triggers a claim that opencode supplied the model.
+ */
+export function fallbackAnnouncement(fallbackEngineName, selectedEngineName) {
+    if (!fallbackEngineName || selectedEngineName !== fallbackEngineName)
+        return undefined;
+    return FALLBACK_ANNOUNCEMENT;
+}

package/dist/integrations/agent/profiles.js

@@ -91,6 +91,20 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
+/**
+ * Binary the `opencode-sdk` harness needs on PATH.
+ *
+ * The embedded SDK is not self-contained, and that is the SDK's own design
+ * rather than a consequence of how akm drives it: `@opencode-ai/sdk` ships
+ * with `"dependencies": {}` and its `createOpencodeServer` is itself a
+ * `spawn("opencode", ["serve", ...])`. akm's runner spawns the same binary
+ * directly and talks HTTP to it (see `harnesses/opencode-sdk/sdk-runner.ts`),
+ * so the `opencode` binary gates the SDK path exactly as it gates the CLI
+ * path — a host with the npm package but no binary can dispatch neither.
+ * `opencode-sdk` deliberately has no {@link BUILTINS} entry — it dispatches
+ * without argv construction — so this is the one place that pairing lives.
+ */
+export const OPENCODE_SDK_SERVER_BIN = "opencode";
 /** Names of the canonical built-in harness descriptors. Stable, sorted. */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
 /** Returns the built-in descriptor for a canonical harness id. */

package/dist/integrations/agent/prompts.js

@@ -12,11 +12,11 @@
  * `src/integrations/agent/` rather than `src/llm/` is deliberate: these are
  * shell-out prompts targeting an agent CLI, not in-tree LLM API calls.
  *
- * The legacy stdout output an agent must produce is a *strict* JSON object:
+ * The stdout output an agent must produce is a strict JSON object:
  *
  * ```json
  * {
- *   "ref": "lesson:my-lesson",
+ *   "ref": "lessons/my-lesson",
  *   "content": "---\ndescription: ...\nwhen_to_use: ...\n---\n\nbody",
  *   "frontmatter": { "description": "...", "when_to_use": "..." }
  * }
@@ -29,6 +29,7 @@ import reflectLlmFramedContract from "../../assets/prompts/reflect-llm-framed-co
 import reflectLlmSchemaContract from "../../assets/prompts/reflect-llm-schema-contract.md" with { type: "text" };
 import reflectOutputRepair from "../../assets/prompts/reflect-output-repair.md" with { type: "text" };
 import { placementTypes } from "../../core/asset/asset-placement.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType, DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, requiresDescription, } from "../../core/authoring-rules.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
@@ -45,7 +46,7 @@ const TYPE_HINTS = {
     memory: "memory assets are short factual notes the user wants persisted across sessions. Frontmatter usually includes `description`.",
     workflow: "workflow assets are markdown describing a multi-step process. Include `# <Title>` and ordered `## Step N` sections.",
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
-    env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>`; prefer `--clean` in agent contexts so the child starts from a minimal inherited environment. AKM itself does not print values, but the child command can print its environment, so do not run `env`, `printenv`, shell tracing, or similar diagnostics when secrets are in scope. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
+    env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env/<name> -- <cmd>`; prefer `--clean` in agent contexts so the child starts from a minimal inherited environment. AKM itself does not print values, but the child command can print its environment, so do not run `env`, `printenv`, shell tracing, or similar diagnostics when secrets are in scope. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
     fact: "fact assets are durable stash-level facts (personal/team/project details, coding conventions, stash-meta). Frontmatter SHOULD include `description` and a `category` (personal|team|project|convention|meta); set `pinned: true` only for the small always-injected core. Keep each fact short, high-signal, and self-contained — it is durable context, not an episodic note.",
 };
@@ -63,7 +64,10 @@ function knownTypeList() {
  */
 const RESPONSE_CONTRACT_JSON = [
     "Respond ONLY with a single JSON object. No prose before or after.",
-    'Shape: {"ref": "<type>:<name>", "content": "<full file contents>", "frontmatter": {...}, "confidence": <number 0..1>}',
+    // Slash conceptId, not the retired `<type>:<name>` colon grammar (Q-02/Q-08).
+    // This contract is the schema an agent copies from, so a stale spelling here
+    // teaches every proposal to use a ref form the CLI now rejects outright.
+    'Shape: {"ref": "<type>/<name>", "content": "<full file contents>", "frontmatter": {...}, "confidence": <number 0..1>}',
     "`content` is the full file body that will be written if accepted.",
     "`frontmatter` is optional — include it if `content` starts with `---` so reviewers can sanity-check the keys.",
     "`confidence` is REQUIRED. Self-rate this proposal on [0, 1] by how certain you are it materially improves the source asset. Calibrate honestly:",
@@ -174,7 +178,7 @@ export function buildReflectPrompt(input) {
         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 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}`);
@@ -210,7 +214,7 @@ export function buildReflectPrompt(input) {
         sections.push(input.standardsContext.trim());
     }
     {
-        const resolvedType = input.type ?? (input.ref?.includes(":") ? input.ref.split(":")[0] : "");
+        const resolvedType = input.type ?? (input.ref ? parseRefInput(input.ref).type : "");
         const authoringRules = resolvedType ? authoringRulesForType(resolvedType) : "";
         if (authoringRules) {
             sections.push(authoringRules);
@@ -268,7 +272,7 @@ export function buildReflectPrompt(input) {
         }
         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.");
+        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.rejectedProposals && input.rejectedProposals.length > 0) {
         const lines = ["## Previously Rejected Proposals"];
@@ -423,7 +427,7 @@ export function buildSchemaRepairPrompt(input) {
  * can map to {@link AgentFailureReason} `parse_error`.
  *
  * Resilient to two common local-LLM failure modes:
- *  1. `<think>…</think>` blocks emitted before the JSON (stripped by `stripJsonFences`).
+ *  1. `<think>…</think>` blocks emitted before the JSON (stripped before parsing).
  *  2. Prose preamble / postamble around the JSON object (handled by `extractEmbeddedJson`).
  */
 export function parseAgentProposalPayload(stdout) {

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

@@ -76,8 +76,10 @@ export function collectDispatchSensitiveValues(spec, opts, envSource = opts.envS
                 add(value);
         }
     }
-    for (const value of Object.values(opts.env ?? {}))
-        add(value);
+    for (const [name, value] of Object.entries(opts.env ?? {})) {
+        if (!isEnvPassthroughValueSafeToExpose(name, value))
+            add(value);
+    }
     return collectSensitiveValues(values);
 }
 function redactResult(result, sensitiveValues) {

package/dist/integrations/agent/runner.js

@@ -97,4 +97,3 @@ export function resolveImproveProcessRunner(strategy, processName, config) {
         timeoutMs: resolved.timeoutMs,
     };
 }
-export { isProcessEnabled } from "../../llm/feature-gate.js";

package/dist/integrations/agent/spawn.js

@@ -21,7 +21,6 @@ import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { runManagedSubprocess, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-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.
@@ -144,7 +143,7 @@ function streamFailureMessage(profileName, stdout, stderr) {
 export async function runAgent(profile, prompt, options = {}) {
     const stdioMode = options.stdio ?? profile.stdio;
     // null = explicitly disabled (no kill timer). undefined = runtime default.
-    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_AGENT_TIMEOUT_MS;
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
@@ -160,7 +159,7 @@ export async function runAgent(profile, prompt, options = {}) {
         }
     };
     // Build argv via the platform-specific builder when dispatch params are
-    // provided; fall back to the legacy positional-prompt form otherwise.
+    // provided; otherwise use the direct positional-prompt form.
     let builtArgv;
     let builtEnv;
     if (options.dispatch !== undefined) {
@@ -170,10 +169,10 @@ export async function runAgent(profile, prompt, options = {}) {
         builtEnv = built.env;
     }
     else {
-        const legacyArgs = [...profile.args, ...(options.args ?? [])];
+        const positionalArgs = [...profile.args, ...(options.args ?? [])];
         if (prompt !== undefined)
-            legacyArgs.push(prompt);
-        builtArgv = [profile.bin, ...legacyArgs];
+            positionalArgs.push(prompt);
+        builtArgv = [profile.bin, ...positionalArgs];
     }
     // Extra args (e.g. forwarded CLI positionals) are appended after the builder output.
     const finalArgv = [...builtArgv, ...(options.dispatch ? (options.args ?? []) : [])];