@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/watchdog/runner.js

@@ -36,6 +36,13 @@ import { injectIntoTerminal } from '../terminal/inject.js';
 import { classifyTerminal, isLikelyTrulyBlocked, renderWatchdogPrompt, parseWatchdogResponse, } from './watchdog.js';
 import { readWatchdogTail, WATCHDOG_STALL_MS, WATCHDOG_COOLDOWN_MS, WATCHDOG_DORMANT_MS, WATCHDOG_TAIL_LINES, } from './read.js';
 import { getRuntimeStateDir } from '../state.js';
+import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomic.js';
+import { resolveAnswerRoute, isOpenQuestionBlock } from '../answer-router.js';
+import { enqueue, mailboxDir } from '../mailbox.js';
+import { mailboxIdForActiveSession } from '../mailbox-target.js';
+import { readBlock, blockIdForSession } from '../feed.js';
+import { summarizeWatchdogTail } from './watchdogTail.js';
+import { appendWatchdogEvents } from './log.js';
 export const DEFAULT_THRESHOLDS = {
     stallMs: WATCHDOG_STALL_MS,
     cooldownMs: WATCHDOG_COOLDOWN_MS,
@@ -103,12 +110,10 @@ function defaultLastActivity(s) {
     return s.startedAtMs;
 }
 /**
- * Minimal local mirror of COMPLETION_HINTS in watchdog.ts:42-47. We cannot lean
- * on isLikelyTrulyBlocked to screen completions out: its FORCE_REVIEW_STALL_MS
- * short-circuit (watchdog.ts:171 — `stalledForMs >= 15m` returns true) fires
- * BEFORE its own COMPLETION_HINTS check (watchdog.ts:176), so a session idle
- * 15m-60m whose tail says "done"/"finished" would be reported as blocked. Keep
- * this list in sync with the core.
+ * COMPLETION_HINTS mirror of watchdog.ts. The deterministic pre-filter screens
+ * completions to `skip` before the promise check so a finished-but-idle session
+ * is never nudged. (isLikelyTrulyBlocked also guards completion now that its 15m
+ * precedence is fixed; this explicit check keeps the pre-filter self-contained.)
  */
 const COMPLETION_HINTS = ['done', 'completed', 'all set', 'finished'];
 function tailShowsCompletion(candidate) {
@@ -118,45 +123,130 @@ function tailShowsCompletion(candidate) {
     return COMPLETION_HINTS.some((hint) => lowerTail.includes(hint));
 }
 function deterministicDecision(session, candidate) {
+    // Parked on a question — the case Muqsit cares about most. Do NOT drop it:
+    // escalate to the brain, which decides drive-forward vs leave-for-human.
     if (session.activity === 'waiting_input') {
-        return { nudge: false, reason: `waiting on user${session.awaitingReason ? ` (${session.awaitingReason})` : ''}` };
+        return {
+            kind: 'escalate',
+            reason: `parked on a question${session.awaitingReason ? ` (${session.awaitingReason})` : ''} — escalate to the brain`,
+        };
     }
-    // Completion is checked EXPLICITLY here — never nudge a finished session, even
-    // past the 15m force-review window where isLikelyTrulyBlocked would return true
-    // before reaching its completion check (see COMPLETION_HINTS note above).
+    // Clearly complete — cheap skip, no LLM.
     if (tailShowsCompletion(candidate)) {
-        return { nudge: false, reason: 'tail shows completion (done / finished / all set) — skip regardless of stall age' };
+        return { kind: 'skip', reason: 'tail shows completion (done / finished / all set) — skip' };
     }
+    // Clear promise-without-toolcall — cheap nudge, no LLM.
     if (isLikelyTrulyBlocked(candidate)) {
-        return { nudge: true, reason: 'stalled after announcing an action with no follow-through' };
+        return { kind: 'nudge', reason: 'stalled after announcing an action with no follow-through' };
     }
-    return { nudge: false, reason: 'no promise-without-toolcall signal in tail (completion / question / unclear)' };
+    // Ambiguous stall — let the brain judge rather than blindly skip.
+    return { kind: 'escalate', reason: 'ambiguous stall — escalate to the brain' };
 }
 /**
- * The optional LLM decider. Shells out to `agents run <agent>` with the watchdog
- * prompt and parses its JSON verdict. Best-effort and NON-deterministic — the
- * default path is deterministicDecision. Isolated here so the tick stays pure
- * over its seams; the command layer opts in with --smart.
+ * The smart brain. Resolves a `watchdog` workflow for the session's cwd
+ * (project > user > system precedence, via resolveWorkflowRef) so a repo/user
+ * override AND `model:` frontmatter come for free; when a workflow resolves it
+ * runs `agents run watchdog --mode plan <prompt>`, else it falls back to the
+ * improved built-in prompt via `agents run <agent> --mode plan <prompt>`. Plan
+ * mode keeps the decider read-only. Best-effort and NON-deterministic: any
+ * failure (decider unavailable, no verdict) returns a SAFE skip — a parked
+ * question we cannot judge is left for the human, never blindly nudged.
  */
-async function smartDecision(candidate, agent) {
-    const prompt = renderWatchdogPrompt([candidate]);
+export function makeDefaultSmartDecider(agent) {
+    return async (session, candidate) => {
+        const prompt = renderWatchdogPrompt([candidate]);
+        try {
+            const [{ resolveWorkflowRef }, { execFile }, { promisify }] = await Promise.all([
+                import('../workflows.js'),
+                import('child_process'),
+                import('util'),
+            ]);
+            const cwd = session.cwd || process.cwd();
+            const workflowPath = resolveWorkflowRef('watchdog', cwd);
+            // A resolved `watchdog` workflow runs by name so its WORKFLOW.md body + model
+            // frontmatter apply; otherwise the bare agent runs the built-in prompt.
+            const runTarget = workflowPath ? 'watchdog' : agent;
+            const execFileAsync = promisify(execFile);
+            const { stdout } = await execFileAsync('agents', ['run', runTarget, '--mode', 'plan', prompt], {
+                encoding: 'utf8',
+                maxBuffer: 4 * 1024 * 1024,
+                timeout: 120_000,
+            });
+            const decisions = parseWatchdogResponse(stdout);
+            const d = decisions.find((x) => x.terminalId === candidate.terminalId) ?? decisions[0];
+            if (!d)
+                return { nudge: false, reason: 'smart decider returned no verdict' };
+            return { nudge: d.action === 'nudge', reason: d.reason || `smart: ${d.action}`, text: d.text || undefined };
+        }
+        catch (err) {
+            return { nudge: false, reason: `smart decider unavailable: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    };
+}
+/**
+ * Pick the delivery mechanism. resolveAnswerRoute (answer-router.ts) chooses
+ * mailbox vs resume vs refuse; resolveInjectTargetForSession (resolve.ts) supplies
+ * the precise inject target — CRUCIALLY it handles the vscodium rail that the
+ * answer-router's own resolver cannot, so an IDE-terminal (VS Codium / Cursor /
+ * VS Code) session parked on a question is injected into its exact terminal rather
+ * than being downgraded to resume/refuse. When a precise rail exists it wins
+ * (that includes a stalled non-parked agent, so the v1 terminal-inject path is
+ * preserved and no nudge is stranded in a mailbox the agent will never poll).
+ */
+function planDelivery(session, chosenText, block, allowGhosttyFocus) {
+    const sessionId = session.sessionId ?? '';
+    const mailboxId = mailboxIdForActiveSession(session) ?? sessionId;
+    const resolution = resolveInjectTargetForSession(session, { allowGhosttyFocus });
+    const route = resolveAnswerRoute({ mailboxId, answer: chosenText, session, block });
+    // A precise split (tmux / iTerm / vscodium / pty) is the authoritative target.
+    if (resolution.addressable) {
+        return { via: 'inject', rail: resolution.rail, target: resolution.target };
+    }
+    // No precise rail: honor the answer-router's parked-agent decision.
+    if (route.kind === 'resume')
+        return { via: 'resume' };
+    // Mailbox is correct ONLY for a still-looping agent that has an OPEN question
+    // block — it is seen at the next tool call. A stalled agent that simply stopped
+    // (no open block) would never poll the mailbox, so it is flagged instead of
+    // silently dropping a nudge into a spool it will never read.
+    if (route.kind === 'mailbox' && isOpenQuestionBlock(block))
+        return { via: 'mailbox', mailboxId };
+    return { via: 'refuse', reason: route.kind === 'refuse' ? route.reason : resolution.reason };
+}
+/** Default open-block reader — the same lookup `agents message` uses. */
+function defaultOpenBlockFor(session) {
+    const id = mailboxIdForActiveSession(session) ?? session.sessionId;
+    if (!id)
+        return null;
+    const direct = readBlock(blockIdForSession(id));
+    if (direct && direct.mailboxId === id)
+        return direct;
+    return null;
+}
+/** Enqueue a nudge into a session's mailbox (running agent, seen at next tool call). */
+function deliverViaMailbox(mailboxId, text, block) {
+    enqueue(mailboxDir(mailboxId), { to: mailboxId, text, from: 'watchdog', blockId: block?.blockId });
+}
+/** Re-enter a parked headless agent with the nudge as its next user turn. */
+async function deliverViaResume(session, text) {
+    const sid = session.sessionId;
+    if (!sid)
+        return { ok: false, error: 'no session id to resume' };
     try {
-        const { execFile } = await import('child_process');
-        const { promisify } = await import('util');
-        const execFileAsync = promisify(execFile);
-        const { stdout } = await execFileAsync('agents', ['run', agent, '--mode', 'plan', prompt], {
-            encoding: 'utf8',
-            maxBuffer: 4 * 1024 * 1024,
-            timeout: 120_000,
+        const [{ getAgentsInvocation }, { spawn }] = await Promise.all([
+            import('../daemon.js'),
+            import('child_process'),
+        ]);
+        const inv = getAgentsInvocation(['run', session.kind, '--resume', sid, '--', text]);
+        const code = await new Promise((resolve) => {
+            const child = spawn(inv.command, inv.args, { stdio: 'ignore', env: process.env, detached: false });
+            child.on('exit', (c) => resolve(c ?? 1));
+            child.on('error', () => resolve(1));
         });
-        const decisions = parseWatchdogResponse(stdout);
-        const d = decisions.find((x) => x.terminalId === candidate.terminalId) ?? decisions[0];
-        if (!d)
-            return { nudge: false, reason: 'smart decider returned no verdict' };
-        return { nudge: d.action === 'nudge', reason: d.reason || `smart: ${d.action}`, text: d.text || undefined };
+        return code === 0 ? { ok: true } : { ok: false, error: `resume exited ${code}` };
     }
     catch (err) {
-        return { nudge: false, reason: `smart decider unavailable: ${err instanceof Error ? err.message : String(err)}` };
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
     }
 }
 // --- the tick ---------------------------------------------------------------
@@ -174,10 +264,18 @@ export async function runWatchdogTick(opts = {}) {
     const lastActivityFor = opts.lastActivityFor ?? defaultLastActivity;
     const tailFor = opts.tailFor ?? ((s) => (s.sessionId ? readWatchdogTail(s.sessionId, s.kind, WATCHDOG_TAIL_LINES) : []));
     const policyFor = opts.policyFor ?? ((s) => (s.sessionId ? readPolicySentinel(dir, s.sessionId) : 'keep'));
+    const smartDecider = opts.smartDecider ?? makeDefaultSmartDecider(opts.smartAgent ?? 'claude');
+    const openBlockFor = opts.openBlockFor ?? defaultOpenBlockFor;
+    const injectFn = opts.injectFn ?? injectIntoTerminal;
     const sessions = opts.sessions ?? (await getActiveSessions());
     const ledger = readNudgeLedger(dir);
+    // Cooldown timestamps this tick decided to (re)start — merged into the ledger
+    // under a lock at the end so a concurrent tick's updates are never lost.
+    const ledgerUpdates = {};
     const flags = {};
     const outcomes = [];
+    const logEvents = [];
+    const viaLabel = (plan) => plan.via === 'inject' ? `inject (${plan.rail})` : plan.via;
     for (const session of sessions) {
         const policy = policyFor(session);
         const base = {
@@ -236,39 +334,66 @@ export async function runWatchdogTick(opts = {}) {
             tailLines,
             stalledForMs: status.stalledForMs,
         };
-        const decision = opts.smart
-            ? await smartDecision(candidate, opts.smartAgent ?? 'claude')
-            : deterministicDecision(session, candidate);
+        // The brain. The cheap deterministic pre-filter resolves the obvious cases;
+        // parked-on-question and ambiguous stalls ESCALATE to the smart brain. `smart`
+        // forces every stalled candidate through the brain.
+        let decision;
+        if (opts.smart) {
+            decision = await smartDecider(session, candidate);
+        }
+        else {
+            const det = deterministicDecision(session, candidate);
+            decision = det.kind === 'escalate'
+                ? await smartDecider(session, candidate)
+                : { nudge: det.kind === 'nudge', reason: det.reason };
+        }
         const chosenText = decision.text ?? nudgeText;
+        // Log the decision for the Factory watchdog card.
+        const summary = summarizeWatchdogTail(tailLines, candidate.agentType);
+        logEvents.push({
+            ts: nowMs,
+            kind: 'decision',
+            terminalId: session.sessionId,
+            agentType: candidate.agentType,
+            message: decision.reason,
+            reason: decision.reason,
+            stalledForMs: status.stalledForMs,
+            tailLines,
+            nudgeText: decision.nudge ? chosenText : undefined,
+            lastUserMessage: summary.lastUserMessage,
+            lastAssistantMessage: summary.lastAssistantMessage,
+        });
         if (!decision.nudge) {
             outcomes.push({ ...base, decision: 'skip', reason: decision.reason });
             continue;
         }
-        // A nudge is warranted — run it past the safety gate BEFORE any delivery.
-        const resolution = resolveInjectTargetForSession(session, {
-            allowGhosttyFocus: opts.allowGhosttyFocus,
-        });
-        if (!resolution.addressable) {
-            // Flag the un-addressable stall for the tray; NEVER guess a target.
-            flags[session.sessionId] = { reason: resolution.reason, host: session.host, atMs: nowMs };
+        // A nudge is warranted — plan delivery (answer-router picks mailbox/resume/
+        // refuse; resolveInjectTargetForSession supplies the vscodium-aware inject
+        // target) BEFORE any side effect.
+        const block = openBlockFor(session);
+        const plan = planDelivery(session, chosenText, block, opts.allowGhosttyFocus);
+        const rail = plan.via === 'inject' ? plan.rail : undefined;
+        const addressable = plan.via === 'inject' ? true : undefined;
+        if (plan.via === 'refuse') {
+            // No addressable rail and not headless-resumable — flag, NEVER guess.
+            flags[session.sessionId] = { reason: plan.reason, host: session.host, atMs: nowMs };
             outcomes.push({
                 ...base, decision: 'skip', addressable: false,
-                reason: `nudge-worthy but un-addressable — ${resolution.reason}`,
+                reason: `nudge-worthy but un-addressable — ${plan.reason}`,
                 nudgeText: chosenText,
             });
             continue;
         }
-        // handsoff = detect + flag, but never inject. Record a flag so the tray can
-        // surface "would-nudge but hands-off" alongside the un-addressable flags.
+        // handsoff = detect + flag, but never deliver.
         if (policy === 'handsoff') {
             flags[session.sessionId] = {
-                reason: `handsoff: would nudge via ${resolution.rail} but policy is hands-off`,
+                reason: `handsoff: would nudge via ${viaLabel(plan)} but policy is hands-off`,
                 host: session.host,
                 atMs: nowMs,
             };
             outcomes.push({
-                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: false,
-                reason: `handsoff: flagged, not injected (would nudge via ${resolution.rail})`,
+                ...base, decision: 'nudge', addressable, rail, via: plan.via, injected: false,
+                reason: `handsoff: flagged, not delivered (would nudge via ${viaLabel(plan)})`,
                 nudgeText: chosenText,
             });
             continue;
@@ -276,38 +401,80 @@ export async function runWatchdogTick(opts = {}) {
         // Dry status (no --nudge): report what WOULD happen, deliver nothing.
         if (!opts.nudge) {
             outcomes.push({
-                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: false,
-                reason: `would nudge via ${resolution.rail} (dry — pass --nudge to inject)`,
+                ...base, decision: 'nudge', addressable, rail, via: plan.via, injected: false,
+                reason: `would nudge via ${viaLabel(plan)} (dry — pass --nudge)`,
                 nudgeText: chosenText,
             });
             continue;
         }
-        // Deliver into the EXACT resolved split.
-        let result;
-        try {
-            result = await injectIntoTerminal(resolution.target, chosenText, { dryRun: opts.injectDryRun });
+        // Deliver. injectDryRun exercises the path without a real side effect: inject
+        // still calls injectFn (which honors dryRun), mailbox/resume are short-circuited.
+        let delivered;
+        if (plan.via === 'inject') {
+            try {
+                const r = await injectFn(plan.target, chosenText, { dryRun: opts.injectDryRun });
+                delivered = { ok: r.ok, error: r.error };
+            }
+            catch (err) {
+                delivered = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
         }
-        catch (err) {
-            result = { ok: false, backend: resolution.target.backend, writes: 0, error: err instanceof Error ? err.message : String(err) };
+        else if (plan.via === 'mailbox') {
+            if (opts.injectDryRun) {
+                delivered = { ok: true };
+            }
+            else {
+                try {
+                    deliverViaMailbox(plan.mailboxId, chosenText, block);
+                    delivered = { ok: true };
+                }
+                catch (err) {
+                    delivered = { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+            }
+        }
+        else {
+            delivered = opts.injectDryRun ? { ok: true } : await deliverViaResume(session, chosenText);
         }
-        if (result.ok) {
-            ledger[session.sessionId] = nowMs; // start the cooldown clock
+        if (delivered.ok) {
+            ledgerUpdates[session.sessionId] = nowMs; // start the cooldown clock
+            logEvents.push({
+                ts: nowMs, kind: 'nudge', terminalId: session.sessionId, agentType: candidate.agentType,
+                message: `nudged via ${viaLabel(plan)}`, reason: decision.reason, nudgeText: chosenText,
+            });
             outcomes.push({
-                ...base, decision: 'nudge', addressable: true, rail: resolution.rail, injected: true,
-                reason: `nudged via ${resolution.rail}`,
+                ...base, decision: 'nudge', addressable, rail, via: plan.via, injected: true,
+                reason: `nudged via ${viaLabel(plan)}`,
                 nudgeText: chosenText,
             });
         }
         else {
             outcomes.push({
-                ...base, decision: 'skip', addressable: true, rail: resolution.rail, injected: false,
-                reason: `inject failed via ${resolution.rail}: ${result.error ?? 'unknown error'}`,
+                ...base, decision: 'skip', addressable, rail, via: plan.via, injected: false,
+                reason: `nudge via ${viaLabel(plan)} failed: ${delivered.error ?? 'unknown error'}`,
                 nudgeText: chosenText,
             });
         }
     }
-    // Persist the tray-readable state.
-    writeJsonFile(path.join(dir, 'nudges.json'), ledger);
+    // Persist the cooldown ledger under a lock: fresh-read + merge this tick's
+    // updates + atomic write, so a concurrent tick's timestamps are never lost
+    // (the old unlocked read-at-start / write-at-end was a lost-update race).
+    if (Object.keys(ledgerUpdates).length > 0) {
+        const nudgesPath = path.join(dir, 'nudges.json');
+        const ledgerLock = path.join(dir, '.ledger.lock');
+        try {
+            ensureLockTarget(ledgerLock);
+            withFileLock(ledgerLock, () => {
+                const current = readNudgeLedger(dir);
+                for (const [sid, ts] of Object.entries(ledgerUpdates))
+                    current[sid] = ts;
+                atomicWriteFileSync(nudgesPath, JSON.stringify(current, null, 2));
+            });
+        }
+        catch {
+            /* best-effort: a lock failure must not throw out of a tick */
+        }
+    }
     writeJsonFile(path.join(dir, 'flags.json'), flags);
     const counts = {
         total: outcomes.length,
@@ -318,5 +485,13 @@ export async function runWatchdogTick(opts = {}) {
     };
     const result = { atMs: nowMs, didNudge: opts.nudge === true, outcomes, counts };
     writeJsonFile(path.join(dir, 'last-tick.json'), result);
+    // Heartbeat + decision/nudge events to the canonical watchdog.log the Factory
+    // Floor reads. Best-effort; never throws into the tick.
+    logEvents.push({
+        ts: nowMs,
+        kind: 'tick',
+        message: `${counts.total} live · ${counts.stalled} stalled · ${counts.nudged} nudged · ${counts.unaddressable} un-addressable`,
+    });
+    appendWatchdogEvents(logEvents, { logPath: opts.logPath });
     return result;
 }

package/dist/lib/watchdog/watchdog.d.ts

@@ -33,7 +33,7 @@ export interface ClassifyInput {
     dormantMs: number;
 }
 export declare function classifyTerminal(input: ClassifyInput): StallStatus;
-export declare const WATCHDOG_SYSTEM_PROMPT = "You are a watchdog monitoring AI coding agents that run in terminals.\nFor each stalled terminal below, decide: NUDGE (send a short message to unstick it) or SKIP.\n\nNudge when:\n- The last assistant turn announced an action (\"I'll write X\", \"let me run Y\")\n  but no matching tool call followed.\n- The agent appears stuck mid-task with no recent progress and the task is incomplete.\n\nSkip when:\n- The agent asked the user a direct question (waiting on human input).\n- The task looks complete.\n- You cannot tell what the agent is doing.\n\nNudge text must be:\n- One sentence, imperative (\"Show me the file.\", \"Run the tests.\").\n- No emojis. No apologies. Under 120 characters.\n\nRespond with ONLY a JSON array (no prose, no code fence):\n[{\"terminalId\":\"<id>\",\"action\":\"nudge\"|\"skip\",\"text\":\"<message or empty>\",\"reason\":\"<brief>\"}]";
+export declare const WATCHDOG_SYSTEM_PROMPT = "You are the watchdog for AI coding agents running in terminals. These agents are\nexpected to DRIVE TO COMPLETION end-to-end. They too often stop to ask a needless\nquestion or pause with the task unfinished. For each stalled terminal below, decide\nNUDGE (send a message that unsticks it and pushes it to finish) or SKIP (it genuinely\nneeds the human).\n\nNUDGE when the agent could have continued on its own:\n- It asked permission for an obvious or already-authorized next step\n  (\"should I proceed?\", \"want me to continue?\", \"shall I run the tests?\").\n- It asked a question it could answer itself from the available context or a\n  reasonable default.\n- It announced an action (\"I'll run X\", \"let me write Y\") but no tool call followed.\n- It paused with the task incomplete and no real blocker.\nThe nudge text MUST: restate the goal, tell it to use best judgment and finish\nend-to-end WITHOUT asking again, and give ONE concrete hint \u2014 the specific next\nstep, a tool it forgot, or the sensible default to take. Imperative, 1-2 sentences,\nno emojis, under 200 characters.\n\nSKIP when the agent genuinely needs the human:\n- Credentials, auth, login, 2FA, or biometric.\n- An irreversible or outward-facing action that needs sign-off (force-push, delete\n  prod data, publish/release, spend money, send an external message).\n- A real product or intent decision with genuine ambiguity (not a trivial default).\n- The task is actually complete.\n- You cannot tell what the agent is doing.\n\nRespond with ONLY a JSON array (no prose, no code fence):\n[{\"terminalId\":\"<id>\",\"action\":\"nudge\"|\"skip\",\"text\":\"<message or empty>\",\"reason\":\"<brief>\"}]";
 export declare function composePromptWithPlaybook(basePrompt: string, playbook: string): string;
 export declare function renderWatchdogPrompt(candidates: WatchdogCandidate[], playbook?: string): string;
 export declare function parseWatchdogResponse(stdout: string): Decision[];

package/dist/lib/watchdog/watchdog.js

@@ -64,23 +64,32 @@ export function classifyTerminal(input) {
     }
     return { kind: 'stalled', stalledForMs: age };
 }
-export const WATCHDOG_SYSTEM_PROMPT = `You are a watchdog monitoring AI coding agents that run in terminals.
-For each stalled terminal below, decide: NUDGE (send a short message to unstick it) or SKIP.
+export const WATCHDOG_SYSTEM_PROMPT = `You are the watchdog for AI coding agents running in terminals. These agents are
+expected to DRIVE TO COMPLETION end-to-end. They too often stop to ask a needless
+question or pause with the task unfinished. For each stalled terminal below, decide
+NUDGE (send a message that unsticks it and pushes it to finish) or SKIP (it genuinely
+needs the human).
 
-Nudge when:
-- The last assistant turn announced an action ("I'll write X", "let me run Y")
-  but no matching tool call followed.
-- The agent appears stuck mid-task with no recent progress and the task is incomplete.
+NUDGE when the agent could have continued on its own:
+- It asked permission for an obvious or already-authorized next step
+  ("should I proceed?", "want me to continue?", "shall I run the tests?").
+- It asked a question it could answer itself from the available context or a
+  reasonable default.
+- It announced an action ("I'll run X", "let me write Y") but no tool call followed.
+- It paused with the task incomplete and no real blocker.
+The nudge text MUST: restate the goal, tell it to use best judgment and finish
+end-to-end WITHOUT asking again, and give ONE concrete hint — the specific next
+step, a tool it forgot, or the sensible default to take. Imperative, 1-2 sentences,
+no emojis, under 200 characters.
 
-Skip when:
-- The agent asked the user a direct question (waiting on human input).
-- The task looks complete.
+SKIP when the agent genuinely needs the human:
+- Credentials, auth, login, 2FA, or biometric.
+- An irreversible or outward-facing action that needs sign-off (force-push, delete
+  prod data, publish/release, spend money, send an external message).
+- A real product or intent decision with genuine ambiguity (not a trivial default).
+- The task is actually complete.
 - You cannot tell what the agent is doing.
 
-Nudge text must be:
-- One sentence, imperative ("Show me the file.", "Run the tests.").
-- No emojis. No apologies. Under 120 characters.
-
 Respond with ONLY a JSON array (no prose, no code fence):
 [{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>"}]`;
 // User-editable playbook appended below the built-in prompt. The user maintains
@@ -137,15 +146,21 @@ export function parseWatchdogResponse(stdout) {
     return decisions;
 }
 export function isLikelyTrulyBlocked(candidate) {
-    if (candidate.stalledForMs >= FORCE_REVIEW_STALL_MS)
-        return true;
+    // With no tail to reason over, only a very long stall counts as blocked.
     if (candidate.tailLines.length === 0)
-        return false;
+        return candidate.stalledForMs >= FORCE_REVIEW_STALL_MS;
     const lowerTail = candidate.tailLines.join('\n').toLowerCase();
+    // Waiting-on-user and completion hints are checked BEFORE the 15m force-review
+    // short-circuit — a long-idle OPEN QUESTION must defer (not be blindly
+    // force-nudged) and a finished task is done. The old order tested stall age
+    // first, so a 15m-60m idle session whose tail said "waiting on user" / "done"
+    // was force-nudged anyway. Precedence fixed here (watchdog-brain-v2).
     if (WAITING_HINTS.some((hint) => lowerTail.includes(hint)))
         return false;
     if (COMPLETION_HINTS.some((hint) => lowerTail.includes(hint)))
         return false;
+    if (candidate.stalledForMs >= FORCE_REVIEW_STALL_MS)
+        return true;
     if (BLOCKED_HINTS.some((hint) => lowerTail.includes(hint)))
         return true;
     let sawToolAfter = false;

package/dist/lib/workflows.d.ts

@@ -296,6 +296,22 @@ export declare function transformWorkflowForKimi(workflowPath: string, name: str
 export declare function transformWorkflowForAntigravity(workflowPath: string, name: string): string;
 /** Convert a canonical agents-cli workflow bundle into an OpenClaw Lobster file. */
 export declare function transformWorkflowForOpenClaw(workflowPath: string, name: string): string;
+/** Marker comment prefix written into agents-cli-managed Grok `.rhai` files. */
+export declare const GROK_WORKFLOW_MARKER = "agents_workflow";
+/**
+ * Convert a canonical agents-cli workflow bundle into a Grok native Rhai
+ * workflow script. Grok discovers saved workflows as
+ * `~/.grok/workflows/<name>.rhai` (and project `.grok/workflows/`) and exposes
+ * each as a `/<name>` slash command (enabled by default since v0.2.111).
+ *
+ * The projection is a single-agent orchestrator that feeds the WORKFLOW.md
+ * body as the agent prompt plus the caller's `args.prompt` (or string args).
+ * Multi-phase fan-out is left to hand-authored Rhai — agents-cli's job is to
+ * land the orchestrator instructions in the native path.
+ */
+export declare function transformWorkflowForGrok(workflowPath: string, name: string): string;
+/** Read the agents_workflow marker from a Grok `.rhai` file, if present. */
+export declare function grokWorkflowMarker(filePath: string): string | null;
 /**
  * Resolve an `agents run <workflow>` reference.
  *