@bybrawe/opencode-loop 0.5.30 → 0.5.31

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.31
+
+- Add best-effort experimental OpenCode 2 runtime logging in the existing JSON-lines `loop.log` format, tagged with `v2: true`, plus experimental `/loop-logs` diagnostics for recent V2 records. Logging remains non-critical and does not change the stable OpenCode 1.x support claim.
+- Keep an already-installed `@bybrawe/opencode-goal` companion current when Loop is installed/updated by delegating to Goals' own `@latest` installer. Add `--with-goals` for an explicit combined install and `--loop-only` to suppress companion network work; Loop uninstall never removes Goals.
+- Add deterministic cross-platform companion-installer coverage for package/local/managed-command detection, JSONC comment false positives, opt-out, explicit failure semantics, help output, and best-effort automatic refresh behavior.
+- Keep release metadata internally consistent by synchronizing the package-lock root `bin` map with `package.json` while preparing releases.
+
 ## 0.5.30
 
 - Harden npm publishing so a one-shot release publishes the immutable trigger SHA, verifies that commit belongs to `main`, serializes releases, confirms the package is readable from npm, and tags exactly the published snapshot.

package/README.md

@@ -4,7 +4,7 @@
 
 OpenCode Loop adds `/loop`, scheduled prompt/command/shell jobs, compact scheduling, safe long-running continuation helpers, and the `opencode-loopd` background daemon.
 
-> **Current release: `0.5.30`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
+> **Current release: `0.5.31`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
 
 ## Install or update
 
@@ -16,7 +16,21 @@ Choose either installation method below.
 npx -y @bybrawe/opencode-loop@latest
 ```
 
-Run the same command again whenever you want to update.
+Run the same command again whenever you want to update. If **OpenCode Goals is already installed**, a normal Loop install/update also makes a best-effort call to the official `@bybrawe/opencode-goal@latest` installer so the companion Goal plugin does not silently remain on an older release.
+
+Install Loop and Goals together from scratch with:
+
+```bash
+npx -y @bybrawe/opencode-loop@latest --with-goals
+```
+
+Update/install only Loop and skip all Goals companion network work with:
+
+```bash
+npx -y @bybrawe/opencode-loop@latest --loop-only
+```
+
+`--with-goals` is explicit and fails if the requested Goals install/update fails. The automatic refresh of an already-installed Goals companion is best-effort: Loop still finishes its own update and prints a retry command if the companion registry/install step is temporarily unavailable.
 
 ### Option 2 — install with npm
 
@@ -34,6 +48,12 @@ npm install -g @bybrawe/opencode-loop@latest
 opencode-loop
 ```
 
+If you want the global Loop installer to install Goals too, run:
+
+```bash
+opencode-loop --with-goals
+```
+
 `npm install @bybrawe/opencode-loop` by itself only adds the Node package to the current project. For a normal OpenCode installation, use the global npm method above or the recommended `npx` installer.
 
 The installer:
@@ -42,7 +62,9 @@ The installer:
 - installs the `/loop-*` slash-command definitions;
 - installs the tool-denied `opencode-loop-local` command agent;
 - keeps an existing npm plugin entry pinned to the installer’s exact version to avoid stale OpenCode package-cache resolution;
-- removes duplicate old local Loop plugin copies when the package entry is authoritative.
+- removes duplicate old local Loop plugin copies when the package entry is authoritative;
+- refreshes OpenCode Goals through **Goals' own official installer** when an existing managed Goals installation is detected;
+- can explicitly install both packages with `--with-goals`, or skip companion network work with `--loop-only`.
 
 Then **fully restart OpenCode** and verify:
 
@@ -51,6 +73,12 @@ Then **fully restart OpenCode** and verify:
 /loop-doctor
 ```
 
+If Goals is installed too, also verify:
+
+```text
+/goal status
+```
+
 ### Uninstall
 
 If you use the `npx` installer:
@@ -68,7 +96,7 @@ npm uninstall -g @bybrawe/opencode-loop
 
 Run `opencode-loop --uninstall` before removing the global npm package so it can clean its OpenCode registrations and managed command files.
 
-Uninstall removes known OpenCode Loop package registrations, local plugin files, `/loop-*` command markdown files, and the Loop local command agent while preserving unrelated OpenCode configuration.
+Uninstall removes known OpenCode Loop package registrations, local plugin files, `/loop-*` command markdown files, and the Loop local command agent while preserving unrelated OpenCode configuration. It **does not uninstall OpenCode Goals**; Goals remains separately managed by its own installer.
 
 Project Loop state is intentionally preserved under:
 
@@ -142,7 +170,13 @@ OpenCode Loop still includes the older **experimental** `/loop-goal` workflow. I
 
 For durable Goal Contracts, host-owned evidence, semantic verification, native Todo coordination, revision isolation, false-completion protection, restart recovery, Goal audit, budgets, and ordered Goals, install **OpenCode Goals**.
 
-Recommended one-command installer:
+Convenient combined installer from Loop:
+
+```bash
+npx -y @bybrawe/opencode-loop@latest --with-goals
+```
+
+Or install Goals directly with its standalone installer:
 
 ```bash
 npx -y @bybrawe/opencode-goal@latest
@@ -177,21 +211,21 @@ Do **not** run Loop’s `/loop-goal` and OpenCode Goals `/goal` against the same
 
 Likewise, avoid leaving a prompt-producing `/loop ...` job continuously injecting agent turns into a session while an OpenCode Goal is actively continuing. Use separate sessions or pause/remove that prompt loop until the Goal is done. Scheduled shell/command jobs should also be chosen carefully so they do not race files or verification.
 
-Install both when needed with `npx`:
+Install both with one `npx` command:
 
 ```bash
-npx -y @bybrawe/opencode-loop@latest
-npx -y @bybrawe/opencode-goal@latest
+npx -y @bybrawe/opencode-loop@latest --with-goals
 ```
 
-Or install both globally with npm, then run both installers:
+Or install both globally with npm, then run the Loop installer with the companion flag:
 
 ```bash
 npm install -g @bybrawe/opencode-loop@latest @bybrawe/opencode-goal@latest
-opencode-loop
-opencode-goal
+opencode-loop --with-goals
 ```
 
+Once Goals is managed in the OpenCode config, future normal `opencode-loop` / `npx ...opencode-loop@latest` updates also attempt to refresh Goals to its latest stable release. Use `--loop-only` when you intentionally do not want that companion refresh.
+
 ## Core commands
 
 | Command | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.30",
+  "version": "0.5.31",
   "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",
@@ -21,10 +21,10 @@
     "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/opencode/command-router.js && node --check src/source/opencode/goal-commands.js && node --check src/source/opencode/loop-commands.js && node --check src/source/opencode/loop-registration.js && node --check src/source/runtime/session-activity.js && node --check src/source/runtime/session-status.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-runtime.js && node --check src/source/runtime/goal-policy.js && node --check src/source/runtime/goal-steering.js && node --check src/source/runtime/job-workspace.js && node --check src/source/opencode2/prompt-runtime.js && node --check src/source/opencode2/diagnostics.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/command-router-test.mjs && node --check scripts/goal-command-handlers-test.mjs && node --check scripts/loop-command-handlers-test.mjs && node --check scripts/loop-registration-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/compaction-runtime-test.mjs && node --check scripts/executor-runtime-test.mjs && node --check scripts/scheduler-runtime-test.mjs && node --check scripts/goal-runtime-test.mjs && node --check scripts/goal-policy-test.mjs && node --check scripts/goal-steering-test.mjs && node --check scripts/job-workspace-test.mjs && node --check scripts/v2-prompt-runtime-test.mjs && node --check scripts/v2-prompt-interval-test.mjs && node --check scripts/v2-command-runtime-test.mjs && node --check scripts/v2-command-adapter-test.mjs && node --check scripts/v2-diagnostics-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs && node --check scripts/host-goal-steering-canary.mjs && node --check scripts/publish-workflow-test.mjs",
-    "test": "node scripts/publish-workflow-test.mjs && node scripts/command-router-test.mjs && node scripts/goal-command-handlers-test.mjs && node scripts/loop-command-handlers-test.mjs && node scripts/loop-registration-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/executor-runtime-test.mjs && node scripts/scheduler-runtime-test.mjs && node scripts/goal-runtime-test.mjs && node scripts/goal-policy-test.mjs && node scripts/goal-steering-test.mjs && node scripts/job-workspace-test.mjs && node scripts/v2-prompt-runtime-test.mjs && node scripts/v2-prompt-interval-test.mjs && node scripts/v2-command-runtime-test.mjs && node scripts/v2-command-adapter-test.mjs && node scripts/v2-diagnostics-test.mjs && 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",
+    "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/opencode/command-router.js && node --check src/source/opencode/goal-commands.js && node --check src/source/opencode/loop-commands.js && node --check src/source/opencode/loop-registration.js && node --check src/source/runtime/session-activity.js && node --check src/source/runtime/session-status.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-runtime.js && node --check src/source/runtime/goal-policy.js && node --check src/source/runtime/goal-steering.js && node --check src/source/runtime/job-workspace.js && node --check src/source/opencode2/prompt-runtime.js && node --check src/source/opencode2/diagnostics.js && node --check src/source/opencode2/logging.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/install-with-goals.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/goal-companion-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/command-router-test.mjs && node --check scripts/goal-command-handlers-test.mjs && node --check scripts/loop-command-handlers-test.mjs && node --check scripts/loop-registration-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/compaction-runtime-test.mjs && node --check scripts/executor-runtime-test.mjs && node --check scripts/scheduler-runtime-test.mjs && node --check scripts/goal-runtime-test.mjs && node --check scripts/goal-policy-test.mjs && node --check scripts/goal-steering-test.mjs && node --check scripts/job-workspace-test.mjs && node --check scripts/v2-prompt-runtime-test.mjs && node --check scripts/v2-prompt-interval-test.mjs && node --check scripts/v2-command-runtime-test.mjs && node --check scripts/v2-command-adapter-test.mjs && node --check scripts/v2-diagnostics-test.mjs && node --check scripts/v2-logging-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs && node --check scripts/host-goal-steering-canary.mjs && node --check scripts/publish-workflow-test.mjs",
+    "test": "node scripts/publish-workflow-test.mjs && node scripts/command-router-test.mjs && node scripts/goal-command-handlers-test.mjs && node scripts/loop-command-handlers-test.mjs && node scripts/loop-registration-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/executor-runtime-test.mjs && node scripts/scheduler-runtime-test.mjs && node scripts/goal-runtime-test.mjs && node scripts/goal-policy-test.mjs && node scripts/goal-steering-test.mjs && node scripts/job-workspace-test.mjs && node scripts/v2-prompt-runtime-test.mjs && node scripts/v2-prompt-interval-test.mjs && node scripts/v2-command-runtime-test.mjs && node scripts/v2-command-adapter-test.mjs && node scripts/v2-diagnostics-test.mjs && node scripts/v2-logging-test.mjs && node scripts/install-test.mjs && node scripts/goal-companion-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 && node scripts/host-goal-steering-canary.mjs",
-    "install:global": "node scripts/install-node.mjs",
+    "install:global": "node scripts/install-with-goals.mjs",
     "pack:zip": "node scripts/make-zip.mjs"
   },
   "keywords": [
@@ -64,7 +64,7 @@
     "@opencode-ai/plugin": "^1.18.15"
   },
   "bin": {
-    "opencode-loop": "scripts/install-node.mjs",
+    "opencode-loop": "scripts/install-with-goals.mjs",
     "opencode-loopd": "scripts/loopd.mjs"
   },
   "publishConfig": {

package/scripts/goal-companion-test.mjs

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict"
+import { spawn } from "node:child_process"
+import { promises as fs } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
+const installer = path.join(root, "scripts", "install-with-goals.mjs")
+const temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-loop-goal-companion-"))
+const fakeNpm = path.join(temporaryRoot, "fake-npm.mjs")
+const expectedGoalExec = [
+  "exec",
+  "--yes",
+  "--package=@bybrawe/opencode-goal@latest",
+  "--",
+  "opencode-goal",
+]
+
+await fs.writeFile(fakeNpm, `
+import { appendFileSync } from "node:fs"
+const log = process.env.FAKE_NPM_LOG
+if (log) appendFileSync(log, JSON.stringify(process.argv.slice(2)) + "\\n", "utf8")
+process.exit(Number(process.env.FAKE_NPM_EXIT || 0))
+`, "utf8")
+
+async function runInstaller(config, cliArgs = [], env = {}) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [installer, ...cliArgs], {
+      cwd: root,
+      env: {
+        ...process.env,
+        OPENCODE_CONFIG_DIR: config,
+        npm_execpath: fakeNpm,
+        ...env,
+      },
+      windowsHide: true,
+    })
+    const stdout = []
+    const stderr = []
+    child.stdout.on("data", (data) => stdout.push(Buffer.from(data)))
+    child.stderr.on("data", (data) => stderr.push(Buffer.from(data)))
+    child.on("error", reject)
+    child.on("close", (code) => resolve({
+      code,
+      stdout: Buffer.concat(stdout).toString("utf8"),
+      stderr: Buffer.concat(stderr).toString("utf8"),
+    }))
+  })
+}
+
+async function calls(log) {
+  try {
+    return (await fs.readFile(log, "utf8"))
+      .trim()
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => JSON.parse(line))
+  } catch (error) {
+    if (error?.code === "ENOENT") return []
+    throw error
+  }
+}
+
+async function writeConfig(config, plugins, comment = "") {
+  await fs.mkdir(config, { recursive: true })
+  await fs.writeFile(
+    path.join(config, "opencode.jsonc"),
+    `{\n  ${comment ? `// ${comment}\n  ` : ""}\"plugin\": ${JSON.stringify(plugins, null, 2).replaceAll("\n", "\n  ")},\n}\n`,
+    "utf8",
+  )
+}
+
+try {
+  const absentConfig = path.join(temporaryRoot, "absent")
+  const absentLog = path.join(temporaryRoot, "absent.log")
+  const absent = await runInstaller(absentConfig, [], { FAKE_NPM_LOG: absentLog })
+  assert.equal(absent.code, 0, absent.stderr)
+  assert.deepEqual(await calls(absentLog), [], "Loop-only installations must not silently add Goals")
+
+  const existingConfig = path.join(temporaryRoot, "existing")
+  const existingLog = path.join(temporaryRoot, "existing.log")
+  await writeConfig(existingConfig, ["other-plugin", "@bybrawe/opencode-goal@1.3.16"])
+  const existing = await runInstaller(existingConfig, [], { FAKE_NPM_LOG: existingLog })
+  assert.equal(existing.code, 0, existing.stderr)
+  assert.deepEqual(await calls(existingLog), [expectedGoalExec], "an installed Goals package must auto-refresh through its own latest installer")
+  assert.match(existing.stdout, /Installed\/updated OpenCode Goals via @bybrawe\/opencode-goal@latest/)
+
+  const localConfig = path.join(temporaryRoot, "local-goal")
+  const localLog = path.join(temporaryRoot, "local-goal.log")
+  await writeConfig(localConfig, ["./plugins/opencode-goal.ts"])
+  const local = await runInstaller(localConfig, [], { FAKE_NPM_LOG: localLog })
+  assert.equal(local.code, 0, local.stderr)
+  assert.deepEqual(await calls(localLog), [expectedGoalExec], "legacy local Goals installs must be refreshed/migrated by the companion installer")
+
+  const managedCommandConfig = path.join(temporaryRoot, "managed-command")
+  const managedCommandLog = path.join(temporaryRoot, "managed-command.log")
+  await fs.mkdir(path.join(managedCommandConfig, "commands"), { recursive: true })
+  await fs.writeFile(path.join(managedCommandConfig, "commands", "goal.md"), "<!-- managed-by:@bybrawe/opencode-goal -->\n", "utf8")
+  const managedCommand = await runInstaller(managedCommandConfig, [], { FAKE_NPM_LOG: managedCommandLog })
+  assert.equal(managedCommand.code, 0, managedCommand.stderr)
+  assert.deepEqual(await calls(managedCommandLog), [expectedGoalExec], "a managed /goal command is sufficient evidence that Goals should be refreshed")
+
+  const commentedConfig = path.join(temporaryRoot, "comment-only")
+  const commentedLog = path.join(temporaryRoot, "comment-only.log")
+  await writeConfig(commentedConfig, ["other-plugin"], 'old note: "@bybrawe/opencode-goal@1.3.16"')
+  const commented = await runInstaller(commentedConfig, [], { FAKE_NPM_LOG: commentedLog })
+  assert.equal(commented.code, 0, commented.stderr)
+  assert.deepEqual(await calls(commentedLog), [], "a package name mentioned only in JSONC comments must not trigger a network update")
+
+  const explicitConfig = path.join(temporaryRoot, "explicit")
+  const explicitLog = path.join(temporaryRoot, "explicit.log")
+  const explicit = await runInstaller(explicitConfig, ["--with-goals"], { FAKE_NPM_LOG: explicitLog })
+  assert.equal(explicit.code, 0, explicit.stderr)
+  assert.deepEqual(await calls(explicitLog), [expectedGoalExec], "--with-goals must install the companion even when it is absent")
+
+  const optOutConfig = path.join(temporaryRoot, "opt-out")
+  const optOutLog = path.join(temporaryRoot, "opt-out.log")
+  await writeConfig(optOutConfig, ["@bybrawe/opencode-goal@1.3.16"])
+  const optOut = await runInstaller(optOutConfig, ["--loop-only"], { FAKE_NPM_LOG: optOutLog })
+  assert.equal(optOut.code, 0, optOut.stderr)
+  assert.deepEqual(await calls(optOutLog), [], "--loop-only must suppress companion network work")
+  assert.match(optOut.stdout, /Skipped OpenCode Goals companion update/)
+
+  const autoFailureConfig = path.join(temporaryRoot, "auto-failure")
+  const autoFailureLog = path.join(temporaryRoot, "auto-failure.log")
+  await writeConfig(autoFailureConfig, ["@bybrawe/opencode-goal@1.3.16"])
+  const autoFailure = await runInstaller(autoFailureConfig, [], { FAKE_NPM_LOG: autoFailureLog, FAKE_NPM_EXIT: "7" })
+  assert.equal(autoFailure.code, 0, "a best-effort refresh failure must not break an otherwise successful Loop update")
+  assert.match(autoFailure.stderr, /could not be refreshed/)
+  assert.match(autoFailure.stderr, /npx -y @bybrawe\/opencode-goal@latest/)
+
+  const explicitFailureConfig = path.join(temporaryRoot, "explicit-failure")
+  const explicitFailureLog = path.join(temporaryRoot, "explicit-failure.log")
+  const explicitFailure = await runInstaller(explicitFailureConfig, ["--with-goals"], { FAKE_NPM_LOG: explicitFailureLog, FAKE_NPM_EXIT: "9" })
+  assert.equal(explicitFailure.code, 9, "an explicitly requested companion install must fail closed")
+  assert.match(explicitFailure.stderr, /companion install\/update failed/)
+
+  const conflicting = await runInstaller(path.join(temporaryRoot, "conflicting"), ["--with-goals", "--loop-only"])
+  assert.equal(conflicting.code, 2)
+  assert.match(conflicting.stderr, /either --with-goals or --loop-only/)
+
+  const helpLog = path.join(temporaryRoot, "help.log")
+  const help = await runInstaller(path.join(temporaryRoot, "help"), ["--with-goals", "--help"], { FAKE_NPM_LOG: helpLog })
+  assert.equal(help.code, 0, help.stderr)
+  assert.match(help.stdout, /OpenCode Loop installer\/updater/)
+  assert.match(help.stdout, /--with-goals/)
+  assert.match(help.stdout, /--loop-only/)
+  assert.match(help.stdout, /Loop uninstall never removes Goals/)
+  assert.deepEqual(await calls(helpLog), [], "help/version flows must never install companion packages")
+
+  console.log("OpenCode Loop Goals companion installer test passed")
+} finally {
+  await fs.rm(temporaryRoot, { recursive: true, force: true })
+}

package/scripts/install-with-goals.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import { readFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const loopInstaller = join(root, "scripts", "install-node.mjs")
+const config = process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode")
+const configCandidates = ["opencode.json", "opencode.jsonc", "config.json", "config.jsonc"]
+const goalPackageName = "@bybrawe/opencode-goal"
+const goalPackageSpec = `${goalPackageName}@latest`
+const managedGoalCommandMarker = "<!-- managed-by:@bybrawe/opencode-goal -->"
+const rawArgs = process.argv.slice(2)
+const withGoals = rawArgs.includes("--with-goals")
+const loopOnly = rawArgs.includes("--loop-only")
+const loopArgs = rawArgs.filter((arg) => arg !== "--with-goals" && arg !== "--loop-only")
+const uninstallRequested = loopArgs.length === 1 && ["--uninstall", "uninstall", "--remove"].includes(loopArgs[0] || "")
+const helpRequested = loopArgs.some((arg) => ["--help", "-h"].includes(arg))
+const versionRequested = loopArgs.some((arg) => ["--version", "-v"].includes(arg))
+const informational = helpRequested || versionRequested
+
+function stripJsonComments(input) {
+  let output = ""
+  let quote = ""
+  let escaped = false
+  let lineComment = false
+  let blockComment = false
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index]
+    const next = input[index + 1]
+    if (lineComment) {
+      if (char === "\n" || char === "\r") { lineComment = false; output += char }
+      continue
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") { blockComment = false; index++ }
+      else if (char === "\n" || char === "\r") output += char
+      continue
+    }
+    if (quote) {
+      output += char
+      if (escaped) escaped = false
+      else if (char === "\\") escaped = true
+      else if (char === quote) quote = ""
+      continue
+    }
+    if (char === '"') { quote = char; output += char; continue }
+    if (char === "/" && next === "/") { lineComment = true; index++; continue }
+    if (char === "/" && next === "*") { blockComment = true; index++; continue }
+    output += char
+  }
+  return output
+}
+
+function stripTrailingCommas(input) {
+  let output = ""
+  let quote = ""
+  let escaped = false
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index]
+    if (quote) {
+      output += char
+      if (escaped) escaped = false
+      else if (char === "\\") escaped = true
+      else if (char === quote) quote = ""
+      continue
+    }
+    if (char === '"') { quote = char; output += char; continue }
+    if (char === ",") {
+      let lookahead = index + 1
+      while (/\s/.test(input[lookahead] || "")) lookahead++
+      if (input[lookahead] === "]" || input[lookahead] === "}") continue
+    }
+    output += char
+  }
+  return output
+}
+
+function parseJsonc(input) {
+  const parsed = JSON.parse(stripTrailingCommas(stripJsonComments(input)))
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenCode config root must be a JSON object")
+  return parsed
+}
+
+function isGoalPluginSpec(value) {
+  if (typeof value !== "string") return false
+  const spec = value.trim()
+  if (spec === goalPackageName || spec.startsWith(`${goalPackageName}@`)) return true
+  const normalized = spec.replaceAll("\\", "/")
+  return normalized === "./plugins/opencode-goal.ts"
+    || normalized === "./plugins/opencode-goal.js"
+    || normalized.endsWith("/plugins/opencode-goal.ts")
+    || normalized.endsWith("/plugins/opencode-goal.js")
+}
+
+async function goalsAlreadyInstalled() {
+  for (const name of configCandidates) {
+    try {
+      const parsed = parseJsonc(await readFile(join(config, name), "utf8"))
+      if (Array.isArray(parsed.plugin) && parsed.plugin.some(isGoalPluginSpec)) return true
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        console.warn(`Could not inspect ${join(config, name)} for OpenCode Goals: ${error.message}`)
+      }
+    }
+  }
+
+  try {
+    const command = await readFile(join(config, "commands", "goal.md"), "utf8")
+    return command.includes(managedGoalCommandMarker)
+  } catch (error) {
+    if (error?.code !== "ENOENT") console.warn(`Could not inspect managed /goal command: ${error.message}`)
+  }
+  return false
+}
+
+function runLoopInstaller() {
+  return spawnSync(process.execPath, [loopInstaller, ...loopArgs], {
+    cwd: root,
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+  })
+}
+
+function runGoalInstaller() {
+  const npmExecPath = process.env.npm_execpath
+  const command = npmExecPath ? process.execPath : (process.platform === "win32" ? "npm.cmd" : "npm")
+  const args = npmExecPath
+    ? [npmExecPath, "exec", "--yes", `--package=${goalPackageSpec}`, "--", "opencode-goal"]
+    : ["exec", "--yes", `--package=${goalPackageSpec}`, "--", "opencode-goal"]
+
+  return spawnSync(command, args, {
+    cwd: root,
+    env: { ...process.env, OPENCODE_CONFIG_DIR: config },
+    stdio: "inherit",
+    windowsHide: true,
+    timeout: 180_000,
+  })
+}
+
+function statusCode(result) {
+  if (Number.isInteger(result?.status)) return result.status
+  return result?.error ? 1 : 0
+}
+
+function printCompanionHelp() {
+  console.log(`\nOpenCode Goals companion options:\n  --with-goals  Install/update @bybrawe/opencode-goal@latest even when it is not already installed.\n  --loop-only   Skip all OpenCode Goals companion detection and network update work.\n\nNormal Loop install/update refreshes an already-managed OpenCode Goals installation on a best-effort basis. Loop uninstall never removes Goals.`)
+}
+
+async function main() {
+  if (withGoals && loopOnly) {
+    console.error("Use either --with-goals or --loop-only, not both.")
+    process.exitCode = 2
+    return
+  }
+
+  const loopResult = runLoopInstaller()
+  if (loopResult.error) {
+    console.error(`OpenCode Loop installer failed to start: ${loopResult.error.message}`)
+    process.exitCode = 1
+    return
+  }
+  const loopCode = statusCode(loopResult)
+  if (loopCode !== 0) {
+    process.exitCode = loopCode
+    return
+  }
+
+  if (informational) {
+    if (helpRequested) printCompanionHelp()
+    return
+  }
+  if (uninstallRequested) return
+
+  if (loopOnly) {
+    console.log("Skipped OpenCode Goals companion update (--loop-only).")
+    return
+  }
+
+  const alreadyInstalled = await goalsAlreadyInstalled()
+  if (!alreadyInstalled && !withGoals) return
+
+  const goalResult = runGoalInstaller()
+  const goalCode = statusCode(goalResult)
+  if (goalCode === 0) {
+    console.log(`Installed/updated OpenCode Goals via ${goalPackageSpec}.`)
+    return
+  }
+
+  const detail = goalResult.error?.message || `exit code ${goalCode}`
+  if (withGoals) {
+    console.error(`OpenCode Goals companion install/update failed (${detail}).`)
+    process.exitCode = goalCode || 1
+    return
+  }
+
+  console.warn(`OpenCode Loop updated, but the existing OpenCode Goals companion could not be refreshed (${detail}).`)
+  console.warn(`Retry later with: npx -y ${goalPackageSpec}`)
+}
+
+main().catch((error) => {
+  console.error(error?.stack || error)
+  process.exitCode = 1
+})

package/scripts/v2-diagnostics-test.mjs

@@ -7,12 +7,17 @@ const state = {
   version: 1,
   jobs: [{ id: "job_export", name: "exported", runCount: 2, paused: false }],
 }
+const logLines = [
+  JSON.stringify({ time: "stable", line: "stable-only" }),
+  ...Array.from({ length: 82 }, (_, index) => JSON.stringify({ time: `t${index + 1}`, line: "run", v2: true, seq: index + 1 })),
+].join("\n")
 const runtime = createOpenCode2DiagnosticsRuntime({
   prompt: async (request) => { prompts.push(request) },
   readState: async (directory, sessionID) => {
     reads.push([directory, sessionID])
     return structuredClone(state)
   },
+  readFile: async () => logLines,
   runtimeVersion: "v-test",
   runtimePlatform: "test-platform",
 })
@@ -48,6 +53,7 @@ assert.equal(prompts[1].text, OPENCODE_LOOP_V2_HELP_TEXT)
 assert.match(prompts[1].text, /^OpenCode Loop V2 experimental help:/)
 assert.match(prompts[1].text, /\/loop-status/)
 assert.match(prompts[1].text, /\/loop-export/)
+assert.match(prompts[1].text, /\/loop-logs/)
 assert.match(prompts[1].text, /\/loop-doctor/)
 assert.match(prompts[1].text, /does not yet claim full stable-plugin parity/)
 assert.doesNotMatch(prompts[1].text, /\/loop-goal/)
@@ -69,6 +75,27 @@ assert.match(prompts[2].text, /- platform: test-platform/)
 assert.match(prompts[2].text, /- full stable parity: not claimed/)
 assert.match(prompts[2].text, /- smoke test: \/loop 0s --max-runs 1/)
 
+const logs = await runtime.onEvent({ kind: "command", action: "executed", name: "loop-logs", sessionID: "ses", directory: "/work" })
+assert.equal(logs.handled, true)
+assert.equal(logs.accepted, true)
+assert.equal(reads.length, 2, "loop-logs must not read or mutate Loop state")
+assert.equal(prompts.length, 4)
+assert.equal(prompts[3].noReply, true)
+assert.match(prompts[3].text, /^OpenCode Loop V2 logs:\n/)
+assert.doesNotMatch(prompts[3].text, /stable-only/)
+assert.doesNotMatch(prompts[3].text, /"seq":1}/)
+assert.doesNotMatch(prompts[3].text, /"seq":2}/)
+assert.match(prompts[3].text, /"seq":3}/)
+assert.match(prompts[3].text, /"seq":82}/)
+
+const missingLogs = []
+const missingLogRuntime = createOpenCode2DiagnosticsRuntime({
+  prompt: async (request) => { missingLogs.push(request) },
+  readFile: async () => { throw new Error("missing") },
+})
+await missingLogRuntime.onEvent({ kind: "command", action: "executed", name: "loop-logs", sessionID: "ses", directory: "/work" })
+assert.equal(missingLogs[0].text, "OpenCode Loop V2 logs:\nNo OpenCode 2 Loop log found.")
+
 assert.throws(() => createOpenCode2DiagnosticsRuntime({}), /requires prompt\(\)/)
 
 console.log("OpenCode 2 diagnostics contract passed")

package/scripts/v2-logging-test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict"
+import { createOpenCode2LogRuntime } from "../src/source/opencode2/logging.js"
+
+const records = []
+const runtime = createOpenCode2LogRuntime({
+  appendLoopLog: async (...args) => { records.push(args) },
+})
+
+assert.equal(await runtime.record({ kind: "message", action: "updated", sessionID: "ses", directory: "/work" }, { handled: false }), false)
+assert.equal(records.length, 0)
+
+assert.equal(await runtime.record(
+  { kind: "command", action: "executed", name: "loop", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, job: { id: "job_a", name: "alpha" } },
+), true)
+assert.deepEqual(records[0], ["/work", "add", { sessionID: "ses", v2: true, job: "alpha" }])
+
+await runtime.record(
+  { kind: "command", action: "executed", name: "loop-now", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, target: "alpha", count: 1 },
+)
+await runtime.record(
+  { kind: "command", action: "executed", name: "loop-pause", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, target: "alpha", count: 1 },
+)
+await runtime.record(
+  { kind: "command", action: "executed", name: "loop-resume", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, target: "alpha", count: 1 },
+)
+await runtime.record(
+  { kind: "command", action: "executed", name: "loop-remove", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, target: "alpha", count: 1 },
+)
+await runtime.record(
+  { kind: "command", action: "executed", name: "loop-clear", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, target: "all", count: 1 },
+)
+await runtime.record(
+  { kind: "session", action: "idle", sessionID: "ses", directory: "/work" },
+  { handled: true, dispatched: true, kind: "prompt", job: { id: "job_a", name: "alpha", runCount: 2 } },
+)
+
+assert.deepEqual(records.map((entry) => entry[1]), ["add", "run-now", "pause", "resume", "remove", "clear", "run"])
+assert.deepEqual(records.at(-1), ["/work", "run", { sessionID: "ses", v2: true, job: "alpha", kind: "prompt", runs: 2 }])
+
+const beforeRejected = records.length
+await runtime.record(
+  { kind: "command", action: "executed", name: "loop", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: false, reason: "unsupported" },
+)
+assert.equal(records.length, beforeRejected, "rejected commands must not create success logs")
+
+const failing = createOpenCode2LogRuntime({ appendLoopLog: async () => { throw new Error("disk unavailable") } })
+assert.equal(await failing.record(
+  { kind: "command", action: "executed", name: "loop-now", sessionID: "ses", directory: "/work" },
+  { handled: true, accepted: true, target: "all", count: 1 },
+), false, "logging failures must never fail the Loop runtime")
+
+console.log("OpenCode 2 logging contract passed")

package/scripts/v2-plugin-sentinel-test.mjs

@@ -33,6 +33,7 @@ assert.deepEqual(Object.keys(OPENCODE_LOOP_V2_COMMANDS), [
   "loop-export",
   "loop-help",
   "loop-doctor",
+  "loop-logs",
 ])
 assert.deepEqual(
   parseOpenCode2LoopCommandText(`${OPENCODE_LOOP_V2_COMMANDS["loop-now"].template}\n\nsecond`),

package/src/source/opencode2/commands.js

@@ -43,6 +43,10 @@ export const OPENCODE_LOOP_V2_COMMANDS = Object.freeze({
     description: "Show experimental OpenCode 2 Loop diagnostics.",
     template: "OpenCode Loop doctor command handled locally. Reply exactly: OK.",
   }),
+  "loop-logs": Object.freeze({
+    description: "Show recent experimental OpenCode 2 Loop runtime events.",
+    template: "OpenCode Loop logs command handled locally. Reply exactly: OK.",
+  }),
 })
 
 export function registerOpenCode2LoopCommands(draft) {

package/src/source/opencode2/diagnostics.js

@@ -1,3 +1,5 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
 import { readState as defaultReadState, stateDir } from "../core/state.js"
 
 export const OPENCODE_LOOP_V2_HELP_TEXT = [
@@ -11,6 +13,7 @@ export const OPENCODE_LOOP_V2_HELP_TEXT = [
   "/loop-stop [target] | /loop-remove [target]       remove matching jobs",
   "/loop-clear                                       clear all jobs",
   "/loop-export                                      export current session Loop state as JSON",
+  "/loop-logs                                        show the latest V2 runtime events",
   "/loop-help                                        show this experimental V2 help",
   "/loop-doctor                                      show local V2 diagnostics",
   "Experimental V2 does not yet claim full stable-plugin parity; unsupported options fail closed.",
@@ -26,6 +29,7 @@ function scopeFrom(event) {
 export function createOpenCode2DiagnosticsRuntime(options = {}) {
   if (typeof options.prompt !== "function") throw new TypeError("V2 diagnostics runtime requires prompt()")
   const readState = typeof options.readState === "function" ? options.readState : defaultReadState
+  const readFile = typeof options.readFile === "function" ? options.readFile : (...args) => fs.readFile(...args)
   const runtimeVersion = options.runtimeVersion || process.version
   const runtimePlatform = options.runtimePlatform || process.platform
 
@@ -67,14 +71,33 @@ export function createOpenCode2DiagnosticsRuntime(options = {}) {
     return { handled: true, accepted: true, state, request }
   }
 
+  async function logs(event) {
+    const scope = scopeFrom(event)
+    if (!scope) return { handled: false, reason: "missing-scope" }
+    let text = "No OpenCode 2 Loop log found."
+    try {
+      const raw = await readFile(path.join(stateDir(scope.directory), "loop.log"), "utf8")
+      const lines = String(raw || "")
+        .trim()
+        .split(/\r?\n/)
+        .filter((line) => line.includes('"v2":true'))
+        .slice(-80)
+      if (lines.length) text = lines.join("\n")
+    } catch {}
+    const request = { sessionID: scope.sessionID, text: `OpenCode Loop V2 logs:\n${text}`, noReply: true }
+    await options.prompt(request)
+    return { handled: true, accepted: true, request }
+  }
+
   async function onEvent(event) {
     if (event?.kind === "command" && event?.action === "executed") {
       if (event?.name === "loop-export") return await exportState(event)
       if (event?.name === "loop-help") return await help(event)
       if (event?.name === "loop-doctor") return await doctor(event)
+      if (event?.name === "loop-logs") return await logs(event)
     }
     return { handled: false }
   }
 
-  return Object.freeze({ onEvent, exportState, help, doctor })
+  return Object.freeze({ onEvent, exportState, help, doctor, logs })
 }

package/src/source/opencode2/experimental.js

@@ -1,6 +1,7 @@
 import { inspectOpenCode2Context } from "./capabilities.js"
 import { OPENCODE_LOOP_V2_COMMANDS, registerOpenCode2LoopCommands } from "./commands.js"
 import { createOpenCode2DiagnosticsRuntime } from "./diagnostics.js"
+import { createOpenCode2LogRuntime } from "./logging.js"
 import { createOpenCode2PromptRuntime } from "./prompt-runtime.js"
 import { createOpenCode2RuntimeAdapter } from "./runtime-adapter.js"
 
@@ -23,8 +24,10 @@ export const OpenCodeLoopV2ExperimentalPlugin = {
 
     let promptRuntime
     let diagnosticsRuntime
+    const logRuntime = createOpenCode2LogRuntime()
     const onRuntimeEvent = async (event) => {
       const promptResult = await promptRuntime?.onEvent(event)
+      await logRuntime.record(event, promptResult)
       if (promptResult?.handled) return promptResult
       return await diagnosticsRuntime?.onEvent(event) ?? promptResult
     }

package/src/source/opencode2/logging.js

@@ -0,0 +1,66 @@
+import { appendLoopLog as defaultAppendLoopLog } from "../core/process.js"
+
+function scopeFrom(event) {
+  const directory = typeof event?.directory === "string" ? event.directory.trim() : ""
+  const sessionID = String(event?.sessionID || "").trim()
+  if (!directory || !sessionID) return undefined
+  return { directory, sessionID }
+}
+
+function jobName(job) {
+  return String(job?.name || job?.id || "default")
+}
+
+export function createOpenCode2LogRuntime(options = {}) {
+  const appendLoopLog = typeof options.appendLoopLog === "function" ? options.appendLoopLog : defaultAppendLoopLog
+
+  async function append(scope, line, extra = {}) {
+    try {
+      await appendLoopLog(scope.directory, line, { sessionID: scope.sessionID, v2: true, ...extra })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async function record(event, result) {
+    if (!result?.handled) return false
+    const scope = scopeFrom(event)
+    if (!scope) return false
+
+    if (event?.kind === "session" && event?.action === "idle" && result.dispatched && result.job) {
+      return await append(scope, "run", {
+        job: jobName(result.job),
+        kind: result.kind || "prompt",
+        runs: Number(result.job.runCount || 0),
+      })
+    }
+
+    if (event?.kind !== "command" || event?.action !== "executed" || result.accepted !== true) return false
+
+    if (event.name === "loop" && result.job) {
+      return await append(scope, "add", { job: jobName(result.job) })
+    }
+    if (event.name === "loop-now") {
+      return await append(scope, "run-now", { target: result.target, count: Number(result.count || 0) })
+    }
+    if (event.name === "loop-pause") {
+      return await append(scope, "pause", { target: result.target, count: Number(result.count || 0) })
+    }
+    if (event.name === "loop-resume") {
+      return await append(scope, "resume", { target: result.target, count: Number(result.count || 0) })
+    }
+    if (event.name === "loop-stop") {
+      return await append(scope, "stop", { target: result.target, count: Number(result.count || 0) })
+    }
+    if (event.name === "loop-remove") {
+      return await append(scope, "remove", { target: result.target, count: Number(result.count || 0) })
+    }
+    if (event.name === "loop-clear") {
+      return await append(scope, "clear", { target: result.target, count: Number(result.count || 0) })
+    }
+    return false
+  }
+
+  return Object.freeze({ record })
+}