akm-cli 0.10.261016-beta → 0.10.261018-beta

package/dist/indexer/passes/metadata.js

@@ -136,7 +136,7 @@ export function validateStashEntry(entry) {
     const sources = normalizeNonEmptyStringList(e.sources);
     if (sources)
         result.sources = sources;
-    // SPEC-6: `category` must survive the projection. Non-string values are
+    // `category` must survive the projection. Non-string values are
     // dropped, not coerced.
     if (typeof e.category === "string" && e.category.trim().length > 0) {
         result.category = e.category.trim();
@@ -346,7 +346,7 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const quality = asNonEmptyString(fmData.quality);
     if (quality)
         entry.quality = normalizeQuality(quality);
-    // SPEC-6 capture step: the `category:` frontmatter key (e.g. `convention`,
+    // Capture the `category:` frontmatter key (e.g. `convention`,
     // `meta` on facts) must land on the indexed entry so category-keyed
     // policies can see it. Trimmed; blank/non-string values are ignored.
     const category = asNonEmptyString(fmData.category);
@@ -384,13 +384,13 @@ export function applyCuratedFrontmatter(entry, fmData) {
         entry.evidenceSources = evidenceSources;
     if (typeof fmData.evidence === "string" && fmData.evidence.trim().length > 0)
         entry.evidence = fmData.evidence;
-    // Phase 5A / Advantage D5: capture parent ref for derived memories.
+    // Capture the parent ref for derived memories.
     // Memory-inference writes `source: "memories/<parent>"` and `inferred: true`
     // (and a derived child name suffix `.derived`). We mirror that source ref into
     // `entry.derivedFrom` so the indexer can populate the dedicated `derived_from`
-    // column. Group-C item 2: the column is stored in the 0.9.0 `memories/<name>`
-    // conceptId grammar — moving in lockstep with the `getDerivedForParent` lookup
-    // key (search-hit-enrichers) so producer + consumer speak one grammar.
+    // column. The column is stored as the `memories/<name>` conceptId, matching
+    // the `getDerivedForParent` lookup key (search-hit-enrichers) so producer and
+    // consumer speak one grammar.
     // Non-derived entries leave this field unset.
     if (entry.type === "memory") {
         const isDerivedByName = entry.name.toLowerCase().endsWith(".derived");
@@ -473,7 +473,7 @@ function isWikiRole(value) {
 /**
  * Parse one `verified:` family value into the `IndexDocument.provenance` shape.
  * Accepts OKF v0.2's list form and its documented single-mapping shorthand
- * ("consumers MUST treat a bare mapping as a one-element list", per OKF v0.2).
+ * ("consumers MUST treat a bare mapping as a one-element list", OKF v0.2 §5.2).
  * Tolerant: an entry without a usable `by` is dropped individually.
  */
 function parseVerifiedFamily(value) {
@@ -491,9 +491,9 @@ function parseVerifiedFamily(value) {
 }
 /**
  * Extract the OKF v0.2 provenance families that `promoteProposal` stamps onto
- * accepted AKM-native proposals (D2, #730), and apply them to the entry.
+ * accepted AKM-native proposals (#730), and apply them to the entry.
  *
- * The on-disk shape is deliberately **hybrid** (owner decision, #730 review):
+ * The on-disk shape is deliberately **hybrid** (#730 review):
  * `generated:` and `verified:` are stamped BARE at the top level, exactly as
  * OKF v0.2 spells them, because neither has any pre-existing AKM consumer — so
  * a third-party OKF v0.2 reader treating an AKM stash as an OKF bundle sees
@@ -505,8 +505,8 @@ function parseVerifiedFamily(value) {
  * non-strings).
  *
  * The nested `provenance.generatedBy` / `.generatedAt` / `.verified` spellings
- * are still read as a fallback so assets stamped by an earlier build of this
- * branch keep resolving. Tolerant throughout: any malformed sub-field is
+ * are still read as a fallback so assets stamped by an earlier build keep
+ * resolving. Tolerant throughout: any malformed sub-field is
  * dropped individually rather than rejecting the whole block.
  */
 export function applyProvenanceFrontmatter(entry, fmData) {
@@ -545,8 +545,8 @@ export function applyProvenanceFrontmatter(entry, fmData) {
         entry.provenance = result;
 }
 // AKM-stash indexing policy (env/vaults/secrets sensitive-marker + wiki-infra
-// exclusions) moved to the `akm` adapter's `recognize` as path/stat-based
-// abstention (owner ruling 2026-07-21 — adapter-owned filtering). See
+// exclusions) lives in the `akm` adapter's `recognize` as path/stat-based
+// abstention. See
 // `akmStashAbstains` in `src/core/adapter/adapters/akm-adapter.ts`.
 /**
  * Extract `@param` JSDoc tags from a script file's leading comment block.
@@ -764,11 +764,9 @@ function mergeAliases(existing, generated) {
 /**
  * Maximum native Markdown prose carried by the low-weight `content` field.
  *
- * Raised far past any real authored document:
- * this used to sit at 16_384 chars, tight enough that ordinary long-form
- * skills/knowledge docs lost their tail from both FTS and the embedding
- * input with no visible signal (the cut was reported via `warnVerbose`,
- * silent unless `AKM_VERBOSE` was set). The remaining bound exists only to
+ * Set far past any real authored document, so ordinary long-form
+ * skills/knowledge docs never lose their tail from FTS or the embedding
+ * input. The bound exists only to
  * stop a truly pathological single file (a committed data dump, a decompressed
  * log) from ballooning index size — not to shave real content — so a caller
  * that hits it is always told, unconditionally.
@@ -873,6 +871,58 @@ function isMarkdownFenceClosing(line, fence) {
         return false;
     return /^[\t ]*$/.test(line.slice(cursor));
 }
+/**
+ * Version of what {@link projectMarkdownContent} indexes. It is part of every
+ * directory's index fingerprint, so bumping it makes the next `akm index`
+ * re-project every directory once instead of keeping the old text for
+ * unchanged files. 2: identifiers from fenced code (akm#1260).
+ */
+export const CONTENT_PROJECTION_VERSION = 2;
+/** At or above this length a token with a digit reads as a key or hash, not a name. */
+const TOKEN_LIKE_MIN_LENGTH = 20;
+/**
+ * The searchable identifiers of one line of fenced code, without its literal
+ * values (akm#1260). Fenced code holds the names agents look for (functions,
+ * classes, CLI flags, config keys, environment variable names, paths) and
+ * also example secrets, so it keeps names and drops values:
+ *
+ * - a quoted string survives only as a key (`"name":`) or an absolute path;
+ *   every other quoted literal is dropped;
+ * - the value of an assignment (`KEY=value`, `key: value`, `"key": value`,
+ *   `Authorization: Bearer token`) is dropped unless it is a dotted code
+ *   reference (`process.env.CI`); the name stays;
+ * - long token-like strings with digits (keys, hashes) are dropped, base64
+ *   included: its `/`, `+` and `=` do not cut it into short kept pieces;
+ * - camelCase, snake_case, dotted and dashed names also add their parts.
+ *
+ * Numbers, punctuation and operators never reach the result.
+ */
+export function fencedCodeIdentifiers(line) {
+    const cleaned = line
+        .replace(/(["'`])((?:\\.|(?!\1).)*)\1(\s*:)?/g, (match, _quote, body, colon, offset) => {
+        // Keep a key's colon when an unquoted value follows, so the assignment rule below drops that value.
+        if (colon)
+            return /^\s*["'`]/.test(line.slice(offset + match.length)) ? ` ${body} ` : ` ${body}: `;
+        return /^\/[\w./-]+$/.test(body) ? ` ${body} ` : " ";
+    })
+        .replace(/([A-Za-z_][A-Za-z0-9_.-]*\s*[:=]\s*)((?:[Bb]earer|[Bb]asic|[Tt]oken|[Dd]igest)\s+\S+|\S+)/g, (_match, name, value) => /^[!(]*[A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)+[()\]}]*[,;]?$/.test(value) ? `${name} ${value}` : name)
+        // Base64 is one token: its `/`, `+` and `=` would otherwise cut a key body into short pieces that are kept.
+        .replace(/(?<![\w.-])[A-Za-z0-9+/=]{20,}(?![\w.-])/g, (run) => /[a-z]/.test(run) && /[A-Z]/.test(run) && /\d/.test(run) ? " " : run);
+    const words = [];
+    for (let token of cleaned.match(/--?[A-Za-z][A-Za-z0-9-]*|[A-Za-z_][A-Za-z0-9_.-]*/g) ?? []) {
+        token = token.replace(/[.-]+$/, "");
+        const bare = token.replace(/^-+/, "");
+        if (bare.length < 2)
+            continue;
+        if (bare.length >= TOKEN_LIKE_MIN_LENGTH && /\d/.test(bare))
+            continue;
+        words.push(token);
+        const parts = bare.split(/[_.-]|(?<=[a-z0-9])(?=[A-Z])/).filter((part) => part.length > 1);
+        if (parts.length > 1)
+            words.push(...parts);
+    }
+    return words.join(" ");
+}
 function stripMarkdownHtmlComments(line, state) {
     let cursor = 0;
     let visible = "";
@@ -1048,17 +1098,23 @@ function stripMarkdownLinkDestinations(text, nesting = 0) {
 }
 /**
  * Derive the one low-weight search projection for an AKM-native Markdown body.
- * Frontmatter is removed by the caller. This projection drops comments,
- * fenced code, raw link targets, and structural punctuation while retaining
- * prose, headings, link labels, and inline identifiers. It never receives
- * secret/env/session bytes; that policy is enforced at the adapter metadata
- * boundary below.
+ * Frontmatter is removed by the caller. This projection drops comments, raw
+ * link targets, and structural punctuation while retaining prose, headings,
+ * link labels, and inline identifiers. From fenced code it keeps only the
+ * identifiers ({@link fencedCodeIdentifiers}): names, flags, keys and paths,
+ * never literal values (akm#1260). It never receives secret/env/session bytes;
+ * that policy is enforced at the adapter metadata boundary below.
+ *
+ * Changing what this returns changes the indexed text of every Markdown entry,
+ * so bump {@link CONTENT_PROJECTION_VERSION} with it: the indexer re-projects
+ * every directory once on the next `akm index`.
  */
 export function projectMarkdownContent(body, truncationInfo) {
     const lines = body.split(/\r?\n/);
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
     const projected = [];
+    const fenced = [];
     forEachVisibleMarkdownLine(lines, start, (_index, visible) => {
         let trimmed = visible.trim();
         if (!trimmed || /^(-{3,}|\*{3,}|_{3,}|=+)$/.test(trimmed))
@@ -1077,8 +1133,13 @@ export function projectMarkdownContent(body, truncationInfo) {
         trimmed = trimmed.replace(/\s+/g, " ").trim();
         if (trimmed)
             projected.push(trimmed);
+    }, (_index, fencedLine) => {
+        const identifiers = fencedCodeIdentifiers(fencedLine);
+        if (identifiers)
+            fenced.push(identifiers);
     });
-    const text = projected.join(" ").replace(/\s+/g, " ").trim();
+    // Fenced identifiers follow the prose, so a head-truncated embedding input keeps the prose first.
+    const text = [...projected, ...fenced].join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
     if (truncationInfo)
@@ -1088,8 +1149,10 @@ export function projectMarkdownContent(body, truncationInfo) {
 /**
  * Visit each line from `start` that lies outside fenced code, with HTML
  * comments removed (`visible`); fence lines themselves are never visited.
+ * `visitFenced`, when given, receives each raw line inside a fence (not the
+ * opening or closing fence line), from the same fence state.
  */
-function forEachVisibleMarkdownLine(lines, start, visit) {
+function forEachVisibleMarkdownLine(lines, start, visit, visitFenced) {
     let fence;
     const htmlComment = { inComment: false };
     for (let index = start; index < lines.length; index += 1) {
@@ -1097,6 +1160,8 @@ function forEachVisibleMarkdownLine(lines, start, visit) {
         if (fence) {
             if (isMarkdownFenceClosing(rawLine, fence))
                 fence = undefined;
+            else
+                visitFenced?.(index, rawLine);
             continue;
         }
         // A leading fence owns the whole line, including any info string that
@@ -1174,13 +1239,12 @@ export function projectMarkdownFragmentContent(raw) {
 /**
  * Priorities 1-2 of the metadata pipeline — package.json (P1), `.md`
  * frontmatter (P2), and script `@param`/comment metadata (P2b) — everything
- * that runs BEFORE the renderer-contributor step (P3). Extracted (Chunk 5 M-b)
- * so the `akm` adapter's synchronous `recognize` shares this exact assembly
- * with the live index-drain path; the two differ ONLY in how they obtain the
+ * that runs BEFORE the renderer-contributor step (P3). Shared by the `akm`
+ * adapter's synchronous `recognize` and the live index-drain path; the two
+ * differ ONLY in how they obtain the
  * P3 renderer metadata (the adapter uses the synchronous
  * `foldRecognizedMetadata`), guaranteeing P1/P2/P4 parity by construction.
- * Behavior-preserving: this is a verbatim lift of the former inline P1/P2/P2b
- * block. Mutates `entry` in place.
+ * Mutates `entry` in place.
  */
 export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
     const ext = path.extname(file).toLowerCase();
@@ -1207,7 +1271,7 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
             entry.parameters = fmParams;
         // Pass wiki-pattern frontmatter through onto the entry
         applyWikiFrontmatter(entry, parsed.data);
-        // D2 (#730): reread the namespaced `provenance:` block promoteProposal stamps.
+        // #730: reread the namespaced `provenance:` block promoteProposal stamps.
         applyProvenanceFrontmatter(entry, parsed.data);
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
@@ -1220,7 +1284,7 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
                 entry.content = contentProjection;
                 if (truncationInfo.truncated) {
                     entry.contentTruncated = true;
-                    // Unconditional, not warnVerbose: this bound now sits far past any
+                    // Unconditional, not warnVerbose: this bound sits far past any
                     // real document, so tripping it means
                     // something unusual is in the bundle and the operator should see
                     // it without having to pass --verbose.
@@ -1252,8 +1316,8 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
  * Priority 4 of the metadata pipeline — filename-heuristic fallbacks (P4) that
  * run AFTER the renderer-contributor step (P3): a filename description when none
  * was set, path/dir-derived tags, tag normalization, and alias generation.
- * Extracted (Chunk 5 M-b) alongside {@link applyPreContributorFields} so both
- * pipeline paths share it. Behavior-preserving verbatim lift. Mutates `entry`.
+ * Shared with {@link applyPreContributorFields} by both pipeline paths.
+ * Mutates `entry`.
  */
 export function applyPostContributorFields(entry, file, canonicalName, dirPath) {
     const ext = path.extname(file).toLowerCase();
@@ -1267,7 +1331,7 @@ export function applyPostContributorFields(entry, file, canonicalName, dirPath)
     if (!entry.tags || entry.tags.length === 0) {
         entry.tags = extractTagsFromPath(file, dirPath);
     }
-    // Stash-organization conventions (SPEC-2): directory (scope/domain) tokens
+    // Stash-organization conventions: directory (scope/domain) tokens
     // always reach the tags column, even when the author set explicit tags, so
     // nested assets keep the exact-tag ranking boost for their scope token.
     // Derived from canonicalName (the ref subpath) rather than the filesystem
@@ -1284,13 +1348,6 @@ export function applyPostContributorFields(entry, file, canonicalName, dirPath)
     // Heuristic search hints are too noisy to be useful for search quality
     entry.filename = path.basename(file);
 }
-// The pre-0.9.0 flat-walk matcher-pass metadata source was DELETED in Chunk 5
-// F4a M-core-3. Its role (recognize a stash root's files into durable entries)
-// is now the `akm` adapter's `recognize`, drained by `indexer/scan/drain-dir.ts`
-// (`drainDirDocuments` for the live indexer, `recognizeStashEntries` for the
-// `manifest` fallback / `registry` index builder / metadata unit tests). The
-// flip is the F4 engine swap; the shadow-parity gate proved recognize produced
-// the identical entries before the old pass was removed.
 export function buildMetadataSkipWarning(filePath, assetType, error) {
     const detail = error instanceof Error ? error.message : String(error);
     // Workflow errors are already multi-line `path:line — message` blocks; print
@@ -1327,9 +1384,9 @@ function normalizeTerms(values) {
         if (!cleaned)
             continue;
         normalized.add(cleaned);
-        // De-pluralization heuristic removed: the FTS5 porter stemmer (configured
-        // with `tokenize='porter unicode61'`) handles stemming correctly, including
-        // edge cases like "kubernetes" and "status" that the naive s-strip mangled.
+        // No de-pluralization here: the FTS5 porter stemmer (configured with
+        // `tokenize='porter unicode61'`) handles stemming correctly, including
+        // edge cases like "kubernetes" and "status" that a naive s-strip mangles.
     }
     return Array.from(normalized);
 }
@@ -1437,7 +1494,7 @@ export function extractTagsFromPath(filePath, rootDir) {
  * Unlike {@link extractTagsFromPath} this never tokenizes the filename
  * segment: it exists so a nested asset's directory (scope/domain) tokens can
  * be merged into explicit author tags without dragging every filename word
- * into exact-tag matching (SPEC-2, docs/architecture/specs/stash-conventions-code-spec.md).
+ * into exact-tag matching.
  * Tokenization mirrors `extractTagsFromPath`: each segment splits on `-`/`_`/
  * `.`, lowercased, single-character tokens dropped. A name with no directory
  * segments yields no tags.

package/dist/indexer/search/ranking.js

@@ -41,9 +41,13 @@ export function reciprocalRankFusion(channels) {
  * 1 + w·(ln(1+pos) − ln(1+neg)) moves a score by about 2% / 3% / 5% / 9% for
  * 1 / 2 / 5 / 20 positives at 0.03. Measured on the retrieval suite's fused
  * lists, 5 positives lift a hit from rank 10 by a median of 3 places (from rank 5,
- * by 2) and 20 by 4 to 5, so a voted hit passes its near neighbours and a clearly
- * better match stays ahead. At 0.05 the same votes lift it 4 to 5 and 6 to 7
- * places, and two wrong votes cost about 1.6 times the nDCG@10 they cost at 0.03.
+ * by 2) and 20 by 4 to 5. What a vote can pass depends on the channels. In
+ * keyword-only search every fused score is exactly 1 / (RRF_K + rank), so
+ * neighbours in the first 20 sit 1.3 to 1.6% apart and one vote (about 2%) moves
+ * a hit one place (through rank 38) whatever the keyword margin between them. When both channels contribute, their
+ * ranks spread the scores and a vote passes only near-ties. At 0.05 the same
+ * votes lift it 4 to 5 and 6 to 7 places, and two wrong votes cost about 1.6
+ * times the nDCG@10 they cost at 0.03.
  */
 export const FEEDBACK_WEIGHT = 0.03;
 /**

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

@@ -13,7 +13,7 @@
  *  - tags: tags + aliases joined
  *  - hints: searchHints + examples + usage + intent fields
  *  - content: bounded native/adapter body projection + TOC headings + parameters
- *    (lowest-weight catch-all)
+ *    (the catch-all; BM25 weighs all five fields equally)
  */
 export function buildSearchFields(entry) {
     const name = entry.name.replace(/[-_]/g, " ");

package/dist/indexer/usage/usage-events.js

@@ -69,20 +69,28 @@ export function insertUsageEventStrict(db, event) {
 // ── Query ────────────────────────────────────────────────────────────────────
 /**
  * User feedback counts for many assets at once, keyed by durable `entry_ref`.
- * Refs with no user feedback are absent from the map. Read in one query per
- * chunk of refs.
+ * A negative that carried an exact fix does not count once an accepted
+ * `feedback` proposal for the asset exists at or after it (the rule `akm
+ * improve` uses for a fix already acted on); reverting that proposal makes it
+ * count again. Refs with no user feedback are absent from the map. Read in one
+ * query per chunk of refs.
  */
 export function countFeedbackSignalsByRef(db, refs) {
     const counts = new Map();
     for (let i = 0; i < refs.length; i += SQLITE_CHUNK_SIZE) {
         const chunk = refs.slice(i, i + SQLITE_CHUNK_SIZE);
         const rows = db
-            .prepare(`SELECT entry_ref,
-           SUM(CASE WHEN signal = 'positive' THEN 1 ELSE 0 END) AS pos,
-           SUM(CASE WHEN signal = 'negative' THEN 1 ELSE 0 END) AS neg
-         FROM usage_events
-         WHERE event_type = 'feedback' AND source = 'user' AND entry_ref IN (${chunk.map(() => "?").join(",")})
-         GROUP BY entry_ref`)
+            .prepare(`SELECT u.entry_ref,
+           SUM(CASE WHEN u.signal = 'positive' THEN 1 ELSE 0 END) AS pos,
+           SUM(CASE WHEN u.signal = 'negative' AND NOT (
+             json_extract(u.metadata, '$.fix') IS NOT NULL AND EXISTS (
+               SELECT 1 FROM proposals p
+               WHERE p.ref = u.entry_ref AND p.source = 'feedback' AND p.status = 'accepted'
+                 AND julianday(p.created_at) >= julianday(u.created_at))
+           ) THEN 1 ELSE 0 END) AS neg
+         FROM usage_events u
+         WHERE u.event_type = 'feedback' AND u.source = 'user' AND u.entry_ref IN (${chunk.map(() => "?").join(",")})
+         GROUP BY u.entry_ref`)
             .all(...chunk);
         for (const row of rows)
             counts.set(row.entry_ref, { pos: row.pos, neg: row.neg });
@@ -150,3 +158,17 @@ export function purgeOldUsageEvents(db, retentionDays) {
         /* Table may not exist yet */
     }
 }
+/**
+ * Rewrite every `usage_events.entry_ref` naming `oldBundleId` to `newBundleId`
+ * (`akm bundle rename`). Search ranking counts feedback by `entry_ref`, so an
+ * event left under the old prefix stops counting for the renamed bundle's
+ * assets. `entry_id` is untouched: the rename keeps every entry's row id. A
+ * legacy unqualified ref is not matched by the `<old>//` prefix and is left alone.
+ * Returns the number of rows rewritten.
+ */
+export function renameUsageEventRefs(db, oldBundleId, newBundleId) {
+    const prefix = `${oldBundleId}//`;
+    return Number(db
+        .prepare(`UPDATE usage_events SET entry_ref = ? || substr(entry_ref, length(?) + 1) WHERE substr(entry_ref, 1, length(?)) = ?`)
+        .run(newBundleId, oldBundleId, prefix, prefix).changes);
+}

package/dist/indexer/walk/walker.js

@@ -112,7 +112,7 @@ function walkStashGit(stashRoot, options) {
         ? ignoredResult.stdout.toString("utf8")
         : String(ignoredResult.stdout ?? "");
     // Data-hygiene filename skips: the legacy metadata sidecar (never indexed as
-    // content — Chunk-8 folds it into the bundle format) plus git dot-files.
+    // content) plus git dot-files.
     const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
     const stdout = Buffer.isBuffer(result.stdout) ? result.stdout.toString("utf8") : String(result.stdout ?? "");
     const files = [...stdout.split("\0"), ...ignoredStdout.split("\0")]

package/dist/integrations/agent/spawn.js

@@ -14,6 +14,7 @@
  * The command comes from the harness (`harness.build`); this module never
  * touches a model. Agents are reachable only via shell-out.
  */
+import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { childProcessEnv } from "../../core/paths.js";
 import { runManagedSubprocess, streamCaptureFailure } from "../../core/subprocess.js";
@@ -86,10 +87,14 @@ export async function runBuiltCommand(label, { argv, env, stdin }, options, stdi
     // and the optional stdin payload. This keeps the agent-specific surface:
     // the failure taxonomy.
     const start = Date.now();
+    // A program started after `cd <dir>` has PWD equal to <dir>, and OpenCode takes its directory from PWD before its
+    // own working directory: the PWD akm inherits names where akm was started, so a run given a directory names it. One
+    // path is both, so they agree even where the kernel would resolve a `..` after a symbolic link elsewhere.
+    const cwd = options.cwd ? path.resolve(options.cwd) : undefined;
     const result = await runManagedSubprocess([...argv], {
         capture: stdioMode === "captured",
-        env: { ...env },
-        ...(options.cwd ? { cwd: options.cwd } : {}),
+        env: { ...env, ...(cwd ? { PWD: cwd } : {}) },
+        ...(cwd ? { cwd } : {}),
         ...(stdin !== undefined ? { stdin } : {}),
         timeoutMs,
         ...(options.signal ? { signal: options.signal } : {}),

package/dist/integrations/harnesses/opencode/agent-builder.js

@@ -60,9 +60,17 @@ const MODEL_WORK_AGENT_DEFINITION = {
     ],
 };
 const CONFIG_CONTENT_ENV = "OPENCODE_CONFIG_CONTENT";
+/**
+ * OpenCode's built-in browser plugin, removed from model work (a `-` entry in `plugins` removes a plugin, OpenCode 2.0.0
+ * and later). From 2.2.0 it appends a deny of its own skill after every agent's rules, and a rule on one skill keeps
+ * the `skill` tool listed for an agent that denies every tool; without the plugin, the `*` deny removes the tool again.
+ * Model work denies the browser anyway.
+ */
+const WITHOUT_BROWSER_PLUGIN = "-opencode.browser";
 /**
  * The inline config model work runs with: the user's own `OPENCODE_CONFIG_CONTENT` as it is, with akm's agent set on
- * `agents.akm-model-work`, the one key akm's definition wins. OpenCode 2 reads that native `agents` map over the
+ * `agents.akm-model-work`, the one key akm's definition wins, and {@link WITHOUT_BROWSER_PLUGIN} after the user's
+ * `plugins`. OpenCode 2 reads that native `agents` map over the
  * legacy `agent` one, so a same-named entry the user keeps in `agent` is left out rather than left to conflict. The
  * child's value is built from the parent's, so a provider, model or key the user keeps only there stays. It is read as
  * OpenCode reads it, as JSONC (comments and trailing commas), and written back as JSON; content that reads only once
@@ -78,6 +86,7 @@ function modelWorkConfig() {
     }
     const config = {
         ...user,
+        plugins: [...(Array.isArray(user?.plugins) ? user.plugins : []), WITHOUT_BROWSER_PLUGIN],
         agents: { ...asRecord(user?.agents), [MODEL_WORK_AGENT]: MODEL_WORK_AGENT_DEFINITION },
     };
     const legacy = asRecord(user?.agent);

package/dist/integrations/harnesses/opencode/runtime/binary.js

@@ -25,10 +25,13 @@ import { info } from "../../../../core/warn.js";
  * The OpenCode release akm's own runtime runs. It is pinned because the runtime depends on things no OpenCode release
  * promises: the inline config's shape, the `--standalone` flag, the plugin API, the text `run` prints, and the
  * `opencode.db` tables that `../session-log-v2.ts` reads. To move it, change this version and `PACKAGES` if the release
- * adds or drops a platform package, then run `tests/integration/opencode-runtime-sessions.test.ts` against the new
- * binary (it fetches it) and read `docs/reference/configuration.md` ("Without a harness") for what the version changes.
+ * adds or drops a platform package, then run `tests/integration/opencode-runtime-sessions.test.ts` and
+ * `tests/integration/opencode-runtime-loop-guard.test.ts` against the new binary (they fetch it; the plugin ends a
+ * looping run by throwing from a hook, which OpenCode might one day handle differently, and tells the model by changing
+ * the body of a request, which it might one day stop letting a plugin do) and read
+ * `docs/reference/configuration.md` ("Without a harness") for what the version changes.
  */
-export const OPENCODE_RUNTIME_VERSION = "2.1.4";
+export const OPENCODE_RUNTIME_VERSION = "2.2.0";
 /** The platform packages of `@opencode/cli` at {@link OPENCODE_RUNTIME_VERSION}. */
 const PACKAGES = new Set([
     "@opencode/cli-linux-x64",

package/dist/integrations/harnesses/opencode/runtime/index.js

@@ -23,7 +23,7 @@ import { openDatabase } from "../../../../storage/database.js";
 import { resolveAkmInvocation } from "../../../../tasks/resolve-akm-bin.js";
 import { buildChildEnv, runBuiltCommand, } from "../../../agent/spawn.js";
 import { akmOpencodeDatabasePath, akmRuntimeDir } from "../roots.js";
-import { v2SessionTokens } from "../session-log-v2.js";
+import { v2SessionFailure, v2SessionTokens } from "../session-log-v2.js";
 import { ensureRuntimeBinary, OPENCODE_RUNTIME_VERSION, runtimeBinaryPath } from "./binary.js";
 import { runtimeArgv, runtimeConfig, runtimeEnv, runtimePrepareArgv } from "./command.js";
 /**
@@ -61,10 +61,11 @@ function installPlugin(directory) {
 /**
  * OpenCode makes and migrates its database when a process starts, and two processes doing that to one database break
  * each other (one fails with "Standalone server exited before reporting readiness"; on 2.1.4 two runs started together
- * on a fresh directory lose one of them every time). So the first start of this OpenCode version is a preparing run of
- * its own, under a lock file in the runtime directory that every run, of this akm process or another, waits on, and it
- * leaves a marker naming the version; a run that finds the marker and the database starts at once. A dead holder's
- * lock is reclaimed. The run itself reports anything the preparation does not.
+ * on a fresh directory lose one of them every time; on 2.2.0, 4 of 24 starts in groups of eight failed). So the first
+ * start of this OpenCode version is a preparing run of its own, under a lock file in the runtime directory that every
+ * run, of this akm process or another, waits on, and it leaves a marker naming the version; a run that finds the marker
+ * and the database starts at once. A dead holder's lock is reclaimed. The run itself reports anything the preparation
+ * does not.
  */
 async function prepareDatabase(directory, command, opts) {
     const marker = path.join(directory, `prepared-${OPENCODE_RUNTIME_VERSION}`);
@@ -100,9 +101,9 @@ async function prepareDatabase(directory, command, opts) {
     }
 }
 /**
- * The run's session as OpenCode recorded it, read once the process has ended: its id and the tokens its turn used,
- * which a workflow's `budget.max_tokens` and the unit journal count. Nothing when the run made no session. Accounting
- * is best-effort: a database that cannot be read leaves the run's result as it is.
+ * The run's session as OpenCode recorded it, read once the process has ended: its id, the tokens its turn used, which a
+ * workflow's `budget.max_tokens` and the unit journal count, and the message its turn failed with, if it did. Nothing
+ * when the run made no session. Best-effort: a database that cannot be read leaves the run's result as it is.
  */
 function sessionRecord(sessionId) {
     try {
@@ -111,9 +112,11 @@ function sessionRecord(sessionId) {
             const tokens = v2SessionTokens(db, sessionId);
             if (!tokens)
                 return {};
+            const failure = v2SessionFailure(db, sessionId);
             return {
                 sessionId,
                 usage: { inputTokens: tokens.input, outputTokens: tokens.output, reasoningTokens: tokens.reasoning },
+                ...(failure ? { failure } : {}),
             };
         }
         finally {
@@ -160,7 +163,13 @@ export const opencodeRuntime = {
                     writeKeyFile(keyFile, connection.apiKey);
                 await prepareDatabase(directory, { argv: runtimePrepareArgv(binary), env }, opts);
                 const result = await runBuiltCommand(label, { argv: runtimeArgv(connection, dispatch, binary, session), env, stdin: dispatch.prompt }, opts, "captured");
-                return { ...result, ...sessionRecord(session) };
+                const { failure, ...record } = sessionRecord(session);
+                return {
+                    ...result,
+                    ...record,
+                    // OpenCode prints why the turn failed on stderr, which a workflow does not keep; the error carries it.
+                    ...(result.reason === "non_zero_exit" && failure ? { error: `${result.error}: ${failure}` } : {}),
+                };
             }
             finally {
                 fs.rmSync(keyFile, { force: true });

package/dist/integrations/harnesses/opencode/session-log-v2.js

@@ -141,7 +141,7 @@ export function listV2Sessions(db, sinceMs) {
 }
 /**
  * The tokens one session's turns used: OpenCode records them on each assistant message and keeps their sums on the
- * session row (equal, measured on 2.1.4). Undefined when the session is not in the file.
+ * session row (equal, measured on 2.1.4 and 2.2.0). Undefined when the session is not in the file.
  */
 export function v2SessionTokens(db, sessionId) {
     const row = db
@@ -149,6 +149,16 @@ export function v2SessionTokens(db, sessionId) {
         .get(sessionId);
     return row ? { input: row.tokens_input, output: row.tokens_output, reasoning: row.tokens_reasoning } : undefined;
 }
+/**
+ * The message a session's turn failed with, as OpenCode recorded it on the session's `idle` message (an error a plugin
+ * hook threw, a provider's refusal). Undefined when the session is not in the file or its turn did not fail.
+ */
+export function v2SessionFailure(db, sessionId) {
+    const row = db
+        .prepare("SELECT json_extract(data, '$.error.message') AS message FROM session_message WHERE session_id = ? AND type = 'idle' AND json_extract(data, '$.outcome') = 'failed' ORDER BY seq DESC LIMIT 1")
+        .get(sessionId);
+    return typeof row?.message === "string" && row.message.trim() !== "" ? row.message : undefined;
+}
 /** One session's events, from its messages in order. Throws when the session is not in the file. */
 export function readV2Session(db, harness, sessionId, filePath) {
     const row = db

package/dist/output/shapes/helpers.js

@@ -71,7 +71,7 @@ export function shapeProposalEntry(entry, detail) {
     if (detail === "normal") {
         // `confidence` and `gateDecision` (#577) explain why a proposal is pending,
         // so they are projected at `normal` for `akm proposal list/show` when present.
-        // `retirement` (alpha.9) is the same kind of field for a consolidate
+        // `retirement` is the same kind of field for a consolidate
         // `retire` proposal: without it, "list/show" carries no reason a reviewer
         // could act on (its `payload.content` is empty by design — a retire
         // proposal deletes, it does not write).
@@ -278,7 +278,7 @@ export function shapeSearchHit(hit, detail) {
     }
     // Stash hit (local or remote)
     // `ref` is included at `brief` so agents can run `akm show <ref>` without
-    // needing --detail full or --detail agent (REC-03).
+    // needing --detail full or --detail agent.
     if (detail === "brief") {
         return pickFields(hit, ["type", "name", "ref", "action", "estimatedTokens", "keys"]);
     }
@@ -376,7 +376,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
     const base = pickFields(result, [
         "type",
         "name",
-        // ref is always projected, same as path/editable below (R-020).
+        // ref is always projected, same as path/editable below.
         "ref",
         "origin",
         "action",

package/dist/output/text/command-format.js

@@ -7,8 +7,7 @@
  * events/history, search/curate, and the stash-lifecycle verbs (init,
  * index, list, add, remove, update, upgrade, clone).
  *
- * Split out of `helpers.ts` (formerly 1418 lines / 59 fns) as its own
- * sibling module: unlike `show`/`workflow`/`proposal` (each a stateful,
+ * Unlike `show`/`workflow`/`proposal` (each a stateful,
  * multi-branch renderer with its own module), these are flat
  * field-extraction formatters with no shared state.
  */
@@ -308,7 +307,7 @@ export function formatSearchPlain(r, detail) {
         if (parts.length > 0)
             lines.push(`timing: ${parts.join(", ")}`);
     }
-    // REC-02: When stash hits exist, tell the agent the next required step so it
+    // When stash hits exist, tell the agent the next required step so it
     // doesn't skip `akm show` and write from training memory instead.
     if (hits.length >= 1) {
         // Prefer skill/command/agent type hits for the "Next:" ref — knowledge docs are
@@ -517,7 +516,7 @@ export function formatAddPlain(r) {
     // writes a desired locator to config — nothing is synced until a later
     // `akm bundle update`. Force-fitting the declarative shape's `added`/`entry`/`message`
     // fields into the "Installed <ref> (N scanned...)" wording produced
-    // "Installed undefined (0 directories scanned...)" (R-014) because it
+    // "Installed undefined (0 directories scanned...)" because it
     // implied a sync that never happened. `AddResponse` always carries an
     // `index` block (even when zero entries were scanned); `SourceAddResult`
     // never does — that is the reliable shape discriminator used below to
@@ -630,11 +629,11 @@ export function formatBundleRenamePlain(r) {
     return lines.join("\n");
 }
 export function formatUpdatePlain(r) {
-    // R-015: `processed` alone conflated three cases into one empty array —
+    // `processed` alone would conflate three cases into one empty array —
     // a true no-op (--all with nothing configured), a source this call flatly
     // never looked at (a plain source under --all), and a plain git/website
     // source that WAS just synced successfully but has no `UpdateResultItem`
-    // shape to report (no version/lock to diff). All three rendered as the
+    // shape to report (no version/lock to diff). All three would render as the
     // same misleading "nothing to update". `plainSynced` and `skipped` (see
     // sources/types.ts) cover the other two so this can report accurately.
     const processed = r.processed;