@aron98/load-lock 0.1.1 → 1.0.0

package/README.md

@@ -43,8 +43,11 @@ agent A (OpenCode)        agent B (Codex)         agent C (Claude Code)
   and auto-respawn transparently.
 - **Honest notifications** — tool-boundary offer delivery everywhere; real
   idle wakeup where the harness supports it (live-verified on OpenCode;
-  hook-based on Claude Code and Codex CLI); durable event ids for
-  reconnects. A notification never authorizes work — only `claim` does.
+  hook-based on Claude Code and Codex CLI); a bounded blocking
+  `wait_for_turn` (`load-lock wait` on the CLI) that sleeps until your
+  turn and auto-claims for harnesses without idle wakeup; durable event
+  ids for reconnects. A notification never authorizes work — only
+  `claim` does.
 - **Policy that actually reaches the model** — installed per harness via
   its real mechanism (plugin context hook, SessionStart hooks incl.
   compact matchers, global instruction files), plus a detailed skill/guide.
@@ -55,7 +58,8 @@ agent A (OpenCode)        agent B (Codex)         agent C (Claude Code)
 
 ```sh
 npm install -g @aron98/load-lock
-load-lock install --harness opencode     # or claude-code | codex | generic
+load-lock install --harness opencode     # or claude-code | codex | gemini-cli |
+                                         # copilot-cli | cline | roo-code | goose | generic
 load-lock doctor
 ```
 
@@ -67,9 +71,13 @@ use the generic stdio server; plain shells use the CLI:
 ```sh
 load-lock run --reason "nightly build" -- npm run build   # acquire→run→release
 load-lock status                                          # machine-wide view
+load-lock top                                             # live read-only dashboard (q quits)
 load-lock configure --capacity 2 --reason "16-core host" --author me
 ```
 
+OpenCode users also get a live dashboard panel inside the TUI (`/load-lock`)
+— same data, themed. See docs/OPERATIONS.md → "Dashboard".
+
 ## Layout
 
 ```
@@ -99,18 +107,35 @@ skills/         packaged skill
 
 ## Status
 
-- Core daemon/protocol/CLI: implemented, 32 automated tests passing
+- Core daemon/protocol/CLI: implemented, 68 automated tests passing
   (multi-process daemons, real processes, restarts, races, expiry,
-  PID-reuse, subprocess survival).
+  PID-reuse, subprocess survival; plus 9 dashboard tests — view-model
+  shaping, event-cursor resume across a daemon restart, reconnect, and a
+  `load-lock top --once` render smoke test).
 - OpenCode adapter: implemented and **live-verified** (tools, policy
   injection, compaction-proof context hook, execution-boundary wakeup
   with tokens, skill).
-- Claude Code + Codex CLI adapters: implemented, contract-tested against
-  documented hook JSON; not yet live-verified (harnesses not installed on
-  the verification machine).
-- Gemini CLI, Copilot CLI, Cursor, Cline, Roo Code, Goose, Aider:
-  researched; MCP fallback tier (Aider: manual CLI tier). See
-  COMPATIBILITY.md for the matrix.
+- Claude Code adapter: implemented, contract-tested against documented
+  hook JSON; not yet live-verified (harness not installed on the
+  verification machine).
+- Codex CLI adapter: implemented and **live-verified** end-to-end in
+  Docker (interactive TUI via pty: policy injection, MCP round-trip,
+  FIFO queueing behind a competing holder, Stop-hook decision-block
+  wakeup; see COMPATIBILITY.md for the two upstream/provider constraints
+  the verification harness works around).
+- Tier-3 fallback installers (Gemini CLI, Copilot CLI, Cline, Roo Code,
+  Goose): implemented merge-only installers (MCP stdio server entry into
+  the harness's real config + a global instructions-file section/policy
+  rule file), config-tested via temp-HOME round-trips; fallback tier (no
+  hooks, no async push — no idle wakeup).
+- Cursor adapter: implemented (issue #6) — merge-only project-level installer
+  (`.cursor/mcp.json` MCP entry, `.cursor/hooks.json` stop hook per the now-
+  officially-documented hooks v1 contract, `.cursor/rules/load-lock.mdc`
+  Always-apply rule) + `hook cursor stop` handler emitting
+  `{"followup_message":...}` idle wakeup. **Contract-tested**, not
+  live-verified (no Cursor on the verification machine).
+- Aider: researched; manual CLI tier. See COMPATIBILITY.md for the matrix.
 
 Linux-first; macOS works with documented liveness-check limitations;
-Windows would need a named-pipe transport adapter (planned, not built).
+Windows has a named-pipe transport adapter (implemented and unit-tested on
+Linux via platform injection; not yet verified on a Windows machine).

package/demo/demo.sh

@@ -99,7 +99,7 @@ say "final state"
     const j = JSON.parse(s);
     console.log(`config version ${j.config.version}; capacity(heavy)=${j.config.pools.heavy.capacity}; offer window ${j.config.offerTimeoutMs}ms`);
     console.log("change history:");
-    for (const h of j.history) console.log(`  v${h.version} by ${h.author}: ${h.reason}`);
+    for (const h of j.history) console.log(`  v${h.resultingVersion} by ${h.author}: ${h.reason}`);
   });'
 
 say "event log (durable identities — every grant, offer, claim, release)"

package/dist/adapters/opencode/plugin.js

@@ -20,6 +20,8 @@ import os from "node:os";
 import path from "node:path";
 import { LLClient } from "../../shared/client.js";
 import { POLICY_BRIEF } from "../../policy/text.js";
+import { waitForTurn, WaitAbortedError } from "../../shared/wait-turn.js";
+import { killProcessGroup } from "../../shared/transport.js";
 const client = new LLClient();
 const knownSessions = new Set();
 const jobs = new Map();
@@ -106,6 +108,40 @@ export default Plugin.define({
             })));
             add("cancel", "Cancel a queued/offered/paused request you no longer need.", { request_id: { type: "string" } }, (input) => client.request("cancel", { requestId: input.request_id }));
             add("rejoin", "Rejoin the FIFO queue after your offer expired or you declined (paused requests never auto-recycle).", { request_id: { type: "string" } }, (input) => client.request("rejoin", { requestId: input.request_id }));
+            add("wait_for_turn", "Sleep until it is your turn (bounded blocking wait for a queued request). Returns a structured result on every path: granted (offer auto-claimed for you — permit_token in entry), still_queued (timed out; queue_position + holders shown), paused (rejoin instructions), cancelled, or not_found (daemon restarted — acquire again). Holds NO permit and NO capacity; cancelling this call is safe and never strands anything — the request keeps its queue position.", {
+                request_id: { type: "string", description: "Request to watch (default: your oldest offered/front-most queued/oldest paused request)" },
+                timeout_ms: { type: "number", description: "Bounded sleep in ms (default 600000, clamped to the machine's maxTurnWaitMs cap; 0 = check-only)" },
+            }, async (input, context) => {
+                try {
+                    const r = await waitForTurn({
+                        client,
+                        agentId: context.sessionID,
+                        requestId: input.request_id,
+                        timeoutMs: input.timeout_ms,
+                        signal: context.signal,
+                    });
+                    return {
+                        state: r.state,
+                        request_id: r.requestId,
+                        auto_claimed: r.autoClaimed,
+                        permit_token: r.state === "granted" ? r.entry?.permitToken : undefined,
+                        waited_ms: r.waitedMs,
+                        effective_wait_ms: r.effectiveWaitMs,
+                        entry: r.entry,
+                        queue_position: r.queuePosition,
+                        queue_length: r.queueLength,
+                        holders: r.holders,
+                        next_action: r.nextAction,
+                        detail: r.detail,
+                    };
+                }
+                catch (err) {
+                    if (err instanceof WaitAbortedError) {
+                        return { state: "aborted", detail: "wait cancelled by the harness/caller; the request keeps its queue position" };
+                    }
+                    throw err;
+                }
+            });
             add("pending", "Your outstanding offers (claim NOW — they expire), queue positions, paused and held requests.", {}, (_input, context) => client.request("pending", { agentId: context.sessionID }));
             add("status", "Machine-wide pool snapshot: capacity, holders, offers, queue.", { pool: { type: "string" } }, (input) => client.request("status", input.pool ? { pool: input.pool } : {}));
             add("inspect_machine", "Honest machine resources incl. cgroup/container limits and current pressure.", {}, () => client.request("inspect", {}));
@@ -161,12 +197,7 @@ export default Plugin.define({
                     await client.request("start_job", { permitToken: input.permit_token, pid: child.pid, pgid: child.pid });
                 }
                 catch (err) {
-                    try {
-                        process.kill(-child.pid, "SIGKILL");
-                    }
-                    catch {
-                        /* already gone */
-                    }
+                    killProcessGroup(child.pid, "SIGKILL");
                     return { error: `permit no longer startable (${err.message}); job killed before doing work; acquire again` };
                 }
                 jobs.set(job.id, job);
@@ -189,20 +220,10 @@ export default Plugin.define({
                 if (!job)
                     return { error: "unknown job_id" };
                 if (!job.exited) {
-                    try {
-                        process.kill(-job.child.pid, "SIGTERM");
-                    }
-                    catch {
-                        /* already gone */
-                    }
+                    killProcessGroup(job.child.pid, "SIGTERM");
                     setTimeout(() => {
                         if (!job.exited) {
-                            try {
-                                process.kill(-job.child.pid, "SIGKILL");
-                            }
-                            catch {
-                                /* already gone */
-                            }
+                            killProcessGroup(job.child.pid, "SIGKILL");
                         }
                     }, 5000).unref?.();
                 }

package/dist/adapters/opencode/tui.d.ts

@@ -0,0 +1,31 @@
+/**
+ * load-lock TUI plugin for OpenCode V2 — live lock-status dashboard (issue #10).
+ *
+ * Companion to the main SDK plugin (src/adapters/opencode/plugin.ts, which
+ * owns tools/policy/wakeups and stays unchanged). Exposed through the
+ * package's "./tui" export; the OpenCode TUI loads it automatically beside
+ * the main plugin (see the plugin guide's "Publish and load" section).
+ *
+ * Surfaces:
+ *  - "load-lock.dashboard" session panel: pools with capacity vs in-use,
+ *    holder cards (label, reason, phase, pid/pgid, age, lease deadline),
+ *    offer cards with claim-window countdown, FIFO queue positions,
+ *    paused requests, the recent event feed, and the inspect_machine panel
+ *  - a home.footer.status indicator summarizing the heavy pool
+ *  - /load-lock (palette + slash command) opens the panel full-screen
+ *  - 'r' resync and 'x' force-release while the panel is open; force-release
+ *    is an admin action gated behind an explicit select + confirm dialog
+ *
+ * The viewer is read-only and light: it only ever READS daemon state
+ * (status / events / inspect / watch) and never acquires a permit itself.
+ *
+ * Reactivity note: this file is compiled by plain tsc (no Solid babel
+ * preset), so JSX expressions evaluate eagerly instead of becoming reactive
+ * getters. All liveness therefore flows through ONE keyed <Show> boundary
+ * (created with explicit property getters) that is recreated whenever the
+ * feed emits a new view snapshot or the 1s countdown tick fires; below
+ * that boundary, eager evaluation is exactly the semantics we want.
+ */
+import { Plugin } from "@opencode/plugin/tui";
+declare const _default: Plugin.Definition;
+export default _default;

package/dist/adapters/opencode/tui.js

@@ -0,0 +1,268 @@
+import { jsx as _jsx, Fragment as _Fragment } from "@opentui/solid/jsx-runtime";
+/**
+ * load-lock TUI plugin for OpenCode V2 — live lock-status dashboard (issue #10).
+ *
+ * Companion to the main SDK plugin (src/adapters/opencode/plugin.ts, which
+ * owns tools/policy/wakeups and stays unchanged). Exposed through the
+ * package's "./tui" export; the OpenCode TUI loads it automatically beside
+ * the main plugin (see the plugin guide's "Publish and load" section).
+ *
+ * Surfaces:
+ *  - "load-lock.dashboard" session panel: pools with capacity vs in-use,
+ *    holder cards (label, reason, phase, pid/pgid, age, lease deadline),
+ *    offer cards with claim-window countdown, FIFO queue positions,
+ *    paused requests, the recent event feed, and the inspect_machine panel
+ *  - a home.footer.status indicator summarizing the heavy pool
+ *  - /load-lock (palette + slash command) opens the panel full-screen
+ *  - 'r' resync and 'x' force-release while the panel is open; force-release
+ *    is an admin action gated behind an explicit select + confirm dialog
+ *
+ * The viewer is read-only and light: it only ever READS daemon state
+ * (status / events / inspect / watch) and never acquires a permit itself.
+ *
+ * Reactivity note: this file is compiled by plain tsc (no Solid babel
+ * preset), so JSX expressions evaluate eagerly instead of becoming reactive
+ * getters. All liveness therefore flows through ONE keyed <Show> boundary
+ * (created with explicit property getters) that is recreated whenever the
+ * feed emits a new view snapshot or the 1s countdown tick fires; below
+ * that boundary, eager evaluation is exactly the semantics we want.
+ */
+import { Plugin } from "@opencode/plugin/tui";
+import { createComponent, createSignal, Show } from "solid-js";
+import { LLClient } from "../../shared/client.js";
+import { DashboardFeed } from "../../dashboard/feed.js";
+import { fmtBytes, fmtClock, fmtDuration, } from "../../dashboard/view.js";
+const PANEL_NAME = "load-lock.dashboard";
+function themeFg(t) {
+    return {
+        base: t.text.base,
+        dim: t.text.muted,
+        accent: t.text.feedback.info.base,
+        good: t.text.feedback.success.base,
+        warn: t.text.feedback.warning.base,
+        bad: t.text.feedback.error.base,
+    };
+}
+function stateColor(s, f) {
+    if (s === "live")
+        return f.good;
+    if (s === "connecting")
+        return f.dim;
+    return f.bad;
+}
+const STATE_LABEL = {
+    live: "LIVE",
+    connecting: "CONNECTING",
+    reconnecting: "RECONNECTING",
+    down: "DAEMON DOWN",
+};
+function holderLines(h, out, fg) {
+    const id = h.requestId.slice(0, 14);
+    let meta = h.phaseLabel;
+    if (h.phase === "claimed" && h.startDeadlineInMs !== undefined)
+        meta += ` · must start in ${fmtDuration(h.startDeadlineInMs)}`;
+    if (h.phase === "running_tracked" && h.pid !== undefined)
+        meta += ` · pid ${h.pid}` + (h.pgid !== undefined && h.pgid !== h.pid ? ` · pgid ${h.pgid}` : "");
+    if (h.phase === "running_untracked" && h.leaseDeadlineInMs !== undefined)
+        meta += ` · lease ends in ${fmtDuration(h.leaseDeadlineInMs)}`;
+    out.push({ text: `  HELD   ${h.agent} (${id}) · ${meta} · age ${fmtDuration(h.heldMs)}`, fg: fg.good });
+    out.push({ text: `         reason: ${h.reason}`, fg: fg.dim });
+}
+function dashboardLines(v, width, f) {
+    const W = Math.max(40, width - 2);
+    const out = [];
+    const push = (text, fg) => {
+        out.push({ text: text.length > W ? text.slice(0, W - 1) + "…" : text, fg });
+    };
+    const syncAge = v.lastSyncAt ? fmtDuration(Math.max(0, v.now - v.lastSyncAt)) : "never";
+    push(`load-lock dashboard   ${STATE_LABEL[v.state] ?? v.state}   synced ${syncAge} ago`, stateColor(v.state, f));
+    if (v.daemon) {
+        push(`daemon pid ${v.daemon.pid} · uptime ${fmtDuration(v.daemon.uptimeMs)} · config v${v.daemon.configVersion} · protocol v${v.daemon.protocolVersion} · events through #${v.latestEventId}`, f.dim);
+    }
+    else {
+        push(`daemon unreachable — it auto-spawns on the next load-lock command`, f.dim);
+    }
+    if (v.daemonRestartNote)
+        push(`note: ${v.daemonRestartNote}`, f.warn);
+    if (v.machine) {
+        const m = v.machine;
+        const cg = m.cgroupCpuQuota != null ? ` · cgroup quota ${m.cgroupCpuQuota / 100} CPU` : "";
+        push(`MACHINE  ${m.logicalCores} cores (effective ${m.effectiveCores}${cg}) · load ${m.loadavg.map((n) => n.toFixed(2)).join(" ")} = ${m.loadPerEffectiveCore.toFixed(2)}/core · mem ${fmtBytes(m.memTotalBytes)} total, ${fmtBytes(m.memAvailableBytes)} avail (limit ${fmtBytes(m.memEffectiveLimitBytes)})`, f.accent);
+        push(`         pressure: cpu ${m.loadPressure}, mem ${m.memPressure} — ${m.note}`, f.dim);
+        if (m.suggestion)
+            push(`         suggestion: ${m.suggestion}`, f.dim);
+    }
+    push("");
+    if (!v.pools.length)
+        push(`no pools configured`, f.dim);
+    for (const p of v.pools) {
+        const full = p.capacity > 0 && p.used >= p.capacity;
+        push(`POOL ${p.pool}  ${p.used}/${p.capacity} used (held ${p.heldWeight}, offered ${p.offeredWeight}, free ${p.free}) · queue ${p.queue.length} · paused ${p.paused.length}`, full ? f.warn : f.accent);
+        for (const h of p.holders)
+            holderLines(h, out, f);
+        for (const o of p.offers) {
+            const id = o.requestId.slice(0, 14);
+            const window = o.claimInMs >= 0 ? `claim within ${fmtDuration(o.claimInMs)}` : "claim window elapsed";
+            out.push({ text: `  OFFER  ${o.agent} (${id}) · ${window} · expires ${fmtClock(o.expiresAt)}`, fg: f.warn });
+            out.push({ text: `         reason: ${o.reason}`, fg: f.dim });
+        }
+        for (const q of p.queue) {
+            push(`  QUEUE  #${q.position}  ${q.agent} — ${q.reason} (waiting ${fmtDuration(q.waitMs)})`, f.base);
+        }
+        for (const q of p.paused) {
+            push(`  PAUSED ${q.agent} — ${q.reason} (paused ${fmtDuration(q.pausedMs)} · rejoin required)`, f.bad);
+        }
+    }
+    push("");
+    push(`EVENTS (newest first)`, f.accent);
+    if (!v.events.length)
+        push(`  (no events yet)`, f.dim);
+    for (const e of v.events.slice(0, 12)) {
+        push(`  #${e.id} ${fmtClock(e.ts)}  ${e.text}`);
+    }
+    push("");
+    push(`r resync · x force-release (admin, confirm required) · Esc closes · read-only viewer — never acquires a permit`, f.dim);
+    return out;
+}
+function PanelBody(v, panel, ctx) {
+    const f = themeFg(ctx.theme);
+    const lines = dashboardLines(v, panel.width || 100, f);
+    return (_jsx("box", { children: _jsx(_Fragment, { children: lines.map((l) => (_jsx("text", { fg: l.fg, children: l.text }))) }) }));
+}
+function MiniIndicator(v, ctx) {
+    const f = themeFg(ctx.theme);
+    const pool = v.pools.find((p) => p.pool === "heavy") ?? v.pools[0];
+    if (!pool)
+        return _jsx("text", { fg: f.dim, children: "lock: no pools" });
+    const bits = [`${pool.used}/${pool.capacity}`];
+    if (pool.queue.length)
+        bits.push(`Q${pool.queue.length}`);
+    if (pool.paused.length)
+        bits.push(`P${pool.paused.length}`);
+    const fg = v.state !== "live"
+        ? f.bad
+        : pool.used >= pool.capacity
+            ? f.warn
+            : pool.queue.length
+                ? f.warn
+                : f.good;
+    return _jsx("text", { fg: fg, children: `lock ${bits.join("·")}` });
+}
+// ---------------------------------------------------------------- plugin
+export default Plugin.define({
+    id: "load-lock.tui",
+    setup(ctx) {
+        const [view, setView] = createSignal(null);
+        const feed = new DashboardFeed(new LLClient());
+        feed.onChange = () => setView(feed.view());
+        feed.onState = () => setView(feed.view());
+        void feed.start().catch(() => {
+            /* daemon down or spawning; the feed keeps retrying and will go live */
+        });
+        // Local countdown tick: produces a fresh snapshot once per second so
+        // ages/deadlines advance even between daemon events.
+        const tick = setInterval(() => setView(feed.view()), 1000);
+        tick.unref?.();
+        const panelOpen = () => ctx.ui.panel.current()?.name === PANEL_NAME;
+        // ------------------------------------------------------ force-release
+        async function forceReleaseFlow() {
+            const holders = (feed.view().pools ?? []).flatMap((p) => p.holders);
+            if (!holders.length) {
+                ctx.ui.toast.show({ message: "load-lock: no held permits to release", variant: "info" });
+                return;
+            }
+            const pick = await ctx.ui.dialog.select({
+                title: "Force-release a permit (admin)",
+                placeholder: "Select holder",
+                options: holders.map((h) => ({
+                    title: `${h.agent} (${h.requestId.slice(0, 14)})`,
+                    description: `${h.phaseLabel}${h.pid !== undefined ? ` · pid ${h.pid}` : ""} · held ${fmtDuration(h.heldMs)} · ${h.reason}`,
+                    value: h.requestId,
+                })),
+            });
+            if (!pick)
+                return;
+            const confirmed = await ctx.ui.dialog.confirm({
+                title: "Force-release permit",
+                message: `Reclaim ${pick}? Its owner may still be mid-build; this is a last-resort recovery action.`,
+                label: { confirm: "Force-release", cancel: "Cancel" },
+            });
+            if (confirmed !== true)
+                return;
+            try {
+                await feed.forceRelease(pick);
+                ctx.ui.toast.show({ message: `load-lock: force-released ${pick.slice(0, 14)}`, variant: "warning" });
+            }
+            catch (e) {
+                ctx.ui.toast.show({ message: `load-lock: force-release failed: ${String(e)}`, variant: "error" });
+            }
+        }
+        // ----------------------------------------------------------- keymap
+        ctx.keymap.layer(() => ({
+            mode: "global",
+            priority: 5,
+            commands: [
+                {
+                    id: "load-lock.dashboard.open",
+                    title: "load-lock: open the lock-status dashboard",
+                    group: "load-lock",
+                    palette: true,
+                    slash: { name: "load-lock", aliases: ["lock", "ll"] },
+                    run: () => {
+                        ctx.ui.panel.open(PANEL_NAME, { presentation: "fullscreen" });
+                    },
+                },
+                {
+                    id: "load-lock.dashboard.resync",
+                    title: "load-lock: resync the dashboard",
+                    group: "load-lock",
+                    bind: "r",
+                    enabled: panelOpen,
+                    run: () => {
+                        void feed.resync().catch(() => { });
+                    },
+                },
+                {
+                    id: "load-lock.dashboard.force-release",
+                    title: "load-lock: force-release a permit (admin)",
+                    group: "load-lock",
+                    bind: "x",
+                    enabled: panelOpen,
+                    run: () => {
+                        void forceReleaseFlow();
+                    },
+                },
+            ],
+        }));
+        // ------------------------------------------------------------ slots
+        // Session panel contribution: renders only when our name is selected.
+        const offPanel = ctx.ui.slot({
+            append: "session.panel",
+            render: (panel) => createComponent(Show, {
+                get when() {
+                    return panel.name === PANEL_NAME ? (view() ?? false) : false;
+                },
+                keyed: true,
+                children: (v) => PanelBody(v, panel, ctx),
+            }),
+        });
+        // Home footer mini indicator (heavy pool summary).
+        const offFooter = ctx.ui.slot({
+            append: "home.footer.status",
+            render: () => createComponent(Show, {
+                get when() {
+                    return view() ?? false;
+                },
+                keyed: true,
+                children: (v) => MiniIndicator(v, ctx),
+            }),
+        });
+        return () => {
+            if (tick)
+                clearInterval(tick);
+            offPanel();
+            offFooter();
+            void feed.stop();
+        };
+    },
+});

package/dist/cli/hook.js

@@ -1,5 +1,5 @@
 /**
- * load-lock harness hook handlers (Claude Code, Codex CLI).
+ * load-lock harness hook handlers (Claude Code, Codex CLI, Cursor).
  *
  * These are invoked by the harness's hook system with the harness's hook
  * JSON on stdin. They are intentionally fast (one daemon RPC or none) and
@@ -16,6 +16,11 @@
  *  - Codex SessionStart/SubagentStart: plain stdout = additionalContext.
  *  - Codex Stop: {"decision":"block","reason":...} continues; async hooks
  *    cannot wake an idle Codex session (documented limitation).
+ *  - Cursor Stop (hooks v1, https://cursor.com/docs/hooks): stdin carries
+ *    workspace_roots (no cwd) and loop_count; stdout JSON
+ *    {"followup_message":...} is auto-submitted as the next user message
+ *    (idle wakeup). loop_count > 0 guards against followup loops. Verified
+ *    against the official docs only (contract-tested, not live-verified).
  */
 import { LLClient } from "../shared/client.js";
 import { POLICY_BRIEF } from "../policy/text.js";
@@ -103,6 +108,35 @@ export async function hookCommand(rest) {
             }
             return;
         }
+        // Cursor Stop (hooks v1): {"followup_message":...} is auto-submitted by
+        // Cursor as the next user message — the documented loop-style idle
+        // wakeup. loop_count counts prior stop-hook followups for this
+        // conversation (starts at 0) — Cursor's stop_hook_active equivalent.
+        case "cursor/stop": {
+            if ((input.loop_count ?? 0) > 0) {
+                return; // already woke once for this conversation; do not loop
+            }
+            const cursorCwd = input.workspace_roots?.[0] || process.cwd();
+            try {
+                const c = new LLClient({ spawnDaemon: false });
+                await c.connect();
+                try {
+                    const { offers } = (await c.request("offers_for_cwd", { cwd: cursorCwd }));
+                    if (offers.length > 0) {
+                        const o = offers[0];
+                        const seconds = Math.max(0, Math.round(((o.offerExpiresAt ?? Date.now()) - Date.now()) / 1000));
+                        process.stdout.write(JSON.stringify({ followup_message: claimInstruction(o, seconds) }) + "\n");
+                    }
+                }
+                finally {
+                    c.close();
+                }
+            }
+            catch {
+                /* daemon down: nothing to deliver */
+            }
+            return;
+        }
         // async + asyncRewake watcher (Claude Code only; Codex async hooks cannot
         // wake an idle session — documented).
         case "claude-code/await-offer": {