@polygraph/claude-plugin 0.5.1 → 0.5.3

package/.claude-plugin/plugin.json

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

package/hooks/CAPTURE_CONTRACT.md

@@ -0,0 +1,178 @@
+# Capture wake hook contract
+
+The wake hooks in this directory carry capture liveness only. Transcript
+records remain canonical for prompts, answers, completion, and step
+boundaries. No wake event communicates a semantic boundary, and no wake may
+create, close, or cancel a step or pass a status.
+
+## Wake events per harness
+
+Each harness wakes capture on prompt submission and on agent-done/idle,
+using the lifecycle events its plugin API actually exposes:
+
+- Claude Code: `UserPromptSubmit` and `Stop` (manifest-async).
+- Codex: `UserPromptSubmit` and `Stop` (hook detaches via `--detach`).
+- OpenCode: `chat.message` (session from the hook's documented
+  `input.sessionID`) and the `session.idle` bus event (both deferred to a
+  detached worker; subagent sessions resolve to their root before waking).
+- Cursor: `beforeSubmitPrompt`, `afterAgentResponse`, and `stop` (all
+  detach via `--detach`). `beforeSubmitPrompt` is a blocking hook, so the
+  parent process must return immediately and emit nothing on stdout; Cursor
+  treats empty output as allow. `afterAgentResponse` is the agent-done wake:
+  an observational hook that fires once an assistant message completes. It
+  carries the message text, which the wake never forwards. `stop` is
+  Cursor's blocking agent-loop-end hook: it may answer with a
+  `followup_message`, which Cursor auto-submits as the next prompt, so the
+  wake exits 0 with empty stdout and never writes to it — Cursor treats no
+  output as no follow-up. Live multi-turn runs under `cursor-agent --plugin-dir`
+  dispatched `beforeSubmitPrompt`, `afterAgentResponse`, `sessionStart`,
+  `afterAgentThought`, `postToolUse`, and `sessionEnd` to plugin-scope
+  hooks; `stop` was never observed, so its registration is inert unless a
+  Cursor build dispatches it, in which case it repeats the same idempotent
+  poke. All registrations live in the plugin manifest; nothing may prompt a
+  user-scope `~/.cursor/hooks.json` registration. None of these events
+  defines a step boundary — a multi-message turn wakes more than once, and
+  the transcript alone decides where steps begin and end.
+
+Every wake calls `_ensure-agent-session-capture` with the agent type, the
+harness session ID, and `--observed-at <ms>`: the epoch-millisecond time at
+which the hook fired, read synchronously in the hook process (for OpenCode,
+in the event handler) before any deferral or worker detach. Ocean uses it to
+refresh the exact mapping and to compare terminal-marker freshness. It is
+lifecycle/liveness metadata only — never a step boundary and never data —
+and a worker's own start time is never used, so a delayed worker cannot
+present its startup as evidence that the harness was still live. Mutable
+working-directory and transcript-path evidence must not narrow an ensure
+lookup. There is no `--source` on the ensure command: a liveness poke has no
+mapping provenance. Which event fired is never forwarded — prompt-submit and
+agent-done wakes are identical invocations apart from the timestamp. The
+legacy `_link-agent-session` compatibility fallback keeps the working
+directory, transcript path, and `--source hook` because it still records a
+mapping, and never carries `--observed-at`. `_finalize-agent-session` carries
+its own `--observed-at`, described under Finalization.
+
+## Process identity
+
+Harness and plugin links never carry a PID. A command hook's `process.ppid`
+is an implementation detail of the harness's hook launcher and may name a
+short-lived shell or helper rather than the agent. OpenCode's in-process
+plugin PID is host-wide rather than session-specific. Neither is trustworthy
+session lifecycle evidence, so `_link-agent-session`, capture wakes, and
+finalizers never emit `--pid`. Claude, Codex, and Cursor use their explicit
+session-end events for graceful finalization. OpenCode exposes no trustworthy
+per-session exit event; capture already uploads transcript records
+incrementally, and an unobserved hard exit does not create a semantic boundary.
+
+## Execution rules
+
+Command-hook wakes are bounded by one shared twenty-second deadline,
+repeatable, and may overlap or arrive out of order with SessionEnd. A
+timed-out or ambiguously executed command is never retried by the plugin.
+An older CLI that reports `_ensure-agent-session-capture` as unsupported is
+retried once through the established `_link-agent-session` mapping command.
+The version-skew check accepts Ocean's explicit marker and the observed Shell
+0.1.x root-usage/validation response whose first rejected argument is the
+hidden command. Other CLI failures never trigger the fallback. A wake is
+successful only when the preferred command or that fallback exits
+successfully, so a successful compatibility wake does not log the old CLI's
+full usage on every prompt and done event.
+
+A `POLYGRAPH_CLI` that points at a plain `.js`/`.mjs`/`.cjs` entry always
+runs through a Node runtime — never executed directly — so exactly one
+process launches per wake even on hosts (Bun in OpenCode) that throw spawn
+launch errors synchronously instead of reporting them on the result.
+
+Every launch — the wake or finalize CLI process and the detached worker —
+starts from a directory that exists: the claim's working directory when it
+still does, else the home directory, else the temp directory. A harness
+working directory can vanish before a delayed hook runs (an archived
+session worktree), and a spawn from a missing cwd fails with ENOENT before
+the CLI starts, which would silently drop a finalize. The fallback changes
+only where the process starts; the `--cwd` evidence on the finalize and
+legacy link commands stays the claim's original directory. The
+`_link-agent-session` process run by `record-session-mapping` (SessionStart
+and PostToolUse links) launches by the same rule while keeping its
+synchronous, unbounded, stdout-ignored contract. A hook's own working
+directory is consulted only when the payload carries none, only inside the
+protected path, and only for Claude and Codex, whose command hooks run in the
+session directory: a hook already running from a deleted directory
+(`process.cwd()` fails with `uv_cwd`) still reaches that fallback instead of
+crashing before it. Cursor runs plugin hooks from the plugin root, which is
+never the repository, so a Cursor payload without `workspace_roots` yields a
+claim with no directory and no `--cwd` on the finalize or legacy link
+command; the launch then starts from the home directory as a spawn detail
+only.
+
+Detached command hooks, OpenCode wakes, and Claude/Codex/Cursor finalization
+hand off to a detached worker. A wake worker enforces the shared twenty-second
+CLI kill deadline; the finalization worker allows at most 90 seconds. Each
+worker owns the complete CLI invocation and writes failures durably to
+`~/.polygraph/logs/hooks.log`; the harness event loop observes launch errors
+only. Workers always launch through a Node runtime — `process.execPath` when
+it is Node, otherwise `node` from PATH — because OpenCode hosts the plugin
+inside a compiled Bun binary.
+
+A worker's inherited stdout/stderr go to `~/.polygraph/logs/capture-wake.log`
+or `session-finalize.log`, each rotated to `.1` once it exceeds 5 MiB, the
+same bound as `hooks.log`. If that file cannot be opened, the worker still
+launches with its output discarded and the failure is logged best-effort;
+no hook ever writes to its own stdout, and no hook waits on a worker.
+
+## Finalization
+
+Claude's and Codex's `SessionEnd` and Cursor's `sessionEnd` finalize
+(`_finalize-agent-session`, which keeps `--source`): each is the one
+lifecycle event of its harness that means the conversation has ended. All
+three hand off to the detached finalization worker and emit nothing on stdout.
+Cursor's `sessionEnd` is observational and dispatched to plugin-scope hooks
+under `cursor-agent --plugin-dir`; its payload carries `session_id` and
+`conversation_id`, `workspace_roots`, `transcript_path`, `reason`, and
+`final_status`. The finalize claim forwards identity, working directory,
+transcript path, `--source hook`, and `--observed-at <ms>` — the
+epoch-millisecond time at which the session-end hook fired, read
+synchronously in the hook process before the worker detaches, exactly as a
+wake reads it — and never a PID (Cursor's hook parent is a transient
+wrapper) or the end reason, because the transcript alone decides what the
+final answer was. The observation time is what lets Ocean order a finalize
+against wakes and relinks: the finalization worker may run up to 90 seconds
+after the harness exit it describes, and its own start time is never used. Claude `SessionStart` accepts
+`startup`, `resume`, `clear`, `compact`, and `fork`. Ordinary Stop/idle
+events never finalize. Codex's graceful `SessionEnd` hook has a one-second
+default budget and three-second maximum; the hook only launches the detached
+worker, so final capture continues outside that budget. OpenCode exposes no
+trustworthy per-session exit event and cannot finalize.
+
+## Environment
+
+All wake and finalize invocations preserve the hook environment except for
+`POLYGRAPH_SESSION_ID` and `POLYGRAPH_CAPTURE_TOKEN`. A
+`POLYGRAPH_CHILD_AGENT` environment disables every wake and finalize. On
+Windows, Ocean may provide `POLYGRAPH_CLI_REEXEC` as a JSON argv array for a
+shell-free invocation of the exact CLI build.
+
+## Ocean's obligations
+
+Ocean must provide the ordering guarantee the plugin cannot impose across
+asynchronous hooks: ensure/link and finalize are idempotent for an agent
+session, finalize dominates an in-flight or later wake, and a wake after
+finalization does not resurrect capture. Concretely, Ocean keeps a terminal
+marker for each finalized harness session and applies a freshness guard to
+it: a delayed or reordered wake whose `--observed-at` does not postdate a
+harness session's terminal marker is a no-op and never resurrects capture,
+while a genuinely newer session mapping for that identity — a later
+SessionStart/sessionStart link recorded after the marker — may supersede
+the older terminal marker and start fresh capture. The plugin never
+distinguishes the two cases; it issues the same identity-plus-timestamp
+wake either way. Ocean must accept `--observed-at` on
+`_ensure-agent-session-capture` and on `_finalize-agent-session`, and must
+ignore a finalize whose observation predates the mapping's last-seen time
+(`mapping.lastSeenAt > observedAt`) instead of writing a completion marker:
+a harness exit observed at T1 whose finalize lands after a
+SessionStart/sessionStart relink or a wake of the same identity observed
+later than T1 describes a conversation that has since resumed, and must not
+terminate it. Ocean should emit
+`POLYGRAPH_ENSURE_AGENT_SESSION_CAPTURE_UNSUPPORTED` when a CLI
+intentionally cannot serve the ensure command; the plugin also recognizes
+the legacy Shell 0.1.x stdout response: root `Usage: polygraph`, followed by
+`Validation failed for one or more options` and `Unknown argument:
+_ensure-agent-session-capture`, with exit status 1 and empty stderr.

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

@@ -1,25 +1,57 @@
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
-function nonEmptyString(value) {
-  return typeof value === 'string' && value.trim() ? value : undefined;
-}
+import {
+  cliFailure,
+  isManagedChildEnvironment,
+  launchDetachedHookWorker,
+  nonEmptyString,
+  observedAtValue,
+  runCaptureCliSync,
+} from './capture-cli.mjs';
 
-function isManagedChildEnvironment(env) {
-  return Boolean(env && Object.hasOwn(env, 'POLYGRAPH_CHILD_AGENT'));
-}
+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);
-  if (agentType !== 'claude') throw new Error(`Unsupported agent type: ${agentType}`);
+  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',
@@ -35,51 +67,104 @@ export function buildFinalizeAgentSessionArgs({
   const transcript = nonEmptyString(transcriptPath);
   if (transcript) args.push('--transcript-path', transcript);
 
-  args.push('--source', hookSource);
+  args.push('--source', hookSource, '--observed-at', String(observed));
   return args;
 }
 
-export function finalizeAgentSession(claim, spawn = spawnSync, env = process.env) {
+export function finalizeAgentSession(
+  claim,
+  spawn = spawnSync,
+  env = process.env,
+  runnerOptions = {}
+) {
   if (isManagedChildEnvironment(env)) return false;
 
-  const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? 'polygraph';
-  const commandEnv = { ...env };
-  delete commandEnv.POLYGRAPH_SESSION_ID;
-  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
-
-  const result = spawn(command, buildFinalizeAgentSessionArgs(claim), {
-    encoding: 'utf8',
-    env: commandEnv,
-    stdio: ['ignore', 'ignore', 'pipe'],
+  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) throw result.error;
-  if (result?.status !== 0) {
-    const detail = nonEmptyString(result?.stderr);
-    throw new Error(
-      `polygraph _finalize-agent-session exited with status ${String(result?.status)}` +
-        (detail ? `: ${detail}` : '')
-    );
+  if (result?.error || result?.status !== 0) {
+    throw cliFailure('_finalize-agent-session', result);
   }
 
   return true;
 }
 
-export function buildCommandHookFinalize(payload, agentType, env = process.env) {
-  if (!payload || typeof payload !== 'object') return undefined;
+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 (agentType !== 'claude' || payload.hook_event_name !== 'SessionEnd') {
+  if (FINALIZE_EVENTS_BY_AGENT[agentType] !== payload.hook_event_name) {
     return undefined;
   }
 
-  const agentSessionId = nonEmptyString(payload.session_id);
+  // 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),
+    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;