@ghl-ai/aw 0.1.44-beta.1 → 0.1.44-beta.2

package/c4/diagnostics.mjs

@@ -0,0 +1,536 @@
+/**
+ * c4/diagnostics.mjs — end-of-run health probes + summary formatting.
+ *
+ * Five exports, each with a separate, tightly-scoped responsibility:
+ *
+ *   summarizeAsOneLine(state)
+ *     Pure formatter. Renders a single ANSI-clean line for stdout that
+ *     captures the install verdict at a glance.
+ *
+ *   diagnoseAwRouterView({ awHome })
+ *     Codex-relevant: replays the upstream `find * /skills/* /SKILL.md`
+ *     enumeration logic against ~/.aw/.aw_registry/platform/core/skills/
+ *     and reports which expected stage skills are visible to the
+ *     SessionStart hook. Catches Bug A failures (registry path empty
+ *     post-init).
+ *
+ *   diagnosePromptRouterInjection(home, opts)
+ *     Codex-relevant: spawnSyncs the wrapper at <home>/.codex/hooks/
+ *     aw-user-prompt-submit.sh with synthetic stdin (steady-state OR
+ *     first-turn shape per opts.simulateFirstTurn) and asserts the
+ *     stdout JSON envelope contains <EXTREMELY_IMPORTANT> framing.
+ *     Tests both that the wrapper is registered AND that it actually
+ *     emits the router (catches "wrapper installed but does nothing").
+ *
+ *   diagnoseSkillResolution({ harness, home, awHome, eccHome, skills })
+ *     Multi-path × multi-skill probe. For each skill, checks four
+ *     candidate paths in priority order. Top-level ok=true ONLY if
+ *     using-aw-skills AND every stage skill the slim card promises
+ *     resolve via at least one path. Catches "router fires but
+ *     dispatches to ENOENT" silent failures.
+ *
+ *   dumpPostInitState({ harness, cwd, awHome, configPaths, writer, shell })
+ *     Triage dump to stderr (NEVER stdout) — token-redacted gh auth
+ *     status, git remote state, key-only enumeration of config files
+ *     (no values, since some keys carry secrets), and the first 10
+ *     SKILL.md paths visible to the registry enumerator.
+ *
+ * All probes are pure or replay-style; none mutate state. Adapters
+ * (writer, shell, spawnSync) are dependency-injected for testability.
+ *
+ * Contract: spec.md::§"c4/diagnostics.mjs", tasks.md::4.2.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+
+/**
+ * @typedef {'cursor-cloud' | 'codex-web' | 'claude-web' | 'unknown'} Harness
+ */
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Stable expected sets — referenced by multiple probes.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const EXPECTED_STAGE_SKILLS = Object.freeze([
+  'aw-plan',
+  'aw-build',
+  'aw-investigate',
+  'aw-review',
+]);
+const ROUTER_SKILL = 'using-aw-skills';
+const DEFAULT_SKILL_LIST = Object.freeze([ROUTER_SKILL, ...EXPECTED_STAGE_SKILLS]);
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * summarizeAsOneLine
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const CHECK = '\u2713'; // ✓
+const CROSS = '\u2717'; // ✗
+const DOT = ' \u00B7 '; // " · "
+
+/**
+ * @param {object} state
+ *   Combination of PreflightResult + per-harness install outcomes:
+ *     - state.harness, state.hasToken, state.tokenSource, state.authOk
+ *     - state.bridge?: { ok: boolean }    (codex-web only)
+ *     - state.injector?: { ok: boolean }  (codex-web only)
+ *     - state.mcpProbe?: 'ok' | 'invalid-token' | 'unauthorized' | 'unreachable' | 'unknown'
+ *     - state.didInit: boolean
+ *     - state.durationMs: number
+ * @returns {string}
+ */
+export function summarizeAsOneLine(state) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('summarizeAsOneLine: state object required');
+  }
+
+  if (!state.hasToken) {
+    return `[aw-c4] ${state.harness}${DOT}no token${DOT}skipped (agent continues)`;
+  }
+
+  const parts = [`[aw-c4] ${state.harness}`];
+  // authOk === null means "not probed" (diagnose mode skips the auth probe).
+  // Render '?' in that case to avoid the misleading "GITHUB_PAT ✗" tick that
+  // would otherwise show on every diagnose run.
+  const authTick = state.authOk == null ? '?' : (state.authOk ? CHECK : CROSS);
+  parts.push(`${state.tokenSource} ${authTick}`);
+
+  if (state.harness === 'codex-web') {
+    if (state.bridge != null) parts.push(`bridge ${state.bridge.ok ? CHECK : CROSS}`);
+    if (state.injector != null) parts.push(`injector ${state.injector.ok ? CHECK : CROSS}`);
+  } else {
+    parts.push(`auth ${authTick}`);
+    parts.push('bridge n/a');
+  }
+
+  if (state.mcpProbe) parts.push(`mcp ${state.mcpProbe}`);
+
+  const seconds = Number(state.durationMs ?? 0) / 1000;
+  parts.push(`init ${seconds.toFixed(1)}s`);
+  parts.push(state.didInit ? 'ready' : 'skipped');
+
+  return parts.join(DOT);
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * diagnoseAwRouterView
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Replay of the upstream session-start.sh enumerator scan:
+ *   find <awHome>/.aw_registry/platform -path STAR/skills/STAR/SKILL.md
+ *
+ * @param {object} opts
+ * @param {string} opts.awHome
+ * @returns {{ enumerableSkills: string[], expected: string[], missing: string[], ok: boolean }}
+ */
+export function diagnoseAwRouterView({ awHome } = {}) {
+  if (!awHome) throw new Error('diagnoseAwRouterView: awHome is required');
+
+  const platformRoot = join(awHome, '.aw_registry/platform');
+  const enumerableSkills = enumerateRegistrySkills(platformRoot);
+  const expected = [...EXPECTED_STAGE_SKILLS];
+  const missing = expected.filter((s) => !enumerableSkills.includes(s));
+  const ok = missing.length === 0;
+
+  return { enumerableSkills, expected, missing, ok };
+}
+
+/**
+ * Walk <root>/<team>/skills/<skill>/SKILL.md two levels deep, mirroring the
+ * upstream find pattern. Returns the deduped sorted list of skill
+ * directory names.
+ */
+function enumerateRegistrySkills(platformRoot) {
+  if (!existsSync(platformRoot)) return [];
+  const set = new Set();
+  let teams;
+  try {
+    teams = readdirSync(platformRoot, { withFileTypes: true });
+  } catch {
+    // readdir on the platform root failed (EACCES, ENOENT). Treat as
+    // "no skills enumerable" — the caller's missing-list will surface it.
+    return [];
+  }
+  for (const team of teams) {
+    if (!team.isDirectory()) continue;
+    const skillsDir = join(platformRoot, team.name, 'skills');
+    if (!existsSync(skillsDir)) continue;
+    let skills;
+    try {
+      skills = readdirSync(skillsDir, { withFileTypes: true });
+    } catch {
+      // readdir on a team's skills/ subdirectory failed — skip this team
+      // dir but continue probing siblings.
+      continue;
+    }
+    for (const skill of skills) {
+      if (!skill.isDirectory()) continue;
+      const skillMd = join(skillsDir, skill.name, 'SKILL.md');
+      if (existsSync(skillMd)) set.add(skill.name);
+    }
+  }
+  return [...set].sort();
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * diagnosePromptRouterInjection (G10)
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const ROUTER_FRAMING_MARKER = '<EXTREMELY_IMPORTANT>';
+const WRAPPER_HEADER_MARKER = '# aw-c4 router injector v1';
+
+/**
+ * Replay the Codex per-turn wrapper with synthetic stdin and assert the
+ * stdout envelope contains <EXTREMELY_IMPORTANT> framing.
+ *
+ * `simulateFirstTurn: true` (default — per spec line 996) sends a
+ * synthetic first-turn payload with no prior-turn fields, guarding against
+ * the failure mode where wrapper logic depends on prior-turn state and
+ * silently no-ops on turn 1.
+ *
+ * Note on the return shape: when `simulateFirstTurn` is false (test-only
+ * escape hatch), `firstTurnEmitsRouter` mirrors `emitsFullRouter` (no
+ * separate replay was performed). Production calls from c4Command always
+ * run with `simulateFirstTurn: true`, so the field always reflects a real
+ * first-turn probe in production.
+ *
+ * @param {string} home
+ * @param {object} [opts]
+ * @param {boolean} [opts.simulateFirstTurn=true]
+ * @param {string}  [opts.escapeEnvOverride]  Forwarded as AW_PROMPT_ROUTER_INJECT (e.g. '0').
+ * @param {Function} [opts.spawnSync]         Injectable for tests (defaults to node:child_process).
+ * @returns {{ wrapperRegistered: boolean, emitsFullRouter: boolean, firstTurnEmitsRouter: boolean, ok: boolean }}
+ */
+export function diagnosePromptRouterInjection(home, opts = {}) {
+  if (!home) throw new Error('diagnosePromptRouterInjection: home is required');
+
+  const simulateFirstTurn = opts.simulateFirstTurn !== false;
+  const spawn = opts.spawnSync ?? nodeSpawnSync;
+  const wrapperPath = join(home, '.codex/hooks/aw-user-prompt-submit.sh');
+
+  const wrapperRegistered = isWrapperRegistered(wrapperPath);
+  if (!wrapperRegistered) {
+    return { wrapperRegistered: false, emitsFullRouter: false, firstTurnEmitsRouter: false, ok: false };
+  }
+
+  const env = { ...process.env };
+  if (opts.escapeEnvOverride !== undefined) {
+    env.AW_PROMPT_ROUTER_INJECT = String(opts.escapeEnvOverride);
+  }
+
+  // Steady-state replay: payload carries prior-turn fields. cwd is the
+  // injected `home` (matches firstTurnStdin) — keeps the probe hermetic and
+  // out of the host CWD.
+  const steadyOutput = invokeWrapper(spawn, wrapperPath, steadyStateStdin(home), env);
+  const emitsFullRouter = envelopeContainsRouter(steadyOutput);
+
+  // First-turn replay: minimal payload — proves the wrapper does not depend
+  // on prior-turn state to emit the router envelope. When opts.simulateFirstTurn
+  // is false, firstTurnEmitsRouter mirrors emitsFullRouter (no separate replay
+  // is performed). Production callers always run with simulateFirstTurn=true.
+  let firstTurnEmitsRouter = emitsFullRouter;
+  if (simulateFirstTurn) {
+    const firstTurnOutput = invokeWrapper(spawn, wrapperPath, firstTurnStdin(home), env);
+    firstTurnEmitsRouter = envelopeContainsRouter(firstTurnOutput);
+  }
+
+  const ok = wrapperRegistered && emitsFullRouter && firstTurnEmitsRouter;
+  return { wrapperRegistered, emitsFullRouter, firstTurnEmitsRouter, ok };
+}
+
+function isWrapperRegistered(wrapperPath) {
+  if (!existsSync(wrapperPath)) return false;
+  try {
+    return readFileSync(wrapperPath, 'utf8').slice(0, 256).includes(WRAPPER_HEADER_MARKER);
+  } catch {
+    // Wrapper file became unreadable between existence check and read —
+    // fall back to "not registered" so the orchestrator does not try to
+    // invoke a half-broken hook.
+    return false;
+  }
+}
+
+function invokeWrapper(spawn, wrapperPath, stdinPayload, env) {
+  const result = spawn('bash', [wrapperPath], {
+    input: stdinPayload,
+    encoding: 'utf8',
+    env,
+  });
+  return result?.stdout ?? '';
+}
+
+function steadyStateStdin(cwd) {
+  return JSON.stringify({
+    prompt: 'steady state diag probe',
+    cwd,
+    workspace_roots: [cwd],
+    tool_results: [],
+    previous_response_id: 'resp-prior',
+  });
+}
+
+function firstTurnStdin(home) {
+  return JSON.stringify({
+    prompt: 'first turn smoke',
+    cwd: home,
+    workspace_roots: [home],
+  });
+}
+
+function envelopeContainsRouter(output) {
+  if (typeof output !== 'string' || output.length === 0) return false;
+  // Spec invariant: full router envelope places <EXTREMELY_IMPORTANT> in the
+  // hookSpecificOutput.additionalContext field. We accept any occurrence in
+  // stdout (the wrapper builds a JSON object via python3, so framing always
+  // appears in the JSON-encoded form).
+  return output.includes(ROUTER_FRAMING_MARKER);
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * diagnoseSkillResolution (G2)
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/**
+ * @typedef {object} SkillResolutionResult
+ * @property {string}  skill
+ * @property {string[]} candidatePathsChecked
+ * @property {string|null} found
+ * @property {boolean} ok
+ */
+
+/**
+ * For each skill, probe four candidate paths in priority order. Top-level
+ * ok=true ONLY if the router skill (using-aw-skills) AND every stage skill
+ * (aw-plan, aw-build, aw-investigate, aw-review) resolve.
+ *
+ * @param {object} opts
+ * @param {Harness} opts.harness
+ * @param {string}  opts.home
+ * @param {string}  opts.awHome
+ * @param {string}  opts.eccHome
+ * @param {string[]} [opts.skills]  Default: DEFAULT_SKILL_LIST
+ * @returns {{
+ *   perSkill: SkillResolutionResult[],
+ *   routerSkill: SkillResolutionResult,
+ *   stageSkillsOk: boolean,
+ *   ok: boolean
+ * }}
+ */
+export function diagnoseSkillResolution(opts = {}) {
+  if (!opts.harness) throw new Error('diagnoseSkillResolution: harness is required');
+  if (!opts.home) throw new Error('diagnoseSkillResolution: home is required');
+  if (!opts.awHome) throw new Error('diagnoseSkillResolution: awHome is required');
+  if (!opts.eccHome) throw new Error('diagnoseSkillResolution: eccHome is required');
+
+  const { harness, home, awHome, eccHome } = opts;
+  const skills = opts.skills ?? [...DEFAULT_SKILL_LIST];
+
+  const perSkill = skills.map((skill) => probeOneSkill(skill, harness, home, awHome, eccHome));
+  const routerSkill = perSkill.find((e) => e.skill === ROUTER_SKILL) ?? {
+    skill: ROUTER_SKILL,
+    candidatePathsChecked: [],
+    found: null,
+    ok: false,
+  };
+
+  const stageEntries = perSkill.filter((e) => e.skill !== ROUTER_SKILL);
+  const stageSkillsOk = stageEntries.length > 0 && stageEntries.every((e) => e.ok);
+  const ok = routerSkill.ok && stageSkillsOk;
+
+  return { perSkill, routerSkill, stageSkillsOk, ok };
+}
+
+function harnessSkillsDir(harness, home) {
+  if (harness === 'claude-web') return join(home, '.claude/skills');
+  if (harness === 'cursor-cloud') return join(home, '.cursor/skills');
+  // codex-web: registry path is the canonical source; the per-harness skills
+  // dir is conventionally absent. We still probe the registry + ECC paths.
+  return null;
+}
+
+function probeOneSkill(skill, harness, home, awHome, eccHome) {
+  const harnessDir = harnessSkillsDir(harness, home);
+  const candidatePathsChecked = [];
+
+  if (harnessDir) {
+    candidatePathsChecked.push(join(harnessDir, skill, 'SKILL.md'));
+    candidatePathsChecked.push(join(harnessDir, `platform-core-${skill}`, 'SKILL.md'));
+  }
+  candidatePathsChecked.push(join(awHome, '.aw_registry/platform/core/skills', skill, 'SKILL.md'));
+  candidatePathsChecked.push(join(eccHome, 'skills', skill, 'SKILL.md'));
+
+  let found = null;
+  for (const p of candidatePathsChecked) {
+    if (existsSync(p)) {
+      found = p;
+      break;
+    }
+  }
+
+  return { skill, candidatePathsChecked, found, ok: found != null };
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * dumpPostInitState — stderr-only triage dump
+ * ───────────────────────────────────────────────────────────────────────── */
+
+// Covers GitHub classic PAT prefixes (ghp_, gho_, ghs_, ghu_) and the
+// fine-grained PAT prefix github_pat_ (GA since 2023). The 8-char minimum
+// is intentional — short enough to catch redacted-but-leaked fragments,
+// long enough to avoid false-positive on prose like "ghx_" mentions.
+const TOKEN_PATTERN = /(github_pat_[A-Za-z0-9_]{16,}|gh[opsu]_[A-Za-z0-9_]{8,})/g;
+
+const DEFAULT_WRITER = {
+  stderr: (s) => process.stderr.write(s),
+  stdout: (s) => process.stdout.write(s),
+};
+
+function defaultDumpShell(cmd) {
+  const r = nodeSpawnSync(cmd, [], { shell: true, encoding: 'utf8' });
+  return {
+    ok: r.status === 0,
+    stdout: r.stdout ?? '',
+    stderr: r.stderr ?? '',
+    exitCode: r.status ?? -1,
+  };
+}
+
+/**
+ * Triage dump — token-redacted, value-redacted, stderr-only.
+ *
+ * @param {object} opts
+ * @param {Harness} opts.harness
+ * @param {string}  opts.cwd
+ * @param {string}  opts.awHome
+ * @param {string[]} opts.configPaths
+ * @param {object}  [opts.writer]   Default: { stderr: process.stderr.write, stdout: process.stdout.write }
+ * @param {Function} [opts.shell]   Default: real spawnSync.
+ * @returns {void}
+ */
+export function dumpPostInitState(opts = {}) {
+  if (!opts.harness) throw new Error('dumpPostInitState: harness is required');
+  if (!opts.cwd) throw new Error('dumpPostInitState: cwd is required');
+  if (!opts.awHome) throw new Error('dumpPostInitState: awHome is required');
+
+  const writer = opts.writer ?? DEFAULT_WRITER;
+  const shell = typeof opts.shell === 'function' ? opts.shell : defaultDumpShell;
+  const configPaths = Array.isArray(opts.configPaths) ? opts.configPaths : [];
+
+  const lines = [];
+  lines.push('─── aw c4 post-init dump ───');
+  lines.push(`harness: ${opts.harness}`);
+  lines.push(`cwd:     ${opts.cwd}`);
+  lines.push(`awHome:  ${opts.awHome}`);
+  lines.push('');
+
+  // gh auth status (token-redacted).
+  lines.push('$ gh auth status --hostname github.com');
+  const ghAuth = shell('gh auth status --hostname github.com');
+  lines.push(redactTokens(ghAuth.stdout || ghAuth.stderr || '<no output>'));
+  lines.push('');
+
+  // git remote -v.
+  lines.push(`$ git -C "${opts.cwd}" remote -v`);
+  const remote = shell(`git -C "${opts.cwd}" remote -v`);
+  lines.push(redactTokens(remote.stdout || '<none>'));
+  lines.push('');
+
+  // Config-file enumeration — keys only, no values (some keys carry secrets).
+  for (const cfg of configPaths) {
+    lines.push(`$ keys-of ${cfg}`);
+    lines.push(...enumerateConfigKeysOnly(cfg));
+    lines.push('');
+  }
+
+  // Registry SKILL.md sample (first 10).
+  lines.push(`$ find ${opts.awHome}/.aw_registry -name SKILL.md | head -10`);
+  for (const skillPath of sampleRegistrySkillPaths(opts.awHome, 10)) {
+    lines.push(`  ${skillPath}`);
+  }
+  lines.push('─── end ───');
+  lines.push('');
+
+  writer.stderr(lines.join('\n'));
+}
+
+function redactTokens(text) {
+  if (typeof text !== 'string') return '';
+  return text.replace(TOKEN_PATTERN, (m) => `${m.slice(0, 4)}\u2026`);
+}
+
+function enumerateConfigKeysOnly(filePath) {
+  if (!existsSync(filePath)) return ['  <file missing>'];
+  let body;
+  try {
+    body = readFileSync(filePath, 'utf8');
+  } catch {
+    return ['  <unreadable>'];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return ['  <not JSON; key enumeration skipped>'];
+  }
+  if (parsed == null || typeof parsed !== 'object') {
+    return ['  <empty or non-object>'];
+  }
+  const out = [];
+  for (const [k, v] of Object.entries(parsed)) {
+    if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(`  ${k} (${Object.keys(v).length} nested keys)`);
+    } else if (Array.isArray(v)) {
+      out.push(`  ${k} (array, ${v.length} entries)`);
+    } else {
+      out.push(`  ${k}`);
+    }
+  }
+  return out;
+}
+
+function sampleRegistrySkillPaths(awHome, max) {
+  const root = join(awHome, '.aw_registry/platform');
+  if (!existsSync(root)) return ['  <registry not provisioned>'];
+  const out = [];
+  walkSkillMd(root, out, max);
+  return out.length > 0 ? out : ['  <no SKILL.md files>'];
+}
+
+function walkSkillMd(dir, out, max) {
+  if (out.length >= max) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // readdir failed on a nested registry dir (EACCES, ENOENT, broken
+    // symlink target). Skip silently — the dump is best-effort triage.
+    return;
+  }
+  for (const e of entries) {
+    if (out.length >= max) return;
+    const p = join(dir, e.name);
+    if (e.isFile() && e.name === 'SKILL.md') {
+      out.push(p);
+    } else if (e.isDirectory()) {
+      walkSkillMd(p, out, max);
+    } else if (e.isSymbolicLink()) {
+      // Cheap stat check — symlinks pointing at SKILL.md (the bridge case)
+      // should still appear in the dump.
+      try {
+        const st = statSync(p);
+        if (st.isFile() && e.name === 'SKILL.md') out.push(p);
+        else if (st.isDirectory()) walkSkillMd(p, out, max);
+      } catch {
+        // Broken symlink — skip.
+      }
+    }
+  }
+}