@polygraph/cursor-plugin 0.4.51 → 0.4.52

package/hooks/agent-session-link.mjs

@@ -1,6 +1,6 @@
 import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
@@ -56,6 +56,17 @@ export function buildLinkAgentSessionArgs({
   return args;
 }
 
+/**
+ * Node runtime for the JS-entry fallback. This shim also runs inside
+ * non-Node hosts (the opencode plugin executes it in-process, and opencode
+ * is a compiled Bun binary), where process.execPath is not a Node
+ * executable — fall back to PATH resolution there.
+ */
+function nodeRuntime() {
+  const base = basename(process.execPath).toLowerCase();
+  return base === 'node' || base === 'node.exe' ? process.execPath : 'node';
+}
+
 export function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
   if (isManagedChildEnvironment(env)) return false;
 
@@ -67,11 +78,22 @@ export function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
     delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
   }
 
-  const result = spawn(command, args, {
+  const spawnOptions = {
     encoding: 'utf8',
     env: commandEnv,
     stdio: ['ignore', 'ignore', 'pipe'],
-  });
+  };
+
+  let result = spawn(command, args, spawnOptions);
+
+  // POLYGRAPH_CLI may point at a plain JS entry that cannot be spawned
+  // directly: a dev build without the executable bit, or a platform that
+  // cannot exec scripts. A spawn that failed to LAUNCH ran nothing, so the
+  // retry under a Node runtime is side-effect free — and anything that
+  // spawns directly today keeps its exact behavior.
+  if (result?.error && /\.[cm]?js$/i.test(command)) {
+    result = spawn(nodeRuntime(), [command, ...args], spawnOptions);
+  }
 
   if (result?.error) throw result.error;
   if (result?.status !== 0) {

package/package.json

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

package/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "polygraph",
-  "version": "0.4.51",
+  "version": "0.4.52",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination"
 }

package/skills/polygraph/SKILL.md

@@ -43,6 +43,8 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `select_account` | `polygraph account select` | Select the organization that future commands run against |
 | `whoami` | `polygraph whoami` | Show current auth status and org |
 
+**Delegation rules:** `list_repos` and `start_session` MUST be called via the `polygraph-init-subagent` as described in the "Initialize or Join Polygraph Session" section. Direct `add_repo` is allowed only when the user provides exact repo refs for an existing session. `spawn_agent` is a fast, non-blocking call and IS allowed directly in the main conversation — it returns a delegation id. Waited `show_agent` POLLING must run in a background `Task` (`subagent_type: "polygraph-delegate-subagent"`, `run_in_background: true`), collected with `Await`, never inline. One-off unwaited `show_agent` reads in the main conversation are fine and expected — that is how you read a child's result. See [`reference/delegation.md`](reference/delegation.md). The init subagent is launched the same way, by its bare name: a `Task` with `subagent_type: "polygraph-init-subagent"` — without `run_in_background`, since you need its summary before continuing.
+
 ## CLI Statefulness
 
 The Polygraph CLI (`polygraph`) is **stateful**. When you select an organization — via `polygraph account select` or the equivalent MCP tool — that selection is saved globally and all subsequent CLI commands and MCP tool calls operate against it. You do not need to pass the org on every command.
@@ -69,8 +71,8 @@ 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.
 
-2. **Initialize or join Polygraph session** - If you already have a session ID, call `show_session` to fetch details. If the user asks to add exact repo refs, call `add_repo` directly and skip candidate discovery. Otherwise, discover candidate repos, select relevant repositories, and create a new session via `list_repos` and `start_session`.
-3. **Delegate work to each repo** - Use `spawn_agent` to start child agents in other repositories (returns immediately with a delegation id). With the default role, delegate only to *other* repos — never to the repo you are in; work on it directly. Delegating into the repo you are in is allowed only with an explicit non-default `role`. Parallel delegation across repos is encouraged. Read [`reference/delegation.md`](reference/delegation.md) before delegating.
+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** - Call `spawn_agent` for each repo to get a delegation id, then launch one background `polygraph-delegate-subagent` per id to wait on it. With the default role, 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). Delegating into the repo you are in is allowed only with an explicit non-default `role`. Parallel delegation across repos is encouraged. Read [`reference/delegation.md`](reference/delegation.md) before delegating.
    
 4. **Monitor child agents** - Let the background poller subagent do the waiting. When it exits, read that child's answer with a single unwaited `show_agent(sessionId, id)` — `result.text` is the child's final message.
 5. **Stop child agents** (if needed) - Use `stop_agent` with the delegation id 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.
@@ -97,7 +99,7 @@ There are three cases. Pick exactly one before calling any tool. The case labels
 
 **Case C — No session at all.** Launch the `polygraph-init-subagent` with only `userContext` (no `sessionId`). The subagent will discover candidates and call `start_session` to create a new session.
 
-In case B, direct exact repo refs go straight to `add_repo`; use `list_repos` only when discovery/filtering is needed. In case C, discover candidate repos using `list_repos`, select relevant repositories, and call `start_session`. In case A, just call `show_session`.
+In case B, call `add_repo` yourself when exact repo refs were provided; otherwise the subagent handles discovery and attachment. In case C the subagent handles session creation. In case A you call `show_session` yourself.
 
 **Session ID handling:**
 
@@ -281,7 +283,7 @@ If the session has a description timeline, also display:
 
 ## Best Practices
 
-1. **Delegate asynchronously** — Use `spawn_agent` which returns immediately with a delegation id, then poll with `show_agent`.
+1. **Wait in background subagents** — `spawn_agent` is fine to call directly and returns a delegation id, but every waited `show_agent` poll belongs in a background `Task` with `subagent_type: "polygraph-delegate-subagent"` and `run_in_background: true`. Collect that Task with `Await`, and if `Await` returns while the poller is still running, call `Await` again with the same background-task id. Inline polling floods the context with status noise.
    
 1. **Read each result once** — when a poller exits, read that child with a single unwaited `show_agent(sessionId, id)`; `result.text` is the child's final message. Only reach for an explicit `tail` if that is not enough.
 1. **Poll child status before proceeding** — Always verify child agents have reached a terminal `child.status` (`'completed'`, `'failed'`, or `'cancelled'`) before pushing branches or creating PRs
@@ -291,4 +293,6 @@ If the session has a description timeline, also display:
 1. **Test integration** before marking PRs ready
 1. **Coordinate merge order** if there are deployment dependencies
    
+1. **NEVER run a waited `show_agent` loop in the main conversation**. Waiting MUST run inside `polygraph-delegate-subagent`, launched as a background `Task` and collected with `Await`.
+   
 1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed (pass the delegation id). 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.

package/skills/polygraph/reference/delegation.md

@@ -41,6 +41,11 @@ For each id, launch one background poller subagent whose entire job is to block
 - **Claude Code** — a background `Task` with `subagent_type: "polygraph:polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Fall back to the bare agent name only if the namespaced form is not found.
 - **OpenCode** — invoke `@polygraph-delegate-subagent`.
 - **Codex** — launch `agent_type: "polygraph-delegate-subagent"` via Codex's own `spawn_agent`, and collect it with `wait_agent`.
+- **Cursor** — a background `Task` with `subagent_type: "polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Collect it with `Await`.
+
+A collect step that returns while the poller subagent is still running has not failed. It has only reached the end of its collection window. Collect the same background-task id again, as many times as it takes for the poller subagent to stop. A poller that runs for several minutes is ordinary, and it is never a reason to take the wait back into the main conversation.
+
+The background-task id is the handle your own harness returned when you launched the poller. It is not the Polygraph delegation id (`frontend-1`), which addresses the child agent. Once the poller subagent has finished, do not collect it again: read the child instead, as described below. A child that stops for attention also ends the poller, so treat that as a finished poller and not as a collection window running out.
 
 The poller has exactly one tool and cannot read logs. It exits with a few lines naming the repo, the id, and the final status. That message is a doorbell, not a report — it tells you the child is worth reading, and nothing about what the child did.