@polygraph/cursor-plugin 0.4.51

package/hooks/agent-session-link.mjs

@@ -0,0 +1,163 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+
+const AGENT_TYPES = new Set(['claude', 'codex', 'opencode', 'cursor']);
+const COMMAND_HOOK_TOOL = /^mcp__(?:plugin_polygraph_)?polygraph[-_]mcp__/;
+const OPENCODE_TOOL = /^polygraph(?:(?:-|_)mcp)?_/;
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function isManagedChildEnvironment(env) {
+  return Boolean(env && Object.hasOwn(env, 'POLYGRAPH_CHILD_AGENT'));
+}
+
+export function isPolygraphMcpToolName(toolName) {
+  const name = nonEmptyString(toolName);
+  return Boolean(name && (COMMAND_HOOK_TOOL.test(name) || OPENCODE_TOOL.test(name)));
+}
+
+export function buildLinkAgentSessionArgs({
+  polygraphSessionId,
+  agentType,
+  agentSessionId,
+  cwd,
+  transcriptPath,
+  pid,
+  source,
+}) {
+  const session = nonEmptyString(polygraphSessionId);
+  const harnessSession = nonEmptyString(agentSessionId);
+  const claimSource = nonEmptyString(source);
+  if (!AGENT_TYPES.has(agentType)) throw new Error(`Unsupported agent type: ${agentType}`);
+  if (!harnessSession) throw new Error('agentSessionId is required');
+  if (!claimSource) throw new Error('source is required');
+
+  const args = ['_link-agent-session'];
+  if (session) args.push('--session', session);
+  args.push('--agent-type', agentType, '--agent-session-id', harnessSession);
+
+  const workingDirectory = nonEmptyString(cwd);
+  if (workingDirectory) args.push('--cwd', workingDirectory);
+
+  const transcript = nonEmptyString(transcriptPath);
+  if (transcript) args.push('--transcript-path', transcript);
+
+  if (Number.isSafeInteger(pid) && pid > 0) {
+    args.push('--pid', String(pid));
+  }
+
+  args.push('--source', claimSource);
+  return args;
+}
+
+export function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
+  if (isManagedChildEnvironment(env)) return false;
+
+  const args = buildLinkAgentSessionArgs(claim);
+  const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? 'polygraph';
+  const commandEnv = nonEmptyString(claim.polygraphSessionId) ? env : { ...env };
+  if (commandEnv !== env) {
+    delete commandEnv.POLYGRAPH_SESSION_ID;
+    delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+  }
+
+  const result = spawn(command, args, {
+    encoding: 'utf8',
+    env: commandEnv,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+
+  if (result?.error) throw result.error;
+  if (result?.status !== 0) {
+    const detail = nonEmptyString(result?.stderr);
+    throw new Error(
+      `polygraph _link-agent-session exited with status ${String(result?.status)}` +
+        (detail ? `: ${detail}` : '')
+    );
+  }
+
+  return true;
+}
+
+export function buildCommandHookLink(payload, agentType, env = process.env) {
+  if (!payload || typeof payload !== 'object') return undefined;
+  if (isManagedChildEnvironment(env)) return undefined;
+
+  // Cursor payloads carry the id in both session_id and conversation_id;
+  // the fallback keeps the link working if one of them disappears.
+  const agentSessionId =
+    nonEmptyString(payload.session_id) ?? nonEmptyString(payload.conversation_id);
+  if (!agentSessionId) return undefined;
+
+  // Cursor has no top-level cwd; workspace_roots[0] is the launch directory.
+  const workspaceRoot = Array.isArray(payload.workspace_roots)
+    ? nonEmptyString(payload.workspace_roots[0])
+    : undefined;
+
+  const common = {
+    agentType,
+    agentSessionId,
+    cwd: nonEmptyString(payload.cwd) ?? workspaceRoot,
+    transcriptPath: nonEmptyString(payload.transcript_path),
+    source: 'hook',
+  };
+
+  // Claude and Codex send PascalCase event names; cursor sends camelCase.
+  if (
+    payload.hook_event_name === 'SessionStart' ||
+    payload.hook_event_name === 'sessionStart'
+  ) {
+    const polygraphSessionId = nonEmptyString(env.POLYGRAPH_SESSION_ID);
+    if (polygraphSessionId) return { ...common, polygraphSessionId };
+
+    // Ordinary sessions of every supported harness are eligible for
+    // speculative capture, so later session searches can find them even when
+    // the session was not launched with Polygraph session evidence.
+    return AGENT_TYPES.has(agentType) ? common : undefined;
+  }
+
+  if (payload.hook_event_name === 'PostToolUse') {
+    return isPolygraphMcpToolName(payload.tool_name) ? common : undefined;
+  }
+
+  return undefined;
+}
+
+export function logHookFailure(
+  hook,
+  error,
+  meta = {},
+  home = process.env.HOME?.trim() || homedir()
+) {
+  try {
+    const logsDir = join(home, '.polygraph', 'logs');
+    mkdirSync(logsDir, { recursive: true });
+    const logFile = join(logsDir, 'hooks.log');
+
+    try {
+      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync(logFile, `${logFile}.1`);
+      }
+    } catch {
+      // There may be no prior log, and logging must stay best-effort.
+    }
+
+    const entry = {
+      time: new Date().toISOString(),
+      hook,
+      pid: process.pid,
+      ...meta,
+      error: error instanceof Error ? error.message : String(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+    appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch {
+    // Hook diagnostics must never break the harness event that triggered them.
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node hooks/record-session-mapping.mjs cursor"
+      }
+    ]
+  }
+}

package/hooks/record-session-mapping.mjs

@@ -0,0 +1,62 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildCommandHookLink,
+  linkAgentSession,
+  logHookFailure,
+} from './agent-session-link.mjs';
+
+function readPayload() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  env = process.env,
+  pid = process.ppid,
+  spawn,
+} = {}) {
+  try {
+    const link = buildCommandHookLink(payload, agentType, env);
+    if (!link) return false;
+
+    const claim = {
+      ...link,
+      cwd: link.cwd ?? process.cwd(),
+    };
+    // Claude lifecycle hooks deliberately forward only the exact harness
+    // identity, transcript, cwd, and hook source. PID is not identity and can
+    // be stale by the time an asynchronous SessionStart hook runs.
+    if (!(agentType === 'claude' && payload?.hook_event_name === 'SessionStart')) {
+      claim.pid = pid;
+    }
+
+    return linkAgentSession(claim, spawn, env);
+  } catch (error) {
+    logHookFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: payload?.session_id,
+    });
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@polygraph/cursor-plugin",
+  "version": "0.4.51",
+  "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
+  "license": "UNLICENSED",
+  "private": false,
+  "author": {
+    "name": "Narwhal Technologies Inc",
+    "email": "hello@nrwl.io",
+    "url": "https://nx.dev"
+  },
+  "homepage": "https://github.com/nrwl/polygraph-skills#readme",
+  "repository": "https://github.com/nrwl/polygraph-skills",
+  "keywords": [
+    "claude",
+    "codex",
+    "nx",
+    "opencode",
+    "polygraph",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "plugin.json",
+    "skills/",
+    "agents/",
+    "hooks/",
+    "bin/",
+    "README.md"
+  ],
+  "bin": {
+    "polygraph-cursor-plugin": "./bin/polygraph-cursor-plugin.mjs"
+  }
+}

package/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "polygraph",
+  "version": "0.4.51",
+  "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination"
+}

package/skills/adversarial-review/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: adversarial-review
+description: Review a Polygraph session with independent per-repo reviewers and attach one consolidated review artifact.
+
+---
+
+# Adversarial Review
+
+1. Skip this step entirely if a reviewer agent was already named — by the user, or in the instruction that launched you (e.g. from `polygraph session review --adversarial`); in that case use that agent and do not ask. Otherwise, **pick the agent**: Ask which should review—`claude`, `codex`, or `opencode` for `spawn_agent`'s `agent` parameter. If the user names a model, pass it via `spawn_agent`'s optional `model` parameter; don't ask about models.
+2. **Get the session description.**
+3. **Get each repo's plan.**
+4. **Delegate one reviewer per repo** in parallel, `role: "reviewer"`. Ask to review, identify issues. Do the delegation even for the "initiator" repo.
+5. **Summarize and attach.** Consolidate reviews into one consolidated Markdown review with per-repo sections and present it to the user. Then call `upload_artifact` once with `sessionId`, that review as `content`, `kind: "review"`, `format: "markdown"`, name `adversarial-review-YYYY-MM-DDTHH-mm-ssZ.md`. If the upload fails, report that separately without suppressing the review.
+6. **Ask what next.** Address feedback or continue. Skip if the user already said.
+7. If the user selects "address the feedback", pass each repo's feedback to the repo default agent (not the reviewer). The initiator should fix things itself without delegating.

package/skills/await-polygraph-ci/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: await-polygraph-ci
+description: Wait for CI to settle across all repos in a Polygraph session, then report results and investigate failures. USE WHEN user says "await polygraph", "wait for polygraph ci", "polygraph ci status", "check polygraph ci", "watch polygraph session", "monitor polygraph".
+
+---
+
+# Await Polygraph CI
+
+Wait for all CI pipelines in a Polygraph session to reach a stable state (succeeded, failed, etc.), then produce a unified summary. If any pipelines failed, investigate via child agents and present fix options.
+
+Some Polygraph tools have both MCP and CLI equivalents — use whichever is available in your environment. See the polygraph skill's tool table for the full mapping.
+
+## CI status source
+
+CI polling uses the polygraph-mcp `show_session` tool, which now carries per-PR CI status directly on each pull request:
+
+```
+show_session(sessionId: "<session-id>")
+```
+
+It returns the full session, including `repositories[]` (for repo display names) and `pullRequests[]`. Each `pullRequests[]` entry has `id`, `repositoryId`, `url`, `branch`, `status` (PR status: `DRAFT` / `OPEN` / `MERGED` / `CLOSED`), and a `ci` object — **`ci` may be absent if the PR has no CI**. When present, `ci` has `status`, `cipeUrl` (non-null ⇒ CIPE; null + `externalCIRuns` ⇒ external CI), `completedAt`, `selfHealingStatus`, and `externalCIRuns[]` (each with `runId`, `name`, `status`, `conclusion`, `url`, and `jobs[]`). Always read `ci` defensively (`pr.ci?.…`).
+
+**`cipeUrl` is a human-facing web link, NOT a data source.** It points at the Nx Cloud web app, which requires browser authentication and returns no machine-readable data. Never fetch, curl, WebFetch, or poll `cipeUrl` (or any other Nx Cloud URL) directly. CI *status* comes only from polling `show_session`; CIPE *details* (failed tasks, logs, self-healing) come only from the Nx MCP `ci_information` tool. The only thing to do with `cipeUrl` is display it to the user so they can open it in a browser.
+
+## Prerequisite: Nx MCP server (CIPE deep-dive + self-healing)
+
+CIPE failure investigation (`ci_information`) and applying/rejecting self-healing fixes (`update_self_healing_fix`) are **not** polygraph-mcp tools — they are provided by the **Nx MCP server** (`mcp__plugin_nx_nx-mcp`). Before relying on the Phase 4 CIPE deep-dive or the Phase 5 self-healing actions, install the Nx MCP server and verify it is available.
+
+If the Nx MCP server is **not** available, this skill can still:
+
+- Monitor CI to a terminal state (Phases 1–3) via `show_session`, and
+- Download and inspect **external-CI** job logs via `get_ci_logs` (a polygraph-mcp tool).
+
+But it **cannot** perform CIPE deep-dives (`ci_information`) or apply self-healing fixes (`update_self_healing_fix`) without the Nx MCP server. Do NOT compensate by fetching or scraping `cipeUrl` — there is no HTTP fallback for CIPE data; the Nx MCP server is the only programmatic access.
+
+If nx-mcp is missing, don't just report the limitation — tell the user how to install it:
+
+- In an Nx workspace, run `nx configure-ai-agents` — it sets up the Nx MCP server (and Nx agent skills) for their AI tools, or
+- Add the server manually as a stdio MCP server: `npx nx-mcp@latest` (see https://github.com/nrwl/nx-ai-agents-config for details).
+
+MCP servers load at session start, so the user must restart the agent session after installing before the deep-dive and self-healing actions become available.
+
+## Phase 1: Session Setup
+
+Fetch the session using `show_session` and read per-PR CI status from `pullRequests[]`.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+
+```
+show_session(sessionId: "<session-id>")
+```
+
+1. Record `monitorStartedAt` = current timestamp (epoch millis).
+2. Build a tracking table from `pullRequests[]`. For each PR, map:
+   - `repo`: repository display name from the matching `repositories[]` entry by `pr.repositoryId` (fall back to `pr.branch` if not found)
+   - `repoId`: `pr.repositoryId` (pass straight to `get_ci_logs`)
+   - `prUrl`: `pr.url`
+   - `prStatus`: `pr.status` (DRAFT / OPEN / MERGED / CLOSED)
+   - `ciStatus`: `pr.ci?.status` (may already be a terminal status from a previous run)
+   - `cipeUrl`: `pr.ci?.cipeUrl` (null if none → external CI or no CI)
+   - `cipeCompletedAt`: `pr.ci?.completedAt` (epoch millis, null if CIPE is active or absent)
+   - `selfHealingStatus`: `pr.ci?.selfHealingStatus` (null if none)
+   - `jobs`: `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)` (external-CI job list, used in Phase 4)
+   - `firstSeenAt`: current timestamp
+3. If `pullRequests[]` is empty, report "No PRs in session" and exit.
+4. **Stale detection**: For each PR, determine if its CI status is **stale** — meaning it reflects a previous run, not a current one. A PR's CI status is stale if:
+   - `cipeCompletedAt` is non-null AND `cipeCompletedAt < monitorStartedAt` (the CIPE finished before the monitor started)
+   - Mark these PRs as `stale: true`
+5. Display the initial status table, annotating stale PRs:
+   ```
+   backend: SUCCEEDED (stale) | frontend: SUCCEEDED (stale) | shared-lib: NOT_STARTED
+   ```
+
+## Phase 2: Polling Loop
+
+**Configuration:**
+
+- Timeout: 30 minutes total
+- Backoff: 60s → 90s → 120s (cap)
+- Circuit breaker: exit after 5 consecutive polls with no status change
+
+**Each poll iteration:**
+
+1. Call `show_session(sessionId: <session-id>)`
+2. Update each tracked PR from its matching `pullRequests[]` entry (by PR `id` / `repositoryId`): `ciStatus` ← `pr.ci?.status`, `cipeUrl` ← `pr.ci?.cipeUrl`, `cipeCompletedAt` ← `pr.ci?.completedAt`, `selfHealingStatus` ← `pr.ci?.selfHealingStatus`, `prStatus` ← `pr.status`, and `jobs` ← `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)`
+3. **Clear stale flag**: If a PR was marked `stale: true` and its `cipeCompletedAt` has changed (or become null, meaning a new CIPE is active), clear the stale flag — this PR now has fresh CI data.
+4. Display status update:
+   ```
+   [await-polygraph-ci] Poll #N | Elapsed: Xm | Repos: Y total, Z completed
+    backend: SUCCEEDED | frontend: FAILED (self-healing: PENDING) | shared-lib: SUCCEEDED (stale)
+   ```
+   Include `selfHealingStatus` inline when non-null. Annotate stale PRs.
+5. Check exclusion rule: if a PR has `prStatus: DRAFT` and `ciStatus: NOT_STARTED` for more than 5 minutes since `firstSeenAt`, mark it as `EXCLUDED` (DRAFT PRs may not trigger CI)
+6. Check terminal conditions — a PR is terminal when:
+   - It is NOT stale, AND:
+     - CI status is `SUCCEEDED`, `CANCELED`, or `TIMED_OUT`, OR
+     - CI status is `FAILED` AND there is no active self-healing (i.e., `selfHealingStatus` is null or a final state like `APPLIED`, `REJECTED`, `FAILED`)
+   - A `FAILED` PR with `selfHealingStatus` indicating an in-progress fix (e.g., `PENDING`, `IN_PROGRESS`) is NOT terminal — keep polling to track the self-healing outcome
+   - A **stale** PR is NOT terminal — keep polling until it gets a fresh CIPE or is excluded
+7. **Stale timeout**: If a stale PR remains stale for more than 5 minutes, assume no new CI is expected for it. Clear the stale flag and treat its current status as final.
+8. If all non-excluded PRs are terminal → proceed to Phase 3
+9. If timeout or circuit breaker hit → proceed to Phase 3 with partial results
+10. Otherwise → wait with backoff, then poll again
+
+## Phase 3: Results Analysis
+
+Categorize repos into: succeeded, failed, canceled, timed_out, excluded, in_progress (if timed out).
+
+Display final summary table. When showing self-healing status, distinguish clearly between these states:
+
+- `COMPLETED` = a fix was **generated and verified**, but **NOT yet applied**. Display as `fix available`.
+- `APPLIED` = the fix was **applied** by the user or agent. Display as `fix applied, awaiting re-run`.
+- `IN_PROGRESS` / `PENDING` = the fix is still being generated. Display as `in progress`.
+- `REJECTED` = the fix was rejected. Display as `fix rejected`.
+- `FAILED` = self-healing failed to produce a fix. Display as `fix failed`.
+
+```
+[await-polygraph-ci] Final Results | Elapsed: Xm
+ SUCCEEDED: backend, shared-lib
+ FAILED: frontend (self-healing: fix available)
+ EXCLUDED: docs (DRAFT, no CI)
+```
+
+Include self-healing status for any repo that has one.
+
+- If all succeeded → report success and exit
+- If any failed with `selfHealingStatus: APPLIED`, inform the user that the fix was applied and a CI re-run may be in progress or needed
+- If any failed with `selfHealingStatus: COMPLETED`, inform the user that a fix is **available but not yet applied**, and offer to apply it
+- If any failed → proceed to Phase 4
+
+## Phase 4: Failure Investigation (Child Agent Delegation)
+
+For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show_session` (`pullRequests[]`):
+
+- **If `pr.ci.cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using the Nx MCP `ci_information` tool (requires the Nx MCP server — see the prerequisite note above; if nx-mcp is unavailable, report the CIPE URL to the user, offer the install steps from the prerequisite section, and do NOT fetch the URL as a substitute).
+- **If `pr.ci.cipeUrl` is null but `pr.ci.externalCIRuns` exists** → external CI only. Examine failed jobs from `pr.ci.externalCIRuns[].jobs` and use `get_ci_logs(sessionId, repositoryId, jobId)` (a polygraph-mcp tool) for log retrieval, passing `pr.repositoryId` and the failed job's `jobId` straight from the same PR object.
+
+1. Display known info from the PR's `ci` object before delegating:
+
+   ```
+   Repository: frontend
+   CI Source: <CIPE or External CI (GitHub Actions)>
+   CI Pipeline: <pr.ci.cipeUrl, or GitHub Actions run URL>
+   Self-healing: <pr.ci.selfHealingStatus, or "None">
+   Investigating failure details...
+   ```
+
+2. **Delegate investigation** (non-blocking) — call `spawn_agent` for each failed repo:
+
+   - `sessionId`: the session ID
+   - `repo`: the repository name
+   - `instruction` (when CIPE exists): Use the Nx MCP `ci_information` tool to investigate the CI failure on this branch (the Nx MCP server must be installed). Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
+   - `instruction` (when no CIPE, external CI only): The PR's `ci` object shows external CI failures with these failed jobs: [list `jobId` + `name` from `pr.ci.externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repositoryId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
+   - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is the PR's `repositoryId`.
+
+   Since `spawn_agent` is non-blocking, you can delegate to multiple failed repos in parallel.
+
+3. **Monitor investigation progress** — launch one background `polygraph-delegate-subagent` per delegation id and let it do the waiting. When it exits, read that investigation with a single unwaited `show_agent`:
+
+   ```
+   show_agent(sessionId: "<session-id>", id: "<delegation-id>")
+   ```
+
+   `result.text` is the child's investigation summary. Never run a waited `show_agent` loop here, and do not pass `tail` unless `result.text` alone is insufficient.
+
+4. Collect each child agent's response from its unwaited `show_agent` read. If a child agent fails or gets stuck, use `stop_agent` with its delegation id to terminate it and skip that repo.
+
+5. Display failure summary for each repo:
+
+   ```
+   Repository: frontend
+   CI Pipeline: <cipeUrl>
+   Failed Tasks (2):
+     - frontend:build → TypeScript error in src/app.tsx:42
+     - frontend:test  → 3 test suites failed
+   Category: Build + Test failures
+   Self-healing: <selfHealingStatus>
+   Job Logs: <number of logs retrieved, if any>
+   ```
+
+   If CI job logs were retrieved via `get_ci_logs`, include relevant excerpts (error messages, stack traces) in the summary. Keep excerpts concise — only the most relevant lines.
+
+## Phase 5: Fix Planning
+
+1. Group failures by category (Build, Test, Lint, E2E, Infra)
+2. Identify cross-repo dependency issues (e.g., shared-lib build failure blocking frontend)
+3. Suggest fix order based on dependency graph (upstream repos first)
+4. Present next actions to the user based on self-healing status:
+   - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it. `update_self_healing_fix` is an **Nx MCP** tool (`mcp__plugin_nx_nx-mcp`) — it requires the Nx MCP server. If nx-mcp is unavailable, report that a fix is available but cannot be applied from here, and offer the install steps from the prerequisite section.
+   - If self-healing was already applied → offer to **resume monitoring** to watch the re-triggered CI
+   - **Delegate fixes**: use Polygraph to send fix instructions to child agents (for repos without self-healing or where self-healing was rejected/failed)
+   - **Get more details**: drill into a specific repo's failure
+   - **Exit**: done monitoring
+
+## Notes
+
+- This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, an **Nx MCP** tool that performs an Nx Cloud operation (not a local code change) and requires the Nx MCP server.
+- Both `ci_information` and `update_self_healing_fix` are **Nx MCP** tools (`mcp__plugin_nx_nx-mcp`), not polygraph-mcp tools. Their responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
+- `cipeUrl` is a browser link for the user — never fetch, curl, WebFetch, or poll it (in the main agent or in child agents). CIPE data is only available via the Nx MCP `ci_information` tool.
+- All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
+
+- Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`pr.ci.cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via the Nx MCP `ci_information` tool. Job IDs come from `pr.ci.externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
+- `spawn_agent` is **non-blocking** — it starts the child agent and returns a delegation id immediately. Waiting on that id belongs in a background poller subagent; an unwaited `show_agent` by id returns the result, and `stop_agent` by id terminates a stuck agent.
+- The `show_session` response is compact and safe to poll from the main agent.

package/skills/get-latest-ci/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: get-latest-ci
+description: Fetch the latest CI pipeline execution for the current branch. Returns the most recent CIPE which may be completed, in progress, or null. Use when you need to review CI status, check failures, or inspect CI state.
+
+---
+
+# Get Latest CI Information
+
+Fetch the latest CI pipeline execution for the current branch. This is a **one-shot fetch** — return results immediately. Do NOT poll, loop, or wait for status changes.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+
+## Step 1: Fetch CI Status via Subagent
+
+Call the `ci_information` tool from the nx MCP server with these parameters:
+
+```yaml
+select: 'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning,hints'
+```
+
+If `cipeStatus` is `FAILED` and `selfHealingStatus` is `COMPLETED` or `FAILED` and there are `failedTaskIds`, make a second call with:
+
+```yaml
+select: 'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription'
+```
+
+Only return the first page — do not paginate.
+
+## Step 2: Report Results
+
+Based on the subagent's response, report to the user. Always include the CIPE URL when available.
+
+If the response contains a non-empty `hints` array, include those hints in the output to the user.
+
+### No CIPE found (null/empty response)
+
+```
+[get-latest-ci] No CI pipeline execution found for branch '<branch>'.
+```
+
+### CI Succeeded
+
+```
+[get-latest-ci] CI passed!
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+```
+
+### CI In Progress / Not Started
+
+```
+[get-latest-ci] CI is <IN_PROGRESS|NOT_STARTED>.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+```
+
+If self-healing is also in progress, add:
+
+```
+[get-latest-ci] Self-healing: <selfHealingStatus> | Verification: <verificationStatus>
+```
+
+### CI Failed — With Self-Healing Fix Available
+
+When `cipeStatus == 'FAILED'` AND `selfHealingStatus == 'COMPLETED'` AND `suggestedFix != null`:
+
+```
+[get-latest-ci] CI failed.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+[get-latest-ci] Failed tasks: <failedTaskIds>
+[get-latest-ci]
+[get-latest-ci] Self-healing fix available!
+[get-latest-ci] Short link: <shortLink>
+[get-latest-ci] Confidence: <confidence> — <confidenceReasoning>
+[get-latest-ci] Verification: <verificationStatus>
+[get-latest-ci] Auto-apply eligible: <couldAutoApplyTasks>
+[get-latest-ci]
+[get-latest-ci] Fix description: <suggestedFixDescription>
+[get-latest-ci] Fix reasoning: <suggestedFixReasoning> (truncated to first page)
+```
+
+### CI Failed — Self-Healing In Progress
+
+When `cipeStatus == 'FAILED'` AND `selfHealingStatus == 'IN_PROGRESS'`:
+
+```
+[get-latest-ci] CI failed. Self-healing is generating a fix...
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+[get-latest-ci] Failed tasks: <failedTaskIds>
+[get-latest-ci]
+[get-latest-ci] Use /monitor-ci to wait for the fix and apply it.
+```
+
+### CI Failed — Self-Healing Failed or Not Available
+
+When `cipeStatus == 'FAILED'` AND (`selfHealingStatus` is `FAILED`, `NOT_EXECUTABLE`, or `null`):
+
+```
+[get-latest-ci] CI failed.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+[get-latest-ci] Failed tasks: <failedTaskIds>
+[get-latest-ci] Self-healing: <selfHealingStatus or "not available">
+[get-latest-ci] Classification: <failureClassification>
+```
+
+If `taskOutputSummary` was fetched, include a brief summary of failures.
+
+### CI Failed — Environment Issue
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+```
+[get-latest-ci] CI failed due to environment issue.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Classification: ENVIRONMENT_STATE
+[get-latest-ci]
+[get-latest-ci] Use /monitor-ci to request an environment rerun.
+```
+
+### CI Canceled / Timed Out
+
+```
+[get-latest-ci] CI was <CANCELED|TIMED_OUT>.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+```
+
+### CI Failed — No Tasks Recorded
+
+When `cipeStatus == 'FAILED'` AND `failedTaskIds` is empty AND `selfHealingStatus` is null:
+
+```
+[get-latest-ci] CI failed but no Nx tasks were recorded (likely infrastructure issue).
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Check CI provider logs for details.
+```
+
+## Important
+
+- This skill is **read-only**. Do NOT apply fixes, push code, or modify anything.
+- `cipeUrl` and `shortLink` are human-facing web links — include them in the output for the user to open in a browser, but never fetch, curl, or poll them yourself. All CIPE data comes from the Nx MCP `ci_information` tool.
+
+- If the user wants to act on the results (apply a fix, monitor, etc.), suggest `/monitor-ci`.
+- If the subagent returns an error, report it and suggest the user check their Nx Cloud connection.