@polygraph/opencode-plugin 0.4.40 → 0.4.42

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/agent-capture-mapping.mjs

@@ -8,13 +8,25 @@
 // every session start and compaction; the CLI reader looks for mapping-*.json
 // files in the per-session sidecars directory.
 //
-// File contract:
+// File contract (must match the Polygraph CLI reader exactly):
+//   <sessionsRoot>/<POLYGRAPH_SESSION_ID>/sidecars/mapping-opencode-<sessionId>.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-opencode-<sessionId>.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 or POLYGRAPH_CHILD_AGENT is set.
 //   - Atomic write via tmp-file rename.
-//   - Refresh: preserves firstSeenAt when a valid prior mapping exists.
+//   - Refresh: preserves firstSeenAt when a valid prior mapping exists
+//     (checked in the new location first, then the legacy flat dir — keeps
+//     firstSeenAt continuity when migrating a mapping from the legacy dir).
 //   - All failures are silently swallowed.
 
 import {
@@ -82,9 +94,34 @@ export function logHookFailure(
   }
 }
 
+// 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.
+function sessionsRoot(home) {
+  const fromEnv = process.env.POLYGRAPH_ROOT?.trim();
+  if (fromEnv) return fromEnv;
+
+  try {
+    const config = JSON.parse(
+      readFileSync(path.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 path.join(home, '.polygraph', 'sessions');
+}
+
 /**
  * Write (or refresh) the agent-capture mapping for an OpenCode session.
- * Reads POLYGRAPH_SESSION_ID and POLYGRAPH_CHILD_AGENT from process.env.
+ *
+ * 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. Reads POLYGRAPH_SESSION_ID and POLYGRAPH_CHILD_AGENT from process.env.
  *
  * @param {string} agentSessionId  The OpenCode session id (input.sessionID).
  * @param {string} [home]          Override HOME for testing.
@@ -99,19 +136,34 @@ export function writeAgentCaptureMapping(
     if (process.env.POLYGRAPH_CHILD_AGENT) return;
     if (!agentSessionId) return;
 
-    const sidecarDir = path.join(home, '.polygraph', 'sidecars', polygraphSessionId);
-    mkdirSync(sidecarDir, { recursive: true });
-
     const filenamePart = sanitizeMappingFilename(`opencode-${agentSessionId}`);
-    const finalPath = path.join(sidecarDir, `mapping-${filenamePart}.json`);
+    const fileName = `mapping-${filenamePart}.json`;
+
+    const sessionDir = path.join(sessionsRoot(home), polygraphSessionId);
+    const sessionSidecarDir = path.join(sessionDir, 'sidecars');
+    const legacyDir = path.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 = path.join(targetDir, fileName);
     const tmpPath = `${finalPath}.tmp-${process.pid}`;
 
     const now = Date.now();
-    let firstSeenAt = now;
 
-    if (existsSync(finalPath)) {
+    // Refresh semantics: preserve firstSeenAt from a valid prior mapping.
+    // Check the new location first, then the legacy flat dir — this keeps
+    // firstSeenAt continuity when migrating a mapping from the legacy dir.
+    let firstSeenAt = now;
+    for (const candidate of [
+      path.join(sessionSidecarDir, fileName),
+      path.join(legacyDir, fileName),
+    ]) {
+      if (!existsSync(candidate)) continue;
       try {
-        const existing = JSON.parse(readFileSync(finalPath, 'utf8'));
+        const existing = JSON.parse(readFileSync(candidate, 'utf8'));
         if (
           existing.version === 1 &&
           existing.polygraphSessionId === polygraphSessionId &&
@@ -119,6 +171,7 @@ export function writeAgentCaptureMapping(
           Number.isFinite(existing.firstSeenAt)
         ) {
           firstSeenAt = existing.firstSeenAt;
+          break;
         }
       } catch {
         // ignore — treat as missing

package/agents/polygraph-delegate-subagent.md

@@ -20,13 +20,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.
 
@@ -35,6 +36,7 @@ spawn_agent(
   sessionId: "<sessionId>",
   repo: "<repo>",
   instruction: "<instruction>",
+  role: "<role, if any>",
   context: "<context>"
 )
 ```
@@ -49,6 +51,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
 )
 ```
@@ -65,7 +68,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.
@@ -79,14 +82,14 @@ 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.
 
 3. `child.status === 'permission-required'` — child is paused waiting for a permission grant decision:
    - Read `child.pendingPermission` — inspect `harness`, `action`, `target`, `repoFullName`, `scope`, `availableScopes`, and optional `reason`/`rawInput`.
    - Surface the request to the parent/user: "Child agent in `{repoFullName}` requests `{scope}` permission to run `{action}` on `{target}`."
    - Wait for the parent/user to decide.
-   - Call `allow_agent` (to grant) or `deny_agent` (to refuse) with `{ sessionId, repo }` — `allow_agent` also takes `scope` (`'one-time'` or `'session'`) and an optional `reason`; `deny_agent` takes only `{ sessionId, repo }` plus an optional `reason`.
+   - Call `allow_agent` (to grant) or `deny_agent` (to refuse) with `{ sessionId, repo, role? }` — `allow_agent` also takes `scope` (`'one-time'` or `'session'`) and an optional `reason`; `deny_agent` takes only an optional `reason` on top.
    - **Fail-closed:** When you see `permission-required`, you MUST call either `allow_agent` or `deny_agent`. Failing to call one leaves the gate held open until the child's idle timer fires; the child cannot make progress until you decide.
    - Resume polling.
 
@@ -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.md

@@ -0,0 +1,27 @@
+---
+
+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.
+mode: subagent
+
+---
+
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/opencode-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/server.js

@@ -166,33 +166,57 @@ function polygraphCompactionNote(agentSessionId, root) {
   );
 }
 
-function readPolygraphSession(
-  agentSessionId,
-  root = path.join(homedir(), '.polygraph')
-) {
-  if (!agentSessionId) {
+// Scan the immediate subdirectories of `baseDir`; for each, `candidatePath`
+// maps the subdirectory name to a candidate parent-sidecar file. Returns the
+// sessionId of the first match, or undefined.
+function scanForParentSidecar(baseDir, candidatePath) {
+  if (!existsSync(baseDir)) {
     return undefined;
   }
 
-  const sidecarsDir = path.join(root, 'sidecars');
-  if (!existsSync(sidecarsDir)) {
+  let entries;
+  try {
+    entries = readdirSync(baseDir, { withFileTypes: true });
+  } catch {
     return undefined;
   }
 
-  const fileName = `parent-${agentSessionId}.json`;
-  let polygraphSessionId;
-  for (const entry of readdirSync(sidecarsDir, { withFileTypes: true })) {
+  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)) {
       try {
-        polygraphSessionId = JSON.parse(readFileSync(candidate, 'utf8')).sessionId;
+        return JSON.parse(readFileSync(candidate, 'utf8')).sessionId;
       } catch {
-        polygraphSessionId = undefined;
+        return undefined;
       }
-      break;
     }
   }
+  return undefined;
+}
+
+function readPolygraphSession(
+  agentSessionId,
+  root = path.join(homedir(), '.polygraph')
+) {
+  if (!agentSessionId) {
+    return undefined;
+  }
+
+  const fileName = `parent-${agentSessionId}.json`;
+
+  // New layout: <sessionsRoot>/<sessionId>/sidecars/parent-<agentSessionId>.json
+  // (sessionsRoot = $POLYGRAPH_ROOT or <root>/sessions), with a fallback to
+  // the legacy shared sidecars directory for sessions created by older CLIs.
+  const sessionsDir = process.env.POLYGRAPH_ROOT?.trim() || path.join(root, 'sessions');
+  const legacyDir = path.join(root, 'sidecars');
+  const polygraphSessionId =
+    scanForParentSidecar(sessionsDir, (sessionId) =>
+      path.join(sessionsDir, sessionId, 'sidecars', fileName)
+    ) ??
+    scanForParentSidecar(legacyDir, (sessionId) =>
+      path.join(legacyDir, sessionId, fileName)
+    );
   if (!polygraphSessionId) {
     return undefined;
   }

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

@@ -163,7 +163,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

@@ -20,9 +20,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. |
@@ -71,10 +71,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.
@@ -202,15 +202,23 @@ 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.
 
 **CRITICAL:** `spawn_agent` and `show_agent` MUST ALWAYS be called via `@polygraph-delegate-subagent`, NEVER directly from the main conversation. Direct calls flood the context window with polling noise and degrade the user experience. This is a hard requirement, not a suggestion.
 
-1. For each repo, invoke `@polygraph-delegate-subagent` with `sessionId`, `repo`, `instruction`, and optional `context`. The subagent calls `spawn_agent`, then polls `show_agent` via chained `waitForTransitionMs` long-poll calls until terminal.
-2. Delegate to multiple repos in parallel by launching multiple `@polygraph-delegate-subagent` invocations — 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).
+1. For each repo, invoke `@polygraph-delegate-subagent` with `sessionId`, `repo`, `instruction`, optional `role`, and optional `context`. The subagent calls `spawn_agent`, then polls `show_agent` via chained `waitForTransitionMs` long-poll calls until terminal.
+2. Delegate to multiple repos in parallel by launching multiple `@polygraph-delegate-subagent` invocations — 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. Once all subagents report a terminal status, continue to `push_branch` + `create_pr`.
 
 Use Simple when the task is well-defined and the child will not need clarification.
@@ -219,13 +227,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'`.
@@ -235,13 +243,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
    {
@@ -253,7 +261,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.
 
@@ -267,7 +275,7 @@ Child agents running in other repositories may pause and ask the parent agent wh
 
 **Native path (MCP permission dialog):** If your MCP client supports the permission dialog UI, the user picks directly in that dialog — you (the agent) won't see `permission-required` tasks in that flow.
 
-**Structured fallback path:** When `cloud_polygraph_child_status` reports a task in `permission-required` state, read the `pendingPermission` object on that task (carries `harness`, `action`, `target`, `repositoryId`, `repoFullName`, `scope`, `availableScopes`, optional `reason`, optional `rawInput`), then call `allow_agent` (to grant the requested action) or `deny_agent` (to refuse it) with the `{sessionId, repo}` of the child agent.
+**Structured fallback path:** When `cloud_polygraph_child_status` reports a task in `permission-required` state, read the `pendingPermission` object on that task (carries `harness`, `action`, `target`, `repositoryId`, `repoFullName`, `scope`, `availableScopes`, optional `reason`, optional `rawInput`), then call `allow_agent` (to grant the requested action) or `deny_agent` (to refuse it) with the `{sessionId, repo, role?}` of the child agent.
 
 ### Answering a permission request
 
@@ -276,6 +284,7 @@ Child agents running in other repositories may pause and ask the parent agent wh
 {
   "sessionId": "...",
   "repo": "org/repo-name",
+  "role": "reviewer",              // optional
   "scope": "session",              // or "one-time"
   "reason": "Trusted local repo"   // optional
 }
@@ -285,6 +294,7 @@ Child agents running in other repositories may pause and ask the parent agent wh
 {
   "sessionId": "...",
   "repo": "org/repo-name",
+  "role": "reviewer",              // optional
   "reason": "Action looks risky"   // optional
 }
 // — call `deny_agent` with this payload.
@@ -307,29 +317,14 @@ When polling `cloud_polygraph_child_status` (or `show_agent`), treat `permission
 1. Read `child.pendingPermission` — inspect `harness`, `action`, `target`, `repoFullName`, and `scope`.
 2. Surface the request to the user: "Child agent in `{repoFullName}` requests `{scope}` permission to run `{action}` on `{target}`."
 3. Obtain the user's decision.
-4. Call `allow_agent` (to grant) or `deny_agent` (to refuse) with `{ sessionId, repo }`.
+4. Call `allow_agent` (to grant) or `deny_agent` (to refuse) with `{ sessionId, repo, role? }`.
 5. Resume polling.
 
-### 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
 
@@ -337,121 +332,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>")
@@ -498,67 +390,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.
 
@@ -578,7 +410,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.
 
@@ -692,6 +524,6 @@ If the session has a description timeline, also display:
    
 1. **NEVER call `spawn_agent` or `show_agent` directly**. These MUST ALWAYS go through `@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.
    

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.