@sorenllm/opencode-forge 0.2.2 → 0.3.0

package/README.md

@@ -80,7 +80,20 @@ the plugin never writes them):
       "disable": true              // one-knob return to native: no forge,
                                    // build/plan restored, no tools/commands
     }
-  }
+  },
+  // per-plugin options ride the plugin entry as a [spec, options] tuple
+  "plugin": [
+    ["@sorenllm/opencode-forge", {
+      "jobs": {
+        "mode": "auto",              // "auto" (default) | "forge" | "native" — see the stage matrix below
+        "keepBuiltinShell": false    // stage 0: keep the builtin shell visible alongside forge_shell
+      },
+      "watchdog": {
+        "mode": "kill",              // "kill" (default) | "dry-run" | "off"
+        "stallMs": 600000            // stall threshold, min 60000
+      }
+    }]
+  ]
 }
 ```
 
@@ -100,6 +113,9 @@ and the plugin's command of that name is not registered.
 4. Done — the hidden native `build`/`plan` agents come back automatically
    (the hide was runtime-only). Your `.opencode/plan/` and `.opencode/goal/`
    files are yours; delete them yourself if you want.
+5. Optional runtime debris: delete `<tmp>/opencode-forge/` (job logs, the
+   job registry ledger, and the watchdog ledger — the file ledger table
+   above lists everything).
 
 ## File ledger
 
@@ -109,7 +125,10 @@ What this plugin touches, exhaustively:
 | --- | --- | --- |
 | `<project>/.opencode/plan/*.md` | plan files | user data — kept forever, uninstall never deletes |
 | `<project>/.opencode/goal/*.md` | goal files (contract, Check Log, Turn Ledger) | user data — kept forever, uninstall never deletes |
-| merged config object (RAM only) | forge agent, native build/plan `disable`, `command.plan`, `command.goal`, goal permission keys | vanishes when the plugin is removed; nothing is written to disk |
+| merged config object (RAM only) | forge agent, native build/plan `disable`, `command.plan`, `command.goal`, goal permission keys, `permission.forge_shell`, stage-0 builtin shell hide | vanishes when the plugin is removed; nothing is written to disk |
+| `<tmp>/opencode-forge/jobs/<jobId>.log` | job output tee (full output; oldest rotated out above 50 files) | runtime debris — delete freely, also after uninstall |
+| `<tmp>/opencode-forge/jobs/ledger.jsonl` | job registry ledger (bounded: 1 MB reset, 200 entries) | runtime debris — delete freely, also after uninstall |
+| `<tmp>/opencode-forge/watchdog/log.jsonl` | watchdog interventions ledger (bounded: 200 entries, oldest rotated) | runtime debris — delete freely, also after uninstall |
 | `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
 | `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
 
@@ -187,6 +206,129 @@ They are drafted by the model from your objective. Read them in the dialog
 before allowing the arm; `--contains` contracts are strictly
 workspace-relative (path escape is refused).
 
+## Job supervisor (a shell that can never hang the session)
+
+The builtin `shell` tool treats closed stdio pipes as completion — a
+detached grandchild holding them open suspends the call indefinitely (the
+multi-hour agent hangs behind upstream issues #47350 / #50316 / #49169).
+Subagents have it worse: the native task tool has no timeout at all.
+`forge_shell` is the replacement exec surface for the forge agent.
+
+**`forge_shell`** completes on the FIRST of four conditions, and only the
+exit condition is bound to the actual exit event (structural immunity to
+the stdio-EOF bug):
+
+| condition | knob | on trigger |
+| --- | --- | --- |
+| process exit | — | final; exit code + output tail returned |
+| `success_pattern` regex matches new output | opt-in | completes as success; process kept alive by default (server semantics), `keep_alive: false` kills its tree |
+| `idle_ms` with no new output | default 60000 | early return `still-running` + `jobId`; process stays alive |
+| `max_wait_ms` hard cap | default 120000, max 600000 | early return `still-running`; never kills |
+
+`run_in_background: true` skips all waiting and returns
+`{jobId, logPath}` immediately. Every run pops one permission dialog
+(`permission.forge_shell = "ask"`; an explicit `deny` in your config wins).
+
+**`forge_jobs`** manages the registry: `list` / `poll {jobId, waitMs≤30s}`
+(bounded wait for new output or exit, drains it) / `log {jobId, offset?,
+limit?}` (line paging over the on-disk log) / `kill` (whole process tree) /
+`clear` (drop a finished entry) / `handoff` (rebind ownership to the root
+session so a subagent's job survives the subagent). Delegated agents are
+instructed to poll their jobs before yielding a conclusion.
+
+**Exit wakes.** A job that exits after its `forge_shell` call already
+returned queues a single `[forge:job-complete]` message, delivered into the
+owning session via `promptAsync` the next time it goes idle (exactly once;
+`notify: false` opts out per job).
+
+**Ownership.** Jobs belong to the session that created them. Session
+deleted → its live session-scoped jobs are killed and the event is recorded
+in a bounded ledger (`handoff` beforehand survives). Plugin unload disposes
+everything it still owns.
+
+### Stage matrix (future compatibility, by design)
+
+OpenCode upstream is converging on native backgrounding (PRs #47231 /
+#50276, umbrella #34366). The supervisor degrades ahead of it:
+
+| stage | how you get there | builtin shell | forge_shell / forge_jobs |
+| --- | --- | --- | --- |
+| 0 — full forge path | default (`jobs.mode: "auto"`, no native support detected) | hidden on the plugin-created forge agent (runtime injection only) | registered; the exec surface |
+| 1 — native backgrounding detected | automatic: `config.experimental` background flag, or the builtin shell's schema grows `run_in_background` | visible again | still registered as the additive layer (idle/success/wake supervision); its description now points plain backgrounding at the native parameter |
+| 2 — native confirmed complete | manual only: `jobs.mode: "native"` (never auto-detected — completeness is a semantic judgement) | visible | retired; calls throw with a pointer to the native parameter |
+
+Pin `jobs.mode: "forge"` to stay on stage 0 forever; `jobs.keepBuiltinShell:
+true` keeps the builtin shell visible at any stage.
+
+### Artifacts and uninstall additions
+
+Job output tees to `<tmp>/opencode-forge/jobs/<jobId>.log` (oldest rotated
+out above 50 files) and registry events append to
+`<tmp>/opencode-forge/jobs/ledger.jsonl` (bounded, 1 MB reset, 200 entries).
+These are runtime debris, not data: deleting the directory after uninstall
+is safe and complete.
+
+## Hang watchdog (a stuck builtin shell unblocks itself)
+
+`forge_shell` is structurally immune to the stdio-EOF hang, but the builtin
+`shell`/`bash` tool can still hang outside it — user-defined agents keep
+the builtin shell, and the stage matrix above restores it at stage 1/2.
+The watchdog is the independent backstop for those paths, in **every**
+session (primary and delegated subagents alike):
+
+1. The host's shell environment hook stamps each builtin shell call's
+   process with a plugin-namespaced marker (`FORGE_WATCHDOG_MARK`), and the
+   call is timed from start to end.
+2. At 80% of the stall budget: a diagnostic entry (the session is busy —
+   injecting a message would just queue, so nothing is sent to it).
+3. At `watchdog.stallMs` (default 600000): the call's process tree is
+   located and **killed** — the pipes hit EOF and the pending tool call
+   resolves immediately with whatever output was captured.
+4. If the call still hasn't returned after the kill, or no matching
+   process exists (a hang with nothing to kill): an honest
+   diagnostics-only `unresolved` report.
+
+Location is exact where foreign process environments are readable (POSIX
+`/proc/*/environ` marker match). On Windows they are not readable, so the
+watchdog infers in two guarded waves, both restricted to processes created
+during the stalled call: wave 1 matches descendants of the opencode host
+process or processes whose command line carries the stalled call's own
+command text; wave 2 — only when wave 1 found nothing, or killed and the
+call still didn't return within the observation window — additionally
+matches processes whose command lives in the stalled command's own
+directory, which is exactly where the detached stdio holders of the
+exit-with-inherited-stdio hang class sit. The locator never targets its
+own probe processes, console hosts (`conhost.exe`), or anything created
+before the call's time window. If the shell environment hook itself ever
+stops firing (host API drift), the watchdog detects the missing marker and
+degrades itself to dry-run instead of killing by inference alone.
+
+**Modes** (`watchdog.mode`, default `kill`): `dry-run` records the exact
+process list it *would* terminate and kills nothing — recommended for a
+first observation round on a new host; `off` disables timing entirely.
+`watchdog.stallMs` is clamped to a 60 s protection floor. Invalid option
+values fall back to the defaults and the fallback is ledgered.
+
+**Known trade-off.** The builtin shell exposes no output visibility, so
+the watchdog cannot tell "hung" from "quietly working" — a legitimate
+silent command longer than the threshold will be killed. That is the
+deliberated price of stopping multi-hour hangs; the guidance layer already
+routes legitimate long-running work to `forge_shell`, which has real idle
+detection. On Windows, concurrent builtin shell calls started inside the
+same window are inferred together (the rare case) — `dry-run` makes the
+exact blast radius auditable before you trust `kill`.
+
+**Retiring it.** When upstream ships exit-based completion for the builtin
+shell, switch `watchdog.mode` to `dry-run` for an observation round, then
+`off`.
+
+### Watchdog ledger
+
+Every intervention (warn / kill / dry-run candidate / unresolved /
+config fallback) appends to `<tmp>/opencode-forge/watchdog/log.jsonl`
+(bounded: 200 entries, oldest rotated out). Deleting the directory after
+uninstall is safe and complete.
+
 ## Design stance (read before filing "bash is blocked" issues)
 
 During a plan's draft phase every mutating tool — `bash` included — is
@@ -195,6 +337,12 @@ read/grep/glob; if you genuinely need a shell command to decide the plan,
 approve the plan first (revising after approval is allowed via a new `/plan`).
 The escape hatches are `plan_approve` and `/plan discard`, by design.
 
+Separately, at stage 0 the builtin shell is hidden on the plugin-created
+forge agent on purpose — `forge_shell` is the exec surface there (see the
+job supervisor chapter above). A **user-defined** `agent.forge` entry,
+`jobs.keepBuiltinShell: true`, or any stage ≥ 1 keeps the builtin shell
+visible.
+
 A process restart forgets the session binding: the write-ban soft-disables
 (safety over strictness) and the next session's system notice + `/plan
 resume` re-bind from the plan file on disk, which is the source of truth.
@@ -214,7 +362,9 @@ carry their own full discipline, hermes-style: the entry turn is the
 rulebook) + `src/plan-file.ts` / `src/goal-file.ts`
 (pure document cores, unit-tested, no opencode imports) + `src/run-check.ts`
 (shell/file-contract runner with tree-kill timeouts and a workspace path
-guard). Behavioral changes go through the
+guard) + `src/proc.ts` (shared spawn/tree-kill muscle) + `src/job-manager.ts`
+(job registry, ownership, wake queue — pure logic) + `src/job-runner.ts`
+(four-condition race, pipe capture, log tee). Behavioral changes go through the
 OpenSpec workflow in `openspec/` — see AGENTS.md. Common pitfalls live in
 `../opencode-plugin-dev-pitfalls.md`.