@bybrawe/opencode-loop 0.5.27 → 0.5.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.27",
+  "version": "0.5.28",
   "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: heartbeat scheduler, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
   "type": "module",
   "main": "src/index.js",
@@ -18,8 +18,11 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "check": "node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/loopd-test.mjs && node --check scripts/smoke-test.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs",
-    "test": "node scripts/install-test.mjs && node scripts/loopd-test.mjs && node scripts/smoke-test.mjs && node scripts/comprehensive-test.mjs",
+    "build:plugin": "bun build src/source/v1.js --outfile=src/index.js --target=bun --format=esm --external=@opencode-ai/plugin/tool",
+    "build:plugin:npm": "npm run build:plugin",
+    "prepack": "node --check src/index.js",
+    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/state.js && node --check src/source/core/jobs.js && node --check src/source/core/process.js && node --check src/source/opencode/sdk.js && node --check src/source/opencode/session-context.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/loopd-test.mjs && node --check scripts/smoke-test.mjs && node --check scripts/host-adapter-contract-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs",
+    "test": "node scripts/install-test.mjs && node scripts/loopd-test.mjs && node scripts/smoke-test.mjs && node scripts/host-adapter-contract-test.mjs && node scripts/comprehensive-watchdog.mjs",
     "canary:host": "node scripts/host-loop-canary.mjs",
     "install:global": "node scripts/install-node.mjs",
     "pack:zip": "node scripts/make-zip.mjs"

package/scripts/comprehensive-test.mjs

@@ -6,6 +6,18 @@ import path from "node:path"
 import OpenCodeLoopPlugin from "../src/index.js"
 
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+async function waitForValue(read, timeoutMs = 1_000, intervalMs = 10) {
+  const deadline = Date.now() + timeoutMs
+  let value
+  while (Date.now() < deadline) {
+    value = await read()
+    if (value) return value
+    await delay(intervalMs)
+  }
+  return await read()
+}
+
 let harnessNumber = 0
 
 async function createHarness(options = {}) {
@@ -405,9 +417,11 @@ async function testNativeCompactionLifecycleAndFallback() {
     await h.hooks["experimental.session.compacting"]({ sessionID: h.sessionID }, compactOutput)
     assert.deepEqual(compactOutput, { context: [], prompt: undefined }, "loop lifecycle tracking must not rewrite OpenCode's compaction prompt")
     await h.hooks.event({ event: { type: "session.compacted", properties: { sessionID: h.sessionID } } })
-    await delay(20)
-    const state = await h.readState()
-    assert.ok(state.jobs[0].lastFinishedAt > 0, "session.compacted must finalize an explicit compact job without waiting for stale status recovery")
+    const state = await waitForValue(async () => {
+      const candidate = await h.readState()
+      return candidate.jobs[0]?.lastFinishedAt > 0 ? candidate : undefined
+    })
+    assert.ok(state?.jobs[0]?.lastFinishedAt > 0, "session.compacted must finalize an explicit compact job without waiting for stale status recovery")
   } finally {
     await h.cleanup()
   }
@@ -750,4 +764,4 @@ await testWindowsStateRenameRetriesBeforeFallback()
 await testStateReadRetriesTransientPartialJson()
 await testStateRebasePreservesConcurrentPause()
 
-console.log("OpenCode Loop comprehensive test passed")
+console.log("OpenCode Loop comprehensive test passed")

package/scripts/comprehensive-watchdog.mjs

@@ -0,0 +1,32 @@
+import { promises as fs } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const scriptsDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptsDir, "..")
+const sourcePath = path.join(scriptsDir, "comprehensive-test.mjs")
+const timeoutMs = Math.max(5_000, Number(process.env.OPENCODE_LOOP_COMPREHENSIVE_TIMEOUT_MS) || 60_000)
+const tempPath = path.join(os.tmpdir(), `opencode-loop-comprehensive-watchdog-${process.pid}-${Date.now()}.mjs`)
+
+const source = await fs.readFile(sourcePath, "utf8")
+const pluginURL = pathToFileURL(path.join(rootDir, "src", "index.js")).href
+let instrumented = source.replace('import OpenCodeLoopPlugin from "../src/index.js"', `import OpenCodeLoopPlugin from ${JSON.stringify(pluginURL)}`)
+instrumented = instrumented.replace(
+  /^await (test[A-Za-z0-9_]+)\(\)$/gm,
+  'globalThis.__opencodeLoopActiveCase = "$1"; await $1(); globalThis.__opencodeLoopActiveCase = undefined',
+)
+if (instrumented === source) throw new Error("failed to instrument comprehensive test")
+
+await fs.writeFile(tempPath, instrumented, "utf8")
+const watchdog = setTimeout(() => {
+  const active = globalThis.__opencodeLoopActiveCase
+  throw new Error(`OpenCode Loop comprehensive test timed out after ${timeoutMs}ms${active ? ` while running ${active}` : ""}`)
+}, timeoutMs)
+
+try {
+  await import(`${pathToFileURL(tempPath).href}?run=${Date.now()}`)
+} finally {
+  clearTimeout(watchdog)
+  try { await fs.rm(tempPath, { force: true }) } catch {}
+}

package/scripts/host-adapter-contract-test.mjs

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict"
+import { createOpenCodeHostAdapter } from "../src/source/opencode/adapter.js"
+import {
+  activeRunCompletionFromMessages,
+  compactSession,
+  compactTuiCommandName,
+  executeTuiCommand,
+  orderedSessionMessages,
+  readRecentSessionMessages,
+  resolveCompactionModel,
+} from "../src/source/opencode/host.js"
+import {
+  deleteSessionExecutionContext,
+  getSessionExecutionContext,
+} from "../src/source/opencode/session-context.js"
+
+function messagesClient(messages) {
+  return { session: { messages: async () => ({ data: structuredClone(messages) }) } }
+}
+
+assert.equal(compactTuiCommandName("/compact"), "session_compact")
+assert.equal(compactTuiCommandName("summarize"), "session_compact")
+assert.equal(compactTuiCommandName("other"), undefined)
+
+{
+  const calls = []
+  const client = { tui: { executeCommand: async (args) => {
+    calls.push(args)
+    if (args?.body) return { error: { message: "body shape rejected" } }
+    return { data: args.command }
+  } } }
+  assert.equal(await executeTuiCommand(client, "session_compact"), "session_compact")
+  assert.deepEqual(calls, [
+    { body: { command: "session_compact" } },
+    { command: "session_compact" },
+  ])
+}
+
+{
+  const calls = []
+  const client = { session: { messages: async (args) => {
+    calls.push(args)
+    if (args?.path?.id) throw new Error("id shape rejected")
+    return { data: [{ info: { id: "m1", role: "assistant" } }] }
+  } } }
+  const result = await readRecentSessionMessages(client, "ses_messages", "/tmp/project", 7)
+  assert.equal(result[0].info.id, "m1")
+  assert.equal(calls.length, 2)
+}
+
+{
+  const ordered = orderedSessionMessages([
+    { info: { id: "b", time: { created: 20 } } },
+    { info: { id: "a", time: { created: 10 } } },
+    { info: { id: "c", time: { created: 20 } } },
+  ])
+  assert.deepEqual(ordered.map((item) => item.info.id), ["a", "b", "c"])
+
+  assert.equal(await activeRunCompletionFromMessages("/tmp", {}, "missing", { startedAt: 100 }), "unknown")
+  assert.equal(await activeRunCompletionFromMessages(
+    "/tmp", messagesClient([{ info: { role: "assistant", time: { created: 50, completed: 90 } } }]), "old", { startedAt: 100 },
+  ), "incomplete")
+  assert.equal(await activeRunCompletionFromMessages(
+    "/tmp", messagesClient([{ info: { role: "assistant", time: { created: 110, completed: 120 } } }]), "done", { startedAt: 100 },
+  ), "completed")
+}
+
+{
+  const sessionID = "ses_message_model_contract"
+  deleteSessionExecutionContext(sessionID)
+  const client = messagesClient([
+    { info: { role: "assistant", time: { created: 10 }, model: { providerID: "old", modelID: "old" } } },
+    { info: { role: "assistant", time: { created: 20 }, model: { providerID: "provider", modelID: "model" } } },
+  ])
+  assert.deepEqual(await resolveCompactionModel("/tmp", client, sessionID), { providerID: "provider", modelID: "model" })
+  assert.deepEqual(getSessionExecutionContext(sessionID)?.model, { providerID: "provider", modelID: "model" })
+  deleteSessionExecutionContext(sessionID)
+}
+
+{
+  const tuiCalls = []
+  const client = {
+    app: { log: async () => ({ data: true }) },
+    tui: { executeCommand: async (args) => {
+      const command = args?.body?.command || args?.command
+      tuiCalls.push(command)
+      if (command === "session.compact") return { error: { message: "unsupported" } }
+      return { data: true }
+    } },
+  }
+  assert.equal(await compactSession("/tmp", client, "ses_tui"), true)
+  assert.ok(tuiCalls.includes("session.compact"))
+  assert.ok(tuiCalls.includes("session_compact"))
+}
+
+{
+  const summaries = []
+  const client = {
+    app: { log: async () => ({ data: true }) },
+    tui: { showToast: async () => ({ data: true }) },
+    session: { summarize: async (args) => { summaries.push(args); return { data: true } } },
+  }
+  assert.equal(await compactSession("/tmp", client, "ses_summary", "provider/model"), true)
+  assert.deepEqual(summaries[0], {
+    path: { id: "ses_summary" },
+    body: { providerID: "provider", modelID: "model", auto: false },
+  })
+}
+
+{
+  const calls = []
+  const client = {
+    app: { log: async (args) => { calls.push(["log", args]); return { data: true } } },
+    tui: {
+      executeCommand: async (args) => { calls.push(["command", args]); return { data: true } },
+      showToast: async (args) => { calls.push(["toast", args]); return { data: true } },
+    },
+    session: {
+      messages: async (args) => {
+        calls.push(["messages", args])
+        return { data: [{ info: { role: "assistant", time: { created: 10, completed: 20 } } }] }
+      },
+    },
+  }
+  const adapter = createOpenCodeHostAdapter(client, "/bound/project")
+  assert.equal(Object.isFrozen(adapter), true)
+  assert.deepEqual(Object.keys(adapter).sort(), [
+    "activeRunCompletion",
+    "compactSession",
+    "executeTuiCommand",
+    "log",
+    "readRecentMessages",
+    "resolveCompactionModel",
+    "toast",
+  ])
+  await adapter.executeTuiCommand("session_compact")
+  await adapter.readRecentMessages("ses_adapter", 7)
+  assert.equal(await adapter.activeRunCompletion("ses_adapter", { startedAt: 5 }), "completed")
+  assert.deepEqual(await adapter.resolveCompactionModel("ses_adapter", "provider/model"), { providerID: "provider", modelID: "model" })
+  await adapter.log("info", "adapter log")
+  await adapter.toast("adapter toast", "warning")
+  const messageCall = calls.find(([kind]) => kind === "messages")?.[1]
+  assert.equal(messageCall?.query?.directory, "/bound/project")
+  assert.equal(messageCall?.query?.limit, 7)
+}
+
+console.log("OpenCode host adapter contract test passed")

package/scripts/host-bridge-parity-test.mjs

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict"
+import { promises as fs } from "node:fs"
+
+const legacy = await fs.readFile("src/source/legacy-v1.js", "utf8")
+const host = await fs.readFile("src/source/opencode/host.js", "utf8")
+
+const legacyStart = legacy.indexOf("function fireSdk(")
+const legacyEnd = legacy.indexOf("function guardLoopOwnedUserMessage(")
+const hostStart = host.indexOf("export function fireSdk(")
+assert.ok(legacyStart >= 0 && legacyEnd > legacyStart, "legacy host bridge block not found")
+assert.ok(hostStart >= 0, "host bridge module block not found")
+
+const normalize = (text) => text
+  .replace(/\bexport\s+(?=(?:async\s+)?function\b)/g, "")
+  .replace(/\r\n/g, "\n")
+  .trim()
+
+const legacyBlock = normalize(legacy.slice(legacyStart, legacyEnd))
+const hostBlock = normalize(host.slice(hostStart))
+assert.equal(hostBlock, legacyBlock, "OpenCode host bridge drifted from the stable V1 implementation")
+
+console.log("host bridge parity test passed")

package/scripts/host-loop-canary.mjs

@@ -213,6 +213,20 @@ async function waitFor(predicate, description, diagnostics, timeoutMs = 45_000)
   throw new Error(`timed out waiting for ${description}\n${diagnostics()}`)
 }
 
+function isFetchTimeout(error) {
+  return error?.name === "TimeoutError" || /aborted due to timeout/i.test(String(error?.message ?? error))
+}
+
+async function bootstrapSessions(api, diagnostics) {
+  try {
+    return await api("/session", { method: "GET", signal: AbortSignal.timeout(30_000) })
+  } catch (error) {
+    if (!isFetchTimeout(error)) throw error
+    console.error(`OpenCode session API was not ready after 30s; retrying once.\n${diagnostics()}`)
+    return await api("/session", { method: "GET", signal: AbortSignal.timeout(45_000) })
+  }
+}
+
 async function main() {
   const workspace = await mkdtemp(path.join(os.tmpdir(), "opencode-loop-host-canary-"))
   const home = path.join(workspace, ".home")
@@ -286,7 +300,7 @@ async function main() {
       try { return JSON.parse(text) } catch { return text }
     }
 
-    const sessionsBefore = await api("/session", { method: "GET", signal: AbortSignal.timeout(45_000) })
+    const sessionsBefore = await bootstrapSessions(api, () => `server log:\n${serverLog}`)
     assert.ok(Array.isArray(sessionsBefore?.data ?? sessionsBefore), "GET /session bootstrap did not return an array")
     const createdPayload = await api("/session", { method: "POST", body: JSON.stringify({ title: "opencode-loop host canary" }) })
     const session = createdPayload?.data ?? createdPayload
@@ -340,4 +354,4 @@ async function main() {
 main().catch((error) => {
   console.error(error?.stack || error)
   process.exitCode = 1
-})
+})

package/scripts/opencode2-host-canary.mjs

@@ -0,0 +1,194 @@
+import { spawnSync } from "node:child_process"
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const pluginID = "bybrawe.opencode-loop.v2.experimental"
+const sentinelID = "bybrawe.opencode-loop.v2-canary-sentinel"
+
+function run(command, args, { cwd, env, allowFailure = false, timeout = 60_000 } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024,
+    timeout,
+    windowsHide: true,
+  })
+  if (result.error) throw result.error
+  if (!allowFailure && result.status !== 0) {
+    throw new Error([
+      `command failed (${result.status}): ${command} ${args.join(" ")}`,
+      String(result.stdout ?? ""),
+      String(result.stderr ?? ""),
+    ].filter(Boolean).join("\n"))
+  }
+  return result
+}
+
+function output(result) {
+  return `${String(result.stdout ?? "")}\n${String(result.stderr ?? "")}`.trim()
+}
+
+function parseJSONOutput(result, label) {
+  const text = String(result.stdout ?? "").trim()
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${label} did not return JSON on stdout.\nstdout:\n${text}\nstderr:\n${String(result.stderr ?? "")}`)
+  }
+}
+
+function collectPluginIDs(value) {
+  if (Array.isArray(value)) return value.flatMap(collectPluginIDs)
+  if (typeof value === "string") return [value]
+  if (!value || typeof value !== "object") return []
+  const direct = [value.id, value.pluginID, value.name].filter((item) => typeof item === "string")
+  const nested = [value.data, value.plugin, value.plugins, value.items].flatMap((item) => collectPluginIDs(item))
+  return [...direct, ...nested]
+}
+
+function uniquePluginIDs(value) {
+  return [...new Set(collectPluginIDs(value))]
+}
+
+async function failureLog(env) {
+  const candidates = [
+    path.join(env.XDG_DATA_HOME, "opencode", "log", "opencode.log"),
+    path.join(env.XDG_STATE_HOME, "opencode", "log", "opencode.log"),
+  ]
+  for (const file of candidates) {
+    try {
+      const raw = await readFile(file, "utf8")
+      return raw.slice(-30_000)
+    } catch {}
+  }
+  return ""
+}
+
+async function main() {
+  const temp = await mkdtemp(path.join(os.tmpdir(), "opencode-loop-v2-host-"))
+  const project = path.join(temp, "project")
+  const home = path.join(temp, "home")
+  const config = path.join(home, ".config")
+  const data = path.join(home, ".local", "share")
+  const state = path.join(home, ".local", "state")
+  const pluginDirectory = path.join(project, ".opencode", "plugins")
+  const pluginFile = path.join(root, "src", "source", "opencode2", "experimental.js")
+  const adapterBridge = path.join(pluginDirectory, "opencode-loop-v2-canary.js")
+  const sentinelFile = path.join(pluginDirectory, "opencode-loop-v2-sentinel.js")
+  const sentinelURL = pathToFileURL(sentinelFile).href
+  const adapterURL = pathToFileURL(adapterBridge).href
+
+  await Promise.all([
+    mkdir(pluginDirectory, { recursive: true }),
+    mkdir(config, { recursive: true }),
+    mkdir(data, { recursive: true }),
+    mkdir(state, { recursive: true }),
+  ])
+
+  await writeFile(sentinelFile, `export default { id: ${JSON.stringify(sentinelID)}, server: async () => ({ id: ${JSON.stringify(sentinelID)} }) }\n`)
+  await writeFile(adapterBridge, `export { default } from ${JSON.stringify(pathToFileURL(pluginFile).href)}\n`)
+  await writeFile(path.join(project, "README.md"), "# OpenCode Loop V2 host canary\n")
+  await writeFile(path.join(project, "opencode.json"), `${JSON.stringify({
+    $schema: "https://opencode.ai/config.json",
+    plugin: [
+      "./.opencode/plugins/opencode-loop-v2-sentinel.js",
+      "./.opencode/plugins/opencode-loop-v2-canary.js",
+    ],
+  }, null, 2)}\n`)
+
+  const env = {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,
+    XDG_CONFIG_HOME: config,
+    XDG_DATA_HOME: data,
+    XDG_STATE_HOME: state,
+    OPENCODE_DB: path.join(data, "opencode", "opencode-loop-v2-canary.db"),
+    OPENCODE_LOG_LEVEL: "DEBUG",
+    OPENCODE_CONFIG_CONTENT: JSON.stringify({ plugin: [sentinelURL, adapterURL] }),
+    CI: "true",
+  }
+
+  run("git", ["init", "-q"], { cwd: project, env })
+  run("git", ["config", "user.name", "OpenCode Loop Canary"], { cwd: project, env })
+  run("git", ["config", "user.email", "opencode-loop-canary@example.invalid"], { cwd: project, env })
+  run("git", ["add", "."], { cwd: project, env })
+  run("git", ["commit", "-q", "-m", "initialize canary workspace"], { cwd: project, env })
+
+  try {
+    run("opencode2", ["service", "stop"], { cwd: project, env, allowFailure: true, timeout: 15_000 })
+
+    const version = output(run("opencode2", ["--version"], { cwd: project, env, timeout: 30_000 }))
+    if (!version) throw new Error("opencode2 --version returned no output")
+
+    const health = output(run("opencode2", ["api", "get", "/api/health"], { cwd: project, env }))
+    if (!health) throw new Error("OpenCode 2 health API returned no output")
+
+    const plainPluginResult = run("opencode2", ["api", "get", "/api/plugin"], { cwd: project, env })
+    const plainResponse = parseJSONOutput(plainPluginResult, "GET /api/plugin from project cwd")
+    const plainIDs = uniquePluginIDs(plainResponse)
+
+    const pluginPath = `/api/plugin?location%5Bdirectory%5D=${encodeURIComponent(project)}`
+    const scopedPluginResult = run("opencode2", ["api", "get", pluginPath], { cwd: project, env })
+    const scopedResponse = parseJSONOutput(scopedPluginResult, "GET /api/plugin at project Location")
+
+    if (scopedResponse?._tag) {
+      throw new Error(`project-scoped /api/plugin rejected the Location: ${JSON.stringify(scopedResponse)}`)
+    }
+    if (scopedResponse?.location?.directory !== project) {
+      throw new Error(`OpenCode 2 resolved the wrong Location: expected ${project}, got ${String(scopedResponse?.location?.directory)}`)
+    }
+
+    const scopedIDs = uniquePluginIDs(scopedResponse)
+    const ids = [...new Set([...plainIDs, ...scopedIDs])]
+    if (!ids.includes(sentinelID)) {
+      throw new Error([
+        `OpenCode 2 did not activate the current-loader sentinel. Active IDs: ${JSON.stringify(ids)}`,
+        `Plain /api/plugin IDs: ${JSON.stringify(plainIDs)}`,
+        `Scoped /api/plugin IDs: ${JSON.stringify(scopedIDs)}`,
+        `Plain response: ${String(plainPluginResult.stdout ?? "")}`,
+        `Scoped response: ${String(scopedPluginResult.stdout ?? "")}`,
+      ].join("\n"))
+    }
+    if (!ids.includes(pluginID)) {
+      throw new Error([
+        `OpenCode 2 activated the current-loader sentinel but not ${pluginID}. Active IDs: ${JSON.stringify(ids)}`,
+        `Plain /api/plugin IDs: ${JSON.stringify(plainIDs)}`,
+        `Scoped /api/plugin IDs: ${JSON.stringify(scopedIDs)}`,
+        `Plain response: ${String(plainPluginResult.stdout ?? "")}`,
+        `Scoped response: ${String(scopedPluginResult.stdout ?? "")}`,
+      ].join("\n"))
+    }
+
+    console.log(JSON.stringify({
+      ok: true,
+      platform: process.platform,
+      node: process.version,
+      opencode2Version: version,
+      health,
+      projectDirectory: scopedResponse.location.directory,
+      sentinelID,
+      pluginID,
+      plainPluginIDs: plainIDs,
+      scopedPluginIDs: scopedIDs,
+      activePluginIDs: ids,
+    }, null, 2))
+  } catch (error) {
+    const logs = await failureLog(env)
+    if (logs) console.error(`OpenCode 2 server log tail:\n${logs}`)
+    throw error
+  } finally {
+    run("opencode2", ["service", "stop"], { cwd: project, env, allowFailure: true, timeout: 15_000 })
+    await rm(temp, { recursive: true, force: true })
+  }
+}
+
+main().catch((error) => {
+  console.error(error?.stack || error)
+  process.exitCode = 1
+})

package/scripts/runtime-contract-test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict"
+import { createSessionRuntimeManager } from "../src/source/runtime/session-manager.js"
+import { createSessionRegistry } from "../src/source/runtime/session-registry.js"
+
+let clock = 1000
+const registry = createSessionRegistry({ now: () => clock, staleAfterMs: 100 })
+const first = {}
+const second = {}
+
+registry.observeExternal("ses_a", first)
+clock = 1050
+assert.equal(registry.peek("ses_a").seenAt, 1000)
+assert.equal(registry.entries()[0].seenAt, 1000)
+assert.deepEqual(registry.pruneStale(), [])
+
+registry.observeExternal("ses_a", first)
+assert.equal(registry.peek("ses_a").seenAt, 1050)
+clock = 1060
+registry.observeExternal("ses_a", second)
+assert.equal(registry.remove("ses_a", first), false)
+assert.equal(registry.peek("ses_a").runtime, second)
+
+clock = 1159
+assert.deepEqual(registry.pruneStale(), [])
+clock = 1160
+assert.deepEqual(registry.pruneStale(), ["ses_a"])
+assert.equal(registry.peek("ses_a"), undefined)
+
+{
+  const factoryCalls = []
+  const timerAPI = {}
+  const manager = createSessionRuntimeManager({
+    timerAPI,
+    runtimeFactory({ sessionID, timerAPI: injectedTimerAPI }) {
+      let active = true
+      const runtime = {
+        sessionID,
+        scope: { isActive: () => active },
+        dispose() { active = false; return true },
+      }
+      factoryCalls.push({ injectedTimerAPI, runtime })
+      return runtime
+    },
+  })
+
+  assert.throws(() => manager.observeExternal("   "), /session ID/)
+  assert.equal(factoryCalls.length, 0)
+  const runtime = manager.observeExternal("  ses_custom  ")
+  assert.equal(runtime.sessionID, "ses_custom")
+  assert.equal(factoryCalls[0].injectedTimerAPI, timerAPI)
+  assert.equal(manager.observeExternal("ses_custom"), runtime)
+  assert.equal(factoryCalls.length, 1)
+  runtime.dispose()
+  assert.notEqual(manager.observeExternal("ses_custom"), runtime)
+  assert.equal(factoryCalls.length, 2)
+  assert.equal(manager.dispose(), true)
+}
+
+console.log("OpenCode runtime contract test passed")

package/scripts/runtime-event-test.mjs

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict"
+import { normalizeOpenCodeEvent } from "../src/source/runtime/events.js"
+
+assert.deepEqual(
+  normalizeOpenCodeEvent({ type: "session.idle", properties: { sessionID: "ses_idle" } }),
+  { kind: "session", action: "idle", sessionID: "ses_idle", directory: undefined },
+)
+
+assert.deepEqual(
+  normalizeOpenCodeEvent({
+    directory: "/workspace",
+    payload: { type: "session.status", properties: { sessionID: "ses_busy", status: { type: "busy" } } },
+  }),
+  { kind: "session", action: "status", sessionID: "ses_busy", directory: "/workspace", status: "busy" },
+)
+
+assert.deepEqual(
+  normalizeOpenCodeEvent({
+    type: "session.created",
+    properties: { info: { id: "ses_child", directory: "/project", parentID: "ses_parent" } },
+  }),
+  { kind: "session", action: "created", sessionID: "ses_child", directory: "/project", parentID: "ses_parent" },
+)
+
+assert.deepEqual(
+  normalizeOpenCodeEvent({
+    directory: "/workspace",
+    payload: {
+      type: "message.updated",
+      properties: {
+        info: {
+          id: "msg_done",
+          sessionID: "ses_message",
+          role: "assistant",
+          time: { created: 10, completed: 20 },
+          finish: "stop",
+        },
+      },
+    },
+  }),
+  {
+    kind: "message",
+    action: "updated",
+    sessionID: "ses_message",
+    directory: "/workspace",
+    messageID: "msg_done",
+    role: "assistant",
+    completedAt: 20,
+    finish: "stop",
+  },
+)
+
+assert.deepEqual(
+  normalizeOpenCodeEvent({
+    type: "command.executed",
+    properties: { name: "loop-status", sessionID: "ses_command", arguments: "--json", messageID: "msg_command" },
+  }),
+  {
+    kind: "command",
+    action: "executed",
+    sessionID: "ses_command",
+    directory: undefined,
+    name: "loop-status",
+    arguments: "--json",
+    messageID: "msg_command",
+  },
+)
+
+assert.deepEqual(
+  normalizeOpenCodeEvent({ type: "server.instance.disposed", properties: { directory: "/old" } }),
+  { kind: "server", action: "disposed", directory: "/old" },
+)
+
+assert.equal(normalizeOpenCodeEvent({ type: "session.idle", properties: {} }), undefined)
+assert.equal(normalizeOpenCodeEvent({ payload: { properties: {} } }), undefined)
+assert.equal(normalizeOpenCodeEvent({ type: "file.edited", properties: { file: "x.txt" } }), undefined)
+
+console.log("OpenCode runtime event normalization test passed")