@polygraph/claude-plugin 0.4.35 → 0.4.36

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "polygraph",
-  "version": "0.4.35",
-  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
+  "version": "0.4.36",
+  "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "author": {
     "name": "Narwhal Technologies Inc",
     "email": "hello@nrwl.io",

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/polygraph-skills/source/assets/polygraph-light.svg">
-    <img src="https://raw.githubusercontent.com/nrwl/polygraph-skills/source/assets/polygraph.svg" alt="Polygraph Logo" width="140">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/polygraph-skills/main/source/assets/polygraph-light.svg">
+    <img src="https://raw.githubusercontent.com/nrwl/polygraph-skills/main/source/assets/polygraph.svg" alt="Polygraph Logo" width="140">
   </picture>
 </p>
 
@@ -37,7 +37,7 @@ It detects your AI agent — Claude Code, Codex, OpenCode, and more — and inst
 
 ## Skills
 
-- **polygraph** — Comprehensive guidance for multi-repo coordination: session init, delegation, branch pushing, PR creation, and session management
+- **polygraph** — Comprehensive guidance for Polygraph sessions: shared context, repository graph visibility, PR/CI state, delegation, and session management
 - **await-polygraph-ci** — Wait for CI pipelines to settle across all repos in a session, investigate failures, and present fix options
 - **get-latest-ci** — One-shot fetch of the latest CI pipeline execution for the current branch
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.4.35",
-  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
+  "version": "0.4.36",
+  "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,
   "author": {

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

@@ -19,9 +19,30 @@ Wait for all CI pipelines in a Polygraph session to reach a stable state (succee
 
 Some Polygraph tools have both MCP and CLI equivalents — use whichever is available in your environment. See the polygraph skill's tool table for the full mapping.
 
+## CI status source
+
+CI polling uses the polygraph-mcp `show_session` tool, which now carries per-PR CI status directly on each pull request:
+
+```
+show_session(sessionId: "<session-id>")
+```
+
+It returns the full session, including `repositories[]` (for repo display names) and `pullRequests[]`. Each `pullRequests[]` entry has `id`, `repositoryId`, `url`, `branch`, `status` (PR status: `DRAFT` / `OPEN` / `MERGED` / `CLOSED`), and a `ci` object — **`ci` may be absent if the PR has no CI**. When present, `ci` has `status`, `cipeUrl` (non-null ⇒ CIPE; null + `externalCIRuns` ⇒ external CI), `completedAt`, `selfHealingStatus`, and `externalCIRuns[]` (each with `runId`, `name`, `status`, `conclusion`, `url`, and `jobs[]`). Always read `ci` defensively (`pr.ci?.…`).
+
+## Prerequisite: Nx MCP server (CIPE deep-dive + self-healing)
+
+CIPE failure investigation (`ci_information`) and applying/rejecting self-healing fixes (`update_self_healing_fix`) are **not** polygraph-mcp tools — they are provided by the **Nx MCP server** (`mcp__plugin_nx_nx-mcp`). Before relying on the Phase 4 CIPE deep-dive or the Phase 5 self-healing actions, install the Nx MCP server and verify it is available.
+
+If the Nx MCP server is **not** available, this skill can still:
+
+- Monitor CI to a terminal state (Phases 1–3) via `show_session`, and
+- Download and inspect **external-CI** job logs via `get_ci_logs` (a polygraph-mcp tool).
+
+But it **cannot** perform CIPE deep-dives (`ci_information`) or apply self-healing fixes (`update_self_healing_fix`) without the Nx MCP server. If nx-mcp is missing, state this limitation to the user explicitly.
+
 ## Phase 1: Session Setup
 
-Fetch the Polygraph session using `show_session`.
+Fetch the session using `show_session` and read per-PR CI status from `pullRequests[]`.
 
 **Parameters:**
 
@@ -32,16 +53,18 @@ show_session(sessionId: "<session-id>")
 ```
 
 1. Record `monitorStartedAt` = current timestamp (epoch millis).
-2. Build a tracking table of all repos with PRs. For each PR, record:
-   - `repo`: repository name
-   - `prUrl`: PR URL
-   - `prStatus`: DRAFT / OPEN / MERGED / CLOSED
-   - `ciStatus`: from session (may already be a terminal status from a previous run)
-   - `cipeUrl`: CI pipeline URL (null if none)
-   - `cipeCompletedAt`: `completedAt` from session (epoch millis, null if CIPE is active or absent)
-   - `selfHealingStatus`: self-healing fix status (null if none)
+2. Build a tracking table from `pullRequests[]`. For each PR, map:
+   - `repo`: repository display name from the matching `repositories[]` entry by `pr.repositoryId` (fall back to `pr.branch` if not found)
+   - `repoId`: `pr.repositoryId` (pass straight to `get_ci_logs`)
+   - `prUrl`: `pr.url`
+   - `prStatus`: `pr.status` (DRAFT / OPEN / MERGED / CLOSED)
+   - `ciStatus`: `pr.ci?.status` (may already be a terminal status from a previous run)
+   - `cipeUrl`: `pr.ci?.cipeUrl` (null if none → external CI or no CI)
+   - `cipeCompletedAt`: `pr.ci?.completedAt` (epoch millis, null if CIPE is active or absent)
+   - `selfHealingStatus`: `pr.ci?.selfHealingStatus` (null if none)
+   - `jobs`: `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)` (external-CI job list, used in Phase 4)
    - `firstSeenAt`: current timestamp
-3. If no PRs found, report "No PRs in session" and exit.
+3. If `pullRequests[]` is empty, report "No PRs in session" and exit.
 4. **Stale detection**: For each PR, determine if its CI status is **stale** — meaning it reflects a previous run, not a current one. A PR's CI status is stale if:
    - `cipeCompletedAt` is non-null AND `cipeCompletedAt < monitorStartedAt` (the CIPE finished before the monitor started)
    - Mark these PRs as `stale: true`
@@ -61,7 +84,7 @@ show_session(sessionId: "<session-id>")
 **Each poll iteration:**
 
 1. Call `show_session(sessionId: <session-id>)`
-2. Update each tracked PR from the session response: `ciStatus`, `cipeUrl`, `cipeCompletedAt`, and `selfHealingStatus`
+2. Update each tracked PR from its matching `pullRequests[]` entry (by PR `id` / `repositoryId`): `ciStatus` ← `pr.ci?.status`, `cipeUrl` ← `pr.ci?.cipeUrl`, `cipeCompletedAt` ← `pr.ci?.completedAt`, `selfHealingStatus` ← `pr.ci?.selfHealingStatus`, `prStatus` ← `pr.status`, and `jobs` ← `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)`
 3. **Clear stale flag**: If a PR was marked `stale: true` and its `cipeCompletedAt` has changed (or become null, meaning a new CIPE is active), clear the stale flag — this PR now has fresh CI data.
 4. Display status update:
    ```
@@ -109,18 +132,18 @@ Include self-healing status for any repo that has one.
 
 ## Phase 4: Failure Investigation (Child Agent Delegation)
 
-For each repo with `ciStatus: FAILED`, first check the CI data source from `ciStatus[prId]`:
+For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show_session` (`pullRequests[]`):
 
-- **If `cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using `ci_information`.
-- **If `cipeUrl` is null but `externalCIRuns` exists** → external CI only. Examine failed jobs from `externalCIRuns` in the session data and use `get_ci_logs` for log retrieval.
+- **If `pr.ci.cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using the Nx MCP `ci_information` tool (requires the Nx MCP server — see the prerequisite note above; if nx-mcp is unavailable, report the CIPE URL but note the deep-dive can't run).
+- **If `pr.ci.cipeUrl` is null but `pr.ci.externalCIRuns` exists** → external CI only. Examine failed jobs from `pr.ci.externalCIRuns[].jobs` and use `get_ci_logs(sessionId, repositoryId, jobId)` (a polygraph-mcp tool) for log retrieval, passing `pr.repositoryId` and the failed job's `jobId` straight from the same PR object.
 
-1. Display known info from the session data before delegating:
+1. Display known info from the PR's `ci` object before delegating:
 
    ```
    Repository: frontend
    CI Source: <CIPE or External CI (GitHub Actions)>
-   CI Pipeline: <cipeUrl from session, or GitHub Actions run URL>
-   Self-healing: <selfHealingStatus from session, or "None">
+   CI Pipeline: <pr.ci.cipeUrl, or GitHub Actions run URL>
+   Self-healing: <pr.ci.selfHealingStatus, or "None">
    Investigating failure details...
    ```
 
@@ -128,9 +151,9 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
 
    - `sessionId`: the session ID
    - `repo`: the repository name
-   - `instruction` (when CIPE exists): Use the `ci_information` tool to investigate the CI failure on this branch. Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
-   - `instruction` (when no CIPE, external CI only): The session data shows external CI failures with these failed jobs: [list jobId + name from `externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repoId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
-   - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is available from the session data.
+   - `instruction` (when CIPE exists): Use the Nx MCP `ci_information` tool to investigate the CI failure on this branch (the Nx MCP server must be installed). Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
+   - `instruction` (when no CIPE, external CI only): The PR's `ci` object shows external CI failures with these failed jobs: [list `jobId` + `name` from `pr.ci.externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repositoryId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
+   - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is the PR's `repositoryId`.
 
    Since `spawn_agent` is non-blocking, you can delegate to multiple failed repos in parallel.
 
@@ -165,7 +188,7 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
 2. Identify cross-repo dependency issues (e.g., shared-lib build failure blocking frontend)
 3. Suggest fix order based on dependency graph (upstream repos first)
 4. Present next actions to the user based on self-healing status:
-   - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it
+   - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it. `update_self_healing_fix` is an **Nx MCP** tool (`mcp__plugin_nx_nx-mcp`) — it requires the Nx MCP server. If nx-mcp is unavailable, report that a fix is available but cannot be applied from here.
    - If self-healing was already applied → offer to **resume monitoring** to watch the re-triggered CI
    - **Delegate fixes**: use Polygraph to send fix instructions to child agents (for repos without self-healing or where self-healing was rejected/failed)
    - **Get more details**: drill into a specific repo's failure
@@ -173,10 +196,10 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
 
 ## Notes
 
-- This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, which is an Nx Cloud operation (not a local code change).
-- Both `ci_information` and `update_self_healing_fix` responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
+- This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, an **Nx MCP** tool that performs an Nx Cloud operation (not a local code change) and requires the Nx MCP server.
+- Both `ci_information` and `update_self_healing_fix` are **Nx MCP** tools (`mcp__plugin_nx_nx-mcp`), not polygraph-mcp tools. Their responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
 - All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
 
-- Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`ciStatus[prId].cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via `ci_information`. Job IDs come from `ciStatus[prId].externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
+- Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`pr.ci.cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via the Nx MCP `ci_information` tool. Job IDs come from `pr.ci.externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
 - `spawn_agent` is **non-blocking** — it starts the child agent and returns immediately. Use `show_agent` to poll for results and `stop_agent` to terminate stuck agents.
 - The `show_session` response is compact and safe to poll from the main agent.

package/skills/polygraph/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: polygraph
-description: Guidance for working with Polygraph — repositories, sessions, child agents, PRs, and CI. Use when discovering repositories or how code is consumed across them, starting, joining, resuming, or sharing a Polygraph session, handing off progress, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
+description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
 
 allowed-tools:
   - mcp__plugin_polygraph_polygraph-mcp
@@ -15,6 +15,28 @@ Polygraph connects repositories and the agent work happening across them. Its ce
 
 **Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repositories are worked on in separate Polygraph-managed clones via `spawn_agent`.
 
+## Sandboxing in Polygraph Sessions
+
+Polygraph launches agent sessions inside an OS-level sandbox by default. Writes are limited to the repository working tree, the session root (`~/.polygraph/sessions/<session-id>/`), the system temp directory, and a few allowlisted directories; network access is restricted to allowlisted hosts. In practice: binding a listening socket is denied (dev servers fail with `EPERM`), localhost servers are unreachable, and writes outside the allowlist are rejected. The user may not know the session is sandboxed.
+
+**Recognize sandbox denials — do not retry or work around them.** When a command fails in a sandbox-shaped way (`EPERM` binding a port, a blocked network host, a denied write to an ordinary path), the sandbox blocked it. Do NOT retry variations, escalate through workarounds, or route the command through `!`-prefixed user commands — those run inside the same sandbox. One failure is enough evidence; stop and inform the user.
+
+**Warn before attempting known-blocked operations.** Before starting a dev server, anything else that listens on a port, or an operation that needs writes or network access outside the allowlist, tell the user up front that it will not work while sandboxing is on and offer the options below instead of attempting it.
+
+**What to tell the user.** Explain that Polygraph runs this session in a sandbox, then present both options. Each takes effect on the next agent launch, so the Polygraph session must be relaunched afterwards:
+
+1. **Keep the sandbox on and allow the specific operation** (preferred). The sandbox belongs to the agent harness, so exceptions live in harness settings committed to the repository; array settings merge with Polygraph's generated allowlist rather than replacing it. Add writable paths to `.claude/settings.json` (or `.claude/settings.local.json`):
+
+   ```json
+   { "sandbox": { "filesystem": { "allowWrite": ["<path>"] } } }
+   ```
+
+   The `.claude/` directory is read-only inside the sandbox, so give the user the exact snippet to commit — you cannot apply it yourself.
+
+2. **Turn sandboxing off.** The user quits the agent, runs `polygraph config`, toggles **Agent Options → Claude → sandbox** off (or per-repo under **Repo Options**), and relaunches the Polygraph session. Non-interactive alternative: set `agentOptions.claude.sandbox: false` (or `repoOptions."org/repo".sandbox: false`) in `~/.polygraph/config.json`. Warn that this removes filesystem isolation — the agent can then write anywhere the OS user can.
+
+**Never blame the tooling.** A sandbox denial means the environment blocked the operation — not that the repo, tool, or framework is broken. Do not record conclusions like "X is unusable" in memory, session descriptions, or messages based on sandboxed failures.
+
 ## Available Tools
 
 Polygraph functionality is available via both MCP tools and CLI commands. Use whichever is available in your current environment.
@@ -55,10 +77,13 @@ Before using Polygraph tools, ensure the CLI is authenticated and an organizatio
 
 ### Check Authentication
 
-Use `polygraph whoami` (or the `whoami` MCP tool) to check if the user is currently logged in and which organization is active.
+Use `polygraph whoami` (or the `whoami` MCP tool) before session work to check if the user is currently logged in and which organization is active.
 
 - If the user **is logged in** and an org is selected → proceed to the workflow.
-- If the user **is not logged in** → use `polygraph auth login` (or the `login` MCP tool) to authenticate. After login, an organization must be selected.
+- If auth is **missing, expired, or no org is selected** → stop session work. Do not keep trying session creation, repository discovery, delegation, or CI checks.
+- Facilitate user reauth through the browser-based login flow, such as `polygraph auth login` (or the `login` MCP tool). In interactive desktop clients, browser reauth is usually user-driven; surface the need clearly and wait for the user to complete it.
+- After login, an organization must be selected. Use `polygraph account select` (or the MCP equivalent) when needed.
+- Re-run `polygraph whoami` (or `whoami`) after reauth and org selection. Continue only after it confirms a valid login and selected organization.
 
 ### Select Organization
 
@@ -101,6 +126,8 @@ In case B, call `add_repo` yourself when exact repo refs were provided; otherwis
 
 - For a new session (case C), `start_session` auto-generates a unique session ID. You do NOT need to pass one.
 - For cases A and B, the session ID already exists; reuse it everywhere — never let `start_session` run in this conversation.
+- The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
+- For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
 
 **Launch the init subagent** (cases B and C — skip in case A):
 
@@ -656,3 +683,6 @@ If the session has a description timeline, also display:
    
 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. **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/session-start/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: session-start
+description: Start or reconnect a Polygraph session for shared, resumable agent context. Use when the user asks to start a Polygraph session, create session memory, share or resume work context, include related repositories, or inspect an existing session before continuing.
+
+allowed-tools:
+  - mcp__plugin_polygraph_polygraph-mcp
+
+---
+
+# Start a Polygraph Session
+
+Start or reconnect a Polygraph session so the current work has shared, resumable context: session URL, repository graph visibility, linked PR/CI state, and the option to expand across repository boundaries when needed.
+
+## Check Authentication First
+
+Before session work, the parent conversation must check Polygraph auth with `whoami` or `polygraph whoami`.
+
+- If auth is valid and an organization is selected, continue.
+- If auth is missing, expired, or no organization is selected, stop session work. Do not keep trying session creation or discovery.
+- Facilitate user reauth through the browser-based flow, such as `polygraph auth login` or the MCP `login` equivalent. After login, make sure an organization is selected with `polygraph account select` or the MCP equivalent when needed.
+- Re-run `whoami` after reauth. Continue only after it confirms a valid login and selected organization.
+
+Do not breeze past auth failures. In Codex Desktop, auth recovery usually requires the user to complete the browser login flow; surface that clearly and wait for it before continuing.
+
+## Parent Session Detection
+
+The parent conversation is responsible for detecting an existing Polygraph session ID from the current context, startup banner, or user-provided session URL/ID, then passing that `sessionId` explicitly to `polygraph-init-subagent` when launching it. The init subagent cannot infer the parent's current session context by itself.
+
+For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected. Launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
+
+## Decide the Session Path
+
+Pick one path before using tools.
+
+1. **Existing session with repos** - If a Polygraph session ID is already in scope and the user did not ask to add repositories, call `show_session` to inspect it and print the session details. Do not create a new session.
+2. **Existing session, adding exact repository refs** - If a session ID is in scope and the user provided exact refs by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo(sessionId, repoIds: [...])` directly. Do not run discovery.
+3. **Existing session, discovery needed** - If a session ID is in scope but repos need to be discovered or selected, launch `polygraph-init-subagent` with the existing `sessionId` and `userContext`. The subagent must use `add_repo`, not `start_session`.
+4. **No session in scope** - Launch `polygraph-init-subagent` with `userContext` and no `sessionId`. The subagent will discover related repositories when needed and call `start_session`.
+
+Exact refs are not limited to organization repos. Public open-source repos can be added by `owner/repo` slug or URL even if they do not appear in repository discovery.
+
+Launch the plugin-namespaced `polygraph:polygraph-init-subagent` Task for discovery or new-session creation. Use direct `add_repo` only for exact refs on an existing session.
+
+## Print the Result
+
+When a brand-new session is created, render the session welcome card. Prefer the `session_intro` MCP tool when available; otherwise run `polygraph session intro -s <sessionId>` and print the returned markdown verbatim.
+
+For an existing or reconnected session, print:
+
+**Session:** POLYGRAPH_SESSION_URL
+
+**Repositories in this session:**
+
+- REPO_FULL_NAME
+
+Use `polygraphSessionUrl` from the session response for `POLYGRAPH_SESSION_URL`, and use repository entries from the session response for `REPO_FULL_NAME`.