@polygraph/opencode-plugin 0.4.45 → 0.4.46

package/agent-session-link.mjs

@@ -0,0 +1,202 @@
+// source/hooks/agent-session-link.mjs
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+var HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+var AGENT_TYPES = /* @__PURE__ */ new Set(["claude", "codex", "opencode"]);
+var COMMAND_HOOK_TOOL = /^mcp__(?:plugin_polygraph_)?polygraph[-_]mcp__/;
+var OPENCODE_TOOL = /^polygraph(?:(?:-|_)mcp)?_/;
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function isManagedChildEnvironment(env) {
+  return Boolean(env && Object.hasOwn(env, "POLYGRAPH_CHILD_AGENT"));
+}
+function isPolygraphMcpToolName(toolName) {
+  const name = nonEmptyString(toolName);
+  return Boolean(name && (COMMAND_HOOK_TOOL.test(name) || OPENCODE_TOOL.test(name)));
+}
+function buildLinkAgentSessionArgs({
+  polygraphSessionId,
+  agentType,
+  agentSessionId,
+  cwd,
+  transcriptPath,
+  pid,
+  source
+}) {
+  const session = nonEmptyString(polygraphSessionId);
+  const harnessSession = nonEmptyString(agentSessionId);
+  const claimSource = nonEmptyString(source);
+  if (!AGENT_TYPES.has(agentType)) throw new Error(`Unsupported agent type: ${agentType}`);
+  if (!harnessSession) throw new Error("agentSessionId is required");
+  if (!claimSource) throw new Error("source is required");
+  const args = ["_link-agent-session"];
+  if (session) args.push("--session", session);
+  args.push("--agent-type", agentType, "--agent-session-id", harnessSession);
+  const workingDirectory = nonEmptyString(cwd);
+  if (workingDirectory) args.push("--cwd", workingDirectory);
+  const transcript = nonEmptyString(transcriptPath);
+  if (transcript) args.push("--transcript-path", transcript);
+  if (Number.isSafeInteger(pid) && pid > 0) {
+    args.push("--pid", String(pid));
+  }
+  args.push("--source", claimSource);
+  return args;
+}
+function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
+  if (isManagedChildEnvironment(env)) return false;
+  const args = buildLinkAgentSessionArgs(claim);
+  const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? "polygraph";
+  const commandEnv = nonEmptyString(claim.polygraphSessionId) ? env : { ...env };
+  if (commandEnv !== env) {
+    delete commandEnv.POLYGRAPH_SESSION_ID;
+    delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+  }
+  const result = spawn(command, args, {
+    encoding: "utf8",
+    env: commandEnv,
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  if (result?.error) throw result.error;
+  if (result?.status !== 0) {
+    const detail = nonEmptyString(result?.stderr);
+    throw new Error(
+      `polygraph _link-agent-session exited with status ${String(result?.status)}` + (detail ? `: ${detail}` : "")
+    );
+  }
+  return true;
+}
+function logHookFailure(hook, error, meta = {}, home = process.env.HOME?.trim() || homedir()) {
+  try {
+    const logsDir = join(home, ".polygraph", "logs");
+    mkdirSync(logsDir, { recursive: true });
+    const logFile = join(logsDir, "hooks.log");
+    try {
+      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync(logFile, `${logFile}.1`);
+      }
+    } catch {
+    }
+    const entry = {
+      time: (/* @__PURE__ */ new Date()).toISOString(),
+      hook,
+      pid: process.pid,
+      ...meta,
+      error: error instanceof Error ? error.message : String(error),
+      ...error instanceof Error && error.stack ? { stack: error.stack } : {}
+    };
+    appendFileSync(logFile, JSON.stringify(entry) + "\n");
+  } catch {
+  }
+}
+
+// source/opencode/agent-session-link.mjs
+function sessionRecord(result) {
+  if (result?.error) {
+    throw new Error(`OpenCode session lookup failed: ${JSON.stringify(result.error)}`);
+  }
+  const record = result && typeof result === "object" && Object.hasOwn(result, "data") ? result.data : result;
+  return record && typeof record === "object" && !Array.isArray(record) ? record : void 0;
+}
+async function resolveOpenCodeRootSessionId(client, sessionId) {
+  if (!sessionId) return void 0;
+  if (typeof client?.session?.get !== "function") {
+    throw new Error("OpenCode client.session.get is unavailable");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let current = sessionId;
+  while (current) {
+    if (seen.has(current)) {
+      throw new Error(`OpenCode session parent cycle detected at ${current}`);
+    }
+    seen.add(current);
+    const record = sessionRecord(
+      await client.session.get({ path: { id: current } })
+    );
+    if (!record) {
+      throw new Error(`OpenCode session ${current} was not found`);
+    }
+    if (record.id !== current) {
+      throw new Error(`OpenCode session lookup returned ${String(record.id)} for ${current}`);
+    }
+    if (!record.parentID) return current;
+    if (typeof record.parentID !== "string") {
+      throw new Error(`OpenCode session ${current} has an invalid parentID`);
+    }
+    current = record.parentID;
+  }
+  return void 0;
+}
+async function linkOpenCodeSessionCreatedEvent(input, sessionLinker) {
+  const event = input?.event;
+  if (event?.type !== "session.created") return false;
+  return sessionLinker.fromSessionCreated(event.properties?.info);
+}
+function deferOpenCodeToolActivity(input, sessionLinker, onError, schedule = setTimeout) {
+  schedule(() => {
+    Promise.resolve(sessionLinker.fromToolActivity(input)).catch(onError);
+  }, 0);
+}
+function createOpenCodeSessionLinker({
+  client,
+  directory,
+  env = process.env,
+  pid = process.pid,
+  link,
+  spawn
+} = {}) {
+  const roots = /* @__PURE__ */ new Map();
+  const linkedLifecycleSessions = /* @__PURE__ */ new Set();
+  const submitLink = link ?? ((claim) => linkAgentSession(claim, spawn, env));
+  async function rootSessionId(sessionId) {
+    if (!sessionId) return void 0;
+    if (roots.has(sessionId)) return roots.get(sessionId);
+    const root = await resolveOpenCodeRootSessionId(client, sessionId);
+    if (root) roots.set(sessionId, root);
+    return root;
+  }
+  async function submit(openCodeSessionId, cwd, polygraphSessionId) {
+    if (!openCodeSessionId || env && Object.hasOwn(env, "POLYGRAPH_CHILD_AGENT")) {
+      return false;
+    }
+    const agentSessionId = await rootSessionId(openCodeSessionId);
+    if (!agentSessionId) return false;
+    const lifecycleKey = polygraphSessionId ? `${polygraphSessionId}\0${agentSessionId}` : void 0;
+    if (lifecycleKey && linkedLifecycleSessions.has(lifecycleKey)) return false;
+    const linked = await submitLink({
+      ...polygraphSessionId ? { polygraphSessionId } : {},
+      agentType: "opencode",
+      agentSessionId,
+      cwd: cwd || directory || process.cwd(),
+      pid,
+      source: "hook"
+    });
+    if (linked && lifecycleKey) linkedLifecycleSessions.add(lifecycleKey);
+    return linked;
+  }
+  async function fromEnvironment(sessionId, cwd) {
+    if (!env.POLYGRAPH_SESSION_ID) return false;
+    return submit(sessionId, cwd, env.POLYGRAPH_SESSION_ID);
+  }
+  return {
+    async fromSessionCreated(info) {
+      if (!info?.id || info.parentID) return false;
+      roots.set(info.id, info.id);
+      return fromEnvironment(info.id, info.directory);
+    },
+    fromEnvironment,
+    async fromToolActivity(input) {
+      if (!isPolygraphMcpToolName(input?.tool)) return false;
+      return submit(input?.sessionID);
+    }
+  };
+}
+export {
+  createOpenCodeSessionLinker,
+  deferOpenCodeToolActivity,
+  linkOpenCodeSessionCreatedEvent,
+  logHookFailure,
+  resolveOpenCodeRootSessionId
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/opencode-plugin",
-  "version": "0.4.45",
+  "version": "0.4.46",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,
@@ -24,7 +24,7 @@
   },
   "files": [
     "server.js",
-    "agent-capture-mapping.mjs",
+    "agent-session-link.mjs",
     "skills/",
     "agents/",
     "README.md"

package/server.js

@@ -5,7 +5,7 @@
 // plugin loading ENTIRELY for every user who has the plugin installed.
 //
 // DO NOT add new exports to this file. Put shared or testable logic in sibling
-// modules under source/opencode/ (e.g. agent-capture-mapping.mjs) and import
+// modules under source/opencode/ (e.g. agent-session-link.mjs) and import
 // it here instead.
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
@@ -14,17 +14,34 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
 
-import { writeAgentCaptureMapping, logHookFailure } from './agent-capture-mapping.mjs';
+import {
+  createOpenCodeSessionLinker,
+  deferOpenCodeToolActivity,
+  linkOpenCodeSessionCreatedEvent,
+  logHookFailure,
+} from './agent-session-link.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = __dirname;
 const skillsDir = path.join(packageRoot, 'skills');
 const agentsDir = path.join(packageRoot, 'agents');
 
-export const PolygraphPlugin = async () => {
+export const PolygraphPlugin = async ({ client, directory } = {}) => {
   const agents = loadAgents();
+  const sessionLinker = createOpenCodeSessionLinker({ client, directory });
 
   return {
+    event: async (input) => {
+      try {
+        await linkOpenCodeSessionCreatedEvent(input, sessionLinker);
+      } catch (error) {
+        logHookFailure('opencode:event', error, {
+          eventType: input?.event?.type,
+          sessionID: input?.event?.properties?.info?.id,
+        });
+      }
+    },
+
     config: async (cfg) => {
       cfg.skills ??= {};
       cfg.skills.paths ??= [];
@@ -42,15 +59,22 @@ export const PolygraphPlugin = async () => {
       try {
         output.env.POLYGRAPH_AGENT_SESSION_ID = input.sessionID;
         output.env.POLYGRAPH_AGENT_TYPE = 'opencode';
-        // Record the agent-capture mapping so the Polygraph CLI can bind
-        // parent-log capture deterministically for this session.
-        writeAgentCaptureMapping(input.sessionID);
+        await sessionLinker.fromEnvironment(input.sessionID, input.cwd);
       } catch (error) {
         // Never let a hook failure break the OpenCode session; just record it.
         logHookFailure('opencode:shell.env', error, { sessionID: input?.sessionID });
       }
     },
 
+    'tool.execute.after': async (input) => {
+      deferOpenCodeToolActivity(input, sessionLinker, (error) => {
+        logHookFailure('opencode:tool.execute.after', error, {
+          sessionID: input?.sessionID,
+          tool: input?.tool,
+        });
+      });
+    },
+
     // OpenCode has no SessionStart hook, but the Polygraph CLI already seeds the
     // session id into context at launch. The one thing compaction can drop is
     // that identity, so we steer the summary prompt to retain it. This fires
@@ -62,9 +86,7 @@ export const PolygraphPlugin = async () => {
         if (note) {
           output.context.push(note);
         }
-        // Refresh the mapping on compaction (same refresh semantics as Claude/Codex
-        // SessionStart hooks firing on 'compact').
-        writeAgentCaptureMapping(input.sessionID);
+        await sessionLinker.fromEnvironment(input.sessionID);
       } catch (error) {
         // Never let a hook failure break the OpenCode session; just record it.
         logHookFailure('opencode:session.compacting', error, {

package/skills/polygraph/SKILL.md

@@ -8,9 +8,9 @@ description: Guidance for working with Polygraph sessions, shared/resumable agen
 
 **IMPORTANT:** Polygraph keeps local clones only for *other* repositories in the session. NEVER `cd` into those clones or access their files directly — work in other repositories ALWAYS happens through the Polygraph MCP `spawn_agent` tool, invoked via `@polygraph-delegate-subagent`.
 
-Polygraph connects repositories and the agent work happening across them. Its central artifact is the session, which groups the repositories, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repositories, and also on its own to share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
+Polygraph connects repos and the agent work happening across them. Its central artifact is the session, which groups the repos, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repos or in a single repoto share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
 
-**Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repositories are worked on in separate Polygraph-managed clones via `spawn_agent`.
+**Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repos are worked on in separate Polygraph-managed clones via `spawn_agent`.
 
 ## Available Tools
 
@@ -59,29 +59,28 @@ Use `polygraph whoami` (or the `whoami` MCP tool) before session work to check i
 - If the user **is logged in** and an org is selected → proceed to the workflow.
 - If auth is **missing, expired, or no org is selected** → stop session work. Do not keep trying session creation, repository discovery, delegation, or CI checks.
 - Facilitate user reauth through the browser-based login flow, such as `polygraph auth login` (or the `login` MCP tool). In interactive desktop clients, browser reauth is usually user-driven; surface the need clearly and wait for the user to complete it.
-- After login, an organization must be selected. Use `polygraph account select` (or the MCP equivalent) when needed.
+- After login, an organization must be selected. Use `polygraph account select` (or MCP equivalent) when needed.
 - Re-run `polygraph whoami` (or `whoami`) after reauth and org selection. Continue only after it confirms a valid login and selected organization.
 
 ### Select Organization
 
-After logging in (or if logged in but no org is selected), use `polygraph account select` (or the equivalent MCP tool) to choose the organization that future commands will run against.
+After logging in (or if logged in but no org is selected), use `polygraph account select` (or MCP equivalent) to choose the organization that future commands will run against.
 
 ## Workflow Overview
 
 The delegate/monitor/stop steps apply only when working across repos. A single-repo session skips them and still benefits from shared progress, resume, and CI visibility.
 
-0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly with those refs and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session.
-1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. Delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Parallel delegation across repos is encouraged. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
+0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session.
+1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents. Delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Parallel delegation across repos is encouraged. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
    
 4. **Monitor child agents** - Use `show_agent` to poll one repo's children (`repo` is required; pass `role` to narrow to one agent) and read each entry's `status` and `lastOutputLines` from the `children[]` array.
 5. **Stop child agents** (if needed) - Use `stop_agent` (with `role` when targeting a non-default agent) to cancel an in-progress child agent. The agent's session is preserved for later read-only context restoration; after a resume, wait for explicit user instructions before making changes.
 6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
-7. **Update session description** - Use `update_session` to update the session description; must follow the Session Description Policy. Independent of PR creation or mark-ready.
-8. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
-9. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
-10. **Query PR status** - Use `show_session` to check progress.
-11. **Mark PRs ready** - Use `mark_pr_ready` when work is complete.
-12. **Archive session** - Use `archive_session` to archive the session when the user requests it.
+7. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
+8. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
+9. **Query PR status** - Use `show_session` to check progress.
+10. **Mark PRs ready** - Use `mark_pr_ready` when work is complete.
+11. **Archive session** - Use `archive_session` to archive the session when the user requests it.
 
 ## Step-by-Step Guide
 
@@ -89,7 +88,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
 
 There are three cases. Pick exactly one before calling any tool. The case labels are internal routing shorthand — never mention them in anything you show the user.
 
-**Hard rule: if a session ID is already in scope (e.g., the startup banner says "You're in Polygraph session …", or the user passed one), that session ID is authoritative for this entire conversation. NEVER call `start_session` — doing so creates a brand-new session and orphans the one the parent harness is pointed at. Reuse the existing session via `show_session` and, if needed, `add_repo`.**
+**Hard rule: if a session ID is already in scope (e.g., the startup banner says "You're in Polygraph session …", or the user passed one or you are provided one by a reminder hook), that session ID is authoritative for this entire conversation. NEVER call `start_session` — doing so creates a brand-new session and orphans the one the parent harness is pointed at. Reuse the existing session via `show_session` and, if needed, `add_repo`.**
 
 **Case A — Existing session, already has repos.** Call `show_session` directly with the known session ID. Skip the init subagent entirely, show the session details (format below), and proceed.
 
@@ -102,14 +101,10 @@ In case B, call `add_repo` yourself when exact repo refs were provided; otherwis
 **Session ID handling:**
 
 - For a new session (case C), `start_session` auto-generates a unique session ID. You do NOT need to pass one.
-- For cases A and B, the session ID already exists; reuse it everywhere — never let `start_session` run in this conversation.
+- For cases A and B, the session ID already exists; reuse it everywhere
 - The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
 - For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
 
-**Launch the init subagent** using `@polygraph-init-subagent` (cases B and C — skip in case A):
-
-Invoke the `polygraph-init-subagent` agent when discovery is needed. Always pass `userContext`. If you are in case B (existing session with no repos) and no exact repo refs were provided, also pass the existing `sessionId` and instruct the subagent to use `add_repo` rather than `start_session`. The subagent returns a structured summary.
-
 The subagent will:
 
 1. Use exact repo refs directly when provided for an existing session; otherwise call `list_repos` to discover available repositories
@@ -118,7 +113,7 @@ The subagent will:
 4. Call `show_session` to retrieve session details
 5. Return a summary with session URL and repo info
 
-**When the init subagent has just created a brand-new session,** render the session welcome card instead of the session-details block below. Prefer the `session_intro` MCP tool — call it with the session ID; it returns the card as markdown. If that tool is unavailable, run `polygraph session intro -s <sessionId>` via the CLI instead. The CLI command is intentionally hidden/internal and may not appear in public command listings, but it remains the correct skill fallback for rendering the welcome card. Either way, print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue (ask the user what they want, or start the requested task).
+**When the init subagent has just created a brand-new session,** render the session welcome card instead of the session-details block below. Prefer the `session_intro` MCP tool (or the hidden `polygraph session intro -s <sessionId>` via the CLI) — call it with the session ID; it returns the card as markdown. Print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue.
 
 **For an existing session — after `show_session` returns or the init subagent's summary arrives — show the session details:**
 
@@ -138,7 +133,7 @@ Use this workflow when the user gives a Polygraph session ID and asks to underst
 **Resume is not a work command.** If the user's intent is to resume, reconnect, or reconstruct a prior Polygraph session, fetch and summarize the restored context, then stop. Do not edit files, push branches, add repos, delegate new work, or continue previous changes until the user explicitly asks for changes. Treat "resume" as context restoration followed by waiting for user instructions.
 
 1. Fetch detailed session context:
-   - Prefer `show_session` with `details: true` when the MCP tool exposes that option.
+   - Prefer `show_session` with `details: true` 
    - Otherwise run `polygraph session show --details <session-id>`.
 2. Treat the detailed output as authoritative context. It should include:
    - `<summary>` — the session summary.
@@ -178,29 +173,8 @@ Inspect the PR commits/diff and investigate the requested behavior. Report findi
 
 ### Finding the Session Behind a Commit or Line
 
-Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code.
-
-**Given a commit sha.** When the user names a sha, or asks what session is behind a commit, resolve it with `search_sessions` using the `sha` parameter (CLI: `polygraph session search --sha <sha>`):
-
-- Pass **exactly one** of `query` or `sha` — they are mutually exclusive.
-- `sha` accepts a full or partial sha, 7-40 hex chars.
-- The lookup is exact and one-shot: it returns the session(s) linked to that commit, newest first, scoped to the current org, and only explicit sessions.
-
-```
-search_sessions(sha: "a1b2c3d")
-# CLI equivalent:
-polygraph session search --sha a1b2c3d
-```
-
-**Given a line number.** There is no line-number lookup — a line MUST first be resolved to a commit sha with `git blame`, then that sha is fed into the sha lookup:
-
-1. `git blame -L <line>,<line> -- <file>` to get the commit that last touched the line.
-2. Pass that sha to `search_sessions(sha: ...)` (or `polygraph session search --sha <sha>`).
-
-**Reading the results.**
-
-- Multiple sessions may match a sha. They come back newest first — pick the most relevant one and report the others if they matter.
-- **A "no match" result does NOT prove the commit had no work behind it.** Not every commit is linked to an explicit session: commits pushed directly (rather than via an ingested PR) and gaps in ingestion metadata mean the sha may simply not be recorded, and implicit sessions are never returned. Report "no linked session found for that sha" — never assert that no work exists behind the commit.
+Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code. 
+**Read [`reference/session-by-commit.md`](reference/session-by-commit.md) before running any lookup.** That reference file holds clear, reliable steps for answering questions related to this.
 
 ## Agent roles
 
@@ -222,6 +196,8 @@ Use this pattern when the task is well-defined and the child is not expected to
 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`.
 
+To debug a stuck subagent you can call `show_agent` as a one-off, but routine polling belongs in the background subagents.
+
 Use Simple when the task is well-defined and the child will not need clarification.
 
 ## Multi-turn tasks (interactive)
@@ -276,44 +252,25 @@ 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, role?}` 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, 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
 
-```jsonc
-// To grant the requested action:
-{
-  "sessionId": "...",
-  "repo": "org/repo-name",
-  "role": "reviewer",              // optional
-  "scope": "session",              // or "one-time"
-  "reason": "Trusted local repo"   // optional
-}
-// — call `allow_agent` with this payload.
-
-// To refuse the requested action:
-{
-  "sessionId": "...",
-  "repo": "org/repo-name",
-  "role": "reviewer",              // optional
-  "reason": "Action looks risky"   // optional
-}
-// — call `deny_agent` with this payload.
-```
-
 The three decisions:
 
 - `allow_agent` with `scope: 'one-time'` — permits the single action only; the child must ask again for the next action of the same type.
 - `allow_agent` with `scope: 'session'` — permits the action and remembers that grant for the rest of the child's session; the child will not ask again.
 - `deny_agent` — rejects the request; child continues without performing the action.
 
+You always pass the sessionId, repo, optional role, optional reason to the allow/deny tool.
+
 **Fail-closed default:** When you see a task in `permission-required` state, 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.
 
 > **OpenCode caveat:** *OpenCode children sometimes request permissions without specific command/path (target is empty). Dialog says 'session' grant covers ALL `${action}` calls this session — read carefully before granting session scope.*
 
 ### Polling for permission-required in the fallback path
 
-When polling `cloud_polygraph_child_status` (or `show_agent`), treat `permission-required` like `input-required`:
+When polling `show_agent`, treat `permission-required` like `input-required`:
 
 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}`."
@@ -327,30 +284,16 @@ When polling `cloud_polygraph_child_status` (or `show_agent`), treat `permission
 
 Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must precede PR creation), `create_pr` (linked draft PRs, including fork PRs via `targetRepository`), `mark_pr_ready` (transition drafts to OPEN), and `associate_pr` (link PRs created outside Polygraph).
 
-**Whenever you push a branch, create or associate a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow: parameters and examples for each tool, `push_branch` local-checkout semantics, the PR title format rules, and the session-URL printing steps. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy below.
+**Whenever you push a branch, create or associate a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow.
 
 ### Session Description Policy
 
 `description` is user-facing Polygraph session context. It is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (`mark_pr_ready` does not take a description).
 
-**Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy: the canonical Markdown-heading template (`## Goal` / `## Current progress` / `## What worked` / `## Next steps`), the dual-audience guidance (humans in the web UI now, agents reconstructing history later), and the formatting building blocks the app renders (callouts, tables, mermaid, links, `link_reference`).
+**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.
 
-### Get Current Polygraph Session
-
-Check the details of a session using `show_session` or `polygraph session show --details <session-id>`. Returns the full session state — basic metadata like id, url & description timeline, plus the connected repositories, `pullRequests[]`, per-PR `ciStatus`, and `session.linkedReferences`.
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-
-**CI status rules:**
-
-- `ciStatus[prId].cipeUrl` (null if no CIPE) is a human-facing Nx Cloud web link — display it to the user, but never fetch, curl, or poll it directly; CIPE data is only accessible programmatically via the Nx MCP `ci_information` tool.
-- When no CIPE exists, external CI data (e.g., GitHub Actions) appears in `ciStatus[prId].externalCIRuns[]` as runs with nested `jobs[]`; each job's `jobId` is the input for `get_ci_logs`.
-
-```
-show_session(sessionId: "<session-id>")
-```
+Use `update_session` directly when the user asks to summarize progress, update the session description, or capture the current state.
+Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
 
 ### Linked References
 
@@ -364,55 +307,16 @@ Use `link_reference` to link an external reference to the current Polygraph sess
 
 When an external resource is mentioned during a Polygraph session and appears relevant to the current work, the parent agent should record it with `link_reference({ sessionId, reference })`. This applies to relevant external resources such as pull requests, GitHub issues, other Polygraph sessions, and Linear issues.
 
-Invoke the MCP tool with a single object containing `{ sessionId, reference }`. For example, to record a relevant pull request:
-
-```
-link_reference({
-  sessionId: "<current-session-id>",
-  reference: {
-    type: "github_pr",
-    url: "https://github.com/nrwl/polygraph-skills/pull/123",
-    label: "Implementation PR"
-  }
-})
-```
-
-To record a relevant Polygraph session, use the same invocation shape and include `reference.sessionId`:
-
-```
-link_reference({
-  sessionId: "<current-session-id>",
-  reference: {
-    type: "session",
-    url: "https://polygraph.example/s/<inspected-session-id>",
-    label: "Inspected Polygraph session",
-    sessionId: "<inspected-session-id>"
-  }
-})
-```
-
-The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command.
+The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command; `show_session` returns a session's existing links as `session.linkedReferences`.
 
 ### Add Repositories to a Session
 
 Use `add_repo` to add repositories to an existing Polygraph session after it has already started.
 
-**Direct-add rule:** When the user provides exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, pass those refs directly to `add_repo` and do not call `list_repos` first. Candidate discovery remains account-repo-only and is only for cases where the user does not know the exact repo or asks to choose/filter candidates.
+**Direct-add rule:** When the user provides exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, pass those refs directly to `add_repo` and do not call `list_repos` first. Candidate discovery is only for cases where the user does not know the exact repo.
 
 **Not limited to your organization:** repos outside the org — including public open-source repos — can be added by GitHub `owner/repo` slug or URL. Only `list_repos` discovery is org-scoped, so a repo missing from `list_repos` can still be added directly.
 
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `repoIds` (required): Repository IDs or exact repository refs to add. Accepts IDs, short names, full names, GitHub `owner/repo` slugs, and URL-like slugs.
-
-```
-add_repo(
-  sessionId: "<session-id>",
-  repoIds: ["org/repo-name", "facebook/react"]
-)
-```
-
 ### Archive Session
 
 **IMPORTANT: Only call this tool when the user explicitly asks to archive or close the session.** Do not archive sessions automatically as part of the workflow.
@@ -433,14 +337,6 @@ When you need to fetch and read a failed job's log, read [`reference/ci-job-logs
 
 Session repos are shallow (`--depth 1`) clones. When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` and retry. Read [`reference/shallow-clone-history.md`](reference/shallow-clone-history.md) for the CLI form, the `depth`/`refs` options, and the redundant-call behavior.
 
-### Update Session Description
-
-Use this when the user asks to summarize progress, update the session description, or capture the current state.
-
-Read [`reference/session-description.md`](reference/session-description.md) for the full update procedure (what to read before writing, how to append vs. replace) and the canonical Markdown-heading format. Then call `update_session` with the resulting summary as `description`.
-
-Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
-
 ### Print Polygraph Session Details
 
 When asked to print polygraph session details, use `show_session` or `polygraph session show --details <session-id>` and display in the following format.
@@ -461,7 +357,7 @@ If the session has a description timeline, also display:
 - PR_URL, PR_TITLE, PR_STATUS: from `pullRequests[]`
 - CI_STATUS: from `ciStatus[prId].status`
 - SELF_HEALING_STATUS: from `ciStatus[prId].selfHealingStatus` (omit or show `-` if null)
-- CIPE_URL: from `ciStatus[prId].cipeUrl`
+- CIPE_URL: from `ciStatus[prId].cipeUrl` (null if no CIPE — omit the CI Link cell) — a human-facing Nx Cloud link: render it for the user, never fetch, curl, or poll it. CIPE data is only reachable via the Nx MCP `ci_information` tool.
 - POLYGRAPH_SESSION_URL: from `polygraphSessionUrl`
 - SESSION_DESCRIPTION: from the latest/current item in `description`
 
@@ -479,5 +375,3 @@ 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 (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

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

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

@@ -0,0 +1,25 @@
+# Finding the Session Behind a Commit or Line
+
+Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code.
+
+**Given a commit sha.** When the user names a sha, or asks what session is behind a commit, resolve it with `search_sessions` using the `sha` parameter (CLI: `polygraph session search --sha <sha>`):
+
+- Pass **exactly one** of `query` or `sha` — they are mutually exclusive.
+- `sha` accepts a full or partial sha, 7-40 hex chars.
+- The lookup is exact and one-shot: it returns the session(s) linked to that commit, newest first, scoped to the current org, and only explicit sessions.
+
+```
+search_sessions(sha: "a1b2c3d")
+# CLI equivalent:
+polygraph session search --sha a1b2c3d
+```
+
+**Given a line number.** There is no line-number lookup — a line MUST first be resolved to a commit sha with `git blame`, then that sha is fed into the sha lookup:
+
+1. `git blame -L <line>,<line> -- <file>` to get the commit that last touched the line.
+2. Pass that sha to `search_sessions(sha: ...)` (or `polygraph session search --sha <sha>`).
+
+**Reading the results.**
+
+- Multiple sessions may match a sha. They come back newest first — pick the most relevant one and report the others if they matter.
+- **A "no match" result does NOT prove the commit had no work behind it.** Not every commit is linked to an explicit session: commits pushed directly (rather than via an ingested PR) and gaps in ingestion metadata mean the sha may simply not be recorded, and implicit sessions are never returned. Report "no linked session found for that sha" — never assert that no work exists behind the commit.

package/agent-capture-mapping.mjs

@@ -1,202 +0,0 @@
-// Agent-capture mapping writer for the OpenCode plugin.
-// Exported from this sibling module (NOT from server.js) so it can be tested
-// independently. See server.js for the constraint on why server.js itself must
-// stay export-free beyond its plugin entry.
-//
-// Records the (agentSessionId ↔ polygraphSessionId) mapping file so the
-// Polygraph CLI can bind parent-log capture deterministically. Written on
-// every session start and compaction; the CLI reader looks for mapping-*.json
-// files in the per-session sidecars directory.
-//
-// 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
-//     (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 {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
-import { homedir } from 'node:os';
-import path from 'node:path';
-
-function sanitizeMappingFilename(str) {
-  return str.replace(/[^A-Za-z0-9._-]/g, '_');
-}
-
-const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
-
-/**
- * Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
- *
- * Hooks otherwise swallow their errors silently (a broken hook must never break
- * the agent session) and must never write to stdout — so this on-disk log is the
- * only record that something went wrong. The logger is itself failure-proof:
- * any error here is swallowed so a logging bug can never break a hook.
- *
- * @param {string} hook        Identifier for the failing hook.
- * @param {unknown} error      The thrown value.
- * @param {object} [meta]      Extra context to record (sessionID, etc.).
- * @param {string} [home]      Override HOME for testing.
- */
-export function logHookFailure(
-  hook,
-  error,
-  meta = {},
-  home = process.env.HOME?.trim() || homedir()
-) {
-  try {
-    const logsDir = path.join(home, '.polygraph', 'logs');
-    mkdirSync(logsDir, { recursive: true });
-    const logFile = path.join(logsDir, 'hooks.log');
-
-    // Best-effort rotation so the log can't grow unbounded.
-    try {
-      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
-        renameSync(logFile, `${logFile}.1`);
-      }
-    } catch {
-      // no prior log, or rotation failed — ignore
-    }
-
-    const entry = {
-      time: new Date().toISOString(),
-      hook,
-      pid: process.pid,
-      ...meta,
-      error: error instanceof Error ? error.message : String(error),
-      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
-    };
-    appendFileSync(logFile, JSON.stringify(entry) + '\n');
-  } catch {
-    // Logging must never throw — a failing logger must not break the hook.
-  }
-}
-
-// 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.
- *
- * 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.
- */
-export function writeAgentCaptureMapping(
-  agentSessionId,
-  home = process.env.HOME?.trim() || homedir()
-) {
-  try {
-    const polygraphSessionId = process.env.POLYGRAPH_SESSION_ID;
-    if (!polygraphSessionId) return;
-    if (process.env.POLYGRAPH_CHILD_AGENT) return;
-    if (!agentSessionId) return;
-
-    const filenamePart = sanitizeMappingFilename(`opencode-${agentSessionId}`);
-    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();
-
-    // 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(candidate, 'utf8'));
-        if (
-          existing.version === 1 &&
-          existing.polygraphSessionId === polygraphSessionId &&
-          existing.agentSessionId === agentSessionId &&
-          Number.isFinite(existing.firstSeenAt)
-        ) {
-          firstSeenAt = existing.firstSeenAt;
-          break;
-        }
-      } catch {
-        // ignore — treat as missing
-      }
-    }
-
-    const mapping = {
-      version: 1,
-      polygraphSessionId,
-      agentType: 'opencode',
-      agentSessionId,
-      cwd: process.cwd(),
-      // OpenCode transcripts are resolved by the CLI from its own storage by
-      // session id, so we omit transcriptPath here.
-      pid: process.pid,
-      source: 'hook',
-      firstSeenAt,
-      lastSeenAt: now,
-    };
-
-    writeFileSync(tmpPath, JSON.stringify(mapping, null, 2) + '\n');
-    renameSync(tmpPath, finalPath);
-  } catch (error) {
-    // Silent toward the agent — a broken plugin hook must never break the
-    // session — but record it so failures are not invisible.
-    logHookFailure('opencode:writeAgentCaptureMapping', error, { agentSessionId }, home);
-  }
-}