@orchestrator-claude/definitions 3.36.0 → 3.37.1

package/hooks/pre-agent-dispatch.mjs

@@ -1,38 +1,68 @@
 import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
 
 // hooks/pre-agent-dispatch.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 
 // 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";
@@ -73,6 +103,10 @@ async function ensureProjectIdResolved(token) {
     );
   }
 }
+function normalizeAgentName(subagentType) {
+  const i = subagentType.lastIndexOf(":");
+  return i === -1 ? subagentType : subagentType.slice(i + 1);
+}
 function log(prefix, msg) {
   const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
   try {
@@ -211,6 +245,72 @@ function outputContext(hookEvent, context) {
   );
 }
 
+// hooks/lib/dispatch-marker.ts
+import { execFileSync } from "node:child_process";
+var DISPATCH_MARKER_REF_PREFIX = "refs/orchestrator/dispatch";
+var MAX_DISPATCH_MARKERS_PER_KEY = 20;
+var EMPTY_COMPONENT_PLACEHOLDER = "unknown";
+function sanitizeRefComponent(raw) {
+  const cleaned = (raw || "").replace(/[^A-Za-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned || EMPTY_COMPONENT_PLACEHOLDER;
+}
+function formatMarkerStamp(d) {
+  return d.toISOString().replace(/[-:.]/g, "");
+}
+function buildMarkerRefName(branch, agent, stamp) {
+  const branchPart = sanitizeRefComponent(branch);
+  const agentPart = sanitizeRefComponent(agent);
+  const stampPart = sanitizeRefComponent(stamp);
+  return `${DISPATCH_MARKER_REF_PREFIX}/${branchPart}/${stampPart}-${agentPart}`;
+}
+function runGitDefault(args) {
+  return execFileSync("git", args, {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+}
+function pruneOldestMarkers(prefix, cap, deps) {
+  const listed = deps.runGit(["for-each-ref", "--format=%(refname)", "--sort=refname", `${prefix}/`]).split("\n").map((l) => l.trim()).filter(Boolean);
+  const excess = listed.length - cap;
+  if (excess <= 0) return [];
+  const doomed = listed.slice(0, excess);
+  for (const ref of doomed) {
+    deps.runGit(["update-ref", "-d", ref]);
+  }
+  return doomed;
+}
+function writeDispatchBoundaryMarker(agentName, branch, deps) {
+  let ref = "";
+  try {
+    if (sanitizeRefComponent(agentName) === EMPTY_COMPONENT_PLACEHOLDER) {
+      return {
+        status: "failed",
+        reason: `refusing to write an unattributable marker (agent name "${agentName}")`
+      };
+    }
+    const sha = deps.runGit(["rev-parse", "HEAD"]).trim();
+    if (!/^[0-9a-f]{40}$/.test(sha)) {
+      return { status: "failed", reason: `HEAD did not resolve to a 40-hex sha (got "${sha}")` };
+    }
+    const stamp = formatMarkerStamp((deps.now ?? (() => /* @__PURE__ */ new Date()))());
+    ref = buildMarkerRefName(branch, agentName, stamp);
+    deps.runGit(["update-ref", ref, sha]);
+    let pruned = [];
+    try {
+      pruned = pruneOldestMarkers(
+        `${DISPATCH_MARKER_REF_PREFIX}/${sanitizeRefComponent(branch)}`,
+        MAX_DISPATCH_MARKERS_PER_KEY,
+        deps
+      );
+    } catch {
+      pruned = [];
+    }
+    return { status: "written", ref, sha, pruned };
+  } catch (err) {
+    return { status: "failed", reason: `${ref ? `ref="${ref}" ` : ""}${String(err)}` };
+  }
+}
+
 // hooks/pre-agent-dispatch.ts
 var HOOK = "PRE-AGENT-DISPATCH";
 var KNOWN_AGENTS = [
@@ -232,10 +332,6 @@ var COMMITTING_AGENTS = [
   "frontend-engineer"
 ];
 var PROTECTED_BRANCHES = ["main", "master"];
-function normalizeAgentName(subagentType) {
-  const i = subagentType.lastIndexOf(":");
-  return i === -1 ? subagentType : subagentType.slice(i + 1);
-}
 function isCommittingAgent(subagentType) {
   if (!subagentType) return false;
   const t = normalizeAgentName(subagentType).toLowerCase();
@@ -274,7 +370,7 @@ function evaluateDispatch(ctx) {
 }
 function readBranchFromGit() {
   try {
-    return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    return execFileSync2("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
@@ -288,7 +384,8 @@ var defaultDeps = {
   log,
   readBranch: readBranchFromGit,
   getActiveWorkflow,
-  writeDispatchIntent
+  writeDispatchIntent,
+  writeDispatchMarker: (agentName, branch) => writeDispatchBoundaryMarker(agentName, branch, { runGit: runGitDefault })
 };
 var DISPATCH_INTENT_RESOLVE_TIMEOUT_MS = 3e3;
 async function stampDispatchIntent(deps) {
@@ -310,6 +407,29 @@ async function stampDispatchIntent(deps) {
     deps.log(HOOK, `[TD-205] stampDispatchIntent failed (fail-open): ${String(err)}`);
   }
 }
+function markDispatchBoundary(subagentType, branch, deps) {
+  if (!deps.writeDispatchMarker) return [];
+  if (!isCommittingAgent(subagentType)) return [];
+  try {
+    const outcome = deps.writeDispatchMarker(subagentType, branch);
+    if (outcome.status === "written") {
+      deps.log(HOOK, `[S445] boundary marker ${outcome.ref} -> ${outcome.sha}`);
+      if (outcome.pruned.length > 0) {
+        deps.log(HOOK, `[S445] pruned ${outcome.pruned.length} marker(s) over retention cap`);
+      }
+      return [];
+    }
+    deps.log(HOOK, `[S445] boundary marker FAILED: ${outcome.reason}`);
+    return [
+      `[BOUNDARY-MARKER][S445] Could not record the pre-dispatch git coordinate for '${subagentType}' on '${branch}': ${outcome.reason}. The dispatch proceeds (this never blocks), but there will be NO ref to 'git reset --hard' back to for this agent's work.`
+    ];
+  } catch (err) {
+    deps.log(HOOK, `[S445] boundary marker threw (fail-open): ${String(err)}`);
+    return [
+      `[BOUNDARY-MARKER][S445] Boundary-marker step threw for '${subagentType}': ${String(err)}. Dispatch proceeds; no rollback coordinate was recorded.`
+    ];
+  }
+}
 async function mainWithDeps(deps) {
   const stdin = await deps.readStdin();
   const toolInput = getField(stdin, "tool_input") || "";
@@ -317,6 +437,7 @@ async function mainWithDeps(deps) {
   const prompt = getField(stdin, "tool_input.prompt") || getField(stdin, "tool_input.description") || (typeof toolInput === "string" ? toolInput : JSON.stringify(toolInput));
   const branch = deps.readBranch();
   const warnings = evaluateDispatch({ subagentType, prompt, branch });
+  warnings.push(...markDispatchBoundary(subagentType, branch, deps));
   await stampDispatchIntent(deps);
   if (warnings.length > 0) {
     deps.outputContext(HOOK, warnings.join("\n"));
@@ -340,7 +461,7 @@ export {
   isCommittingAgent,
   isProtectedBranch,
   mainWithDeps,
-  normalizeAgentName,
+  markDispatchBoundary,
   parseBranchFromHead,
   stampDispatchIntent
 };

package/hooks/pre-agent-dispatch.ts

@@ -1,7 +1,9 @@
 /**
  * pre-agent-dispatch.ts — PreToolUse hook for the Agent tool
  *
- * NON-BLOCKING (always exits 0; only injects advisory context). Two responsibilities:
+ * NON-BLOCKING (always exits 0; only injects advisory context). Four responsibilities
+ * (the count said "Two" while listing three, from S445 back to whenever the third was
+ * added — corrected here rather than left to drift a fourth time):
  *
  *  1. (RFC-027 Sprint 4) Warn when a known agent is dispatched WITHOUT subagent_type,
  *     so frontmatter (model/tools) loads correctly.
@@ -29,6 +31,15 @@
  *     Best-effort / fail-open in every dimension (missing deps, no active workflow,
  *     resolution timeout, filesystem error) — never blocks the dispatch.
  *
+ *  4. (S445, RFC-042) Boundary marker per ref. RFC-042 settled that a checkpoint is an
+ *     AUDIT MARK (D1) and is EXPLICIT (D2) — neither of which yields a coordinate for
+ *     "the state just before this agent started". This hook fires at the exact instant
+ *     of dispatch and already talks to git, so it records that coordinate: a ref under
+ *     `refs/orchestrator/` at HEAD's full 40-hex sha, for COMMITTING agents only.
+ *     It creates no commit, writes no file, and touches no database — a ref is git
+ *     metadata, so `git status` is unchanged. Rollback is deliberately NOT implemented:
+ *     it is plain `git reset --hard <ref>`. See lib/dispatch-marker.ts.
+ *
  * Design note (TD-171): the committing-agent set mirrors the `createCheckpoint` tool
  * holders in `.claude/agents/*.md`. Keep it in sync with that ground truth and with the
  * orchestrator SKILL §2c.1 Commit-Policy scope.
@@ -42,7 +53,13 @@ import {
   outputContext,
   getActiveWorkflow,
   writeDispatchIntent,
+  normalizeAgentName,
 } from './lib/api-client.js';
+import {
+  writeDispatchBoundaryMarker,
+  runGitDefault,
+  type DispatchMarkerOutcome,
+} from './lib/dispatch-marker.js';
 
 const HOOK = 'PRE-AGENT-DISPATCH';
 
@@ -80,20 +97,6 @@ const PROTECTED_BRANCHES: readonly string[] = ['main', 'master'];
 // Pure helpers (exported for testing)
 // ─────────────────────────────────────────────────────────────
 
-/**
- * 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.
- */
-export function normalizeAgentName(subagentType: string): string {
-  const i = subagentType.lastIndexOf(':');
-  return i === -1 ? subagentType : subagentType.slice(i + 1);
-}
-
 export function isCommittingAgent(subagentType: string): boolean {
   if (!subagentType) return false;
   const t = normalizeAgentName(subagentType).toLowerCase();
@@ -176,6 +179,13 @@ export interface HookDeps {
   getActiveWorkflow?: () => Promise<{ id: string } | null>;
   /** TD-205: stamps the dispatch-intent marker for workflowId. See getActiveWorkflow doc. */
   writeDispatchIntent?: (workflowId: string) => boolean;
+  /**
+   * S445 (RFC-042): records the git BOUNDARY MARKER for a committing agent —
+   * a ref at HEAD's full sha, so there is a coordinate to `git reset --hard`
+   * back to. Optional for the same reason as the TD-205 deps above: pre-S445
+   * test doubles must keep working, and an absent dep simply skips the marker.
+   */
+  writeDispatchMarker?: (agentName: string, branch: string) => DispatchMarkerOutcome;
 }
 
 function readBranchFromGit(): string {
@@ -197,6 +207,8 @@ const defaultDeps: HookDeps = {
   readBranch: readBranchFromGit,
   getActiveWorkflow,
   writeDispatchIntent,
+  writeDispatchMarker: (agentName, branch) =>
+    writeDispatchBoundaryMarker(agentName, branch, { runGit: runGitDefault }),
 };
 
 /**
@@ -240,6 +252,57 @@ export async function stampDispatchIntent(
   }
 }
 
+/**
+ * S445 (RFC-042): writes the git boundary marker for a COMMITTING agent, and
+ * returns an advisory line if it failed (empty array otherwise).
+ *
+ * ONLY committing agents get a marker. An agent that cannot commit cannot move
+ * HEAD, so a marker for it records a boundary nothing can cross — pure noise
+ * consuming the retention cap. This condition is the load-bearing one and is
+ * covered by an explicit negative control in the test suite.
+ *
+ * FAIL-OPEN BUT NOT SILENT. A marker failure must never block or delay the
+ * dispatch, so everything here is caught. But "fail-open" is not "invisible":
+ * the failure mode this feature must avoid is a GREEN VACUUM — the ref silently
+ * never being written (e.g. an invalid ref name) while everything looks fine. So
+ * a failure is reported on BOTH existing channels: the debug log AND the in-band
+ * advisory context the TD-171 branch warning already uses, which is the one a
+ * human or orchestrator actually reads.
+ */
+export function markDispatchBoundary(
+  subagentType: string,
+  branch: string,
+  deps: Pick<HookDeps, 'writeDispatchMarker' | 'log'>
+): string[] {
+  if (!deps.writeDispatchMarker) return [];
+  if (!isCommittingAgent(subagentType)) return [];
+
+  try {
+    const outcome = deps.writeDispatchMarker(subagentType, branch);
+
+    if (outcome.status === 'written') {
+      deps.log(HOOK, `[S445] boundary marker ${outcome.ref} -> ${outcome.sha}`);
+      if (outcome.pruned.length > 0) {
+        deps.log(HOOK, `[S445] pruned ${outcome.pruned.length} marker(s) over retention cap`);
+      }
+      return [];
+    }
+
+    deps.log(HOOK, `[S445] boundary marker FAILED: ${outcome.reason}`);
+    return [
+      `[BOUNDARY-MARKER][S445] Could not record the pre-dispatch git coordinate for ` +
+        `'${subagentType}' on '${branch}': ${outcome.reason}. The dispatch proceeds (this never ` +
+        `blocks), but there will be NO ref to 'git reset --hard' back to for this agent's work.`,
+    ];
+  } catch (err) {
+    deps.log(HOOK, `[S445] boundary marker threw (fail-open): ${String(err)}`);
+    return [
+      `[BOUNDARY-MARKER][S445] Boundary-marker step threw for '${subagentType}': ${String(err)}. ` +
+        `Dispatch proceeds; no rollback coordinate was recorded.`,
+    ];
+  }
+}
+
 // ─────────────────────────────────────────────────────────────
 // Core logic (exported for testing)
 // ─────────────────────────────────────────────────────────────
@@ -259,6 +322,10 @@ export async function mainWithDeps(deps: HookDeps): Promise<void> {
 
   const warnings = evaluateDispatch({ subagentType, prompt, branch });
 
+  // S445: record the pre-dispatch git coordinate BEFORE the sub-agent spawns.
+  // Committing agents only; never blocks; a failure is surfaced, not swallowed.
+  warnings.push(...markDispatchBoundary(subagentType, branch, deps));
+
   // TD-205: stamp the dispatch-intent marker regardless of whether a warning
   // fires — a dispatch is happening either way, and the marker exists purely
   // to cover the bg-dispatch race for dangling-guard's Stop hook.