@bojackduy/opencode-loopd 1.5.2 → 1.6.0

package/dist/tui.js

@@ -22,7 +22,7 @@ import { useKeyboard } from "@opentui/solid";
 // src/infrastructure/state-repository.ts
 import { promises as fs } from "fs";
 import path from "path";
-var CURRENT_VERSION = 2;
+var CURRENT_VERSION = 5;
 function emptyState() {
   return { version: CURRENT_VERSION, revision: 0, goals: [], runtimes: [], commandLedger: [] };
 }
@@ -76,6 +76,53 @@ function migrate(state) {
       blocker: g.blocker ?? undefined
     }));
   }
+  if (result.version < 3) {
+    result.version = 3;
+    result.runtimes = result.runtimes.map((rt) => {
+      const oldTurnCount = rt.turnCount ?? 0;
+      const { turnCount: _deprecatedTurnCount, ...rest } = rt;
+      return {
+        ...rest,
+        budgetTurnCount: rest.budgetTurnCount ?? oldTurnCount,
+        runCount: rest.runCount ?? oldTurnCount,
+        runGeneration: rest.runGeneration ?? 0,
+        freeRetryPending: rest.freeRetryPending ?? false,
+        lastRejectionDetails: rest.lastRejectionDetails ?? undefined,
+        activePromptMessageID: rest.activePromptMessageID ?? undefined,
+        lastActivityAt: rest.lastActivityAt ?? undefined,
+        idleCandidateAt: rest.idleCandidateAt ?? undefined,
+        activeToolCallIDs: rest.activeToolCallIDs ?? []
+      };
+    });
+  }
+  if (result.version < 4) {
+    result.version = 4;
+    result.runtimes = result.runtimes.map((rt) => ({
+      ...rt,
+      lastVerificationAttempt: rt.lastVerificationAttempt ?? undefined,
+      recentVerificationAttempts: rt.recentVerificationAttempts ?? []
+    }));
+  }
+  if (result.version < 5) {
+    result.version = 5;
+    result.goals = result.goals.map((goal) => ({
+      ...goal,
+      config: {
+        ...goal.config,
+        workspaceWrite: goal.config?.workspaceWrite ?? true
+      }
+    }));
+    result.runtimes = result.runtimes.map((rt) => ({
+      ...rt,
+      activePromptObservedAt: rt.activePromptObservedAt ?? undefined,
+      activeAssistantMessageID: rt.activeAssistantMessageID ?? undefined,
+      activeAssistantCompletedAt: rt.activeAssistantCompletedAt ?? undefined,
+      idleCandidateGeneration: rt.idleCandidateGeneration ?? undefined,
+      unknownStatusCount: rt.unknownStatusCount ?? 0,
+      lastUnknownStatusAt: rt.lastUnknownStatusAt ?? undefined,
+      workerUnreachableNotifiedAt: rt.workerUnreachableNotifiedAt ?? undefined
+    }));
+  }
   return result;
 }
 async function writeAtomic(target, contents) {
@@ -643,7 +690,7 @@ function LoopDashboard(props) {
       return;
     }
   });
-  const goals = () => state()?.goals.filter((g) => g.status !== "complete") || [];
+  const goals = () => state()?.goals.filter((g) => showCompleted() || g.status !== "complete") || [];
   async function executeCommand(cmd) {
     debugLog("executeCommand raw=", JSON.stringify(cmd));
     const parsed = parseCommand(cmd);
@@ -1203,7 +1250,7 @@ function LoopDashboard(props) {
             const turnColor = () => {
               if (!runtime() || !maxTurns)
                 return phaseColor(runtime()?.phase || "idle", theme());
-              const ratio = runtime().turnCount / maxTurns;
+              const ratio = runtime().budgetTurnCount / maxTurns;
               if (ratio >= 1)
                 return theme().error;
               if (ratio >= 0.8)
@@ -1250,7 +1297,7 @@ function LoopDashboard(props) {
                 })(), (() => {
                   var _el$98 = _$createElement("span"), _el$99 = _$createTextNode(` `);
                   _$insertNode(_el$98, _el$99);
-                  _$insert(_el$98, () => runtime().turnCount, null);
+                  _$insert(_el$98, () => runtime().budgetTurnCount, null);
                   _$insert(_el$98, maxTurns ? `/${maxTurns}` : "", null);
                   _$effect((_$p) => _$setProp(_el$98, "style", {
                     fg: turnColor()
@@ -1366,9 +1413,12 @@ function LoopDashboard(props) {
               }, _$p));
               return _el$118;
             })(), (() => {
-              var _el$120 = _$createElement("span"), _el$121 = _$createTextNode(` turn `);
+              var _el$120 = _$createElement("span"), _el$121 = _$createTextNode(` run `), _el$122 = _$createTextNode(` (budget `), _el$123 = _$createTextNode(`)`);
               _$insertNode(_el$120, _el$121);
-              _$insert(_el$120, () => rt().turnCount, null);
+              _$insertNode(_el$120, _el$122);
+              _$insertNode(_el$120, _el$123);
+              _$insert(_el$120, () => rt().runCount, _el$122);
+              _$insert(_el$120, () => rt().budgetTurnCount, _el$123);
               _$effect((_$p) => _$setProp(_el$120, "style", {
                 fg: theme().textMuted
               }, _$p));
@@ -1379,113 +1429,113 @@ function LoopDashboard(props) {
           _$insert(_el$109, (() => {
             var _c$8 = _$memo(() => !!lp());
             return () => _c$8() && [(() => {
-              var _el$122 = _$createElement("span"), _el$123 = _$createTextNode(`
+              var _el$124 = _$createElement("span"), _el$125 = _$createTextNode(`
 \u2714 `);
-              _$insertNode(_el$122, _el$123);
-              _$effect((_$p) => _$setProp(_el$122, "style", {
+              _$insertNode(_el$124, _el$125);
+              _$effect((_$p) => _$setProp(_el$124, "style", {
                 fg: theme().success
               }, _$p));
-              return _el$122;
+              return _el$124;
             })(), (() => {
-              var _el$125 = _$createElement("span");
-              _$insert(_el$125, () => lp().summary.slice(0, 100));
-              _$effect((_$p) => _$setProp(_el$125, "style", {
+              var _el$127 = _$createElement("span");
+              _$insert(_el$127, () => lp().summary.slice(0, 100));
+              _$effect((_$p) => _$setProp(_el$127, "style", {
                 fg: theme().text
               }, _$p));
-              return _el$125;
+              return _el$127;
             })(), (() => {
-              var _el$126 = _$createElement("span"), _el$127 = _$createTextNode(` \u2192 `);
-              _$insertNode(_el$126, _el$127);
-              _$insert(_el$126, () => lp().next?.slice(0, 60) || "", null);
-              _$effect((_$p) => _$setProp(_el$126, "style", {
+              var _el$128 = _$createElement("span"), _el$129 = _$createTextNode(` \u2192 `);
+              _$insertNode(_el$128, _el$129);
+              _$insert(_el$128, () => lp().next?.slice(0, 60) || "", null);
+              _$effect((_$p) => _$setProp(_el$128, "style", {
                 fg: theme().textMuted
               }, _$p));
-              return _el$126;
+              return _el$128;
             })()];
           })(), null);
           _$insert(_el$109, (() => {
             var _c$9 = _$memo(() => !!blk());
             return () => _c$9() && [(() => {
-              var _el$128 = _$createElement("span"), _el$129 = _$createTextNode(`
+              var _el$130 = _$createElement("span"), _el$131 = _$createTextNode(`
 \u2716 blocked: `);
-              _$insertNode(_el$128, _el$129);
-              _$effect((_$p) => _$setProp(_el$128, "style", {
+              _$insertNode(_el$130, _el$131);
+              _$effect((_$p) => _$setProp(_el$130, "style", {
                 fg: theme().error,
                 bold: true
               }, _$p));
-              return _el$128;
+              return _el$130;
             })(), (() => {
-              var _el$131 = _$createElement("span");
-              _$insert(_el$131, () => blk().reason.slice(0, 140));
-              _$effect((_$p) => _$setProp(_el$131, "style", {
+              var _el$133 = _$createElement("span");
+              _$insert(_el$133, () => blk().reason.slice(0, 140));
+              _$effect((_$p) => _$setProp(_el$133, "style", {
                 fg: theme().error
               }, _$p));
-              return _el$131;
+              return _el$133;
             })(), (() => {
-              var _el$132 = _$createElement("span"), _el$133 = _$createTextNode(` \u2014 `);
-              _$insertNode(_el$132, _el$133);
-              _$insert(_el$132, () => blk().needed.slice(0, 60), null);
-              _$effect((_$p) => _$setProp(_el$132, "style", {
+              var _el$134 = _$createElement("span"), _el$135 = _$createTextNode(` \u2014 `);
+              _$insertNode(_el$134, _el$135);
+              _$insert(_el$134, () => blk().needed.slice(0, 60), null);
+              _$effect((_$p) => _$setProp(_el$134, "style", {
                 fg: theme().textMuted
               }, _$p));
-              return _el$132;
+              return _el$134;
             })()];
           })(), null);
           _$insert(_el$109, (() => {
             var _c$0 = _$memo(() => !!goal().config.artifactDir);
             return () => _c$0() && [(() => {
-              var _el$134 = _$createElement("span"), _el$135 = _$createTextNode(`
+              var _el$136 = _$createElement("span"), _el$137 = _$createTextNode(`
 \uD83D\uDCC1 `);
-              _$insertNode(_el$134, _el$135);
-              _$effect((_$p) => _$setProp(_el$134, "style", {
+              _$insertNode(_el$136, _el$137);
+              _$effect((_$p) => _$setProp(_el$136, "style", {
                 fg: theme().accent
               }, _$p));
-              return _el$134;
+              return _el$136;
             })(), (() => {
-              var _el$137 = _$createElement("span");
-              _$insert(_el$137, () => String(goal().config.artifactDir).replace(String(props.directory), "."));
-              _$effect((_$p) => _$setProp(_el$137, "style", {
+              var _el$139 = _$createElement("span");
+              _$insert(_el$139, () => String(goal().config.artifactDir).replace(String(props.directory), "."));
+              _$effect((_$p) => _$setProp(_el$139, "style", {
                 fg: theme().textMuted
               }, _$p));
-              return _el$137;
+              return _el$139;
             })()];
           })(), null);
           _$insert(_el$109, (() => {
             var _c$1 = _$memo(() => (goal().config.checks?.length ?? 0) > 0);
             return () => _c$1() ? [(() => {
-              var _el$138 = _$createElement("span"), _el$139 = _$createTextNode(`
+              var _el$140 = _$createElement("span"), _el$141 = _$createTextNode(`
 \u25A3 checks: `);
-              _$insertNode(_el$138, _el$139);
-              _$effect((_$p) => _$setProp(_el$138, "style", {
+              _$insertNode(_el$140, _el$141);
+              _$effect((_$p) => _$setProp(_el$140, "style", {
                 fg: theme().warning
               }, _$p));
-              return _el$138;
+              return _el$140;
             })(), (() => {
-              var _el$141 = _$createElement("span");
-              _$insert(_el$141, () => goal().config.checks.join(", ").slice(0, 100));
-              _$effect((_$p) => _$setProp(_el$141, "style", {
+              var _el$143 = _$createElement("span");
+              _$insert(_el$143, () => goal().config.checks.join(", ").slice(0, 100));
+              _$effect((_$p) => _$setProp(_el$143, "style", {
                 fg: theme().textMuted
               }, _$p));
-              return _el$141;
+              return _el$143;
             })()] : null;
           })(), null);
           _$insert(_el$109, (() => {
             var _c$10 = _$memo(() => !!rt()?.lastError);
             return () => _c$10() && [(() => {
-              var _el$142 = _$createElement("span"), _el$143 = _$createTextNode(`
+              var _el$144 = _$createElement("span"), _el$145 = _$createTextNode(`
 \u26A0 `);
-              _$insertNode(_el$142, _el$143);
-              _$effect((_$p) => _$setProp(_el$142, "style", {
+              _$insertNode(_el$144, _el$145);
+              _$effect((_$p) => _$setProp(_el$144, "style", {
                 fg: theme().error
               }, _$p));
-              return _el$142;
+              return _el$144;
             })(), (() => {
-              var _el$145 = _$createElement("span");
-              _$insert(_el$145, () => rt().lastError.slice(0, 120));
-              _$effect((_$p) => _$setProp(_el$145, "style", {
+              var _el$147 = _$createElement("span");
+              _$insert(_el$147, () => rt().lastError.slice(0, 120));
+              _$effect((_$p) => _$setProp(_el$147, "style", {
                 fg: theme().error
               }, _$p));
-              return _el$145;
+              return _el$147;
             })()];
           })(), null);
           _$effect((_p$) => {
@@ -1535,29 +1585,29 @@ function LoopDashboard(props) {
           },
           children: (ev) => [`
 `, (() => {
-            var _el$146 = _$createElement("span");
-            _$insert(_el$146, () => String(ev.type));
-            _$effect((_$p) => _$setProp(_el$146, "style", {
+            var _el$148 = _$createElement("span");
+            _$insert(_el$148, () => String(ev.type));
+            _$effect((_$p) => _$setProp(_el$148, "style", {
               fg: eventColor(String(ev.type), theme()),
               bold: true
             }, _$p));
-            return _el$146;
+            return _el$148;
           })(), (() => {
-            var _el$147 = _$createElement("span"), _el$148 = _$createTextNode(` `);
-            _$insertNode(_el$147, _el$148);
-            _$insert(_el$147, () => ev.goalID?.slice(0, 8), null);
-            _$effect((_$p) => _$setProp(_el$147, "style", {
+            var _el$149 = _$createElement("span"), _el$150 = _$createTextNode(` `);
+            _$insertNode(_el$149, _el$150);
+            _$insert(_el$149, () => ev.goalID?.slice(0, 8), null);
+            _$effect((_$p) => _$setProp(_el$149, "style", {
               fg: theme().textMuted
             }, _$p));
-            return _el$147;
+            return _el$149;
           })(), _$memo(() => _$memo(() => !!ev.summary)() && (() => {
-            var _el$149 = _$createElement("span"), _el$150 = _$createTextNode(` \u2014 `);
-            _$insertNode(_el$149, _el$150);
-            _$insert(_el$149, () => String(ev.summary).slice(0, 60), null);
-            _$effect((_$p) => _$setProp(_el$149, "style", {
+            var _el$151 = _$createElement("span"), _el$152 = _$createTextNode(` \u2014 `);
+            _$insertNode(_el$151, _el$152);
+            _$insert(_el$151, () => String(ev.summary).slice(0, 60), null);
+            _$effect((_$p) => _$setProp(_el$151, "style", {
               fg: theme().text
             }, _$p));
-            return _el$149;
+            return _el$151;
           })())]
         }), null);
         _$effect((_p$) => {
@@ -1726,7 +1776,7 @@ var tui = async (api) => {
       run: open
     }],
     bindings: [{
-      key: "<leader>d",
+      key: "<leader>o",
       cmd: "opencode.loopd.dashboard",
       desc: "Open loop dashboard"
     }]

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bojackduy/opencode-loopd",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "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-only",

package/skills/loopd/SKILL.md

@@ -31,27 +31,59 @@ Do not use loopd when:
 ```
 created → active → complete
                   → blocked (needs user intervention)
+                  → budget_limited / usage_limited (engine limits)
          paused (user-initiated, can resume)
+         retry (blocked → active, clears failures)
 ```
 
+Only `active` goals own live worker runs. `blocked`/`paused`/`budget_limited` wait for an explicit owner transition (`resume`/`retry`/`nudge`). The loop is engine-driven, not parent-driven.
+
+## Contract & Evaluation Semantics
+
+Every goal has an **immutable contract** at creation — the source of truth for completion:
+
+* **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** — which subagent model runs the worker (`sloppy-agent`, `smart-agent`, …). Required unless `defaultAgent` is configured in `opencode.jsonc` plugin options.
+* **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.
+ * **Limits** — `maxTurns` (default 50), `maxNoProgress`, `maxFailures`, `maxEvaluatorRejections` (default 3), `timeoutMs`, `compactEvery`, `progressFile`.
+
+**Who decides completion:**
+* **Host is the acceptance authority** — it runs `checks` deterministically. If any check fails, `complete_goal` is **rejected** (`ok:false`, `rejectionCount++`, `freeRetryPending=true` for <3 rejections, `blocked` after 3). The worker gets the exact failure in the next steering.
+* **Model is the proposer** — it must self-audit via `## COMPLETION REVIEW` (derive requirements → locate evidence → judge `proves|contradicts|incomplete|missing`) and only call `complete_goal` when every requirement is proved. If objective and checks conflict, it must `block_goal`, not silently violate either.
+
+**Hardened loop guarantees (1da88dc):**
+* **Prompt correlation** — each turn’s prompt gets a `msg-` UUID (`activePromptMessageID`); the engine correlates `message.updated`/`message.part.updated` by that ID and by `runGeneration`. Stale events never release a newer lease.
+* **Generation fencing** — `idleCandidateAt` is tied to `idleCandidateGeneration`; a new prompt clears the candidate. Finalization also requires the transcript anchor: the latest user prompt must be the engine’s prompt **and** its assistant response must be completed.
+* **Maintenance (30s)** — auto-repairs `phase=idle + activeRunID` (stale lease), bounds `unknown` status polls (`unknownStatusCount` threshold 3 → one `notifyOwner` per episode, `workerUnreachableNotifiedAt` deduped), and recovers counters on success. `active`-only polling; `blocked`/`paused` never auto-continue.
+* **Per-goal mutex** — `withGoalOperation(goalID)` serializes `continueTurn`/`pause`/`resume`/`retry`/`clear`/`nudge` per goal, and `turn.acquire` re-checks `leaseIsValid` inside the transaction for exclusivity.
+* **Lease** — `acquireLease`/`releaseLease` + `timeoutMs` (default 5 min); prompt failures release the lease and schedule `waiting_retry` with exponential backoff.
+
 ## Creating a Goal
 
-Use `loopd_create_goal` after clarifying the objective with the user:
+Use `loopd_create_goal` **after** clarifying the objective with the user (what / where / how to verify). The tool validates the contract before spawning:
 
 ```
 loopd_create_goal({
   name: "short-name",
   objective: "Detailed description of what the goal should accomplish.",
-  checks: ["npm test"],                    // optional: shell commands for completion verification
-  progressFile: ".opencode/loopd/progress.md", // optional: worker reads/writes this
-  maxTurns: 50,                            // optional: safety budget
-  maxNoProgress: 5,                        // optional: auto-block without progress
-  maxFailures: 3,                          // optional: auto-block on failures
-  compactEvery: 3,                         // optional: compact worker session every N turns
+  agent: "smart-agent",                    // required unless plugin defaultAgent is configured
+  checks: ["npm test"],                    // mandatory if workspaceWrite:true (or configure defaultChecks)
+  checkCwd: "/project/root",               // optional; writers default to project root, readers to artifactDir
+  workspaceWrite: true,                    // default true; set false explicitly for artifact-only/read-only
+  progressFile: ".opencode/loopd/progress.md", // optional; defaults to <artifactDir>/progress.md
+  maxTurns: 50,                            // optional; ≥50 enforces FINAL REPORT REQUIRED
+  maxNoProgress: 5,                        // optional; auto-block without progress
+  maxFailures: 3,                          // optional; auto-block on failures
+  maxEvaluatorRejections: 3,               // optional; block after N check failures (default 3)
+  compactEvery: 3,                         // optional; compact worker session every N turns
+  timeoutMs: 300000,                       // optional; per-turn lease
 })
 ```
 
-The goal starts immediately. The user can monitor it via `/loop` (<leader>d).
+Returns `ok:true` with `goalID`, `workerSessionID`, `artifactDir`, `agent`, `checks`, `workspaceWrite`, `defaultsApplied:{agent,checks}`. On contract violation you get `ok:false` with `errorCode: "missing_agent"` or `"missing_checks"` or `"already active"` (writer serialization).
+
+The goal starts immediately. The user can monitor it via `/loop` (<leader>d). Plugin options `defaultAgent` / `defaultChecks` in `opencode.jsonc` can supply defaults so callers don’t have to repeat them.
 
 ## Worker Tools (Running Inside the Goal)
 
@@ -111,23 +143,34 @@ block_goal({
 
 ## Owner Tools (Parent Chat)
 
-These tools are available in the parent chat that created the goal:
+All are filtered by `ownerSessionID` (only the session that created the goal sees it). They are the **only** way to recover a stuck worker — they mutate the engine state (Entity B) and, when needed, force the bridge to the real subagent session (Entity A).
 
 ### list_background_goals
 
-Lists all active goals owned by this session. Shows status and progress.
+Lists all `active` goals owned by this session (name, status, phase, turn, last progress, blocker).
 
 ### inspect_background_goal
 
-Shows detailed info: objective, config, progress, blocker, runtime state.
+Shows detailed contract + runtime: `objective`, `config{agent,checks,checkCwd,workspaceWrite,limits,artifactDir}`, `lastProgress`, `completionEvidence`, `blocker`, `runtime{phase,runCount,budgetTurnCount,runGeneration,evaluatorRejectionCount,lastActivityAt,activePromptMessageID,unknownStatusCount}`.
 
 ### read_goal_transcript
 
-Reads the last N messages from the worker session. Useful for debugging what the worker is doing.
+Reads the last N messages from the worker session (`role`, `content`, `timestamp`, `messageID`). Use to see if the worker’s steering contained `HOST VERDICT`.
 
 ### send_goal_input
 
-Sends a message to the worker's next turn. See table above.
+Appends to the goal’s inbox file; the next `continueTurn` injects it as `## USER INSTRUCTIONS`. **Does not itself re-prompt** — the engine does on next idle/maintenance.
+
+### nudge_goal
+
+Force re-prompts a stuck worker even if `sessionStatus` is not `idle`. Clears stale `activeRunID`/`idleCandidateAt`/`activePromptMessageID`/lease, sets `phase=idle`, and calls `continueTurn({force:true})`. Use when `unknownStatusCount` ≥3 or the worker is `running` with no activity. Returns `{ok, message}`.
+
+### pause_goal / resume_goal / retry / clear
+
+* `pause_goal` — `active → paused`, `releaseLease`, `abortWorker`. Frees the writer slot.
+* `resume_goal` — `paused → active`, reuses the existing worker session if `sessionStatus` is still `idle`/`busy` (preserves transcript), otherwise creates a new one. Fails with `already active` if another writer is active.
+* `retry` (via `resume` on `blocked`) — `blocked → active`, resets `consecutiveFailures`/`forceFinishRequested`.
+* `clear_goal` — aborts worker and removes `goal` + `runtime` + ledger entry (cannot be undone).
 
 ## Dashboard Commands
 
@@ -165,13 +208,16 @@ Open the dashboard with `/loop` or <leader>d.
 
 ## Safety Patterns
 
-1. **Always call `get_goal` first** — Read the objective before doing any work.
-2. **Progress after durable changes** — Call `report_goal_progress` after file writes or verifications, not after thinking.
-3. **Complete with evidence** — Never call `complete_goal` without concrete proof (test output, file checks passing).
-4. **Block for real blockers only** — Don't block for things you can figure out. Block when you genuinely need user input.
-5. **Use checks for verification** — Set `checks` on goal creation to auto-verify completion (e.g., `["npm test", "test -f README.md"]`).
-6. **Set safety budgets** — Use `maxTurns`, `maxNoProgress`, and `maxFailures` to prevent runaway goals.
-7. **Compact periodically** — Use `compactEvery` to keep the worker session's context manageable.
+1. **Always call `get_goal` first** — Read the full contract (objective + checks + limits) before doing any work. The `COMPLETION REVIEW` and `HOST VERDICT` in steering are authoritative.
+2. **Progress after durable changes** — Call `report_goal_progress` after file writes or verifications (resets `consecutiveFailures`/`noProgressCount`), not after thinking.
+3. **Complete with evidence — host decides** — Never call `complete_goal` without concrete proof. The host will reject it if `checks` fail; you’ll get `Rejection #N` with exact `stderr` and a **free retry** (`budgetTurnCount` not charged for N<3). After 3 rejections the goal is `blocked`.
+4. **Block for real blockers only** — Don’t block for things you can figure out. If objective and `checks` appear contradictory, `block_goal` — don’t silently violate either.
+5. **Use checks for verification — mandatory for writers** — `workspaceWrite:true` goals **require** `checks` (explicit or `defaultChecks`). Checks run from `checkCwd` (writers → project root by default). `["npm test","bun run typecheck"]` is a good default.
+6. **Serialize workspace edits** — Keep `workspaceWrite:true` (the default) for code/repo changes. The engine allows **only one active writer**; a second `start`/`resume`/`retry` fails with `already active`. Use `workspaceWrite:false` explicitly for artifact-only research to allow concurrency.
+7. **Set safety budgets** — `maxTurns` (default 50), `maxNoProgress`, `maxFailures` prevent runaways. On `maxTurns`/`maxNoProgress` the engine injects `FINAL REPORT REQUIRED`; if ignored, it `blocked (force-finish ignored)` after the next idle.
+8. **Compact periodically** — `compactEvery` keeps the worker session’s context manageable.
+9. **Recover stuck workers explicitly** — If `inspect` shows `phase=running` with `unknownStatusCount ≥3` or `lastActivityAt` far in the past, use `nudge_goal` (force re-prompt) or `pause`/`resume`. `send_goal_input` alone does not re-prompt.
+10. **One writer, one check suite** — Don’t run concurrent `start` calls that touch the same files from parallel chats; chain them sequentially or mark the second as `workspaceWrite:false`.
 
 ## Example: Creating and Monitoring a Goal
 
@@ -179,17 +225,24 @@ Open the dashboard with `/loop` or <leader>d.
 ```
 User: Write a README for this project and create a changelog.
 
-Agent: I'll set up a background goal for this.
+Agent: I'll set up a background goal for this. What's the verification?
+
+User: Just that both files exist.
+
+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: "smart-agent",
   checks: ["test -f README.md", "test -f CHANGELOG.md"],
+  checkCwd: "/Users/you/project",           // explicit for writers; defaults to project root
+  workspaceWrite: true,                     // default true — serialized
   progressFile: ".opencode/loopd/docs-progress.md",
   maxTurns: 20
 })
-
-# Goal starts. User can monitor with /loop.
+# → {ok:true, artifactDir: ".opencode/loopd/goals/<id>", defaultsApplied:{...}}
+# Goal starts. User can monitor with /loop. If checks fail, the worker gets HOST VERDICT with exact stderr and a free retry.
 ```
 
 **Worker session (automatic):**