@cairnkeep/cli 2.3.1 → 2.5.0

package/mcp-memory-server/scripts/fixtures/compaction-opencode-1.17.20-messages.json

@@ -0,0 +1,119 @@
+{
+  "session": {
+    "id": "opencode-compaction-session-001",
+    "title": "Pinned compaction fixture",
+    "version": "1.17.20",
+    "projectID": "synthetic-project",
+    "directory": "/synthetic/project",
+    "time": {
+      "created": 1785052800000,
+      "updated": 1785052810000
+    }
+  },
+  "messages": [
+    {
+      "info": {
+        "id": "oc-ordinary-user",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "user",
+        "time": { "created": 1785052801000 }
+      },
+      "parts": [
+        { "id": "oc-ordinary-text", "sessionID": "opencode-compaction-session-001", "messageID": "oc-ordinary-user", "type": "text", "text": "Continue normal work." }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-compact-user-old",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "user",
+        "time": { "created": 1785052802000 }
+      },
+      "parts": [
+        { "id": "oc-compaction-part-old", "sessionID": "opencode-compaction-session-001", "messageID": "oc-compact-user-old", "type": "compaction", "auto": true }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-summary-incomplete",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "assistant",
+        "parentID": "oc-compact-user-old",
+        "summary": true,
+        "time": { "created": 1785052803000 }
+      },
+      "parts": [
+        { "id": "oc-incomplete-text", "sessionID": "opencode-compaction-session-001", "messageID": "oc-summary-incomplete", "type": "text", "text": "# Objective\nThis incomplete decoy must not win." }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-summary-error",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "assistant",
+        "parentID": "oc-compact-user-old",
+        "summary": true,
+        "finish": "stop",
+        "error": { "name": "SyntheticError", "message": "failed summary decoy" },
+        "time": { "created": 1785052803500, "completed": 1785052803600 }
+      },
+      "parts": [
+        { "id": "oc-error-text", "sessionID": "opencode-compaction-session-001", "messageID": "oc-summary-error", "type": "text", "text": "# Objective\nThis errored decoy must not win." }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-summary-valid-old",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "assistant",
+        "parentID": "oc-compact-user-old",
+        "summary": true,
+        "finish": "stop",
+        "time": { "created": 1785052804000, "completed": 1785052805000 }
+      },
+      "parts": [
+        { "id": "oc-old-summary-text", "sessionID": "opencode-compaction-session-001", "messageID": "oc-summary-valid-old", "type": "text", "text": "# Objective\nPreserve the old goal.\n\n# Important Details\n- Decision: Keep this valid summary as a selection fallback.\n\n# Work State\n## Completed\n- Fixture parsing is pinned.\n## Active\n- Older work remains.\n## Blocked\n- Error: OldError at old.ts:1.\n\n# Next Move\n- Replace this summary with a newer valid revision.\n\n# Relevant Files\n- src/old.ts" }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-compact-user-new",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "user",
+        "time": { "created": 1785052806000 }
+      },
+      "parts": [
+        { "id": "oc-compaction-part-new", "sessionID": "opencode-compaction-session-001", "messageID": "oc-compact-user-new", "type": "compaction", "auto": false }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-summary-wrong-parent",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "assistant",
+        "parentID": "oc-ordinary-user",
+        "summary": true,
+        "finish": "stop",
+        "time": { "created": 1785052808000, "completed": 1785052809000 }
+      },
+      "parts": [
+        { "id": "oc-wrong-parent-text", "sessionID": "opencode-compaction-session-001", "messageID": "oc-summary-wrong-parent", "type": "text", "text": "# Objective\nThis newest wrong-parent decoy must not win." }
+      ]
+    },
+    {
+      "info": {
+        "id": "oc-summary-valid-new",
+        "sessionID": "opencode-compaction-session-001",
+        "role": "assistant",
+        "parentID": "oc-compact-user-new",
+        "summary": true,
+        "finish": "stop",
+        "time": { "created": 1785052807000, "completed": 1785052808000 }
+      },
+      "parts": [
+        { "id": "oc-new-summary-text", "sessionID": "opencode-compaction-session-001", "messageID": "oc-summary-valid-new", "type": "text", "text": "# Objective\nPreserve supported compaction state across sessions.\n\n# Important Details\n- Decision: Pin adapter behavior to the documented session.compacted family.\n- Nested credentials: {\"authorization\":\"Bearer opencode-compaction-secret-001\",\"nested\":{\"api_key\":\"sk-opencode-compaction-secret-002\"}}\n\n# Work State\n## Completed\n- The exact fixture family is recorded.\n## Active\n- Adapter implementation remains.\n## Blocked\n- Error: TypeError: recovery pointer invalid at selectRecovery (compaction.ts:42).\n\n# Next Move\n- Implement the local immutable compaction adapter.\n\n# Relevant Files\n- mcp-memory-server/src/compaction-normalize.ts" },
+        { "id": "oc-new-summary-ignored", "sessionID": "opencode-compaction-session-001", "messageID": "oc-summary-valid-new", "type": "text", "text": "IGNORED_SUMMARY_SECRET", "ignored": true }
+      ]
+    }
+  ]
+}

package/mcp-memory-server/scripts/fixtures/compaction-unknown-version.json

@@ -0,0 +1,17 @@
+{
+  "harness": "opencode",
+  "harness_version": "99.0.0",
+  "event": {
+    "type": "session.compacted",
+    "properties": {
+      "sessionID": "unknown-version-session"
+    }
+  },
+  "payload": {
+    "authorization": "Bearer unknown-version-secret-001",
+    "nested": {
+      "api_key": "sk-unknown-version-secret-002",
+      "summary": "UNKNOWN_VERSION_PAYLOAD_MUST_NOT_SURVIVE"
+    }
+  }
+}

package/opencode/capability-contract/plugins/capability-command.ts

@@ -0,0 +1,319 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { spawn, spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+
+const COORDINATOR = "@@INFRA_ROOT@@/mcp-memory-server/dist/capability-cli.js"
+const FIXED_BLOCK = "Cairn capability disabled."
+const MAX_COORDINATOR_OUTPUT = 8 * 1024
+const COORDINATOR_TIMEOUT_MS = 3000
+const MAX_TRACKED_SESSIONS = 10_000
+const DISPOSAL_BATCH_SIZE = 32
+const SESSION_ID = /^(?:cairn:)?[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/
+const COMMANDS = new Set([
+  "wiki-ingest",
+  "wiki-query",
+  "wiki-lint",
+  "graphify",
+  "security-audit",
+])
+
+const OPENCODE_CAPABILITY_CONTRACT = {
+  version: "1.17.20",
+  sourceCommit: "4473fc3c9055046183990a965d68df3db7ea6f62",
+  admissionHook: "command.execute.before",
+  terminalEvents: {
+    success_terminals: ["session.idle", "session.status:idle"],
+    error_terminal: "session.error",
+    abandonment_only: "session.deleted",
+    event_callback_is_awaited: false,
+  },
+} as const
+
+type JsonObject = Record<string, unknown>
+type SessionState = {
+  unfinished: boolean
+  terminalEpoch: number
+  operations: number
+  tail: Promise<void>
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function hasExactKeys(value: JsonObject, required: readonly string[], optional: readonly string[] = []): boolean {
+  const keys = Object.keys(value)
+  const allowed = new Set([...required, ...optional])
+  return required.every((key) => Object.hasOwn(value, key))
+    && keys.every((key) => allowed.has(key))
+}
+
+function validSessionID(value: unknown): value is string {
+  return typeof value === "string" && value !== "unknown" && SESSION_ID.test(value)
+}
+
+function contractEnabled(): boolean {
+  return /^(1|true|yes|on)$/i.test(process.env.CAIRN_CAPABILITY_CONTRACT ?? "")
+}
+
+function validatedProjectRoot(values: unknown[]): string | undefined {
+  try {
+    if (!values.every((value) => typeof value === "string" && path.isAbsolute(value))) return undefined
+    const roots = values.map((value) => fs.realpathSync(value as string))
+    if (!roots.every((value) => value === roots[0])) return undefined
+    if (!fs.statSync(roots[0]).isDirectory()) return undefined
+    return roots[0]
+  } catch {
+    return undefined
+  }
+}
+
+function coordinator(operation: string, payload: JsonObject): Promise<JsonObject | undefined> {
+  return new Promise((resolvePromise) => {
+    let stdout = ""
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const finish = (value?: JsonObject) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      resolvePromise(value)
+    }
+    const child = spawn("node", [COORDINATOR, operation], {
+      stdio: ["pipe", "pipe", "ignore"],
+    })
+    timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL")
+      } catch {
+        // best-effort termination only
+      }
+      finish()
+    }, COORDINATOR_TIMEOUT_MS)
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8")
+      if (Buffer.byteLength(stdout, "utf8") > MAX_COORDINATOR_OUTPUT) {
+        stdout = ""
+        try {
+          child.kill("SIGKILL")
+        } catch {
+          // best-effort termination only
+        }
+      }
+    })
+    child.on("error", () => finish())
+    child.on("close", (code) => {
+      if (code !== 0 || !stdout) {
+        finish()
+        return
+      }
+      try {
+        const value = JSON.parse(stdout) as unknown
+        finish(isObject(value) ? value : undefined)
+      } catch {
+        finish()
+      }
+    })
+    child.stdin.on("error", () => finish())
+    child.stdin.end(JSON.stringify(payload))
+  })
+}
+
+function coordinatorSync(operation: string, payload: JsonObject): JsonObject | undefined {
+  const child = spawnSync("node", [COORDINATOR, operation], {
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    timeout: COORDINATOR_TIMEOUT_MS,
+    maxBuffer: MAX_COORDINATOR_OUTPUT,
+    stdio: ["pipe", "pipe", "ignore"],
+  })
+  if (child.error || child.status !== 0 || !child.stdout) return undefined
+  try {
+    const value = JSON.parse(child.stdout) as unknown
+    return isObject(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function terminalRequiresSync(): boolean {
+  return (process.versions as NodeJS.ProcessVersions & { bun?: string }).bun !== undefined
+    || process.env.CAIRN_TEST_OPENCODE_NON_AWAITED === "1"
+}
+
+function admission(input: unknown, output: unknown): {
+  command: string
+  sessionID: string
+} | undefined {
+  if (!isObject(input) || !isObject(output)) return undefined
+  if (!hasExactKeys(input, ["command", "sessionID", "arguments"])) return undefined
+  if (!hasExactKeys(output, ["parts"]) || !Array.isArray(output.parts)) return undefined
+  if (typeof input.command !== "string" || !COMMANDS.has(input.command)) return undefined
+  if (!validSessionID(input.sessionID) || typeof input.arguments !== "string") return undefined
+  return { command: input.command, sessionID: input.sessionID }
+}
+
+function eventTerminal(event: unknown): { sessionID: string; outcome: "success" | "error" | "abandoned" } | undefined {
+  if (!isObject(event) || !hasExactKeys(event, ["type", "properties"], ["id"]) || !isObject(event.properties)) {
+    return undefined
+  }
+  if (Object.hasOwn(event, "id")
+    && (typeof event.id !== "string" || event.id.length === 0 || event.id.length > 256)) return undefined
+  const properties = event.properties
+  if (event.type === "session.idle") {
+    if (!hasExactKeys(properties, ["sessionID"]) || !validSessionID(properties.sessionID)) return undefined
+    return { sessionID: properties.sessionID, outcome: "success" }
+  }
+  if (event.type === "session.error") {
+    if (!hasExactKeys(properties, [], ["sessionID", "error"]) || !validSessionID(properties.sessionID)) return undefined
+    return { sessionID: properties.sessionID, outcome: "error" }
+  }
+  if (event.type === "session.status") {
+    if (!hasExactKeys(properties, ["sessionID", "status"]) || !validSessionID(properties.sessionID)) return undefined
+    if (!isObject(properties.status) || properties.status.type !== "idle" || !hasExactKeys(properties.status, ["type"])) {
+      return undefined
+    }
+    return { sessionID: properties.sessionID, outcome: "success" }
+  }
+  if (event.type === "session.deleted") {
+    if (!hasExactKeys(properties, ["info"]) || !isObject(properties.info)) return undefined
+    const info = properties.info
+    if (!hasExactKeys(
+      info,
+      ["id", "projectID", "directory", "title", "version", "time"],
+      ["parentID", "summary", "share", "revert"],
+    ) || !validSessionID(info.id) || !isObject(info.time)) return undefined
+    if (!hasExactKeys(info.time, ["created", "updated"], ["compacting"])) return undefined
+    if (typeof info.projectID !== "string" || typeof info.directory !== "string"
+      || typeof info.title !== "string" || typeof info.version !== "string"
+      || typeof info.time.created !== "number" || typeof info.time.updated !== "number") return undefined
+    return { sessionID: info.id, outcome: "abandoned" }
+  }
+  return undefined
+}
+
+const capabilityCommandPlugin: Plugin = async ({ directory, worktree, project }) => {
+  const projectRoot = validatedProjectRoot([directory, worktree, project.worktree])
+  const sessions = new Map<string, SessionState>()
+
+  const sessionState = (sessionID: string): SessionState | undefined => {
+    const existing = sessions.get(sessionID)
+    if (existing) return existing
+    if (sessions.size >= MAX_TRACKED_SESSIONS) return undefined
+    const created: SessionState = {
+      unfinished: false,
+      terminalEpoch: 0,
+      operations: 0,
+      tail: Promise.resolve(),
+    }
+    sessions.set(sessionID, created)
+    return created
+  }
+
+  const forgetFinishedSession = (sessionID: string, state: SessionState) => {
+    if (!state.unfinished && state.operations === 0 && sessions.get(sessionID) === state) {
+      sessions.delete(sessionID)
+    }
+  }
+
+  const serialize = async <T>(sessionID: string, state: SessionState, operation: () => Promise<T>): Promise<T> => {
+    const result = state.operations === 0
+      ? Promise.resolve(operation())
+      : state.tail.then(operation, operation)
+    state.operations += 1
+    state.tail = result.then(() => undefined, () => undefined)
+    try {
+      return await result
+    } finally {
+      state.operations -= 1
+    }
+  }
+
+  const callCoordinator = (operation: string, payload: JsonObject) => coordinator(operation, payload)
+    .catch(() => undefined)
+
+  return {
+    "command.execute.before": async (input, output) => {
+      if (!contractEnabled()) return
+      if (!isObject(input) || typeof input.command !== "string" || !COMMANDS.has(input.command)) return
+      const parsed = admission(input, output)
+      if (!parsed || !projectRoot || !fs.existsSync(COORDINATOR)) throw new Error(FIXED_BLOCK)
+      const state = sessionState(parsed.sessionID)
+      const terminalEpoch = state?.terminalEpoch
+      const invoke = () => callCoordinator("harness-before", {
+        schema_version: 1,
+        harness: "opencode",
+        command: parsed.command,
+        session_id: parsed.sessionID,
+        project_root: projectRoot,
+      })
+      let decision: JsonObject | undefined
+      try {
+        decision = state
+          ? await serialize(parsed.sessionID, state, invoke)
+          : await invoke()
+      } catch (error) {
+        if (state) forgetFinishedSession(parsed.sessionID, state)
+        throw error
+      }
+      if (decision?.schema_version !== 1 || (decision.decision !== "allow" && decision.decision !== "block")) {
+        if (state) forgetFinishedSession(parsed.sessionID, state)
+        throw new Error(FIXED_BLOCK)
+      }
+      if (decision.decision === "block") {
+        if (state) forgetFinishedSession(parsed.sessionID, state)
+        throw new Error(FIXED_BLOCK)
+      }
+      if (state && state.terminalEpoch === terminalEpoch) state.unfinished = true
+      else if (state) forgetFinishedSession(parsed.sessionID, state)
+    },
+    event: async ({ event }) => {
+      if (!contractEnabled() || !fs.existsSync(COORDINATOR)) return
+      const terminal = eventTerminal(event)
+      if (!terminal) return
+      const state = sessionState(terminal.sessionID)
+      if (state) {
+        state.unfinished = false
+        state.terminalEpoch += 1
+      }
+      const payload = {
+        schema_version: 1,
+        harness: "opencode",
+        session_id: terminal.sessionID,
+        outcome: terminal.outcome,
+      } as const
+      const invoke = () => terminalRequiresSync()
+        ? Promise.resolve(coordinatorSync("harness-terminal", payload))
+        : callCoordinator("harness-terminal", payload)
+      if (state) {
+        await serialize(terminal.sessionID, state, invoke)
+        forgetFinishedSession(terminal.sessionID, state)
+      } else await invoke()
+    },
+    dispose: async () => {
+      if (!contractEnabled() || !fs.existsSync(COORDINATOR)) return
+      const unfinished = [...sessions.entries()].filter(([, state]) => state.unfinished)
+      for (const [, state] of unfinished) {
+        state.unfinished = false
+        state.terminalEpoch += 1
+      }
+      for (let offset = 0; offset < unfinished.length; offset += DISPOSAL_BATCH_SIZE) {
+        const batch = unfinished.slice(offset, offset + DISPOSAL_BATCH_SIZE)
+        for (const [sessionID, state] of batch) {
+          await serialize(sessionID, state, () => callCoordinator("harness-terminal", {
+            schema_version: 1,
+            harness: "opencode",
+            session_id: sessionID,
+            outcome: "abandoned",
+          }))
+        }
+      }
+      for (const [sessionID, state] of unfinished) forgetFinishedSession(sessionID, state)
+    },
+  }
+}
+
+export const CapabilityCommandPlugin = Object.assign(capabilityCommandPlugin, {
+  contract: OPENCODE_CAPABILITY_CONTRACT,
+})

package/opencode/command/graphify.md

@@ -7,22 +7,21 @@ tools:
   task: true
 ---
 
-**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by OpenCode's command system. Using the Read tool on this file wastes tokens. Begin executing Step 1 immediately.**
 
 **graphify CLI:** the `graphify` subcommand is exposed by `gsd-tools` (on PATH). Invoke as `gsd-tools graphify …` as documented in this command and in `docs/CLI-TOOLS.md`. Other GSD queries use `gsd-tools <subcmd>` where a handler exists.
 
-## Step 0 -- Banner
+## Output heading
 
-**Before ANY tool calls**, display this banner:
-
-```
-GRAPHIFY
-```
-
-Then proceed to Step 1.
+Begin the final user-facing response with `GRAPHIFY`. Do not emit a standalone
+banner before owner I/O: in headless OpenCode, content-only output can end the
+turn before the command reaches its tools.
 
 ## Step 1 -- Config Gate
 
+**First action:** invoke the Read tool for `.planning/config.json`; do not emit
+text before this tool call.
+
 Check if graphify is enabled by reading `.planning/config.json` directly using the Read tool.
 
 **DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
@@ -49,7 +48,15 @@ Then run /graphify build to create the initial graph.
 
 ## Step 2 -- Parse Argument
 
-Parse `$ARGUMENTS` to determine the operation mode:
+The exact invocation argument is delimited here:
+
+```text
+<argument>$ARGUMENTS</argument>
+```
+
+Parse only the text between those markers to determine the operation mode. If
+the markers contain `status`, that is the status mode; do not treat it as an
+empty or unknown argument. Apply the same exact matching rule to every row:
 
 | Argument | Action |
 |----------|--------|
@@ -75,7 +82,8 @@ Modes:
 
 ### Step 2a -- Query
 
-Run:
+**Invoke the shell tool** with this exact command; do not print the command as
+the result and do not continue until the tool returns:
 
 ```bash
 gsd-tools graphify query <term>
@@ -91,7 +99,8 @@ Parse the JSON output and display results:
 
 ### Step 2b -- Status
 
-Run:
+**Invoke the shell tool** with this exact command; do not print the command as
+the result and do not continue until the tool returns:
 
 ```bash
 gsd-tools graphify status
@@ -105,7 +114,8 @@ Parse the JSON output and display:
 
 ### Step 2c -- Diff
 
-Run:
+**Invoke the shell tool** with this exact command; do not print the command as
+the result and do not continue until the tool returns:
 
 ```bash
 gsd-tools graphify diff
@@ -123,7 +133,8 @@ If no snapshot exists, suggest running `build` twice (first to create, second to
 
 ## Step 3 -- Build (Inline)
 
-Run:
+**Invoke the shell tool** with this exact command; do not print the command as
+the result and do not continue until the tool returns:
 
 ```bash
 gsd-tools graphify build [--force]