@polygraph/codex-plugin 0.4.39 → 0.4.41

package/.codex-plugin/plugin.json

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

package/README.md

@@ -46,6 +46,7 @@ It detects your AI agent — Claude Code, Codex, OpenCode, and more — and inst
 
 - **polygraph-init-subagent** — Discovers candidate repositories and initializes a Polygraph session
 - **polygraph-delegate-subagent** — Delegates work to a child agent in another repository, polls for completion
+- **session-debrief** — Analyzes the raw logs of past Polygraph sessions and returns a structured, rank-ordered debrief for the current task
 
 ## Development
 

package/agents/polygraph-delegate-subagent.toml

@@ -37,22 +37,21 @@ spawn_agent(
 
 The call returns immediately — the child agent runs asynchronously.
 
-**Backoff schedule for polling:**
+**Polling with long-poll waits:**
 
-| Poll Attempt | Wait Before Poll |
-| ------------ | ---------------- |
-| 1st          | Immediately      |
-| 2nd          | 10 seconds       |
-| 3rd          | 30 seconds       |
-| 4th+         | 60 seconds (cap) |
-
-Use `sleep` in Bash between polls — this is mandatory, not aspirational. Without it you will hammer `show_agent` every 2-3s, which both wastes calls and floods your own context with repeated polling output. Always run sleep in the **foreground** (never background).
+Call `show_agent` in a loop, passing `waitForTransitionMs: 50000` on every call:
 
 ```
-sleep 60   # between 4th+ polls
+show_agent(
+  sessionId: "<sessionId>",
+  repo: "<repo>",
+  waitForTransitionMs: 50000
+)
 ```
 
-## Polling the children (multi-turn + input-required)
+Each call blocks up to ~50 seconds and resolves within ~1 second of a state change. It returns immediately if the child is already terminal, `input-required`, or `permission-required`. Call it back-to-back in a loop.
+
+## Polling the child (multi-turn + input-required)
 
 After calling `spawn_agent`, parse the structured JSON response:
 
@@ -60,9 +59,9 @@ After calling `spawn_agent`, parse the structured JSON response:
 { "taskId": "…", "message": "…", "status": "delegated" }
 ```
 
-Then poll `show_agent` on a backoff cadence. **Do not pass a `tail` argument** — the tool's default is sized for status polling. Only set `tail` if you have a specific reason (e.g., the default truncated output you actually need to inspect, or you are hunting for an earlier failure that scrolled off). Never ratchet `tail` upward across polls; that is what causes the polling loop to flood your context window.
+Then poll `show_agent` in a loop with `waitForTransitionMs: 50000`. **Do not pass a `tail` argument** — the tool's default is sized for status polling. Only set `tail` if you have a specific reason (e.g., the default truncated output you actually need to inspect, or you are hunting for an earlier failure that scrolled off). Never ratchet `tail` upward across polls; that is what causes the polling loop to flood your context window.
 
-For each child in the response (field: `children[]`), inspect:
+The response's `children[]` array has a single entry — the child for your repo. On it, inspect:
 
 - `child.status` — an AcpRunStatus value: one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`). Note `'permission-required'` and `'input-required'` are DIFFERENT states handled by different cases below — do not conflate them.
 - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`; contains the verbatim question the child agent has asked the parent.
@@ -71,7 +70,7 @@ For each child in the response (field: `children[]`), inspect:
 
 State machine:
 
-1. `child.status === 'created'` or `'in-progress'` — child is still executing. Continue polling.
+1. `child.status === 'created'` or `'in-progress'` — child is still executing. Call `show_agent` (with `waitForTransitionMs: 50000`) again.
 2. `child.status === 'input-required'` — child is paused waiting for parent input:
    - Read `child.inputRequiredQuestion`.
    - Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
@@ -82,14 +81,14 @@ State machine:
 <!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
      rendered by polygraph-mcp's show_agent handler. The dialog targets the parent's main
      thread, NOT this subagent. From this subagent's perspective the gate is transient: a
-     poll may observe permission-required briefly, but the parent's pick resolves it and the
-     next poll sees the child back in progress. Do nothing here. -->
+     waited show_agent call returns immediately while the gate is open, but the parent's pick
+     resolves it and a later poll sees the child back in progress. Do nothing here. -->
 3. `child.status === 'permission-required'` — the child opened a permission gate. **This is NOT `input-required`. Do not treat it like case 2.** The parent's native MCP elicitation dialog already renders the prompt in the parent's own UI and routes the decision back to the child through `polygraph-mcp`. Your only job is to stay out of the way and keep polling:
 
    - **Do NOT return, finish, summarize, relay, or surface this to the parent.** Do NOT describe the child as "needing input", "awaiting approval", "asking for permission", or anything that would make the parent prompt the user — the parent already has its own dialog. Returning here is the bug this case exists to prevent.
    - **Do NOT read `child.pendingPermission` as a question to answer or forward.** It is for inspection/logging only; it is not your input prompt.
    - **Do NOT call any tool** (`spawn_agent`, `stop_agent`, `allow_agent`, `deny_agent`) to resolve it.
-   - Treat `permission-required` **exactly like `in-progress`**: this is a transient state. **Sleep through the backoff and resume polling** — no other action. The next poll observes the child back in `in-progress` (then `completed`), or `failed` / `cancelled` if the user denied or dismissed. Only at a terminal state do you return, per the cases below.
+   - Treat `permission-required` **like `in-progress`**: just call `show_agent` (with `waitForTransitionMs`) again — the parent's dialog resolves it. Only at a terminal state do you return, per the cases below.
 
 4. `child.status === 'completed'` — child finished successfully. Read `child.lastOutputLines` for the most recent log tail and report outcome.
 5. `child.status === 'failed'` — child failed. Read `child.lastOutputLines` for failure context and report the error.

package/agents/session-debrief.toml

@@ -0,0 +1,24 @@
+name = "session-debrief"
+description = "Analyze the raw logs of one or more past Polygraph sessions and return a structured, rank-ordered debrief for the current task. Launch as a background agent with a ranked list of relevant Polygraph session IDs/lines and a one-paragraph statement of the current task; it invokes the session-debrief skill, pulls parent and child transcripts via the polygraph CLI, and returns one consolidated debrief. Read-only with respect to the inspected sessions."
+developer_instructions = '''
+# Session Debrief Subagent
+
+You produce debriefs of PAST Polygraph sessions so a parent agent working on a NEW task can decide what context is relevant. You run in the background and speed matters — the parent keeps working while it waits and folds your debrief in whenever it lands.
+
+You are READ-ONLY with respect to the inspected sessions: never resume them, never spawn agents into them, never push branches, create PRs, or update their descriptions.
+
+## Input Parameters (from Main Agent)
+
+The main agent provides these in the prompt:
+
+| Parameter     | Description                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `sessions`    | A ranked list of relevant Polygraph sessions (IDs/lines, most relevant first, with optional titles/URLs) |
+| `currentTask` | A one-paragraph statement of the task the parent is currently working on                         |
+
+## What to do
+
+Invoke the `session-debrief` skill and follow its procedure and output template exactly. Pass through the ranked session list and the current-task statement you received. The skill is the single source of truth for how to pull transcripts via the polygraph CLI, how to fan out across multiple sessions, and how to format each debrief section — do not reinvent or duplicate that procedure here.
+
+Return the consolidated, rank-ordered debrief as your final message.
+'''

package/bin/polygraph-codex-plugin.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // source/codex/lib/installer.mjs
+import { spawnSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -35,10 +36,19 @@ function resolveUserHome(env = process.env) {
   const userHome = env.HOME?.trim() || homedir();
   return resolve(expandHome(userHome, env));
 }
-function getMarketplacePath(userHome) {
+function getMarketplaceRoot(userHome) {
+  return join(userHome, ".polygraph", "codex-marketplace");
+}
+function getMarketplacePath(marketplaceRoot) {
+  return join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
+}
+function getPluginInstallPath(marketplaceRoot) {
+  return join(marketplaceRoot, "plugins", PLUGIN_NAME);
+}
+function getLegacyMarketplacePath(userHome) {
   return join(userHome, ".agents", "plugins", "marketplace.json");
 }
-function getPluginInstallPath(userHome) {
+function getLegacyPluginInstallPath(userHome) {
   return join(userHome, ".agents", "plugins", PLUGIN_NAME);
 }
 function loadPackageMetadata(packageRoot) {
@@ -74,7 +84,9 @@ function loadPackageMetadata(packageRoot) {
 function installPlugin({
   packageRoot,
   env = process.env,
-  force = false
+  force = false,
+  // Injectable so tests do not have to shell out to a real codex binary.
+  register = registerMarketplace
 } = {}) {
   if (!packageRoot) {
     throw new Error("packageRoot is required");
@@ -83,8 +95,9 @@ function installPlugin({
   const codexHome = resolveCodexHome(env);
   const userHome = resolveUserHome(env);
   const agentsPath = getAgentsPath(codexHome);
-  const marketplacePath = getMarketplacePath(userHome);
-  const pluginPath = getPluginInstallPath(userHome);
+  const marketplaceRoot = getMarketplaceRoot(userHome);
+  const marketplacePath = getMarketplacePath(marketplaceRoot);
+  const pluginPath = getPluginInstallPath(marketplaceRoot);
   const installAlreadyPresent = existsSync(pluginPath);
   let previousVersion = null;
   if (installAlreadyPresent) {
@@ -117,15 +130,20 @@ function installPlugin({
     copied = true;
   }
   const agentsChanged = installCodexAgents({ packageRoot, agentsPath });
-  const marketplaceChanged = enablePluginInMarketplace({
+  const marketplaceChanged = writeMarketplaceManifest({
     marketplacePath,
-    pluginPath,
-    userHome
+    marketplaceRoot,
+    pluginPath
   });
+  const legacyCleanup = cleanLegacyMarketplaceEntry({ userHome });
+  const registration = register({ marketplaceRoot, env });
   return {
     ok: true,
     action: "install",
     plugin: PLUGIN_ID,
+    marketplaceName: MARKETPLACE_NAME,
+    marketplaceRoot,
+    marketplaceRegistered: registration.registered,
     version,
     codexHome,
     agentsPath,
@@ -136,9 +154,68 @@ function installPlugin({
     pluginUpdated: installAlreadyPresent && versionMismatch && !force,
     previousVersion,
     agentsChanged,
-    marketplaceChanged
+    marketplaceChanged,
+    legacyEntryRemoved: legacyCleanup.entryRemoved,
+    legacyMarketplaceRemoved: legacyCleanup.fileRemoved,
+    ...registration.error ? { marketplaceRegistrationError: registration.error } : {}
   };
 }
+function registerMarketplace({ marketplaceRoot, env = process.env }) {
+  const result = spawnSync(
+    "codex",
+    ["plugin", "marketplace", "add", marketplaceRoot, "--json"],
+    { encoding: "utf8", env }
+  );
+  if (result.error) {
+    return {
+      registered: false,
+      error: `Could not run \`codex\`: ${result.error.message}. Run \`codex plugin marketplace add ${marketplaceRoot}\` once codex is available.`
+    };
+  }
+  if (result.status !== 0) {
+    return {
+      registered: false,
+      error: `\`codex plugin marketplace add\` failed: ${(result.stderr || "").trim()}`
+    };
+  }
+  return { registered: true };
+}
+function cleanLegacyMarketplaceEntry({ userHome }) {
+  const legacyPath = getLegacyMarketplacePath(userHome);
+  const unchanged = { entryRemoved: false, fileRemoved: false };
+  if (!existsSync(legacyPath)) {
+    return unchanged;
+  }
+  let marketplace;
+  try {
+    marketplace = readJsonFile(legacyPath);
+  } catch {
+    return unchanged;
+  }
+  if (!isPlainObject(marketplace) || !Array.isArray(marketplace.plugins)) {
+    return unchanged;
+  }
+  const remaining = marketplace.plugins.filter(
+    (plugin) => plugin?.name !== PLUGIN_NAME
+  );
+  if (remaining.length === marketplace.plugins.length) {
+    return unchanged;
+  }
+  if (remaining.length === 0 && marketplace.name === MARKETPLACE_NAME) {
+    rmSync(legacyPath, { force: true });
+    rmSync(getLegacyPluginInstallPath(userHome), {
+      recursive: true,
+      force: true
+    });
+    return { entryRemoved: true, fileRemoved: true };
+  }
+  writeJsonFile(legacyPath, { ...marketplace, plugins: remaining });
+  rmSync(getLegacyPluginInstallPath(userHome), {
+    recursive: true,
+    force: true
+  });
+  return { entryRemoved: true, fileRemoved: false };
+}
 function checkInstall({ packageRoot, env = process.env } = {}) {
   let version = null;
   if (packageRoot) {
@@ -147,29 +224,46 @@ function checkInstall({ packageRoot, env = process.env } = {}) {
   const codexHome = resolveCodexHome(env);
   const userHome = resolveUserHome(env);
   const agentsPath = getAgentsPath(codexHome);
-  const marketplacePath = getMarketplacePath(userHome);
-  const pluginPath = getPluginInstallPath(userHome);
+  const marketplaceRoot = getMarketplaceRoot(userHome);
+  const marketplacePath = getMarketplacePath(marketplaceRoot);
+  const pluginPath = getPluginInstallPath(marketplaceRoot);
   const pluginInstalled = isValidInstalledPluginDir(pluginPath);
   const agentsInstalled = packageRoot ? areCodexAgentsInstalled({ packageRoot, agentsPath }) : hasDefaultCodexAgents(agentsPath);
   const marketplaceConfigured = isPluginConfiguredInMarketplace({
     marketplacePath,
-    userHome,
+    marketplaceRoot,
     pluginPath
   });
-  const ok = pluginInstalled && agentsInstalled && marketplaceConfigured;
+  const legacyMarketplacePresent = hasLegacyPluginEntry({ userHome });
+  const ok = pluginInstalled && agentsInstalled && marketplaceConfigured && !legacyMarketplacePresent;
   return {
     ok,
     action: "check",
     plugin: PLUGIN_ID,
+    marketplaceName: MARKETPLACE_NAME,
+    marketplaceRoot,
     codexHome,
     agentsPath,
     pluginPath,
     marketplacePath,
     pluginInstalled,
     agentsInstalled,
-    marketplaceConfigured
+    marketplaceConfigured,
+    legacyMarketplacePresent
   };
 }
+function hasLegacyPluginEntry({ userHome }) {
+  const legacyPath = getLegacyMarketplacePath(userHome);
+  if (!existsSync(legacyPath)) {
+    return false;
+  }
+  try {
+    const marketplace = readJsonFile(legacyPath);
+    return Array.isArray(marketplace?.plugins) && marketplace.plugins.some((plugin) => plugin?.name === PLUGIN_NAME);
+  } catch {
+    return false;
+  }
+}
 function getPackagePayloadPaths(packageRoot, packageJson) {
   const relativePaths = new Set(packageJson.files ?? []);
   relativePaths.add("package.json");
@@ -234,44 +328,30 @@ function hasDefaultCodexAgents(agentsPath) {
     (agentFile) => existsSync(join(agentsPath, agentFile))
   );
 }
-function enablePluginInMarketplace({
+function writeMarketplaceManifest({
   marketplacePath,
-  pluginPath,
-  userHome
+  marketplaceRoot,
+  pluginPath
 }) {
-  const marketplace = readJsonFile(marketplacePath, {});
-  if (marketplace.plugins !== void 0 && !Array.isArray(marketplace.plugins)) {
-    throw new Error(`Expected plugins array in ${marketplacePath}`);
-  }
-  const marketplacePluginPath = toMarketplaceSourcePath(userHome, pluginPath);
-  const nextPluginEntry = {
-    name: PLUGIN_NAME,
-    source: {
-      source: "local",
-      path: marketplacePluginPath
-    },
-    policy: {
-      installation: "AVAILABLE",
-      authentication: "ON_INSTALL"
-    },
-    category: "Productivity"
-  };
-  const plugins = marketplace.plugins ?? [];
-  const existingIndex = plugins.findIndex(
-    (plugin) => plugin?.name === PLUGIN_NAME
-  );
-  const nextPlugins = existingIndex === -1 ? [...plugins, nextPluginEntry] : plugins.map(
-    (plugin, index) => index === existingIndex ? nextPluginEntry : plugin
-  );
   const nextMarketplace = {
-    ...marketplace,
-    name: marketplace.name ?? MARKETPLACE_NAME,
-    interface: isPlainObject(marketplace.interface) ? {
-      ...marketplace.interface,
-      displayName: marketplace.interface.displayName ?? MARKETPLACE_DISPLAY_NAME
-    } : { displayName: MARKETPLACE_DISPLAY_NAME },
-    plugins: nextPlugins
+    name: MARKETPLACE_NAME,
+    interface: { displayName: MARKETPLACE_DISPLAY_NAME },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: {
+          source: "local",
+          path: toMarketplaceSourcePath(marketplaceRoot, pluginPath)
+        },
+        policy: {
+          installation: "AVAILABLE",
+          authentication: "ON_INSTALL"
+        },
+        category: "Productivity"
+      }
+    ]
   };
+  const marketplace = readJsonFile(marketplacePath, null);
   const changed = JSON.stringify(nextMarketplace) !== JSON.stringify(marketplace);
   if (changed) {
     writeJsonFile(marketplacePath, nextMarketplace);
@@ -280,13 +360,21 @@ function enablePluginInMarketplace({
 }
 function isPluginConfiguredInMarketplace({
   marketplacePath,
-  userHome,
+  marketplaceRoot,
   pluginPath
 }) {
   if (!existsSync(marketplacePath)) {
     return false;
   }
-  const marketplace = readJsonFile(marketplacePath);
+  let marketplace;
+  try {
+    marketplace = readJsonFile(marketplacePath);
+  } catch {
+    return false;
+  }
+  if (marketplace?.name !== MARKETPLACE_NAME) {
+    return false;
+  }
   if (!Array.isArray(marketplace.plugins)) {
     return false;
   }
@@ -296,7 +384,7 @@ function isPluginConfiguredInMarketplace({
   if (!isPlainObject(pluginEntry?.source) || pluginEntry.source.source !== "local") {
     return false;
   }
-  const configuredPath = resolve(userHome, pluginEntry.source.path);
+  const configuredPath = resolve(marketplaceRoot, pluginEntry.source.path);
   return configuredPath === resolve(pluginPath);
 }
 function readJsonFile(path, fallbackValue) {
@@ -341,11 +429,11 @@ function expandHome(inputPath, env) {
   }
   return inputPath;
 }
-function toMarketplaceSourcePath(userHome, targetPath) {
-  const relativePath = relative(userHome, targetPath);
+function toMarketplaceSourcePath(marketplaceRoot, targetPath) {
+  const relativePath = relative(marketplaceRoot, targetPath);
   if (relativePath === "" || relativePath === "." || relativePath.startsWith(`..${sep}`) || relativePath === "..") {
     throw new Error(
-      `Expected plugin install path ${targetPath} to be inside ${userHome} so it can be referenced from the personal marketplace`
+      `Expected plugin install path ${targetPath} to be inside ${marketplaceRoot} so it can be referenced from the marketplace manifest`
     );
   }
   return `./${relativePath.split(sep).join("/")}`;
@@ -360,8 +448,10 @@ var usage = `Usage:
   npx @polygraph/codex-plugin install [--force] [--json]
   npx @polygraph/codex-plugin check [--json]
 
-The install command materializes the plugin payload so that codex's official
-plugin system can pick it up. After running install, run:
+The install command materializes the plugin payload into the marketplace Polygraph
+owns (~/.polygraph/codex-marketplace) and registers that marketplace with codex.
+It does not write to the shared ~/.agents/plugins/marketplace.json. After running
+install, run:
 
   codex plugin add polygraph@polygraph-plugins
 
@@ -408,17 +498,30 @@ ${usage}`);
     } else {
       const pluginState = result.pluginInstalled ? "plugin files present" : "plugin files not present";
       const agentsState = result.agentsInstalled ? "agents installed" : "agents not installed";
-      const marketplaceState = result.marketplaceConfigured ? "plugin present in marketplace" : "plugin not present in marketplace";
+      const marketplaceState = result.marketplaceConfigured ? `plugin published from the ${result.marketplaceName} marketplace` : `plugin not published from the ${result.marketplaceName} marketplace`;
+      const legacyState = result.legacyMarketplacePresent ? "; a stale entry remains in ~/.agents/plugins/marketplace.json (re-run install to clear it)" : "";
       console.error(
-        `Polygraph Codex plugin check failed: ${pluginState}; ${agentsState}; ${marketplaceState}.`
+        `Polygraph Codex plugin check failed: ${pluginState}; ${agentsState}; ${marketplaceState}${legacyState}.`
       );
     }
   } else {
     console.log(`Materialized Polygraph Codex plugin ${result.version}.`);
     console.log(`Plugin path: ${result.pluginPath}`);
     console.log(`Agents: ${result.agentsPath}`);
-    console.log(`Marketplace: ${result.marketplacePath}`);
-    console.log(`Next step: codex plugin add ${result.plugin}`);
+    console.log(`Marketplace: ${result.marketplaceName} (${result.marketplaceRoot})`);
+    if (result.legacyEntryRemoved) {
+      console.log(
+        result.legacyMarketplaceRemoved ? "Removed the obsolete ~/.agents/plugins/marketplace.json written by an earlier version." : "Removed the obsolete polygraph entry from ~/.agents/plugins/marketplace.json; your other plugins were left untouched."
+      );
+    }
+    if (result.marketplaceRegistered) {
+      console.log(`Next step: codex plugin add ${result.plugin}`);
+    } else {
+      console.warn(`Warning: ${result.marketplaceRegistrationError}`);
+      console.warn(
+        `Then run: codex plugin add ${result.plugin}`
+      );
+    }
   }
   if (command === "check" && !result.ok) {
     process.exitCode = 1;

package/package.json

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

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; 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".
+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; fetching missing git history in a shallow session clone; 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", "shallow clone", "missing commit", "bad object", "unshallow", "fetch history".
 
 ---
 
@@ -56,7 +56,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
 | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
 | `spawn_agent` | — | Start a new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context? }`. Output: `{ taskId, message, status: 'delegated' }`. Follow-up routing is automatic: if the repo already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. A repo has at most one active child at a time. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. |
-| `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'permission-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
+| `show_agent` | — | Poll the status of the specified repo's child (`repo` is required — one call covers one repo). Output: `{ children: PolygraphChildStatusItem[] }` with a single entry for that repo; the item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'permission-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
 | `stop_agent` | — | Cancel an in-progress child. Output: `{ taskId, state: 'cancelled', sessionPreserved: true, output, message }`. Because `sessionPreserved: true`, the preserved agent session can be restored later for context, but resume must wait for explicit user instructions before making changes. |
 | `push_branch` | — | Push a local git branch to the remote repository. For the repo you are in, this pushes from your current checkout. Requires a session description. |
 | `create_pr` | — | Create draft PRs with session metadata linking related PRs |
@@ -68,6 +68,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
 | `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
 | `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
+| `git_fetch` | `polygraph git fetch` | Fetch additional git history for a shallow session clone. Use when git operations fail with "bad object" or missing-commit errors; by default fetches the full history of the default branch. Input: `{ sessionId, repo, depth?, refs? }`. See "Fetching Git History for Shallow Clones". |
 | `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. |
@@ -107,7 +108,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
 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, but only one active child per repo. 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 progress and read the flat `children[]` array for each child's `status` and `lastOutputLines`.
+4. **Monitor child agents** - Use `show_agent` to poll one repo's child (`repo` is required) and read its `status` and `lastOutputLines` from the single-entry `children[]` array.
 5. **Stop child agents** (if needed) - Use `stop_agent` to cancel an in-progress child agent. The underlying agent 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.
@@ -269,13 +270,13 @@ spawn_agent(
     - instruction: "<the task instruction>"
     - context: "<optional context>"
 
-    Call the Polygraph MCP spawn_agent for the repo, then poll show_agent on backoff until terminal. Return a structured summary with repo, status, session ID, and result text.
+    Call the Polygraph MCP spawn_agent for the repo, then poll show_agent via chained waitForTransitionMs long-poll calls until terminal. Return a structured summary with repo, status, session ID, and result text.
   """
 )
 ```
 
 2. Delegate to multiple repos in parallel by launching multiple `polygraph-delegate-subagent` instances before waiting for results — one delegation per repo at a time.
-3. For each child, the subagent watches `child.status` in the flat `children[]` response and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped).
+3. The subagent watches `child.status` on the single `children[]` entry for its repo 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`.
@@ -292,7 +293,7 @@ Use this pattern when the child may need clarification, the task is exploratory,
    { "taskId": "…", "message": "…", "status": "delegated" }
    ```
 
-2. Poll `show_agent`. The response shape is `{ children: PolygraphChildStatusItem[] }`. For each child, inspect:
+2. Poll `show_agent` via chained `waitForTransitionMs` long-poll calls (`repo` is required). The response shape is `{ children: PolygraphChildStatusItem[] }` with a single entry for that repo. On it, inspect:
 
    - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
    - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
@@ -672,6 +673,10 @@ get_ci_logs(
 
 **Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.
 
+### Fetching Git History for Shallow Clones
+
+Session repos are shallow (`--depth 1`) clones and plain `git fetch --unshallow` fails on private repos (the clone-time credential is not retained). When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` (CLI: `polygraph git fetch <repo> --session <id> --json`), then retry. Defaults fetch the default branch's full history; pass `depth` for a bounded fetch or `refs` for extra branches. Safe to call redundantly (`alreadyComplete: true`).
+
 ### Update Session Description
 
 Use this when the user asks to summarize progress, update the session description, or capture the current state.