session-orchestrator 3.22.0 → 3.24.0

package/hooks/enforce-scope.mjs

@@ -9,6 +9,12 @@
  *   G1  tool filter — only Edit/Write/MultiEdit are gated
  *   G2  file_path present + string
  *   G3  wave-scope.json exists
+ *   G3b (#1123, #1194) the manifest belongs to THIS session — a manifest that
+ *       PROVABLY names another live session in this shared working copy is not
+ *       ours to enforce; allow + emit one event. Runs AFTER the parse so a
+ *       corrupt manifest still fails closed. Identity is PROCESS-LOCAL only
+ *       (hook payload + CLAUDE_CODE_SESSION_ID), never the repo-global
+ *       `session.lock` — see the gate's own block for why.
  *   G4  path-guard gate enabled
  *   G5  enforcement != "off"
  *   G5b (#792) allowlist-first: an EXPLICIT absolute allowedPaths entry that
@@ -98,6 +104,11 @@ let readJson;
 let classifyEmptyScope;
 let suggestForEmptyScope;
 let sessionStartedAtMs;
+// #1123 — "is this manifest even mine?" (G3b). Process-local identity only
+// (#1194): the repo-global `session.lock` tier is shared by every session in the
+// checkout and would classify a peer's manifest as ours.
+let readProcessLocalSessionIds;
+let classifyManifestSession;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -154,6 +165,10 @@ async function bootstrap() {
       // `scope-gate` transitively, so this adds no new failure mode — a broken
       // scope-gate already banners GUARD INACTIVE through that edge.
       scopeGate: { specifier: lib('scope-gate.mjs') },
+      // #1123. Bound through the same loader as every other repo dependency, so
+      // a SyntaxError in the identity module banners GUARD INACTIVE instead of
+      // link-crashing the hook into a silent fail-open (#993).
+      sessionIdentity: { specifier: lib('session-identity/own-session.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -169,6 +184,7 @@ async function bootstrap() {
   ({ findScopeFile, pathMatchesPattern, suggestForScopeViolation } = modules.hardening);
   ({ readJson } = modules.common);
   ({ classifyEmptyScope, suggestForEmptyScope, sessionStartedAtMs } = modules.scopeGate);
+  ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
 }
 
 async function main() {
@@ -220,6 +236,83 @@ async function main() {
     scope = {};
   }
 
+  // -------------------------------------------------------------------------
+  // Gate 3b (#1123) — is this manifest even MINE?
+  //
+  // `wave-scope.json` lives in the WORKING COPY, not in the session. Two live
+  // sessions sharing one checkout read the same file, so session A's manifest
+  // enforced session B's writes: measured 2026-08-22 (#1082), where a Discovery
+  // wave's `allowedPaths: []` — which `wave-loop.md` prescribes for EVERY
+  // Discovery wave — denied every write of an unrelated parallel session, with
+  // a deny reason that could only tell it to fix a wave plan it does not own.
+  //
+  // Deliberately runs AFTER the parse block: a corrupt manifest yields `{}`,
+  // hence no ids, hence `'unknown'` — and keeps failing closed. A gate that
+  // peeked at the raw bytes instead would let a truncated manifest disarm the
+  // guard.
+  //
+  // `'own'` and `'unknown'` fall through completely unchanged. A legacy manifest
+  // without a `session` field is `'unknown'` and stays enforced: only what is
+  // PROVABLY foreign is treated as foreign.
+  //
+  // IDENTITY TIER (#1194): `readProcessLocalSessionIds` — the hook payload and
+  // `CLAUDE_CODE_SESSION_ID` — and deliberately NOT `readOwnSessionIds`, whose
+  // third tier is the repo-global `session.lock`. That lock is ONE file shared
+  // by every session in the checkout, so unioning it made a peer's manifest
+  // match a peer-written lock id and classify as `'own'`: Gate 7 then denied the
+  // second session's legitimate writes — the exact lockout G3b exists to end.
+  // A better signal REPLACES a worse one (`host-resources.md` § HR-102).
+  //
+  // The trade this buys, accepted rather than hidden: a session that wrote a
+  // PEER's id into its OWN manifest (it lost the `bootstrapLock()` race, so
+  // `sessionAttribution()` handed it the peer's lock id) now reads `'foreign'`
+  // and its own guard stands down. The defense is on the WRITER side — the
+  // manifest writer must omit the `session` keys when the lock does not name it
+  // (`skills/wave-executor/wave-loop.md` § Scope Manifest, "Verify the binding
+  // names YOU before you write it") — not on this reader.
+  //
+  // CEILING (BV-004): on a harness that exports no session env var and puts no
+  // `session_id` in the hook payload (Codex CLI, Cursor today), both tiers are
+  // empty, so G3b is permanently `'unknown'` = enforce = pre-#1123 behaviour
+  // there. Revisit when Codex/Cursor hook payloads carry a session id.
+  //
+  // ACCEPTED RESIDUAL, named rather than hidden: `session` is a plain field in a
+  // file any process in this working copy can write, so writing a foreign id
+  // into it switches this guard off for that manifest. That is the SAME power
+  // `enforcement: "off"` already grants in the same file — this gate adds no new
+  // authority, and the manifest is the coordinator's own artefact either way.
+  {
+    // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
+    // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
+    // ownIds : new Set()` — a bare array would silently become EMPTY, making
+    // every manifest read `unknown`.
+    const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+    const { verdict, manifestIds } = classifyManifestSession(scope, ownIds);
+    if (verdict === 'foreign') {
+      // Observability only, and deliberately NOT emitWarn: this branch is hit on
+      // every single Edit of the non-owning session, so a stderr line per write
+      // would be noise the operator learns to ignore. One event per decision
+      // point, awaited before emitAllow() — emitAllow() calls process.exit(),
+      // which would discard a pending append.
+      try {
+        const { emitEvent } = await import('../scripts/lib/events.mjs');
+        await emitEvent(
+          'orchestrator.scope.foreign_session_ignored',
+          {
+            hook: HOOK_NAME,
+            manifest: scopePath,
+            manifest_session: manifestIds,
+            own_session: [...ownIds],
+            wave: scope.wave,
+            file_path: filePath,
+          },
+          { repoRoot: projectRoot },
+        );
+      } catch { /* observability is best-effort — never blocks the decision */ }
+      return emitAllow();
+    }
+  }
+
   const enforcement = scope.enforcement ?? 'strict';
   const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
   // A PRESENT-but-non-array `allowedPaths` (#558: null / string / object) is a

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.22.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.24.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks-cursor.json

@@ -1,24 +1,205 @@
 {
-  "_comment": "Cursor IDE hook mapping reference. Configure hooks in Cursor Settings > Hooks.",
-  "_note": "Cursor hooks fire at different lifecycle points than Claude Code. See docs/cursor-setup.md for details.",
-  "_limitation": "SessionStart greeting (session-start skill) is NOT available on Cursor. Cursor has no conversation-start lifecycle event equivalent to Claude Code's UserPromptSubmit hook. Session initialisation must be triggered manually.",
-  "_enforcement": "reference-only",
-  "_enforcement_note": "MACHINE-READABLE STATUS (#919): every entry below is an intended mapping, NOT live enforcement. No Cursor payload adapter exists (Pi has scripts/lib/pi-hook-bridge.mjs; Cursor has nothing), so each handler short-circuits on a Cursor-shaped payload and writes 0 bytes with exit 0. Operator decision 2026-07-31: gap registered, not closed. The machine-readable counterpart of this key is DOCUMENTED_ASYMMETRIES.handlerAsymmetries.cursor in scripts/lib/validate/check-hooks-symmetry.mjs, which Check 6 counts per event; the projection that makes that comparison non-vacuous is DOCUMENTED_ASYMMETRIES.cursorEventMap.",
-  "_issues": ["#919", "#946"],
+  "_comment": "Cursor IDE hook mapping. Event names are Cursor-native; commands receive Claude/Codex-compatible hook JSON on stdin after scripts/lib/cursor-hook-bridge.mjs normalises the payload. CURSOR_PLUGIN_ROOT is set by the bridge; CURSOR_RULES_DIR is the compatibility alias used by plugin-root resolution.",
+  "_enforcement": "live",
+  "_enforcement_note": "LIVE via scripts/lib/cursor-hook-bridge.mjs and .cursor/hooks.json. The bridge maps Cursor stdin onto tool_name / tool_input and maps emitDeny envelopes onto Cursor { permission }. afterFileEdit remains post-hoc (cannot prevent an edit already written).",
+  "_issues": ["#919"],
   "hooks": {
-    "afterFileEdit": {
-      "script": "hooks/enforce-scope.mjs",
-      "enforcement": "none",
-      "issue": "#919",
-      "mapsToClaudeEvent": "PostToolUse",
-      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before), so this maps onto PostToolUse, never PreToolUse. Cannot prevent out-of-scope edits, only warn — and today not even that: on a Cursor afterFileEdit payload enforce-scope.mjs writes 0 bytes to stdout AND stderr with exit 0 (measured 2026-07-31), because it reads Claude Code's PreToolUse field names."
-    },
-    "beforeShellExecution": {
-      "script": "hooks/enforce-commands.mjs",
-      "enforcement": "none",
-      "issue": "#919",
-      "mapsToClaudeEvent": "PreToolUse",
-      "note": "NOT WIRED (#919) — silent no-op on a Cursor payload, NOT a block. The handler reads Claude Code's PreToolUse field names (tool_name === 'Bash', tool_input.command) and emits a Claude Code PreToolUse envelope (hookSpecificOutput.permissionDecision). Fed a Cursor beforeShellExecution payload it short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with exit 0 — the harness sees no decision, so the command runs. Cursor needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none exists. Treat this entry as the intended mapping, not as live enforcement."
-    }
+    "sessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-session-start.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "sessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-session-end.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-destructive-guard.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-staging-fence.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-memory-propose-audit.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-sessions-ledger-guard.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-templates-first.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/pre-bash-issue-budget.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/enforce-commands.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "preToolUse": [
+      {
+        "matcher": "Write|StrReplace|TabWrite|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/enforce-scope.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/config-protection.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "afterShellExecution": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-bash-write-verify.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "postToolUse": [
+      {
+        "matcher": "Write|StrReplace|TabWrite|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-edit-validate.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/loop-guard.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-edit-validate.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tooluse-frontend-slop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tool-failure-corrective-context.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "subagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/subagent-telemetry.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "subagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/on-stop.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/subagent-telemetry.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-subagent-discovery-validator.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
   }
 }

package/hooks/hooks-pi.json

@@ -20,7 +20,7 @@
           {
             "type": "command",
             "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/on-session-end.mjs\"",
-            "timeout": 5
+            "timeout": 10
           }
         ]
       }

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.22.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.24.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -25,7 +25,7 @@
           {
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/on-session-end.mjs\"",
-            "timeout": 5
+            "timeout": 10
           }
         ]
       }