@orchestrator-claude/definitions 3.31.0 → 3.31.2

package/hooks/session-start.ts

@@ -4,93 +4,462 @@
  * Injects workflow status context on session start.
  */
 
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
 import {
   log,
   getActiveWorkflow,
   getNextAction,
   outputContext,
-} from "./lib/api-client.js";
+  getToken,
+} from './lib/api-client.js';
+import {
+  needsRescan,
+  buildCapabilityIndex,
+  writeCapabilitiesToVault,
+  readCapabilitiesFromVault,
+  scanAgentDefinitions,
+  formatCapabilityMatrix,
+  readMemoryIndex,
+  filterRelevantMemories,
+  formatMemoryContext,
+} from './lib/capability-scanner.js';
 
-const HOOK = "SESSION-START";
+const HOOK = 'SESSION-START';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PROJECT_ROOT = join(__dirname, "..", "..");
+const GRAPHRAG_TIMEOUT_MS = 2000;
+const PROJECT_ROOT = join(__dirname, '..', '..');
+
+// ─── Capability Matrix paths (RFC-027 Sprint 2) ─────────
+const HOME = process.env.HOME ?? process.env.USERPROFILE ?? '/home/user';
+const INSTALLED_PLUGINS_PATH = join(HOME, '.claude', 'plugins', 'installed_plugins.json');
+const AGENTS_DIR = join(PROJECT_ROOT, '.claude', 'agents');
+const VAULT_CONFIG_PATH = join(PROJECT_ROOT, 'project-guidelines', '.vault-config.yaml');
+const PROFILES_PATH = join(PROJECT_ROOT, '.claude', 'plugin-profiles.yaml');
+const MEMORY_INDEX_PATH = join(
+  PROJECT_ROOT,
+  '.claude',
+  'agent-memory',
+  'orchestrator',
+  'memory-index.yaml'
+);
+
+/**
+ * Read session_id from SessionStart stdin payload.
+ * Claude Code sends JSON with session_id on SessionStart.
+ */
+function readSessionId(): string | null {
+  try {
+    const raw = readFileSync('/dev/stdin', 'utf-8').trim();
+    if (!raw) return null;
+    const payload = JSON.parse(raw) as Record<string, unknown>;
+    return (payload.session_id as string) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── RFC-033 Phase 1: project-state.yaml reader ─────────────────────────────
+
+const PROJECT_STATE_PATH = join(PROJECT_ROOT, 'project-guidelines', 'project-state.yaml');
+
+interface PendingCounts {
+  critical: number;
+  high: number;
+  medium: number;
+  ci_gating: number;
+}
+
+interface BacklogSummary {
+  version: string;
+  next: string;
+  status: string;
+  lastSession: string;
+}
+
+/**
+ * Synthesize a short status string from pending counts (RFC-033 Phase 1).
+ * Output format: "0 CRITICAL · 0 HIGH · 1 MEDIUM · 0 CI-gating" (<=80 chars).
+ * Exported for unit-testability.
+ */
+export function synthesizeStatus(pending: PendingCounts): string {
+  const { critical, high, medium, ci_gating: ciGating } = pending;
+  return `${String(critical)} CRITICAL · ${String(high)} HIGH · ${String(medium)} MEDIUM · ${String(ciGating)} CI-gating`;
+}
+
+/**
+ * Try to read project-state.yaml and map fields to BacklogSummary shape.
+ * Returns null on ANY failure (file absent, parse error, missing required fields).
+ * Exported for unit-testability.
+ */
+export function readProjectState(filePath: string): BacklogSummary | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    const raw = readFileSync(filePath, 'utf-8');
+    const doc = parseYaml(raw) as Record<string, unknown>;
+
+    // Required field guard
+    const version = doc?.version as string | undefined;
+    const session = doc?.session as Record<string, unknown> | undefined;
+    const nextStep = doc?.next_step as Record<string, unknown> | undefined;
+    const pending = doc?.pending as Record<string, unknown> | undefined;
+
+    if (!version || typeof version !== 'string') return null;
+    const nextSummary = nextStep?.summary as string | undefined;
+    if (!nextSummary || typeof nextSummary !== 'string') return null;
+
+    const lastSummary = (session?.last_summary as string | undefined) ?? '';
+    const counts: PendingCounts = {
+      critical: Number(pending?.critical ?? 0),
+      high: Number(pending?.high ?? 0),
+      medium: Number(pending?.medium ?? 0),
+      ci_gating: Number(pending?.ci_gating ?? 0),
+    };
+
+    return {
+      version,
+      next: nextSummary,
+      status: synthesizeStatus(counts),
+      lastSession: lastSummary,
+    };
+  } catch {
+    return null;
+  }
+}
 
 /**
- * Read BACKLOG.md to extract version and next work item.
- * Returns structured summary for the greeting.
+ * Legacy BACKLOG.md parser — kept as the fallback path (RFC-033 Phase 1).
+ * Extracted from the original getBacklogSummary() body; behaviour unchanged.
  */
-function getBacklogSummary(): { version: string; next: string; status: string } {
+function readBacklogFallback(): BacklogSummary {
   try {
-    const backlogPath = join(PROJECT_ROOT, "project-guidelines", "BACKLOG.md");
-    const content = readFileSync(backlogPath, "utf-8");
-    const lines = content.split("\n").slice(0, 40);
+    const backlogPath = join(PROJECT_ROOT, 'project-guidelines', 'BACKLOG.md');
+    const content = readFileSync(backlogPath, 'utf-8');
+    const allLines = content.split('\n');
+    // Version is always near the top (frontmatter + header area)
+    const headerLines = allLines.slice(0, 40);
 
     // Extract version from "**Release Atual:** vX.Y.Z" or "Current Release: vX.Y.Z"
-    const versionLine = lines.find((l) => /release atual|current release/i.test(l));
+    const versionLine = headerLines.find((l) => /release atual|current release/i.test(l));
     const versionMatch = versionLine?.match(/v(\d+\.\d+\.\d+)/);
-    const version = versionMatch ? `v${versionMatch[1]}` : "v?.?.?";
-
-    // Extract pending status from "**Pendente:**" line (colon may be inside or outside bold)
-    const pendenteLine = lines.find((l) => /\*\*pendente/i.test(l));
-    const status = pendenteLine
-      ?.replace(/.*\*\*pendente:?\*\*:?\s*/i, "")
-      .replace(/\s*$/, "")
-      .slice(0, 80) || "";
-
-    // Extract next step from "**Proximo passo:**" or "**Next:**" line
-    const nextLine = lines.find((l) => /\*\*proximo passo/i.test(l) || /\*\*next/i.test(l));
-    const next = nextLine
-      ?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, "")
-      .replace(/\s*$/, "")
-      .slice(0, 120) || "see BACKLOG.md";
-
-    log(HOOK, `BACKLOG parsed: version=${version} next=${next.slice(0, 50)}`);
-    return { version, next, status };
+    const version = versionMatch ? `v${versionMatch[1]}` : 'v?.?.?';
+
+    // Extract pending status from "**Pendente:**" line — must be line-anchored
+    // to avoid matching inline mentions inside session summaries.
+    const pendenteLine = allLines.find((l) => /^\*\*pendente/i.test(l));
+    const status =
+      pendenteLine
+        ?.replace(/.*\*\*pendente:?\*\*:?\s*/i, '')
+        .replace(/\s*$/, '')
+        .slice(0, 80) || '';
+
+    // Extract last session summary — allows "Sessao N:**", "Sessao N FINAL:**",
+    // "Sessao N (suffix):**". Picks the entry with the highest session number
+    // so updates at the file top are preferred over older entries.
+    const sessionRegex = /^\*\*Sessao (\d+)[^*]*:\*\*/i;
+    const sessionMatches = allLines
+      .map((l, idx) => {
+        const m = sessionRegex.exec(l);
+        return m ? { line: l, num: Number(m[1]), idx } : null;
+      })
+      .filter((x): x is { line: string; num: number; idx: number } => x !== null);
+    const latestSession = sessionMatches.sort((a, b) => b.num - a.num || a.idx - b.idx)[0];
+    const lastSession = latestSession?.line.replace(/\*\*/g, '').slice(0, 120) || '';
+
+    // Extract next step from "**Proximo passo:**" or "**Next:**" line — must be
+    // line-anchored to avoid matching inline mentions inside session summaries.
+    const nextLine = allLines.find((l) => /^\*\*proximo passo/i.test(l) || /^\*\*next/i.test(l));
+    const next =
+      nextLine
+        ?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, '')
+        .replace(/\s*$/, '')
+        .slice(0, 120) || 'see BACKLOG.md';
+
+    log(
+      HOOK,
+      `BACKLOG.md fallback parsed: version=${version} next=${next.slice(0, 50)} lastSession=${lastSession.slice(0, 50)}`
+    );
+    return { version, next, status, lastSession };
   } catch (err) {
     log(HOOK, `BACKLOG read failed: ${err}`);
-    return { version: "v?.?.?", next: "see BACKLOG.md", status: "" };
+    return { version: 'v?.?.?', next: 'see BACKLOG.md', status: '', lastSession: '' };
+  }
+}
+
+/**
+ * Read session context: try project-state.yaml first (RFC-033 Phase 1),
+ * fall back to legacy BACKLOG.md parsing on any failure.
+ * Return shape is IDENTICAL to the original function.
+ */
+function getBacklogSummary(): BacklogSummary {
+  const structured = readProjectState(PROJECT_STATE_PATH);
+  if (structured !== null) {
+    log(
+      HOOK,
+      `project-state.yaml: version=${structured.version} next=${structured.next.slice(0, 50)}`
+    );
+    return structured;
+  }
+  log(HOOK, 'project-state.yaml absent/invalid — using BACKLOG.md fallback');
+  return readBacklogFallback();
+}
+
+type TierInfo = { onboardingNeeded: true } | { tier: number; source: string } | null;
+
+/**
+ * Check the project tier from vault YAML config.
+ * Returns null on any unexpected error (tier omitted from output).
+ * Note: API call removed (I-5) — the endpoint needs a real project UUID which the hook doesn't have.
+ */
+async function checkTier(): Promise<TierInfo> {
+  try {
+    // Use module-level VAULT_CONFIG_PATH constant (IMP-003)
+    if (!existsSync(VAULT_CONFIG_PATH)) {
+      return { onboardingNeeded: true };
+    }
+
+    const content = readFileSync(VAULT_CONFIG_PATH, 'utf-8');
+    const config = parseYaml(content) as Record<string, unknown>;
+    const project = config?.project as Record<string, unknown> | undefined;
+    const tier = project?.tier as number | undefined;
+    if (tier !== undefined) {
+      return { tier, source: 'config' };
+    }
+
+    return null;
+  } catch (err) {
+    log(HOOK, `Tier check failed: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * Format tier info as a segment string for the ORCHESTRATOR-DATA line.
+ */
+export function formatTierSegment(info: TierInfo): string {
+  if (info === null) return '';
+  if ('onboardingNeeded' in info) return ' | onboarding_needed=true';
+  return ` | tier=${info.tier} (${info.source})`;
+}
+
+/**
+ * Build [CAPABILITY-MATRIX] + [MEMORY-CONTEXT] lines for injection.
+ * Fail-open: returns empty string on any error.
+ */
+function buildCapabilityMatrixContext(): string {
+  try {
+    let index = readCapabilitiesFromVault(VAULT_CONFIG_PATH);
+    const cachedMtime = index?.installedPluginsMtime ?? '';
+
+    if (!index || needsRescan(INSTALLED_PLUGINS_PATH, cachedMtime)) {
+      log(HOOK, 'Capability rescan triggered');
+      index = buildCapabilityIndex({
+        installedPluginsPath: INSTALLED_PLUGINS_PATH,
+        agentsDir: AGENTS_DIR,
+        vaultConfigPath: VAULT_CONFIG_PATH,
+        profilesPath: PROFILES_PATH,
+      });
+      writeCapabilitiesToVault(VAULT_CONFIG_PATH, index);
+    } else {
+      // Agents are always scanned fresh (fast, <10ms)
+      index.agents = scanAgentDefinitions(AGENTS_DIR);
+      log(HOOK, 'Using cached capability index');
+    }
+
+    const matrixLine = formatCapabilityMatrix(index);
+
+    // Memory context
+    const memoryEntries = readMemoryIndex(MEMORY_INDEX_PATH);
+    let memoryLine = '';
+    if (memoryEntries) {
+      const filtered = filterRelevantMemories(memoryEntries);
+      memoryLine = formatMemoryContext(filtered);
+    }
+
+    return [matrixLine, memoryLine].filter(Boolean).join('\n');
+  } catch (err) {
+    log(HOOK, `Capability matrix failed: ${err}`);
+    return '';
+  }
+}
+
+/**
+ * Check sprint mailbox inbox for pending tasks (RFC-027 Sprint 4).
+ * Only runs when SPRINT_ID and PANE_ROLE are set (sprint pane sessions).
+ * Returns formatted [ACTION-REQUIRED] lines or empty string.
+ */
+function checkSprintInbox(): string {
+  const sprintId = process.env.SPRINT_ID;
+  const paneRole = process.env.PANE_ROLE;
+
+  if (!sprintId || !paneRole) return '';
+
+  try {
+    const inboxDir = join('/tmp', sprintId, 'mailbox', paneRole, 'inbox');
+    if (!existsSync(inboxDir)) return '';
+
+    const files = readdirSync(inboxDir).filter((f) => f.endsWith('.json'));
+    if (files.length === 0) return '';
+
+    const pendingTasks: string[] = [];
+    const maxShow = 5;
+
+    for (const file of files.slice(0, maxShow)) {
+      try {
+        const content = readFileSync(join(inboxDir, file), 'utf-8');
+        const envelope = JSON.parse(content) as Record<string, unknown>;
+        const body = envelope.body as Record<string, unknown> | undefined;
+        if (body?.type) {
+          pendingTasks.push(
+            `  → ${body.type}: ${body.title || body.summary || body.originalTaskId || '(no title)'}`
+          );
+        }
+      } catch {
+        // skip malformed files
+      }
+    }
+
+    if (pendingTasks.length === 0) return '';
+
+    const extra = files.length > maxShow ? `\n  (+ ${files.length - maxShow} more)` : '';
+    return [
+      `[ACTION-REQUIRED] ${files.length} pending task(s) in mailbox:`,
+      ...pendingTasks,
+      extra,
+      `[ACTION-REQUIRED] Execute NOW. Send task_complete when done.`,
+    ]
+      .filter(Boolean)
+      .join('\n');
+  } catch (err) {
+    log(HOOK, `checkSprintInbox failed: ${err}`);
+    return '';
+  }
+}
+
+// ─── Graph Context (RFC-021 T-G4-06) ──────────────────────────────────────────
+
+type GraphFetcher = (path: string, token: string, timeoutMs?: number) => Promise<unknown>;
+
+interface GraphStatsResponse {
+  nodeCount?: number;
+  edgeCount?: number;
+  hotPaths?: string[];
+}
+
+interface AtRiskResponse {
+  atRisk?: string[];
+}
+
+/**
+ * Fetch graph stats and at-risk components from the GraphRAG API.
+ * Uses Promise.all for parallel calls with a 2s AbortController timeout.
+ * Fail-open: returns "" on any error so session-start never blocks.
+ *
+ * @param token - JWT token (null → skip API calls, return "")
+ * @param fetcher - injectable fetch function (default: real HTTP via api-client pattern)
+ */
+export async function getGraphContext(
+  token: string | null,
+  fetcher?: GraphFetcher
+): Promise<string> {
+  if (token === null || token === '') return '';
+
+  const defaultFetcher: GraphFetcher = async (path, tok, timeoutMs = GRAPHRAG_TIMEOUT_MS) => {
+    const resp = await fetch(`http://localhost:3000${path}`, {
+      headers: { Authorization: `Bearer ${tok}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!resp.ok) return null;
+    return resp.json() as Promise<unknown>;
+  };
+
+  const fetch_ = fetcher ?? defaultFetcher;
+
+  try {
+    const [statsRaw, atRiskRaw] = await Promise.all([
+      fetch_('/api/v1/graphrag/stats', token, GRAPHRAG_TIMEOUT_MS),
+      fetch_('/api/v1/graphrag/at-risk', token, GRAPHRAG_TIMEOUT_MS),
+    ]);
+
+    const stats = statsRaw as GraphStatsResponse | null;
+    if (stats?.nodeCount === undefined) return '';
+
+    const atRiskData = atRiskRaw as AtRiskResponse | null;
+    const components = String(stats.nodeCount);
+    const edges = String(stats.edgeCount ?? 0);
+    const hotPaths = (stats.hotPaths ?? []).join(',');
+    const atRisk = (atRiskData?.atRisk ?? []).join(',');
+
+    return `[GRAPH-CONTEXT] components=${components} edges=${edges} hot_paths=[${hotPaths}] at_risk=[${atRisk}]`;
+  } catch {
+    return '';
   }
 }
 
 async function main(): Promise<void> {
-  log(HOOK, "SessionStart hook triggered");
+  log(HOOK, 'SessionStart hook triggered');
+
+  const sessionId = readSessionId();
+  const sessionSegment = sessionId ? ` | session=${sessionId}` : '';
+  if (sessionId) log(HOOK, `Claude session: ${sessionId}`);
 
   const backlog = getBacklogSummary();
+  const tierInfo = await checkTier();
+  const tierSegment = formatTierSegment(tierInfo);
+  const capabilityContext = buildCapabilityMatrixContext();
   const workflow = await getActiveWorkflow();
 
+  // Sprint inbox check (RFC-027 S4 — only for sprint panes)
+  const sprintInboxContext = checkSprintInbox();
+
+  // Graph context (RFC-021 T-G4-06) — fail-open, 2s timeout
+  const token = await getToken();
+  const graphContext = await getGraphContext(token);
+
   if (!workflow) {
-    log(HOOK, "No active workflow, injecting greeting data");
+    log(HOOK, 'No active workflow, injecting greeting data');
     outputContext(
-      "SessionStart",
+      'SessionStart',
       [
-        `[ORCHESTRATOR-DATA] version=${backlog.version} | workflow=none | next=${backlog.next}`,
+        `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=none${tierSegment} | next=${backlog.next}`,
+        backlog.lastSession ? `[LAST-SESSION] ${backlog.lastSession}` : '',
+        backlog.status ? `[PENDENTE] ${backlog.status}` : '',
         `[ORCHESTRATOR] Greet the user via AskUserQuestion using the data above (CLAUDE.md Rule #1).`,
-        "Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.",
-        "Invoke /orchestrator skill only when the user chooses to start a workflow.",
-      ].join("\n")
+        'Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.',
+        'Invoke /orchestrator skill only when the user chooses to start a workflow.',
+        capabilityContext,
+        graphContext,
+        sprintInboxContext,
+      ]
+        .filter(Boolean)
+        .join('\n')
     );
     return;
   }
 
   // Active workflow — inject state + backlog
   const action = await getNextAction(workflow.id);
-  const actionHint = action?.hasAction && action.pendingAction
-    ? ` | pending=${action.pendingAction.agent} (${action.pendingAction.status})`
-    : "";
+  const actionHint =
+    action?.hasAction && action.pendingAction
+      ? ` | pending=${action.pendingAction.agent} (${action.pendingAction.status})`
+      : '';
 
   log(HOOK, `Injecting workflow context (wf=${workflow.id} phase=${workflow.currentPhase})`);
   outputContext(
-    "SessionStart",
+    'SessionStart',
     [
-      `[ORCHESTRATOR-DATA] version=${backlog.version} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}`,
+      `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}${tierSegment}`,
       `[ORCHESTRATOR] Active workflow detected. Greet the user via AskUserQuestion showing workflow state (CLAUDE.md Rule #1).`,
-      "Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.",
-      "Invoke /orchestrator skill when the user chooses to continue the workflow.",
-    ].join("\n")
+      'Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.',
+      'Invoke /orchestrator skill when the user chooses to continue the workflow.',
+      capabilityContext,
+      graphContext,
+    ]
+      .filter(Boolean)
+      .join('\n')
   );
 }
 

package/hooks/sprint-registry.ts

@@ -39,10 +39,9 @@ async function main(): Promise<void> {
   const stdin = await readStdin();
   const sessionId = (stdin.session_id as string) ?? undefined;
 
-
   // Read required env vars
-  const sprintId = process.env['SPRINT_ID'];
-  const paneRole = process.env['PANE_ROLE'];
+  const sprintId = process.env.SPRINT_ID;
+  const paneRole = process.env.PANE_ROLE;
 
   if (!sprintId || !paneRole) {
     log(`Skipping: SPRINT_ID=${sprintId ?? 'unset'} PANE_ROLE=${paneRole ?? 'unset'}`);
@@ -52,7 +51,7 @@ async function main(): Promise<void> {
   const registryDir = `/tmp/${sprintId}/registry`;
   const entryPath = join(registryDir, `${paneRole}.json`);
 
-  const workflowId = process.env['WORKFLOW_ID'];
+  const workflowId = process.env.WORKFLOW_ID;
 
   const entry: Record<string, unknown> = {
     role: paneRole,
@@ -73,7 +72,9 @@ async function main(): Promise<void> {
   try {
     mkdirSync(registryDir, { recursive: true });
     writeFileSync(entryPath, JSON.stringify(entry, null, 2), 'utf-8');
-    log(`Registered ${paneRole} for sprint ${sprintId} (pid=${process.pid}, session=${sessionId ?? 'unknown'})`);
+    log(
+      `Registered ${paneRole} for sprint ${sprintId} (pid=${process.pid}, session=${sessionId ?? 'unknown'})`
+    );
   } catch (err) {
     // Log but do not fail — registration is best-effort
     log(`Registration failed: ${err}`);

package/hooks/subagent-start.ts

@@ -10,17 +10,18 @@ import {
   getField,
   getActiveWorkflow,
   startInvocation,
-} from "./lib/api-client.js";
+  writeInvocationState,
+} from './lib/api-client.js';
 
-const HOOK = "SUBAGENT-START";
+const HOOK = 'SUBAGENT-START';
 
 const PHASE_MAP: Record<string, string> = {
-  specifier: "specify",
-  planner: "plan",
-  "task-generator": "tasks",
-  implementer: "implement",
-  researcher: "research",
-  reviewer: "review",
+  specifier: 'specify',
+  planner: 'plan',
+  'task-generator': 'tasks',
+  implementer: 'implement',
+  researcher: 'research',
+  reviewer: 'review',
 };
 
 async function main(): Promise<void> {
@@ -28,10 +29,10 @@ async function main(): Promise<void> {
   log(HOOK, `SubagentStart triggered`);
 
   const agentType =
-    getField(stdin, "tool_input.subagent_type") ||
-    getField(stdin, "subagent_type") ||
-    getField(stdin, "tool_input.type") ||
-    "unknown";
+    getField(stdin, 'tool_input.subagent_type') ||
+    getField(stdin, 'subagent_type') ||
+    getField(stdin, 'tool_input.type') ||
+    'unknown';
 
   const phase = PHASE_MAP[agentType] || agentType;
 
@@ -39,12 +40,23 @@ async function main(): Promise<void> {
 
   const workflow = await getActiveWorkflow();
   if (!workflow) {
-    log(HOOK, "No active workflow, skipping");
+    log(HOOK, 'No active workflow, skipping');
     return;
   }
 
-  await startInvocation(agentType, workflow.id, phase);
-  log(HOOK, `START: agent=${agentType} phase=${phase} workflow=${workflow.id}`);
+  const invocationId = await startInvocation(agentType, workflow.id, phase);
+  if (invocationId) {
+    const written = writeInvocationState(workflow.id, agentType, invocationId);
+    log(
+      HOOK,
+      `START: agent=${agentType} phase=${phase} workflow=${workflow.id} invocationId=${invocationId} stateWritten=${written}`
+    );
+  } else {
+    log(
+      HOOK,
+      `START: agent=${agentType} phase=${phase} workflow=${workflow.id} — startInvocation returned null (POST failed or no token)`
+    );
+  }
 }
 
 main().catch(() => process.exit(0));