@orchestrator-claude/definitions 3.37.0 → 3.37.1

package/hooks/dangling-guard.mjs

@@ -3925,7 +3925,7 @@ var init_esm5 = __esm({
 
 // ../../node_modules/path-scurry/dist/esm/index.js
 import { posix, win32 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { fileURLToPath } from "node:url";
 import { lstatSync, readdir as readdirCB, readdirSync as readdirSync2, readlinkSync, realpathSync as rps } from "fs";
 import * as actualFS from "node:fs";
 import { lstat, readdir, readlink, realpath } from "node:fs/promises";
@@ -5057,7 +5057,7 @@ var init_esm6 = __esm({
       constructor(cwd = process.cwd(), pathImpl, sep2, { nocase, childrenCacheSize = 16 * 1024, fs = defaultFS } = {}) {
         this.#fs = fsFromOption(fs);
         if (cwd instanceof URL || cwd.startsWith("file://")) {
-          cwd = fileURLToPath2(cwd);
+          cwd = fileURLToPath(cwd);
         }
         const cwdPath = pathImpl.resolve(cwd);
         this.roots = /* @__PURE__ */ Object.create(null);
@@ -6491,7 +6491,7 @@ var init_walker = __esm({
 });
 
 // ../../node_modules/glob/dist/esm/glob.js
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 var defaultPlatform3, Glob;
 var init_glob = __esm({
   "../../node_modules/glob/dist/esm/glob.js"() {
@@ -6559,7 +6559,7 @@ var init_glob = __esm({
         if (!opts.cwd) {
           this.cwd = "";
         } else if (opts.cwd instanceof URL || opts.cwd.startsWith("file://")) {
-          opts.cwd = fileURLToPath3(opts.cwd);
+          opts.cwd = fileURLToPath2(opts.cwd);
         }
         this.cwd = opts.cwd || "";
         this.root = opts.root;
@@ -6799,34 +6799,64 @@ var init_esm7 = __esm({
 
 // hooks/lib/api-client.ts
 import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
-import { join as join2, dirname as dirname2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join as join2 } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 
 // ../project-root-resolver/dist/index.js
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+function hasProjectRootMarker(candidate, sentinel) {
+  return existsSync(join(candidate, ".git")) || existsSync(join(candidate, "package.json")) || existsSync(join(candidate, sentinel, ".root"));
+}
 function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  const candidates = [];
   let currentDir = cwd;
   for (; ; ) {
     if (existsSync(join(currentDir, sentinel))) {
-      return currentDir;
+      candidates.push(currentDir);
     }
     const parentDir = dirname(currentDir);
     if (parentDir === currentDir) {
-      return null;
+      break;
     }
     currentDir = parentDir;
   }
+  const [innermost] = candidates;
+  if (innermost === void 0) {
+    return null;
+  }
+  for (const candidate of candidates) {
+    if (hasProjectRootMarker(candidate, sentinel)) {
+      return candidate;
+    }
+  }
+  return innermost;
 }
 
 // hooks/lib/api-client.ts
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname2(__filename);
-var PROJECT_ROOT = join2(__dirname, "..", "..", "..");
-var STATE_DIR = join2(PROJECT_ROOT, ".orchestrator", ".state");
+function resolveFallbackStateDir(cwd) {
+  const cwdHash = createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+  return join2(tmpdir(), "orchestrator-hook-fallback", cwdHash);
+}
+var PROJECT_ROOT = (() => {
+  const resolved = resolveHookProjectRoot(process.cwd());
+  if (resolved !== null && hasProjectRootMarker(resolved, ".orchestrator")) {
+    return resolved;
+  }
+  return null;
+})();
+var STATE_DIR_OVERRIDE = process.env.ORCHESTRATOR_STATE_DIR;
+var STATE_DIR = STATE_DIR_OVERRIDE !== void 0 && STATE_DIR_OVERRIDE !== "" ? STATE_DIR_OVERRIDE : PROJECT_ROOT !== null ? join2(PROJECT_ROOT, ".orchestrator", ".state") : resolveFallbackStateDir(process.cwd());
 var JWT_CACHE = join2(STATE_DIR, "jwt-token");
 var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
 mkdirSync(STATE_DIR, { recursive: true });
+if ((STATE_DIR_OVERRIDE === void 0 || STATE_DIR_OVERRIDE === "") && PROJECT_ROOT === null) {
+  log(
+    "API-CLIENT",
+    `PROJECT_ROOT: no marker-verified ".orchestrator" project root found above ${process.cwd()} \u2014 falling back to isolated state dir ${STATE_DIR} (RF-003)`
+  );
+}
 var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
 var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
 var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";

package/hooks/gate-guardian.mjs

@@ -2,34 +2,64 @@ import { createRequire as __createRequireShim } from 'node:module'; const requir
 
 // hooks/lib/api-client.ts
 import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
-import { join as join2, dirname as dirname2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join as join2 } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 
 // ../project-root-resolver/dist/index.js
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+function hasProjectRootMarker(candidate, sentinel) {
+  return existsSync(join(candidate, ".git")) || existsSync(join(candidate, "package.json")) || existsSync(join(candidate, sentinel, ".root"));
+}
 function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  const candidates = [];
   let currentDir = cwd;
   for (; ; ) {
     if (existsSync(join(currentDir, sentinel))) {
-      return currentDir;
+      candidates.push(currentDir);
     }
     const parentDir = dirname(currentDir);
     if (parentDir === currentDir) {
-      return null;
+      break;
     }
     currentDir = parentDir;
   }
+  const [innermost] = candidates;
+  if (innermost === void 0) {
+    return null;
+  }
+  for (const candidate of candidates) {
+    if (hasProjectRootMarker(candidate, sentinel)) {
+      return candidate;
+    }
+  }
+  return innermost;
 }
 
 // hooks/lib/api-client.ts
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname2(__filename);
-var PROJECT_ROOT = join2(__dirname, "..", "..", "..");
-var STATE_DIR = join2(PROJECT_ROOT, ".orchestrator", ".state");
+function resolveFallbackStateDir(cwd) {
+  const cwdHash = createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+  return join2(tmpdir(), "orchestrator-hook-fallback", cwdHash);
+}
+var PROJECT_ROOT = (() => {
+  const resolved = resolveHookProjectRoot(process.cwd());
+  if (resolved !== null && hasProjectRootMarker(resolved, ".orchestrator")) {
+    return resolved;
+  }
+  return null;
+})();
+var STATE_DIR_OVERRIDE = process.env.ORCHESTRATOR_STATE_DIR;
+var STATE_DIR = STATE_DIR_OVERRIDE !== void 0 && STATE_DIR_OVERRIDE !== "" ? STATE_DIR_OVERRIDE : PROJECT_ROOT !== null ? join2(PROJECT_ROOT, ".orchestrator", ".state") : resolveFallbackStateDir(process.cwd());
 var JWT_CACHE = join2(STATE_DIR, "jwt-token");
 var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
 mkdirSync(STATE_DIR, { recursive: true });
+if ((STATE_DIR_OVERRIDE === void 0 || STATE_DIR_OVERRIDE === "") && PROJECT_ROOT === null) {
+  log(
+    "API-CLIENT",
+    `PROJECT_ROOT: no marker-verified ".orchestrator" project root found above ${process.cwd()} \u2014 falling back to isolated state dir ${STATE_DIR} (RF-003)`
+  );
+}
 var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
 var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
 var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";

package/hooks/hooks.json

@@ -2,7 +2,7 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume",
+        "matcher": "startup|resume|clear|compact|fork",
         "hooks": [
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"", "timeout": 10000 },
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sprint-registry.mjs\"", "timeout": 5000 }
@@ -42,13 +42,13 @@
     ],
     "SubagentStart": [
       {
-        "matcher": "(orchestrator:)?(implementer|specifier|planner|task-generator|reviewer|researcher)",
+        "matcher": "(orchestrator:)?(adversarial-reviewer|api-extractor|azure-devops-engineer|business-rule-miner|cicd-platform-engineer|ciclo-engineer|code-archaeologist|debug-sidecar|doc-sidecar|docs-guardian|frontend-engineer|harness-architect|implementer|legacy-discoverer|legacy-synthesizer|methodology-researcher|operational-artifact-builder|orchestrator|planner|presentation-engineer|python-data-engineer|researcher|reviewer|schema-extractor|software-architect|specifier|task-generator|test-sidecar)",
         "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.mjs\"", "timeout": 10000 }]
       }
     ],
     "SubagentStop": [
       {
-        "matcher": "(orchestrator:)?(implementer|specifier|planner|task-generator|reviewer|researcher)",
+        "matcher": "(orchestrator:)?(adversarial-reviewer|api-extractor|azure-devops-engineer|business-rule-miner|cicd-platform-engineer|ciclo-engineer|code-archaeologist|debug-sidecar|doc-sidecar|docs-guardian|frontend-engineer|harness-architect|implementer|legacy-discoverer|legacy-synthesizer|methodology-researcher|operational-artifact-builder|orchestrator|planner|presentation-engineer|python-data-engineer|researcher|reviewer|schema-extractor|software-architect|specifier|task-generator|test-sidecar)",
         "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.mjs\"", "timeout": 30000 }]
       }
     ],
@@ -67,12 +67,6 @@
         "matcher": "mcp__(plugin_orchestrator_)?orchestrator-tools__advancePhase",
         "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-implement.mjs\"", "timeout": 15000 }]
       }
-    ],
-    "PostCompact": [
-      {
-        "matcher": "",
-        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-compact.mjs\"", "timeout": 5000 }]
-      }
     ]
   }
 }

package/hooks/lib/api-client.ts

@@ -4,21 +4,119 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { resolveProjectRoot } from '@orchestrator-claude/project-root-resolver';
-
-// Resolve paths relative to this file
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PROJECT_ROOT = join(__dirname, '..', '..', '..');
-const STATE_DIR = join(PROJECT_ROOT, '.orchestrator', '.state');
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import {
+  resolveProjectRoot,
+  hasProjectRootMarker,
+} from '@orchestrator-claude/project-root-resolver';
+
+// S467 H-1 (TASK-004): `__filename`/`__dirname` (this file's own on-disk
+// location) used to anchor PROJECT_ROOT below — removed together with that
+// derivation. See the RF-001/RF-002/RF-003 comment block ahead of
+// PROJECT_ROOT for why anchoring on this file's own location was the bug.
+
+/**
+ * RF-003 (S467, H-1): pure, zero-throw fallback used when the calling
+ * session's own cwd has no resolvable, marker-verified `.orchestrator`
+ * project root (see PROJECT_ROOT below) — e.g. an arbitrary directory, or a
+ * bare/incidental sentinel that fails the marker check (RF-002). Isolated
+ * per-cwd via a stable hash so two distinct unresolved cwds never collide
+ * on the same fallback directory (verified:
+ * api-client-project-root-derivation.test.ts, RF-003 anti-collision case),
+ * and deliberately OUTSIDE this repo's own tree (os.tmpdir()) so it can
+ * never be mistaken for, or leak into, this repo's own `.orchestrator/.state`.
+ */
+export function resolveFallbackStateDir(cwd: string): string {
+  const cwdHash = createHash('sha256').update(cwd).digest('hex').slice(0, 16);
+  return join(tmpdir(), 'orchestrator-hook-fallback', cwdHash);
+}
+
+// TD-224 Achado 0 (S426) superseded by S467 H-1 (RF-001/RF-002/RF-003): this
+// used to derive PROJECT_ROOT via `resolveProjectRoot(__dirname)` —
+// `__dirname` is the location of THIS FILE ON DISK, not the calling
+// session's own working directory. Because the `orchestrator-local`
+// marketplace resolves by `directory` (marketplace.json `source:
+// "./packages/definitions"`), every hook process on this machine, for every
+// session of every consumer project, has `__dirname` inside THIS repo's own
+// checkout — so the walk-up always found and won on THIS repo's
+// `.orchestrator` sentinel, regardless of which project's session actually
+// invoked the hook. Cross-project state leakage (H-1).
+//
+// RF-001: anchor on `process.cwd()` — the session's own cwd — via the
+// already-exported `resolveHookProjectRoot` wrapper below, instead of
+// `__dirname`.
+//
+// RF-002: a bare `.orchestrator` sentinel with none of
+// `.git`/`package.json`/`.orchestrator/.root` (e.g. a real user home
+// directory that happens to carry a bare `.orchestrator` dir — measured
+// S466/S467 against this very machine's `/home/cmac`) must NOT resolve to
+// itself. `resolveProjectRoot`'s own backward-compatible fallback
+// (innermost-wins when no candidate satisfies the marker check, ADR-P3)
+// would otherwise happily return it — reject that case explicitly via the
+// now-exported `hasProjectRootMarker` (ADR-P3, TASK-003) and fall through
+// to RF-003.
+//
+// RF-003: never `throw` at module load. The prior comment here justified
+// throwing by citing `.orchestrator/.state/.gitkeep` (tracked at this
+// repo's own root) as a guarantee the sentinel is "always present" — that
+// guarantee held only because the OLD code anchored on `__dirname` (always
+// inside this repo). It stops applying once the anchor is `process.cwd()`
+// of an arbitrary session: a hook process serving ANY unregistered cwd must
+// still load and degrade gracefully into an isolated, per-cwd fallback
+// state directory (`resolveFallbackStateDir` above), not crash every hook
+// invocation for that session (RNF-001, availability).
+//
+// ORCHESTRATOR_STATE_DIR (TD-224 Achado 1, RACE-001) is resolved separately
+// below and continues to win unconditionally over ALL of this — checked
+// before any consumer of PROJECT_ROOT/STATE_DIR ever runs.
+const PROJECT_ROOT = ((): string | null => {
+  const resolved = resolveHookProjectRoot(process.cwd());
+  if (resolved !== null && hasProjectRootMarker(resolved, '.orchestrator')) {
+    return resolved;
+  }
+  return null;
+})();
+// TD-224 Achado 1 (S426, RACE-001): ORCHESTRATOR_STATE_DIR, when set, wins
+// outright over the .orchestrator-sentinel-derived PROJECT_ROOT — every
+// state-file path below (JWT_CACHE, DEBUG_LOG, invocation/dispatch-intent
+// state) resolves inside the override directory instead. Motivation:
+// tests/unit/seam-conformance's execution extractor drives every exported
+// function of this module for real (fetch mocked, everything else live) to
+// build a route census; without this seam, the ONLY way to keep it from
+// touching the REAL dev-session jwt-token cache was a backup/seed/restore
+// dance around the real path — unsafe both under concurrent test-file
+// execution (two vitest worker threads) and under process interruption (a
+// kill between "seed" and "restore" corrupts the real cache with zero
+// concurrency required). Pointing this override at an isolated temp
+// directory removes the real path from the equation entirely: no window,
+// concurrent or interrupted, in which it is ever opened. Unset in every
+// production invocation — default derivation is unchanged.
+const STATE_DIR_OVERRIDE = process.env.ORCHESTRATOR_STATE_DIR;
+const STATE_DIR =
+  STATE_DIR_OVERRIDE !== undefined && STATE_DIR_OVERRIDE !== ''
+    ? STATE_DIR_OVERRIDE
+    : PROJECT_ROOT !== null
+      ? join(PROJECT_ROOT, '.orchestrator', '.state')
+      : resolveFallbackStateDir(process.cwd());
 const JWT_CACHE = join(STATE_DIR, 'jwt-token');
 const DEBUG_LOG = join(STATE_DIR, 'hook-debug.log');
 
 // Ensure state dir exists
 mkdirSync(STATE_DIR, { recursive: true });
 
+// RF-003: log the fallback degradation, once, at module load — but only
+// when it actually happened (override absent AND no marker-verified
+// project root resolved for this cwd).
+if ((STATE_DIR_OVERRIDE === undefined || STATE_DIR_OVERRIDE === '') && PROJECT_ROOT === null) {
+  log(
+    'API-CLIENT',
+    `PROJECT_ROOT: no marker-verified ".orchestrator" project root found above ${process.cwd()} — ` +
+      `falling back to isolated state dir ${STATE_DIR} (RF-003)`
+  );
+}
+
 // Config from env
 const API_URL = process.env.ORCHESTRATOR_API_URL || 'http://localhost:3001';
 // RFC-040 ADR-002 (S358, TASK-RBAC-02): hooks authenticate as the seeded
@@ -153,6 +251,27 @@ export function setEffectiveProjectId(projectId: string): void {
   PROJECT_ID = projectId;
 }
 
+// --- Agent Identity Normalization (TD-214/TD-239 TASK-001) ---
+
+/**
+ * Strip the plugin namespace from a dispatch name.
+ *
+ * Under plugin scope the harness namespaces every agent (`orchestrator:implementer`
+ * — measured in the S398 sandbox, RFC-040 §18.14); in project scope the same agent
+ * arrives bare (`implementer`). A guard that compares against the bare name only
+ * answers `false` for the namespaced form — and since hooks fail open, it disables
+ * itself in silence. Both forms MUST resolve to the same decision.
+ *
+ * Moved here from `pre-agent-dispatch.ts` (TD-214/TD-239 TASK-001) so every hook
+ * that needs identity normalization shares ONE implementation instead of
+ * hand-rolling its own `lastIndexOf(':')` substring logic — see TASK-002's
+ * consolidator test for the full list of consumers this is meant to unify.
+ */
+export function normalizeAgentName(subagentType: string): string {
+  const i = subagentType.lastIndexOf(':');
+  return i === -1 ? subagentType : subagentType.slice(i + 1);
+}
+
 // --- Types ---
 
 export interface WorkflowStatus {