@mstar-harness/engine 3.4.0 → 3.4.1

package/dist/dispatch.d.ts

@@ -172,13 +172,24 @@ export declare function assertTriIdentity(reviewerRoles: readonly string[]): Gat
  */
 export type ComposeDispatchGateOptions = {
     /**
-     * Host role-binding field (omp task entry `agent` / opencode `subagent` /
-     * cursor `subagent_type` / dsh `dispatchBinding`). The anti-recursion
-     * precheck runs for EVERY Assignment-shaped text: an empty or omitted
-     * binding fails closed (`dispatch.anti-recursion.empty-binding`) — the
-     * host cannot prove the dispatching agent is not recursing.
+     * Dispatching agent's OWN harness role (dsh `Config.dispatchBinding`).
+     * When non-empty, the anti-recursion precheck compares it against the
+     * Assignment's `Execute as` — equality is self-recursion
+     * (`dispatch.anti-recursion.self-type`, critical). Leave unset on hosts
+     * whose tool-call event cannot report the dispatching agent's identity
+     * (omp/opencode/cursor): the precheck is skipped there and the NEVER red
+     * line stays prompt-level (mstar-dispatch-gates).
      */
-    agent?: string;
+    caller?: string;
+    /**
+     * True on hosts whose contract declares the caller binding mandatory
+     * (dsh): an empty/missing `caller` then fails closed with
+     * `dispatch.anti-recursion.empty-binding` (critical) — the host could
+     * have declared the binding, so an absent one proves nothing and the
+     * dispatch must not proceed as if the NEVER red line held. Default
+     * `false`: the precheck is skipped entirely when `caller` is empty.
+     */
+    callerRequired?: boolean;
     /**
      * `false` for read-only roles (scout/explore) — skips the branch-form and
      * default-branch gates. Default: `true` (writable).
@@ -206,10 +217,14 @@ export type ComposeDispatchGateResult = GateResult & {
  *    Assignment-shaped passes silently (`shaped: false`).
  * 2. `validateAssignmentFields` with `writable: false` when `opts.writable
  *    === false` (read-only roles), else the writable default.
- * 3. Anti-recursion precheck — runs for every Assignment-shaped text; an
- *    empty/omitted host binding fails closed (`dispatch.anti-recursion.
- *    empty-binding`), a binding equal to `Execute as` is the existing
- *    `dispatch.anti-recursion.self-type` critical.
+ * 3. Anti-recursion precheck — CALLER semantics (issue #156): runs only
+ *    when the host supplies its own role binding (`caller`), or fails
+ *    closed on an empty one when the host contract requires it
+ *    (`callerRequired`, dsh). A caller equal to `Execute as` is the
+ *    `dispatch.anti-recursion.self-type` critical; a required-but-empty
+ *    caller is `dispatch.anti-recursion.empty-binding`. Target-only hosts
+ *    (omp/opencode/cursor) skip the leg — their binding field carries the
+ *    spawn TARGET, which equals `Execute as` on every compliant dispatch.
  * 4. Default-branch gate for writable text: the branch comes from the
  *    Assignment's own branch forms (create-form name / Working branch /
  *    Branch policy branch), else `$MSTAR_WORKING_BRANCH`; a well-formed
@@ -224,13 +239,17 @@ export type ComposeDispatchGateResult = GateResult & {
 export declare function composeDispatchGate(text: string, opts?: ComposeDispatchGateOptions): ComposeDispatchGateResult;
 /**
  * Anti-recursion precheck (NEVER red line, mstar-dispatch-gates § 承接方反递归
- * 红线): a leaf executor MUST NOT invoke a Task/subagent whose role-binding
- * field (`subagent_type` / `agent` / `subagent`) equals its own `Execute as`.
- * Comparison is case-insensitive after trim. An EMPTY binding fails closed
- * (`dispatch.anti-recursion.empty-binding`, critical): the host cannot
- * report which agent is calling, so anti-recursion cannot be proven — the
- * dispatch must not proceed as if the NEVER red line held. An empty
- * `executeAs` with a set binding stays ok (field presence is
- * `validateAssignmentFields`' job, not this precheck).
+ * 红线): a leaf executor MUST NOT dispatch a Task/subagent whose target role
+ * (the new Assignment's `Execute as`) equals its OWN role. `subagentType`
+ * is therefore the DISPATCHING agent's own role binding (dsh
+ * `Config.dispatchBinding`) — never the spawn-target field (omp `agent` /
+ * opencode `subagent`), which equals `Execute as` on every compliant
+ * dispatch (issue #156). Comparison is case-insensitive after trim. An
+ * EMPTY binding fails closed (`dispatch.anti-recursion.empty-binding`,
+ * critical): the host cannot report which agent is calling, so
+ * anti-recursion cannot be proven — the dispatch must not proceed as if
+ * the NEVER red line held. An empty `executeAs` with a set binding stays
+ * ok (field presence is `validateAssignmentFields`' job, not this
+ * precheck).
  */
 export declare function antiRecursionPrecheck(subagentType: string, executeAs: string): GateResult;

package/dist/engine.js

@@ -965,8 +965,10 @@ function composeDispatchGate(text, opts = {}) {
     const violations = [];
     const writable = opts.writable !== false;
     violations.push(...validateAssignmentFields(text, { writable }).violations);
-    const agent = opts.agent ?? "";
-    violations.push(...antiRecursionPrecheck(agent, parseAssignmentFields(text).executeAs ?? "").violations);
+    const caller = opts.caller ?? "";
+    if (caller.trim() !== "" || opts.callerRequired === true) {
+      violations.push(...antiRecursionPrecheck(caller, parseAssignmentFields(text).executeAs ?? "").violations);
+    }
     if (writable) {
       const forms = parseAssignmentBranchForms(text);
       const branch = forms.createForm?.name ?? forms.workingBranch ?? forms.directOn?.branch ?? process.env.MSTAR_WORKING_BRANCH;
@@ -989,7 +991,7 @@ function antiRecursionPrecheck(subagentType, executeAs) {
     return {
       ok: false,
       violations: [
-        violation3("critical", "dispatch.anti-recursion.empty-binding", `empty host role binding — the host cannot report which agent is calling, so anti-recursion cannot be proven (a dispatch could silently recurse)`, "set the host role-binding field (omp task entry `agent` / opencode `subagent` / cursor `subagent_type` / dsh `dispatchBinding`) before dispatching")
+        violation3("critical", "dispatch.anti-recursion.empty-binding", `empty caller role binding — the host cannot report which agent is calling, so anti-recursion cannot be proven (a dispatch could silently recurse)`, "declare the dispatching agent's own role binding (dsh Config `dispatchBinding`) before dispatching")
       ]
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {