@polygraph/codex-plugin 0.4.45 → 0.4.46

package/.codex-plugin/plugin.json

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

package/hooks/agent-session-link.mjs

@@ -0,0 +1,146 @@
+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']);
+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;
+
+  const agentSessionId = nonEmptyString(payload.session_id);
+  if (!agentSessionId) return undefined;
+
+  const common = {
+    agentType,
+    agentSessionId,
+    cwd: nonEmptyString(payload.cwd),
+    transcriptPath: nonEmptyString(payload.transcript_path),
+    source: 'hook',
+  };
+
+  if (payload.hook_event_name === 'SessionStart') {
+    const polygraphSessionId = nonEmptyString(env.POLYGRAPH_SESSION_ID);
+    return polygraphSessionId ? { ...common, polygraphSessionId } : 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

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "mcp__plugin_polygraph_.*|mcp__polygraph.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${PLUGIN_ROOT}/hooks/record-session-mapping.mjs codex",
+            "statusMessage": "Linking Polygraph agent session"
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "startup|resume|compact",
@@ -12,7 +24,7 @@
           {
             "type": "command",
             "command": "node ${PLUGIN_ROOT}/hooks/record-session-mapping.mjs codex",
-            "statusMessage": "Recording Polygraph agent capture mapping"
+            "statusMessage": "Linking Polygraph agent session"
           }
         ]
       }

package/hooks/record-session-mapping.mjs

@@ -1,263 +1,54 @@
-// Hidden SessionStart hook — records an agent-capture mapping file that binds
-// this agent's session id to the Polygraph session id in the environment.
-// Used by both the Claude Code plugin (agentType=claude) and the Codex plugin
-// (agentType=codex). The agentType is passed as the first CLI argument so the
-// same script ships in both plugin artifacts.
-//
-// File contract (must match the Polygraph CLI reader exactly):
-//   <sessionsRoot>/<POLYGRAPH_SESSION_ID>/sidecars/mapping-<agentType>-<agentSessionId>.json
-//     where sessionsRoot = $POLYGRAPH_ROOT, else `globalRoot` from
-//     ~/.polygraph/config.json, else ~/.polygraph/sessions
-//   Legacy fallback, used ONLY when <sessionsRoot>/<POLYGRAPH_SESSION_ID>
-//   does not exist (for real sessions nothing new is written here):
-//   ~/.polygraph/sidecars/<POLYGRAPH_SESSION_ID>/mapping-<agentType>-<agentSessionId>.json
-//
-// The session folder is a trustworthy location for this parent-transcript
-// binding because the Polygraph CLI's child-agent sandboxes exclude the
-// session root — children cannot write there. The CLI reads mappings from
-// the session folder first, with the flat dir as a read-only fallback.
-//
-// Behaviour:
-//   - Silent no-op when POLYGRAPH_SESSION_ID is unset.
-//   - Silent no-op when POLYGRAPH_CHILD_AGENT is set (child agents must not
-//     register themselves as parents).
-//   - Atomic write: write to <path>.tmp-<pid>, then rename over final path.
-//   - Refresh: when a valid prior mapping for the same session already exists
-//     (checked in the new location first, then the legacy flat dir), preserve
-//     its firstSeenAt and only update lastSeenAt + mutable fields — so
-//     migrating a mapping from the legacy dir keeps firstSeenAt continuity.
-//   - All failures are silently swallowed; never writes to stdout (Claude Code
-//     injects hook stdout into the model context); never exits non-zero.
-
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  realpathSync,
-  renameSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
-
-// Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
-// This hook swallows its errors silently and must never write to stdout (Claude
-// Code injects hook stdout into the model context), 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 readStdin() {
-  try {
-    return readFileSync(0, 'utf8');
-  } catch {
-    return '';
-  }
-}
+import {
+  buildCommandHookLink,
+  linkAgentSession,
+  logHookFailure,
+} from './agent-session-link.mjs';
 
-function tryParseJson(str) {
+function readPayload() {
   try {
-    return JSON.parse(str);
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
   } catch {
-    return null;
+    return undefined;
   }
 }
 
-function sanitizeFilename(str) {
-  return str.replace(/[^A-Za-z0-9._-]/g, '_');
-}
-
-// Resolve the root directory that holds per-session folders:
-// $POLYGRAPH_ROOT, else `globalRoot` from ~/.polygraph/config.json, else
-// ~/.polygraph/sessions. Must match the Polygraph CLI's own resolution.
-export function sessionsRoot(home = process.env.HOME?.trim() || homedir()) {
-  const fromEnv = process.env.POLYGRAPH_ROOT?.trim();
-  if (fromEnv) return fromEnv;
-
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  env = process.env,
+  pid = process.ppid,
+  spawn,
+} = {}) {
   try {
-    const config = tryParseJson(
-      readFileSync(join(home, '.polygraph', 'config.json'), 'utf8')
+    const link = buildCommandHookLink(payload, agentType, env);
+    if (!link) return false;
+
+    return linkAgentSession(
+      {
+        ...link,
+        pid,
+        cwd: link.cwd ?? process.cwd(),
+      },
+      spawn,
+      env
     );
-    if (typeof config?.globalRoot === 'string' && config.globalRoot.trim()) {
-      return config.globalRoot.trim();
-    }
-  } catch {
-    // no config — use the default
-  }
-
-  return join(home, '.polygraph', 'sessions');
-}
-
-/**
- * Write (or refresh) the agent-capture mapping file.
- *
- * Written into the session folder (`<sessionsRoot>/<sessionId>/sidecars/`)
- * when the session directory exists; only when it does not exist does the
- * write fall back to the legacy flat `~/.polygraph/sidecars/<sessionId>/`
- * dir — for real sessions nothing new lands under the flat dir.
- *
- * @param {object} opts
- * @param {string} opts.agentType         'claude' | 'codex'
- * @param {string} opts.agentSessionId    The harness's own session id.
- * @param {string} opts.polygraphSessionId Value of POLYGRAPH_SESSION_ID.
- * @param {string} opts.cwd               Agent working directory.
- * @param {string} [opts.transcriptPath]  Absolute transcript path; omit when unknown.
- * @param {number} [opts.pid]             Harness process id; omit when not knowable.
- * @param {string} [home]                 Override HOME for testing.
- */
-export function writeCaptureMapping(
-  { agentType, agentSessionId, polygraphSessionId, cwd, transcriptPath, pid },
-  home = process.env.HOME?.trim() || homedir()
-) {
-  const filenamePart = sanitizeFilename(`${agentType}-${agentSessionId}`);
-  const fileName = `mapping-${filenamePart}.json`;
-
-  const sessionDir = join(sessionsRoot(home), polygraphSessionId);
-  const sessionSidecarDir = join(sessionDir, 'sidecars');
-  const legacyDir = join(home, '.polygraph', 'sidecars', polygraphSessionId);
-
-  // New location when the session directory exists; legacy flat dir only
-  // when it does not.
-  const targetDir = existsSync(sessionDir) ? sessionSidecarDir : legacyDir;
-  mkdirSync(targetDir, { recursive: true });
-
-  const finalPath = join(targetDir, fileName);
-  const tmpPath = `${finalPath}.tmp-${process.pid}`;
-
-  const now = Date.now();
-
-  // Refresh semantics: preserve firstSeenAt from a valid prior mapping.
-  // Check the new location first, then the legacy flat dir — this keeps
-  // firstSeenAt continuity when migrating a mapping from the legacy dir.
-  let firstSeenAt = now;
-  for (const candidate of [
-    join(sessionSidecarDir, fileName),
-    join(legacyDir, fileName),
-  ]) {
-    if (!existsSync(candidate)) continue;
-    const existing = tryParseJson(readFileSync(candidate, 'utf8'));
-    if (
-      existing !== null &&
-      existing.version === 1 &&
-      existing.polygraphSessionId === polygraphSessionId &&
-      existing.agentSessionId === agentSessionId &&
-      Number.isFinite(existing.firstSeenAt)
-    ) {
-      firstSeenAt = existing.firstSeenAt;
-      break;
-    }
-  }
-
-  const mapping = {
-    version: 1,
-    polygraphSessionId,
-    agentType,
-    agentSessionId,
-    cwd,
-    ...(transcriptPath != null ? { transcriptPath } : {}),
-    ...(pid != null ? { pid } : {}),
-    source: 'hook',
-    firstSeenAt,
-    lastSeenAt: now,
-  };
-
-  writeFileSync(tmpPath, JSON.stringify(mapping, null, 2) + '\n');
-  renameSync(tmpPath, finalPath);
-}
-
-export function main() {
-  try {
-    const polygraphSessionId = process.env.POLYGRAPH_SESSION_ID;
-    if (!polygraphSessionId) return;
-    if (process.env.POLYGRAPH_CHILD_AGENT) return;
-
-    const agentType = process.argv[2];
-    if (!agentType) return;
-
-    let payload = {};
-    const raw = readStdin();
-    if (raw) {
-      const parsed = tryParseJson(raw);
-      if (parsed !== null) payload = parsed;
-    }
-
-    const agentSessionId =
-      typeof payload.session_id === 'string' ? payload.session_id : '';
-    if (!agentSessionId) return;
-
-    const cwd =
-      typeof payload.cwd === 'string' && payload.cwd
-        ? payload.cwd
-        : process.cwd();
-
-    // transcript_path is present on Claude/Codex payloads; may be null — omit
-    // the field when absent or null rather than writing null into the mapping.
-    const transcriptPath =
-      typeof payload.transcript_path === 'string' && payload.transcript_path
-        ? payload.transcript_path
-        : undefined;
-
-    writeCaptureMapping({
-      agentType,
-      agentSessionId,
-      polygraphSessionId,
-      cwd,
-      transcriptPath,
-      // process.ppid is the harness pid when the hook is spawned as a child.
-      pid: process.ppid,
-    });
   } catch (error) {
-    // Silent toward the agent — a broken hook must never break the session —
-    // but record it so failures are not invisible.
-    logHookFailure(`${process.argv[2] || 'unknown'}:record-session-mapping`, error);
+    logHookFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: payload?.session_id,
+    });
+    return false;
   }
 }
 
-// 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))
-    );
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
   } catch {
     return false;
   }

package/package.json

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

package/skills/polygraph/SKILL.md

@@ -16,12 +16,11 @@ Read this before the tool table below — it determines which tools are yours to
 - **For new sessions:** call Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"`. Do NOT call Polygraph MCP `list_repos` or `start_session` directly from this conversation.
 - **For explicit repo additions to an existing session:** if the user gives exact refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, call Polygraph MCP `add_repo` directly with those refs. Do NOT call `list_repos` or launch candidate discovery first.
 - **For repo work:** call Codex `spawn_agent` with `agent_type: "polygraph-delegate-subagent"`. Do NOT call Polygraph MCP `spawn_agent` or `show_agent` directly from this conversation; collect results with `wait_agent` when needed.
-- **Allowed direct Polygraph MCP calls from the parent:** `whoami`, `login`, `list_accounts`, `select_account`, `show_session` for read-only inspection of an existing session, `update_session` for session metadata updates, `link_reference` for linking external references to sessions, and `add_repo` only for explicit repo additions to an existing session.
 - Do NOT pass `fork_context: true` to Codex `spawn_agent` when `agent_type` is a custom agent — Codex rejects it.
 
-Polygraph connects repositories and the agent work happening across them. Its central artifact is the session, which groups the repositories, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repositories, and also on its own to share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
+Polygraph connects repos and the agent work happening across them. Its central artifact is the session, which groups the repos, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repos or in a single repoto share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
 
-**Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repositories are worked on in separate Polygraph-managed clones via `spawn_agent`.
+**Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repos are worked on in separate Polygraph-managed clones via `spawn_agent`.
 
 ## Sandboxing in Polygraph Sessions
 
@@ -76,29 +75,28 @@ Use `polygraph whoami` (or the `whoami` MCP tool) before session work to check i
 - If the user **is logged in** and an org is selected → proceed to the workflow.
 - If auth is **missing, expired, or no org is selected** → stop session work. Do not keep trying session creation, repository discovery, delegation, or CI checks.
 - Facilitate user reauth through the browser-based login flow, such as `polygraph auth login` (or the `login` MCP tool). In interactive desktop clients, browser reauth is usually user-driven; surface the need clearly and wait for the user to complete it.
-- After login, an organization must be selected. Use `polygraph account select` (or the MCP equivalent) when needed.
+- After login, an organization must be selected. Use `polygraph account select` (or MCP equivalent) when needed.
 - Re-run `polygraph whoami` (or `whoami`) after reauth and org selection. Continue only after it confirms a valid login and selected organization.
 
 ### Select Organization
 
-After logging in (or if logged in but no org is selected), use `polygraph account select` (or the equivalent MCP tool) to choose the organization that future commands will run against.
+After logging in (or if logged in but no org is selected), use `polygraph account select` (or MCP equivalent) to choose the organization that future commands will run against.
 
 ## Workflow Overview
 
 The delegate/monitor/stop steps apply only when working across repos. A single-repo session skips them and still benefits from shared progress, resume, and CI visibility.
 
-0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly with those refs and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session.
-1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. Delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Parallel delegation across repos is encouraged. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
+0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session.
+1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents. Delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Parallel delegation across repos is encouraged. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
    
 4. **Monitor child agents** - Use `show_agent` to poll one repo's children (`repo` is required; pass `role` to narrow to one agent) and read each entry's `status` and `lastOutputLines` from the `children[]` array.
 5. **Stop child agents** (if needed) - Use `stop_agent` (with `role` when targeting a non-default agent) to cancel an in-progress child agent. The agent's session is preserved for later read-only context restoration; after a resume, wait for explicit user instructions before making changes.
 6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
-7. **Update session description** - Use `update_session` to update the session description; must follow the Session Description Policy. Independent of PR creation or mark-ready.
-8. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
-9. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
-10. **Query PR status** - Use `show_session` to check progress.
-11. **Mark PRs ready** - Use `mark_pr_ready` when work is complete.
-12. **Archive session** - Use `archive_session` to archive the session when the user requests it.
+7. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
+8. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
+9. **Query PR status** - Use `show_session` to check progress.
+10. **Mark PRs ready** - Use `mark_pr_ready` when work is complete.
+11. **Archive session** - Use `archive_session` to archive the session when the user requests it.
 
 ## Step-by-Step Guide
 
@@ -106,7 +104,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
 
 There are three cases. Pick exactly one before calling any tool. The case labels are internal routing shorthand — never mention them in anything you show the user.
 
-**Hard rule: if a session ID is already in scope (e.g., the startup banner says "You're in Polygraph session …", or the user passed one), that session ID is authoritative for this entire conversation. NEVER call `start_session` — doing so creates a brand-new session and orphans the one the parent harness is pointed at. Reuse the existing session via `show_session` and, if needed, `add_repo`.**
+**Hard rule: if a session ID is already in scope (e.g., the startup banner says "You're in Polygraph session …", or the user passed one or you are provided one by a reminder hook), that session ID is authoritative for this entire conversation. NEVER call `start_session` — doing so creates a brand-new session and orphans the one the parent harness is pointed at. Reuse the existing session via `show_session` and, if needed, `add_repo`.**
 
 **Case A — Existing session, already has repos.** Call `show_session` directly with the known session ID. Skip the init subagent entirely, show the session details (format below), and proceed.
 
@@ -119,29 +117,10 @@ In case B, call `add_repo` yourself when exact repo refs were provided; otherwis
 **Session ID handling:**
 
 - For a new session (case C), `start_session` auto-generates a unique session ID. You do NOT need to pass one.
-- For cases A and B, the session ID already exists; reuse it everywhere — never let `start_session` run in this conversation.
+- For cases A and B, the session ID already exists; reuse it everywhere
 - The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
 - For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
 
-**Launch `polygraph-init-subagent`** (cases B and C — skip in case A):
-
-Use Codex's `spawn_agent` tool to start the custom Polygraph init subagent:
-
-```
-spawn_agent(
-  agent_type: "polygraph-init-subagent",
-  message: """
-    Parameters:
-    - sessionId: "<existing-session-id-or-omit-for-new-session>"
-    - userContext: "<description of what the user wants to do>"
-
-    If sessionId is provided, reuse that session and use add_repo to attach repositories — do NOT call start_session. If exact repo refs were provided, pass them directly to add_repo and do NOT call list_repos. If discovery is needed, discover candidates and select relevant repos. If sessionId is omitted, create a new session via start_session. Return a structured summary.
-  """
-)
-```
-
-Omit the `sessionId` line for case C. Include it (with the existing session ID) for case B. When the main flow needs the session before proceeding, collect the result with `wait_agent`.
-
 The subagent will:
 
 1. Use exact repo refs directly when provided for an existing session; otherwise call `list_repos` to discover available repositories
@@ -150,7 +129,7 @@ The subagent will:
 4. Call `show_session` to retrieve session details
 5. Return a summary with session URL and repo info
 
-**When the init subagent has just created a brand-new session,** render the session welcome card instead of the session-details block below. Prefer the `session_intro` MCP tool — call it with the session ID; it returns the card as markdown. If that tool is unavailable, run `polygraph session intro -s <sessionId>` via the CLI instead. The CLI command is intentionally hidden/internal and may not appear in public command listings, but it remains the correct skill fallback for rendering the welcome card. Either way, print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue (ask the user what they want, or start the requested task).
+**When the init subagent has just created a brand-new session,** render the session welcome card instead of the session-details block below. Prefer the `session_intro` MCP tool (or the hidden `polygraph session intro -s <sessionId>` via the CLI) — call it with the session ID; it returns the card as markdown. Print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue.
 
 **For an existing session — after `show_session` returns or the init subagent's summary arrives — show the session details:**
 
@@ -170,7 +149,7 @@ Use this workflow when the user gives a Polygraph session ID and asks to underst
 **Resume is not a work command.** If the user's intent is to resume, reconnect, or reconstruct a prior Polygraph session, fetch and summarize the restored context, then stop. Do not edit files, push branches, add repos, delegate new work, or continue previous changes until the user explicitly asks for changes. Treat "resume" as context restoration followed by waiting for user instructions.
 
 1. Fetch detailed session context:
-   - Prefer `show_session` with `details: true` when the MCP tool exposes that option.
+   - Prefer `show_session` with `details: true` 
    - Otherwise run `polygraph session show --details <session-id>`.
 2. Treat the detailed output as authoritative context. It should include:
    - `<summary>` — the session summary.
@@ -210,29 +189,8 @@ Inspect the PR commits/diff and investigate the requested behavior. Report findi
 
 ### 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.
+Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code. 
+**Read [`reference/session-by-commit.md`](reference/session-by-commit.md) before running any lookup.** That reference file holds clear, reliable steps for answering questions related to this.
 
 ## Agent roles
 
@@ -271,7 +229,7 @@ spawn_agent(
 3. The subagent watches `child.status` on its delegation's `children[]` entry — the one matching its repo and role — and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped).
 4. Collect completed results with `wait_agent` when the main flow needs them, then continue to `push_branch` + `create_pr`.
 
-In rare cases where you need to check the raw child agent status directly (e.g., debugging a stuck subagent), you may call the Polygraph MCP `show_agent` as a one-off tool call. Do NOT use this for regular polling — that belongs inside `polygraph-delegate-subagent`.
+To debug a stuck subagent you can call `show_agent` as a one-off, but routine polling belongs in the background subagents.
 
 Use Simple when the task is well-defined and the child will not need clarification.
 
@@ -326,7 +284,7 @@ Use Multi-turn when the child may need clarification, the task is exploratory, o
 
 Your MCP client supports the native permission dialog. When a child agent requests permission, the dialog renders directly in your UI and the user picks — the decision routes back through `polygraph-mcp` automatically.
 
-**Critical: do NOT call `allow_agent` or `deny_agent` yourself.** If `show_agent` (or `cloud_polygraph_child_status`) briefly reports a child in `permission-required` state with `pendingPermission` populated, that is a transient state the dialog is in the middle of resolving. Your job is to keep polling — the next poll will see the child back in `in-progress` (or `failed` / `cancelled` if the user denied or dismissed).
+**Critical: do NOT call `allow_agent` or `deny_agent` yourself.** If `show_agent` briefly reports a child in `permission-required` state with `pendingPermission` populated, that is a transient state the dialog is in the middle of resolving. Your job is to keep polling — the next poll will see the child back in `in-progress` (or `failed` / `cancelled` if the user denied or dismissed).
 
 If you call `allow_agent` while the dialog is already open, you create a race: the user's pick lands first and the explicit allow fails with `Task <id> is in state 'completed', not 'permission-required'`. The child receives the user's choice; your call is wasted work.
 
@@ -338,30 +296,16 @@ The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do
 
 Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must precede PR creation), `create_pr` (linked draft PRs, including fork PRs via `targetRepository`), `mark_pr_ready` (transition drafts to OPEN), and `associate_pr` (link PRs created outside Polygraph).
 
-**Whenever you push a branch, create or associate a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow: parameters and examples for each tool, `push_branch` local-checkout semantics, the PR title format rules, and the session-URL printing steps. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy below.
+**Whenever you push a branch, create or associate a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow.
 
 ### Session Description Policy
 
 `description` is user-facing Polygraph session context. It is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (`mark_pr_ready` does not take a description).
 
-**Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy: the canonical Markdown-heading template (`## Goal` / `## Current progress` / `## What worked` / `## Next steps`), the dual-audience guidance (humans in the web UI now, agents reconstructing history later), and the formatting building blocks the app renders (callouts, tables, mermaid, links, `link_reference`).
-
-### Get Current Polygraph Session
-
-Check the details of a session using `show_session` or `polygraph session show --details <session-id>`. Returns the full session state — basic metadata like id, url & description timeline, plus the connected repositories, `pullRequests[]`, per-PR `ciStatus`, and `session.linkedReferences`.
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-
-**CI status rules:**
+**Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy.
 
-- `ciStatus[prId].cipeUrl` (null if no CIPE) 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.
-- When no CIPE exists, external CI data (e.g., GitHub Actions) appears in `ciStatus[prId].externalCIRuns[]` as runs with nested `jobs[]`; each job's `jobId` is the input for `get_ci_logs`.
-
-```
-show_session(sessionId: "<session-id>")
-```
+Use `update_session` directly when the user asks to summarize progress, update the session description, or capture the current state.
+Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
 
 ### Linked References
 
@@ -375,55 +319,16 @@ Use `link_reference` to link an external reference to the current Polygraph sess
 
 When an external resource is mentioned during a Polygraph session and appears relevant to the current work, the parent agent should record it with `link_reference({ sessionId, reference })`. This applies to relevant external resources such as pull requests, GitHub issues, other Polygraph sessions, and Linear issues.
 
-Invoke the MCP tool with a single object containing `{ sessionId, reference }`. For example, to record a relevant pull request:
-
-```
-link_reference({
-  sessionId: "<current-session-id>",
-  reference: {
-    type: "github_pr",
-    url: "https://github.com/nrwl/polygraph-skills/pull/123",
-    label: "Implementation PR"
-  }
-})
-```
-
-To record a relevant Polygraph session, use the same invocation shape and include `reference.sessionId`:
-
-```
-link_reference({
-  sessionId: "<current-session-id>",
-  reference: {
-    type: "session",
-    url: "https://polygraph.example/s/<inspected-session-id>",
-    label: "Inspected Polygraph session",
-    sessionId: "<inspected-session-id>"
-  }
-})
-```
-
-The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command.
+The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command; `show_session` returns a session's existing links as `session.linkedReferences`.
 
 ### Add Repositories to a Session
 
 Use `add_repo` to add repositories to an existing Polygraph session after it has already started.
 
-**Direct-add rule:** When the user provides exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, pass those refs directly to `add_repo` and do not call `list_repos` first. Candidate discovery remains account-repo-only and is only for cases where the user does not know the exact repo or asks to choose/filter candidates.
+**Direct-add rule:** When the user provides exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, pass those refs directly to `add_repo` and do not call `list_repos` first. Candidate discovery is only for cases where the user does not know the exact repo.
 
 **Not limited to your organization:** repos outside the org — including public open-source repos — can be added by GitHub `owner/repo` slug or URL. Only `list_repos` discovery is org-scoped, so a repo missing from `list_repos` can still be added directly.
 
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `repoIds` (required): Repository IDs or exact repository refs to add. Accepts IDs, short names, full names, GitHub `owner/repo` slugs, and URL-like slugs.
-
-```
-add_repo(
-  sessionId: "<session-id>",
-  repoIds: ["org/repo-name", "facebook/react"]
-)
-```
-
 ### Archive Session
 
 **IMPORTANT: Only call this tool when the user explicitly asks to archive or close the session.** Do not archive sessions automatically as part of the workflow.
@@ -444,14 +349,6 @@ When you need to fetch and read a failed job's log, read [`reference/ci-job-logs
 
 Session repos are shallow (`--depth 1`) clones. When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` and retry. Read [`reference/shallow-clone-history.md`](reference/shallow-clone-history.md) for the CLI form, the `depth`/`refs` options, and the redundant-call behavior.
 
-### Update Session Description
-
-Use this when the user asks to summarize progress, update the session description, or capture the current state.
-
-Read [`reference/session-description.md`](reference/session-description.md) for the full update procedure (what to read before writing, how to append vs. replace) and the canonical Markdown-heading format. Then call `update_session` with the resulting summary as `description`.
-
-Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
-
 ### Print Polygraph Session Details
 
 When asked to print polygraph session details, use `show_session` or `polygraph session show --details <session-id>` and display in the following format.
@@ -472,7 +369,7 @@ If the session has a description timeline, also display:
 - PR_URL, PR_TITLE, PR_STATUS: from `pullRequests[]`
 - CI_STATUS: from `ciStatus[prId].status`
 - SELF_HEALING_STATUS: from `ciStatus[prId].selfHealingStatus` (omit or show `-` if null)
-- CIPE_URL: from `ciStatus[prId].cipeUrl`
+- CIPE_URL: from `ciStatus[prId].cipeUrl` (null if no CIPE — omit the CI Link cell) — a human-facing Nx Cloud link: render it for the user, never fetch, curl, or poll it. CIPE data is only reachable via the Nx MCP `ci_information` tool.
 - POLYGRAPH_SESSION_URL: from `polygraphSessionUrl`
 - SESSION_DESCRIPTION: from the latest/current item in `description`
 
@@ -490,7 +387,3 @@ If the session has a description timeline, also display:
 1. **NEVER call the Polygraph MCP `spawn_agent` or `show_agent` directly for routine delegation**. These MUST run inside `polygraph-delegate-subagent`.
    
 1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed (pass `role` to target a non-default agent). The child's session is preserved (`sessionPreserved: true`) so the context can be restored later, but after resuming you must wait for explicit user instructions before making changes.
-1. **Only archive sessions when asked** — Only call `archive_session` when the user explicitly requests it. Archiving hides the session from active lists; it can still be resumed later.
-   
-1. **Respect the sandbox** — When a command fails with a sandbox denial (`EPERM` binding a port, blocked host, denied write), stop instead of retrying and point the user to the options in "Sandboxing in Polygraph Sessions": commit harness sandbox settings to the repo, or toggle sandboxing via `polygraph config`.
-   

package/skills/polygraph/reference/publish-changes.md

@@ -6,6 +6,8 @@ The branch-to-PR flow: push branches, create draft PRs, mark them ready, and ass
 
 Once work is complete in a repository, push the branch using `push_branch`. This must be done before creating a PR.
 
+**If `push_branch` fails, don't guess at the cause.** Report the tool's actual error to the user first. Only once the real cause is clear, offer to fall back to a manual `git push` — let the user decide, rather than falling back unprompted or asserting what a credential/token can or cannot do.
+
 `push_branch` pushes from the local checkout: for the repo you are in, that is your current working directory with your commits; for delegated repos, it is the Polygraph-managed clone the child agent worked in. There is no separate session copy of the current repo.
 
 **Parameters:**

package/skills/polygraph/reference/session-by-commit.md

@@ -0,0 +1,25 @@
+# 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.