@orchestrator-claude/definitions 3.32.1 → 3.33.0

package/hooks/lib/api-client.ts

@@ -3,9 +3,10 @@
  * Replaces orch-helpers.sh: typed, async/await, zero `node -e` hacks.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync } from 'node:fs';
+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);
@@ -20,13 +21,137 @@ mkdirSync(STATE_DIR, { recursive: true });
 
 // 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
+// `system` tier account (level 4, ABOVE admin) rather than admin — the
+// env-override chain is preserved verbatim so an explicit
+// ORCHESTRATOR_ADMIN_EMAIL/ORCHESTRATOR_AUTH_EMAIL still wins.
 const AUTH_EMAIL =
   process.env.ORCHESTRATOR_ADMIN_EMAIL ||
   process.env.ORCHESTRATOR_AUTH_EMAIL ||
-  'admin@orchestrator.local';
+  'system@orchestrator.local';
 const AUTH_PASSWORD =
-  process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || 'admin123';
-const PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || '';
+  process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || 'system123';
+// Mutable (not const): RFC-040 Operator Multi-Project, Slice 5 (C5) lazily
+// resolves this once per process when the env var is absent — see
+// ensureProjectIdResolved() below.
+let PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || '';
+
+// --- Project Root / Identity Resolution (RFC-040 Operator Multi-Project, C5) ---
+
+/**
+ * Resolves the project root for hook file-system access by delegating to the
+ * zero-dependency `resolveProjectRoot` primitive (RFC-040 C1): walks up from
+ * `cwd` for the nearest ancestor holding a `.orchestrator` sentinel. Returns
+ * `null` — never throws — when no ancestor up to the filesystem root has the
+ * sentinel (unregistered cwd).
+ *
+ * Deliberately has NO `__dirname` fallback: falling back to the
+ * Orchestrator's own repo root would leak this project's vault
+ * (.claude/agents, project-guidelines/, agent-memory) into an unregistered
+ * project's session. Exported as a thin, directly-testable wrapper so
+ * session-start.ts, subagent-stop.ts and workflow-guard.ts share one
+ * resolution boundary.
+ */
+export function resolveHookProjectRoot(cwd: string): string | null {
+  return resolveProjectRoot(cwd);
+}
+
+/**
+ * Resolves the `.claude/agent-memory` base directory for the CURRENT hook
+ * invocation: under the RESOLVED project root when the cwd is registered,
+ * falling back to `cwd` itself when unresolved (preserves prior behaviour —
+ * this fallback is intentionally different from resolveHookProjectRoot's
+ * no-fallback contract, since callers here need *some* writable directory
+ * regardless of registration state).
+ */
+export function resolveAgentMemoryBaseDir(cwd: string): string {
+  return join(resolveHookProjectRoot(cwd) ?? cwd, '.claude', 'agent-memory');
+}
+
+/** Once-per-process guard so a failed/empty resolution is not retried on every getToken() call. */
+let projectIdResolutionAttempted = false;
+
+/**
+ * Best-effort, once-per-process resolution of PROJECT_ID when it was not
+ * supplied via the ORCHESTRATOR_PROJECT_ID env var (RFC-040 Operator
+ * Multi-Project, Slice 5/C5). Walks up from `process.cwd()` for the
+ * `.orchestrator` sentinel, then resolves the projectId via
+ * GET /api/v1/projects/resolve using the already-authenticated Bearer
+ * token (the endpoint is excluded from X-Project-ID validation —
+ * project-context.plugin.ts EXCLUDED_ROUTES includes '/api/v1/projects').
+ *
+ * Fail-open: any failure (no sentinel found, rootPath unregistered, network
+ * error) leaves PROJECT_ID unchanged ('') and is logged, never thrown —
+ * callers proceed with an empty X-Project-ID header exactly as before this
+ * change.
+ */
+async function ensureProjectIdResolved(token: string): Promise<void> {
+  if (PROJECT_ID || projectIdResolutionAttempted) return;
+  projectIdResolutionAttempted = true;
+
+  try {
+    const rootPath = resolveHookProjectRoot(process.cwd());
+    if (rootPath === null) {
+      log(
+        'API-CLIENT',
+        'ensureProjectIdResolved: cwd not registered (.orchestrator sentinel not found) — skipping'
+      );
+      return;
+    }
+
+    const resolved = await resolveProjectIdByPath(rootPath, token);
+    if (resolved) {
+      PROJECT_ID = resolved;
+      log(
+        'API-CLIENT',
+        `ensureProjectIdResolved: resolved projectId=${resolved} rootPath=${rootPath}`
+      );
+    } else {
+      log(
+        'API-CLIENT',
+        `ensureProjectIdResolved: rootPath=${rootPath} not registered to any project — skipping`
+      );
+    }
+  } catch (err) {
+    log(
+      'API-CLIENT',
+      `ensureProjectIdResolved: unexpected failure — ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+/**
+ * Returns the current in-memory PROJECT_ID (env value, or the RFC-040 C5
+ * lazily-resolved value once a prior getToken() call has resolved it).
+ * Sync getter — never triggers resolution itself.
+ */
+export function getEffectiveProjectId(): string {
+  return PROJECT_ID;
+}
+
+/**
+ * Overwrites the current in-memory PROJECT_ID with an explicitly-resolved
+ * value (RFC-040 TD-206, S372). Used by session-start.ts to feed the
+ * precedence-resolved SessionProjectBinding (env-override > selection >
+ * cwd-hint, TD-204 ⑥-c) back into the api-client's own scoping BEFORE
+ * getActiveWorkflow()/getNextAction() run, so their `X-Project-ID` header
+ * reflects the SAME projectId the [ORCHESTRATOR-DATA] line surfaces —
+ * closing the display-vs-scoping gap proven empirically in S371 Case-2
+ * (a selection-bound session showed the right `project=` but queried the
+ * wrong workflow, see AC-C9-4-selection-model-acceptance.md §5).
+ *
+ * Deliberately a raw assignment, not a "resolve" — the caller has already
+ * done precedence resolution; this function trusts the input and never
+ * touches the network itself. Passing '' is valid (mirrors the `none`
+ * binding source). Because ensureProjectIdResolved's guard is
+ * `if (PROJECT_ID || projectIdResolutionAttempted) return;`, setting a
+ * non-empty value here also transitively prevents any LATER
+ * ensureProjectIdResolved call (e.g. from a subsequent getToken()) from
+ * clobbering it with a fresh cwd-based resolution.
+ */
+export function setEffectiveProjectId(projectId: string): void {
+  PROJECT_ID = projectId;
+}
 
 // --- Types ---
 
@@ -86,8 +211,14 @@ function getCachedToken(): string | null {
 }
 
 async function login(): Promise<string | null> {
-  if (!PROJECT_ID) return null;
-
+  // RFC-040 Operator Multi-Project, Slice 5 (C5): the pre-C5 guard used to
+  // bail out here when PROJECT_ID was unset. Relaxed deliberately —
+  // /api/v1/auth/login is a PUBLIC route (auth.middleware.ts PUBLIC_ROUTES)
+  // AND is excluded from X-Project-ID validation
+  // (project-context.plugin.ts EXCLUDED_ROUTES includes '/api/v1/auth') —
+  // the server ignores X-Project-ID on this route entirely, so login can
+  // always proceed and PROJECT_ID is resolved afterwards, once a Bearer
+  // token is available (see ensureProjectIdResolved, called from getToken()).
   try {
     const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
       method: 'POST',
@@ -115,7 +246,17 @@ async function login(): Promise<string | null> {
 }
 
 export async function getToken(): Promise<string | null> {
-  return getCachedToken() || (await login());
+  const token = getCachedToken() || (await login());
+  if (token) {
+    // RFC-040 C5: single funnel point — every caller (getActiveWorkflow,
+    // getNextAction, allocateSessionNumber, startInvocation, ...) obtains
+    // its token via getToken(), so resolving PROJECT_ID here (once,
+    // memoized) applies it to ALL subsequent project-scoped calls,
+    // including any later re-invocation of login() itself (login() reads
+    // the module-level PROJECT_ID at call time, not a stale closure).
+    await ensureProjectIdResolved(token);
+  }
+  return token;
 }
 
 // --- API Helpers ---
@@ -160,6 +301,59 @@ async function apiPost<T>(
   }
 }
 
+/**
+ * Resolves a projectId given an absolute root path via
+ * GET /api/v1/projects/resolve (excluded from X-Project-ID validation —
+ * project-agnostic by design, requires only a Bearer token). Fail-open:
+ * returns null on 404 (unregistered rootPath), network error, or any other
+ * non-2xx response — reuses apiGet's fail-open contract, never throws.
+ */
+export async function resolveProjectIdByPath(
+  rootPath: string,
+  token: string
+): Promise<string | null> {
+  const resp = await apiGet<{ projectId: string }>(
+    `/api/v1/projects/resolve?rootPath=${encodeURIComponent(rootPath)}`,
+    token
+  );
+  return resp?.projectId ?? null;
+}
+
+/** Minimal shape of a registered project needed by ⑤-B / ⑤-C consumers. */
+export interface RegisteredProjectSummary {
+  id: string;
+  name: string;
+  rootPath: string;
+}
+
+/**
+ * Lists every registered project (Postgres SoT) via GET /api/v1/projects —
+ * the SAME `ProjectRegistryService` domain path ResolveProjectByPathUseCase
+ * (C2 `/resolve`) and ListProjectsUseCase both read from (RFC-040 TD-204
+ * ⑤-B). Two consumers:
+ *   - additional-directories-sync.ts (⑤-B): needs every registered rootPath
+ *     to union-merge into settings.json's additionalDirectories.
+ *   - session-start.ts (⑤-C): needs {id, name} pairs to list as
+ *     AskUserQuestion options in the 2-phase selection prompt.
+ *
+ * Fail-open (mirrors every other api-client query): returns [] on missing
+ * token, non-2xx, network error, or a non-array response body — never
+ * throws, never blocks the caller.
+ */
+export async function listRegisteredProjects(): Promise<RegisteredProjectSummary[]> {
+  const token = await getToken();
+  if (!token) return [];
+
+  const resp = await apiGet<{ id: string; name: string; rootPath: string }[]>(
+    '/api/v1/projects',
+    token
+  );
+
+  if (!Array.isArray(resp)) return [];
+
+  return resp.map((p) => ({ id: p.id, name: p.name, rootPath: p.rootPath }));
+}
+
 // --- Workflow Queries ---
 
 export async function getActiveWorkflow(): Promise<WorkflowStatus | null> {
@@ -402,6 +596,165 @@ export function consumeInvocationState(workflowId: string, agentType: string): b
   }
 }
 
+/**
+ * Lists all live (not-yet-consumed) invocation state payloads recorded for a
+ * given workflowId, across every agentType file (TD-203).
+ *
+ * subagent-start.ts writes one state file per <workflowId>-<agentType> pair
+ * (buildInvocationStatePath). A caller that does not know a-priori which
+ * agentType(s) were dispatched — e.g. dangling-guard.ts's Stop hook, which
+ * fires on the MAIN session's turn end and has no direct knowledge of which
+ * background sub-agent(s) are in-flight for the active workflow — needs to
+ * discover ALL live invocations for the workflow, not just one agentType.
+ *
+ * workflowId is a UUID (fixed 36-char format), so no workflowId is ever a
+ * string-prefix of another — the `${workflowId}-` prefix match is
+ * unambiguous, matching buildInvocationStatePath's own naming convention.
+ *
+ * Fail-open: returns [] when the invocations directory does not exist (no
+ * invocation has ever been recorded) or cannot be read. Individual malformed
+ * files are skipped (not thrown), matching readInvocationState's contract.
+ */
+export function listInvocationStatesForWorkflow(workflowId: string): InvocationStatePayload[] {
+  let files: string[];
+  try {
+    files = readdirSync(INVOCATIONS_DIR);
+  } catch {
+    return [];
+  }
+
+  const prefix = `${workflowId}-`;
+  const results: InvocationStatePayload[] = [];
+  for (const file of files) {
+    if (!file.startsWith(prefix) || !file.endsWith('.json')) continue;
+    try {
+      const raw = readFileSync(join(INVOCATIONS_DIR, file), 'utf-8');
+      const data = JSON.parse(raw) as Record<string, unknown>;
+      if (
+        typeof data.invocationId === 'string' &&
+        typeof data.startedAt === 'string' &&
+        typeof data.agentType === 'string' &&
+        typeof data.workflowId === 'string'
+      ) {
+        results.push({
+          invocationId: data.invocationId,
+          startedAt: data.startedAt,
+          agentType: data.agentType,
+          workflowId: data.workflowId,
+        });
+      }
+    } catch {
+      // skip malformed file — fail-open, matches readInvocationState contract
+    }
+  }
+  return results;
+}
+
+// --- Dispatch Intent (TD-205 bg-dispatch race) ---
+
+/** Payload written to the per-workflow dispatch-intent marker file. */
+export interface DispatchIntentPayload {
+  workflowId: string;
+  stampedAt: string;
+}
+
+const DISPATCH_INTENT_DIR = join(STATE_DIR, 'dispatch-intent');
+
+/**
+ * Grace window for a dispatch-intent marker: SECONDS, not the 4h
+ * INVOCATION_STATE_TTL_MS staleness definition used elsewhere. Sized to
+ * comfortably exceed subagent-start.ts's own SubagentStart hook timeout
+ * (10_000ms, settings.json) plus scheduling slack between the sub-agent
+ * spawning and that hook actually running, while staying far short of a
+ * genuinely-dangling session (minutes/hours). A marker older than this is
+ * NOT treated as covering the race — it falls through to dangling-guard's
+ * rule 9 zombie safety net, so this window can never become a permanent
+ * hole (TD-205).
+ */
+const DISPATCH_INTENT_GRACE_WINDOW_MS = 30_000;
+
+/** Returns the per-workflow dispatch-intent marker path: <stateDir>/dispatch-intent/<workflowId>.json */
+export function buildDispatchIntentPath(stateDir: string, workflowId: string): string {
+  return join(stateDir, 'dispatch-intent', `${workflowId}.json`);
+}
+
+/**
+ * Stamps a dispatch-intent marker for workflowId. Called SYNCHRONOUSLY by
+ * pre-agent-dispatch.ts (PreToolUse[Agent] — fires before the sub-agent
+ * spawns / before the turn yields) so the marker is guaranteed to exist by
+ * the time a background-dispatch Stop hook could race ahead of
+ * subagent-start.ts's async startInvocation()+writeInvocationState().
+ * Fail-open: returns false on any filesystem error.
+ */
+export function writeDispatchIntent(workflowId: string): boolean {
+  try {
+    mkdirSync(DISPATCH_INTENT_DIR, { recursive: true });
+    const path = buildDispatchIntentPath(STATE_DIR, workflowId);
+    const payload: DispatchIntentPayload = { workflowId, stampedAt: new Date().toISOString() };
+    writeFileSync(path, JSON.stringify(payload), 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads the dispatch-intent marker for workflowId. Returns null when absent,
+ * malformed, or unreadable (fail-open).
+ */
+export function readDispatchIntent(workflowId: string): DispatchIntentPayload | null {
+  try {
+    const path = buildDispatchIntentPath(STATE_DIR, workflowId);
+    const raw = readFileSync(path, 'utf-8');
+    const data = JSON.parse(raw) as Record<string, unknown>;
+    if (typeof data.workflowId !== 'string' || typeof data.stampedAt !== 'string') {
+      return null;
+    }
+    return { workflowId: data.workflowId, stampedAt: data.stampedAt };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns true when workflowId has a dispatch-intent marker stamped within
+ * the short grace window (TD-205). This is the bg-dispatch-race signal
+ * consumed by dangling-guard.ts's rule 6 — deliberately bounded (seconds,
+ * NOT the 4h INVOCATION_STATE_TTL_MS) so a genuinely-dead agent whose marker
+ * outlives the window still falls through to the rule-9 safety net.
+ * Malformed/missing stampedAt is treated as NOT fresh (fail-safe — same
+ * posture as isInvocationStateStale's malformed-timestamp handling).
+ */
+export function hasFreshDispatchIntent(
+  workflowId: string,
+  nowMs: number = Date.now(),
+  graceWindowMs: number = DISPATCH_INTENT_GRACE_WINDOW_MS
+): boolean {
+  const marker = readDispatchIntent(workflowId);
+  if (!marker) return false;
+  const stampedAtMs = new Date(marker.stampedAt).getTime();
+  if (isNaN(stampedAtMs)) return false;
+  return nowMs - stampedAtMs <= graceWindowMs;
+}
+
+/**
+ * Deletes the per-workflow dispatch-intent marker file. Not currently called
+ * from production wiring (the grace window is short enough to self-expire
+ * without explicit clearing — see DISPATCH_INTENT_GRACE_WINDOW_MS doc);
+ * exported for symmetry with consumeInvocationState and for test cleanup.
+ * Returns true if deleted, false if already gone.
+ */
+export function consumeDispatchIntent(workflowId: string): boolean {
+  try {
+    const path = buildDispatchIntentPath(STATE_DIR, workflowId);
+    readFileSync(path); // throws if missing — fast existence check
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Start tracking an agent invocation.
  * Returns the invocationId string on success, or null on any failure (fail-open).
@@ -502,6 +855,34 @@ export async function registerCheckpoint(
   });
 }
 
+// --- Session Allocation (RFC-040 Operator Multi-Project, Slice 2C/C9, S358) ---
+
+/** Response shape from POST /api/v1/sessions/allocate */
+export interface AllocateSessionResult {
+  number: number;
+  sessionId: string;
+}
+
+/**
+ * Allocates a new, globally-numbered session for a project via
+ * POST /api/v1/sessions/allocate. Requires the hook's `system`-tier
+ * identity (RFC-040 ADR-002, TASK-RBAC-02) — an `admin` identity would be
+ * rejected (403) by the endpoint's rbacSystem guard.
+ *
+ * Fail-open, mirrors registerCheckpoint's shape: returns null on any
+ * failure (no token, network error, non-2xx response) so the hook never
+ * blocks the session on this call.
+ */
+export async function allocateSessionNumber(
+  projectId: string
+): Promise<AllocateSessionResult | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiPost<AllocateSessionResult>(`/api/v1/sessions/allocate`, token, {
+    projectId,
+  });
+}
+
 // --- Telemetry ---
 
 /**

package/hooks/lib/session-selection.ts

@@ -0,0 +1,81 @@
+/**
+ * session-selection.ts — RFC-040 TD-204 ⑤-C.
+ *
+ * Persists a session's explicit project SELECTION — the dormant precedence
+ * tier in session-start.ts's `resolveSessionProjectBinding` (TD-204 ⑥-c):
+ *
+ *   env-override (pin) > selection > cwd-hint > none
+ *
+ * Phase 1 of the 2-phase session-start flow (feature-flagged, default OFF)
+ * prompts the operator to choose a project when no binding resolves. Once
+ * chosen, the choice is written here, keyed by Claude Code's `session_id`,
+ * so a later SessionStart re-fire (matcher `startup|resume`) can read it
+ * back as the `selection` tier and inject the scoped [ORCHESTRATOR-DATA]
+ * ("phase 2"). NOTE: the interactive consumer that CALLS
+ * writeSessionSelection() after the operator answers (an MCP tool or
+ * slash command) is explicitly OUT of Phase I scope — see the
+ * implementation report. This module ships the read/write primitives and
+ * session-start.ts's READ-side wiring only.
+ *
+ * Class C (context/telemetry) hook classification (TD-204 §31-34): every
+ * function here degrades benignly — never throws, fails open to
+ * `undefined` on any error. No hardcoded `~/.claude` path: `stateDir` is
+ * always an explicit parameter (installer-compatible, same discipline as
+ * additional-directories-sync.ts).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface SessionSelectionRecord {
+  projectId: string;
+  selectedAt: string;
+}
+
+/** Sanitizes sessionId into a safe file-name fragment — no path traversal. */
+function selectionFilePath(stateDir: string, sessionId: string): string {
+  const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return join(stateDir, `session-selection-${safeId}.json`);
+}
+
+/**
+ * Reads the persisted project selection for `sessionId`, or `undefined`
+ * when none exists / the file is malformed / any fs error occurs (Class C
+ * benign degrade — never throws).
+ */
+export function readSessionSelection(stateDir: string, sessionId: string): string | undefined {
+  if (sessionId === '') return undefined;
+  try {
+    const filePath = selectionFilePath(stateDir, sessionId);
+    if (!existsSync(filePath)) return undefined;
+    const raw = readFileSync(filePath, 'utf-8');
+    const record = JSON.parse(raw) as Partial<SessionSelectionRecord>;
+    return typeof record.projectId === 'string' && record.projectId !== ''
+      ? record.projectId
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persists `projectId` as the selection for `sessionId`. No-op (never
+ * throws) when either argument is empty, or on any fs failure (Class C
+ * benign degrade — a failed selection write must never crash the caller
+ * that just answered an AskUserQuestion prompt).
+ */
+export function writeSessionSelection(
+  stateDir: string,
+  sessionId: string,
+  projectId: string
+): void {
+  if (sessionId === '' || projectId === '') return;
+  try {
+    mkdirSync(stateDir, { recursive: true });
+    const filePath = selectionFilePath(stateDir, sessionId);
+    const record: SessionSelectionRecord = { projectId, selectedAt: new Date().toISOString() };
+    writeFileSync(filePath, JSON.stringify(record, null, 2), 'utf-8');
+  } catch {
+    // Class C benign degrade — never throws.
+  }
+}