@polygraph/codex-plugin 0.5.0 → 0.5.2

package/.codex-plugin/plugin.json

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

package/hooks/agent-session-capture.mjs

@@ -0,0 +1,214 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import {
+  cliFailure,
+  isManagedChildEnvironment,
+  launchDetachedHookWorker,
+  nonEmptyString,
+  observedAtValue,
+  runCaptureCliSync,
+} from './capture-cli.mjs';
+
+// Ocean may spend up to 2.5 seconds waiting for its singleton startup lock and
+// 10 seconds on the sidecar handshake. Keep enough headroom for CLI startup
+// while retaining one bounded deadline across ensure and its legacy fallback.
+export const ENSURE_CAPTURE_TIMEOUT_MS = 20_000;
+export const ENSURE_CAPTURE_UNSUPPORTED_MARKER =
+  'POLYGRAPH_ENSURE_AGENT_SESSION_CAPTURE_UNSUPPORTED';
+
+const WAKE_AGENT_TYPES = new Set(['claude', 'codex', 'opencode', 'cursor']);
+
+// Every wake event is capture liveness only. Which harness event fired, and
+// in which order, is never forwarded: the transcript alone carries step
+// semantics, so both the prompt-submit and the agent-done wake of a harness
+// produce the identical identity-only invocation.
+const WAKE_EVENTS_BY_AGENT = {
+  claude: new Set(['UserPromptSubmit', 'Stop']),
+  codex: new Set(['UserPromptSubmit', 'Stop']),
+  // afterAgentResponse fires per completed assistant message, so one Cursor
+  // turn may wake several times; every wake is the same idempotent poke and
+  // the message text it carries is never forwarded.
+  cursor: new Set(['beforeSubmitPrompt', 'afterAgentResponse', 'stop']),
+};
+
+const 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];
+}
+
+// The ensure command carries stable harness identity plus the moment the
+// hook fired. Ocean refreshes the exact mapping and compares terminal-marker
+// freshness against that timestamp, so it must be the hook's own clock
+// reading, never the detached worker's start time: a delayed worker cannot
+// present its startup as evidence that the harness was still live.
+export function buildEnsureAgentSessionCaptureArgs({
+  agentType,
+  agentSessionId,
+  observedAt,
+}) {
+  const identity = wakeIdentityArgs({ agentType, agentSessionId });
+  const observed = observedAtValue(observedAt);
+  if (observed === undefined) {
+    throw new Error('observedAt is required: a wake must carry the hook-captured time');
+  }
+
+  return [
+    '_ensure-agent-session-capture',
+    ...identity,
+    '--observed-at',
+    String(observed),
+  ];
+}
+
+// The legacy mapping command keeps its mutable path evidence and `--source`
+// provenance and never carries `--observed-at`. The preferred ensure command
+// above deliberately carries only stable harness identity so a cwd or
+// transcript-path change cannot narrow a liveness lookup to zero mappings.
+export 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 ?? ''}\n${result?.stderr ?? ''}`;
+  if (output.includes(ENSURE_CAPTURE_UNSUPPORTED_MARKER)) return true;
+
+  // Shell 0.1.x prints the root usage to stdout and reports every token as an
+  // unknown argument. Match that complete, observed failure shape rather than
+  // treating an arbitrary error that happens to mention the hidden command as
+  // evidence of version skew.
+  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')
+  );
+}
+
+export function ensureAgentSessionCapture(
+  claim,
+  spawn = spawnSync,
+  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);
+}
+
+export 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,
+  });
+}
+
+export function buildCommandHookEnsureCapture(
+  payload,
+  agentType,
+  env = process.env,
+  now = Date.now
+) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return undefined;
+  }
+  if (isManagedChildEnvironment(env)) return undefined;
+
+  const wakeEvents = WAKE_EVENTS_BY_AGENT[agentType];
+  if (!wakeEvents?.has(payload.hook_event_name)) return undefined;
+
+  // Cursor payloads carry the id in both session_id and conversation_id and
+  // have no top-level cwd; workspace_roots[0] is the launch directory.
+  const agentSessionId =
+    nonEmptyString(payload.session_id) ??
+    (agentType === 'cursor' ? nonEmptyString(payload.conversation_id) : undefined);
+  if (!agentSessionId) return undefined;
+
+  const workspaceRoot =
+    agentType === 'cursor' && Array.isArray(payload.workspace_roots)
+      ? nonEmptyString(payload.workspace_roots[0])
+      : undefined;
+
+  // Captured here, synchronously in the hook process, before any detach.
+  return {
+    agentType,
+    agentSessionId,
+    cwd: nonEmptyString(payload.cwd) ?? workspaceRoot,
+    transcriptPath: nonEmptyString(payload.transcript_path),
+    observedAt: now(),
+  };
+}

package/hooks/agent-session-finalize.mjs

@@ -0,0 +1,170 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import {
+  cliFailure,
+  isManagedChildEnvironment,
+  launchDetachedHookWorker,
+  nonEmptyString,
+  observedAtValue,
+  runCaptureCliSync,
+} from './capture-cli.mjs';
+
+export const FINALIZE_TIMEOUT_MS = 90_000;
+
+const FINALIZE_AGENT_TYPES = new Set(['claude', 'codex', 'cursor']);
+
+// The one lifecycle event per harness that means the conversation ended.
+// Claude and Codex send PascalCase; Cursor sends camelCase. OpenCode exposes
+// no trustworthy per-session exit event.
+const FINALIZE_EVENTS_BY_AGENT = {
+  claude: 'SessionEnd',
+  codex: 'SessionEnd',
+  cursor: 'sessionEnd',
+};
+
+const FINALIZE_WORKER_PATH = fileURLToPath(
+  new URL('./finalize-agent-session-worker.mjs', import.meta.url)
+);
+
+// The finalize command carries identity, the mutable path evidence,
+// `--source`, and the moment the session-end hook fired. Ocean compares that
+// observation against the mapping's last-seen time and ignores a finalize
+// that predates a later wake or relink, so it must be the hook's own clock
+// reading, never the detached worker's start time: a finalize worker may run
+// up to 90 seconds after the harness exit it describes.
+export function buildFinalizeAgentSessionArgs({
+  agentType,
+  agentSessionId,
+  cwd,
+  transcriptPath,
+  source,
+  observedAt,
+}) {
+  const harnessSession = nonEmptyString(agentSessionId);
+  const hookSource = nonEmptyString(source);
+  const observed = observedAtValue(observedAt);
+  if (!FINALIZE_AGENT_TYPES.has(agentType)) {
+    throw new Error(`Unsupported agent type: ${agentType}`);
+  }
+  if (!harnessSession) throw new Error('agentSessionId is required');
+  if (!hookSource) throw new Error('source is required');
+  if (observed === undefined) {
+    throw new Error('observedAt is required: a finalize must carry the hook-captured time');
+  }
+
+  const args = [
+    '_finalize-agent-session',
+    '--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);
+
+  args.push('--source', hookSource, '--observed-at', String(observed));
+  return args;
+}
+
+export function finalizeAgentSession(
+  claim,
+  spawn = spawnSync,
+  env = process.env,
+  runnerOptions = {}
+) {
+  if (isManagedChildEnvironment(env)) return false;
+
+  const {
+    options = {},
+    timeoutMs = FINALIZE_TIMEOUT_MS,
+    now = Date.now,
+    ...runOptions
+  } = runnerOptions;
+  const boundedTimeout =
+    Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? Math.min(Math.floor(timeoutMs), FINALIZE_TIMEOUT_MS)
+      : FINALIZE_TIMEOUT_MS;
+  const deadline = now() + boundedTimeout;
+  const result = runCaptureCliSync(buildFinalizeAgentSessionArgs(claim), {
+    ...runOptions,
+    env,
+    spawn,
+    cwd: claim.cwd,
+    deadline,
+    now,
+    options: {
+      ...options,
+      killSignal: 'SIGKILL',
+      maxBuffer: 256 * 1024,
+    },
+  });
+
+  if (result?.error || result?.status !== 0) {
+    throw cliFailure('_finalize-agent-session', result);
+  }
+
+  return true;
+}
+
+export function launchAgentSessionFinalize(
+  claim,
+  spawn,
+  env = process.env,
+  { workerPath = FINALIZE_WORKER_PATH, ...workerOptions } = {}
+) {
+  if (isManagedChildEnvironment(env)) return false;
+
+  return launchDetachedHookWorker({
+    logName: 'session-finalize.log',
+    ...workerOptions,
+    workerPath,
+    claim,
+    ...(spawn ? { spawn } : {}),
+    env,
+  });
+}
+
+export function buildCommandHookFinalize(
+  payload,
+  agentType,
+  env = process.env,
+  now = Date.now
+) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return undefined;
+  }
+  if (isManagedChildEnvironment(env)) return undefined;
+  if (FINALIZE_EVENTS_BY_AGENT[agentType] !== payload.hook_event_name) {
+    return undefined;
+  }
+
+  // Cursor payloads carry the id in both session_id and conversation_id and
+  // have no top-level cwd; workspace_roots[0] is the launch directory. The
+  // end reason and final status stay behind: the transcript alone decides
+  // what the final answer was. No finalize claim ever carries a PID.
+  const agentSessionId =
+    nonEmptyString(payload.session_id) ??
+    (agentType === 'cursor' ? nonEmptyString(payload.conversation_id) : undefined);
+  if (!agentSessionId) return undefined;
+
+  const workspaceRoot =
+    agentType === 'cursor' && Array.isArray(payload.workspace_roots)
+      ? nonEmptyString(payload.workspace_roots[0])
+      : undefined;
+
+  // The observation time is read here, synchronously in the hook process,
+  // before the worker detaches.
+  return {
+    agentType,
+    agentSessionId,
+    cwd: nonEmptyString(payload.cwd) ?? workspaceRoot,
+    transcriptPath: nonEmptyString(payload.transcript_path),
+    source: 'hook',
+    observedAt: now(),
+  };
+}

package/hooks/agent-session-link.mjs

@@ -3,6 +3,8 @@ import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+import { resolveLaunchDirectory } from './capture-cli.mjs';
+
 const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
 
 const AGENT_TYPES = new Set(['claude', 'codex', 'opencode', 'cursor']);
@@ -29,13 +31,24 @@ export function isPolygraphMcpToolName(toolName) {
   return Boolean(name && (COMMAND_HOOK_TOOL.test(name) || OPENCODE_TOOL.test(name)));
 }
 
+/**
+ * The harness session a hook payload names, for failure diagnostics. Claude
+ * and Codex carry it as session_id; Cursor's prompt and agent-done payloads
+ * carry only conversation_id, and its lifecycle payloads carry both with
+ * the same value.
+ */
+export function hookPayloadSessionId(payload) {
+  return (
+    nonEmptyString(payload?.session_id) ?? nonEmptyString(payload?.conversation_id)
+  );
+}
+
 export function buildLinkAgentSessionArgs({
   polygraphSessionId,
   agentType,
   agentSessionId,
   cwd,
   transcriptPath,
-  pid,
   source,
   hookOperation,
 }) {
@@ -56,10 +69,6 @@ export function buildLinkAgentSessionArgs({
   const transcript = nonEmptyString(transcriptPath);
   if (transcript) args.push('--transcript-path', transcript);
 
-  if (Number.isSafeInteger(pid) && pid > 0) {
-    args.push('--pid', String(pid));
-  }
-
   // Cursor post-tool evidence rides the hook payload (the transcript stores
   // no tool results); forwarded verbatim, classified by the CLI. The
   // operation travels on STDIN, never argv: toolInput can carry an entire
@@ -99,22 +108,35 @@ export function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
     delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
   }
 
+  // The link launches from a directory that exists — the claim's own when it
+  // still does, else home, else temp — exactly like the wake and finalize
+  // processes. The launch directory is a spawn detail only: the recorded
+  // working directory is the claim's `--cwd` above, which a Cursor claim
+  // without workspace roots omits rather than substituting the plugin root.
+  const launchDirectory = resolveLaunchDirectory(claim.cwd, env);
   const spawnOptions = {
     encoding: 'utf8',
     env: commandEnv,
     stdio: [input === undefined ? 'ignore' : 'pipe', 'ignore', 'pipe'],
     ...(input === undefined ? {} : { input }),
+    ...(launchDirectory ? { cwd: launchDirectory } : {}),
   };
 
-  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);
+  // directly: a dev build without the executable bit, a local package
+  // install, or a platform that cannot exec scripts. Such entries run
+  // through a Node runtime up front, so exactly one process ever launches
+  // per link. Bun (which hosts this module in-process for OpenCode) throws
+  // launch errors from spawnSync instead of returning them, so both error
+  // shapes must land in the same path.
+  const jsEntry = /\.[cm]?js$/i.test(command);
+  let result;
+  try {
+    result = jsEntry
+      ? spawn(nodeRuntime(), [command, ...args], spawnOptions)
+      : spawn(command, args, spawnOptions);
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
   }
 
   if (result?.error) throw result.error;

package/hooks/capture-cli.mjs

@@ -0,0 +1,294 @@
+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';
+
+const JS_CLI_ENTRY = /\.[cm]?js$/i;
+export const HOOK_WORKER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+
+export function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+export function isManagedChildEnvironment(env) {
+  return Boolean(env && Object.hasOwn(env, 'POLYGRAPH_CHILD_AGENT'));
+}
+
+export function captureCommandEnvironment(env = process.env) {
+  const commandEnv = { ...env };
+  delete commandEnv.POLYGRAPH_SESSION_ID;
+  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+  return commandEnv;
+}
+
+/**
+ * The directory a capture process is launched from. A claim carries the
+ * harness working directory, but that directory can be gone by the time a
+ * delayed hook or detached worker runs (an archived session worktree, a
+ * removed temp dir), and a spawn from a missing cwd fails with ENOENT before
+ * the CLI ever starts. Working-directory evidence reaches the CLI as an
+ * explicit `--cwd` argument where it matters, so the launch itself only
+ * needs a directory that exists: the claim's own when it does, else the home
+ * directory, else the temp directory.
+ */
+export 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 {
+      // Missing or unreadable: try the next candidate.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The hook process's own working directory, or undefined when it no longer
+ * has one. A harness can start a hook in a directory removed moments earlier
+ * or remove it while the hook runs, and `process.cwd()` then throws
+ * `uv_cwd`. Callers use this only as the last-resort claim directory, so a
+ * missing answer degrades to the launch fallback instead of a crash.
+ */
+export function processWorkingDirectory() {
+  try {
+    return process.cwd();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The working directory a claim may record when the payload carries none.
+ * Claude and Codex run command hooks in the session's own directory, so the
+ * hook process's cwd is genuine harness evidence there. Cursor runs plugin
+ * hooks from the plugin root, which is never the repository: a Cursor claim
+ * without workspace_roots records no directory at all, and the launch
+ * fallback (home, then temp) stays a spawn detail rather than evidence.
+ */
+export function fallbackClaimDirectory(agentType, hookCwd) {
+  if (agentType === 'cursor') return undefined;
+  return nonEmptyString(hookCwd) ?? processWorkingDirectory();
+}
+
+/**
+ * A hook-captured observation time: a positive epoch-millisecond integer, or
+ * undefined for anything else. Wakes and finalizations both carry one, and
+ * neither ever substitutes a worker's own clock for it.
+ */
+export function observedAtValue(value) {
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+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 undefined;
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      Array.isArray(parsed) &&
+      parsed.length > 0 &&
+      parsed.every((part) => nonEmptyString(part))
+    ) {
+      return parsed;
+    }
+  } catch {
+    // An invalid portability hint is ignored in favor of the normal launch.
+  }
+  return undefined;
+}
+
+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 === undefined) return options;
+  const remaining = Math.floor(deadline - now());
+  if (remaining < 1) return undefined;
+  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();
+  // Some runtimes hosting these hooks in-process (OpenCode runs under Bun)
+  // THROW launch errors from spawnSync instead of returning them in
+  // result.error. Both shapes must land in the same error path.
+  try {
+    return spawn(command, args, boundedOptions);
+  } catch (error) {
+    return { error, status: null, signal: null };
+  }
+}
+
+export 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,
+  };
+
+  // A plain JavaScript CLI entry (a local package install, a dev build without
+  // the executable bit) is never executed directly: direct execution fails
+  // EACCES/ENOEXEC on most platforms and Bun surfaces that as a synchronous
+  // throw. Running it through Node up front means exactly one process ever
+  // launches per wake — there is no ambiguity about which attempt ran.
+  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 reportWorkerLaunchFailure(onFailure, error) {
+  try {
+    const pending = onFailure(error);
+    if (pending && typeof pending.catch === 'function') {
+      pending.catch(() => {});
+    }
+  } catch {
+    // A detached handoff must never turn diagnostics into a hook failure.
+  }
+}
+
+// A worker's inherited stdout/stderr land in one append-only log per worker
+// kind, rotated to `.1` past the same bound as hooks.log so a chatty CLI can
+// never grow it without limit.
+export 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 {
+    // There may be no prior log, and rotation must stay best-effort.
+  }
+
+  return openSync(logFile, 'a', 0o600);
+}
+
+/**
+ * Hand a serialized claim to a detached Node worker and return immediately.
+ * The worker owns the complete CLI invocation and its durable failure
+ * logging; the short-lived parent hook observes launch errors only, because
+ * it cannot outlive the harness event that spawned it.
+ *
+ * The worker is a plain JS module, so it always launches through a Node
+ * runtime: process.execPath is the host binary, and under OpenCode that is
+ * the compiled Bun executable rather than Node.
+ */
+export function launchDetachedHookWorker({
+  workerPath,
+  claim,
+  logName,
+  spawn = spawnChild,
+  env = process.env,
+  execPath = process.execPath,
+  onFailure = () => {},
+  openLog = openHookWorkerLog,
+  closeLog = closeSync,
+}) {
+  // The log is diagnostic only. If it cannot be opened (unwritable home,
+  // exhausted descriptors) the worker still launches with its output
+  // discarded; its own durable hooks.log write does not depend on it.
+  let logFd;
+  try {
+    logFd = openLog(env, logName);
+  } catch (error) {
+    reportWorkerLaunchFailure(onFailure, error);
+  }
+  const output = logFd === undefined ? 'ignore' : logFd;
+
+  // The serialized claim keeps the harness cwd as evidence even when the
+  // launch has to happen elsewhere.
+  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 !== undefined) {
+      try {
+        closeLog(logFd);
+      } catch (error) {
+        reportWorkerLaunchFailure(onFailure, error);
+      }
+    }
+  }
+
+  child.once('error', (error) => reportWorkerLaunchFailure(onFailure, error));
+  child.unref();
+
+  return true;
+}
+
+export 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}` : '')
+  );
+}

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

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { ensureAgentSessionCapture } from './agent-session-capture.mjs';
+import { logHookFailure } from './agent-session-link.mjs';
+
+function writeWorkerFailure(error, claim) {
+  try {
+    const entry = {
+      time: 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 {
+    // The inherited log stream is diagnostic only.
+  }
+}
+
+export 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 {
+      // The worker is already detached; diagnostics cannot be allowed to crash it.
+    }
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  process.exitCode = main() ? 0 : 1;
+}

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

@@ -0,0 +1,79 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildCommandHookEnsureCapture,
+  ensureAgentSessionCapture,
+  launchAgentSessionCaptureWake,
+} from './agent-session-capture.mjs';
+import { hookPayloadSessionId, logHookFailure } from './agent-session-link.mjs';
+import { fallbackClaimDirectory } from './capture-cli.mjs';
+
+function readPayload() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  // Harness manifests without an async hook flag pass --detach so the hook
+  // returns immediately; a detached worker then owns the bounded wake. This
+  // matters most for cursor's blocking beforeSubmitPrompt, which would
+  // otherwise stall every prompt on a slow CLI.
+  detach = process.argv.includes('--detach'),
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  // The hook's own directory is read lazily, inside the protected path, and
+  // only when the payload carries none and the harness runs hooks in the
+  // session directory: a default evaluated at entry would throw uv_cwd from
+  // an already-deleted cwd before any fallback could run, and Cursor's hook
+  // cwd is the plugin root rather than the repository.
+  cwd,
+  launcherOptions = {},
+  now = Date.now,
+} = {}) {
+  const reportFailure = (error) =>
+    logFailure(`${agentType || 'unknown'}:ensure-agent-session-capture`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: hookPayloadSessionId(payload),
+    });
+
+  try {
+    const built = buildCommandHookEnsureCapture(payload, agentType, env, now);
+    if (!built) return false;
+
+    const claim = {
+      ...built,
+      cwd: built.cwd ?? fallbackClaimDirectory(agentType, cwd),
+    };
+    if (detach) {
+      return launchAgentSessionCaptureWake(claim, spawn, env, {
+        ...launcherOptions,
+        onFailure: reportFailure,
+      });
+    }
+    return ensureAgentSessionCapture(claim, spawn, env);
+  } catch (error) {
+    reportFailure(error);
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/hooks/finalize-agent-session-worker.mjs

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { finalizeAgentSession } from './agent-session-finalize.mjs';
+import { logHookFailure } from './agent-session-link.mjs';
+
+function writeWorkerFailure(error, claim) {
+  try {
+    const entry = {
+      time: new Date().toISOString(),
+      hook: `${claim?.agentType ?? 'unknown'}:finalize-agent-session-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 {
+    // The inherited log stream is diagnostic only.
+  }
+}
+
+export function main({
+  serializedClaim = process.argv[2],
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  writeFailure = writeWorkerFailure,
+} = {}) {
+  let claim;
+  try {
+    claim = JSON.parse(serializedClaim);
+    return finalizeAgentSession(claim, spawn, env);
+  } catch (error) {
+    writeFailure(error, claim);
+    try {
+      logFailure(
+        `${claim?.agentType ?? 'unknown'}:finalize-agent-session-worker`,
+        error,
+        {
+          agentSessionId: claim?.agentSessionId,
+          cli: env.POLYGRAPH_CLI || 'polygraph',
+        }
+      );
+    } catch {
+      // The worker is already detached; diagnostics cannot be allowed to crash it.
+    }
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  process.exitCode = main() ? 0 : 1;
+}

package/hooks/finalize-agent-session.mjs

@@ -0,0 +1,70 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildCommandHookFinalize,
+  launchAgentSessionFinalize,
+} from './agent-session-finalize.mjs';
+import { hookPayloadSessionId, logHookFailure } from './agent-session-link.mjs';
+import { fallbackClaimDirectory } from './capture-cli.mjs';
+
+function readPayload() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  // The hook's own directory is read lazily, inside the protected path, and
+  // only when the payload carries none and the harness runs hooks in the
+  // session directory: a default evaluated at entry would throw uv_cwd from
+  // an already-deleted cwd before any fallback could run, and Cursor's hook
+  // cwd is the plugin root rather than the repository.
+  cwd,
+  launcherOptions = {},
+  now = Date.now,
+} = {}) {
+  const reportFailure = (error) =>
+    logFailure(`${agentType || 'unknown'}:finalize-agent-session`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: hookPayloadSessionId(payload),
+    });
+
+  try {
+    const finalize = buildCommandHookFinalize(payload, agentType, env, now);
+    if (!finalize) return false;
+    return launchAgentSessionFinalize(
+      {
+        ...finalize,
+        cwd: finalize.cwd ?? fallbackClaimDirectory(agentType, cwd),
+      },
+      spawn,
+      env,
+      { ...launcherOptions, onFailure: reportFailure }
+    );
+  } catch (error) {
+    reportFailure(error);
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/hooks/hooks.json

@@ -28,6 +28,39 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${PLUGIN_ROOT}/hooks/ensure-agent-session-capture.mjs codex --detach",
+            "statusMessage": "Ensuring Polygraph session capture"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${PLUGIN_ROOT}/hooks/ensure-agent-session-capture.mjs codex --detach",
+            "statusMessage": "Ensuring Polygraph session capture"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${PLUGIN_ROOT}/hooks/finalize-agent-session.mjs codex",
+            "statusMessage": "Finalizing Polygraph session capture"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/record-session-mapping.mjs

@@ -3,9 +3,11 @@ import { fileURLToPath } from 'node:url';
 
 import {
   buildCommandHookLink,
+  hookPayloadSessionId,
   linkAgentSession,
   logHookFailure,
 } from './agent-session-link.mjs';
+import { fallbackClaimDirectory } from './capture-cli.mjs';
 
 function readPayload() {
   try {
@@ -20,29 +22,29 @@ export function main({
   payload = readPayload(),
   agentType = process.argv[2],
   env = process.env,
-  pid = process.ppid,
   spawn,
+  logFailure = logHookFailure,
 } = {}) {
   try {
     const link = buildCommandHookLink(payload, agentType, env);
     if (!link) return false;
 
-    const claim = {
-      ...link,
-      cwd: link.cwd ?? process.cwd(),
-    };
-    // Claude lifecycle hooks deliberately forward only the exact harness
-    // identity, transcript, cwd, and hook source. PID is not identity and can
-    // be stale by the time an asynchronous SessionStart hook runs.
-    if (!(agentType === 'claude' && payload?.hook_event_name === 'SessionStart')) {
-      claim.pid = pid;
-    }
-
-    return linkAgentSession(claim, spawn, env);
+    // Claude and Codex run this hook in the session directory, so the hook's
+    // own cwd stands in when the payload carries none; Cursor's hook cwd is
+    // the plugin root and is never recorded. Read lazily, inside the
+    // protected path, because a deleted cwd makes process.cwd() throw.
+    return linkAgentSession(
+      {
+        ...link,
+        cwd: link.cwd ?? fallbackClaimDirectory(agentType),
+      },
+      spawn,
+      env
+    );
   } catch (error) {
-    logHookFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
+    logFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
       hookEventName: payload?.hook_event_name,
-      agentSessionId: payload?.session_id,
+      agentSessionId: hookPayloadSessionId(payload),
     });
     return false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/codex-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,

package/skills/polygraph/SKILL.md

@@ -42,6 +42,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. |
@@ -218,9 +219,9 @@ The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do
 
 ### 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
 
@@ -302,6 +303,7 @@ If the session has a description timeline, also display:
 1. **Route waiting through Codex Polygraph subagents** — Use Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"` to create new sessions, and `agent_type: "polygraph-delegate-subagent"` to wait on each delegation id. The Polygraph MCP `spawn_agent` and unwaited `show_agent` reads are yours to call directly; collect poller results with `wait_agent`.
    
 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