akm-opencode 0.8.1 → 0.9.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "akm-opencode",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
-  "description": "OpenCode plugin for AKM v0.8.0 - search, show, and manage extension assets via the akm CLI, including vaults, wikis, workflows, the proposal queue, lesson assets, and improve/propose commands, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
+  "description": "OpenCode plugin for AKM 0.9 with in-process search, show, and curate tools plus feedback and remember.",
   "keywords": [
     "opencode",
     "opencode-ai",
@@ -25,8 +25,6 @@
   "license": "MPL-2.0",
   "files": [
     "index.ts",
-    "agent/",
-    "commands/",
     "shared/",
     "README.md"
   ],
@@ -36,11 +34,15 @@
   },
   "scripts": {
     "prepack": "node ./scripts/vendor-shared.mjs",
-    "postpack": "node ./scripts/unvendor-shared.mjs"
+    "postpack": "node ./scripts/unvendor-shared.mjs",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.2.20",
-    "akm-cli": "^0.8.0",
-    "semver": "^7.7.2"
+    "@opencode-ai/plugin": "^1.18.14",
+    "akm-cli": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.8.3"
   }
 }

package/shared/akm-version.ts

@@ -0,0 +1,45 @@
+// Single source of truth for the akm-cli version contract.
+//
+// Both the Claude hook (claude/hooks/akm-hook.ts) and the OpenCode plugin
+// (opencode/index.ts) validate the user's installed akm-cli against this exact
+// range. Keeping it here — alongside the vendored semver matcher — means a
+// version bump is a one-line change in one file instead of three drifting
+// copies (a hand-rolled `minor === 8` check previously diverged here).
+//
+// The matcher is the vendored `satisfies()` rather than the npm `semver`
+// package because the Claude hook runs as a bare Bun script with no
+// node_modules at hook-execution time. This module is vendored into the
+// published OpenCode tarball by opencode/scripts/vendor-shared.mjs, so the
+// same code path runs on both sides.
+//
+// A single caret clause anchored at the stable release covers the whole
+// supported line: `^0.9.0` admits every stable 0.9.x (0.9.0, 0.9.3, ...).
+// The pre-release floor (`^0.9.0-rc.14`) was retired when akm-cli 0.9.0
+// stable shipped: release candidates are dead once the release exists, and
+// keeping the RC floor would have kept recommending a prerelease install ref.
+//
+// KNOWN GAP: NO prerelease satisfies this range — not 0.9.0-rc.15, and not a
+// *future* line such as 0.9.1-rc.1. That is node-semver's documented behavior
+// and the vendored matcher reproduces it: a prerelease only satisfies a range
+// whose lower bound is a prerelease with the same major.minor.patch. Admitting
+// a prerelease line again is an explicit one-clause edit here
+// (`^0.9.0 || ^0.9.1-rc.1`) when such a build actually needs testing — a
+// deliberate opt-in rather than a range that silently accepts untested
+// prereleases.
+//
+// 0.8.0 support was dropped for the 0.9.0 release: 0.9.0-only runtime paths
+// (`akm proposal extract --session-id`, curate `--detail brief`) fail against
+// 0.8.x, so accepting 0.8.x here would silently pass the version gate onto a
+// CLI the plugin no longer fully works with.
+
+import { satisfies } from "./vendor-semver"
+
+export const AKM_VERSION_RANGE = "^0.9.0"
+
+/**
+ * True when `version` is a valid semver string that satisfies
+ * {@link AKM_VERSION_RANGE}. Non-strings (e.g. a failed probe) return false.
+ */
+export function satisfiesAkmVersionRange(version: string | null | undefined): boolean {
+  return typeof version === "string" && satisfies(version, AKM_VERSION_RANGE)
+}

package/shared/memory-candidates.ts

@@ -1,21 +1,16 @@
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs"
 import path from "node:path"
 import { redactObject } from "./redaction"
-
 // Memory candidates can contain prompt fragments, ref names, and (despite
 // redaction) potentially sensitive contextual data harvested from session
-// activity. Lock the on-disk file down to user-only read/write so multi-user
+// activity. The on-disk file is locked to user-only read/write so multi-user
 // hosts (CI runners, shared VMs, dev sandboxes) cannot side-read another
-// user's stash signals.
-function chmodSafe(filePath: string, mode: number): void {
-  try {
-    chmodSync(filePath, mode)
-  } catch {
-    // Best-effort: filesystems without POSIX mode (FAT, some FUSE mounts) or
-    // platforms where chmod is a no-op (Windows) silently skip. Don't crash
-    // the hook over a hardening attempt.
-  }
-}
+// user's stash signals, and memory-candidates.jsonl is size-capped like every
+// other append-only state file. Both primitives — plus the temp+rename write
+// used by replaceCandidates() (13: "Non-atomic candidate updates") — live in
+// ./state-files so the Claude hook, ./memory-events and this module share one
+// implementation.
+import { atomicWriteFileSync, chmodSafe, rotateIfOversized } from "./state-files"
 
 export type AkmMemoryCandidate = {
   id: string
@@ -150,6 +145,7 @@ export function appendCandidates(filePath: string, candidates: AkmMemoryCandidat
   try {
     mkdirSync(path.dirname(filePath), { recursive: true })
     chmodSafe(path.dirname(filePath), 0o700)
+    rotateIfOversized(filePath)
     const categories: string[] = []
     const created = !existsSync(filePath)
     for (const candidate of candidates) {
@@ -181,8 +177,16 @@ export function readCandidates(filePath: string): AkmMemoryCandidate[] {
 export function replaceCandidates(filePath: string, candidates: AkmMemoryCandidate[]): void {
   mkdirSync(path.dirname(filePath), { recursive: true })
   chmodSafe(path.dirname(filePath), 0o700)
-  writeFileSync(filePath, candidates.map((candidate) => `${JSON.stringify(candidate)}\n`).join(""))
-  chmodSafe(filePath, 0o600)
+  // Atomic rewrite (13: "Non-atomic candidate updates" — see
+  // atomicWriteFileSync above). updateCandidateStatus() is a
+  // read-modify-write over the whole file; without temp+rename, a second
+  // hook process's appendCandidates() (a plain appendFileSync) landing
+  // between this read and this write would be silently overwritten by this
+  // rewrite once it lands, because writeFileSync truncates in place.
+  // temp+rename doesn't fully eliminate that read-modify-write race (true
+  // fix would need a lock), but it does guarantee the file itself is never
+  // observed half-written / truncated by a concurrent reader.
+  atomicWriteFileSync(filePath, candidates.map((candidate) => `${JSON.stringify(candidate)}\n`).join(""), 0o600)
 }
 
 export function updateCandidateStatus(filePath: string, id: string, status: "promoted" | "rejected", reason?: string): AkmMemoryCandidate | undefined {

package/shared/memory-events.ts

@@ -1,17 +1,12 @@
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs"
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs"
 import path from "node:path"
 import { redactObject } from "./redaction"
-
 // Memory events log session activity (refs touched, outcomes, scope). Even
-// post-redaction this is a privileged record; lock the directory + file down
-// to owner-only access. Mirrors memory-candidates' chmodSafe helper.
-function chmodSafe(target: string, mode: number): void {
-  try {
-    chmodSync(target, mode)
-  } catch {
-    // Best-effort; see memory-candidates.ts for rationale.
-  }
-}
+// post-redaction this is a privileged record, so the directory + file are
+// locked to owner-only and events.jsonl is size-capped like every other
+// append-only state file. Both primitives live in ./state-files so the Claude
+// hook, this module and ./memory-candidates share one implementation.
+import { chmodSafe, rotateIfOversized } from "./state-files"
 
 export type AkmMemoryEventType =
   | "session_started"
@@ -90,6 +85,7 @@ export function appendMemoryEvent(filePath: string, event: AkmMemoryEvent): { ok
   try {
     mkdirSync(path.dirname(filePath), { recursive: true })
     chmodSafe(path.dirname(filePath), 0o700)
+    rotateIfOversized(filePath)
     const redacted = redactObject(event)
     const enriched = {
       ...redacted.value,

package/shared/ref-extraction.ts

@@ -1,89 +1,30 @@
 /**
- * AKM ref extraction & live-stash validation.
+ * AKM 0.9 ref extraction and local bundle validation.
  *
- * Background: session-checkpoint memories captured by the hook embed Bash
- * command bodies verbatim — heredocs, grep patterns, jq queries, JSON
- * payloads. Naive ref extraction (`text.match(REF_PATTERN)`) treats every
- * `<type>:<slug>` token as a real reference, which causes `akm lint` to
- * flag string-literal tokens as `missing-ref`. The next session capture
- * regenerates the same flags — a permanent lint treadmill.
- *
- * The fix (this module): we drop the "guess from context" heuristic and
- * instead **validate every candidate against the live local stash**. A
- * token only graduates from "candidate" to "ref" when the referenced asset
- * actually exists on disk. Anything that doesn't resolve is silently
- * dropped — including all the literal-string false positives.
- *
- * The validation logic mirrors the consumer-side lint walker
- * (`src/commands/lint/base-linter.ts#refExistsInAnyStash`). We deliberately
- * inline a small copy here (rather than spawn a subprocess) so the hook's
- * post-tool path stays cheap (zero subprocess, zero JSON parse). The two
- * resolvers must stay in sync; any new asset type added to lint's
- * `refToRelPath` must be added here too.
+ * Session checkpoints can contain command bodies, heredocs, and serialized
+ * tool output. Extraction is deliberately permissive, then candidates are
+ * retained only when their concept ID resolves inside a provided bundle root.
+ * This keeps the hook subprocess-free and drops ref-shaped string literals.
  */
 
-// CONTRACT: ref-resolver
-// ----------------------------------------------------------------------------
-// The `refExistsInAnyStash` and `refToRelPath` helpers below are
-// contract-locked: a sister copy lives in the akm-core repo at
-// `src/commands/lint/base-linter.ts`. Both implementations resolve the same
-// `<type>:<slug>` -> on-disk-asset question and MUST agree on the set of
-// reachable refs for any given stash layout.
-//
-// The lock is enforced by `tests/ref-resolver-contract.test.ts`, which drives
-// `validateRefCandidates` (the only public entry to this resolver) through a
-// canonical fixture set. The akm-core repo ships an equivalent test at
-// `tests/contracts/ref-resolver-contract.test.ts` that drives ITS copy
-// through the SAME inputs. Any change to the resolver behavior on either
-// side MUST update both contract tests in lockstep, or one will fail.
-//
-// NOTE: this file is the SECOND copy of the resolver. The runtime-shipped
-// copy lives at `claude/shared/ref-extraction.ts` and is imported by the
-// post-tool hook. Both copies must agree with each other AND with the
-// akm-core resolver. The contract test runs against `../shared/ref-extraction`
-// (this file) — the divergence between this file and the runtime copy is
-// tracked separately (regex tightness only, see top-level repo notes).
-// ----------------------------------------------------------------------------
-
-import { existsSync, statSync, readdirSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import path from "node:path";
 
-/**
- * Permissive ref regex. Matches `[origin//]type:slug` for the known asset
- * types. Origins (e.g. `local//`, `npm:foo//`) are tolerated but stripped
- * before validation — only `local//` refs are resolvable against the local
- * stash; anything else is dropped because we cannot validate it offline.
- *
- * Kept in sync with the lint walker pattern in
- * `src/commands/lint/base-linter.ts`.
- */
-// Slug body allows the same charset as the lint walker, but the closing
-// character must be alphanumeric, `_`, or `-` — so a trailing `.` or `/`
-// from natural prose (`see memory:rollout-notes.`) does not leak into
-// the captured ref string. Mirrors the consumer-side
-// `src/commands/lint/base-linter.ts` REF_RE, which terminates on a
-// punctuation set including `.` via lookahead. We allow `.` mid-slug
-// (e.g. `env:.env`-style names) by requiring the slug to be at least
-// one character and to *end* on `[A-Za-z0-9_-]`.
+// Passive extraction is intentionally narrower than AKM's explicit ref parser:
+// only standard concept roots are observed. This prevents ordinary paths such
+// as src/app.ts from becoming automatic feedback targets.
+//
+// The concept-root list is the exact set of directories `akm bundle create`
+// scaffolds in 0.9 (agents commands env facts instructions knowledge lessons
+// memories scripts secrets sessions skills tasks workflows), which matches the
+// `assetTypes` array reported by `akm info --format json` modulo pluralization.
+// `wikis` was dropped for 0.9 — it is neither an asset type nor a scaffolded
+// directory — and facts/instructions/sessions were added. Keep this list byte
+// for byte in sync with opencode/index.ts and evals/tier2/metrics/feedback.ts.
 const REF_PATTERN =
-  /(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|lesson|script|workflow|task|env|secret|wiki):(?:[A-Za-z0-9._/-]*[A-Za-z0-9_-]|[A-Za-z0-9_-])/g;
-
-/**
- * Return every `<type>:<slug>` token in `text` regardless of context.
- * Order matches first-occurrence; duplicates are removed.
- */
-export function extractAllRefs(text: string): string[] {
-  if (!text) return [];
-  return [...new Set(text.match(REF_PATTERN) ?? [])];
-}
-
-// Tokenized whitespace-split fallback used by callers that need a strict
-// "this token, in isolation, is a ref" answer (e.g. PreToolUse non-Bash
-// observation, which inspects a single tool input field rather than a
-// transcript-style body). Kept for backward compatibility with existing
-// callers in `claude/hooks/akm-hook.ts` and the opencode plugin.
+  /(?<![A-Za-z0-9@._+/:=-])(?:[A-Za-z0-9@._+-]+\/\/)?(?:agents|commands|env|facts|instructions|knowledge|lessons|memories|scripts|secrets|sessions|skills|tasks|workflows)\/[A-Za-z0-9._/-]+(?:#[A-Za-z0-9._~!$&'()*+,;=:@%/?-]+)?(?![A-Za-z0-9@._+/#$=-])/g;
 const AKM_REF_STRICT =
-  /^(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|task|env|secret|wiki|lesson):[A-Za-z0-9._/\-]+$/;
+  /^(?:[A-Za-z0-9@._+-]+\/\/)?(?:agents|commands|env|facts|instructions|knowledge|lessons|memories|scripts|secrets|sessions|skills|tasks|workflows)\/[A-Za-z0-9._/-]+(?:#[A-Za-z0-9._~!$&'()*+,;=:@%/?-]+)?$/;
 const EDGE_PUNCTUATION = new Set([".", ",", ";", ":", "!", "?", "(", ")", "[", "]", "{", "}", "'", "\"", "`"]);
 
 function normalizeToken(token: string): string {
@@ -94,6 +35,18 @@ function normalizeToken(token: string): string {
   return token.slice(start, end);
 }
 
+/** Return all ref-shaped tokens in first-occurrence order, deduplicated. */
+export function extractAllRefs(text: string): string[] {
+  if (!text) return [];
+  const refs = new Set<string>();
+  for (const match of text.match(REF_PATTERN) ?? []) {
+    const normalized = normalizeToken(match);
+    if (AKM_REF_STRICT.test(normalized)) refs.add(normalized);
+  }
+  return [...refs];
+}
+
+/** Return whitespace-delimited tokens that are complete AKM refs. */
 export function extractAkmRefsFromString(text: string): string[] {
   const refs = new Set<string>();
   for (const token of text.split(/\s+/)) {
@@ -103,159 +56,65 @@ export function extractAkmRefsFromString(text: string): string[] {
   return [...refs];
 }
 
-/**
- * Map ref type → relative path within a stash root.
- * Returns `null` for types that cannot be resolved by direct path
- * (scripts live in nested dirs; remote-only types).
- */
-function refToRelPath(refType: string, refName: string): string | null {
-  switch (refType) {
-    case "agent":
-      return path.join("agents", `${refName}.md`);
-    case "command":
-      return path.join("commands", `${refName}.md`);
-    case "knowledge":
-      return path.join("knowledge", `${refName}.md`);
-    case "memory":
-      return path.join("memories", `${refName}.md`);
-    case "script":
-      return null; // scripts live in nested dirs — skip
-    case "skill":
-      return path.join("skills", refName, "SKILL.md");
-    case "workflow":
-      return path.join("workflows", `${refName}.md`);
-    case "lesson":
-      return path.join("lessons", `${refName}.md`);
-    case "task":
-      return path.join("tasks", `${refName}.md`);
-    case "wiki":
-      return path.join("wikis", `${refName}.md`);
-    case "env":
-      if (!refName || refName === "default") return path.join("env", ".env");
-      return path.join("env", `${refName}.env`);
-    case "secret":
-      return path.join("secrets", refName);
-    default:
-      return null;
-  }
+interface NormalizedRef {
+  canonical: string;
+  conceptId: string;
 }
 
-/**
- * True if `<type>:<refName>` resolves to a real file under any provided
- * stash root. Mirrors `refExistsInAnyStash` in `src/commands/lint/base-linter.ts`.
- */
-function refExistsInAnyStash(refType: string, refName: string, stashRoots: readonly string[]): boolean {
-  const relPath = refToRelPath(refType, refName);
-  if (!relPath) return false;
-  for (const root of stashRoots) {
-    if (!root) continue;
-    const absPath = path.join(root, relPath);
-    if (existsSync(absPath)) return true;
-    // Multi-file skill layout: directory containing SKILL.md
-    const bareDir = absPath.replace(/\.md$/, "");
-    try {
-      if (existsSync(bareDir) && existsSync(path.join(bareDir, "SKILL.md"))) return true;
-    } catch {
-      // ignore
-    }
-    // .derived.md variant for memory refs
-    if (refType === "memory") {
-      const derivedPath = path.join(root, "memories", `${refName}.derived.md`);
-      if (existsSync(derivedPath)) return true;
-    }
-    // Knowledge subdirectory layout (knowledge/projects/foo/...)
-    if (refType === "knowledge") {
-      try {
-        const knowledgeDir = path.join(root, "knowledge");
-        if (existsSync(knowledgeDir) && statSync(knowledgeDir).isDirectory()) {
-          for (const entry of readdirSync(knowledgeDir)) {
-            const subPath = path.join(knowledgeDir, entry, `${refName}.md`);
-            if (existsSync(subPath)) return true;
-          }
-        }
-      } catch {
-        // ignore
-      }
-    }
-    // Fallback: refName already encodes the stash-relative path
-    const directPath = path.join(root, `${refName}.md`);
-    if (existsSync(directPath)) return true;
-    const directDir = path.join(root, refName);
-    try {
-      if (existsSync(directDir) && existsSync(path.join(directDir, "SKILL.md"))) return true;
-    } catch {
-      // ignore
-    }
+function normalizeCandidate(candidate: string): NormalizedRef | null {
+  const canonical = normalizeToken(candidate);
+  if (!AKM_REF_STRICT.test(canonical)) return null;
+
+  const withoutFragment = canonical.split("#", 1)[0] ?? "";
+  const separator = withoutFragment.indexOf("//");
+  const conceptId = separator === -1 ? withoutFragment : withoutFragment.slice(separator + 2);
+  const segments = conceptId.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return null;
+
+  return { canonical, conceptId };
+}
+
+function isFile(file: string): boolean {
+  try {
+    return existsSync(file) && statSync(file).isFile();
+  } catch {
+    return false;
   }
-  return false;
 }
 
-/**
- * Drop candidate tokens that obviously cannot resolve:
- * - Embedded shell expansion: `memory:$(cmd)`, `knowledge:${VAR}`
- * - ACP type notation: `agent::Type`
- * - Empty / placeholder slugs: single char, `**`, leading `/`, `~`, `http*`
- * - Remote origins other than `local//` (cannot be validated offline)
- */
-function normalizeCandidate(fullRef: string): { type: string; name: string } | null {
-  if (fullRef.includes("$(") || fullRef.includes("${")) return null;
-  if (fullRef.includes("::")) return null;
+/** Resolve a concept ID under any local bundle root without invoking AKM. */
+function conceptExistsInAnyBundle(conceptId: string, bundleRoots: readonly string[]): boolean {
+  for (const root of bundleRoots) {
+    if (!root) continue;
+    const resolvedRoot = path.resolve(root);
+    const directPath = path.resolve(resolvedRoot, conceptId);
+    if (directPath !== resolvedRoot && !directPath.startsWith(`${resolvedRoot}${path.sep}`)) continue;
 
-  let ref = fullRef;
-  if (ref.startsWith("local//")) {
-    ref = ref.slice("local//".length);
-  } else if (ref.includes("//")) {
-    return null; // remote origin — cannot validate locally
+    if (isFile(directPath) || isFile(`${directPath}.md`)) return true;
+    if (isFile(path.join(directPath, "SKILL.md"))) return true;
+    if (conceptId.startsWith("memories/") && isFile(`${directPath}.derived.md`)) return true;
   }
-
-  const colonIdx = ref.indexOf(":");
-  if (colonIdx === -1) return null;
-  const type = ref.slice(0, colonIdx);
-  const name = ref.slice(colonIdx + 1);
-  if (!name || name.startsWith("/") || name.startsWith("~") || name.startsWith("http")) return null;
-  if (name.length <= 1 || name === "**") return null;
-  // Slug must not contain shell metacharacters — pipe etc. would be a
-  // pasted regex like `memory:foo|knowledge:bar`.
-  if (/[|&;<>(){}\[\]"`'\\?*]/.test(name)) return null;
-  return { type, name };
+  return false;
 }
 
-/**
- * Given an arbitrary block of text and one or more stash roots, return the
- * subset of `<type>:<slug>` tokens that actually resolve to a real asset
- * on disk. String literals (heredocs, grep patterns, jq queries) are
- * silently dropped — they don't exist in the stash and therefore cannot
- * generate `missing-ref` lint flags after the body is captured.
- *
- * The returned list is sorted alphabetically and deduplicated.
- */
-export function validateLiveRefs(text: string, stashRoots: readonly string[]): string[] {
-  return validateRefCandidates(extractAllRefs(text), stashRoots);
+/** Extract and retain only refs whose concept IDs exist in a local bundle. */
+export function validateLiveRefs(text: string, bundleRoots: readonly string[]): string[] {
+  return validateRefCandidates(extractAllRefs(text), bundleRoots);
 }
 
 /**
- * Validate a pre-extracted list of candidate refs against one or more
- * stash roots. Returns the subset that resolve to a real on-disk asset,
- * sorted alphabetically and deduplicated. The input is typically produced
- * by `extractAllRefs(...)` on raw command/output text — the producer-side
- * collection step is permissive so candidates can be accumulated across
- * tool invocations and validated once at memory-capture time.
+ * Validate pre-extracted refs against local bundle roots. Bundle qualifiers and
+ * fragments are preserved in the result but do not alter local path lookup.
  */
-export function validateRefCandidates(candidates: readonly string[], stashRoots: readonly string[]): string[] {
+export function validateRefCandidates(candidates: readonly string[], bundleRoots: readonly string[]): string[] {
   if (!candidates || candidates.length === 0) return [];
-  const roots = stashRoots.filter(Boolean);
+  const roots = bundleRoots.filter(Boolean);
   if (roots.length === 0) return [];
-  const seen = new Set<string>();
-  const out: string[] = [];
+
+  const refs = new Set<string>();
   for (const candidate of candidates) {
-    const norm = normalizeCandidate(candidate);
-    if (!norm) continue;
-    if (!refExistsInAnyStash(norm.type, norm.name, roots)) continue;
-    const canonical = `${norm.type}:${norm.name}`;
-    if (seen.has(canonical)) continue;
-    seen.add(canonical);
-    out.push(canonical);
+    const normalized = normalizeCandidate(candidate);
+    if (normalized && conceptExistsInAnyBundle(normalized.conceptId, roots)) refs.add(normalized.canonical);
   }
-  out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-  return out;
+  return [...refs].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }

package/shared/state-files.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared helpers for the append-only state files both plugins keep under their
+ * harness state dir (session.log, feedback.log, memory.log, quality-cache.tsv,
+ * sessions/<sid>.md, extract.log, events.jsonl, memory-candidates.jsonl).
+ *
+ * This module is the single copy of three primitives that were previously
+ * duplicated near-verbatim in claude/hooks/akm-hook.ts, ./memory-events.ts and
+ * ./memory-candidates.ts:
+ *
+ *   chmodSafe()          best-effort owner-only hardening that never throws
+ *   atomicWriteFileSync() write-temp-then-rename, with temp cleanup on failure
+ *   rotateIfOversized()   size cap that keeps the newest half of the file
+ *
+ * Constraints this module must keep satisfying:
+ *  - Zero third-party imports. claude/hooks/akm-hook.ts runs as a bare Bun
+ *    script with no node_modules at hook-execution time, so only node:* builtins
+ *    are importable here.
+ *  - It is vendored into the published OpenCode tarball by
+ *    opencode/scripts/vendor-shared.mjs, which copies every *.ts in
+ *    claude/shared/ — no registration step is needed for a new file.
+ */
+
+import { chmodSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+
+/**
+ * Best-effort chmod. State files can hold prompt fragments, ref names and
+ * (despite redaction) sensitive contextual data, so they are locked to
+ * owner-only. Filesystems and platforms without POSIX mode (Windows, FAT, some
+ * FUSE mounts) silently skip: a hardening attempt must never crash a hook.
+ */
+export function chmodSafe(target: string, mode: number): void {
+  try {
+    chmodSync(target, mode)
+  } catch {
+    // Intentionally ignored — see the doc comment above.
+  }
+}
+
+/**
+ * Write a file atomically: temp file in the same directory, then rename over
+ * the target. rename(2) is atomic on POSIX (and on Windows via Node's
+ * implementation), so a concurrent reader always observes either the old
+ * content in full or the new content in full — never a torn/partial write.
+ *
+ * A failed rename removes the temp file (nothing else ever prunes it) and then
+ * rethrows, so each caller keeps its own error semantics: rotateIfOversized()
+ * swallows the error, memory-candidates' replaceCandidates() propagates it.
+ */
+export function atomicWriteFileSync(filePath: string, content: string, mode?: number): void {
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(tmpPath, content)
+  if (mode !== undefined) chmodSafe(tmpPath, mode)
+  try {
+    renameSync(tmpPath, filePath)
+  } catch (error) {
+    // Don't orphan the temp file when the swap fails (EXDEV, permissions, a
+    // concurrent unlink of the target dir, ...).
+    try {
+      rmSync(tmpPath, { force: true })
+    } catch {}
+    throw error
+  }
+}
+
+// State-file rotation/caps (release-0.9.0 review §2 "Unbounded state growth"):
+// every append-only file under the harness state dir previously grew without
+// bound for the lifetime of the machine. AKM_PLUGIN_MAX_LOG_BYTES (default
+// 1 MiB) is the shared cap for all of them.
+const MAX_LOG_BYTES = (() => {
+  const raw = Number(process.env.AKM_PLUGIN_MAX_LOG_BYTES)
+  return Number.isFinite(raw) && raw > 0 ? raw : 1024 * 1024
+})()
+
+/**
+ * Before an append: if the file already exceeds AKM_PLUGIN_MAX_LOG_BYTES,
+ * rewrite it down to its newest half (by line count) via write-temp-then-rename
+ * so a concurrent reader/writer never observes a truncated or partial file.
+ *
+ * Best-effort and never throws: a failed attempt just means the file keeps
+ * growing until the next successful append/rotate.
+ */
+export function rotateIfOversized(filePath: string): void {
+  try {
+    const stat = statSync(filePath)
+    if (stat.size <= MAX_LOG_BYTES) return
+    const lines = readFileSync(filePath, "utf8").split("\n")
+    if (lines[lines.length - 1] === "") lines.pop()
+    // Keep-at-least-one-line guard: a single line larger than the cap would
+    // make slice(ceil(len/2)) empty and rotation would erase the file instead
+    // of capping it. Always retain the newest line.
+    const keep = lines.length <= 1 ? lines : lines.slice(Math.ceil(lines.length / 2))
+    // 0o600 on the replacement: without it the rewritten file would come back
+    // at the umask default and quietly drop the owner-only posture the
+    // originals are created with.
+    atomicWriteFileSync(filePath, keep.length > 0 ? `${keep.join("\n")}\n` : "", 0o600)
+  } catch {
+    // Rotation is best-effort and must never throw — see the doc comment.
+  }
+}