@polygraph/claude-plugin 0.4.37 → 0.4.39

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/hooks/check-plugin-version.mjs

@@ -0,0 +1,294 @@
+// SessionStart hook — checks whether the installed Polygraph plugin is
+// outdated and, when it is, emits a single stdout message so the agent
+// surfaces the problem to the user. Stale plugin versions have silently
+// caused incorrect Polygraph behavior in the past; this makes it visible
+// for agent launches that bypass the polygraph CLI (e.g. desktop apps).
+//
+// Unlike the sibling hooks, this one deliberately writes to stdout — but
+// ONLY when the plugin is outdated. When current, unknown, offline, or on
+// any error it prints nothing and exits 0.
+//
+// The harness ('claude' | 'codex') is passed as the first CLI argument so
+// the same script ships in both plugin artifacts.
+
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+const PACKAGE_BY_HARNESS = {
+  claude: '@polygraph/claude-plugin',
+  codex: '@polygraph/codex-plugin',
+};
+
+const REMEDIATION_BY_HARNESS = {
+  claude: 'run `claude plugins update polygraph@polygraph-plugins`',
+  codex:
+    'run `npx --prefer-online @polygraph/codex-plugin@latest install` then `codex plugin add polygraph@polygraph-plugins`',
+};
+
+// Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
+// This hook swallows its errors silently, so this on-disk log is the only
+// record that something went wrong. The logger is itself failure-proof.
+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 {
+      // no prior log, or rotation failed — ignore
+    }
+
+    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 {
+    // Logging must never throw — a failing logger must not break the hook.
+  }
+}
+
+function tryParseJson(str) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}
+
+function parseSemver(version) {
+  if (typeof version !== 'string') return null;
+  const match = version
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  };
+}
+
+// Returns -1, 0, or 1 when a is lower than, equal to, or higher than b.
+// Returns null when either version is unparseable.
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+
+  for (const key of ['major', 'minor', 'patch']) {
+    if (pa[key] !== pb[key]) return pa[key] < pb[key] ? -1 : 1;
+  }
+
+  // Same core version: a prerelease sorts below a release.
+  if (pa.prerelease.length && !pb.prerelease.length) return -1;
+  if (!pa.prerelease.length && pb.prerelease.length) return 1;
+
+  const len = Math.max(pa.prerelease.length, pb.prerelease.length);
+  for (let i = 0; i < len; i++) {
+    const ia = pa.prerelease[i];
+    const ib = pb.prerelease[i];
+    if (ia === undefined) return -1;
+    if (ib === undefined) return 1;
+    if (ia === ib) continue;
+    const na = /^\d+$/.test(ia) ? Number(ia) : null;
+    const nb = /^\d+$/.test(ib) ? Number(ib) : null;
+    if (na !== null && nb !== null) return na < nb ? -1 : 1;
+    if (na !== null) return -1; // numeric identifiers sort below alphanumeric
+    if (nb !== null) return 1;
+    return ia < ib ? -1 : 1;
+  }
+  return 0;
+}
+
+// Resolve the installed plugin version from the manifest shipped alongside
+// this script: <pluginRoot>/hooks/check-plugin-version.mjs sits next to
+// .claude-plugin/plugin.json (Claude), .codex-plugin/plugin.json (Codex),
+// or package.json.
+export function resolveInstalledVersion(pluginRoot) {
+  const manifests = [
+    join(pluginRoot, '.claude-plugin', 'plugin.json'),
+    join(pluginRoot, '.codex-plugin', 'plugin.json'),
+    join(pluginRoot, 'package.json'),
+  ];
+  for (const manifestPath of manifests) {
+    let raw;
+    try {
+      raw = readFileSync(manifestPath, 'utf8');
+    } catch {
+      continue;
+    }
+    const parsed = tryParseJson(raw);
+    if (parsed && parseSemver(parsed.version)) return parsed.version.trim();
+  }
+  return null;
+}
+
+function cachePath(harness, home) {
+  return join(home, '.polygraph', 'logs', `plugin-version-check-${harness}.json`);
+}
+
+export function readCache(harness, home) {
+  try {
+    return tryParseJson(readFileSync(cachePath(harness, home), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// A cache entry is only trusted when it is recent, was recorded for the
+// currently installed version (updating the plugin invalidates it), and holds
+// either a parseable latest version or null (a negatively-cached failed
+// fetch, so an offline machine does not re-stall on every session start).
+export function isCacheFresh(cache, installed, now) {
+  return Boolean(
+    cache &&
+      Number.isFinite(cache.checkedAt) &&
+      now - cache.checkedAt >= 0 &&
+      now - cache.checkedAt < CACHE_MAX_AGE_MS &&
+      cache.installed === installed &&
+      (cache.latest === null || parseSemver(cache.latest))
+  );
+}
+
+function writeCache(harness, home, entry) {
+  const path = cachePath(harness, home);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmpPath = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(entry) + '\n');
+  renameSync(tmpPath, path);
+}
+
+async function fetchLatestVersion(packageName, fetchImpl) {
+  const registry = (process.env.npm_config_registry?.trim() || DEFAULT_REGISTRY)
+    .replace(/\/+$/, '');
+  const url = `${registry}/-/package/${packageName.replace('/', '%2f')}/dist-tags`;
+  const response = await fetchImpl(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`registry responded ${response.status}`);
+  const distTags = await response.json();
+  return typeof distTags?.latest === 'string' ? distTags.latest : null;
+}
+
+export function buildOutdatedMessage(harness, installed, latest) {
+  return (
+    `The Polygraph plugin is outdated: ${installed} installed, ${latest} latest. ` +
+    'Stale plugin versions cause incorrect Polygraph behavior. ' +
+    `Tell the user to update it now: ${REMEDIATION_BY_HARNESS[harness]} ` +
+    '(or re-run `polygraph config`), then restart the agent session.'
+  );
+}
+
+/**
+ * Check whether the installed plugin is outdated.
+ *
+ * @param {object} opts
+ * @param {string} opts.harness     'claude' | 'codex'
+ * @param {string} opts.pluginRoot  Directory containing the plugin manifest.
+ * @param {string} [opts.home]      Override HOME for testing.
+ * @param {Function} [opts.fetchImpl] Override fetch for testing.
+ * @param {number} [opts.now]       Override the clock for testing.
+ * @returns {Promise<string|null>} The message to emit, or null to stay silent.
+ */
+export async function checkPluginVersion({
+  harness,
+  pluginRoot,
+  home = process.env.HOME?.trim() || homedir(),
+  fetchImpl = fetch,
+  now = Date.now(),
+}) {
+  const packageName = PACKAGE_BY_HARNESS[harness];
+  if (!packageName) return null;
+
+  const installed = resolveInstalledVersion(pluginRoot);
+  if (!installed) return null;
+
+  let latest;
+  const cache = readCache(harness, home);
+  if (isCacheFresh(cache, installed, now)) {
+    if (cache.latest === null) return null;
+    latest = cache.latest;
+  } else {
+    try {
+      latest = await fetchLatestVersion(packageName, fetchImpl);
+    } catch (error) {
+      // Negative cache: remember the failed fetch so an offline machine
+      // does not re-stall for the fetch timeout on every session start.
+      writeCache(harness, home, { checkedAt: now, installed, latest: null });
+      throw error;
+    }
+    if (!parseSemver(latest)) {
+      writeCache(harness, home, { checkedAt: now, installed, latest: null });
+      return null;
+    }
+    writeCache(harness, home, { checkedAt: now, installed, latest });
+  }
+
+  if (compareSemver(installed, latest) === -1) {
+    return buildOutdatedMessage(harness, installed, latest);
+  }
+  return null;
+}
+
+export async function main() {
+  const harness = process.argv[2];
+  try {
+    const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const message = await checkPluginVersion({ harness, pluginRoot });
+    if (message) process.stdout.write(message + '\n');
+  } catch (error) {
+    // Offline or broken registry must never block or pollute the session,
+    // but record it so failures are not invisible.
+    logHookFailure(`${harness || 'unknown'}:check-plugin-version`, error);
+  }
+  process.exitCode = 0;
+}
+
+// Run only when executed directly as a hook, not when imported (e.g. by tests).
+// realpathSync both sides so the check holds when the plugin lives under a
+// symlinked path (e.g. macOS /tmp -> /private/tmp).
+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/hooks/hooks.json

@@ -24,6 +24,15 @@
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/record-session-mapping.mjs claude"
           }
         ]
+      },
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/check-plugin-version.mjs claude"
+          }
+        ]
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,

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

@@ -29,6 +29,8 @@ 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.
@@ -38,7 +40,14 @@ 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. If nx-mcp is missing, state this limitation to the user explicitly.
+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
 
@@ -134,7 +143,7 @@ Include self-healing status for any repo that has one.
 
 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 but note the deep-dive can't run).
+- **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:
@@ -188,7 +197,7 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
 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.
+   - 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
@@ -198,6 +207,7 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
 
 - 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.

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

@@ -153,6 +153,7 @@ When `cipeStatus == 'FAILED'` AND `failedTaskIds` is empty AND `selfHealingStatu
 ## 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.
 
 - Always delegate the MCP call to a subagent. Do NOT call ci_information yourself.
 

package/skills/polygraph/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: polygraph
-description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
+description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; checking CI status and logs; or tracing a commit or line of code back to the session that produced it. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", asks about what other repos are doing with shared code/APIs/endpoints, or asks about a "commit sha", "session behind this commit", "which session changed this line", "find session by sha", "git blame".
 
 allowed-tools:
   - mcp__plugin_polygraph_polygraph-mcp
@@ -61,6 +61,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
 | `logout` | `polygraph auth logout` | Log out of Polygraph |
 | `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
+| `search_sessions` | `polygraph session search` | Find sessions by free-text `query` OR by commit `sha` — pass EXACTLY ONE of the two (they are mutually exclusive). `sha` (CLI: `--sha <sha>`) is an exact lookup of the session(s) linked to a commit, full or partial, 7-40 hex chars; it returns matching sessions newest first, org-scoped, and explicit sessions only (implicit sessions are never returned). Supports `--json` and `--limit` (1-50). See "Finding the Session Behind a Commit or Line". |
 | `list_accounts` | `polygraph account list` | List available organizations |
 | `select_account` | `polygraph account select` | Select the organization that future commands run against |
 | `whoami` | `polygraph whoami` | Show current auth status and org |
@@ -213,6 +214,32 @@ Description:
 Inspect the PR commits/diff and investigate the requested behavior. Report findings with file paths and concrete evidence.
 ```
 
+### Finding the Session Behind a Commit or Line
+
+Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code.
+
+**Given a commit sha.** When the user names a sha, or asks what session is behind a commit, resolve it with `search_sessions` using the `sha` parameter (CLI: `polygraph session search --sha <sha>`):
+
+- Pass **exactly one** of `query` or `sha` — they are mutually exclusive.
+- `sha` accepts a full or partial sha, 7-40 hex chars.
+- The lookup is exact and one-shot: it returns the session(s) linked to that commit, newest first, scoped to the current org, and only explicit sessions.
+
+```
+search_sessions(sha: "a1b2c3d")
+# CLI equivalent:
+polygraph session search --sha a1b2c3d
+```
+
+**Given a line number.** There is no line-number lookup — a line MUST first be resolved to a commit sha with `git blame`, then that sha is fed into the sha lookup:
+
+1. `git blame -L <line>,<line> -- <file>` to get the commit that last touched the line.
+2. Pass that sha to `search_sessions(sha: ...)` (or `polygraph session search --sha <sha>`).
+
+**Reading the results.**
+
+- Multiple sessions may match a sha. They come back newest first — pick the most relevant one and report the others if they matter.
+- **A "no match" result does NOT prove the commit had no work behind it.** Not every commit is linked to an explicit session: commits pushed directly (rather than via an ingested PR) and gaps in ingestion metadata mean the sha may simply not be recorded, and implicit sessions are never returned. Report "no linked session found for that sha" — never assert that no work exists behind the commit.
+
 ## Simple tasks (fire-and-forget)
 
 Use this pattern when the task is well-defined and the child is not expected to need clarification. It is a single-round delegation: kick it off, poll until terminal, then push branch + create PR.
@@ -431,7 +458,7 @@ Check the details of a session using `show_session` or `polygraph session show -
   - `relatedPRs`: Array of related PR URLs across repos
 - `session.ciStatus`: CI pipeline status keyed by PR ID, each containing:
   - `status`: One of `SUCCEEDED`, `FAILED`, `IN_PROGRESS`, `NOT_STARTED` (null if no CIPE and no external CI)
-  - `cipeUrl`: URL to the CI pipeline execution details (null if no CIPE)
+  - `cipeUrl`: URL to the CI pipeline execution details (null if no CIPE). This is a human-facing Nx Cloud web link — display it to the user, but never fetch, curl, or poll it directly; CIPE data is only accessible programmatically via the Nx MCP `ci_information` tool
   - `completedAt`: Epoch millis timestamp, set only when the CIPE has completed (null otherwise)
   - `selfHealingStatus`: The self-healing fix status string from Nx Cloud's AI fix feature (null if no AI fix exists)
   - `externalCIRuns`: Array of external CI runs (present when no CIPE but external CI data exists, e.g., GitHub Actions). Each run contains:
@@ -601,7 +628,7 @@ archive_session(
 
 Use `get_ci_logs` to retrieve the full plain-text log for a specific CI job. This is the drill-in tool for investigating CI failures after identifying a failed job from the session's CI status.
 
-**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via `ci_information` — do NOT call `get_ci_logs`. This tool is specifically for PRs where only external CI runs exist (e.g., GitHub Actions runs without an Nx Cloud CIPE).
+**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via the Nx MCP `ci_information` tool — do NOT call `get_ci_logs`, and do NOT fetch or poll the `cipeUrl` over HTTP (it is a browser link for the user, not an API). This tool is specifically for PRs where only external CI runs exist (e.g., GitHub Actions runs without an Nx Cloud CIPE).
 
 **Parameters:**
 

package/skills/session-debrief/SKILL.md

@@ -14,14 +14,22 @@ You produce debriefs of PAST Polygraph sessions so a parent agent working on a N
 
 ## Procedure
 
-For each session, in rank order:
+Speed matters: the parent agent keeps working while it waits for you, and it folds your debrief in whenever it lands.
 
-1. `polygraph session show --details <sessionId>` — metadata, description timeline, repositories, PRs.
-2. `polygraph session logs -s <sessionId> --json` — the full parent transcript (`--json` returns the full transcript by default).
-3. If the session delegated work to other repositories (child-agent steps exist), pull those transcripts too: `polygraph session logs -s <sessionId> --all --json`, or `--repo <org/repo> --json` for one repo.
-4. Write the debrief section (format below) before moving to the next session.
+**Single session (the usual case).** The parent normally launches one background debrief agent per related session, so your input will usually contain exactly one session. Run the "Debriefing one session" steps directly — do not spawn a subagent for a single session.
 
-Large transcripts: if the full `--json` output is too large to hold, page with `--tail 200 --page <n>` and prioritize, in order: user prompts, assistant text and final messages, tool errors and failure events, task notifications. Routine tool-use noise (file reads, searches) is safe to skim.
+**Multiple sessions: fan out.** When given more than one session, debrief them CONCURRENTLY, never one after another: spawn one subagent per session, all in a single message so they run in parallel. Give each subagent: its session entry (sessionId, title, url, rank), the current-task statement, the "Debriefing one session" steps, and the per-session output template — copied into its prompt, since it cannot see this skill. Each subagent returns its completed debrief section as its final message. Assemble the returned sections in rank order and return them; do not rewrite them. Only if your environment cannot spawn subagents, run the "Debriefing one session" steps yourself, sequentially in rank order.
+
+### Debriefing one session
+
+Invoke the CLI as `${POLYGRAPH_CLI:-polygraph}` in every command: when the session was launched from a specific CLI build, `POLYGRAPH_CLI` points at it and children must use the same one. When you copy these steps into a subagent prompt, keep the `${POLYGRAPH_CLI:-polygraph}` form verbatim.
+
+1. `${POLYGRAPH_CLI:-polygraph} session show --details <sessionId>` — metadata, description timeline, repositories, PRs. The description timeline often already summarizes goals and outcomes; mine it before reading transcripts.
+2. Duplicate-work check: if the metadata shows this session pursuing the SAME task as the current one (not merely related work) and it is unfinished or recently active, do NOT read the transcripts. Return the debrief section immediately, with `**DUPLICATE WORK IN FLIGHT**` as the first line after the heading, followed by the session's status and last activity, one line of evidence for the match, and what resuming it would restore. The parent halts and asks the user to choose between resuming that session and continuing the current one, so speed matters more than depth here.
+3. `${POLYGRAPH_CLI:-polygraph} session logs -s <sessionId> --all --tail none > "$TMPDIR/<sessionId>-logs.txt" 2>&1` — the parent transcript plus every child transcript, rendered as plain text, in ONE call. Then read the file directly (with offsets for large files). Do NOT fetch `--json` and do NOT query the transcript with node/python one-liners — reading the rendered text is faster and you extract while reading.
+4. Write the debrief section (format below).
+
+Large transcripts: read the file in a few large chunks, prioritizing user prompts, assistant text and final messages, tool errors and failure events, and task notifications. Routine tool-use noise (file reads, searches) is safe to skim. Do not make repeated small queries against the transcript; each round trip costs more than reading a bigger chunk.
 
 ## Output
 
@@ -29,6 +37,7 @@ Return ONE consolidated debrief as your final message — it is consumed by the
 
 ### Rank N — <session title> (<sessionId>)
 
+**DUPLICATE WORK IN FLIGHT** — only when the duplicate-work check fired: status, last activity, one-line evidence. Omit this line otherwise.
 **URL:** <session url>
 **Goal:** what the session set out to do.
 **What happened:** condensed narrative of the work performed.
@@ -44,3 +53,5 @@ Return ONE consolidated debrief as your final message — it is consumed by the
 - If a session's logs are hidden or unavailable, say which (`hidden: true` in the CLI output means hidden by the author; empty steps mean no logs uploaded) and debrief from `session show --details` metadata, description timeline, and PRs alone.
 - No speculation: when the transcript does not show why a decision was made, write "rationale not recorded".
 - Read-only: the inspected sessions must be byte-for-byte unaffected by your work.
+- Session data only: debrief from what the CLI and MCP tools return (metadata, description timeline, transcripts, PRs). Do NOT read repository code, run git or gh, or fetch PR diffs to verify claims — report what the session shows and leave verification to the parent.
+- Fail fast: if a CLI command errors, retry it once at most, then report the error verbatim in your debrief section and move on. Do not build workarounds (no copying auth/config to a fake HOME, no POLYGRAPH_ROOT redirection, no privilege or sandbox escapes) — a debrief that says "logs unavailable: <error>" is more useful than one that arrives late.