@bybrawe/opencode-loop 0.5.27 → 0.5.29

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/opencode2-loop-canary.mjs

@@ -0,0 +1,433 @@
+import assert from "node:assert/strict"
+import { createServer } from "node:http"
+import net from "node:net"
+import { execFileSync, spawn } from "node:child_process"
+import { mkdir, mkdtemp, 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 repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const LOOP_OBJECTIVE = "real OpenCode 2 loop canary"
+const EXPECTED_TURNS = 2
+const EXPECTED_COMMANDS = ["loop", "loop-pause", "loop-resume", "loop-stop", "loop-remove", "loop-clear"]
+const SERVER_USERNAME = "opencode"
+const SERVER_PASSWORD = "opencode-loop-v2-canary"
+
+function appendLog(current, chunk, limit = 100_000) {
+  return (current + String(chunk)).slice(-limit)
+}
+
+async function reservePort() {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+      if (!address || typeof address === "string") return reject(new Error("failed to reserve TCP port"))
+      server.close((error) => error ? reject(error) : resolve(address.port))
+    })
+  })
+}
+
+async function waitForTcp(port, child, logs, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) throw new Error(`OpenCode 2 server exited before ready.\n${logs()}`)
+    const connected = await new Promise((resolve) => {
+      const socket = net.createConnection({ host: "127.0.0.1", port })
+      socket.once("connect", () => { socket.destroy(); resolve(true) })
+      socket.once("error", () => resolve(false))
+      socket.setTimeout(500, () => { socket.destroy(); resolve(false) })
+    })
+    if (connected) return
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  throw new Error(`timed out waiting for OpenCode 2 server on ${port}\n${logs()}`)
+}
+
+async function stopProcess(child, timeoutMs = 5_000) {
+  if (!child || child.exitCode !== null) return
+  child.kill("SIGTERM")
+  await new Promise((resolve) => {
+    if (child.exitCode !== null) return resolve()
+    const timer = setTimeout(resolve, timeoutMs)
+    child.once("close", () => { clearTimeout(timer); resolve() })
+  })
+}
+
+async function waitFor(predicate, description, diagnostics, timeoutMs = 60_000) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (await predicate()) return
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  throw new Error(`timed out waiting for ${description}\n${await diagnostics()}`)
+}
+
+function contentText(content) {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return ""
+  return content.map((part) => typeof part?.text === "string" ? part.text : typeof part?.content === "string" ? part.content : "").join("\n")
+}
+
+function lastUserText(body) {
+  const messages = Array.isArray(body.messages) ? body.messages : []
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "user") return contentText(messages[index]?.content)
+  }
+  return ""
+}
+
+function streamHeaders(res) {
+  res.writeHead(200, {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+  })
+}
+
+function writeSse(res, value) {
+  res.write(`data: ${JSON.stringify(value)}\n\n`)
+}
+
+function streamText(res, content, sequence) {
+  const id = `chatcmpl-v2-loop-${sequence}`
+  const created = Math.floor(Date.now() / 1000)
+  streamHeaders(res)
+  writeSse(res, {
+    id,
+    object: "chat.completion.chunk",
+    created,
+    model: "canary",
+    choices: [{ index: 0, delta: { role: "assistant", content }, finish_reason: null }],
+  })
+  writeSse(res, {
+    id,
+    object: "chat.completion.chunk",
+    created,
+    model: "canary",
+    choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+    usage: { prompt_tokens: 30, completion_tokens: 4, total_tokens: 34 },
+  })
+  res.end("data: [DONE]\n\n")
+}
+
+function startProvider() {
+  const stats = { chatRequests: 0, loopRequests: 0, paths: [] }
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1")
+    stats.paths.push(`${req.method} ${url.pathname}`)
+    if (req.method === "GET" && url.pathname.endsWith("/models")) {
+      res.writeHead(200, { "content-type": "application/json" })
+      res.end(JSON.stringify({ object: "list", data: [{ id: "canary", object: "model", owned_by: "canary" }] }))
+      return
+    }
+    if (req.method !== "POST" || !url.pathname.endsWith("/chat/completions")) {
+      res.writeHead(404, { "content-type": "application/json" })
+      res.end(JSON.stringify({ error: { message: `unexpected endpoint: ${req.method} ${url.pathname}` } }))
+      return
+    }
+
+    let raw = ""
+    for await (const chunk of req) raw += String(chunk)
+    const body = raw ? JSON.parse(raw) : {}
+    stats.chatRequests += 1
+    const text = lastUserText(body)
+    if (text.includes("AUTONOMOUS OPENCODE LOOP ITERATION")) {
+      stats.loopRequests += 1
+      streamText(res, `V2_LOOP_TURN_${stats.loopRequests}`, stats.chatRequests)
+      return
+    }
+    streamText(res, "OK", stats.chatRequests)
+  })
+
+  return {
+    stats,
+    async listen() {
+      await new Promise((resolve, reject) => {
+        server.once("error", reject)
+        server.listen(0, "127.0.0.1", resolve)
+      })
+      const address = server.address()
+      if (!address || typeof address === "string") throw new Error("failed to start deterministic V2 provider")
+      return address.port
+    },
+    async close() {
+      await new Promise((resolve) => server.close(() => resolve()))
+    },
+  }
+}
+
+function bridgePluginSource() {
+  return `import { writeFile } from "node:fs/promises"
+
+export default {
+  id: "bybrawe.opencode-loop.v2.loop-canary-bridge",
+  async setup(ctx) {
+    const module = await import(process.env.OPENCODE_LOOP_V2_PLUGIN_URL)
+    const cleanup = await module.default.setup(ctx)
+    await writeFile(process.env.OPENCODE_LOOP_V2_MARKER, JSON.stringify({ activated: true }, null, 2), "utf8")
+    return async () => {
+      if (typeof cleanup === "function") await cleanup()
+    }
+  },
+}
+`
+}
+
+function commandNames(payload) {
+  const data = Array.isArray(payload?.data) ? payload.data : Array.isArray(payload) ? payload : []
+  return new Set(data.map((item) => item?.name).filter((name) => typeof name === "string"))
+}
+
+async function main() {
+  assert.equal(process.platform, "linux", "the real OpenCode 2 Loop canary is intentionally Ubuntu-only")
+
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "opencode-loop-v2-e2e-"))
+  const home = path.join(workspace, ".home")
+  const pluginDir = path.join(workspace, ".opencode", "plugins")
+  const marker = path.join(workspace, "v2-real-adapter-marker.json")
+  const provider = startProvider()
+  const providerPort = await provider.listen()
+  let server
+  let serverLog = ""
+  let apiPrefix = null
+  let latestCommands = new Set()
+  let sessionID = ""
+  let commandError = null
+
+  await Promise.all([
+    mkdir(pluginDir, { recursive: true }),
+    mkdir(path.join(home, ".config"), { recursive: true }),
+    mkdir(path.join(home, ".local", "share"), { recursive: true }),
+    mkdir(path.join(home, ".local", "state"), { recursive: true }),
+  ])
+
+  await writeFile(path.join(pluginDir, "opencode-loop-v2-real.js"), bridgePluginSource(), "utf8")
+  await writeFile(path.join(workspace, "opencode.json"), `${JSON.stringify({
+    $schema: "https://opencode.ai/config.json",
+    model: "canary/canary",
+    providers: {
+      canary: {
+        name: "Deterministic OpenCode 2 Loop Canary",
+        package: "@opencode-ai/ai/providers/openai-compatible",
+        settings: { baseURL: `http://127.0.0.1:${providerPort}/v1` },
+        models: {
+          canary: {
+            name: "Deterministic OpenCode 2 Loop Canary",
+            capabilities: { tools: true, input: ["text"], output: ["text"] },
+            limit: { context: 100000, output: 4096 },
+          },
+        },
+      },
+    },
+  }, null, 2)}\n`)
+
+  execFileSync("git", ["init", "--quiet", workspace], { stdio: "ignore" })
+  execFileSync("git", ["-C", workspace, "config", "user.email", "opencode-loop-ci@example.invalid"], { stdio: "ignore" })
+  execFileSync("git", ["-C", workspace, "config", "user.name", "OpenCode Loop CI"], { stdio: "ignore" })
+  execFileSync("git", ["-C", workspace, "add", "."], { stdio: "ignore" })
+  execFileSync("git", ["-C", workspace, "commit", "--quiet", "-m", "init"], { stdio: "ignore" })
+
+  const env = {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,
+    XDG_CONFIG_HOME: path.join(home, ".config"),
+    XDG_DATA_HOME: path.join(home, ".local", "share"),
+    XDG_STATE_HOME: path.join(home, ".local", "state"),
+    XDG_CACHE_HOME: path.join(home, ".cache"),
+    OPENCODE_LOOP_V2_PLUGIN_URL: pathToFileURL(path.join(repoRoot, "src", "source", "opencode2", "experimental.js")).href,
+    OPENCODE_LOOP_V2_MARKER: marker,
+    OPENCODE_SERVER_USERNAME: SERVER_USERNAME,
+    OPENCODE_SERVER_PASSWORD: SERVER_PASSWORD,
+    OPENCODE_DISABLE_AUTOUPDATE: "true",
+    OPENCODE_DISABLE_LSP_DOWNLOAD: "true",
+    CI: "true",
+  }
+
+  const diagnostics = async () => {
+    let state = "missing"
+    if (sessionID) {
+      try { state = await readFile(path.join(workspace, ".opencode", "opencode-loop", `${sessionID}.json`), "utf8") } catch {}
+    }
+    return [
+      `apiPrefix=${String(apiPrefix)}`,
+      `commands=${JSON.stringify([...latestCommands])}`,
+      `provider=${JSON.stringify(provider.stats)}`,
+      `sessionID=${sessionID || "none"}`,
+      `commandError=${String(commandError ?? "none")}`,
+      `state=${state}`,
+      `serverExit=${server?.exitCode}`,
+      `serverLog=${serverLog}`,
+    ].join("\n")
+  }
+
+  try {
+    const port = await reservePort()
+    server = spawn("opencode2", ["serve", "--hostname", "127.0.0.1", "--port", String(port)], {
+      cwd: workspace,
+      env,
+      windowsHide: true,
+    })
+    server.stdout?.on("data", (chunk) => { serverLog = appendLog(serverLog, chunk) })
+    server.stderr?.on("data", (chunk) => { serverLog = appendLog(serverLog, chunk) })
+    await waitForTcp(port, server, () => serverLog)
+
+    const baseURL = `http://127.0.0.1:${port}`
+    const authorization = `Basic ${Buffer.from(`${SERVER_USERNAME}:${SERVER_PASSWORD}`).toString("base64")}`
+    const request = async (pathname, init = {}, timeoutMs = 30_000) => {
+      const response = await fetch(`${baseURL}${pathname}`, {
+        ...init,
+        headers: {
+          "content-type": "application/json",
+          "x-opencode-directory": workspace,
+          authorization,
+          ...(init.headers ?? {}),
+        },
+        signal: init.signal ?? AbortSignal.timeout(timeoutMs),
+      })
+      const text = await response.text()
+      let body = null
+      if (text) {
+        try { body = JSON.parse(text) } catch { body = text }
+      }
+      return { ok: response.ok, status: response.status, body, text }
+    }
+
+    for (const prefix of ["/api", ""]) {
+      const deadline = Date.now() + 30_000
+      while (Date.now() < deadline) {
+        let response
+        try { response = await request(`${prefix}/command`, { method: "GET" }, 5_000) } catch {}
+        if (response?.ok) {
+          apiPrefix = prefix
+          break
+        }
+        if (response && ![404, 503].includes(response.status)) {
+          throw new Error(`command registry probe failed with HTTP ${response.status}: ${response.text}\n${await diagnostics()}`)
+        }
+        if (response?.status === 404) break
+        await new Promise((resolve) => setTimeout(resolve, 250))
+      }
+      if (apiPrefix !== null) break
+    }
+    assert.notEqual(apiPrefix, null, `OpenCode 2 command API never became ready\n${await diagnostics()}`)
+
+    await waitFor(async () => {
+      try { return Boolean(JSON.parse(await readFile(marker, "utf8"))?.activated) } catch { return false }
+    }, "experimental V2 plugin activation", diagnostics, 30_000)
+
+    await waitFor(async () => {
+      const response = await request(`${apiPrefix}/command`, { method: "GET" }, 5_000)
+      if (!response.ok) return false
+      latestCommands = commandNames(response.body)
+      return EXPECTED_COMMANDS.every((name) => latestCommands.has(name))
+    }, "plugin-registered Loop commands to enter the real V2 registry", diagnostics, 30_000)
+
+    const createdResponse = await request(`${apiPrefix}/session`, {
+      method: "POST",
+      body: JSON.stringify({ title: "OpenCode 2 Loop canary" }),
+    })
+    if (!createdResponse.ok) throw new Error(`session create failed: HTTP ${createdResponse.status} ${createdResponse.text}\n${await diagnostics()}`)
+    const session = createdResponse.body?.data ?? createdResponse.body
+    sessionID = String(session?.id ?? "")
+    assert.ok(sessionID, `OpenCode 2 did not create a session: ${createdResponse.text}\n${await diagnostics()}`)
+
+    const commandPromise = request(`${apiPrefix}/session/${encodeURIComponent(sessionID)}/command`, {
+      method: "POST",
+      body: JSON.stringify({ command: "loop", arguments: `0s --max-runs ${EXPECTED_TURNS} ${LOOP_OBJECTIVE}` }),
+    }, 120_000).catch((error) => {
+      commandError = error
+      return null
+    })
+
+    await waitFor(() => provider.stats.loopRequests >= EXPECTED_TURNS, `${EXPECTED_TURNS} autonomous OpenCode 2 Loop turns`, diagnostics, 90_000)
+    await new Promise((resolve) => setTimeout(resolve, 1_000))
+    assert.equal(provider.stats.loopRequests, EXPECTED_TURNS, `V2 Loop exceeded --max-runs ${EXPECTED_TURNS}\n${await diagnostics()}`)
+
+    const stateFile = path.join(workspace, ".opencode", "opencode-loop", `${sessionID}.json`)
+    const persisted = JSON.parse(await readFile(stateFile, "utf8"))
+    const loop = persisted.jobs?.find((job) => job.name === "default")
+    assert.ok(loop, `persisted V2 Loop job was missing\n${await diagnostics()}`)
+    assert.equal(loop.runCount, EXPECTED_TURNS)
+    assert.equal(loop.enabled, false)
+
+    const commandResponse = await commandPromise
+    if (commandError) throw commandError
+    assert.ok(commandResponse?.ok, `Loop command request failed: ${commandResponse?.status} ${commandResponse?.text}\n${await diagnostics()}`)
+    assert.equal(server.exitCode, null, `OpenCode 2 server exited during canary\n${await diagnostics()}`)
+
+    const readPersisted = async () => {
+      try { return JSON.parse(await readFile(stateFile, "utf8")) }
+      catch (error) {
+        if (error?.code === "ENOENT") return { jobs: [] }
+        throw error
+      }
+    }
+    const jobNamed = async (name) => (await readPersisted()).jobs?.find((job) => String(job?.name || "default") === name)
+    const sendControl = async (command, argumentsText = "") => {
+      const response = await request(`${apiPrefix}/session/${encodeURIComponent(sessionID)}/command`, {
+        method: "POST",
+        body: JSON.stringify({ command, arguments: argumentsText }),
+      }, 120_000)
+      if (!response.ok) throw new Error(`${command} failed: HTTP ${response.status} ${response.text}\n${await diagnostics()}`)
+      return response
+    }
+
+    await sendControl("loop-pause", "default")
+    await waitFor(async () => (await jobNamed("default"))?.paused === true, "real V2 loop-pause state mutation", diagnostics, 30_000)
+
+    await sendControl("loop-resume", "default")
+    await waitFor(async () => {
+      const job = await jobNamed("default")
+      return job?.paused === false && job?.lastRunAt === 0
+    }, "real V2 loop-resume state mutation", diagnostics, 30_000)
+
+    await sendControl("loop-stop", "default")
+    await waitFor(async () => !(await jobNamed("default")), "real V2 loop-stop removal", diagnostics, 30_000)
+
+    const beforeRemoveTurn = provider.stats.loopRequests
+    await sendControl("loop", "0s --max-runs 1 --name removable removable control lifecycle task")
+    await waitFor(() => provider.stats.loopRequests === beforeRemoveTurn + 1, "real V2 removable Loop turn", diagnostics, 60_000)
+    await waitFor(async () => {
+      const job = await jobNamed("removable")
+      return job?.runCount === 1 && job?.enabled === false
+    }, "real V2 removable Loop persisted completion", diagnostics, 30_000)
+    await sendControl("loop-remove", "removable")
+    await waitFor(async () => !(await jobNamed("removable")), "real V2 loop-remove removal", diagnostics, 30_000)
+
+    const beforeClearTurn = provider.stats.loopRequests
+    await sendControl("loop", "0s --max-runs 1 --name clearable clearable control lifecycle task")
+    await waitFor(() => provider.stats.loopRequests === beforeClearTurn + 1, "real V2 clearable Loop turn", diagnostics, 60_000)
+    await waitFor(async () => Boolean(await jobNamed("clearable")), "real V2 clearable Loop persistence", diagnostics, 30_000)
+    await sendControl("loop-clear")
+    await waitFor(async () => (await readPersisted()).jobs?.length === 0, "real V2 loop-clear state removal", diagnostics, 30_000)
+
+    assert.equal(provider.stats.loopRequests, EXPECTED_TURNS + 2, `control lifecycle should add exactly two autonomous Loop turns\n${await diagnostics()}`)
+    assert.equal(server.exitCode, null, `OpenCode 2 server exited during control lifecycle canary\n${await diagnostics()}`)
+
+    console.log(JSON.stringify({
+      ok: true,
+      apiPrefix,
+      sessionID,
+      registeredCommands: [...latestCommands],
+      loopRequests: provider.stats.loopRequests,
+      chatRequests: provider.stats.chatRequests,
+      initialRunCount: loop.runCount,
+      initialEnabled: loop.enabled,
+      controlsVerified: ["loop-pause", "loop-resume", "loop-stop", "loop-remove", "loop-clear"],
+    }, null, 2))
+  } finally {
+    await stopProcess(server)
+    await provider.close().catch(() => undefined)
+    await rm(workspace, { recursive: true, force: true }).catch(() => undefined)
+  }
+}
+
+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")