@orchestrator-claude/definitions 3.37.0 → 3.37.2

package/hooks/session-start.ts

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import {
   log,
+  readStdin,
   getActiveWorkflow,
   getNextAction,
   outputContext,
@@ -24,14 +25,16 @@ import {
 import {
   needsRescan,
   buildCapabilityIndex,
-  writeCapabilitiesToVault,
-  readCapabilitiesFromVault,
+  resolveCapabilityCachePath,
+  writeCapabilityCache,
+  readCapabilityCache,
   scanAgentDefinitions,
   formatCapabilityMatrix,
   readMemoryIndex,
   filterRelevantMemories,
   formatMemoryContext,
 } from './lib/capability-scanner.js';
+import type { MemoryIndexDiagnostic } from './lib/capability-scanner.js';
 import { readSessionSelection } from './lib/session-selection.js';
 
 const HOOK = 'SESSION-START';
@@ -63,29 +66,115 @@ const PROJECT_SELECTION_ENABLED = process.env.ORCHESTRATOR_ENABLE_PROJECT_SELECT
 // that is exactly the "no binding" state phase-1 prompts for).
 const SESSION_SELECTION_STATE_DIR = join(HOME, '.orchestrator', 'session-selection');
 const AGENTS_DIR = PROJECT_ROOT ? join(PROJECT_ROOT, '.claude', 'agents') : null;
+// READ-ONLY from here on (TD-235 half B / S445 VETOR 1): the vault config is a
+// git-tracked governance document. The scan cache moved out of it and into the
+// gitignored state dir — see capability-scanner.ts "Cache Persistence".
 const VAULT_CONFIG_PATH = PROJECT_ROOT
   ? join(PROJECT_ROOT, 'project-guidelines', '.vault-config.yaml')
   : null;
+// Same null-when-unregistered-cwd contract as its siblings (RFC-040 C5).
+const CAPABILITY_CACHE_PATH = PROJECT_ROOT ? resolveCapabilityCachePath(PROJECT_ROOT) : null;
 const PROFILES_PATH = PROJECT_ROOT ? join(PROJECT_ROOT, '.claude', 'plugin-profiles.yaml') : null;
 const MEMORY_INDEX_PATH = PROJECT_ROOT
   ? join(PROJECT_ROOT, '.claude', 'agent-memory', 'orchestrator', 'memory-index.yaml')
   : null;
 
 /**
- * Read session_id from SessionStart stdin payload.
- * Claude Code sends JSON with session_id on SessionStart.
+ * How the harness entered this session. `compact` means context was
+ * compacted MID-TASK — a recovery, not a start (SPEC-S454 §12).
  */
-function readSessionId(): string | null {
+interface SessionStartPayload {
+  sessionId: string | null;
+  source: string | null;
+}
+
+/**
+ * Read the SessionStart stdin payload — BOTH fields, in ONE read.
+ *
+ * SPEC-S455 RF-001/ADR-001: drains `process.stdin` to EOF via `readStdin()`
+ * (the same async primitive 13 of the other 14 hooks in this house already
+ * use successfully — `lib/api-client.ts#readStdin`), not
+ * `readFileSync('/dev/stdin')` (the old, synchronous mechanism — confirmed by
+ * runtime measurement, S455, to never deliver a real payload under the
+ * Claude Code harness's spawn: every `Claude session:` log line in this
+ * repo's history before this fix was a test fixture, zero were real UUIDs).
+ *
+ * ★ `process.stdin` is a stream, drained by the first `for await` inside
+ * `readStdin()`. A second read resolves to `{}` (readStdin's own
+ * empty/malformed contract), so a second call here would yield
+ * `source: null` on every real invocation, permanently pinning the hook to
+ * the boot branch while every mock-based test still passed — the same class
+ * of trap as the old mechanism, now manifested asynchronously instead of
+ * synchronously. That failure is silent by construction, which is why this
+ * function returns the whole payload and is called exactly once (see its
+ * single call site in `main()`). Do not add a second reader.
+ * Regression-pinned by tests/hooks/session-start-source-branch.test.ts, whose
+ * stdin mock models real drain semantics and counts the reads, and by
+ * tests/integration/api/helpers/spawn-session-start.test.ts, which drives a
+ * real OS pipe against the compiled bundle.
+ *
+ * ADR-005 (SPEC-S455 planner finding): the outer try/catch is deliberately
+ * KEPT around `readStdin()`, not removed — `readStdin()`'s own try/catch only
+ * protects `JSON.parse`, never a `for await` that itself throws/rejects (e.g.
+ * `process.stdin` unavailable/non-iterable under an unusual host such as a
+ * Vitest worker thread). Fail-open (RNF-002) must hold against ANY read
+ * failure, not just a malformed payload.
+ */
+async function readSessionStartPayload(): Promise<SessionStartPayload> {
   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;
+    const payload = await readStdin();
+    // SPEC-S455 RF-003: unconditional, every invocation — this is the line
+    // that would have made the old defect diagnosable from day one (model
+    // already validated by dangling-guard.ts:312). Limitation, documented
+    // here and in the spec: readStdin() collapses "stdin empty" and "JSON
+    // malformed" into the same {} — this instrumentation cannot and does not
+    // distinguish the two (out of scope, would require changing the shared
+    // helper, which 13 other hooks depend on).
+    log(HOOK, `stdin keys: [${Object.keys(payload).join(', ')}]`);
+    if (!payload.session_id && !payload.source) {
+      log(
+        HOOK,
+        `[WARN] stdin payload has neither session_id nor source — read likely empty or unparseable (readStdin() collapses both cases to {}); raw keys=[${Object.keys(payload).join(', ')}]`
+      );
+    }
+    return {
+      sessionId: (payload.session_id as string) ?? null,
+      source: (payload.source as string) ?? null,
+    };
+  } catch (err) {
+    // Anomaly readStdin() itself doesn't swallow (its own try/catch only
+    // covers JSON.parse) — e.g. a rejecting/throwing `for await`. Fail-open
+    // per RNF-002/ADR-005, but leave a trace instead of the old silence.
+    log(HOOK, `[WARN] readStdin() itself threw (not just empty/malformed stdin) — ${String(err)}`);
+    return { sessionId: null, source: null };
   }
 }
 
+/**
+ * Recovery is ONLY `compact`. Every other source — including absent, unknown
+ * and unparseable — is a boot, so any degradation lands on the pre-existing
+ * behaviour rather than on a new, less-tested path (RNF-002 fail-open).
+ */
+function isRecoverySource(source: string | null): boolean {
+  return source === 'compact';
+}
+
+/**
+ * Injected INSTEAD of the greeting instructions when recovering.
+ *
+ * The hard guarantee against a mid-task greeting is the missing
+ * `[ORCHESTRATOR-DATA]` token, not this text: the Session Start Protocol keys
+ * its AskUserQuestion greeting off that literal token, so withholding it
+ * disarms the trigger without editing the identity file (SPEC-S454 D-1,
+ * decided by the user). This directive is the belt to that suspenders — it
+ * states the situation the model cannot otherwise infer, since from the
+ * inside a compaction is indistinguishable from a fresh session.
+ */
+const RECOVERY_DIRECTIVE: readonly string[] = [
+  '[ORCHESTRATOR] Context was compacted mid-session. This is NOT a session start.',
+  'Do NOT greet. Do NOT call AskUserQuestion. Resume the in-flight task.',
+];
+
 // ─── RFC-033 Phase 1: project-state.yaml reader ─────────────────────────────
 
 const PROJECT_STATE_PATH = PROJECT_ROOT
@@ -403,59 +492,172 @@ export async function buildProjectSelectionPrompt(): Promise<string> {
 }
 
 /**
- * Build [CAPABILITY-MATRIX] + [MEMORY-CONTEXT] lines for injection.
- * Fail-open: returns empty string on any error.
+ * Build the [CAPABILITY-MATRIX] line (rescan-or-cache + format).
+ * Split out of buildCapabilityMatrixContext (TD-249) so a failure here
+ * cannot discard a memory line already built by buildMemoryLine, or vice
+ * versa — the two used to share one try block and were all-or-nothing.
  */
-function buildCapabilityMatrixContext(): string {
-  try {
-    // RFC-040 C5: unregistered cwd — no vault/agents/memory-index to read, skip.
-    if (
-      VAULT_CONFIG_PATH === null ||
-      AGENTS_DIR === null ||
-      PROFILES_PATH === null ||
-      MEMORY_INDEX_PATH === null
-    ) {
-      log(
-        HOOK,
-        'buildCapabilityMatrixContext: PROJECT_ROOT unresolved (unregistered cwd) — skipping'
-      );
-      return '';
-    }
-    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');
-    }
+function buildMatrixLine(
+  vaultConfigPath: string,
+  agentsDir: string,
+  profilesPath: string,
+  cachePath: string
+): string {
+  // A null cache (absent / corrupt) means RESCAN, never an empty matrix.
+  let index = readCapabilityCache(cachePath, vaultConfigPath);
+  const cachedMtime = index?.installedPluginsMtime ?? '';
+
+  if (!index || needsRescan(INSTALLED_PLUGINS_PATH, cachedMtime)) {
+    log(HOOK, 'Capability rescan triggered');
+    index = buildCapabilityIndex({
+      installedPluginsPath: INSTALLED_PLUGINS_PATH,
+      agentsDir,
+      vaultConfigPath,
+      profilesPath,
+    });
+    writeCapabilityCache(cachePath, index);
+  } else {
+    // Agents are always scanned fresh (fast, <10ms)
+    index.agents = scanAgentDefinitions(agentsDir);
+    log(HOOK, 'Using cached capability index');
+  }
+
+  return formatCapabilityMatrix(index);
+}
 
-    const matrixLine = formatCapabilityMatrix(index);
+/**
+ * Build the [MEMORY-CONTEXT] line. Split out of buildCapabilityMatrixContext
+ * (TD-249) — see buildMatrixLine doc comment for why.
+ */
+function buildMemoryLine(memoryIndexPath: string): string {
+  const diag: MemoryIndexDiagnostic = {};
+  const memoryEntries = readMemoryIndex(memoryIndexPath, diag);
+  if (diag.reason) log(HOOK, `Memory index: ${diag.reason}`);
+
+  // Índice AUSENTE segue silencioso — não ter memória ainda é legítimo, e é o
+  // estado da maior parte dos slugs. Índice que EXISTE e não carrega, NÃO: era
+  // indistinguível de "não há memória" (S480). E o log sozinho não bastaria —
+  // ele vai para um arquivo de debug que ninguém abre. A linha entra NA SESSÃO,
+  // que é onde a ausência precisa ser vista: mesma regra do monitor da Root,
+  // campo ausente nunca some da tela.
+  //
+  // A guarda é `diag.reason`, NÃO `length === 0`: lista legitimamente vazia
+  // segue pelo caminho original (filter -> format -> ''), porque não é o
+  // defeito e mudá-la quebrou um teste que já existia — ele mocka
+  // readMemoryIndex devolvendo [] e assere que o fluxo continua.
+  if (diag.reason && (!memoryEntries || memoryEntries.length === 0)) {
+    return `[MEMORY-CONTEXT] INDISPONÍVEL — nenhuma memória injetada. ${diag.reason}`;
+  }
+  if (!memoryEntries) return '';
+  const filtered = filterRelevantMemories(memoryEntries);
+  return formatMemoryContext(filtered, memoryEntries);
+}
 
-    // Memory context
-    const memoryEntries = readMemoryIndex(MEMORY_INDEX_PATH);
-    let memoryLine = '';
-    if (memoryEntries) {
-      const filtered = filterRelevantMemories(memoryEntries);
-      memoryLine = formatMemoryContext(filtered);
-    }
+/**
+ * RFC-040 C5: unregistered cwd — no vault/agents/memory-index to read, skip.
+ * (Single guard is correct here, NOT a repeat of the TD-249 bug: all five
+ * paths derive from the same PROJECT_ROOT, so they are null/non-null
+ * together — this is one precondition, not two independently-failing
+ * steps. CAPABILITY_CACHE_PATH joined them in S445; it is PROJECT_ROOT-
+ * derived too, unless ORCHESTRATOR_STATE_DIR overrides the state dir, in
+ * which case it is non-null whenever PROJECT_ROOT is.)
+ */
+interface VaultPaths {
+  vaultConfigPath: string;
+  agentsDir: string;
+  profilesPath: string;
+  memoryIndexPath: string;
+  capabilityCachePath: string;
+}
+
+function resolveVaultPaths(caller: string): VaultPaths | null {
+  if (
+    VAULT_CONFIG_PATH === null ||
+    AGENTS_DIR === null ||
+    PROFILES_PATH === null ||
+    MEMORY_INDEX_PATH === null ||
+    CAPABILITY_CACHE_PATH === null
+  ) {
+    log(HOOK, `${caller}: PROJECT_ROOT unresolved (unregistered cwd) — skipping`);
+    return null;
+  }
+  return {
+    vaultConfigPath: VAULT_CONFIG_PATH,
+    agentsDir: AGENTS_DIR,
+    profilesPath: PROFILES_PATH,
+    memoryIndexPath: MEMORY_INDEX_PATH,
+    capabilityCachePath: CAPABILITY_CACHE_PATH,
+  };
+}
 
-    return [matrixLine, memoryLine].filter(Boolean).join('\n');
+/**
+ * Build the [CAPABILITY-MATRIX] line for injection. Fail-open (TD-249):
+ * a throw here returns '' and never touches the memory line, which is
+ * built by buildMemoryContext() on its own try block.
+ * Exported for unit-testability (TD-315).
+ */
+export function buildMatrixContext(): string {
+  const paths = resolveVaultPaths('buildMatrixContext');
+  if (!paths) return '';
+  try {
+    return buildMatrixLine(
+      paths.vaultConfigPath,
+      paths.agentsDir,
+      paths.profilesPath,
+      paths.capabilityCachePath
+    );
   } catch (err) {
     log(HOOK, `Capability matrix failed: ${err}`);
     return '';
   }
 }
 
+/**
+ * Build the [MEMORY-CONTEXT] line for injection. Fail-open (TD-249):
+ * a throw here returns '' and never touches the matrix line.
+ *
+ * TD-315: emitted SEPARATELY from the matrix — and BEFORE [LAST-SESSION] —
+ * so the memory is not the first block to die when the harness truncates
+ * additionalContext. Measured S513/S514: total 17190/17013 chars; with the
+ * old order ([ORCHESTRATOR-DATA] · [LAST-SESSION] · [PENDENTE] · greeting ·
+ * [CAPABILITY-MATRIX] · [MEMORY-CONTEXT]) the memory started at offset
+ * 10974/10551 and a 10000-char cut took ALL 20 memories while the
+ * narrative survived whole. Placed right after the state line (offset
+ * 4101 in S514, ending 10563), the same cut keeps 91% of it, and any cut
+ * >= 10563 keeps it whole — with nothing lost when nothing is cut. Capping
+ * [LAST-SESSION] instead would NOT save the memory (it would still end past
+ * 13000) and would mutilate the PM's narrative every session, cut or not.
+ * Exported for unit-testability (TD-315).
+ */
+export function buildMemoryContext(): string {
+  const paths = resolveVaultPaths('buildMemoryContext');
+  if (!paths) return '';
+  try {
+    return buildMemoryLine(paths.memoryIndexPath);
+  } catch (err) {
+    log(HOOK, `Memory context failed: ${err}`);
+    return '';
+  }
+}
+
+/**
+ * Build [CAPABILITY-MATRIX] + [MEMORY-CONTEXT] lines, matrix first.
+ * Fail-open: each half degrades INDEPENDENTLY (TD-249) — a throw building
+ * the matrix must not discard a working memory line, and a throw building
+ * the memory line must not discard a working matrix line. Previously both
+ * lived in one try block, so either failure returned '' and threw away
+ * whatever the other half had already produced.
+ *
+ * TD-315: no longer what main() injects — main() now places the two halves
+ * at different offsets (memory before the narrative, matrix after the
+ * greeting). Kept as the composed form for the TD-249 partial-failure
+ * contract and any external caller.
+ * Exported for unit-testability (TD-249).
+ */
+export function buildCapabilityMatrixContext(): string {
+  return [buildMatrixContext(), buildMemoryContext()].filter(Boolean).join('\n');
+}
+
 /**
  * Check sprint mailbox inbox for pending tasks (RFC-027 Sprint 4).
  * Only runs when SPRINT_ID and PANE_ROLE are set (sprint pane sessions).
@@ -519,14 +721,22 @@ async function main(): Promise<void> {
     );
   }
 
-  const sessionId = readSessionId();
+  // ONE read of stdin (readStdin() drains process.stdin to EOF), both fields
+  // derived from it — see readSessionStartPayload's doc comment for why a
+  // second read is fatal.
+  const { sessionId, source } = await readSessionStartPayload();
+  const isRecovery = isRecoverySource(source);
   const sessionSegment = sessionId ? ` | session=${sessionId}` : '';
   if (sessionId) log(HOOK, `Claude session: ${sessionId}`);
+  log(HOOK, `source=${source ?? 'unknown'} mode=${isRecovery ? 'recovery' : 'boot'}`);
 
   const backlog = getBacklogSummary();
   const tierInfo = await checkTier();
   const tierSegment = formatTierSegment(tierInfo);
-  const capabilityContext = buildCapabilityMatrixContext();
+  // TD-315: two separate blocks at two different offsets — see
+  // buildMemoryContext's doc comment for the measured reason.
+  const memoryContext = buildMemoryContext();
+  const matrixContext = buildMatrixContext();
 
   // Sprint inbox check (RFC-027 S4 — only for sprint panes)
   const sprintInboxContext = checkSprintInbox();
@@ -582,8 +792,15 @@ async function main(): Promise<void> {
   // folded as extra lines into whichever outputContext() call below fires
   // — never a SECOND outputContext call, so exactly one [ORCHESTRATOR-DATA]
   // block is ever emitted (double-load regression guard).
+  //
+  // SPEC-S454 RF-002: skipped entirely when recovering. A compaction does not
+  // change the project binding — if none resolved, the prompt already fired at
+  // boot — and re-prompting mid-task is both an AskUserQuestion (which the
+  // recovery directive just forbade) and the interruption this fix exists to
+  // avoid. Skipping also spares the API round-trip inside the recovery path
+  // (RNF-001: no new I/O).
   const projectSelectionPrompt =
-    PROJECT_SELECTION_ENABLED && projectBinding.source === 'none'
+    PROJECT_SELECTION_ENABLED && !isRecovery && projectBinding.source === 'none'
       ? await buildProjectSelectionPrompt()
       : '';
 
@@ -604,17 +821,35 @@ async function main(): Promise<void> {
   const workflow = await getActiveWorkflow();
 
   if (!workflow) {
-    log(HOOK, 'No active workflow, injecting greeting data');
+    log(HOOK, `No active workflow, injecting ${isRecovery ? 'recovery' : 'greeting'} data`);
+    // SPEC-S454 RF-002: identical STATE, different FRAME. Only the leading
+    // token and the instruction block differ between boot and recovery — the
+    // capability matrix, memory context and sprint inbox are exactly what a
+    // compaction destroys, so they ride both paths unchanged.
+    // [LAST-SESSION]/[PENDENTE] stay boot-only: they orient someone arriving,
+    // and mid-task they are noise that reads like a session opening.
+    //
+    // TD-315 ORDER CONTRACT: the state line stays at offset 0 (the greeting
+    // keys off the leading token); [MEMORY-CONTEXT] comes IMMEDIATELY after
+    // it, before [LAST-SESSION] and everything else, so that a truncation of
+    // additionalContext takes narrative and routing hints before it takes
+    // memory. Pinned by tests/hooks/session-start-memory-before-narrative.test.ts.
+    const stateLine = `version=${backlog.version}${sessionSegment} | workflow=none${tierSegment}${sessionNumberSegment}${projectBindingSegment} | next=${backlog.next}`;
     outputContext(
       'SessionStart',
       [
-        `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=none${tierSegment}${sessionNumberSegment}${projectBindingSegment} | 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.',
-        capabilityContext,
+        `${isRecovery ? '[ORCHESTRATOR-RECOVERY]' : '[ORCHESTRATOR-DATA]'} ${stateLine}`,
+        memoryContext,
+        ...(isRecovery
+          ? RECOVERY_DIRECTIVE
+          : [
+              backlog.lastSession ? `[LAST-SESSION] ${backlog.lastSession}` : '',
+              backlog.status ? `[PENDENTE] ${backlog.status}` : '',
+              `[ORCHESTRATOR] Greet the user via AskUserQuestion using the data above (orchestrator identity, MUST 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.',
+            ]),
+        matrixContext,
         sprintInboxContext,
         projectSelectionPrompt,
       ]
@@ -631,15 +866,26 @@ async function main(): Promise<void> {
       ? ` | pending=${action.pendingAction.agent} (${action.pendingAction.status})`
       : '';
 
-  log(HOOK, `Injecting workflow context (wf=${workflow.id} phase=${workflow.currentPhase})`);
+  log(
+    HOOK,
+    `Injecting workflow ${isRecovery ? 'recovery' : 'context'} (wf=${workflow.id} phase=${workflow.currentPhase})`
+  );
+  const stateLine = `version=${backlog.version}${sessionSegment} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}${tierSegment}${sessionNumberSegment}${projectBindingSegment}`;
+  // TD-315: same order contract as the no-workflow path — memory right after
+  // the state line, matrix after the instruction block.
   outputContext(
     'SessionStart',
     [
-      `[ORCHESTRATOR-DATA] version=${backlog.version}${sessionSegment} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}${tierSegment}${sessionNumberSegment}${projectBindingSegment}`,
-      `[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.',
-      capabilityContext,
+      `${isRecovery ? '[ORCHESTRATOR-RECOVERY]' : '[ORCHESTRATOR-DATA]'} ${stateLine}`,
+      memoryContext,
+      ...(isRecovery
+        ? RECOVERY_DIRECTIVE
+        : [
+            `[ORCHESTRATOR] Active workflow detected. Greet the user via AskUserQuestion showing workflow state (orchestrator identity, MUST rule #1).`,
+            'Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.',
+            'Invoke /orchestrator skill when the user chooses to continue the workflow.',
+          ]),
+      matrixContext,
       projectSelectionPrompt,
     ]
       .filter(Boolean)