@giamme/forge 0.8.0 → 0.9.0

package/docs/safety.md

@@ -0,0 +1,55 @@
+# Safety
+
+[← README](../README.md) · [All docs](README.md)
+
+What forge never does to your branch and working tree, what it refuses to run on, and how it keeps reviewed work and merged work the same.
+
+## Safety guarantees
+
+- Solo runs leave source changes uncommitted. Forge creates private review commits, but
+  does not commit on the solo source branch, push, or reset the user tree.
+- In a decomposed run, commits and merges happen **only** on the `forge/<run-id>/*` task
+  branches and the `forge/<run-id>-integration` branch — branches forge created for itself.
+  Never your branch, never a push. Your branch and working tree are untouched for the whole
+  run.
+- Bypass flags are never added on forge's own initiative. `--yolo-dwarf` / `--yolo-qa` are the
+  only route to an unsandboxed run, so that choice is always explicit and visible.
+- **One dwarf per working tree, always.** Two agents editing one tree interleave their edits
+  into a diff neither of them wrote and qa cannot untangle. Parallelism comes from separate
+  worktrees, which is why worktrees are mandatory there rather than an optimization.
+- A failed task's branch and worktree are **never** deleted — they're the only record of what
+  went wrong and the only thing to retry from. A successful task's worktree is removed only
+  after `results.tsv` is written and read back.
+- QA runs in a disposable repository. Mutations to the source or review snapshot invalidate
+  acceptance. Disabled editing tools alone do not prevent writes through Bash.
+
+## Preconditions
+
+- Not a git repo → decomposed runs refuse. Worktrees are impossible and there's no honest
+  fallback.
+- Uncommitted changes → **warned prominently.** Worktrees branch from a commit, so your local
+  edits are invisible to every dwarf. This is the likeliest route to a confusingly wrong
+  result.
+
+## Execution integrity
+
+Forge now captures solo changes against a recorded starting snapshot, including staged edits,
+without altering the user's index. Existing work is recorded separately in `existing.diff`.
+QA receives the full implementation requirements and reviews a disposable repository; source
+or snapshot changes invalidate the result. Only the recorded reviewed task commit can merge.
+
+Parallel execution rechecks dependencies before each task and retry. Failed prerequisites leave
+consumers BLOCKED. Directory and child file declarations are serialized.
+
+`forge-dispatch.sh doctor --spec sol --role dwarf` validates a selected model recipe using local
+CLI help. Solo and parallel runners preflight the whole selected pipeline before implementation.
+These checks do not establish authentication, billing or live model availability.
+
+Use `forge-parallel.sh run <plan> --verify 'your check command'` or put the command in
+`.forge/verify` to verify the combined result. Output and exit status are saved with the plan.
+Integration checks a candidate containing the current user branch before updating it. A missing
+command is reported as UNVERIFIED; a failing configured check blocks integration. The project's
+own test suites that the command does not run are named as warnings (advisory), and a failing
+command is rerun once so a flaky lane is reported rather than failing the run — see
+[verification coverage and flaky reruns](reviews.md#verification-coverage-and-flaky-reruns).
+`integrate` also names any task that is not merged and therefore not part of what it delivers.

package/docs/troubleshooting.md

@@ -0,0 +1,54 @@
+# Troubleshooting
+
+[← README](../README.md) · [All docs](README.md)
+
+Symptoms, causes and fixes, from a skill a harness cannot see to a task that will not merge.
+
+| Symptom | Cause / fix |
+|---|---|
+| skill missing in **codex** only | frontmatter isn't strict YAML. Codex refuses to load and logs `invalid YAML`; the other four are lenient and load it fine. Note codex's line numbers exclude the opening `---`, so its "line 3" is the file's line 4 |
+| skill missing in **antigravity** | `agy` ignores `~/.gemini/skills` entirely — skills load only inside a plugin. Re-run `forge-install.sh` |
+| antigravity runs an **old version** | `agy plugin install` copies. Re-run `forge-install.sh` after every edit |
+| duplicate entry in **opencode** | opencode auto-scans `~/.claude/`; a `~/.config/opencode/command/forge.md` on top is redundant |
+| agy: `Find command timed out` | missing `--add-dir <repo>` — forge passes it; a hand-built command must too |
+| agy dwarf ends with an error and an empty diff | it tried to run a shell command without yolo. A single denial aborts the run — use `--yolo-dwarf` |
+| dwarf produced no changes | usually an ambiguous prompt it couldn't resolve headlessly. Nobody can answer a question mid-run |
+| task status `ERROR` | worktree creation or a dispatch failed — read `tasks/<id>/dwarf.out` / `qa.out` |
+| task status `UNKNOWN` | QA never emitted a verdict line; read `tasks/<id>/qa.last`. `retry` (or `run --retry-failed N`) asks QA again on the unchanged work — no dwarf runs, no attempt is spent |
+| task status `INFRA`, `run` exits `8` | a quota/usage limit, auth problem, rate limit, network error or empty answer stopped a dispatch — not a task failure, and no attempt was spent. Read `tasks/<id>/infra.txt` (`class=`, `retry_after=`), fix the cause, run the same command again. `run --infra-retries M` waits it out instead. Dependents stay `PENDING`, never `BLOCKED` |
+| a task merged although its reviewer said FAIL | `--qa-threshold` accepted it: every CONFIRMED finding was labelled and milder than the threshold. See `tasks/<id>/known_issues.md` and `qa.gate`; nothing is accepted without an explicit threshold |
+| `accept` exits `3` "changed since it was reviewed" | the branch or worktree moved after QA, so accepting would sign off on unreviewed code. `retry` for a fresh review |
+| `combine` / `split` refuses | the message names why: unmerged task left behind, duplicate ids, locked or dirty plan, a Fractal-backed plan, or a selection that strands a dependent. Nothing was changed |
+| `integrate --final-review` stops with exit `5` | the whole-run reviewer found a blocking defect (or never reached a verdict); findings are in `<plan>/…/final-review/qa.last`. Your branch is untouched. Exit `8` means the reviewer hit a quota/auth stop: run it again |
+| `FLAKY` in the summary, verification `PASS` | the verify command failed once and passed on rerun. Read `verification.log` (the first run) — an intermittent failure can be a real bug. `--verify-retries 0` restores the strict single run |
+| `verify coverage: suite '…' is not run by the verify command` | the project defines a suite your `--verify` skips. Advisory only; add it to the command (or `.forge/verify`) if it should gate the merge |
+| implementer guard notes in the summary | the dwarf committed, switched branch, left processes running, or promised later work. Recorded in `tasks/<id>/guard.txt`; the diff and the reviewer still decide. Leftover processes were stopped |
+| task status `CONFLICT` | QA passed but the merge conflicted — `files` was understated somewhere. Check the run's scope-drift list: it usually names the file |
+| task status `TIMEOUT` | that role exceeded the dispatch timeout and was killed. Raise `--timeout`, or `retry` — the partial edit is still in the worktree |
+| a dispatch never returns | it can't any more: every backend is killed at its timeout (`--timeout`, else `FORGE_TIMEOUT`, else the registry's `timeout` column, else 45 min — 60 min for the default `xhigh` QA/planner effort) |
+| a task won't re-run: "already exists" | a worktree directory was deleted by hand. `run` and `retry` prune stale registrations first, so re-run rather than deleting the branch |
+| a failed task is expensive to redo | it isn't — `forge-parallel.sh retry <dir> <id> [--dwarf <spec>]` re-runs that one task with its reviewer's findings, in the worktree it already has |
+| an interrupted run seems lost | run `run` again; merged tasks are skipped, not re-dispatched |
+| every wave has exactly one task | `files` sets overlap across most tasks; the decomposition isn't actually parallel |
+| dwarves reimplement already-merged work | `goal.txt` or `files` missing, so the capsule carries no useful status |
+| several tasks report "produced no changes" | the decomposition made tasks that weren't independently actionable — use a coarser `--decompose-level`, not more retries |
+| `retry` says "produced no new changes" | the dwarf returned a byte-identical diff, so no reviewer was paid to read the same code twice. Escalate with `--dwarf`, or fix the prompt |
+| a new file's code never reached QA | fixed: untracked files are diffed against `/dev/null`. A hand-built capture using only `git status --porcelain` shows the reviewer a filename and no content |
+| claude dwarf ends "I need your permission to edit" | a permission mode that prompts for Edit. forge uses `acceptEdits` plus an explicit Bash allowance, because `auto` allows shell but prompts for Edit, and `acceptEdits` alone allows Edit but prompts for real shell commands |
+| `.forge/` turns up in a review | a diff capture is missing `':(exclude).forge'` |
+| memory stays empty | nothing durable was learned — the common, correct case. The ledger still has a row per dispatch |
+| a wrong fact keeps reappearing | `memory.md` is rebuilt from the ledger; delete the ledger rows, not the memory line |
+| dwarves build incompatible interfaces | the seam was never agreed — plan the approach, or use `--planner` |
+| Fractal was installed but a new unattended run uses ordinary execution | installation never activates it; pass `--fractal` explicitly |
+| `Fractal selected but unavailable` | run `forge fractal doctor`, then the suggested managed install; resume retains the selected backend |
+| existing run rejects a new backend, pool or limit | selection and bounds are recorded; create a new run directory for changed settings |
+| Fractal reports completion but Forge has not accepted the work | inspect QA, verdict and verification; execution completion does not establish acceptance |
+| Fractal import stops with `source_drift` | the source changed after its snapshot; preserve both versions and inspect the candidate instead of forcing import |
+| Fractal work was paused or its coordinator exited | inspect `status` and `logs`, then use explicit `resume RUN_ID`; retry starts a new attempt |
+| browser dashboard closed while work is running | execution is independent; reopen with `forge fractal open RUN_ID` |
+| costs are unknown or a dollar cap is rejected | the bridge only reports available usage; v1 cannot enforce a spending cap |
+
+For per-harness invocation details, effort ladders and known CLI failure modes, see
+[`references/harnesses.md`](../references/harnesses.md). For decomposition mechanics, see
+[`references/decompose.md`](../references/decompose.md). For memory internals, see
+[`references/memory.md`](../references/memory.md).

package/forge

@@ -22,6 +22,7 @@ usage() {
     '  jev       optional Jev advice: setup, status, doctor, enable, disable, backtest' \
     '  dataset   every run'"'"'s inputs and outcomes: status, dump, import, export, outcomes, ...' \
     '  ui        forge-ui, the run viewer: open [DIR], status, stop' \
+    '  runs      this repo'"'"'s recent runs in the terminal: state, verdicts and run dirs' \
     '  update    fast-forward this checkout and refresh every harness installation' \
     '  version   the installed version, and whether a newer release is out' \
     '' \
@@ -50,6 +51,10 @@ case "${1:-}" in
     shift
     exec python3 "$ROOT/scripts/forge-ui.py" "$@"
     ;;
+  runs)
+    shift
+    exec python3 "$ROOT/scripts/forge-runs.py" "$@"
+    ;;
   update)
     shift
     exec /bin/bash "$ROOT/scripts/forge-update.sh" "$@"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@giamme/forge",
-  "version": "0.8.0",
-  "description": "One model builds it. A different model reviews what it actually built.",
+  "version": "0.9.0",
+  "description": "Multi-model coding with a reviewer that reads the code: plan, build in parallel worktrees, review every real diff, merge only what passes.",
   "keywords": ["claude-code", "codex", "opencode", "agent-skill", "code-review", "multi-model"],
   "license": "MIT",
   "author": "Giamme",
@@ -14,6 +14,7 @@
     "VERSION",
     "CHANGELOG.md",
     "README.md",
+    "docs/",
     "LICENSE",
     "registry.tsv",
     "references/",

package/references/decompose.md

@@ -521,7 +521,7 @@ its last message, and to say plainly what it could not run.
 ## Accepting, splitting, combining and the whole-run review
 
 Four subcommands act on plans after tasks have run. Full usage and refusal conditions are in the
-[README](../README.md#accepting-a-task-despite-its-reviewer); the mechanics:
+[README](../docs/reviews.md#accepting-a-task-despite-its-reviewer); the mechanics:
 
 - **`accept <plan> <task> --reason … --approved`** overrides a `FAIL`/`UNKNOWN` reviewer only
   when the reviewed commit is still the branch tip and the worktree still matches

package/references/fractal.md

@@ -5,7 +5,7 @@ model routing, independent QA of the cumulative diff, verification and integrati
 Fractal execution completion and Forge acceptance are separate outcomes. Costs are
 observational, and this integration makes no speed or cost-saving claim.
 
-For a first run, follow the [README walkthrough](../README.md#fractal-execution).
+For a first run, follow the [Fractal guide](../docs/fractal.md).
 This reference covers the exact selection, routing, lifecycle and inspection contracts.
 
 ## Contents

package/references/harnesses.md

@@ -46,8 +46,8 @@ disables), else the optional `timeout` column of the model's registry row, else
 
 **Infrastructure failures exit `8`.** After the backend exits, `forge-runtime.py classify` reads
 the dispatch log (never `<role>.last`, which is only created afterwards): claude/openclaude/grok
-`result` events with `is_error`, codex `turn.failed`/`error` events that nothing followed,
-and for the raw-log harnesses (opencode, antigravity) the last 2 KB when the exit was nonzero —
+`result` events with `is_error`, codex `turn.failed`/`error` and opencode `error` events that no
+answer followed, and for the raw-log harness (antigravity) the last 2 KB when the exit was nonzero —
 looking for strong phrases (usage/session limit, quota, insufficient balance/credit, rate limit,
 429/529, unauthorized/401/403, invalid API key, not logged in, ECONNRESET/ENOTFOUND/…). An
 `empty` answer (exit 0, nothing said) is the fifth class. codex's non-fatal reconnect notices
@@ -90,8 +90,9 @@ reason forge validates efforts itself before dispatch.
 
 **Prompt delivery uses stdin.** Forge copies the input once (including FIFOs), checks it
 with a streaming whitespace character class, and runs `codex exec ... - < role.prompt`.
-Native review has no custom prompt and uses `/dev/null`. Codex JSONL events and Claude
-`--output-format json` provide native usage; final responses remain in `<role>.last`.
+Native review has no custom prompt and uses `/dev/null`. Codex JSONL events, Claude and openclaude
+`--output-format stream-json` and opencode `--format json` provide native usage; final responses
+remain in `<role>.last`.
 See the official [Codex non-interactive guide](https://learn.chatgpt.com/docs/non-interactive-mode)
 and [Claude headless guide](https://code.claude.com/docs/en/headless).
 
@@ -109,12 +110,18 @@ and `--approve-for-me` additionally conflicts with an explicit `-s/--sandbox`.
 ## claude / openclaude
 
 ```
-<harness> -p --model <model> --add-dir <run-dir> --effort <effort> \
+<harness> -p --model <model> --add-dir <run-dir> --output-format stream-json --verbose --effort <effort> \
   (--permission-mode acceptEdits --allowedTools Bash | --dangerously-skip-permissions)
   [--disallowed-tools "Edit,Write,NotebookEdit"]
 ```
 with the prompt delivered on **stdin**.
 
+**The log is a stream.** `--output-format stream-json` (which `-p` accepts only with `--verbose`)
+writes one JSON message per line: the session, every assistant message and tool call, every tool
+result, and a closing `result` line with the final answer and the token counts, which is what
+forge reads into `<role>.last` and the metrics. The rest is the run's conversation, which forge-ui
+shows. Hook and rate-limit events in the stream are ignored.
+
 **The prompt must not go on argv when a variadic flag precedes it.** `--disallowed-tools`,
 `--allowed-tools` and friends are variadic, so a following positional is consumed as
 another value. In practice the prompt is parsed word by word into tool names — you get a
@@ -162,7 +169,7 @@ Claude-Code-shaped harness. That is the point of `sol:xhigh:openclaude`.
 ## opencode
 
 ```
-opencode run -m <provider>/<model> --dir <repo> --variant <effort> --auto [--agent plan] "<prompt>"
+opencode run -m <provider>/<model> --dir <repo> --variant <effort> --auto [--agent plan] --format json "<prompt>"
 ```
 
 Models are always `provider/model`; `opencode models` lists what is configured.
@@ -195,6 +202,11 @@ agy --model <model> --print-timeout <t> [--effort <e>] --add-dir <repo> --add-di
 The harness is named `antigravity` in forge; the binary is `agy`. This is how Gemini is
 reached.
 
+**Its log stays plain text.** agy has `--output-format stream-json`, but only its closing event
+has been seen (`{"event": "result", "result": {"status", "response", "error", "usage", ...}}`, on a
+lapsed login), not the stream of a working run, and the final answer would come from it. Until
+then forge keeps agy's printed output, which is both its log and its answer.
+
 **`--print` must use the attached `=` form.** It is a Go flag with an optional value, so
 written detached it consumes whatever token follows as its prompt. `agy --print
 --print-timeout 120s --model X "real prompt"` fails with *"--print took --print-timeout as

package/references/solo.md

@@ -48,7 +48,7 @@ nothing was judged — fix the cause and run again; a dwarf that returns nothing
 nothing is reported as 8, not 5). The default dispatch timeout is 2700 seconds, scaled up for
 `xhigh`/`max` effort (so the default QA/planner effort gets 3600), overridable per model in the
 registry; 0 disables that dispatch timeout, but an enabled Fractal task still has its own attempt
-deadline. See [dispatch timeouts](../README.md#scriptsforge-dispatchsh).
+deadline. See [dispatch timeouts](../docs/commands.md#scriptsforge-dispatchsh).
 
 The dwarf prompt carries implementer rules (no commits, no background processes, finish every
 measurement before the last message). forge records what it observes: if the dwarf committed

package/scripts/forge-dispatch.sh

@@ -405,7 +405,10 @@ case "$HARNESS" in
     # puts it outside the harness's default reach — without this the agent
     # refuses to open the very artifacts forge just wrote for it.
     CMD=("$HARNESS" -p --model "$MODEL" --add-dir "$RUN_DIR")
-    [ "$HARNESS" = claude ] && CMD+=(--output-format json)
+    # One JSON message per line: what the agent said and every tool call, so the run keeps
+    # its conversation (forge-ui reads it), ending in the `result` line forge-runtime.py
+    # takes the final message and the tokens from. stream-json needs --verbose with -p.
+    CMD+=(--output-format stream-json --verbose)
     [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
     if [ "$YOLO" = 1 ]; then
       CMD+=(--dangerously-skip-permissions)
@@ -443,6 +446,9 @@ case "$HARNESS" in
     # permission prompt that nothing can answer headlessly, so it is always set.
     CMD+=(--auto)
     read_only_role && [ "$YOLO" != 1 ] && CMD+=(--agent plan)
+    # One JSON event per line (text, tool_use, step_finish, error): the conversation, the
+    # final message and the tokens, read by forge-runtime.py and forge-ui.
+    CMD+=(--format json)
     CMD+=("$PROMPT")
     ;;
   antigravity)

package/scripts/forge-runs.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""forge runs [--repo DIR | --all] [--limit N] [--json]: this repo's recent runs, in the terminal.
+
+Every solo run, `plan` and `run` registers its run dir (forge_registry.py); this lists them newest
+first, one line each (run id, kind, age, task states, verification and final review, goal) with the
+run dir under it, so you can see what happened without a browser and get the dir to resume, retry
+or open with `forge ui open`. The repo is the Git top level of the current directory unless
+`--repo` names one; `--all` lists the runs of every repo. It reads the same run summaries as
+forge-ui and never writes anything.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+SKILL = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(SKILL / 'scripts'))
+sys.path.insert(0, str(SKILL / 'ui'))
+
+import forge_registry  # noqa: E402
+from forge_ui import reader  # noqa: E402
+
+FIELDS = ('key', 'run_id', 'kind', 'goal', 'repo', 'path', 'created', 'updated', 'task_count', 'counts',
+          'verification_status', 'final_review')
+
+
+def repo_of(start: Path) -> Path:
+    """The Git top level of `start`, else `start` itself: the key runs are registered under."""
+    try:
+        out = subprocess.run(['git', '-C', str(start), 'rev-parse', '--show-toplevel'], capture_output=True,
+                             text=True, stdin=subprocess.DEVNULL, timeout=10)
+        if out.returncode == 0 and out.stdout.strip():
+            return Path(out.stdout.strip()).resolve()
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return start.resolve()
+
+
+def registered(path: Path) -> list[str]:
+    """The run dirs one registry file lists (absolute paths, comments skipped)."""
+    try:
+        lines = path.read_text(encoding='utf-8', errors='replace').splitlines()
+    except OSError:
+        return []
+    return [line.strip() for line in lines if line.strip() and not line.startswith('#') and os.path.isabs(line.strip())]
+
+
+def runs(repo: Path | None) -> list[dict]:
+    if repo is None:
+        found = reader.discover(registry=True, registry_dir=forge_registry.registry_dir())
+    else:
+        found = reader.discover(plans=registered(forge_registry.runs_registry(repo)), registry=False)
+    result = []
+    for path, source in found:
+        try:
+            summary = reader.summarize(path, source)
+        except Exception:  # one unreadable run dir must not hide the others
+            continue
+        result.append({k: summary.get(k) for k in FIELDS})
+    return sorted(result, key=lambda r: r['updated'] if r['updated'] is not None else float('-inf'), reverse=True)
+
+
+def age(epoch, now) -> str:
+    if epoch is None:
+        return '?'
+    s = max(0, now - epoch)
+    for unit, size in (('d', 86400), ('h', 3600), ('m', 60)):
+        if s >= size:
+            return f'{int(s // size)}{unit} ago'
+    return 'just now'
+
+
+def line(run: dict, now: float, with_repo: bool = False) -> str:
+    counts = ' · '.join(f'{status.lower()} {n}' for status, n in (run['counts'] or {}).items()) or 'no tasks'
+    checks = ''.join(f'  {label} {run[key]}' for label, key in (('verify', 'verification_status'), ('review', 'final_review'))
+                     if run.get(key))
+    goal = str(run['goal'] or 'Untitled run').splitlines()[0]
+    if len(goal) > 72:
+        goal = goal[:71] + '…'
+    repo = f"  {Path(run['repo']).name or run['repo']}" if with_repo and run.get('repo') else ''
+    return f"{run['run_id'] or run['key']}  {run['kind']}{repo}  {age(run['updated'], now)}  {counts}{checks}  {goal}\n    {run['path']}"
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog='forge runs', description="This repo's recent forge runs, newest first. Read-only.")
+    which = parser.add_mutually_exclusive_group()
+    which.add_argument('--repo', type=Path, metavar='DIR', help='the repo whose runs to list (default: the Git top level of the current directory)')
+    which.add_argument('--all', action='store_true', help='list the runs of every repo')
+    parser.add_argument('--limit', type=int, default=10, metavar='N', help='at most N runs (default 10; 0 lists them all)')
+    parser.add_argument('--json', action='store_true', help='print the runs as a JSON array, for scripts and agents')
+    args = parser.parse_args(argv)
+    if args.limit < 0:
+        parser.error('--limit must be 0 or more')
+    if args.repo is not None and not args.repo.is_dir():
+        parser.error(f'--repo: no such directory: {args.repo}')
+    repo = None if args.all else repo_of(args.repo if args.repo is not None else Path.cwd())
+    found = runs(repo)
+    shown = found[:args.limit] if args.limit else found
+    if args.json:
+        json.dump(shown, sys.stdout, indent=2)
+        sys.stdout.write('\n')
+        return 0
+    where = 'every repo' if repo is None else str(repo)
+    if not found:
+        print(f'forge runs: no runs registered for {where}')
+        print('Runs register when they start (/forge "<goal>" --dwarf <model>); FORGE_RUN_REGISTRY=off turns that off.')
+        return 0
+    print(f'forge runs for {where}: {len(shown)} of {len(found)}, newest first')
+    now = time.time()
+    for run in shown:
+        print(line(run, now, with_repo=repo is None))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/scripts/forge-runtime.py

@@ -101,9 +101,45 @@ def token_count(value: object) -> int | None:
     return value if type(value) is int and value >= 0 else None
 
 
+# Harnesses whose log is a stream of JSON events rather than the answer itself.
+STRUCTURED = ('codex', 'claude', 'openclaude', 'grok', 'opencode')
+
+
+def _opencode_final(events: list) -> str:
+    """opencode's answer: the text of its last step, after its last tool call."""
+    final, step = '', []
+    for event in events:
+        kind = event.get('type')
+        if kind in ('step_start', 'tool_use'):
+            step = []
+        elif kind == 'text':
+            part = event.get('part')
+            text = part.get('text') if isinstance(part, dict) else None
+            if isinstance(text, str) and text.strip():
+                step.append(text)
+                final = '\n'.join(step)
+    return final
+
+
 def extract(log: str, harness: str) -> tuple[str | None, dict[str, int | None]]:
     usage = dict(input_tokens=None, cached_input_tokens=None, output_tokens=None)
     final = None
+    if harness == 'opencode':
+        events = _events(log)[0]
+        for event in events:
+            part = event.get('part')
+            tokens = part.get('tokens') if event.get('type') == 'step_finish' and isinstance(part, dict) else None
+            if not isinstance(tokens, dict):
+                continue
+            cache = tokens.get('cache') if isinstance(tokens.get('cache'), dict) else {}
+            # input counts what was read from and written to the cache, as claude's does
+            for key, parts in (('input_tokens', (tokens.get('input'), cache.get('read'), cache.get('write'))),
+                               ('cached_input_tokens', (cache.get('read'),)),
+                               ('output_tokens', (tokens.get('output'), tokens.get('reasoning')))):
+                counts = [token_count(v) for v in parts if v is not None]
+                if counts and all(v is not None for v in counts):
+                    usage[key] = (usage[key] or 0) + sum(counts)
+        return _opencode_final(events) or None, usage
     for line in log.splitlines():
         try:
             event = json.loads(line)
@@ -124,8 +160,9 @@ def extract(log: str, harness: str) -> tuple[str | None, dict[str, int | None]]:
             if isinstance(item, dict) and item.get('type') == 'agent_message':
                 if isinstance(item.get('text'), str):
                     final = item['text']
-        # grok's streaming-messages-json ends in the same `result` event, token buckets included.
-        if harness in ('claude', 'grok') and event.get('type') == 'result':
+        # claude's and openclaude's stream-json and grok's streaming-messages-json end in the same
+        # `result` event, token buckets included.
+        if harness in ('claude', 'openclaude', 'grok') and event.get('type') == 'result':
             if isinstance(event.get('result'), str):
                 final = event['result']
             # Claude reports uncached, cache-read and cache-creation separately.
@@ -149,7 +186,7 @@ def finish(attempt: str, root: str, role: str, harness: str, rc: str) -> None:
 def _finish(attempt: Path, root: Path, role: str, harness: str, rc: str) -> None:
     log = root / (role + '.log')
     last = root / (role + '.last')
-    structured = harness in ('codex', 'claude', 'grok')
+    structured = harness in STRUCTURED
     text = log.read_text(errors='replace') if structured and log.exists() else ''
     final, usage = extract(text, harness)
     if not last.exists() or not last.stat().st_size:
@@ -439,7 +476,7 @@ def classify(log: str, harness: str, rc: object, last: str = '', role: str = '',
         text = Path(log).read_text(errors='replace')
     except OSError:
         text = ''
-    events, stray = _events(text) if harness in ('codex', 'claude', 'openclaude', 'grok') else ([], [])
+    events, stray = _events(text) if harness in STRUCTURED else ([], [])
 
     if harness == 'codex':
         final = _codex_final(events, last)
@@ -454,6 +491,22 @@ def classify(log: str, harness: str, rc: object, last: str = '', role: str = '',
             return 'empty', None, 'codex finished with exit 0 but produced no final message'
         return classify_text('\n'.join(pending + [_tail(stray)]), now=now)
 
+    if harness == 'opencode' and events:
+        # Like codex: an error event counts when the run produced no answer after it.
+        errors = []
+        for event in events:
+            error = event.get('error') if event.get('type') == 'error' else None
+            if isinstance(error, dict):
+                data = error.get('data') if isinstance(error.get('data'), dict) else {}
+                errors.append(str(data.get('message') or error.get('name') or json.dumps(error)))
+        final = _opencode_final(events)
+        if rc == 0:
+            if final.strip():
+                return None
+            hit = classify_text('\n'.join(errors), now=now) if errors else None
+            return hit or ('empty', None, 'opencode finished with exit 0 but produced no final message')
+        return classify_text('\n'.join(errors + [_tail(stray)]), now=now)
+
     results = [e for e in events if e.get('type') == 'result'] if harness in ('claude', 'openclaude', 'grok') else []
     if results:
         event = results[-1]
@@ -478,8 +531,8 @@ def classify(log: str, harness: str, rc: object, last: str = '', role: str = '',
             return 'empty', None, '%s finished with exit 0 but its final result is empty' % harness
         return None
 
-    # Raw-log harness (opencode, antigravity, openclaude's plain text, or a claude that
-    # died before emitting its result): the log is the message, so only the tail of a
+    # Raw-log harness (antigravity, an opencode or openclaude from before their streams, or a
+    # claude that died before emitting its result): the log is the message, so only the tail of a
     # failing run is evidence. A successful run's prose is never scanned.
     if rc != 0:
         return classify_text(_tail(text), now=now)

package/scripts/forge-version.py

@@ -10,6 +10,10 @@ VERSION, prints a single line saying so. It is silent offline, when the checkout
 upstream, in CI (`CI` set) and when `FORGE_UPDATE_CHECK=off`, and it always exits 0: it never
 changes a run's outcome. The last check is cached in
 `${XDG_STATE_HOME:-~/.local/state}/forge/update-check.json`.
+
+An npm installation (the package sits under a `node_modules` folder, the same rule as
+forge-update.sh) has no git upstream: there the newest release is the package's `latest` on the
+npm registry (`npm_config_registry` when set, as npm reads it), and the update command is npm's.
 """
 from __future__ import annotations
 
@@ -21,6 +25,8 @@ import subprocess
 import sys
 import tempfile
 import time
+import urllib.parse
+import urllib.request
 from pathlib import Path
 
 SKILL = Path(__file__).resolve().parent.parent
@@ -28,6 +34,8 @@ DAY_S = 24 * 3600
 TIMEOUT_S = 5
 _TAG = re.compile(r'^refs/tags/v(\d+(?:\.\d+)*)$')
 _OFF = ('off', '0', 'false', 'no')
+NPM_PACKAGE = '@giamme/forge'
+NPM_REGISTRY = 'https://registry.npmjs.org/'
 
 
 def state_file() -> Path:
@@ -84,6 +92,34 @@ def checkout(source: Path) -> dict:
     return info
 
 
+def npm_install(source: Path) -> dict:
+    """An npm installation's facts, like checkout()'s: empty when `source` is not under node_modules."""
+    if 'node_modules' not in source.resolve().parts:
+        return {}
+    try:
+        name = json.loads((source / 'package.json').read_text(encoding='utf-8')).get('name') or NPM_PACKAGE
+    except (OSError, ValueError, UnicodeDecodeError, AttributeError):
+        name = NPM_PACKAGE
+    registry = os.environ.get('npm_config_registry') or os.environ.get('NPM_CONFIG_REGISTRY') or NPM_REGISTRY
+    url = registry.rstrip('/') + '/' + urllib.parse.quote(name, safe='@') + '/latest'
+    return dict(npm=name, remote='npm', url=url)
+
+
+def update_command(info: dict) -> str:
+    return f'npm install -g {info["npm"]}@latest && forge install' if info.get('npm') else 'forge update'
+
+
+def npm_latest(url: str) -> str | None:
+    """The `latest` version on the registry, or None when it cannot be read in time."""
+    try:
+        with urllib.request.urlopen(urllib.request.Request(url, headers={'Accept': 'application/json'}),
+                                    timeout=TIMEOUT_S) as reply:
+            version = json.loads(reply.read().decode('utf-8')).get('version')
+    except Exception:  # offline, HTTP error, a proxy page instead of JSON: no answer, never a failure
+        return None
+    return version if isinstance(version, str) and re.fullmatch(r'\d+(?:\.\d+)*', version) else None
+
+
 def latest_release(source: Path, remote: str) -> str | None:
     """The highest vX[.Y[.Z]] tag on the remote, or None when it cannot be reached in time."""
     out = _git(source, 'ls-remote', '--tags', '--refs', '--', remote, 'v*')
@@ -116,7 +152,7 @@ def write_cache(data: dict) -> None:
 def check(source: Path, info: dict) -> dict:
     """Ask the upstream now and cache the answer. Offline keeps the last known release."""
     cache = read_cache()
-    found = latest_release(source, info['remote'])
+    found = npm_latest(info['url']) if info.get('npm') else latest_release(source, info['remote'])
     same = cache.get('url') == info['url']
     entry = dict(checked=time.time(), url=info['url'],
                  latest=found if found else (cache.get('latest') if same else None), reached=found is not None)
@@ -131,15 +167,15 @@ def disabled() -> bool:
     return bool(ci) and ci not in _OFF
 
 
-def available_line(latest: str, current: str) -> str:
-    return f'forge {latest} is available (you have {current}): forge update'
+def available_line(latest: str, current: str, info: dict | None = None) -> str:
+    return f'forge {latest} is available (you have {current}): {update_command(info or {})}'
 
 
 def notice(source: Path) -> None:
     if disabled():
         return
     current = local_version(source)
-    info = checkout(source)
+    info = checkout(source) or npm_install(source)
     if not current or not info.get('remote'):
         return
     cache = read_cache()
@@ -148,22 +184,26 @@ def notice(source: Path) -> None:
         return  # checked (and told) within the last day
     entry = check(source, info)
     if newer(entry['latest'], current):
-        print(available_line(entry['latest'], current))
+        print(available_line(entry['latest'], current, info))
 
 
 def show(source: Path, ask: bool) -> int:
     current = local_version(source)
     print(f'forge {current or "unknown"}')
-    info = checkout(source)
+    info = checkout(source) or npm_install(source)
     if not info:
         print(f'checkout: {source} (not a git checkout; update it with forge update --source <checkout>)')
         return 0
-    where = info['branch'] or 'detached HEAD'
-    print(f'checkout: {source} ({where} @ {info["commit"] or "?"})')
-    if info.get('remote'):
-        print(f'upstream: {info["upstream"] or info["remote"]} ({info["url"] or "no url"})')
+    if info.get('npm'):
+        print(f'installed: {source} (npm package {info["npm"]})')
+        print(f'upstream: npm registry ({info["url"]})')
     else:
-        print('upstream: none')
+        where = info['branch'] or 'detached HEAD'
+        print(f'checkout: {source} ({where} @ {info["commit"] or "?"})')
+        if info.get('remote'):
+            print(f'upstream: {info["upstream"] or info["remote"]} ({info["url"] or "no url"})')
+        else:
+            print('upstream: none')
     entry = check(source, info) if ask and info.get('remote') else read_cache()
     if ask and info.get('remote') and not entry.get('reached'):
         print(f'latest:   could not reach {info["remote"]}')
@@ -172,9 +212,11 @@ def show(source: Path, ask: bool) -> int:
             if isinstance(entry.get('checked'), (int, float)) else 'unknown'
         print(f'latest:   {entry["latest"]} (checked {when})')
         if newer(entry['latest'], current):
-            print(available_line(entry['latest'], current))
+            print(available_line(entry['latest'], current, info))
     else:
         print('latest:   not checked yet; run forge version --check')
+    if info.get('npm'):
+        print(f'update:   {update_command(info)}')
     return 0