@orchestrator-claude/definitions 3.36.0 → 3.37.1

package/hooks/lib/dispatch-marker.ts

@@ -0,0 +1,214 @@
+/**
+ * dispatch-marker.ts — boundary marker per git ref (S445, RFC-042).
+ *
+ * WHAT THIS IS. At the instant a committing agent is dispatched, record WHERE
+ * HEAD WAS, as a git ref pointing at the full 40-hex sha. That is the whole
+ * feature: a COORDINATE for "the state before this agent started".
+ *
+ * WHAT THIS IS NOT, deliberately. It does not restore anything. RFC-042 settled
+ * that a checkpoint is an AUDIT MARK (D1) and is EXPLICIT (D2); asked whether a
+ * restore path was wanted, the answer was that rollback has been needed only a
+ * few times and plain git handled it. So rollback stays plain git:
+ *
+ *     git reset --hard <ref>
+ *
+ * No restore code lives here. An unused restore path is precisely how the
+ * existing checkpoint subsystem accumulated four independent breaks (see the
+ * checkpoint-protocol skill) — a coordinate that git can consume cannot rot the
+ * same way, because git is the thing that consumes it.
+ *
+ * IT DOES NOT CREATE A COMMIT AND DOES NOT TOUCH THE WORKING TREE. A ref is git
+ * metadata: writing one leaves `git status` byte-identical. That is what lets
+ * this coexist with the S445 rule that ordinary machine operation must never
+ * write a git-tracked file.
+ *
+ * THE COLON TRAP (the reason sanitization is a requirement, not a nicety).
+ * Under plugin scope agents are named `orchestrator:implementer`. A git ref name
+ * may not contain a colon (nor space, tilde, caret, question mark, asterisk,
+ * open bracket, backslash, or a double dot). Passing a raw agent name through
+ * would make `update-ref` fail — and since the calling hook is fail-open, it
+ * would fail SILENTLY, leaving the whole feature a green no-op for exactly the
+ * agents that can commit. Hence sanitizeRefComponent, and hence a test that
+ * validates the output with git's own `check-ref-format`.
+ *
+ * RETENTION. Refs are GC roots, so markers would accumulate forever and we would
+ * have traded collectable orphan objects for uncollectable refs. Hence a cap.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Namespace for dispatch boundary markers. Verified free before adoption:
+ * `git for-each-ref refs/orchestrator/` returned 0 refs. The 6 pre-existing
+ * `orchestrator/*` TAGS live under `refs/tags/orchestrator/`, which is a
+ * DIFFERENT namespace — these markers do not collide with them, and are not
+ * tags (a tag is a published, human-meaningful mark; this is machine bookkeeping
+ * with a retention cap).
+ */
+export const DISPATCH_MARKER_REF_PREFIX = 'refs/orchestrator/dispatch';
+
+/**
+ * Maximum markers retained PER KEY (per branch — see writeDispatchBoundaryMarker
+ * for why branch and not workflow). Oldest are pruned once the cap is exceeded.
+ *
+ * WHY A CAP EXISTS AT ALL: a git ref is a GC ROOT. Every marker pins the commit
+ * it points at, so without pruning these would accumulate without bound and
+ * would keep otherwise-unreachable objects alive forever — trading collectable
+ * orphans for uncollectable refs, which is a worse deal than the problem being
+ * solved. 20 is deliberately small: markers are a rollback coordinate for RECENT
+ * work, and a coordinate 20 dispatches old has been superseded by ordinary
+ * commits and branches. Raise it only against a measured need.
+ */
+export const MAX_DISPATCH_MARKERS_PER_KEY = 20;
+
+/** Fallback when an input sanitizes down to nothing. */
+const EMPTY_COMPONENT_PLACEHOLDER = 'unknown';
+
+/**
+ * Reduces arbitrary text to a single ref-name component that git accepts.
+ *
+ * The allowlist is deliberately narrower than git's own rules rather than a
+ * blocklist of forbidden characters. Permitting only [A-Za-z0-9_-] makes whole
+ * FAMILIES of git's restrictions unreachable instead of individually handled:
+ * dropping '.' rules out a leading dot, a trailing dot, a '..' sequence and a
+ * '.lock' suffix at once; dropping '@' and '{' rules out '@{' and the lone '@'.
+ * A blocklist would have to enumerate each rule correctly and stay correct as
+ * git evolves; this cannot fail open by omission.
+ */
+export function sanitizeRefComponent(raw: string): string {
+  const cleaned = (raw || '')
+    .replace(/[^A-Za-z0-9_-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  return cleaned || EMPTY_COMPONENT_PLACEHOLDER;
+}
+
+/**
+ * Compact UTC stamp, e.g. `20260804T142439123Z`. Colons are stripped because a
+ * plain ISO-8601 string (`2026-08-04T14:24:39.123Z`) is an INVALID ref name for
+ * the very same reason the agent name is. Fixed width and zero-padded, so
+ * lexicographic ref order equals chronological order — which is what makes
+ * "prune the oldest" a plain sort.
+ */
+export function formatMarkerStamp(d: Date): string {
+  return d.toISOString().replace(/[-:.]/g, '');
+}
+
+/** `refs/orchestrator/dispatch/<branch>/<stamp>-<agent>`. */
+export function buildMarkerRefName(branch: string, agent: string, stamp: string): string {
+  const branchPart = sanitizeRefComponent(branch);
+  const agentPart = sanitizeRefComponent(agent);
+  const stampPart = sanitizeRefComponent(stamp);
+
+  return `${DISPATCH_MARKER_REF_PREFIX}/${branchPart}/${stampPart}-${agentPart}`;
+}
+
+export type DispatchMarkerOutcome =
+  | { status: 'written'; ref: string; sha: string; pruned: string[] }
+  | { status: 'failed'; reason: string };
+
+export interface DispatchMarkerDeps {
+  /** Runs git and returns stdout. MUST throw on non-zero exit. */
+  runGit: (args: string[]) => string;
+  /** Injectable clock (tests need deterministic, ordered stamps). */
+  now?: () => Date;
+}
+
+/** Production git runner: fixed argv, no shell, so no interpolation surface. */
+export function runGitDefault(args: string[]): string {
+  return execFileSync('git', args, {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+/**
+ * Removes the oldest markers under `prefix` until at most `cap` remain.
+ * Lexicographic ref order is chronological (see formatMarkerStamp).
+ */
+function pruneOldestMarkers(prefix: string, cap: number, deps: DispatchMarkerDeps): string[] {
+  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;
+}
+
+/**
+ * Writes the boundary marker for `agentName` on `branch`.
+ *
+ * RETENTION KEY IS THE BRANCH, NOT THE WORKFLOW — a deliberate substitution,
+ * reported as such. The workflow id is only obtainable here through an async API
+ * call, which would make the marker ABSENT precisely when the system is degraded
+ * (API down) — the opposite of what a rollback coordinate is for. The branch is
+ * already in hand locally and needs no network. It is also the better key on the
+ * merits: `git reset --hard` is a branch-scoped operation, so grouping markers by
+ * branch matches the unit they would be consumed at.
+ *
+ * FAIL-OPEN IN EVERY DIMENSION: git missing, no commits yet, a ref-name that
+ * somehow still fails validation, a broken prune — all return a `failed` outcome.
+ * This function NEVER throws, so it can never block or delay a dispatch. It is
+ * fail-open but NOT silent: it returns the reason, and the caller surfaces it.
+ */
+export function writeDispatchBoundaryMarker(
+  agentName: string,
+  branch: string,
+  deps: DispatchMarkerDeps
+): DispatchMarkerOutcome {
+  let ref = '';
+  try {
+    // An agent name that sanitizes to nothing yields a marker nobody can
+    // attribute — litter that consumes the retention cap rather than a usable
+    // coordinate. NOT a hypothetical guard: a `...-unknown` ref was written into
+    // the real repository during S445's negative-control run, because this hook's
+    // entry module executes on import (top-level `main().catch()`) and therefore
+    // ran with production deps and an empty stdin. The caller gates on
+    // isCommittingAgent, so this never fires in production — it is the backstop
+    // for the paths that bypass that gate.
+    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 ?? (() => new Date()))());
+    ref = buildMarkerRefName(branch, agentName, stamp);
+
+    deps.runGit(['update-ref', ref, sha]);
+
+    // The marker now exists. Pruning is best-effort bookkeeping ON TOP of a
+    // successful write — a prune failure must never downgrade the outcome, or a
+    // full namespace would start reporting failure for markers that were in fact
+    // written.
+    let pruned: string[] = [];
+    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)}` };
+  }
+}

package/hooks/lib/git-checkpoint.ts

@@ -3,7 +3,6 @@
  * Replaces post-phase-checkpoint.sh git logic.
  */
 
-import { execSync } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -24,22 +23,33 @@ function getCompletedPhase(currentPhase: string): string | null {
   return idx > 0 ? (PHASE_ORDER[idx - 1] ?? null) : null;
 }
 
-function exec(cmd: string): string {
-  return execSync(cmd, { cwd: PROJECT_ROOT, encoding: 'utf-8' }).trim();
-}
-
 /**
- * Create a git checkpoint if the phase changed and there are staged changes.
- * Returns the commit hash or null.
+ * Register a checkpoint (PostgreSQL side only) if the phase changed since the
+ * last checkpointed phase.
+ *
+ * TD-257 (S444): this function used to also stage and commit the working
+ * tree (`git add -A` + `git commit --no-verify`, unattended, on every phase
+ * transition). That was DISARMED after measurement — the decision was made
+ * by the user from data, not opinion: 212 such commits by subject over 7
+ * months, 145/212 (68%) pure machine-noise, 42/212 (20%) MIXED (real work
+ * buried alongside noise), one of which (`01c28adf`) deleted 1627 lines
+ * including `EvaluatePhaseGateUseCase.ts` and 3 suites under the message
+ * "Auto-checkpoint after tasks phase" — with zero restores in that window,
+ * and no production caller for `CheckpointManager.restore()` at all. The
+ * separate, deliberate `createCheckpoint` MCP tool (`CheckpointManager.ts`,
+ * `GitOperations.ts`) is UNAFFECTED by this change — it is named, tagged,
+ * and stays. Returns `true` when a checkpoint was registered for a newly
+ * completed phase, `false` otherwise (no completed phase, already
+ * checkpointed, or the registration call failed).
  */
 export async function createCheckpointIfNeeded(
   workflowId: string,
   currentPhase: string
-): Promise<string | null> {
+): Promise<boolean> {
   const completedPhase = getCompletedPhase(currentPhase);
   if (!completedPhase) {
     log('CHECKPOINT', `No completed phase from: ${currentPhase}`);
-    return null;
+    return false;
   }
 
   // Check if already checkpointed
@@ -51,41 +61,28 @@ export async function createCheckpointIfNeeded(
   }
   if (lastPhase === completedPhase) {
     log('CHECKPOINT', `Already checkpointed: ${completedPhase}`);
-    return null;
+    return false;
   }
 
   try {
-    // Stage all changes
-    exec('git add -A');
-
-    // Check if there are staged changes
-    try {
-      exec('git diff --cached --quiet');
-      // No changes
-      log('CHECKPOINT', `No changes for phase: ${completedPhase}`);
-      writeFileSync(LAST_PHASE_FILE, completedPhase);
-      return null;
-    } catch {
-      // Has changes — good, proceed to commit
-    }
-
-    const commitMsg = `[orchestrator] ${completedPhase}: Auto-checkpoint after ${completedPhase} phase`;
-    exec(`git commit -m "${commitMsg}" --no-verify`);
-    const commitHash = exec('git rev-parse HEAD');
-
-    log('CHECKPOINT', `Created: phase=${completedPhase} commit=${commitHash}`);
+    log('CHECKPOINT', `Registering checkpoint for phase: ${completedPhase}`);
 
-    // Register via API
-    await registerCheckpoint(
-      workflowId,
-      `Auto-checkpoint after ${completedPhase} phase`,
-      commitHash
-    );
+    // TD-257: no commit is made anymore, so there is no real hash to report.
+    // registerCheckpoint's `commitHash` parameter is still required by its
+    // signature (out of this task's scope to change — see implementation
+    // report) — '' is the honest value ("no commit exists"), not an invented
+    // placeholder: it mirrors how the separate createCheckpoint MCP tool path
+    // already reports "no commit" as `gitCommit: undefined`
+    // (CreateCheckpointHandler.ts) when there is nothing to point to, and the
+    // field is unused server-side regardless — CreateCheckpointBodySchema
+    // (checkpoints.schemas.ts) has no commitHash field at all, and the route
+    // handler (checkpoints.routes.ts) never reads it off the request body.
+    await registerCheckpoint(workflowId, `Auto-checkpoint after ${completedPhase} phase`, '');
 
     writeFileSync(LAST_PHASE_FILE, completedPhase);
-    return commitHash;
+    return true;
   } catch (err) {
     log('CHECKPOINT', `Error: ${err}`);
-    return null;
+    return false;
   }
 }

package/hooks/lib/observations-helper.ts

@@ -4,11 +4,22 @@
  * Provides types and helper to write observations.yaml files.
  * Used by subagent-stop.ts to record what each sub-agent observed.
  * All functions are fail-open: errors logged to stderr, never thrown.
+ *
+ * TD-214/TD-239 TASK-003 (RF-004): `agent` is normalized via
+ * `normalizeAgentName` BEFORE it is used to build `agentDir`. Under plugin
+ * scope the harness namespaces dispatch names (`orchestrator:reviewer`); in
+ * project scope the same agent arrives bare (`reviewer`). Without this,
+ * the two scopes silently fork into two different observations.yaml
+ * directories for the SAME agent. `data.agent` (the field written INSIDE the
+ * YAML) intentionally keeps the raw, un-normalized input — only the
+ * directory-path use is normalized — so the file still records exactly what
+ * the harness sent, for audit purposes.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { normalizeAgentName } from './api-client.js';
 
 // ─── Types ───────────────────────────────────────────────
 
@@ -47,7 +58,9 @@ export function appendObservation(
   entry: Omit<ObservationEntry, 'promoted'>
 ): void {
   try {
-    const agentDir = join(memoryDir, agent);
+    // TD-214/TD-239 TASK-003: normalize BEFORE building the directory path —
+    // see module doc for why (plugin-scope vs project-scope namespacing).
+    const agentDir = join(memoryDir, normalizeAgentName(agent));
     const filePath = join(agentDir, 'observations.yaml');
 
     // Ensure directory exists

package/hooks/mailbox-listener.mjs

@@ -6,28 +6,80 @@ import {
   readFileSync as readFileSync2,
   unlinkSync as unlinkSync2,
   renameSync,
-  existsSync,
+  existsSync as existsSync2,
   mkdirSync as mkdirSync2,
   writeFileSync as writeFileSync2
 } from "node:fs";
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 import { randomUUID } from "node:crypto";
 
 // hooks/lib/api-client.ts
 import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname(__filename);
-var PROJECT_ROOT = join(__dirname, "..", "..", "..");
-var STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
-var JWT_CACHE = join(STATE_DIR, "jwt-token");
-var DEBUG_LOG = join(STATE_DIR, "hook-debug.log");
+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))) {
+      candidates.push(currentDir);
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      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
+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";
 var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function resolveHookProjectRoot(cwd) {
+  return resolveProjectRoot(cwd);
+}
 function log(prefix, msg) {
   const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
   try {
@@ -37,11 +89,11 @@ function log(prefix, msg) {
   } catch {
   }
 }
-var LAST_COMPLETED_FILE = join(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_FILE = join2(STATE_DIR, "last-completed-workflow.json");
 var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
-var INVOCATIONS_DIR = join(STATE_DIR, "invocations");
+var INVOCATIONS_DIR = join2(STATE_DIR, "invocations");
 var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
-var DISPATCH_INTENT_DIR = join(STATE_DIR, "dispatch-intent");
+var DISPATCH_INTENT_DIR = join2(STATE_DIR, "dispatch-intent");
 function outputContext(hookEvent, context) {
   console.log(
     JSON.stringify({
@@ -82,7 +134,7 @@ function consumeInbox(inboxPath, quarantinePath, paneRole) {
   const consumed = [];
   const errors = [];
   for (const file of files) {
-    const filePath = join2(inboxPath, file);
+    const filePath = join3(inboxPath, file);
     try {
       const raw = readFileSync2(filePath, "utf-8");
       const parsed = JSON.parse(raw);
@@ -101,7 +153,7 @@ function consumeInbox(inboxPath, quarantinePath, paneRole) {
       log(HOOK, `Quarantine: ${file} \u2014 ${errMsg}`);
       try {
         mkdirSync2(quarantinePath, { recursive: true });
-        renameSync(filePath, join2(quarantinePath, file));
+        renameSync(filePath, join3(quarantinePath, file));
       } catch {
       }
     }
@@ -211,7 +263,7 @@ function relaySidecarMessages(consumed, sprintId, paneRole, deps = { readdirSync
         };
         const sidecarAddr = `${sidecar.role}-${String(sidecar.index)}`;
         const targetInbox = `/tmp/${sprintId}/mailbox/${sidecarAddr}/inbox`;
-        const targetPath = join2(targetInbox, `${envelope.id}.json`);
+        const targetPath = join3(targetInbox, `${envelope.id}.json`);
         deps.writeFileSync(targetPath, JSON.stringify(envelope), "utf-8");
         log(HOOK, `Relayed task_complete to ${sidecarAddr}: ${envelope.id}`);
       } catch (err) {
@@ -229,7 +281,7 @@ async function main() {
   }
   const inboxPath = `/tmp/${sprintId}/mailbox/${paneRole}/inbox`;
   const quarantinePath = `/tmp/${sprintId}/mailbox/${paneRole}/quarantine`;
-  if (!existsSync(inboxPath)) {
+  if (!existsSync2(inboxPath)) {
     return;
   }
   let hookEventName;

package/hooks/playwright-output-guard.mjs

@@ -1,38 +1,68 @@
 import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
 
 // hooks/playwright-output-guard.ts
-import { dirname as dirname3, isAbsolute, normalize, resolve } from "node:path";
+import { dirname as dirname2, isAbsolute, normalize, resolve } from "node:path";
 
 // 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";
@@ -95,7 +125,7 @@ var GUIDANCE = 'Playwright Output Guard: screenshots n\xE3o podem cair na raiz d
 function evaluateFilename(filename) {
   if (!filename) return { decision: "allow" };
   const resolved = isAbsolute(filename) ? normalize(filename) : resolve(PROJECT_ROOT2, filename);
-  const dir = dirname3(resolved);
+  const dir = dirname2(resolved);
   if (dir === PROJECT_ROOT2) {
     return { decision: "deny", reason: GUIDANCE };
   }

package/hooks/post-implement.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";