@polygraph/claude-plugin 0.4.51 → 0.4.52

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.51",
+  "version": "0.4.52",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

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/claude-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/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.