@deftai/directive-content 0.86.0 → 0.88.0

package/strategies/probe.md

@@ -104,7 +104,7 @@ feature/component name if probing a sub-scope. Use the same value consistently
 throughout the session. Examples: `my-app-probe`, `auth-probe`.
 
 - ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:
-  - `LockedDecisions` — what was resolved and why
+  - `LockedDecisions` — what was resolved and why (when the lock is an intentional under-build, include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, `status` — see [Graduation (Now+Later)](#graduation-nowlater-when-locking-an-under-build-2899))
   - `SurfacedRisks` — concerns raised, even if not fully resolved
   - `DeferredDecisions` — explicitly acknowledged items with justification
 - ! Each entry in a narrative includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
@@ -114,6 +114,30 @@ throughout the session. Examples: `my-app-probe`, `auth-probe`.
 
 ! After emitting the probe scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
 
+## Graduation (Now+Later) when locking an under-build (#2899)
+
+Probe already separates **locked**, **deferred**, and **risk-accepted** branches. **Graduation** is a fourth case that must not collapse into `DeferredDecisions`:
+
+| Concept | Probe role |
+|---|---|
+| `LockedDecisions` (permanent) | Approach is decided and is the end-product path |
+| `DeferredDecisions` | *Undecided* open question with justification |
+| **Graduation** on a lock | *Decided* weaker **Now** + *decided* end-product **Later** |
+| rapid **graduate** | Strategy-level spike → fresh spec; not dual-path tracking here |
+
+Glossary naming for Graduation is owned by sibling work (#2907); this section is the Wave A probe contract.
+
+- ! When probe **locks** a temporary / weaker approach and the end-product approach is also decided, record the dual-path shape on that `LockedDecisions` entry (not as a `DeferredDecisions` open question):
+  - `now` — what ships in the near path
+  - `later` — end-product approach
+  - `graduationRef` — GitHub issue and/or scope xBRIEF path for Later work
+  - `trigger` — condition that makes Later required (free text)
+  - `status` — `open` | `shipped` | `cancelled` (cancel with justification)
+- ! Permanent locks and true open questions do **not** gain graduation fields — do not ticket-spam every `DeferredDecisions` item into a graduation
+- ! `task scope:complete` on a Now story MUST NOT close linked graduation work; Later stays open until shipped or explicitly cancelled
+- ⊗ Accepting "we'll harden it later" as a locked under-build without dual-path fields, or filing it only as `DeferredDecisions`
+- ⊗ Closing graduation work solely because the MVP / Now story completed
+
 ---
 
 ## Then: Chaining Gate
@@ -143,6 +167,8 @@ written, return to the [chaining gate](./interview.md#chaining-gate).
 ## Anti-Patterns
 
 - ⊗ Accepting "we'll figure it out later" without marking it as explicitly deferred
+- ⊗ Recording a *decided* weaker-Now + stronger-Later path only as `DeferredDecisions` (or chat) instead of dual-path graduation fields on the lock (#2899)
+- ⊗ Treating Now-story `scope:complete` as closure of linked graduation work (#2899)
 - ⊗ Asking generic checklist questions instead of following the decision tree
 - ⊗ Letting vague answers pass without pushing for concrete specifics
 - ⊗ Using codebase exploration as a substitute for asking the user about deliberate design choices

package/tasks/engine-invoke.cjs

@@ -12,6 +12,29 @@
 
 const { spawnSync } = require("node:child_process");
 
+/**
+ * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
+ * tokens (release --summary text, CLI_ARGS, #2547) may legitimately contain
+ * these; double-quoting renders them literal to cmd.exe's parser so a token can
+ * never break out of its argv slot (subprocess-scm-01 / #2911).
+ */
+const WIN32_CMD_METACHAR_RE = /[\s"&|<>^()%!]/;
+
+/**
+ * Quote a single argument for `cmd.exe /d /s /c` so that shell metacharacters
+ * stay inside one argv token. Mirrors tasks/engine-pm-run.cjs quoteWin32Arg but
+ * also quotes cmd.exe separators (& | < > ^ ( ) % !) because engine-invoke
+ * forwards operator free-text, not an allowlisted command.
+ * @param {string} arg
+ */
+function quoteWin32Arg(arg) {
+  const s = String(arg);
+  if (s.length > 0 && !WIN32_CMD_METACHAR_RE.test(s)) {
+    return s;
+  }
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
 /** Minimal POSIX-ish shell word splitter (double/single quotes, escapes). */
 function shellSplit(input) {
   const out = [];
@@ -75,15 +98,8 @@ function main() {
     process.exit(2);
   }
 
-  let execPath;
-  let execArgv;
-  if (mode === "vendored") {
-    execPath = process.execPath;
-    execArgv = [target, ...argv];
-  } else if (mode === "global") {
-    execPath = target;
-    execArgv = argv;
-  } else {
+  const plan = buildSpawnPlan(mode, target, argv);
+  if (!plan) {
     console.error(`deft: engine-invoke unknown mode ${JSON.stringify(mode)}`);
     process.exit(2);
   }
@@ -97,11 +113,12 @@ function main() {
   // stdio inherit (not pipe): piped stdout/stderr deadlocks when the child emits
   // more than the OS pipe buffer before exit — observed as greenfield smoke
   // hanging then CI SIGTERM exit 143 with no output (#2554 / #2547).
-  const result = spawnSync(execPath, execArgv, {
+  const result = spawnSync(plan.command, plan.args, {
     stdio: "inherit",
     env: childEnv,
-    // Global deft/directive on Windows are .cmd shims; shell:false cannot spawn them (#2415).
-    shell: mode === "global" && process.platform === "win32",
+    // Never shell:true — even on win32 global (subprocess-scm-01 / #2911). The
+    // win32 .cmd shim is reached through a tightly quoted cmd.exe wrapper below.
+    shell: plan.shell,
     // CREATE_NO_WINDOW: hide console windows from Cursor Task / nested shells (#2563).
     windowsHide: true,
   });
@@ -109,8 +126,47 @@ function main() {
   process.exit(code === null ? 1 : code);
 }
 
+/**
+ * Resolve the concrete spawn command/args for a mode+target without ever using
+ * shell:true. On the win32 global path the target is a `.cmd` shim that Node
+ * refuses to spawn with shell:false (CVE-2024-27980 / #2415); shell:true would
+ * let cmd.exe re-parse free-text DEFT_ENGINE_CMD_JSON tokens (subprocess-scm-01
+ * / #2911). Instead route through `cmd.exe /d /s /c` with every token tightly
+ * quoted so metacharacters stay inside a single argv token — aligned with
+ * tasks/engine-pm-run.cjs executeAllowlisted().
+ *
+ * @param {string} mode
+ * @param {string} target
+ * @param {string[]} argv
+ * @param {{ platform?: string, nodePath?: string }} [opts]
+ * @returns {{ command: string, args: string[], shell: false } | null}
+ */
+function buildSpawnPlan(mode, target, argv, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const nodePath = opts.nodePath || process.execPath;
+
+  let execPath;
+  let execArgv;
+  if (mode === "vendored") {
+    execPath = nodePath;
+    execArgv = [target, ...argv];
+  } else if (mode === "global") {
+    execPath = target;
+    execArgv = argv;
+  } else {
+    return null;
+  }
+
+  if (mode === "global" && platform === "win32") {
+    const commandLine = [execPath, ...execArgv].map(quoteWin32Arg).join(" ");
+    return { command: "cmd.exe", args: ["/d", "/s", "/c", commandLine], shell: false };
+  }
+
+  return { command: execPath, args: execArgv, shell: false };
+}
+
 if (require.main === module) {
   main();
 }
 
-module.exports = { shellSplit };
+module.exports = { shellSplit, quoteWin32Arg, buildSpawnPlan, WIN32_CMD_METACHAR_RE };

package/tasks/engine-invoke.test.cjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const { describe, it } = require("node:test");
+const {
+  shellSplit,
+  quoteWin32Arg,
+  buildSpawnPlan,
+  WIN32_CMD_METACHAR_RE,
+} = require("./engine-invoke.cjs");
+
+const WIN32 = { platform: "win32", nodePath: "/node" };
+const POSIX = { platform: "linux", nodePath: "/node" };
+
+/**
+ * Split a `cmd.exe`-quoted command line into top-level tokens, honouring
+ * double-quote grouping and the `""` escaped-quote convention. Used to assert
+ * that a metacharacter-bearing arg survives as exactly one argv token and is
+ * never seen by cmd.exe as a command separator.
+ * @param {string} line
+ */
+function splitCmdTokens(line) {
+  const tokens = [];
+  let cur = "";
+  let inQuote = false;
+  let started = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (inQuote) {
+      if (c === '"') {
+        if (line[i + 1] === '"') {
+          cur += '"';
+          i++;
+          continue;
+        }
+        inQuote = false;
+        continue;
+      }
+      cur += c;
+      continue;
+    }
+    if (c === '"') {
+      inQuote = true;
+      started = true;
+      continue;
+    }
+    if (c === " ") {
+      if (started) {
+        tokens.push(cur);
+        cur = "";
+        started = false;
+      }
+      continue;
+    }
+    started = true;
+    cur += c;
+  }
+  if (started) {
+    tokens.push(cur);
+  }
+  return tokens;
+}
+
+describe("shellSplit", () => {
+  it("keeps quoted free-text (apostrophes, spaces, metachars) as one token", () => {
+    assert.deepEqual(shellSplit(`release --summary "It's a & test"`), [
+      "release",
+      "--summary",
+      "It's a & test",
+    ]);
+  });
+});
+
+describe("quoteWin32Arg", () => {
+  it("passes safe tokens through unquoted", () => {
+    assert.equal(quoteWin32Arg("release"), "release");
+    assert.equal(quoteWin32Arg("--summary=fixed"), "--summary=fixed");
+  });
+
+  it("double-quotes whitespace, quotes, and cmd.exe metacharacters", () => {
+    assert.equal(quoteWin32Arg("a b"), '"a b"');
+    assert.equal(quoteWin32Arg("a&b"), '"a&b"');
+    assert.equal(quoteWin32Arg("a|b"), '"a|b"');
+    assert.equal(quoteWin32Arg("a>b"), '"a>b"');
+    assert.equal(quoteWin32Arg("a<b"), '"a<b"');
+    assert.equal(quoteWin32Arg("(a)"), '"(a)"');
+    assert.equal(quoteWin32Arg("%PATH%"), '"%PATH%"');
+    assert.equal(quoteWin32Arg("a^b"), '"a^b"');
+    assert.equal(quoteWin32Arg("a!b"), '"a!b"');
+  });
+
+  it("escapes embedded double quotes by doubling", () => {
+    assert.equal(quoteWin32Arg('a"b'), '"a""b"');
+  });
+
+  it("regex flags every cmd.exe separator", () => {
+    for (const meta of [" ", '"', "&", "|", "<", ">", "^", "(", ")", "%", "!"]) {
+      assert.ok(WIN32_CMD_METACHAR_RE.test(`x${meta}y`), meta);
+    }
+  });
+});
+
+describe("buildSpawnPlan — win32 global (subprocess-scm-01 / #2911)", () => {
+  it("never uses shell:true and routes through cmd.exe /d /s /c", () => {
+    const plan = buildSpawnPlan("global", "deft", ["release"], WIN32);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "cmd.exe");
+    assert.deepEqual(plan.args.slice(0, 3), ["/d", "/s", "/c"]);
+    assert.equal(plan.args[3], "deft release");
+  });
+
+  it("keeps injection-shaped free-text args as a single quoted token", () => {
+    const injections = [
+      "& calc.exe",
+      "&calc",
+      "| whoami",
+      "&& shutdown /s",
+      "; rm -rf /",
+      "$(reboot)",
+      "`reboot`",
+      "> C:\\pwn.txt",
+      "< C:\\secret",
+      "(malicious)",
+      "%USERPROFILE%",
+      "^escaped",
+      "!DELAYED!",
+    ];
+    for (const evil of injections) {
+      const plan = buildSpawnPlan("global", "deft", ["release", "--summary", evil], WIN32);
+      assert.equal(plan.shell, false, evil);
+      const commandLine = plan.args[3];
+      const tokens = splitCmdTokens(commandLine);
+      // deft + release + --summary + evil == 4 top-level tokens, evil intact.
+      assert.deepEqual(tokens, ["deft", "release", "--summary", evil], `injection ${evil}`);
+      // Any cmd.exe metacharacter must be neutralised inside a quoted span so it
+      // can never act as a bare command separator (POSIX-only chars like the
+      // backtick are literal to cmd.exe and need no quoting).
+      if (WIN32_CMD_METACHAR_RE.test(evil)) {
+        assert.ok(commandLine.includes(`"${evil.replace(/"/g, '""')}"`), `quoted ${evil}`);
+      }
+    }
+  });
+
+  it("routes end-to-end from a quoted DEFT_ENGINE_CMD string", () => {
+    const argv = shellSplit('release --summary "pwn & calc | whoami"');
+    const plan = buildSpawnPlan("global", "directive", argv, WIN32);
+    assert.equal(plan.shell, false);
+    assert.deepEqual(splitCmdTokens(plan.args[3]), [
+      "directive",
+      "release",
+      "--summary",
+      "pwn & calc | whoami",
+    ]);
+  });
+
+  it("leaves safe args unquoted for readability", () => {
+    const plan = buildSpawnPlan("global", "deft", ["session:start", "--json"], WIN32);
+    assert.equal(plan.args[3], "deft session:start --json");
+  });
+});
+
+describe("buildSpawnPlan — other paths keep shell:false", () => {
+  it("win32 vendored spawns node directly (no cmd.exe, no shell)", () => {
+    const plan = buildSpawnPlan("vendored", "/bin.js", ["release", "a&b"], WIN32);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "/node");
+    assert.deepEqual(plan.args, ["/bin.js", "release", "a&b"]);
+  });
+
+  it("posix global spawns the shim directly with shell:false", () => {
+    const plan = buildSpawnPlan("global", "deft", ["release", "a&b"], POSIX);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "deft");
+    assert.deepEqual(plan.args, ["release", "a&b"]);
+  });
+
+  it("posix vendored spawns node with shell:false", () => {
+    const plan = buildSpawnPlan("vendored", "/bin.js", ["release"], POSIX);
+    assert.equal(plan.shell, false);
+    assert.equal(plan.command, "/node");
+    assert.deepEqual(plan.args, ["/bin.js", "release"]);
+  });
+
+  it("returns null for unknown modes (caller exits 2)", () => {
+    assert.equal(buildSpawnPlan("bogus", "deft", ["release"], WIN32), null);
+  });
+});

package/tasks/triage-queue.yml

@@ -36,7 +36,7 @@ tasks:
           ENGINE_CMD: 'triage-queue queue --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   show:
-    desc: "Per-issue triage detail (#1128 / D11). -- task triage:show -- <N> [--repo OWNER/NAME]"
+    desc: "Per-issue triage detail (#1128 / D11, #2890). -- task triage:show -- <N> [--format=default|operator] [--repo OWNER/NAME]"
     internal: true
     deps: [":engine:_ts-build"]
     dir: '{{.USER_WORKING_DIR}}'

package/tasks/verify.yml

@@ -59,6 +59,13 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-content-manifest --project-root "{{.DEFT_ROOT}}"'
 
+  license-sync:
+    desc: "Drift guard for root LICENSE ↔ content/LICENSE.md and published package.json license fields (#2902). Three-state exit (0 clean / 1 drift / 2 config). Framework-source only."
+    # Framework-source-only gate: reads THIS repo's LICENSE + package manifests.
+    # Plain node script (no engine build required).
+    cmds:
+      - node "{{.DEFT_ROOT}}/scripts/verify-license-sync.mjs" --project-root "{{.DEFT_ROOT}}"
+
   skill-external-fetch-gate:
     desc: "Verify shipped skills do not pair external fetch/follow-through with execute/install without Security context mitigation (#1936 / #1532)."
     deps:
@@ -91,6 +98,18 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-cursor-tier1 --project-root "{{.DEFT_ROOT}}"'
 
+  openclaw-tier1:
+    desc: "Framework-source content gate (#2875): assert OpenClaw (openclaw descriptor, sessions_spawn primitive) is enumerated as Tier 1 in the swarm Phase 3 capability matrix AND routing accepts openclaw as a dispatch_provider. Fails when a doc/code edit drops the OpenClaw descriptor and silently re-opens grok-build / generic-terminal misclassification. Three-state exit (0 clean / 1 missing marker / 2 config error)."
+    deps:
+      - task: :engine:_ts-build
+    # Framework-source-only gate: it scans THIS repo's swarm skill + routing
+    # module, so it targets DEFT_ROOT (not USER_WORKING_DIR). Mirrors
+    # verify:cursor-tier1 / verify:content-manifest.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-openclaw-tier1 --project-root "{{.DEFT_ROOT}}"'
+
   go-freeze:
     desc: "Tier-1 freeze gate for the legacy Go-installer bridge (#1912). Advisory while the Tier-0 SoT (lastGoInstaller) is null; once the operator pins it, fails when cmd/deft-install is bumped above the frozen tag. Three-state exit (0 ok / 1 violation / 2 config error). Emergency bypass: DEFT_ALLOW_GO_INSTALLER_BUMP=1."
     deps:

package/templates/agent-prompt-preamble.md

@@ -73,15 +73,15 @@ When the operator supplies an ordered plan (delivery sequence, cohort, checklist
 
 ## 2.6 Provider-neutral worker metadata (#1531)
 
-Heterogeneous swarm dispatch (#1531) assigns each worker a **dispatch provider** (the runtime primitive that launched the agent), a **worker role** (what the agent is allowed to do), and a **selected backend** or **routing policy** (how the harness maps that role to a concrete agent). These fields are provider-neutral: Composer-class coding agents, Grok Build (`spawn_subagent`), Cursor/cloud agents, and future adapters share the same contract.
+Heterogeneous swarm dispatch (#1531) assigns each worker a **dispatch provider** (the runtime primitive that launched the agent), a **worker role** (what the agent is allowed to do), and a **selected backend** or **routing policy** (how the harness maps that role to a concrete agent). These fields are provider-neutral: Composer-class coding agents, Grok Build (`spawn_subagent`), Cursor/cloud agents, OpenClaw (`sessions_spawn`, #2874 / #2879), and future adapters share the same contract.
 
 ! Every intentional backend-routed dispatch MUST carry a separate `## Worker metadata` section in the dispatch envelope, placed AFTER `## Allocation context` and BEFORE the task body. This section is advisory metadata for the worker and for audit; it does NOT replace, extend, or reorder the five-field #1378 `## Allocation context` recognition contract above.
 
 When present, the section documents these fields in order:
 
-- `dispatch_provider`: the runtime primitive that launched this worker -- e.g. `spawn_subagent`, `start_agent`, `cursor-composer`, `cursor-cloud-agent`, or a future adapter id. Names the harness surface, not the model.
+- `dispatch_provider`: the runtime primitive that launched this worker -- e.g. `spawn_subagent`, `start_agent`, `sessions_spawn` (OpenClaw host; platform descriptor `openclaw` per #2874 / #2875), `cursor-composer`, `cursor-cloud-agent`, or a future adapter id. Names the harness surface, not the model.
 - `worker_role`: the role boundary for this dispatch -- one of `leaf-implementation`, `orchestrator`, `review-monitor`, or `merge-release` (stable ids from `packages/core/src/swarm/routing.ts` `SWARM_WORKER_ROLES`). Tells the worker which preamble rules and skill surfaces apply.
-- `selected_backend`: the stable backend id from `plan.policy.swarmSubagentBackend` / `task policy:subagent-backends` (e.g. `composer`, `grok-build`, `cursor-cloud`) | null -- which catalogued coding backend the operator selected for this role.
+- `selected_backend`: the stable backend id from `plan.policy.swarmSubagentBackend` / `task policy:subagent-backends` (accepted set today: `composer`, `grok-build`, `cursor-cloud` only — see `KNOWN_SUBAGENT_BACKEND_IDS`) | null -- which catalogued **coding** backend the operator selected for this role. OpenClaw is a **host / dispatch_provider** (`sessions_spawn` / descriptor `openclaw`), not a `swarmSubagentBackend` enum value; do not write `selected_backend: openclaw` into policy (#2879 Greptile P1).
 - `routing_policy`: <path or reference to the operator's routing file / tiering policy> | null -- when backend selection is delegated to harness routing instead of a typed policy field, cite the policy handle here so postmortems can reconstruct the route. The canonical handle is the gitignored, per-machine `.deft/routing.local.json` (#1739), keyed by `(dispatch_provider, worker_role)`; set decisions with `task swarm:routing-set -- --role <role> (--model <slug> | --harness-default)`.
 - `resolved_model` (#1739): the concrete model slug the operator pinned for this `(provider, role)` | null for an explicit harness default. Resolved from `.deft/routing.local.json` and stamped into the `task swarm:launch` manifest. **This is the field the dispatch primitive must actually honor** -- see the threading rule below.
 - `model_source` (#1739): provenance of `resolved_model` -- e.g. `cursor-route`, `harness-default explicit`. Lets a postmortem tell a pinned model from a harness default.
@@ -94,7 +94,7 @@ Populate `selected_backend` OR `routing_policy` (or both when the operator sets
 - `orchestrator`, `review-monitor`, or `merge-release` + explicit backend routing: at least one MUST be non-null so strong-tier audit traces stay reconstructable.
 - Any role on the harness-default agent with no tiering decision: both MAY be null; `dispatch_provider` and `worker_role` remain required.
 
-**Role-boundary expectations (all providers):** the same boundaries apply whether the worker runs on Composer, Grok Build, Cursor/cloud, or a future adapter:
+**Role-boundary expectations (all providers):** the same boundaries apply whether the worker runs on Composer, Grok Build, Cursor/cloud, OpenClaw, or a future adapter:
 
 - ! `leaf-implementation` workers implement scoped xBRIEF work in their assigned worktree only -- gates (`task check`, file-scope audit, Greptile review cycle) are model-agnostic and MUST still pass.
 - ! `orchestrator`, `review-monitor`, and `merge-release` roles MUST run on strong or review-capable agents; dispatchers MUST NOT route these roles to cheap leaf backends.
@@ -460,6 +460,7 @@ These rules bind **orchestrators** dispatching implementation, fix, or review-cy
 
 - ! Long-running workers (expected >~3 min: implementation, fix batches, review-cycle owners, pollers) MUST be dispatched independently / in the background so the parent conversation channel stays interactive and the orchestrator is notified on completion (`DONE` / `BLOCKED` / `FAILED` per §11).
 - ! On Cursor, background dispatch means the Task tool's background path (`run_in_background: true` on the Task invocation) — NOT blocking the orchestrator's turn for the worker's full wall-clock.
+- ! On OpenClaw, background dispatch means `sessions_spawn` (optionally with `visible` so the Control UI can watch the subagent) so the parent session stays interactive; the completion channel is **parent push / announce**, not `get_command_or_subagent_output` and not Cursor Task completion (#2874 / #2879). Nested leaf-spawn-leaf limits mirror Cursor #2797 when the platform does not support reliable nested `sessions_spawn`.
 - ⊗ Foreground/blocking dispatch for long-running implementation, fix, or review-cycle workers when a background/independent dispatch primitive is available — blocking locks the conversation and prevents user steerability (#1878 / Gap D).
 - ~ Foreground dispatch is reserved for short tasks (<~3 min): quick probes, single-command checks, terse status reads.
 
@@ -490,7 +491,7 @@ Reference: scope-expansion comment 4399553752 on issue #954.
 
 ## 10.5 Heartbeat contract (#1365)
 
-Long-running `spawn_subagent` review-cycle agents on the Grok Build hybrid swarm path can go completely dark from the monitor's perspective -- no commits, no PR comments, no completion notifications. The #1166 swarm session demonstrated the failure mode: two of three dispatched pollers produced zero observable signals; the monitor could not distinguish stalled from healthy.
+Long-running `spawn_subagent` review-cycle agents on the Grok Build hybrid swarm path can go completely dark from the monitor's perspective -- no commits, no PR comments, no completion notifications. The same visibility gap applies to OpenClaw `sessions_spawn` and Cursor `Task` pollers. The #1166 swarm session demonstrated the failure mode: two of three dispatched pollers produced zero observable signals; the monitor could not distinguish stalled from healthy.
 
 The heartbeat contract closes that gap. Any sub-agent whose tool loop is expected to run for more than ~3 minutes (review-cycle pollers, watchdogs, long-running implementation agents) MUST emit a small JSON heartbeat at `<project-root>/.deft-scratch/subagent-status/<agent-id>.json` per `docs/subagent-heartbeat.md`.
 
@@ -506,6 +507,10 @@ The parent monitor watches the heartbeat file directly (three-state exit 0 ok /
 
 ! **Cursor false-alive / REDISPATCH_OK (#2824):** On the Cursor `Task` path, the host may report a leaf as "still running" after it has gone silent (empty transcript, no heartbeats, no DONE/FAILED). When `task verify:subagent-alive` exits `1` for a registered in-flight `drive-to: merge*` worker — missing heartbeat, STALE heartbeat, or no recent git/PR activity — the monitor MUST treat the worker as dead and print `REDISPATCH_OK` to authorize takeover re-dispatch. Do NOT block on host resume when the liveness gate has failed closed.
 
+! **OpenClaw `sessions_spawn` / heartbeat mapping (#2879):** Same file-heartbeat contract applies to OpenClaw review-monitors and long-running leaves. OpenClaw host session liveness, Control UI presence, or gateway channel reachability does NOT replace periodic heartbeats — those signals only prove the session exists, not that the tool loop is progressing. OpenClaw pollers write `.deft-scratch/subagent-status/<agent-id>.json` so `task agent:monitor` / `task verify:subagent-alive` can detect stalled monitors; OpenClaw-native session status MAY be a *supplementary* signal only. Host "still running" + missing/STALE heartbeat authorizes the same `REDISPATCH_OK` posture as Cursor #2824.
+
+! **Parent ensures scratch dir + startup grace before REDISPATCH_OK (#2879):** `task verify:subagent-alive` exits `2` (config error, no `REDISPATCH_OK`) when the scratch directory is **missing** and has no records. Parents MUST `mkdir` the worker worktree's `.deft-scratch/subagent-status/` at dispatch time so a later missing record is exit `1` + `REDISPATCH_OK`. Parents MUST ALSO wait a **startup grace** (default 3 minutes from dispatch, or until the first `phase: "starting"` heartbeat is observed) before treating a missing required-agent as takeover-eligible — probing an empty parent-created dir immediately races a healthy worker still writing its first heartbeat and can spawn a duplicate. Exit `2` remains reserved for true config errors (bad args / wrong path).
+
 - Monitors run `task verify:subagent-alive -- --require-agent <agent-id> [--scratch-dir <worktree>/.deft-scratch/subagent-status]` each poll iteration.
 - Workers run `task agent:monitor` (raw sweep) or the gate verb above; both wrap `subagent-monitor` (#1365).
 
@@ -524,6 +529,12 @@ Every worker MUST send a final status message before exiting its tool loop, rega
 
 ⊗ Emit `DONE` from a `drive-to: merge-ready` worker while merge-ready is false — a false-terminal `DONE` pulls the cohort monitor into inline Greptile fixes and violates Gap D (#2843 monitor-as-implementer recurrence).
 
+! **Thin DONE is not success (#2943):** A terminal message that lacks PR URL / merge evidence (no `PR #N`, no PR URL, no merge confirmation) is a **thin DONE** / failed-leaf signal for the parent monitor — re-dispatch or take over after ground truth. Prefer structured completion fields when the host supplies them (`prUrl`, `mergeStatus`, `emptyDiff`). Workers MUST NOT exit with mid-edit prose and call it `DONE` when the envelope required a PR or merge-ready outcome.
+
+! **Parent tool-first after leaf completion (#2943):** When a parent / monitor receives a leaf completion event (`subagent_announce`, parent-push, or host completion notify), its **first response** MUST be a **tool-first** ground-truth batch (`gh` / `git` / worktree or file status) **or** a host **yield** (`sessions_yield` on OpenClaw, or equivalent). ⊗ Multi-sentence progress-only first response with zero tools / yield — the OpenClaw text-repetition hang class (#2943).
+
+⊗ Treat thin DONE (no PR URL / merge evidence) as success (#2943).
+
 Per-step acks during the run are noise. ONE start message, ONE final message; intermediate messages only on `BLOCKED` / `FAILED`. The final message lets the dispatcher distinguish a clean exit from a silent timeout when the lifecycle event arrives.
 
 ## 12. Session ritual + `task verify:cache-fresh` gates before `start_agent` (#1348 / #1127)

package/templates/swarm-greptile-poller-prompt.md

@@ -6,13 +6,14 @@ Canonical Greptile review-cycle / poller sub-agent prompt body.
 Used by parent monitor agents when delegating post-PR work via the platform
 dispatch primitive per the parent's Phase 3 runtime capability detection
 (`spawn_subagent` for "grok-build" / Grok Build TUI, `start_agent` for
-Warp-orchestrated, or equivalent in other environments). See
-`skills/deft-directive-swarm/SKILL.md` Phase 3 + #1342 slices 1-3 and the
-review-cycle skill's updated Approach 1.
+Warp-orchestrated, `sessions_spawn` for OpenClaw, Cursor `Task` with
+`run_in_background: true`, or equivalent in other environments). See
+`skills/deft-directive-swarm/SKILL.md` Phase 3 + #1342 slices 1-3 / #2874
+OpenClaw Tier 1 and the review-cycle skill's updated Approach 1.
 
 The parent reads this file and applies Python `str.format(...)` to substitute
 five placeholders, then passes the formatted prompt via the chosen dispatch
-primitive (spawn_subagent, start_agent, etc.):
+primitive (spawn_subagent, start_agent, sessions_spawn, Cursor Task, etc.):
 
     from pathlib import Path
     prompt = Path("templates/swarm-greptile-poller-prompt.md").read_text(encoding="utf-8").format(
@@ -23,7 +24,9 @@ primitive (spawn_subagent, start_agent, etc.):
         parent_agent_id="<parent-id>",
     )
     # Dispatch via the detected primitive (example for start_agent shown;
-    # use spawn_subagent + the launch adapter for grok-build per #1342)
+    # use spawn_subagent + the launch adapter for grok-build per #1342;
+    # use sessions_spawn for OpenClaw per #2874 / #2879 -- completion is
+    # parent push / announce, not get_command_or_subagent_output)
     start_agent(name=f"greptile-poller-{{N}}", prompt=prompt, execution_mode="local")
 
 This file is the proven prompt body. Hand-authored variants have repeatedly
@@ -31,10 +34,11 @@ missed two specific parsing bugs (markdown-link `Last reviewed commit:`,
 raw `\b(P0|P1)\b` substring scan with negation false-positive); the body
 below encodes the fixes inline. See #727 (canonical encoding) and
 `skills/deft-directive-swarm/SKILL.md` Phase 6 Sub-Agent Role Separation
-(#1342 platform adapter unification: the platform adapter dispatches via
-`spawn_subagent` on grok-build and `start_agent` on Warp-orchestrated, so
-this template is platform-agnostic by construction) for the rules that
-mandate using this template instead of hand-authoring.
+(#1342 / #2879 platform adapter unification: the platform adapter dispatches
+via `spawn_subagent` on grok-build, `start_agent` on Warp-orchestrated, and
+`sessions_spawn` on OpenClaw, so this template is platform-agnostic by
+construction) for the rules that mandate using this template instead of
+hand-authoring.
 
 NOTE on `.format()` escaping: every literal curly brace in this file is
 doubled (`{{` / `}}`) so it survives the `str.format(...)` pass. The five
@@ -48,8 +52,12 @@ DO NOT STOP until ONE of the six terminal exit conditions below fires.
 ## Role posture
 
 - Single role: review-cycle agent. Read `skills/deft-directive-review-cycle/SKILL.md` and follow Phase 2 (Review/Fix Loop) end-to-end.
-- Parent agent ID for status messages: `{parent_agent_id}`. Send status updates via `send_message_to_agent` at start, on each terminal exit condition, and on any blocker.
-- Execution: local. Working directory: the worktree the parent gave you (or your `--cwd` if running under `oz agent run --cwd`).
+- Parent agent ID for status messages: `{parent_agent_id}`. Send status updates at start, on each terminal exit condition, and on any blocker via the **host completion channel** for your dispatch primitive:
+  - Warp / `start_agent`: `send_message_to_agent`
+  - grok-build / `spawn_subagent`: spawn result channel / parent announce (parent may poll `get_command_or_subagent_output`)
+  - **OpenClaw / `sessions_spawn` (#2879):** parent push / announce (session announce or Control UI–visible completion) -- **not** `get_command_or_subagent_output`, and not Cursor Task completion semantics
+  - Cursor `Task` (background): Task completion-notification path
+- Execution: local. Working directory: the worktree the parent gave you (or your `--cwd` if running under `oz agent run --cwd` / OpenClaw session cwd).
 
 ## Bounded poll loop
 
@@ -533,7 +541,7 @@ Send:
 - ! Set `$env:GIT_EDITOR = "true"` (Windows PowerShell) or `GIT_EDITOR=true` (Unix) BEFORE any git command that could open an editor (rebase, commit --amend) to prevent terminal lockup.
 - ! Use Python scripts (single `run_shell_command` call) for the poll loop, NEVER shell `Start-Sleep` + repeated tool calls. The Python script handles `time.sleep({poll_interval_seconds})` between polls and exits when a terminal condition fires.
 - ! Always pass `do_not_summarize_output: true` semantics when fetching `gh pr view --comments` -- summarizers silently drop the Outside-Diff section.
-- ! Send a status message to `{parent_agent_id}` at start (acknowledging the task) and at every terminal exit (CLEAN / NEW P0/P1 FINDINGS escalation / ERRORED / TIMEOUT / STALL). Do NOT silently complete.
+- ! Send a status message to `{parent_agent_id}` at start (acknowledging the task) and at every terminal exit (CLEAN / NEW P0/P1 FINDINGS escalation / ERRORED / TIMEOUT / STALL / INFORMAL-CLEAN). Route it through the host completion channel for your primitive (see Role posture -- OpenClaw `sessions_spawn` uses parent push / announce). Do NOT silently complete.
 
 ## Implementation Notes
 
@@ -554,3 +562,4 @@ Dogfood lessons captured during the #727 self-review cycle. The template body ab
 - #727 -- this template's acceptance issue and the full anti-pattern record (rm-chaining, parsing-bug recurrence, role-conflation in implementation-agent prompts).
 - #1039 -- (5) STALL terminal exit + Tier 1 instrumentation + Tier 3 per-condition fail-loud (`clean_gate_holdout`); the third recurrence in this template's detector-gap chain after #910 (triple-tier) and #1035 (Tier 2.5 + confidence-heading).
 - #1364 -- cohort-level CLEAN verification gate (`task swarm:verify-review-clean`, `scripts/swarm_verify_review_clean.py`). The (1) CLEAN section's swarm-orchestrated terminal contract block declares that only the exact `PR #{pr_number} CLEAN -- ready for merge` subject with `confidence > 3` on current HEAD is an acceptable "review complete" signal for the swarm monitor's Phase 5 -> 6 transition; the cohort verifier picks up any other terminal exit ((2) NEW P0/P1 FINDINGS escalation, (3) ERRORED, (4) TIMEOUT, (5) STALL) and holds the merge gate until fresh poller re-dispatch or explicit user escalation resolves it. Recurrence record: #1166 swarm execution where multiple pollers exited with `clean_gate_holdout=confidence` (confidence == 3) and the monitor still raised the Phase 5 -> 6 gate because the trigger keyed on "all pollers have reported back" rather than "every PR in the cohort is objectively CLEAN".
+- #2879 -- OpenClaw `sessions_spawn` + parent push/announce completion channel named in Role posture (alongside Warp `start_agent` and grok-build `spawn_subagent`); heartbeat mapping in `docs/subagent-heartbeat.md` and preamble §10.5. Epic #2874.

package/vbrief/vbrief.md

@@ -1,10 +1,12 @@
 # vBRIEF Usage in Deft
 
-Canonical reference for vBRIEF file conventions within Deft-managed projects.
+> **Public name (#2907):** The sole current work-state name is **xBRIEF** under `xbrief/` (`.xbrief.json`). **vBRIEF** / `vbrief/` / `.vbrief.json` in this document are **legacy / schema-lineage** names (this path still hosts core schemas). Prefer xbrief in product docs and new guidance. Authoritative rename/history: [UPGRADING.md — xBRIEF rename](../UPGRADING.md#xbrief-rename-2034--2110--2907). Migrate on-disk layouts with `deft migrate:xbrief`.
+
+Canonical **schema and convention** reference for durable work-state files within Deft-managed projects (historical filename: vBRIEF).
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [context/working-memory.md](../context/working-memory.md) | [resilience/continue-here.md](../resilience/continue-here.md) | [context/long-horizon.md](../context/long-horizon.md) | [glossary.md](../glossary.md)
+**⚠️ See also**: [glossary.md](../glossary.md) | [UPGRADING.md — xBRIEF rename](../UPGRADING.md#xbrief-rename-2034--2110--2907) | [context/working-memory.md](../context/working-memory.md) | [resilience/continue-here.md](../resilience/continue-here.md)
 
 ---