@sorenllm/opencode-forge 0.6.0 → 0.7.0

package/README.md

@@ -257,12 +257,12 @@ Subagents have it worse: the native task tool has no timeout at all.
 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 |
+| condition | knob | on trigger | completion behavior |
+| --- | --- | --- | --- |
+| process exit | — | final; exit code + output tail returned | **terminal evidence** — output delivered in full; the job self-clears from the registry (no wake, no clear needed) |
+| `success_pattern` regex matches new output | opt-in | completes as success; process kept alive by default (server semantics), `keep_alive: false` kills its tree | kept alive → later exit still wakes (the server dying is real news); killed inline → self-clears |
+| `idle_ms` with no new output | default 60000 | early return `still-running` + `jobId`; process stays alive | later exit queues a wake; entry stays listed until cleared |
+| `max_wait_ms` hard cap | default 120000, max 600000 | early return `still-running`; never kills | same as idle |
 
 `run_in_background: true` skips all waiting and returns
 `{jobId, logPath}` immediately. Every run pops one permission dialog
@@ -274,14 +274,21 @@ disagrees with that line, the line 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).
+`clear` (drop a finished entry — only early-returned/background jobs need
+this; synchronously consumed jobs self-clear at completion) / `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 whose caller last saw it before completion —
+`run_in_background` starts and `still-running`/kept-alive `success` early
+returns — queues a single `[forge:job-complete]` message when it finishes,
+delivered into the owning session via `promptAsync` the next time it goes
+idle (exactly once; `notify: false` opts out per job). A foreground call
+resolved on the exit event is terminal evidence: the caller already holds
+the complete output, so no wake fires and the registry entry self-clears —
+a stale `poll`/`kill`/`clear` on such an id answers "already consumed"
+instead of "unknown job".
 
 **Ownership.** Jobs belong to the session that created them. Session
 deleted → its live session-scoped jobs are killed and the event is recorded

package/dist/index.js

@@ -13416,12 +13416,30 @@ function createJobManager(opts = {}) {
     job.state = state;
     job.exitCode = exitCode;
     job.endedAt = now();
-    if (job.notify && job.wakeState === "none") {
+    if (job.notify && job.wakeState === "none" && !job.terminalEvidence) {
       job.wakeState = "queued";
       job.wakeQueuedAt = now();
     }
+    if (job.terminalEvidence) {
+      jobs.delete(job.id);
+      rememberConsumed(job.id);
+    }
     enforceCaps();
   }
+  const consumedIds = new Set;
+  function rememberConsumed(id) {
+    if (consumedIds.has(id))
+      return;
+    consumedIds.add(id);
+    if (consumedIds.size > maxFinishedJobs) {
+      const oldest = consumedIds.values().next().value;
+      if (oldest !== undefined)
+        consumedIds.delete(oldest);
+    }
+  }
+  function consumed(id) {
+    return consumedIds.has(id);
+  }
   function kill(job) {
     if (isTerminal2(job))
       return;
@@ -13533,6 +13551,7 @@ function createJobManager(opts = {}) {
     deliverWakesFor,
     abandonStaleWakes,
     ledgerEntries,
+    consumed,
     size: () => jobs.size
   };
 }
@@ -13640,6 +13659,11 @@ function startJob(manager, opts) {
     clearTimeout(maxWaitTimer);
   };
   const firstOutputHooks = [];
+  const foregroundWatch = !opts.runInBackground;
+  const stampTerminalEvidence = () => {
+    if (foregroundWatch && !settled)
+      job.terminalEvidence = true;
+  };
   function resolveStillRunning() {
     if (settled)
       return;
@@ -13675,6 +13699,7 @@ function startJob(manager, opts) {
         closeSync(wfd);
       } catch {}
     }
+    stampTerminalEvidence();
     manager.markTerminal(job, "killed", null);
     maxWaitTimer && clearTimeout(maxWaitTimer);
     resolveSettle({ status: "exited", exitCode: null, outputTail: "", spawnError: String(err) });
@@ -13726,6 +13751,8 @@ function startJob(manager, opts) {
           killTree(child);
           if (opts.survive)
             opts.registry?.remove(id);
+          if (foregroundWatch)
+            job.terminalEvidence = true;
           manager.markTerminal(job, "succeeded", null);
         }
         resolveSettle({ status: "succeeded", matched: m[0], outputTail: job.tail, keptAlive });
@@ -13747,6 +13774,7 @@ function startJob(manager, opts) {
       tail.flush();
       tail.stop();
       liveTails.delete(id);
+      stampTerminalEvidence();
       manager.markTerminal(job, "exited", code);
       if (opts.survive)
         opts.registry?.remove(id);
@@ -13765,6 +13793,7 @@ function startJob(manager, opts) {
     if (opts.survive)
       opts.registry?.remove(id);
     if (!settled) {
+      stampTerminalEvidence();
       settled = true;
       stopTimers();
       manager.markTerminal(job, "killed", null);
@@ -16169,6 +16198,8 @@ var forgeShellTool = tool({
         output: [
           `[forge:job] Command finished (exit=${r.exitCode ?? "none"}).`,
           `cwd: ${cwd}`,
+          `jobId: ${started.job.id}`,
+          `Output was delivered in full above — terminal evidence: the job self-cleared from the registry (no wake fires, no forge_jobs clear needed).`,
           ...r.spawnError ? [`spawn error: ${r.spawnError}`] : [],
           `output:
 ${r.outputTail || "(none)"}`
@@ -16182,7 +16213,7 @@ ${r.outputTail || "(none)"}`
         output: [
           `[forge:job] Success pattern matched: "${r.matched}".`,
           `cwd: ${cwd}`,
-          r.keptAlive ? `The process was kept alive as job ${started.job.id} (stop it with forge_jobs kill when done).` : "The process tree was terminated (keep_alive=false).",
+          r.keptAlive ? `The process was kept alive as job ${started.job.id} (stop it with forge_jobs kill when done).` : `The process tree was terminated (keep_alive=false) — terminal evidence: job ${started.job.id} self-cleared from the registry (no wake, no clear needed).`,
           `output:
 ${r.outputTail}`
         ].join(`
@@ -16205,7 +16236,7 @@ ${r.outputTail || "(none yet)"}`,
 });
 var FORGE_JOBS_ACTIONS = ["list", "poll", "log", "kill", "clear", "handoff"];
 var forgeJobsTool = tool({
-  description: "Manage forge_shell jobs. Actions: list (all jobs, newest first); poll {jobId, waitMs<=30000} — bounded wait for NEW output or exit, drains it; log {jobId, offset?, limit?} — line paging over the on-disk log (omitted offset = tail window, default 200 lines); kill {jobId} — terminate the job's whole process tree; clear {jobId} — drop a finished job from the registry; handoff {jobId} — rebind ownership to the root session so the job survives this (sub)session's end. A delegated agent MUST poll its jobs before yielding its conclusion.",
+  description: "Manage forge_shell jobs. Actions: list (all jobs, newest first); poll {jobId, waitMs<=30000} — bounded wait for NEW output or exit, drains it; log {jobId, offset?, limit?} — line paging over the on-disk log (omitted offset = tail window, default 200 lines); kill {jobId} — terminate the job's whole process tree; clear {jobId} — drop a finished job from the registry (only early-returned/background jobs need this — synchronously consumed jobs self-clear at completion); handoff {jobId} — rebind ownership to the root session so the job survives this (sub)session's end. A delegated agent MUST poll its jobs before yielding its conclusion.",
   args: {
     action: tool.schema.string().describe(`One of: ${FORGE_JOBS_ACTIONS.join(", ")}`),
     jobId: tool.schema.string().optional().describe("Job id from forge_shell (required for every action except list)"),
@@ -16230,8 +16261,9 @@ var forgeJobsTool = tool({
     if (!args.jobId)
       throw new Error(`Action "${action}" requires jobId.`);
     const job = jobManager.get(args.jobId);
-    if (!job)
-      throw new Error(`No job ${args.jobId} in the registry (finished jobs age out; the on-disk log may still exist).`);
+    if (!job) {
+      throw new Error(jobManager.consumed(args.jobId) ? `Job ${args.jobId} was already consumed: a terminal-evidence foreground return delivered its complete output inline, so it self-cleared from the registry — no wake fires and no clear is needed.` : `No job ${args.jobId} in the registry (finished jobs age out; the on-disk log may still exist).`);
+    }
     if (action === "poll") {
       const p = await pollJob(jobManager, args.jobId, args.waitMs ?? 0);
       if (!p)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorenllm/opencode-forge",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Single general-purpose forge agent for opencode: static worker subagents defined in forge.json (pinned model + thoughtLevel pair, or an Auto worker inheriting the parent model; dispatched through the native task tool — TUI-visible), a plan harness (file-backed plans with approve/close confirmation gates and a hard draft write-ban), a goal harness (autonomous, host-verified objectives), a /crew orchestration command (declared-plan waves with an evidence-checked close gate), a job supervisor (forge_shell with exit-bound completion, idle/success early return, background jobs with poll/log/kill/handoff), and a builtin-shell hang watchdog.",
   "type": "module",
   "main": "./dist/index.js",