@bybrawe/opencode-loop 0.5.38 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.6.1 - 2026-09-29
+
+- Expose the root/server and `./v2` npm entrypoints through the official `@opencode/plugin` `Plugin.define({ id, setup })` contract while keeping V1 `server()` as a separate compatibility implementation.
+- Ship `@opencode/plugin@^2.0.18` as a production dependency and lock its non-optional runtime peer closure for reproducible clean installs.
+- Make native local-file installs use the same real V2 entrypoint: `plugins/opencode-loop/index.js` is the `Plugin.define()` wrapper and `native.js` is only its supporting generated runtime.
+- Preserve configured package options while migrating `plugin` to `plugins`; remove old single-file local copies during native upgrades and uninstall.
+- Extend Windows production-tarball smoke time only at the harness boundary so the larger V2 dependency graph can install without weakening runtime assertions.
+- Pair trusted publication with OpenCode Goal 1.3.40 from its exact immutable source and re-run the installed npm pair on OpenCode 2.0.18.
+
+## 0.6.0 - 2026-09-29
+
+- Fix #164: persisted core user-message events cannot abort compaction; trusted admission hooks alone may steer legacy turns.
+- Activate native V2 queued scheduling and default local installation, preserving explicit V1 compatibility.
+- Correct unsupported plugin shell assumptions with a bounded local process lifecycle and correlated terminals.
+- Preserve dedicated Goal ownership, native compaction barriers, uncertain-admission safety, and configuration options.
+- Fix branch success reporting, timeout exit codes and self-matching completion markers.
+- Explicitly report the OpenCode 2.0.18 scheduled-compaction capability gap.
+
+
 ## 0.5.38
 
 Long-session provider-error, waiting-user, and OpenCode 2.0.11 compatibility release.

package/README.md

@@ -1,10 +1,23 @@
 # OpenCode Loop
 
+## Native OpenCode 2 (0.6.1)
+
+The npm and local-file V2 entrypoints now use the official `@opencode/plugin` `Plugin.define()` contract. The local installer writes a discovered plugin package directory with the generated runtime as a supporting module, while explicit `--legacy-v1` remains a separate compatibility path.
+
+The installer now defaults to the standalone native V2 plugin. It needs no V1 SDK or legacy command files for a local installation. Existing npm registrations migrate from `plugin` to `plugins` without dropping object options. Use `--legacy-v1` explicitly for the compatibility installation.
+
+V2 prompt admission and durable inbox/execution/compaction events own scheduling. Core-generated user-role messages never authorize a session abort. An unfinished dedicated Goal reserves its session, including paused and handed-off states; Loop does not wake or replace that Goal. Soft iteration timeouts do not abort a native model/tool/compaction turn.
+
+Scheduled shell commands use bounded local child processes when OpenCode does not expose `session.shell` to plugins. Automatic compaction stays host-owned. **Scheduled compaction requires a host exposing `session.compact`; OpenCode 2.0.18's published plugin Context does not expose it, and those commands are rejected before job creation rather than silently ignored.** Use OpenCode's built-in manual/automatic compaction on that host.
+
+Prompt/command timers, watch and stop conditions, verification, preflight/postrun, notifications, checkpoints and diagnostic commands use the V2 runtime. Uncertain restart admissions pause for review rather than replaying potentially admitted work. The dedicated `@bybrawe/opencode-goal` plugin owns `/goal`; legacy Loop Goal records are preserved and are not silently reinterpreted as new Goal contracts.
+
+
 **Idle-safe auto-continue, scheduled OpenCode work, and background loops.**
 
 OpenCode Loop adds `/loop`, scheduled prompt/command/shell jobs, compact scheduling, verification/checkpoints, and the `opencode-loopd` background daemon.
 
-> **Current stable release: `0.5.38`.**
+> **Current stable release: `0.6.1`.**
 
 ## Install or update
 
@@ -383,6 +396,25 @@ Pin a session and limit runs:
 opencode-loopd --project . --session ses_xxx --every 5m --max-runs 20 --timeout 30m --prompt-file loop-prompt.md
 ```
 
+### Dedicated Goal pulse-check
+
+Use the daemon as a read-only stall detector for dedicated `/goal` state:
+
+```bash
+# one-shot (good for systemd timers / cron-style runners)
+opencode-loopd pulse-check --project . --stale-after 30m
+
+# repeating opt-in watcher
+opencode-loopd pulse-check --project . --stale-after 30m --every 1m
+
+# watch one Goal by Goal ID or session ID
+opencode-loopd pulse-check --project . --goal <goal-or-session-id> --stale-after 30m --every 1m
+```
+
+The pulse-check reads `.opencode/goals/*.json` and alerts only while the dedicated Goal is `active`. `paused`, `waiting_user`, `blocked`, budget/usage-limited, and completed Goals do not alert. A stall episode is based on durable Goal activity (`updatedAt`, progress/revision changes); OpenCode session `updated` time is included only as corroborating telemetry because it is not reliable enough to be the stall authority on every host version.
+
+Episode state is stored separately in `.opencode/opencode-loop/pulse-check.json`. The checker never writes Goal state, never dispatches a prompt, never runs `/goal resume`, and therefore does not participate in the prompt-producing Goal-overlap guard. It emits at most one alert per stall episode and re-arms after observed Goal activity or a status change. The alert explicitly names the human recovery action: run `/goal resume` in the Goal's session.
+
 Windows Task Scheduler:
 
 ```powershell

package/examples/OPENCODE2-0.6.0.md

@@ -0,0 +1,54 @@
+# OpenCode Loop 0.6.0
+
+Native OpenCode 2 release, paired with OpenCode Goal 1.3.39.
+
+## Included behavior
+
+The default installer uses the standalone native V2 entry and preserves plugin
+object options. Explicit V1 compatibility remains available. Native prompt
+admission, durable execution/compaction boundaries and exclusive Goal ownership
+prevent a second continuation owner or aborts caused by synthetic user-role text.
+
+All ten non-Goal presets share schedule parsing, including every/after/in and
+delayed one-shot behavior. /loop-init creates only missing project-local progress
+files, preserves existing bytes and rejects control-plane and symlink escapes.
+Commands resolve their session's actual location rather than a different worktree.
+
+Local scheduled shell work has bounded process-tree cleanup. Plugin teardown and
+partial setup attempt all cleanup without hanging on the event subscription.
+Goal live/archive/lease/queue state cannot satisfy --until; explicit until.txt and
+user-owned project progress files remain valid markers.
+
+Goal 1.3.39 adds the native sidebar, location-bound read-only status RPC, late-result
+handoff guards and full-contract three-session checks. Goal IDs, evidence and
+cumulative budgets remain durable across session rotation.
+
+## Publication and verification
+
+The release no longer creates a release branch. An explicit main release request
+runs Windows/Linux bundle, test and installed-package gates; actual production
+Loop and Goal tarballs are exercised together on OpenCode 2.0.18. Normal CI for the
+same immutable commit must also pass. Only then does the existing OIDC publisher
+publish 0.6.0. Existing npm versions must match their source SHA, not merely version.
+
+Registry latest, gitHead, exports, bins and integrity are checked after publication.
+A clean consumer installs both published packages from npm and re-runs native
+installation, actual-host commands and the two-turn single-session daemon.
+The GitHub tag/release follows those checks in a separate least-privilege job.
+
+## Host capability boundaries
+
+OpenCode 2.0.18 is the exact native integration baseline. Its published plugin
+context does not expose session.compact, so scheduled /loop-compact is rejected
+before durable job creation rather than silently ignored. Automatic compaction is
+host-owned. Legacy Loop Goal records are preserved, not silently converted into
+dedicated Goal contracts. Real-model cost and long-duration reliability are not
+claimed by deterministic local-provider canaries.
+
+Install the published pair after successful registry verification:
+
+```sh
+npx -y @bybrawe/opencode-loop@0.6.0 --with-goals --without-loop-goals
+```
+
+Fully restart OpenCode after installation. Existing project state is preserved.

package/examples/OPENCODE2-0.6.1.md

@@ -0,0 +1,60 @@
+# OpenCode Loop 0.6.1
+
+Official OpenCode 2 plugin-definition release, paired with OpenCode Goal 1.3.40.
+
+## V2 package and local entrypoints
+
+The npm root/server entry and the explicit `./v2` entry now use
+`@opencode/plugin` `Plugin.define({ id, setup })`. V1 `server()` compatibility
+remains a separate implementation rather than an adapter that translates V1 hooks.
+
+A native local install uses the same contract. It creates
+`plugins/opencode-loop/index.js` as the real V2 entrypoint and keeps the generated
+single-file runtime beside it as `native.js`, where it is a support module rather
+than a second auto-discovered plugin. Upgrades remove the old root
+`opencode-loop.ts`/JS copies; explicit `--legacy-v1` still installs the V1 path.
+
+## Runtime and packaging
+
+`@opencode/plugin@^2.0.18` is a production dependency and its required runtime
+peer closure is locked for reproducible npm installs. Clean Windows package smoke
+keeps all previous assertions but permits six minutes for the larger V2 dependency
+graph to install.
+
+The native prompt, command, scheduling, session-location, process-tree, Goal
+ownership, compaction-safety and `--until` control-state protections from 0.6.0
+remain unchanged.
+
+## Paired Goal release
+
+Goal 1.3.40 defines its server, native-only and TUI entries with the official V2
+plugin APIs while preserving separate V1 compatibility. Loop publication is pinned
+to Goal's immutable 1.3.40 source and refuses publication until that exact package
+is visible on npm.
+
+## Publication and verification
+
+The main-only OIDC publisher requires Windows/Linux installed-package gates plus
+normal exact-main CI and Native V2 CI. It builds the declared Goal source, installs
+the actual Loop and Goal tarballs together, and exercises them on OpenCode 2.0.18.
+
+After publication, registry latest, gitHead, exports, bins and integrity are checked.
+A fresh npm consumer then installs Loop 0.6.1 and Goal 1.3.40 and re-runs joint
+installation/options/uninstall, real native commands and the two-turn
+single-session daemon before the GitHub v0.6.1 tag/release is created.
+
+## Capability boundary
+
+OpenCode 2.0.18's published plugin context still does not expose
+`session.compact`; scheduled `/loop-compact` therefore rejects before durable job
+creation while automatic compaction stays host-owned. Controlled-provider canaries
+are functional verification, not live-model cost or endurance measurements.
+
+Install the verified pair after registry publication:
+
+```sh
+npx -y @bybrawe/opencode-goal@1.3.40
+npx -y @bybrawe/opencode-loop@0.6.1 --loop-only --without-loop-goals
+```
+
+Fully restart OpenCode after installation. Existing project state is preserved.

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.38",
+  "version": "0.6.1",
   "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",
+  "main": "src/plugin.js",
   "exports": {
-    ".": "./src/index.js",
-    "./server": "./src/server.js"
+    ".": "./src/plugin.js",
+    "./server": "./src/plugin.js",
+    "./v2": "./src/v2.js",
+    "./v1": "./src/index.js"
   },
   "files": [
     "src",
@@ -19,14 +21,15 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build:plugin": "bun build src/source/v1.js --outfile=src/index.js --target=bun --format=esm --external=@opencode-ai/plugin/tool && bun build src/source/server.js --outfile=src/server.js --target=bun --format=esm --external=@opencode-ai/plugin/tool",
+    "build:plugin": "bun build src/source/v1.js --outfile=src/index.js --target=bun --format=esm --external=@opencode-ai/plugin/tool && bun build src/source/server.js --outfile=src/server.js --target=bun --format=esm --external=@opencode-ai/plugin/tool && bun build src/source/native.js --outfile=src/native.js --target=bun --format=esm",
     "build:plugin:npm": "npm run build:plugin",
-    "prepack": "node --check src/index.js && node --check src/server.js",
-    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/continuation.js && node --check src/source/core/schedule-syntax.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/schedule-policy.js && node --check src/source/runtime/scheduler-diagnostics.js && node --check src/source/runtime/companion-goal.js && node --check src/source/runtime/loop-diagnostics.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/action-dispatch.js && node --check src/source/runtime/network-recovery.js && node --check src/source/runtime/empty-turn.js && node --check src/source/runtime/terminal-guard.js && node --check src/source/runtime/run-finalization.js && node --check src/source/runtime/run-admission.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-prompt.js && node --check src/source/runtime/goal-report.js && node --check src/source/runtime/goal-evidence.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/server.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check src/server.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/server-entry-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/schedule-syntax-test.mjs && node --check scripts/schedule-policy-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/session-status-idle-recovery-test.mjs && node --check scripts/session-error-recovery-test.mjs && node --check scripts/empty-turn-recovery-test.mjs && node --check scripts/network-recovery-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/server-entry-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/schedule-syntax-test.mjs && node scripts/schedule-policy-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/session-status-idle-recovery-test.mjs && node scripts/session-error-recovery-test.mjs && node scripts/empty-turn-recovery-test.mjs && node scripts/network-recovery-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/action-dispatch-test.mjs && node scripts/run-finalization-test.mjs && node scripts/run-admission-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",
+    "prepack": "node --check src/plugin.js && node --check src/v2.js && node --check src/index.js && node --check src/server.js && node --check src/native.js",
+    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/continuation.js && node --check src/source/core/schedule-syntax.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/schedule-policy.js && node --check src/source/runtime/scheduler-diagnostics.js && node --check src/source/runtime/companion-goal.js && node --check src/source/runtime/loop-diagnostics.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/action-dispatch.js && node --check src/source/runtime/network-recovery.js && node --check src/source/runtime/empty-turn.js && node --check src/source/runtime/terminal-guard.js && node --check src/source/runtime/run-finalization.js && node --check src/source/runtime/run-admission.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-prompt.js && node --check src/source/runtime/goal-report.js && node --check src/source/runtime/goal-evidence.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/server.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check src/server.js && node --check scripts/install-node.mjs && node --check scripts/install-with-goals.mjs && node --check scripts/loopd.mjs && node --check scripts/pulse-check.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/server-entry-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/schedule-syntax-test.mjs && node --check scripts/schedule-policy-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/session-status-idle-recovery-test.mjs && node --check scripts/session-error-recovery-test.mjs && node --check scripts/empty-turn-recovery-test.mjs && node --check scripts/network-recovery-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 && node --check scripts/goal-compaction-safety-test.mjs && node --check src/source/native.js && node --check src/source/opencode2/native-plugin.js && node --check src/source/opencode2/native-runtime.js && node --check src/source/opencode2/native-policy.js && node --check src/native.js && node --check scripts/native-entry-test.mjs && node --check scripts/package-native-smoke.mjs && node --check src/v1.js && node --check scripts/native-cli-io-test.mjs && node --check scripts/native-lifecycle-test.mjs && node --check scripts/native-plugin-lifetime-test.mjs && node --check src/source/core/progress.js && node --check scripts/native-presets-test.mjs && node --check scripts/control-plane-until-test.mjs && node --check src/source/opencode2/session-location.js && node --check scripts/native-session-location-test.mjs && node --check src/plugin.js && node --check src/v2.js",
+    "test": "node --test scripts/native-session-location-test.mjs && node --test scripts/control-plane-until-test.mjs && node --test scripts/native-presets-test.mjs && node --test scripts/native-plugin-lifetime-test.mjs && node --test scripts/native-cli-io-test.mjs scripts/native-lifecycle-test.mjs && node scripts/native-entry-test.mjs && node scripts/native-coexistence-test.mjs && node scripts/native-shell-test.mjs && node scripts/native-install-test.mjs && node scripts/native-v2-test.mjs && node scripts/goal-compaction-safety-test.mjs && node scripts/publish-workflow-test.mjs && node scripts/server-entry-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/schedule-syntax-test.mjs && node scripts/schedule-policy-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/session-status-idle-recovery-test.mjs && node scripts/session-error-recovery-test.mjs && node scripts/empty-turn-recovery-test.mjs && node scripts/network-recovery-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/action-dispatch-test.mjs && node scripts/run-finalization-test.mjs && node scripts/run-admission-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-with-goals.mjs",
-    "pack:zip": "node scripts/make-zip.mjs"
+    "pack:zip": "node scripts/make-zip.mjs",
+    "package:smoke": "node scripts/package-native-smoke.mjs"
   },
   "keywords": [
     "opencode",
@@ -70,5 +73,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.18"
   }
 }

package/scripts/branch-hygiene.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+import { appendFile } from "node:fs/promises"
+import process from "node:process"
+
+function sameRepositoryHead(pull, repository) {
+  return pull?.head?.repo?.full_name === repository
+}
+
+function encodeRef(name) {
+  return String(name || "").split("/").map(encodeURIComponent).join("/")
+}
+
+function validSha(value) {
+  return /^[0-9a-f]{40}$/i.test(String(value || ""))
+}
+
+export function planBranchCleanup({ repository, defaultBranch, branches, openPulls, closedPulls }) {
+  const openHeads = new Set(
+    openPulls
+      .filter((pull) => sameRepositoryHead(pull, repository))
+      .map((pull) => String(pull?.head?.ref || "").trim())
+      .filter(Boolean),
+  )
+
+  const mergedHeads = new Map()
+  for (const pull of closedPulls) {
+    if (!pull?.merged_at || !sameRepositoryHead(pull, repository)) continue
+    const name = String(pull?.head?.ref || "").trim()
+    const sha = String(pull?.head?.sha || "").trim()
+    if (!name || !sha) continue
+    const values = mergedHeads.get(name) || []
+    values.push({ sha, number: pull.number })
+    mergedHeads.set(name, values)
+  }
+
+  const candidates = []
+  const retained = []
+  for (const branch of branches) {
+    const name = String(branch?.name || "").trim()
+    const sha = String(branch?.commit?.sha || "").trim()
+    if (!name || !sha) continue
+    if (name === defaultBranch) {
+      retained.push({ name, reason: "default" })
+      continue
+    }
+    if (branch?.protected === true) {
+      retained.push({ name, reason: "protected" })
+      continue
+    }
+    if (openHeads.has(name)) {
+      retained.push({ name, reason: "open-pr" })
+      continue
+    }
+
+    const merged = (mergedHeads.get(name) || []).find((entry) => entry.sha === sha)
+    if (!merged) {
+      retained.push({ name, reason: "no-exact-merged-head" })
+      continue
+    }
+    candidates.push({ name, sha, pull: merged.number, source: "merged-pr" })
+  }
+
+  candidates.sort((a, b) => a.name.localeCompare(b.name))
+  retained.sort((a, b) => a.name.localeCompare(b.name))
+  return { candidates, retained }
+}
+
+export function planArchivedCleanup({
+  repository,
+  defaultBranch,
+  archiveRef,
+  manifest,
+  branches,
+  openPulls,
+}) {
+  if (!manifest || typeof manifest !== "object") throw new Error("archive manifest must be an object")
+  if (manifest.repository !== repository) throw new Error(`archive manifest repository mismatch: ${manifest.repository}`)
+  if (manifest.archiveBranch !== archiveRef) throw new Error(`archive manifest branch mismatch: ${manifest.archiveBranch}`)
+  if (!Array.isArray(manifest.archivedBranches)) throw new Error("archive manifest archivedBranches must be an array")
+
+  const branchByName = new Map(
+    branches
+      .map((branch) => [String(branch?.name || "").trim(), branch])
+      .filter(([name]) => Boolean(name)),
+  )
+  const openHeads = new Set(
+    openPulls
+      .filter((pull) => sameRepositoryHead(pull, repository))
+      .map((pull) => String(pull?.head?.ref || "").trim())
+      .filter(Boolean),
+  )
+
+  const seenNames = new Set()
+  const candidates = []
+  const retained = []
+
+  for (const entry of manifest.archivedBranches) {
+    const name = String(entry?.name || "").trim()
+    const sha = String(entry?.sha || "").trim()
+    if (!name || !validSha(sha)) throw new Error(`invalid archived branch entry: ${JSON.stringify(entry)}`)
+    if (seenNames.has(name)) throw new Error(`duplicate archived branch entry: ${name}`)
+    seenNames.add(name)
+
+    if (name === defaultBranch || name === archiveRef) {
+      retained.push({ name, reason: "reserved" })
+      continue
+    }
+
+    const branch = branchByName.get(name)
+    if (!branch) {
+      retained.push({ name, reason: "already-absent" })
+      continue
+    }
+    if (branch?.protected === true) {
+      retained.push({ name, reason: "protected" })
+      continue
+    }
+    if (openHeads.has(name)) {
+      retained.push({ name, reason: "open-pr" })
+      continue
+    }
+
+    const currentSha = String(branch?.commit?.sha || "").trim()
+    if (currentSha !== sha) {
+      retained.push({ name, reason: "head-changed", expectedSha: sha, currentSha })
+      continue
+    }
+
+    candidates.push({ name, sha, source: "archive-manifest" })
+  }
+
+  candidates.sort((a, b) => a.name.localeCompare(b.name))
+  retained.sort((a, b) => a.name.localeCompare(b.name))
+  return { candidates, retained }
+}
+
+async function request({ api, token }, method, pathname) {
+  const response = await fetch(`${api}${pathname}`, {
+    method,
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${token}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+      "User-Agent": "opencode-branch-hygiene",
+    },
+  })
+  if (response.status === 204) return undefined
+  const raw = await response.text()
+  if (!response.ok) {
+    throw new Error(`${method} ${pathname} failed (${response.status}): ${raw.slice(0, 1000)}`)
+  }
+  return raw ? JSON.parse(raw) : undefined
+}
+
+async function paginate(client, pathname, query = {}) {
+  const values = []
+  for (let page = 1; page <= 100; page += 1) {
+    const params = new URLSearchParams({
+      ...Object.fromEntries(Object.entries(query).map(([key, value]) => [key, String(value)])),
+      per_page: "100",
+      page: String(page),
+    })
+    const batch = await request(client, "GET", `${pathname}?${params}`)
+    if (!Array.isArray(batch)) throw new Error(`Expected an array from ${pathname}`)
+    values.push(...batch)
+    if (batch.length < 100) return values
+  }
+  throw new Error(`Pagination safety limit exceeded for ${pathname}`)
+}
+
+async function loadArchive(client, root, repository, archiveRef) {
+  if (!archiveRef) return null
+
+  const archivePath = "archive/legacy-branches-2026-09-21.json"
+  const encodedRef = encodeURIComponent(archiveRef)
+  const payload = await request(client, "GET", `${root}/contents/${archivePath}?ref=${encodedRef}`)
+  if (payload?.encoding !== "base64" || typeof payload?.content !== "string") {
+    throw new Error("archive manifest content is not base64")
+  }
+
+  const raw = Buffer.from(payload.content.replace(/\s+/g, ""), "base64").toString("utf8")
+  const manifest = JSON.parse(raw)
+  if (manifest.repository !== repository) throw new Error("archive manifest repository does not match current repository")
+  if (manifest.archiveBranch !== archiveRef) throw new Error("archive manifest archiveBranch does not match configured ref")
+
+  const ref = await request(client, "GET", `${root}/git/ref/heads/${encodeRef(archiveRef)}`)
+  const archiveSha = String(ref?.object?.sha || "").trim()
+  if (!validSha(archiveSha)) throw new Error("archive branch did not resolve to a commit SHA")
+
+  return { manifest, archiveSha, archivePath }
+}
+
+async function verifyArchivedReachability(client, root, archiveSha, items) {
+  const verified = []
+  for (const item of items) {
+    const compare = await request(client, "GET", `${root}/compare/${item.sha}...${archiveSha}`)
+    if (!["ahead", "identical"].includes(compare?.status)) {
+      throw new Error(`archive ref does not retain ${item.name} @ ${item.sha}; compare status=${compare?.status || "unknown"}`)
+    }
+    verified.push(item)
+  }
+  return verified
+}
+
+async function deleteCandidates(client, root, items, dryRun, label) {
+  const deleted = []
+  const skipped = []
+  const failures = []
+
+  for (const item of items) {
+    console.log(`${dryRun ? "DRY-RUN" : "DELETE"} [${label}] ${item.name} @ ${item.sha}`)
+    if (dryRun) continue
+
+    try {
+      const encodedRef = encodeRef(item.name)
+      const refPath = `${root}/git/ref/heads/${encodedRef}`
+      const current = await request(client, "GET", refPath)
+      const currentSha = String(current?.object?.sha || "").trim()
+      if (currentSha !== item.sha) {
+        console.log(`SKIP [${label}] ${item.name}: head changed from ${item.sha} to ${currentSha || "unknown"}`)
+        skipped.push({ ...item, reason: "head-changed-at-delete", currentSha })
+        continue
+      }
+      await request(client, "DELETE", `${root}/git/refs/heads/${encodedRef}`)
+      deleted.push(item)
+    } catch (error) {
+      failures.push({ item, error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  return { deleted, skipped, failures }
+}
+
+function countReasons(items) {
+  return Object.fromEntries(
+    [...new Set(items.map((item) => item.reason))]
+      .sort()
+      .map((reason) => [reason, items.filter((item) => item.reason === reason).length]),
+  )
+}
+
+async function main() {
+  const repository = String(process.env.GITHUB_REPOSITORY || "").trim()
+  const token = String(process.env.GITHUB_TOKEN || "").trim()
+  const api = String(process.env.GITHUB_API_URL || "https://api.github.com").replace(/\/$/, "")
+  const defaultBranch = String(process.env.BRANCH_HYGIENE_DEFAULT_BRANCH || "main").trim()
+  const archiveRef = String(process.env.BRANCH_HYGIENE_ARCHIVE_REF || "").trim()
+  const dryRun = process.env.BRANCH_HYGIENE_DRY_RUN === "1"
+
+  if (!/^[^/]+\/[^/]+$/.test(repository)) throw new Error("GITHUB_REPOSITORY must be owner/name")
+  if (!token) throw new Error("GITHUB_TOKEN is required")
+  if (!defaultBranch) throw new Error("default branch is required")
+
+  const client = { api, token }
+  const root = `/repos/${repository}`
+  const [branches, openPulls, closedPulls] = await Promise.all([
+    paginate(client, `${root}/branches`),
+    paginate(client, `${root}/pulls`, { state: "open" }),
+    paginate(client, `${root}/pulls`, { state: "closed" }),
+  ])
+
+  const mergedPlan = planBranchCleanup({
+    repository,
+    defaultBranch,
+    branches,
+    openPulls,
+    closedPulls,
+  })
+
+  let archivePlan = { candidates: [], retained: [] }
+  let archiveSha = ""
+  if (archiveRef) {
+    const archive = await loadArchive(client, root, repository, archiveRef)
+    archiveSha = archive.archiveSha
+    archivePlan = planArchivedCleanup({
+      repository,
+      defaultBranch,
+      archiveRef,
+      manifest: archive.manifest,
+      branches,
+      openPulls,
+    })
+    await verifyArchivedReachability(client, root, archiveSha, archivePlan.candidates)
+  }
+
+  const mergedResult = await deleteCandidates(client, root, mergedPlan.candidates, dryRun, "merged-pr")
+
+  const mergedNames = new Set(mergedPlan.candidates.map((item) => item.name))
+  const archiveCandidates = archivePlan.candidates.filter((item) => !mergedNames.has(item.name))
+  const archiveResult = await deleteCandidates(client, root, archiveCandidates, dryRun, "archive")
+
+  const failures = [...mergedResult.failures, ...archiveResult.failures]
+  const summary = [
+    "## Branch hygiene",
+    "",
+    `- Repository: \`${repository}\``,
+    `- Default branch: \`${defaultBranch}\``,
+    `- Branches scanned: ${branches.length}`,
+    `- Exact merged-head candidates: ${mergedPlan.candidates.length}`,
+    `- Archived inactive candidates: ${archiveCandidates.length}`,
+    `- Archive ref: \`${archiveRef || "disabled"}\``,
+    `- Archive SHA: \`${archiveSha || "n/a"}\``,
+    `- Deleted: ${dryRun ? 0 : mergedResult.deleted.length + archiveResult.deleted.length}`,
+    `- Dry run: ${dryRun}`,
+    `- Retained merged-plan reasons: \`${JSON.stringify(countReasons(mergedPlan.retained))}\``,
+    `- Retained archive-plan reasons: \`${JSON.stringify(countReasons(archivePlan.retained))}\``,
+    "",
+    "Safety rules: merged branches require an exact merged-PR head SHA. Archived branches additionally require an unchanged current SHA, no open PR, and proof that the archived tip is an ancestor of the configured archive ref before deletion.",
+  ].join("\n")
+
+  if (process.env.GITHUB_STEP_SUMMARY) await appendFile(process.env.GITHUB_STEP_SUMMARY, `${summary}\n`, "utf8")
+  console.log(summary)
+
+  if (failures.length) {
+    for (const failure of failures) console.error(`FAILED ${failure.item.name}: ${failure.error}`)
+    throw new Error(`Failed to delete ${failures.length} eligible branch(es)`)
+  }
+}
+
+const invokedDirectly = process.argv[1] && new URL(import.meta.url).pathname.endsWith(process.argv[1].replaceAll("\\", "/"))
+if (invokedDirectly) {
+  main().catch((error) => {
+    console.error(error?.stack || error)
+    process.exitCode = 1
+  })
+}

package/scripts/comprehensive-test.mjs

@@ -373,9 +373,12 @@ async function testActionRoutingAndSafety() {
     await fs.writeFile(path.join(h.directory, "empty.md"), "fallback context", "utf8")
     await h.command("loop-command", "0s --prompt-file empty.md")
     await h.command("loop-now", "command")
-    const state = await h.readState()
-    assert.equal(state.jobs[0].paused, true)
-    assert.equal(state.jobs[0].lastFailureReason, "empty_command")
+    const state = await waitForValue(async () => {
+      const candidate = await h.readState()
+      return candidate.jobs[0]?.paused === true && candidate.jobs[0]?.lastFailureReason === "empty_command" ? candidate : undefined
+    }, 2_000)
+    assert.equal(state?.jobs[0]?.paused, true)
+    assert.equal(state?.jobs[0]?.lastFailureReason, "empty_command")
   } finally {
     await h.cleanup()
   }
@@ -384,9 +387,12 @@ async function testActionRoutingAndSafety() {
   try {
     await h.command("loop-compact", "0s")
     await h.command("loop-now", "compact")
-    const state = await h.readState()
-    assert.equal(state.jobs[0].paused, true)
-    assert.equal(state.jobs[0].lastFailureReason, "compact_failed")
+    const state = await waitForValue(async () => {
+      const candidate = await h.readState()
+      return candidate.jobs[0]?.paused === true && candidate.jobs[0]?.lastFailureReason === "compact_failed" ? candidate : undefined
+    }, 2_000)
+    assert.equal(state?.jobs[0]?.paused, true)
+    assert.equal(state?.jobs[0]?.lastFailureReason, "compact_failed")
   } finally {
     await h.cleanup()
   }