@bybrawe/opencode-loop 0.5.31 → 0.5.32

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.32
+
+- Hide the tool-denied `opencode-loop-local` acknowledgement agent from the normal primary-agent cycle by installing it as a hidden subagent while keeping Loop slash commands explicitly bound to it.
+- Add `--without-loop-goals` so Loop installs/updates can omit the packaged experimental `/loop-goal*` command files without removing normal Loop commands, Loop runtime state, or the separate OpenCode Goals plugin.
+- Keep backward compatibility by installing the older Loop Goal command surface by default; the new opt-out composes with `--with-goals` for a cleaner `/loop` + dedicated `/goal` setup.
+- Add deterministic installer coverage for hidden-agent metadata, default legacy-command compatibility, clean command-surface opt-out, and combined Loop + Goals installation.
+
 ## 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.

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.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.
+> **Current release: `0.5.32`.** 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
 
@@ -24,6 +24,14 @@ Install Loop and Goals together from scratch with:
 npx -y @bybrawe/opencode-loop@latest --with-goals
 ```
 
+If you use the dedicated OpenCode Goals plugin and do not want Loop's older experimental `/loop-goal*` commands in the slash-command list, use:
+
+```bash
+npx -y @bybrawe/opencode-loop@latest --with-goals --without-loop-goals
+```
+
+`--without-loop-goals` removes only Loop's packaged experimental `/loop-goal*` command files for that install/update. It keeps `/loop`, `/loop-command`, `/loop-shell`, the Loop runtime, and the separate OpenCode Goals `/goal` workflow. The choice is not persisted: run the flag again on a later Loop update if you want to keep those legacy command files omitted.
+
 Update/install only Loop and skip all Goals companion network work with:
 
 ```bash
@@ -54,17 +62,23 @@ If you want the global Loop installer to install Goals too, run:
 opencode-loop --with-goals
 ```
 
+For the cleaner command surface with the dedicated Goals plugin:
+
+```bash
+opencode-loop --with-goals --without-loop-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:
 
 - installs/updates the OpenCode Loop plugin;
 - installs the `/loop-*` slash-command definitions;
-- installs the tool-denied `opencode-loop-local` command agent;
+- installs the tool-denied, hidden `opencode-loop-local` acknowledgement subagent used only by Loop's bound local command definitions;
 - 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;
 - 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`.
+- can explicitly install both packages with `--with-goals`, skip companion network work with `--loop-only`, or omit the packaged experimental `/loop-goal*` command files with `--without-loop-goals`.
 
 Then **fully restart OpenCode** and verify:
 
@@ -166,7 +180,7 @@ Loop is idle-safe: if a job becomes due while the session is busy, active tools
 
 ## For stronger persistent Goals, use OpenCode Goals
 
-OpenCode Loop still includes the older **experimental** `/loop-goal` workflow. It is useful for compatibility and lightweight outcome-driven automation, but it is not the strongest Goal implementation in this project family.
+OpenCode Loop still includes the older **experimental** `/loop-goal` workflow for backward compatibility unless you install/update with `--without-loop-goals`. It is useful for compatibility and lightweight outcome-driven automation, but it is not the strongest Goal implementation in this project family.
 
 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**.
 
@@ -176,6 +190,12 @@ Convenient combined installer from Loop:
 npx -y @bybrawe/opencode-loop@latest --with-goals
 ```
 
+For new installations where the dedicated `/goal` workflow replaces Loop's older experimental Goal commands, prefer:
+
+```bash
+npx -y @bybrawe/opencode-loop@latest --with-goals --without-loop-goals
+```
+
 Or install Goals directly with its standalone installer:
 
 ```bash
@@ -207,7 +227,7 @@ Recommended split:
 - use **`/goal`** for persistent, strongly verified outcome completion;
 - use **`/loop`**, `/loop-command`, `/loop-shell`, and `opencode-loopd` for scheduling/repetition/background infrastructure.
 
-Do **not** run Loop’s `/loop-goal` and OpenCode Goals `/goal` against the same work in the same session. Both can autonomously continue on idle boundaries and can compete to start turns.
+Do **not** run Loop’s `/loop-goal` and OpenCode Goals `/goal` against the same work in the same session. Both can autonomously continue on idle boundaries and can compete to start turns. Use `--without-loop-goals` when you want to remove that legacy command surface entirely.
 
 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.
 
@@ -224,7 +244,7 @@ npm install -g @bybrawe/opencode-loop@latest @bybrawe/opencode-goal@latest
 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.
+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. Use `--without-loop-goals` on any install/update where you want the older Loop Goal command files omitted.
 
 ## Core commands
 
@@ -244,7 +264,7 @@ Once Goals is managed in the OpenCode config, future normal `opencode-loop` / `n
 | `/loop-doctor` | Diagnose Loop/OpenCode state |
 | `/loop-init` | Create a starter `progress.md` |
 | `/loop-export` | Export Loop state as JSON |
-| `/loop-goal <objective>` | Start the older experimental Loop Goal Mode |
+| `/loop-goal <objective>` | Start the older experimental Loop Goal Mode when those optional legacy command files are installed |
 
 ## Intervals and job types
 
@@ -386,7 +406,7 @@ opencode-loopd uninstall-task --name OpenCodeLoop
 
 ## Experimental Loop Goal Mode
 
-Loop’s original Goal Mode remains available for existing users:
+Loop’s original Goal Mode remains available for existing users by default. If you install/update Loop with `--without-loop-goals`, its packaged `/loop-goal*` command definitions are removed while the rest of Loop keeps working.
 
 ```text
 /loop-goal --check "npm test" --complete-when-checks-pass fix the failing tests

package/agents/opencode-loop-local.md

@@ -1,6 +1,7 @@
 ---
 description: Handles OpenCode Loop slash-command acknowledgements without tools.
-mode: primary
+mode: subagent
+hidden: true
 permission:
   "*": deny
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.31",
+  "version": "0.5.32",
   "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",

package/scripts/goal-companion-test.mjs

@@ -62,6 +62,20 @@ async function calls(log) {
   }
 }
 
+async function loopGoalCommands(config) {
+  try {
+    return (await fs.readdir(path.join(config, "commands")))
+      .filter((name) => name === "loop-goal.md" || (name.startsWith("loop-goal-") && name.endsWith(".md")))
+  } catch (error) {
+    if (error?.code === "ENOENT") return []
+    throw error
+  }
+}
+
+async function exists(target) {
+  try { await fs.access(target); return true } catch { return false }
+}
+
 async function writeConfig(config, plugins, comment = "") {
   await fs.mkdir(config, { recursive: true })
   await fs.writeFile(
@@ -71,12 +85,26 @@ async function writeConfig(config, plugins, comment = "") {
   )
 }
 
+const localAgent = await fs.readFile(path.join(root, "agents", "opencode-loop-local.md"), "utf8")
+assert.match(localAgent, /^mode:\s*subagent$/m, "the local acknowledgement agent must not participate in the primary-agent cycle")
+assert.match(localAgent, /^hidden:\s*true$/m, "the local acknowledgement agent must be hidden from normal subagent selection")
+
 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")
+  assert.ok((await loopGoalCommands(absentConfig)).length > 0, "legacy Loop Goal commands stay installed by default for compatibility")
+
+  const withoutLoopGoalsConfig = path.join(temporaryRoot, "without-loop-goals")
+  const withoutLoopGoalsLog = path.join(temporaryRoot, "without-loop-goals.log")
+  const withoutLoopGoals = await runInstaller(withoutLoopGoalsConfig, ["--without-loop-goals"], { FAKE_NPM_LOG: withoutLoopGoalsLog })
+  assert.equal(withoutLoopGoals.code, 0, withoutLoopGoals.stderr)
+  assert.deepEqual(await calls(withoutLoopGoalsLog), [], "omitting legacy Loop Goal commands must not silently install Goals")
+  assert.deepEqual(await loopGoalCommands(withoutLoopGoalsConfig), [], "--without-loop-goals must remove every packaged experimental /loop-goal* command")
+  assert.equal(await exists(path.join(withoutLoopGoalsConfig, "commands", "loop.md")), true, "normal Loop commands must remain installed")
+  assert.match(withoutLoopGoals.stdout, /Omitted \d+ packaged experimental \/loop-goal\*/)
 
   const existingConfig = path.join(temporaryRoot, "existing")
   const existingLog = path.join(temporaryRoot, "existing.log")
@@ -114,6 +142,13 @@ try {
   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 explicitCleanConfig = path.join(temporaryRoot, "explicit-clean")
+  const explicitCleanLog = path.join(temporaryRoot, "explicit-clean.log")
+  const explicitClean = await runInstaller(explicitCleanConfig, ["--with-goals", "--without-loop-goals"], { FAKE_NPM_LOG: explicitCleanLog })
+  assert.equal(explicitClean.code, 0, explicitClean.stderr)
+  assert.deepEqual(await calls(explicitCleanLog), [expectedGoalExec], "the clean command surface option must compose with --with-goals")
+  assert.deepEqual(await loopGoalCommands(explicitCleanConfig), [], "combined install must keep the stronger Goals plugin without legacy Loop Goal command clutter")
+
   const optOutConfig = path.join(temporaryRoot, "opt-out")
   const optOutLog = path.join(temporaryRoot, "opt-out.log")
   await writeConfig(optOutConfig, ["@bybrawe/opencode-goal@1.3.16"])
@@ -146,10 +181,11 @@ try {
   assert.match(help.stdout, /OpenCode Loop installer\/updater/)
   assert.match(help.stdout, /--with-goals/)
   assert.match(help.stdout, /--loop-only/)
+  assert.match(help.stdout, /--without-loop-goals/)
   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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process"
-import { readFile } from "node:fs/promises"
+import { readFile, readdir, rm } from "node:fs/promises"
 import { homedir } from "node:os"
 import { dirname, join } from "node:path"
 import process from "node:process"
@@ -16,7 +16,8 @@ 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 withoutLoopGoals = rawArgs.includes("--without-loop-goals")
+const loopArgs = rawArgs.filter((arg) => !["--with-goals", "--loop-only", "--without-loop-goals"].includes(arg))
 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))
@@ -117,6 +118,22 @@ async function goalsAlreadyInstalled() {
   return false
 }
 
+async function removeLoopGoalCommands() {
+  const commandDir = join(config, "commands")
+  const names = (await readdir(join(root, "commands")))
+    .filter((name) => name === "loop-goal.md" || (name.startsWith("loop-goal-") && name.endsWith(".md")))
+  let removed = 0
+  for (const name of names) {
+    try {
+      await rm(join(commandDir, name))
+      removed++
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error
+    }
+  }
+  return removed
+}
+
 function runLoopInstaller() {
   return spawnSync(process.execPath, [loopInstaller, ...loopArgs], {
     cwd: root,
@@ -148,7 +165,7 @@ function statusCode(result) {
 }
 
 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.`)
+  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  --without-loop-goals  Omit/remove Loop's packaged experimental /loop-goal* command files for this install/update.\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() {
@@ -176,6 +193,11 @@ async function main() {
   }
   if (uninstallRequested) return
 
+  if (withoutLoopGoals) {
+    const removed = await removeLoopGoalCommands()
+    console.log(`Omitted ${removed} packaged experimental /loop-goal* command file(s) (--without-loop-goals).`)
+  }
+
   if (loopOnly) {
     console.log("Skipped OpenCode Goals companion update (--loop-only).")
     return
@@ -205,4 +227,4 @@ async function main() {
 main().catch((error) => {
   console.error(error?.stack || error)
   process.exitCode = 1
-})
+})