@polygraph/codex-plugin 0.4.40 → 0.4.42

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.40",
+  "version": "0.4.42",
   "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

@@ -16,13 +16,14 @@ The main agent provides these parameters in the prompt:
 | `sessionId`   | The Polygraph session ID                                                     |
 | `repo`        | Repository to delegate to (e.g., `org/repo-name`)                            |
 | `instruction` | The task instruction for the child agent                                     |
+| `role`        | (Optional) Agent slot within the repo; omit for the default role. Pass the SAME role on every `spawn_agent`/`show_agent`/`stop_agent` call for this delegation. |
 | `context`     | (Optional) Additional context to pass to the child agent                     |
 
 ## Delegating work
 
-Call the `spawn_agent` tool to start a child agent on the repo or to send a follow-up to an active task. Follow-up routing is automatic: if the repo already has an active child task (working or paused on input), the orchestrator delivers your `instruction` to that task as a follow-up message; otherwise it starts a new child run.
+Call the `spawn_agent` tool to start a child agent on the repo or to send a follow-up to an active task. Follow-up routing is automatic per (repo, role): if that (repo, role) already has an active child task (working or paused on input), the orchestrator delivers your `instruction` to that task as a follow-up message rather than starting a second run; otherwise it starts a new child run. A repo therefore has at most one active child per role, though agents with different roles can run in the same repo concurrently.
 
-`repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo. A repo has at most one active child: while one is active, any `spawn_agent` call for that repo is routed to it as a follow-up rather than starting a second run.
+`repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo.
 
 **Resume/reconstruction is read-only.** If the parent asks you to resume, reconnect, restore, or reconstruct a preserved session without an explicit new change request from the user, do not call `spawn_agent` to continue work. Use `show_agent` only as needed to read status/log context, return a concise restoration summary, and stop. After resuming, wait for explicit user instructions before any child agent makes changes.
 
@@ -31,6 +32,7 @@ spawn_agent(
   sessionId: "<sessionId>",
   repo: "<repo>",
   instruction: "<instruction>",
+  role: "<role, if any>",
   context: "<context>"
 )
 ```
@@ -45,6 +47,7 @@ Call `show_agent` in a loop, passing `waitForTransitionMs: 50000` on every call:
 show_agent(
   sessionId: "<sessionId>",
   repo: "<repo>",
+  role: "<role, if any>",
   waitForTransitionMs: 50000
 )
 ```
@@ -61,7 +64,7 @@ After calling `spawn_agent`, parse the structured JSON response:
 
 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.
 
-The response's `children[]` array has a single entry — the child for your repo. On it, inspect:
+The response's `children[]` array has one entry per agent matching your query. Find YOUR delegation's entry (match on `role`; absent means the default role) and 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.
@@ -75,7 +78,7 @@ State machine:
    - Read `child.inputRequiredQuestion`.
    - Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
    - Wait for the parent/user to supply an answer.
-   - Call `spawn_agent` again with the same `repo` and `instruction: <the answer>` — the orchestrator routes it to the active task automatically.
+   - Call `spawn_agent` again with the same `repo`, the same `role`, and `instruction: <the answer>` — the orchestrator routes it to that (repo, role)'s active task automatically.
    - Resume polling.
 
 <!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
@@ -96,7 +99,7 @@ State machine:
 
 ## Cancelling a running child
 
-To cancel a running child mid-work, call `stop_agent` with the repo. Response:
+To cancel a running child mid-work, call `stop_agent` with the repo (and `role`, per the parameter rule above). Response:
 
 ```json
 {
@@ -118,6 +121,7 @@ When the child agent reaches a terminal status, return a structured summary:
 ## Polygraph Delegation Result
 
 **Repo:** <repo>
+**Role:** <role, or "default" when none was given>
 **Status:** <success | failed | cancelled>
 **Session ID:** <sessionId>
 

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/hooks/record-session-mapping.mjs

@@ -5,15 +5,27 @@
 // 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,
-//     preserve its firstSeenAt and only update lastSeenAt + mutable fields.
+//   - 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.
 
@@ -90,9 +102,35 @@ 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;
+
+  try {
+    const config = tryParseJson(
+      readFileSync(join(home, '.polygraph', 'config.json'), 'utf8')
+    );
+    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.
@@ -106,19 +144,33 @@ export function writeCaptureMapping(
   { agentType, agentSessionId, polygraphSessionId, cwd, transcriptPath, pid },
   home = process.env.HOME?.trim() || homedir()
 ) {
-  const sidecarDir = join(home, '.polygraph', 'sidecars', polygraphSessionId);
-  mkdirSync(sidecarDir, { recursive: true });
-
   const filenamePart = sanitizeFilename(`${agentType}-${agentSessionId}`);
-  const finalPath = join(sidecarDir, `mapping-${filenamePart}.json`);
+  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;
-  if (existsSync(finalPath)) {
-    const existing = tryParseJson(readFileSync(finalPath, 'utf8'));
+  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 &&
@@ -127,6 +179,7 @@ export function writeCaptureMapping(
       Number.isFinite(existing.firstSeenAt)
     ) {
       firstSeenAt = existing.firstSeenAt;
+      break;
     }
   }
 

package/hooks/reinject-polygraph-context.mjs

@@ -8,9 +8,12 @@
 // into the model.
 //
 // Everything is read from local Polygraph state — no network calls:
+//   <sessionsRoot>/<polygraphSessionId>/sidecars/parent-<agentSessionId>.json
+//       (sessionsRoot = $POLYGRAPH_ROOT or ~/.polygraph/sessions) maps this
+//       agent session id -> Polygraph session id (the "parent log sidecar"
+//       the CLI uses to stream parent-agent activity to the UI). Falls back
+//       to the legacy location for sessions created by older CLIs:
 //   ~/.polygraph/sidecars/<polygraphSessionId>/parent-<agentSessionId>.json
-//       maps this agent session id -> Polygraph session id (the "parent log
-//       sidecar" the CLI uses to stream parent-agent activity to the UI).
 //   ~/.polygraph/sessions/<polygraphSessionId>/session/session.json
 //       holds the session's repos, agentType, and orgId.
 //   ~/.polygraph/config.json
@@ -83,25 +86,28 @@ function readJson(file) {
   }
 }
 
-// Find the sidecar that maps an agent session id to a Polygraph session.
-// Returns the parsed sidecar object, or null when none matches.
-export function findSidecar(agentSessionId, root = polygraphRoot()) {
-  if (!agentSessionId) return null;
+// Resolve the root directory that holds per-session folders. Overridable via
+// POLYGRAPH_ROOT (must match the Polygraph CLI's own resolution).
+function sessionsRoot(root) {
+  return process.env.POLYGRAPH_ROOT?.trim() || path.join(root, 'sessions');
+}
 
-  const sidecarsDir = path.join(root, 'sidecars');
-  if (!existsSync(sidecarsDir)) return null;
+// Scan the immediate subdirectories of `baseDir`; for each, `candidatePath`
+// maps the subdirectory name to a candidate sidecar file. Returns the first
+// parsed match, or null.
+function scanForSidecar(baseDir, candidatePath) {
+  if (!existsSync(baseDir)) return null;
 
-  const fileName = `parent-${agentSessionId}.json`;
   let entries;
   try {
-    entries = readdirSync(sidecarsDir, { withFileTypes: true });
+    entries = readdirSync(baseDir, { withFileTypes: true });
   } catch {
     return null;
   }
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const candidate = path.join(sidecarsDir, entry.name, fileName);
+    const candidate = candidatePath(entry.name);
     if (existsSync(candidate)) {
       return readJson(candidate);
     }
@@ -109,6 +115,29 @@ export function findSidecar(agentSessionId, root = polygraphRoot()) {
   return null;
 }
 
+// Find the sidecar that maps an agent session id to a Polygraph session.
+// Checks the new per-session layout first, then falls back to the legacy
+// shared sidecars directory. Returns the parsed sidecar object, or null when
+// none matches.
+export function findSidecar(agentSessionId, root = polygraphRoot()) {
+  if (!agentSessionId) return null;
+
+  const fileName = `parent-${agentSessionId}.json`;
+
+  // New layout: <sessionsRoot>/<sessionId>/sidecars/parent-<agentSessionId>.json
+  const sessionsDir = sessionsRoot(root);
+  const fromSessions = scanForSidecar(sessionsDir, (sessionId) =>
+    path.join(sessionsDir, sessionId, 'sidecars', fileName)
+  );
+  if (fromSessions) return fromSessions;
+
+  // Legacy layout: <root>/sidecars/<sessionId>/parent-<agentSessionId>.json
+  const legacyDir = path.join(root, 'sidecars');
+  return scanForSidecar(legacyDir, (sessionId) =>
+    path.join(legacyDir, sessionId, fileName)
+  );
+}
+
 // Build the context block for a Polygraph session, or null when the agent is
 // not running inside a Polygraph session.
 export function buildPolygraphContext(agentSessionId, root = polygraphRoot()) {

package/package.json

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

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

@@ -165,7 +165,7 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
    show_agent(sessionId: "<session-id>", repo: "frontend")
    ```
 
-   Poll until the child agent's status indicates completion. Use the `tail` parameter to retrieve recent output lines containing the investigation results.
+   Poll until the child agent's status indicates completion (pass the same `role` you spawned with, if any). Use the `tail` parameter to retrieve recent output lines containing the investigation results.
 
 4. Collect each child agent's response from the status output. If a child agent fails or gets stuck, use `stop_agent` to terminate it and skip that repo.
 

package/skills/polygraph/SKILL.md

@@ -55,9 +55,9 @@ 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 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. |
+| `spawn_agent` | — | Start a new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, role?, context? }`. Output: `{ taskId, message, status: 'delegated' }`. `role` selects the agent slot within the repo (see "Agent roles"). Follow-up routing is automatic per (repo, role): if that (repo, role) already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. 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 one repo's child status (`repo` required — one repo per call; pass `role` to narrow to that role's agent). Returns `{ children: [...] }` with one self-describing entry per matching agent, exposing `status`, `lastOutputLines`, `role` (absent for the default role), `inputRequiredQuestion`, etc. Full status enum and the poll/state-machine flow are under "Multi-turn tasks". |
+| `stop_agent` | — | Cancel an in-progress child. Input: `{ sessionId, repo, role? }`. 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 |
 | `show_session` | `polygraph session show <id> [--details]` | Query status of the current session. Use details when session summary, repo IDs, PR URLs, and PR descriptions are needed. |
@@ -106,10 +106,10 @@ After logging in (or if logged in but no org is selected), use `polygraph accoun
 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, 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.
+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; a repo can also host multiple concurrent agents under distinct roles (see "Agent roles"). 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 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.
+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.
@@ -252,6 +252,14 @@ polygraph session search --sha a1b2c3d
 - 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.
 
+## Agent roles
+
+A repository in a session can host multiple child agents at once, distinguished by **role**:
+
+- **Purpose.** Roles let independent streams of work run concurrently in one repo — e.g. a default agent implementing a feature while a `reviewer` or `ci-investigator` runs alongside. Each (repo, role) pair has at most one active child.
+- **Default role.** An omitted `role` means the default role: `spawn_agent` without `role` starts or follows up with the repo's default-role agent.
+- **Logs.** Only default-role agents upload logs to the cloud and appear in the multiplexed log stream (`polygraph session logs`). Inspect non-default agents locally with `polygraph agent attach --role <role>`.
+
 ## 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.
@@ -268,6 +276,7 @@ spawn_agent(
     - sessionId: "<session-id>"
     - repo: "<org/repo-name>"
     - instruction: "<the task instruction>"
+    - role: "<optional role>"
     - context: "<optional context>"
 
     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.
@@ -275,8 +284,8 @@ spawn_agent(
 )
 ```
 
-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. 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).
+2. Delegate to multiple repos in parallel by launching multiple `polygraph-delegate-subagent` instances before waiting for results — one delegation per (repo, role) at a time.
+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`.
@@ -287,13 +296,13 @@ Use Simple when the task is well-defined and the child will not need clarificati
 
 Use this pattern when the child may need clarification, the task is exploratory, or interactive collaboration is desired. The orchestrator exposes paused children via the `'input-required'` status.
 
-1. Call `spawn_agent` with the initial `instruction`. Parse the response:
+1. Call `spawn_agent` with the initial `instruction` (and optionally `role`). Parse the response:
 
    ```json
    { "taskId": "…", "message": "…", "status": "delegated" }
    ```
 
-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:
+2. Poll `show_agent` via chained `waitForTransitionMs` long-poll calls (`repo` is required; pass the same `role` you spawned with to narrow to that agent). The response shape is `{ children: PolygraphChildStatusItem[] }` with one entry per matching agent in that repo. On your delegation's entry, 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'`.
@@ -303,13 +312,13 @@ Use this pattern when the child may need clarification, the task is exploratory,
    Drive the state machine:
 
    - `child.status === 'in-progress'` or `'created'` — continue polling.
-   - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with the same `repo` and `instruction: <answer>` — it is routed to the active task automatically. Continue polling.
+   - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with the same `repo`, the same `role`, and `instruction: <answer>` — it is routed to that (repo, role)'s active task automatically. Continue polling.
    - `child.status === 'completed'` — read `child.lastOutputLines`, proceed to `push_branch` + `create_pr`.
    - `child.status === 'failed'` — read `child.lastOutputLines`, surface the failure.
    - `child.status === 'cancelled'` — the child was stopped via `stop_agent`; see below.
    - `child.status === 'permission-required'` — the child is waiting on a permission decision; see "Handling permission requests" below.
 
-3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo }`. The response is:
+3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo, role? }`. The response is:
 
    ```json
    {
@@ -321,7 +330,7 @@ Use this pattern when the child may need clarification, the task is exploratory,
    }
    ```
 
-   Because `sessionPreserved: true`, the preserved agent session can be restored later for context. After resuming, do not make changes or continue prior work until the user explicitly asks for changes.
+   Because `sessionPreserved: true`, the stopped agent's session can be restored later for context. After resuming, do not make changes or continue prior work until the user explicitly asks for changes.
 
 Use Multi-turn when the child may need clarification, the task is exploratory, or interactive collaboration is desired. Otherwise use Simple.
 
@@ -340,26 +349,11 @@ If you call `allow_agent` while the dialog is already open, you create a race: t
 
 The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do NOT advertise elicitation capability (opencode TUI today). They are not part of your flow.
 
-### 2. Push Branches
+### 2. Publish Changes (Push Branches, Create PRs, Mark Ready)
 
-Once work is complete in a repository, push the branch using `push_branch`. This must be done before creating a PR.
+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).
 
-`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:**
-
-- `sessionId` (required): The Polygraph session ID
-- `repo` (required): Repository name or repository ID to push from
-- `branch` (required): Branch name to push to remote
-- `description` (required): A session description is required. Must follow the Session Description Policy.
-
-```
-push_branch(
-  sessionId: "<session-id>",
-  repo: "org/repo-name",
-  branch: "polygraph/ad5fa-add-user-preferences"
-)
-```
+**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.
 
 ### Session Description Policy
 
@@ -367,121 +361,18 @@ push_branch(
 
 **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`).
 
-### 3. Create Draft PRs
-
-Create PRs for all repositories at once using `create_pr`. PRs are created as drafts with session metadata that links related PRs across repos. Branches must be pushed first. For fork PR creation or registration, include `targetRepository` on the PR spec to identify the repository that should receive the PR.
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `prs` (required): Array of PR specifications, each containing:
-  - `owner` (required): GitHub repository owner
-  - `repo` (required): GitHub repository name
-  - `title` (required): PR title
-  - `body` (required): PR description (session metadata is appended automatically)
-  - `branch` (required): Branch name that was pushed
-  - `targetRepository` (optional): Target GitHub repository for fork PR creation or registration, as `owner/repo`. Omit for same-repository PRs.
-- `description` (required): Must follow the Session Description Policy.
-
-**PR title format (applies to parent and child agents):**
+### 3. Get Current Polygraph Session
 
-- PR titles become squash-merge commit messages in most repos. They MUST follow the target repo's commit convention (e.g., Conventional Commits: `<type>(<scope>): <subject>`).
-- Do NOT add agent-identifier prefixes such as `[codex]`, `[claude]`, or `[opencode]` to PR titles. These prefixes violate commit-lint rules and pollute the git history.
-
-```
-create_pr(
-  sessionId: "<session-id>",
-  prs: [
-    {
-      owner: "org",
-      repo: "frontend",
-      title: "feat: Add user preferences UI",
-      body: "Part of multi-repo user preferences feature",
-      branch: "polygraph/ad5fa-add-user-preferences"
-    },
-    {
-      owner: "org",
-      repo: "backend",
-      title: "feat: Add user preferences API",
-      body: "Part of multi-repo user preferences feature",
-      branch: "polygraph/ad5fa-add-user-preferences"
-    }
-  ]
-)
-```
-
-For fork PR creation or registration, keep `owner` and `repo` set to the source repository that owns the pushed branch and set `targetRepository` to the target repository:
-
-```
-create_pr(
-  sessionId: "<session-id>",
-  prs: [
-    {
-      owner: "contributor",
-      repo: "frontend-fork",
-      targetRepository: "org/frontend",
-      title: "feat: Add user preferences UI",
-      body: "Part of multi-repo user preferences feature",
-      branch: "polygraph/ad5fa-add-user-preferences"
-    }
-  ]
-)
-```
-
-**After creating PRs**, always print the Polygraph session URL:
-
-```
-**Polygraph session:** POLYGRAPH_SESSION_URL
-```
-
-### 4. 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 including repositories, PRs, CI status, and the Polygraph session URL.
+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
 
-**Returns:**
+**CI status rules:**
 
-- `session.sessionId`: The session ID
-- `session.polygraphSessionUrl`: URL to the Polygraph session UI
-- `session.description`: DescriptionItem[] timeline describing the session.
-- `session.agentSessionId`: The agent CLI session ID — captured automatically by the MCP server (null if no agent has run yet).
-- `session.linkedReferences`: Array of references linked to this session
-- Session repository entries: Array of connected repositories, each with:
-  - `id`: Repository ID
-  - `name`: Repository name
-  - `defaultBranch`: Default branch (e.g., `main`)
-  - `vcsConfiguration.repositoryFullName`: Full repo name (e.g., `org/repo`)
-  - `vcsConfiguration.provider`: VCS provider (e.g., `GITHUB`)
-  - description field: AI-generated description of what this repository does (may be null)
-  - `initiator`: Whether this repository initiated the session
-- `session.dependencyGraph`: Graph of repository dependency `edges`
-- `session.pullRequests[]`: Array of PRs, each with:
-  - `url`: PR URL
-  - `branch`: Branch name
-  - `baseBranch`: Target branch
-  - `title`: PR title
-  - `status`: One of `DRAFT`, `OPEN`, `MERGED`, `CLOSED`
-  - `repoId`: Associated repository ID
-  - `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). 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:
-    - `runId`: GitHub Actions run ID
-    - `name`: Workflow name
-    - `status`: Run status (`completed`, `in_progress`, `queued`)
-    - `conclusion`: Run conclusion (`success`, `failure`, `cancelled`, `timed_out`, or null)
-    - `url`: GitHub Actions run URL
-    - `jobs`: Array of jobs in the run, each with:
-      - `jobId`: Job ID (use with `get_ci_logs`)
-      - `name`: Job name
-      - `status`: Job status
-      - `conclusion`: Job conclusion (or null)
+- `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>")
@@ -528,67 +419,7 @@ link_reference({
 
 The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command.
 
-### 5. Mark PRs Ready
-
-Once all changes are verified and ready to merge, use `mark_pr_ready` to transition PRs from DRAFT to OPEN status.
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `prUrls` (required): Array of PR URLs to mark as ready for review
-
-```
-mark_pr_ready(
-  sessionId: "<session-id>",
-  prUrls: [
-    "https://github.com/org/frontend/pull/123",
-    "https://github.com/org/backend/pull/456"
-  ]
-)
-```
-
-**After marking PRs as ready**, always print the Polygraph session URL so the user can easily access the session overview. Call `show_session` and display:
-
-```
-**Polygraph session:** POLYGRAPH_SESSION_URL
-```
-
-Where `POLYGRAPH_SESSION_URL` is from `polygraphSessionUrl` in the response.
-
-### 6. Associate Existing PRs
-
-Use `associate_pr` to link pull requests that were created outside of Polygraph (e.g., manually or by CI) to the current session. This is useful when PRs already exist for the branches in the session and you want Polygraph to track them.
-
-Provide either a `prUrl` to associate a specific PR, or a `branch` name plus `repo` to find and associate PRs for a source repository.
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `prUrl` (optional): URL of an existing pull request to associate
-- `branch` (optional): Branch name to find and associate PRs for
-- `repo` (optional): Source repository for branch-based association. Required when using `branch` in a multi-repo session.
-- `description` (required): Must follow the Session Description Policy.
-
-```
-associate_pr(
-  sessionId: "<session-id>",
-  prUrl: "https://github.com/org/repo/pull/123"
-)
-```
-
-Or by branch:
-
-```
-associate_pr(
-  sessionId: "<session-id>",
-  repo: "org/repo",
-  branch: "feature/my-changes"
-)
-```
-
-**Returns** the list of PRs now associated with the session.
-
-### 7. Add Repositories to a Session
+### 4. Add Repositories to a Session
 
 Use `add_repo` to add repositories to an existing Polygraph session after it has already started.
 
@@ -608,7 +439,7 @@ add_repo(
 )
 ```
 
-### 8. Archive Session
+### 5. 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.
 
@@ -722,7 +553,7 @@ 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. 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. **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

@@ -0,0 +1,151 @@
+# Publishing Changes Reference
+
+The branch-to-PR flow: push branches, create draft PRs, mark them ready, and associate PRs created outside Polygraph. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy — read [`session-description.md`](session-description.md) before writing one.
+
+## Push Branches
+
+Once work is complete in a repository, push the branch using `push_branch`. This must be done before creating a PR.
+
+`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:**
+
+- `sessionId` (required): The Polygraph session ID
+- `repo` (required): Repository name or repository ID to push from
+- `branch` (required): Branch name to push to remote
+- `description` (required): A session description is required. Must follow the Session Description Policy.
+
+```
+push_branch(
+  sessionId: "<session-id>",
+  repo: "org/repo-name",
+  branch: "polygraph/ad5fa-add-user-preferences"
+)
+```
+
+## Create Draft PRs
+
+Create PRs for all repositories at once using `create_pr`. PRs are created as drafts with session metadata that links related PRs across repos. Branches must be pushed first. For fork PR creation or registration, include `targetRepository` on the PR spec to identify the repository that should receive the PR.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+- `prs` (required): Array of PR specifications, each containing:
+  - `owner` (required): GitHub repository owner
+  - `repo` (required): GitHub repository name
+  - `title` (required): PR title
+  - `body` (required): PR description (session metadata is appended automatically)
+  - `branch` (required): Branch name that was pushed
+  - `targetRepository` (optional): Target GitHub repository for fork PR creation or registration, as `owner/repo`. Omit for same-repository PRs.
+- `description` (required): Must follow the Session Description Policy.
+
+**PR title format (applies to parent and child agents):**
+
+- PR titles become squash-merge commit messages in most repos. They MUST follow the target repo's commit convention (e.g., Conventional Commits: `<type>(<scope>): <subject>`).
+- Do NOT add agent-identifier prefixes such as `[codex]`, `[claude]`, or `[opencode]` to PR titles. These prefixes violate commit-lint rules and pollute the git history.
+
+```
+create_pr(
+  sessionId: "<session-id>",
+  prs: [
+    {
+      owner: "org",
+      repo: "frontend",
+      title: "feat: Add user preferences UI",
+      body: "Part of multi-repo user preferences feature",
+      branch: "polygraph/ad5fa-add-user-preferences"
+    },
+    {
+      owner: "org",
+      repo: "backend",
+      title: "feat: Add user preferences API",
+      body: "Part of multi-repo user preferences feature",
+      branch: "polygraph/ad5fa-add-user-preferences"
+    }
+  ]
+)
+```
+
+For fork PR creation or registration, keep `owner` and `repo` set to the source repository that owns the pushed branch and set `targetRepository` to the target repository:
+
+```
+create_pr(
+  sessionId: "<session-id>",
+  prs: [
+    {
+      owner: "contributor",
+      repo: "frontend-fork",
+      targetRepository: "org/frontend",
+      title: "feat: Add user preferences UI",
+      body: "Part of multi-repo user preferences feature",
+      branch: "polygraph/ad5fa-add-user-preferences"
+    }
+  ]
+)
+```
+
+**After creating PRs**, always print the Polygraph session URL:
+
+```
+**Polygraph session:** POLYGRAPH_SESSION_URL
+```
+
+## Mark PRs Ready
+
+Once all changes are verified and ready to merge, use `mark_pr_ready` to transition PRs from DRAFT to OPEN status.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+- `prUrls` (required): Array of PR URLs to mark as ready for review
+
+```
+mark_pr_ready(
+  sessionId: "<session-id>",
+  prUrls: [
+    "https://github.com/org/frontend/pull/123",
+    "https://github.com/org/backend/pull/456"
+  ]
+)
+```
+
+**After marking PRs as ready**, always print the Polygraph session URL so the user can easily access the session overview. Call `show_session` and display:
+
+```
+**Polygraph session:** POLYGRAPH_SESSION_URL
+```
+
+Where `POLYGRAPH_SESSION_URL` is from `polygraphSessionUrl` in the response.
+
+## Associate Existing PRs
+
+Use `associate_pr` to link pull requests that were created outside of Polygraph (e.g., manually or by CI) to the current session. This is useful when PRs already exist for the branches in the session and you want Polygraph to track them.
+
+Provide either a `prUrl` to associate a specific PR, or a `branch` name plus `repo` to find and associate PRs for a source repository.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+- `prUrl` (optional): URL of an existing pull request to associate
+- `branch` (optional): Branch name to find and associate PRs for
+- `repo` (optional): Source repository for branch-based association. Required when using `branch` in a multi-repo session.
+- `description` (required): Must follow the Session Description Policy.
+
+```
+associate_pr(
+  sessionId: "<session-id>",
+  prUrl: "https://github.com/org/repo/pull/123"
+)
+```
+
+Or by branch:
+
+```
+associate_pr(
+  sessionId: "<session-id>",
+  repo: "org/repo",
+  branch: "feature/my-changes"
+)
+```
+
+**Returns** the list of PRs now associated with the session.

package/skills/session-debrief/SKILL.md

@@ -26,7 +26,7 @@ Invoke the CLI as `${POLYGRAPH_CLI:-polygraph}` in every command: when the sessi
 
 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.
+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. **Coverage caveat:** `session logs --all` covers default-role children only — agents spawned with a `role` keep their transcripts local to the machine that ran them (viewable there via `polygraph agent attach --role <role>`); if the session used such agents, note in the debrief that their work is not visible in these logs.
 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.