@bojackduy/opencode-loopd 1.10.4 → 1.10.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bojackduy/opencode-loopd",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "description": "Codex-inspired background goal engine for OpenCode — autonomous subagents, engine-driven loop, child worker sessions and modal TUI dashboard. Like Claude Code loop for OpenCode.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/skills/loopd/SKILL.md

@@ -60,8 +60,8 @@ Every goal has an **immutable contract** at creation — the source of truth for
 
 * **Objective** — semantic requirements (free text, self-contained). The worker derives concrete requirements from it.
 * **Checks** — deterministic shell commands that **must pass** for `complete_goal` to be accepted. For `workspaceWrite:true` goals they are **mandatory** (explicit `checks` or plugin `defaultChecks`), and they run from `checkCwd` (writers default to project root; artifact-only jobs run from their `artifactDir`).
-* **Agent** — any OpenCode agent name: built-in (`build`, `plan`, `explore`, `general`), file `~/.config/opencode/agents/*.md`, or `opencode.jsonc` `agent.*`. Discover with `opencode agent list`. Prefer `subagent`-mode agents for workers; `primary`-mode agents work but may expect user interaction. Resolution: explicit arg → **calling session's live agent** (read at creation) → `defaultAgent` → OpenCode global default. So a parent in Plan spawns a Plan worker unless told otherwise.
-* **Model** — any model as `"providerID/modelID"` (e.g. `openai/gpt-5.6-sol`, `ollama/qwen3.8:27b`, `openrouter/google/gemma-4-31b-it:free`). Discover with `opencode models [provider]`. Sent on every worker prompt. Resolution: explicit arg → **calling session's live model** → `defaultModel` → agent config → session history → global default. Caveat: OpenCode exposes no live-model field for history-derived models, so those fall through to agent config.
+* **Agent** — any OpenCode agent name: built-in (`build`, `plan`, `explore`, `general`), file `~/.config/opencode/agents/*.md`, or `opencode.jsonc` `agent.*`. Discover with `opencode agent list`. Prefer `subagent`-mode agents for workers; `primary`-mode agents work but may expect user interaction. Resolution: explicit arg → **calling session's live agent** (read at creation) → `defaultAgent` → OpenCode global default. So a parent in Plan spawns a Plan worker unless told otherwise. **Omit by default — inherit.** Do NOT pass `agent` unless the caller explicitly requests a different identity or the task needs it; explicit values freeze identity and break session upgrades.
+* **Model** — any model as `"providerID/modelID"` (e.g. `openai/gpt-5.6-sol`, `ollama/qwen3.8:27b`, `openrouter/google/gemma-4-31b-it:free`). Discover with `opencode models [provider]`. Sent on every worker prompt. Resolution: explicit arg → **calling session's live model** → `defaultModel` → agent config → session history → global default. Caveat: OpenCode exposes no live-model field for history-derived models, so those fall through to agent config. **Omit by default — inherit.** Do NOT pass `model` unless explicitly requested.
 * **WorkspaceWrite** — `true` (default) = may touch the shared repo; **only one active writer at a time** is allowed (enforced on `start`/`resume`/`retry` with rollback). Set `false` explicitly for artifact-only/read-only work to allow concurrency.
 * **Budgets** — `tokenBudget` (tokens) and `costBudget` (dollars, e.g. `0.5`). When either is exceeded the engine aborts the worker mid-turn and sets `budget_limited`. The worker is stopped immediately, not just at the next turn boundary.
 * **Limits** — `maxTurns` (default 50), `maxNoProgress`, `maxFailures`, `maxEvaluatorRejections` (default 3), `timeoutMs`, `compactEvery`, `progressFile`.
@@ -87,8 +87,9 @@ Use `loopd_create_goal` **after** clarifying the objective with the user (what /
 loopd_create_goal({
   name: "short-name",
   objective: "Detailed description of what the goal should accomplish.",
-  agent: "researcher",                    // any agent name; optional, inherits calling session then defaultAgent
-  model: "openai/gpt-5.6-sol",            // any provider/model; optional, inherits calling session then defaultModel
+  // agent/model: omit by default to inherit calling session — only pass when explicitly requested
+  // agent: "researcher",
+  // model: "openai/gpt-5.6-sol",
   costBudget: 0.5,                         // optional dollars; aborts worker when exceeded
   checks: ["npm test"],                    // mandatory if workspaceWrite:true (or configure defaultChecks)
   checkCwd: "/project/root",               // optional; writers default to project root, readers to artifactDir
@@ -204,10 +205,24 @@ Owner-side equivalents of TUI `:force` / `:block`. Bypass checks — use only wh
 
 ## Command Sessions (Standalone Interactive Processes)
 
-A **command session** is a raw OS process (spawned via `bun-pty`, falling back to a plain pipe) — no agent, no turns, no checks. It is completely independent from goals: starting/stopping one never pauses, blocks, or completes any goal, and vice versa. Use it whenever the request is "run X and let me watch/type into it" rather than "figure out/build X".
+A **command session** is a raw OS process (spawned via `bun-pty`, falling back to a plain pipe) — no agent, no turns, no checks. It is completely independent from goals: starting/stopping one never pauses, blocks, or completes any goal, and vice versa. Use it whenever the request is "run X and let me watch/type into it" rather than "figure out/build X". By default, natural exits (including code 0), timeouts, and missing processes notify the owner; manual termination stays silent. Notification tails are sanitized for chat, while the retained terminal log remains raw. A finished command can still be opened to read its saved output; Ctrl+C/input cannot affect it.
 
 Typical uses: dev servers (`npm run dev`), watch mode (`npm test -- --watch`), REPLs (`python3`, `node`), log tails (`tail -f`), one-off scripts, interactive shells.
 
+### Prefer commands over the built-in shell
+
+**Rule: if it might take a while or never return, start it as a command — never run it in the built-in shell/bash tool.** The built-in shell blocks your entire turn until the process exits: a 5-minute `npm install` freezes you mid-turn (and can hit tool timeouts, losing the output). `loopd_command_start` returns immediately with a `command_id` and pushes you on exit or pattern match, so you stay responsive.
+
+Use a command (not the built-in shell) for: installs (`npm/pip/brew/cargo install`, downloads), builds, full test suites, migrations, dev servers, watchers, log tails, REPLs, anything interactive, or anything whose duration you can't guarantee is seconds. The built-in shell is only for quick one-shots (`ls`, `git status`, a single fast test).
+
+```
+User: install the dependencies and set up the project.
+# WRONG: built-in shell `npm install` — blocks your turn for minutes.
+# RIGHT:
+Agent: loopd_command_start({ title: "npm install", command: "npm", args: ["install"], notify_on_exit: true })
+# → returns immediately; you keep working, and get pushed when it finishes.
+```
+
 ### Agent Tools
 
 | Tool | Purpose |
@@ -248,7 +263,7 @@ On the Commands tab, `o` **never** opens a chat session or a dialog — it close
 - Paste forwards raw bytes immediately.
 - The viewport is measured and resizes both the emulator and the real PTY.
 
-Colon commands available directly on the Commands tab (before opening fullscreen): `:new <command> [args...]` (quoted args preserved, e.g. `:new bash -c "echo hi"`), `:interrupt`, `:terminate`, `:remove`, and bare text + Enter writes stdin to the selected command. Goal controls (`p`/`r`/`R`/`x`/`A`/`N`) never fire on the Commands tab.
+Single-key helpers on the Commands tab: `X` force-kill (SIGKILL now, no grace — for hung processes), `R` restart with the same spec (new ID, old record kept; env values are never persisted so restarted env commands lose their env), `x` remove finished (running commands get a hint, never a kill). Colon commands (before opening fullscreen): `:new <command> [args...]` (quoted args preserved, e.g. `:new bash -c "echo hi"`), `:interrupt`, `:terminate`, `:kill`, `:restart`, `:remove`, `:await <goalID>`, and bare text + Enter writes stdin to the selected command. Goal-only keys (`p`/`r`/`A`/`N`) never fire on the Commands tab; `R`/`x` are tab-scoped (retry/clear on Goals, restart/remove-done on Commands).
 
 ### Example: Watching a Dev Server
 
@@ -330,7 +345,17 @@ Open the shared dashboard with `/loop` (or `<leader>o`) — focuses the **Goals*
 | `h` | Select Goals directionally |
 | `l` | Select Commands directionally |
 
-`j`/`k`/`g`/`G` select within whichever tab is active. Goal controls (`p`/`r`/`R`/`x`/`A`/`N`) only fire on the Goals tab and are refused with a hint on Commands.
+`j`/`k`/`g`/`G` select within whichever tab is active. Goal controls (`p`/`r`/`A`/`N`) only fire on the Goals tab and are refused with a hint on Commands; `R`/`x` are tab-scoped (retry/clear on Goals, restart/remove-done on Commands).
+
+### Commands Tab — Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `X` | Force-kill selected command (SIGKILL now, no grace) |
+| `R` | Restart selected command with the same spec (new ID) |
+| `x` | Remove selected command — finished only (running gets a hint) |
+| `o` | Open fullscreen terminal page |
+| `Ctrl+C` | Interrupt selected command (SIGINT delivery, never a kill) |
 
 ### Goals Tab — Keyboard Shortcuts (Normal Mode)
 
@@ -373,11 +398,13 @@ Open the shared dashboard with `/loop` (or `<leader>o`) — focuses the **Goals*
 | `:new <command> [args...]` | Start a new command (quoted args preserved) | `loopd_command_start` |
 | `:interrupt` | SIGINT the selected command | `loopd_command_interrupt` |
 | `:terminate` | SIGTERM→SIGKILL the selected command | `loopd_command_terminate` |
+| `:kill` | SIGKILL now, no grace (same as `X`) | — (no agent equivalent; agents use `loopd_command_terminate`) |
+| `:restart` | Stop + respawn same spec, new ID (same as `R`) | — (no agent equivalent) |
 | `:remove` | Delete a finished command's record + log | `loopd_command_remove` |
 | bare text + Enter | Write that line as stdin to the selected command | `loopd_command_write` |
 | `q` | Detach (view closes; command keeps running) | — |
 
-Inside the **fullscreen terminal page** (reached via `o`): every keystroke forwards immediately as raw input (no line-submit box), `Ctrl+C` is interrupt input to the process, `Ctrl+]` detaches back to where you came from without stopping the process.
+Inside the **fullscreen terminal page** (reached via `o`): every keystroke forwards immediately as raw input (no line-submit box), `Ctrl+C` is interrupt input to the process, `Ctrl+]` detaches back to where you came from without stopping the process. Press `?` on the Commands tab to see force-kill, restart, and removal shortcuts before opening the terminal.
 
 **Scrolling:** both lists are a `<scrollbox>` capped at 10 rows — short lists sit compact with no gap, long lists scroll and follow `j`/`k`/`g`/`G` via `scrollChildIntoView`. Detail + input stay pinned below in both cases. Empty list shows the fallback tip.
 
@@ -411,8 +438,7 @@ Agent: Got it — creating with a contract.
 loopd_create_goal({
   name: "docs-write",
   objective: "Write a README.md covering: what it is, install, usage, architecture, and examples. Then create CHANGELOG.md with a v1.0.0 entry.",
-  agent: "researcher",
-  model: "openai/gpt-5.6-sol",
+  // omit agent/model to inherit calling session — only pass when explicitly requested
   costBudget: 0.5,
   checks: ["test -f README.md", "test -f CHANGELOG.md"],
   checkCwd: "/Users/you/project",           // explicit for writers; defaults to project root