@polygraph/opencode-plugin 0.5.0 → 0.5.2

package/agent-session-link.mjs

@@ -1,20 +1,123 @@
 // source/hooks/agent-session-link.mjs
-import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import { appendFileSync, mkdirSync as mkdirSync2, renameSync as renameSync2, statSync as statSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { basename as basename2, join as join2 } from "node:path";
+import { spawnSync as spawnSync2 } from "node:child_process";
+
+// source/hooks/capture-cli.mjs
+import { spawn as spawnChild, spawnSync } from "node:child_process";
+import { closeSync, mkdirSync, openSync, renameSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { basename, join } from "node:path";
-import { spawnSync } from "node:child_process";
+var HOOK_WORKER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+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 captureCommandEnvironment(env = process.env) {
+  const commandEnv = { ...env };
+  delete commandEnv.POLYGRAPH_SESSION_ID;
+  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+  return commandEnv;
+}
+function resolveLaunchDirectory(preferred, env = process.env) {
+  const candidates = [preferred, nonEmptyString(env?.HOME) ?? homedir(), tmpdir()];
+  for (const candidate of candidates) {
+    const directory = nonEmptyString(candidate);
+    if (!directory) continue;
+    try {
+      if (statSync(directory).isDirectory()) return directory;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function nodeRuntime(execPath) {
+  const base = basename(execPath).toLowerCase();
+  return base === "node" || base === "node.exe" ? execPath : "node";
+}
+function reportWorkerLaunchFailure(onFailure, error) {
+  try {
+    const pending = onFailure(error);
+    if (pending && typeof pending.catch === "function") {
+      pending.catch(() => {
+      });
+    }
+  } catch {
+  }
+}
+function openHookWorkerLog(env, logName) {
+  const home = nonEmptyString(env?.HOME) ?? homedir();
+  const logsDir = join(home, ".polygraph", "logs");
+  mkdirSync(logsDir, { recursive: true });
+  const logFile = join(logsDir, logName);
+  try {
+    if (statSync(logFile).size > HOOK_WORKER_LOG_MAX_BYTES) {
+      renameSync(logFile, `${logFile}.1`);
+    }
+  } catch {
+  }
+  return openSync(logFile, "a", 384);
+}
+function launchDetachedHookWorker({
+  workerPath,
+  claim,
+  logName,
+  spawn = spawnChild,
+  env = process.env,
+  execPath = process.execPath,
+  onFailure = () => {
+  },
+  openLog = openHookWorkerLog,
+  closeLog = closeSync
+}) {
+  let logFd;
+  try {
+    logFd = openLog(env, logName);
+  } catch (error) {
+    reportWorkerLaunchFailure(onFailure, error);
+  }
+  const output = logFd === void 0 ? "ignore" : logFd;
+  const launchDirectory = resolveLaunchDirectory(claim.cwd, env);
+  let child;
+  try {
+    child = spawn(nodeRuntime(execPath), [workerPath, JSON.stringify(claim)], {
+      ...launchDirectory ? { cwd: launchDirectory } : {},
+      detached: true,
+      env: captureCommandEnvironment(env),
+      shell: false,
+      stdio: ["ignore", output, output],
+      windowsHide: true
+    });
+  } finally {
+    if (logFd !== void 0) {
+      try {
+        closeLog(logFd);
+      } catch (error) {
+        reportWorkerLaunchFailure(onFailure, error);
+      }
+    }
+  }
+  child.once("error", (error) => reportWorkerLaunchFailure(onFailure, error));
+  child.unref();
+  return true;
+}
+
+// source/hooks/agent-session-link.mjs
 var HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
 var AGENT_TYPES = /* @__PURE__ */ new Set(["claude", "codex", "opencode", "cursor"]);
 var COMMAND_HOOK_TOOL = /^mcp__(?:plugin_polygraph_)?polygraph[-_]mcp__/;
 var OPENCODE_TOOL = /^polygraph(?:(?:-|_)mcp)?_/;
-function nonEmptyString(value) {
+function nonEmptyString2(value) {
   return typeof value === "string" && value.trim() ? value : void 0;
 }
-function isManagedChildEnvironment(env) {
+function isManagedChildEnvironment2(env) {
   return Boolean(env && Object.hasOwn(env, "POLYGRAPH_CHILD_AGENT"));
 }
 function isPolygraphMcpToolName(toolName) {
-  const name = nonEmptyString(toolName);
+  const name = nonEmptyString2(toolName);
   return Boolean(name && (COMMAND_HOOK_TOOL.test(name) || OPENCODE_TOOL.test(name)));
 }
 function buildLinkAgentSessionArgs({
@@ -23,26 +126,22 @@ function buildLinkAgentSessionArgs({
   agentSessionId,
   cwd,
   transcriptPath,
-  pid,
   source,
   hookOperation
 }) {
-  const session = nonEmptyString(polygraphSessionId);
-  const harnessSession = nonEmptyString(agentSessionId);
-  const claimSource = nonEmptyString(source);
+  const session = nonEmptyString2(polygraphSessionId);
+  const harnessSession = nonEmptyString2(agentSessionId);
+  const claimSource = nonEmptyString2(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);
+  const workingDirectory = nonEmptyString2(cwd);
   if (workingDirectory) args.push("--cwd", workingDirectory);
-  const transcript = nonEmptyString(transcriptPath);
+  const transcript = nonEmptyString2(transcriptPath);
   if (transcript) args.push("--transcript-path", transcript);
-  if (Number.isSafeInteger(pid) && pid > 0) {
-    args.push("--pid", String(pid));
-  }
   let input;
   if (hookOperation && typeof hookOperation === "object") {
     args.push("--hook-operation-stdin");
@@ -51,46 +150,51 @@ function buildLinkAgentSessionArgs({
   args.push("--source", claimSource);
   return { args, input };
 }
-function nodeRuntime() {
-  const base = basename(process.execPath).toLowerCase();
+function nodeRuntime2() {
+  const base = basename2(process.execPath).toLowerCase();
   return base === "node" || base === "node.exe" ? process.execPath : "node";
 }
-function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
-  if (isManagedChildEnvironment(env)) return false;
+function linkAgentSession(claim, spawn = spawnSync2, env = process.env) {
+  if (isManagedChildEnvironment2(env)) return false;
   const { args, input } = buildLinkAgentSessionArgs(claim);
-  const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? "polygraph";
-  const commandEnv = nonEmptyString(claim.polygraphSessionId) ? env : { ...env };
+  const command = nonEmptyString2(env?.POLYGRAPH_CLI) ?? "polygraph";
+  const commandEnv = nonEmptyString2(claim.polygraphSessionId) ? env : { ...env };
   if (commandEnv !== env) {
     delete commandEnv.POLYGRAPH_SESSION_ID;
     delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
   }
+  const launchDirectory = resolveLaunchDirectory(claim.cwd, env);
   const spawnOptions = {
     encoding: "utf8",
     env: commandEnv,
     stdio: [input === void 0 ? "ignore" : "pipe", "ignore", "pipe"],
-    ...input === void 0 ? {} : { input }
+    ...input === void 0 ? {} : { input },
+    ...launchDirectory ? { cwd: launchDirectory } : {}
   };
-  let result = spawn(command, args, spawnOptions);
-  if (result?.error && /\.[cm]?js$/i.test(command)) {
-    result = spawn(nodeRuntime(), [command, ...args], spawnOptions);
+  const jsEntry = /\.[cm]?js$/i.test(command);
+  let result;
+  try {
+    result = jsEntry ? spawn(nodeRuntime2(), [command, ...args], spawnOptions) : spawn(command, args, spawnOptions);
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
   }
   if (result?.error) throw result.error;
   if (result?.status !== 0) {
-    const detail = nonEmptyString(result?.stderr);
+    const detail = nonEmptyString2(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()) {
+function logHookFailure(hook, error, meta = {}, home = process.env.HOME?.trim() || homedir2()) {
   try {
-    const logsDir = join(home, ".polygraph", "logs");
-    mkdirSync(logsDir, { recursive: true });
-    const logFile = join(logsDir, "hooks.log");
+    const logsDir = join2(home, ".polygraph", "logs");
+    mkdirSync2(logsDir, { recursive: true });
+    const logFile = join2(logsDir, "hooks.log");
     try {
-      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
-        renameSync(logFile, `${logFile}.1`);
+      if (statSync2(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync2(logFile, `${logFile}.1`);
       }
     } catch {
     }
@@ -107,6 +211,25 @@ function logHookFailure(hook, error, meta = {}, home = process.env.HOME?.trim()
   }
 }
 
+// source/hooks/agent-session-capture.mjs
+import { fileURLToPath } from "node:url";
+var ENSURE_WAKE_WORKER_PATH = fileURLToPath(
+  new URL("./ensure-agent-session-capture-worker.mjs", import.meta.url)
+);
+function launchAgentSessionCaptureWake(claim, spawn, env = process.env, { onFailure = () => {
+}, ...workerOptions } = {}) {
+  if (isManagedChildEnvironment(env)) return false;
+  return launchDetachedHookWorker({
+    workerPath: ENSURE_WAKE_WORKER_PATH,
+    logName: "capture-wake.log",
+    ...workerOptions,
+    claim,
+    ...spawn ? { spawn } : {},
+    env,
+    onFailure
+  });
+}
+
 // source/opencode/agent-session-link.mjs
 function sessionRecord(result) {
   if (result?.error) {
@@ -149,22 +272,48 @@ async function linkOpenCodeSessionCreatedEvent(input, sessionLinker) {
   if (event?.type !== "session.created") return false;
   return sessionLinker.fromSessionCreated(event.properties?.info);
 }
+function openCodeChatMessageSessionId(input, output) {
+  return sessionIdValue(input?.sessionID) ?? sessionIdValue(output?.message?.sessionID);
+}
+function sessionIdValue(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
 function deferOpenCodeToolActivity(input, sessionLinker, onError, schedule = setTimeout) {
   schedule(() => {
-    Promise.resolve(sessionLinker.fromToolActivity(input)).catch(onError);
+    return Promise.resolve().then(() => sessionLinker.fromToolActivity(input)).catch((error) => {
+      try {
+        return onError(error);
+      } catch {
+      }
+    }).catch(() => {
+    });
+  }, 0);
+}
+function deferOpenCodeCaptureWake(sessionId, sessionLinker, onError, schedule = setTimeout, now = Date.now) {
+  const observedAt = now();
+  schedule(() => {
+    return Promise.resolve().then(() => sessionLinker.wakeCapture(sessionId, { observedAt })).catch((error) => {
+      try {
+        return onError(error);
+      } catch {
+      }
+    }).catch(() => {
+    });
   }, 0);
 }
 function createOpenCodeSessionLinker({
   client,
   directory,
   env = process.env,
-  pid = process.pid,
   link,
-  spawn
+  ensure,
+  spawn,
+  now = Date.now
 } = {}) {
   const roots = /* @__PURE__ */ new Map();
   const linkedLifecycleSessions = /* @__PURE__ */ new Set();
   const submitLink = link ?? ((claim) => linkAgentSession(claim, spawn, env));
+  const submitEnsure = ensure ?? ((claim) => launchAgentSessionCaptureWake(claim, spawn, env));
   async function rootSessionId(sessionId) {
     if (!sessionId) return void 0;
     if (roots.has(sessionId)) return roots.get(sessionId);
@@ -185,7 +334,6 @@ function createOpenCodeSessionLinker({
       agentType: "opencode",
       agentSessionId,
       cwd: cwd || directory || process.cwd(),
-      pid,
       source: "hook"
     });
     if (linked && lifecycleKey) linkedLifecycleSessions.add(lifecycleKey);
@@ -208,13 +356,31 @@ function createOpenCodeSessionLinker({
     async fromToolActivity(input) {
       if (!isPolygraphMcpToolName(input?.tool)) return false;
       return submit(input?.sessionID);
+    },
+    // Identity-only capture liveness. Resolves the root session (subagent
+    // activity wakes the parent's capture) and pokes the sidecar; it records
+    // no mapping, no provenance, and no step boundary.
+    async wakeCapture(openCodeSessionId, { cwd, observedAt = now() } = {}) {
+      if (!openCodeSessionId || env && Object.hasOwn(env, "POLYGRAPH_CHILD_AGENT")) {
+        return false;
+      }
+      const agentSessionId = await rootSessionId(openCodeSessionId);
+      if (!agentSessionId) return false;
+      return submitEnsure({
+        agentType: "opencode",
+        agentSessionId,
+        cwd: cwd || directory || process.cwd(),
+        observedAt
+      });
     }
   };
 }
 export {
   createOpenCodeSessionLinker,
+  deferOpenCodeCaptureWake,
   deferOpenCodeToolActivity,
   linkOpenCodeSessionCreatedEvent,
   logHookFailure,
+  openCodeChatMessageSessionId,
   resolveOpenCodeRootSessionId
 };

package/ensure-agent-session-capture-worker.mjs

@@ -0,0 +1,304 @@
+// source/hooks/ensure-agent-session-capture-worker.mjs
+import { realpathSync } from "node:fs";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// source/hooks/agent-session-capture.mjs
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// source/hooks/capture-cli.mjs
+import { spawn as spawnChild, spawnSync } from "node:child_process";
+import { closeSync, mkdirSync, openSync, renameSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, join } from "node:path";
+var JS_CLI_ENTRY = /\.[cm]?js$/i;
+var HOOK_WORKER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+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 captureCommandEnvironment(env = process.env) {
+  const commandEnv = { ...env };
+  delete commandEnv.POLYGRAPH_SESSION_ID;
+  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+  return commandEnv;
+}
+function resolveLaunchDirectory(preferred, env = process.env) {
+  const candidates = [preferred, nonEmptyString(env?.HOME) ?? homedir(), tmpdir()];
+  for (const candidate of candidates) {
+    const directory = nonEmptyString(candidate);
+    if (!directory) continue;
+    try {
+      if (statSync(directory).isDirectory()) return directory;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function observedAtValue(value) {
+  return Number.isSafeInteger(value) && value > 0 ? value : void 0;
+}
+function nodeRuntime(execPath) {
+  const base = basename(execPath).toLowerCase();
+  return base === "node" || base === "node.exe" ? execPath : "node";
+}
+function portableReexec(env, platform) {
+  const raw = nonEmptyString(env.POLYGRAPH_CLI_REEXEC);
+  if (!raw || platform !== "win32") return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((part) => nonEmptyString(part))) {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function deadlineExceededResult() {
+  const error = new Error("Polygraph capture command timed out before launch");
+  error.code = "ETIMEDOUT";
+  return { error, status: null, signal: "SIGTERM" };
+}
+function withRemainingTimeout(options, deadline, now) {
+  if (deadline === void 0) return options;
+  const remaining = Math.floor(deadline - now());
+  if (remaining < 1) return void 0;
+  const configured = Number.isFinite(options.timeout) ? options.timeout : remaining;
+  return { ...options, timeout: Math.min(configured, remaining) };
+}
+function runBeforeDeadline(spawn, command, args, options, deadline, now) {
+  const boundedOptions = withRemainingTimeout(options, deadline, now);
+  if (!boundedOptions) return deadlineExceededResult();
+  try {
+    return spawn(command, args, boundedOptions);
+  } catch (error) {
+    return { error, status: null, signal: null };
+  }
+}
+function runCaptureCliSync(args, {
+  env = process.env,
+  spawn = spawnSync,
+  options = {},
+  cwd,
+  deadline,
+  now = Date.now,
+  platform = process.platform,
+  execPath = process.execPath
+} = {}) {
+  const command = nonEmptyString(env.POLYGRAPH_CLI) ?? "polygraph";
+  const reexec = portableReexec(env, platform);
+  const launchDirectory = resolveLaunchDirectory(cwd, env);
+  const spawnOptions = {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+    ...launchDirectory ? { cwd: launchDirectory } : {},
+    env: captureCommandEnvironment(env),
+    shell: false,
+    windowsHide: true
+  };
+  let executable;
+  let prefixArgs;
+  if (reexec) {
+    [executable, ...prefixArgs] = reexec;
+  } else if (JS_CLI_ENTRY.test(command)) {
+    executable = nodeRuntime(execPath);
+    prefixArgs = [command];
+  } else {
+    executable = command;
+    prefixArgs = [];
+  }
+  return runBeforeDeadline(
+    spawn,
+    executable,
+    [...prefixArgs, ...args],
+    spawnOptions,
+    deadline,
+    now
+  );
+}
+function cliFailure(commandName, result) {
+  if (result?.error) return result.error;
+  const stderr = nonEmptyString(result?.stderr);
+  const stdout = nonEmptyString(result?.stdout);
+  const detail = stderr ?? stdout;
+  const outcome = result?.signal ? `terminated by signal ${result.signal}` : `exited with status ${String(result?.status)}`;
+  return new Error(
+    `polygraph ${commandName} ${outcome}` + (detail ? `: ${detail}` : "")
+  );
+}
+
+// source/hooks/agent-session-capture.mjs
+var ENSURE_CAPTURE_TIMEOUT_MS = 2e4;
+var ENSURE_CAPTURE_UNSUPPORTED_MARKER = "POLYGRAPH_ENSURE_AGENT_SESSION_CAPTURE_UNSUPPORTED";
+var WAKE_AGENT_TYPES = /* @__PURE__ */ new Set(["claude", "codex", "opencode", "cursor"]);
+var ENSURE_WAKE_WORKER_PATH = fileURLToPath(
+  new URL("./ensure-agent-session-capture-worker.mjs", import.meta.url)
+);
+function boundedEnsureTimeout(timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+    return ENSURE_CAPTURE_TIMEOUT_MS;
+  }
+  return Math.min(Math.floor(timeoutMs), ENSURE_CAPTURE_TIMEOUT_MS);
+}
+function wakeIdentityArgs({ agentType, agentSessionId }) {
+  const harnessSession = nonEmptyString(agentSessionId);
+  if (!WAKE_AGENT_TYPES.has(agentType)) {
+    throw new Error(`Unsupported agent type: ${agentType}`);
+  }
+  if (!harnessSession) throw new Error("agentSessionId is required");
+  return ["--agent-type", agentType, "--agent-session-id", harnessSession];
+}
+function buildEnsureAgentSessionCaptureArgs({
+  agentType,
+  agentSessionId,
+  observedAt
+}) {
+  const identity = wakeIdentityArgs({ agentType, agentSessionId });
+  const observed = observedAtValue(observedAt);
+  if (observed === void 0) {
+    throw new Error("observedAt is required: a wake must carry the hook-captured time");
+  }
+  return [
+    "_ensure-agent-session-capture",
+    ...identity,
+    "--observed-at",
+    String(observed)
+  ];
+}
+function buildLegacyCaptureWakeArgs(claim) {
+  const args = ["_link-agent-session", ...wakeIdentityArgs(claim)];
+  const workingDirectory = nonEmptyString(claim.cwd);
+  if (workingDirectory) args.push("--cwd", workingDirectory);
+  const transcript = nonEmptyString(claim.transcriptPath);
+  if (transcript) args.push("--transcript-path", transcript);
+  args.push("--source", "hook");
+  return args;
+}
+function commandUnavailable(result) {
+  if (result?.error) return false;
+  const output = `${result?.stdout ?? ""}
+${result?.stderr ?? ""}`;
+  if (output.includes(ENSURE_CAPTURE_UNSUPPORTED_MARKER)) return true;
+  const stdout = typeof result?.stdout === "string" ? result.stdout.replace(/\r\n/g, "\n") : "";
+  return result?.status === 1 && !nonEmptyString(result?.stderr) && stdout.startsWith("Usage: polygraph\n") && stdout.includes("\nValidation failed for one or more options\n") && stdout.includes("\n  - Unknown argument: _ensure-agent-session-capture\n");
+}
+function ensureAgentSessionCapture(claim, spawn = spawnSync2, env = process.env, {
+  timeoutMs = ENSURE_CAPTURE_TIMEOUT_MS,
+  now = Date.now,
+  platform = process.platform,
+  execPath = process.execPath
+} = {}) {
+  if (isManagedChildEnvironment(env)) return false;
+  const deadline = now() + boundedEnsureTimeout(timeoutMs);
+  const options = {
+    killSignal: "SIGKILL",
+    maxBuffer: 256 * 1024
+  };
+  const run = (args) => runCaptureCliSync(args, {
+    env,
+    spawn,
+    options,
+    cwd: claim.cwd,
+    deadline,
+    now,
+    platform,
+    execPath
+  });
+  const result = run(buildEnsureAgentSessionCaptureArgs(claim));
+  if (!result?.error && result?.status === 0) return true;
+  if (commandUnavailable(result)) {
+    const fallback = run(buildLegacyCaptureWakeArgs(claim));
+    if (!fallback?.error && fallback?.status === 0) return true;
+    throw cliFailure("_link-agent-session compatibility fallback", fallback);
+  }
+  throw cliFailure("_ensure-agent-session-capture", result);
+}
+
+// source/hooks/agent-session-link.mjs
+import { appendFileSync, mkdirSync as mkdirSync2, renameSync as renameSync2, statSync as statSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { basename as basename2, join as join2 } from "node:path";
+var HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+function logHookFailure(hook, error, meta = {}, home = process.env.HOME?.trim() || homedir2()) {
+  try {
+    const logsDir = join2(home, ".polygraph", "logs");
+    mkdirSync2(logsDir, { recursive: true });
+    const logFile = join2(logsDir, "hooks.log");
+    try {
+      if (statSync2(logFile).size > HOOK_LOG_MAX_BYTES) {
+        renameSync2(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/hooks/ensure-agent-session-capture-worker.mjs
+function writeWorkerFailure(error, claim) {
+  try {
+    const entry = {
+      time: (/* @__PURE__ */ new Date()).toISOString(),
+      hook: `${claim?.agentType ?? "unknown"}:ensure-agent-session-capture-worker`,
+      pid: process.pid,
+      agentSessionId: claim?.agentSessionId,
+      error: error instanceof Error ? error.message : String(error),
+      ...error instanceof Error && error.stack ? { stack: error.stack } : {}
+    };
+    process.stderr.write(JSON.stringify(entry) + "\n");
+  } catch {
+  }
+}
+function main({
+  serializedClaim = process.argv[2],
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  writeFailure = writeWorkerFailure
+} = {}) {
+  let claim;
+  try {
+    claim = JSON.parse(serializedClaim);
+    return ensureAgentSessionCapture(claim, spawn, env);
+  } catch (error) {
+    writeFailure(error, claim);
+    try {
+      logFailure(
+        `${claim?.agentType ?? "unknown"}:ensure-agent-session-capture-worker`,
+        error,
+        {
+          agentSessionId: claim?.agentSessionId,
+          cli: env.POLYGRAPH_CLI || "polygraph"
+        }
+      );
+    } catch {
+    }
+    return false;
+  }
+}
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath2(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  process.exitCode = main() ? 0 : 1;
+}
+export {
+  main
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/opencode-plugin",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,
@@ -25,6 +25,7 @@
   "files": [
     "server.js",
     "agent-session-link.mjs",
+    "ensure-agent-session-capture-worker.mjs",
     "frontmatter.mjs",
     "skills/",
     "agents/",

package/server.js

@@ -15,9 +15,11 @@ import { fileURLToPath } from 'node:url';
 
 import {
   createOpenCodeSessionLinker,
+  deferOpenCodeCaptureWake,
   deferOpenCodeToolActivity,
   linkOpenCodeSessionCreatedEvent,
   logHookFailure,
+  openCodeChatMessageSessionId,
 } from './agent-session-link.mjs';
 import { parseFrontmatter } from './frontmatter.mjs';
 
@@ -40,6 +42,24 @@ export const PolygraphPlugin = async ({ client, directory } = {}) => {
           sessionID: input?.event?.properties?.info?.id,
         });
       }
+
+      // session.idle is OpenCode's agent-done signal. It is a capture
+      // liveness wake only — the transcript decides step boundaries.
+      if (input?.event?.type === 'session.idle') {
+        const sessionID = input.event.properties?.sessionID;
+        deferOpenCodeCaptureWake(sessionID, sessionLinker, (error) => {
+          logHookFailure('opencode:session.idle', error, { sessionID });
+        });
+      }
+    },
+
+    // Fires when the user submits a prompt; wakes capture so the prompt is
+    // available promptly even if the sidecar died. Liveness only.
+    'chat.message': async (input, output) => {
+      const sessionID = openCodeChatMessageSessionId(input, output);
+      deferOpenCodeCaptureWake(sessionID, sessionLinker, (error) => {
+        logHookFailure('opencode:chat.message', error, { sessionID });
+      });
     },
 
     config: async (cfg) => {

package/skills/polygraph/SKILL.md

@@ -26,6 +26,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `stop_agent` | — | Cancel an in-progress child by delegation id; its session is preserved for later read-only context restoration. |
 | `push_branch` | — | Push a local git branch to the remote repository. For the repo you are in, this pushes from your current checkout. Requires a session description. |
 | `create_pr` | — | Create draft PRs with session metadata linking related PRs |
+| `update_pr` | — | Update title, user-authored body, labels, or assignees on one PR associated with a session |
 | `show_session` | `polygraph session show <id> [--details]` | Query status of the current session. Use details when session summary, repo IDs, PR URLs, and PR descriptions are needed. |
 | `update_session` | `polygraph session update --session <id> [--title] [--description]` | Update the session title and/or description (at least one required); metadata only, independent of PR creation or mark-ready. |
 | `link_reference` | — | Link an external reference to a session. |
@@ -223,9 +224,9 @@ When polling `show_agent`, treat `permission-required` like `input-required`:
 
 ### Publish Changes (Push Branches, Create PRs, Mark Ready)
 
-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).
+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), `associate_pr` (link PRs created outside Polygraph), and `update_pr` (update metadata on an associated PR).
 
-**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.
+**Whenever you push a branch, create, associate, or update 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
 
@@ -307,6 +308,7 @@ If the session has a description timeline, also display:
 1. **Wait in background subagents** — `spawn_agent` is fine to call directly, but every waited `show_agent` poll MUST go through `@polygraph-delegate-subagent`; inline polling floods the context window 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. **State the output in every brief** — children are told to be concise, so the instruction must say what to return: the shape, a cap where one makes sense, and the exact token for "nothing to report". See [`reference/delegation.md`](reference/delegation.md).
 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
 1. **Link PRs in descriptions** - Reference related PRs in each PR body
 1. **Keep PRs as drafts** until all repos are ready

package/skills/polygraph/reference/delegation.md

@@ -28,12 +28,24 @@ spawn_agent(
 
 `agent` picks the child's harness and `model` overrides its default model; include either only when the user named one.
 
-Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, and what "done" looks like. The child has its own repo and its own context; it inherits nothing from yours.
+Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, what "done" looks like, and what to report back. The child has its own repo and its own context; it inherits nothing from yours.
 
 Delegate to several repos in parallel by calling `spawn_agent` once per repo before waiting on any of them.
 
 **Own-repo rule.** With the default role, `repo` must be a repository other than the one you are working in — never delegate into your own repo with the default role; work on it directly (ordinary local subagents are fine for that). Delegating into your own repo IS allowed with an explicit non-default `role`, because each (repo, role) pair is a separate agent slot and the child then runs alongside your own default-role work without colliding with it.
 
+## The output contract
+
+Children are told to be concise: another agent reads their final message and pays for it on every turn that carries it. Expect terse reports; brevity is not less work done.
+
+Your half is the brief: state the output as well as the input — shape (fields, order), a cap where useful, the exact token for "nothing to report", what to omit. In communicating with child agents, maintain extremely high information density while being concise - describe everything needed in the fewest words possible.
+
+Investigation is where it matters most: a fan-out leaves most repos with nothing to report, and without a named empty answer (`NONE`, `no matches`) each writes several thousand characters to say so.
+
+Implementation still wants concision, but lost information is the worse failure: a missed detail costs a round trip, costlier than the prose. Cut narration, recap, hedging — never branch names, files touched, decisions taken, or anything contradicting the brief.
+
+Prose only where necessary. Consumers are agents first, humans second: dense and structural, not narrative.
+
 ## Waiting
 
 For each id, launch one background poller subagent whose entire job is to block until that child stops moving. Give it the `sessionId` and the `id`, and nothing else.
@@ -59,7 +71,7 @@ When a poller exits, read the child's answer yourself with a single **unwaited**
 show_agent(sessionId: "<sessionId>", id: "<id>")
 ```
 
-`result.text` is the child's final message: what it did, what it found, what it wants you to know. This is the payload. Read it once, in the main conversation, and act on it.
+`result.text` is the child's final message: what it did and what it found, in the shape the instruction asked for. This is the payload. Read it once, in the main conversation, and act on it.
 
 One-off unwaited reads like this are cheap and expected inline. It is the *waiting* that belongs in a subagent, not the reading.
 

package/skills/polygraph/reference/publish-changes.md

@@ -1,6 +1,6 @@
 # Publishing Changes Reference
 
-The branch-to-PR flow: push branches, create draft PRs, mark them ready, and associate PRs created outside Polygraph. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy — read [`session-description.md`](session-description.md) before writing one.
+The branch-to-PR flow: push branches, create draft PRs, mark them ready, associate PRs created outside Polygraph, and update associated PRs. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy — read [`session-description.md`](session-description.md) before writing one. `update_pr` does not require a session timeline description.
 
 ## Push Branches
 
@@ -151,3 +151,50 @@ associate_pr(
 ```
 
 **Returns** the list of PRs now associated with the session.
+
+## Update an Associated PR
+
+Use the MCP `update_pr` tool to update one PR already associated with the named Polygraph session. Do not use `gh` or call Ocean HTTP directly. `mark_pr_ready` remains a separate operation.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID.
+- `prUrl` (required): The URL of a PR already associated with the session.
+- `title` (optional): Replacement PR title.
+- `body` (optional): Replacement user-authored PR body. Pass an empty string to clear it. The managed Polygraph session footer remains server-owned.
+- `labels` (optional): A collection update with `mode` and `values`.
+- `assignees` (optional): A collection update with `mode` and `values`.
+
+Omitted fields remain unchanged. For `labels` and `assignees`:
+
+- `{ mode: "set", values: [...] }` replaces the complete collection. An empty `values` list clears it. Use `set` only when you intend to replace every value because it can remove labels or assignees applied by humans.
+- `add` and `remove` preserve unrelated values and require a non-empty `values` list.
+
+Set the complete label collection and clear the user-authored body:
+
+```
+update_pr(
+  sessionId: "<session-id>",
+  prUrl: "https://github.com/org/repo/pull/123",
+  body: "",
+  labels: {
+    mode: "set",
+    values: ["documentation", "release-note"]
+  }
+)
+```
+
+Add an assignee while leaving the title, body, labels, and other assignees unchanged:
+
+```
+update_pr(
+  sessionId: "<session-id>",
+  prUrl: "https://github.com/org/repo/pull/123",
+  assignees: {
+    mode: "add",
+    values: ["octocat"]
+  }
+)
+```
+
+Metadata updates do not require a session timeline `description`.

package/skills/polygraph/reference/session-description.md

@@ -4,7 +4,7 @@
 
 `description` is user-facing Polygraph session context.
 
-`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) The Polygraph web app renders the description as Markdown, so use real Markdown headings — not flat `Label:` lines. Use the canonical structured format:
+`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). Metadata updates through `update_pr` do not require a session timeline description, and `mark_pr_ready` does not take one. The Polygraph web app renders the description as Markdown, so use real Markdown headings — not flat `Label:` lines. Use the canonical structured format:
 
 ```markdown
 ## Goal