@orchestrator-claude/definitions 3.32.1 → 3.33.0

package/hooks/dangling-guard.ts

@@ -12,9 +12,15 @@ import {
   getWorkflowStatus,
   getLastCompletedWorkflow,
   consumeLastCompletedWorkflow,
+  getNextAction,
+  getEffectiveProjectId,
+  listInvocationStatesForWorkflow,
+  isInvocationStateStale,
+  hasFreshDispatchIntent,
   outputBlock,
   postTelemetry,
   type TelemetryPayload,
+  type InvocationStatePayload,
 } from './lib/api-client.js';
 import {
   parseJsonlSession,
@@ -116,6 +122,191 @@ async function emitFinopsTelemetry(
   }
 }
 
+// ---------------------------------------------------------------------------
+// TD-203: async-aware + cwd-scoped block-decision (pure, unit-testable)
+// ---------------------------------------------------------------------------
+
+export type DanglingAction = 'allow' | 'block' | 'info-allow';
+
+export interface DanglingDecision {
+  action: DanglingAction;
+  reason: string;
+}
+
+/** Aggregated signal from listInvocationStatesForWorkflow() + isInvocationStateStale(). */
+export type AgentInvocationSignal = 'fresh' | 'stale' | 'none';
+
+export interface DanglingWorkflowInput {
+  id: string;
+  status: string;
+  phase: string;
+  /**
+   * TD-203 Class-B cwd-scope (TD-204): the workflow's OWN project, when the
+   * API surfaces it.
+   *
+   * VERIFIED (S365, Verify-Before-Assert): WorkflowStatus (api-client.ts)
+   * currently has NO projectId field. This is NOT an unaddressed gap — GET
+   * /api/v1/workflows (list) and GET /api/v1/workflows/:id/status are
+   * ALREADY server-side scoped by the X-Project-ID header sent on every
+   * apiGet call: WorkflowsController.getAll -> listWorkflows ->
+   * findByProjectId ("RF-002 (TD-183): always scoped via findByProjectId —
+   * never falls back to findAll()"), and WorkflowsController.getStatus ->
+   * row-scoped getStatus(id, projectId) -> 404 on cross-tenant (TD-184
+   * RF-001, Camada 1). Since BOTH calls this hook makes are already
+   * project-scoped server-side, it is structurally impossible, under the
+   * current architecture, for getActiveWorkflow() to return a workflow
+   * belonging to a project other than this hook's own resolved PROJECT_ID —
+   * this field is always undefined in production wiring today.
+   *
+   * This branch is kept (dormant, forward-compatible) and fully
+   * unit-tested via synthetic inputs, so it activates automatically the
+   * moment a projectId passthrough is added to the API surface, without
+   * requiring any further change to this decider.
+   */
+  projectId?: string | null;
+}
+
+export interface DanglingDecisionInput {
+  workflow: DanglingWorkflowInput | null;
+  /** This hook's own resolved project (getEffectiveProjectId()), or null when unresolved. */
+  currentProjectId: string | null;
+  agentInvocationState: AgentInvocationSignal;
+  hasPendingAction: boolean;
+  /**
+   * TD-205 bg-dispatch race: true when a dispatch-intent marker exists for
+   * this workflow AND is still within the short grace window (computed by
+   * `hasFreshDispatchIntent()` in api-client.ts — seconds, NOT the 4h
+   * INVOCATION_STATE_TTL_MS). The marker is stamped SYNCHRONOUSLY by
+   * pre-agent-dispatch.ts at PreToolUse[Agent] — which fires before the
+   * sub-agent spawns / before the turn yields — so it is guaranteed present
+   * even when a background dispatch + immediate yield lets this Stop hook
+   * race ahead of subagent-start.ts's async startInvocation()+
+   * writeInvocationState(). Optional (defaults to false) so pre-existing
+   * callers/tests that predate TD-205 are unaffected.
+   */
+  recentlyDispatchedWithinGraceWindow?: boolean;
+}
+
+const ACTIVE_WORKFLOW_STATUSES = ['in_progress', 'awaiting_agent', 'awaiting_approval'];
+
+/**
+ * Pure decision function for the dangling-guard Stop hook (TD-203).
+ *
+ * Evaluates precedence rules 2-8 top-down, first match wins (rule 1 — the
+ * stop_hook_active loop guard — is handled in main() before this is called,
+ * unchanged from the pre-TD-203 behavior). Takes only injected inputs — no
+ * fs/API calls — so every branch is independently testable and
+ * deterministic.
+ */
+export function decideDanglingAction(input: DanglingDecisionInput): DanglingDecision {
+  const {
+    workflow,
+    currentProjectId,
+    agentInvocationState,
+    hasPendingAction,
+    recentlyDispatchedWithinGraceWindow = false,
+  } = input;
+
+  // Rule 2: no active workflow -> allow
+  if (!workflow) {
+    return { action: 'allow', reason: 'No active workflow' };
+  }
+
+  // Rule 3: Class-B cwd-scope (TD-204) — the workflow belongs to a
+  // DIFFERENT project than this session's resolved project -> info-allow
+  // (empty domain, never a bypass; see DanglingWorkflowInput.projectId doc).
+  if (
+    workflow.projectId != null &&
+    currentProjectId != null &&
+    workflow.projectId !== currentProjectId
+  ) {
+    return {
+      action: 'info-allow',
+      reason: `Workflow ${workflow.id} belongs to project ${workflow.projectId}, not this session's project (${currentProjectId}) — empty domain, no-op (Class-B cwd-scope, TD-204)`,
+    };
+  }
+
+  // Rule 4: workflow status not in the active set -> allow
+  if (!ACTIVE_WORKFLOW_STATUSES.includes(workflow.status)) {
+    return {
+      action: 'allow',
+      reason: `Workflow ${workflow.id} status ${workflow.status} is not active`,
+    };
+  }
+
+  // Rule 5: a fresh in-session sub-agent invocation is in-flight -> info-allow.
+  // Re-invocation on agent completion advances the workflow — no abandonment.
+  if (agentInvocationState === 'fresh') {
+    return {
+      action: 'info-allow',
+      reason: `Workflow ${workflow.id} active, awaiting agent completion (fresh invocation signal); allowing stop, will resume on re-invocation`,
+    };
+  }
+
+  // Rule 6 (TD-205): the invocation-state signal is 'none' (subagent-start.ts
+  // has not yet written its file) BUT a dispatch-intent marker is still fresh
+  // -> info-allow. This is the bg-dispatch-race fix: pre-agent-dispatch.ts
+  // stamps the marker SYNCHRONOUSLY at PreToolUse[Agent] (fires before the
+  // sub-agent spawns / before the turn yields), so it is guaranteed present
+  // even when a background dispatch + immediate yield lets this Stop hook
+  // race ahead of subagent-start.ts's async write. Scoped strictly to 'none'
+  // — a 'stale' signal (rule 7 below) always takes precedence over any
+  // dispatch-intent, and the grace window is short (seconds, computed by
+  // hasFreshDispatchIntent()) so a genuinely-dead agent whose marker outlives
+  // the window still falls through to rule 9 (safety net intact — the window
+  // never becomes a permanent hole).
+  if (agentInvocationState === 'none' && recentlyDispatchedWithinGraceWindow) {
+    return {
+      action: 'info-allow',
+      reason: `Workflow ${workflow.id} active, no invocation-state file yet but a fresh dispatch-intent marker exists (bg-dispatch race, TD-205); allowing stop, will resume once subagent-start.ts lands or on the next Stop`,
+    };
+  }
+
+  // Rule 7: the ONLY "alive" signal is a STALE invocation (agent crashed) ->
+  // block. Safety net: without this fallback, async-awareness (rule 5)
+  // becomes a hole that lets a dead agent hold the workflow dangling forever.
+  if (agentInvocationState === 'stale') {
+    return {
+      action: 'block',
+      reason: `[DANGLING-GUARD] Workflow ${workflow.id} has a STALE agent invocation (agent likely crashed/died) and is still ${workflow.status}. You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`,
+    };
+  }
+
+  // Rule 8: the workflow is explicitly waiting on a human (a pending action
+  // is parked, or the phase gate itself is awaiting_approval) -> info-allow.
+  // Ending the session here is expected; the human will resume.
+  if (hasPendingAction || workflow.status === 'awaiting_approval') {
+    return {
+      action: 'info-allow',
+      reason: `Workflow ${workflow.id} active, awaiting human (${hasPendingAction ? 'pending action parked' : 'awaiting_approval'}); allowing stop, will resume on re-invocation`,
+    };
+  }
+
+  // Rule 9: genuine dangling — active in THIS project, no fresh agent, not a
+  // human-wait. This is the case the guard exists for.
+  return {
+    action: 'block',
+    reason: `[DANGLING-GUARD] Workflow ${workflow.id} is still ${workflow.status} (phase: ${workflow.phase}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`,
+  };
+}
+
+/**
+ * Aggregates raw invocation-state payloads (from listInvocationStatesForWorkflow)
+ * into the AgentInvocationSignal consumed by decideDanglingAction. ANY fresh
+ * invocation wins over a stale one (a live agent legitimizes the wait even if
+ * a stale file left behind by a different, earlier crashed agent also exists
+ * for the same workflow). Reuses isInvocationStateStale's default TTL
+ * (INVOCATION_STATE_TTL_MS, 4h) — the SAME staleness definition subagent-stop.ts
+ * already uses for its own zombie-completion safety net on the identical
+ * state files, so both hooks agree on when an invocation record is dead.
+ */
+export function summarizeAgentInvocations(
+  invocations: InvocationStatePayload[]
+): AgentInvocationSignal {
+  if (invocations.length === 0) return 'none';
+  return invocations.some((inv) => !isInvocationStateStale(inv)) ? 'fresh' : 'stale';
+}
+
 async function main(): Promise<void> {
   const stdin = await readStdin();
   log(HOOK, `Stop hook triggered — stdin keys: [${Object.keys(stdin).join(', ')}]`);
@@ -176,12 +367,38 @@ async function main(): Promise<void> {
 
   log(HOOK, `workflow=${workflow.id} status=${wfStatus} phase=${phase}`);
 
-  const activeStatuses = ['in_progress', 'awaiting_agent', 'awaiting_approval'];
-  if (activeStatuses.includes(wfStatus)) {
-    log(HOOK, 'BLOCK stop (workflow still active)');
-    outputBlock(
-      `[DANGLING-GUARD] Workflow ${workflow.id} is still ${wfStatus} (phase: ${phase}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`
-    );
+  // TD-203: gather async-awareness + cwd-scope signals, then delegate the
+  // block/allow/info-allow decision to the pure decider.
+  const invocations = listInvocationStatesForWorkflow(workflow.id);
+  const agentInvocationState = summarizeAgentInvocations(invocations);
+  // TD-205: bg-dispatch race signal — a dispatch-intent marker stamped
+  // synchronously by pre-agent-dispatch.ts, still within its short grace
+  // window (api-client.ts's DISPATCH_INTENT_GRACE_WINDOW_MS).
+  const recentlyDispatchedWithinGraceWindow = hasFreshDispatchIntent(workflow.id);
+  const nextAction = await getNextAction(workflow.id);
+  const hasPendingAction = nextAction?.hasAction === true;
+  const currentProjectId = getEffectiveProjectId() || null;
+
+  const decision = decideDanglingAction({
+    // workflow.projectId intentionally omitted (undefined) — see
+    // DanglingWorkflowInput.projectId doc: not yet surfaced by the API,
+    // already covered transitively by server-side X-Project-ID scoping.
+    workflow: { id: workflow.id, status: wfStatus, phase },
+    currentProjectId,
+    agentInvocationState,
+    hasPendingAction,
+    recentlyDispatchedWithinGraceWindow,
+  });
+
+  log(HOOK, `decision=${decision.action} — ${decision.reason}`);
+
+  if (decision.action === 'block') {
+    outputBlock(decision.reason);
+    return;
+  }
+
+  if (decision.action === 'info-allow') {
+    console.error(`[DANGLING-GUARD] ${decision.reason}`);
     return;
   }