syntaur 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {

package/platforms/SESSION-ID-RESOLUTION.md

@@ -0,0 +1,117 @@
+# Cross-agent session-id resolution
+
+Session identity is an **ambient property of the running process**, resolved on
+demand — never persisted-and-looked-up in the shared `.syntaur/context.json`
+scalar (a co-tenant sharing the workspace clobbers it). The CLI does this in
+`src/utils/session-id.ts` (`resolveOwnSessionId`), with six layers:
+
+1. explicit `--session-id`
+2. injected env var: `CLAUDE_CODE_SESSION_ID` / `OPENCODE_SESSION_ID` / `PI_SESSION_ID`
+3. agent side channel (Cursor nonce → `conversation_id`)
+4. ancestor-pid → runtime marker (`~/.claude/sessions/<pid>.json`, then the
+   generic `~/.syntaur/runtime/sessions/<pid>.json`), pid-reuse-guarded by `procStart`
+5. cwd/mtime transcript scan (last automatic resort; ambiguous under co-tenancy)
+6. legacy `context.json.sessionId` hint (only when the caller opts in)
+
+**The consuming half (layers 2, 4, 5, 6) is implemented and unit-tested today.**
+Each agent's job is only to make its real id reachable by layer 2, 3, or 4 — i.e.
+to **normalize the key**, never to synthesize an id. Per-agent status and the
+exact injector below.
+
+## Generic runtime marker (layer 4)
+
+Any agent whose start/early hook learns the real id but cannot inject env can
+stamp a marker that both the resolver and the Codex cleanup hook read:
+
+```
+~/.syntaur/runtime/sessions/<agentPid>.json
+  = { "sessionId": "<real id>", "agent": "<name>", "cwd": "<abs>",
+      "procStart": "<ps -o lstart= string>", "writtenAt": <epoch ms> }
+```
+
+`procStart` guards against pid reuse (compared to `ps -o lstart= -p <pid>`).
+Helpers: `writeRuntimeMarker` / `readRuntimeMarker` in `src/utils/session-id.ts`.
+Override the dir in tests/hooks via `$SYNTAUR_RUNTIME_SESSIONS_DIR`.
+
+---
+
+## Claude Code — EXACT (shipped, no new runtime code)
+
+Native `CLAUDE_CODE_SESSION_ID` env is injected into every child process, so a
+`syntaur` command is a child and layer 2 hits. Confirmed live:
+`CLAUDE_CODE_SESSION_ID` and the ancestor-pid file `~/.claude/sessions/<pid>.json`
+resolve to the same id. The SessionStart hook still mirrors the id into
+`context.json` as a legacy hint (back-compat). **Fixes the reported bug.**
+
+## OpenCode — injector ships as a plugin (live-build gate)
+
+OpenCode's plugin API exposes `plugin.trigger("shell.env", { sessionID })` per
+spawn (`@opencode-ai/plugin`). A ~5-line plugin injects `OPENCODE_SESSION_ID`,
+which layer 2 then reads. Reference plugin: `platforms/opencode/plugin/syntaur-session-env.js`.
+
+- **Caveat:** the V2 `core` bash tool is not yet wired to `shell.env`
+  (`// TODO` in `packages/core/src/tool/bash.ts`); the `opencode` `ShellTool`
+  path is. Verify on the target build.
+- **Status:** Syntaur's current OpenCode integration is **adapter-file-only**
+  (`platforms/opencode/README.md`) — it has no persistent-plugin install path
+  yet. The plugin is shipped as a reference artifact; wiring it into a
+  Syntaur-managed install is follow-up work.
+- **Live verification gate (cannot run here):** from an OpenCode tool call,
+  `echo $OPENCODE_SESSION_ID` returns the conversation/session id.
+
+## Pi — injector ships as an extension (live-build gate)
+
+Pi extensions expose `session_start` (capture `ctx.sessionManager.getSessionId()`)
+and a bash `spawnHook` that injects env per spawn. Inject `PI_SESSION_ID` (layer
+2). Reference: `platforms/pi/extension/syntaur-session-env.js` + `platforms/pi/README.md`.
+
+- **Status:** Syntaur ships a Pi extension at
+  `platforms/pi/extensions/syntaur/` (dashboard session tracking). It does not
+  yet inject `PI_SESSION_ID`; adding the `spawnHook` injector to that extension
+  is the remaining piece. See `platforms/pi/README.md`.
+- **Live verification gate (cannot run here):** `echo $PI_SESSION_ID` from a Pi
+  tool call returns the real id.
+
+## Cursor — best-effort nonce handshake (env injection impossible)
+
+Cursor hooks deliver `conversation_id` on stdin and can only allow/deny — they
+**cannot inject env**, and there is no `CURSOR_SESSION_ID` (open feature
+request). So we key on a per-invocation **nonce**, not cwd (cwd is ambiguous
+under co-tenancy):
+
+1. The `syntaur` CLI emits a nonce token in its own argv.
+2. A shipped `beforeShellExecution` hook (which knows `conversation_id`) writes
+   `nonce → conversation_id` into `~/.syntaur/runtime/cursor-nonces/<nonce>.json`.
+3. The resolver's **layer-3 seam** (`resolveSideChannelSessionId` in
+   `src/utils/session-id.ts`) reads its own nonce back.
+
+- **Status:** layer-3 seam exists and returns `undefined` (no-op) today; the
+  argv-nonce emission and the `beforeShellExecution` hook are the remaining
+  pieces. Documented design; reference hook in `platforms/cursor/hooks/`.
+- **Live verification gate (cannot run here):** needs a live Cursor session.
+
+## Codex — best-effort; exact requires a start hook (open question resolved)
+
+**Open question (design memo #1): does Codex expose a session-start event and/or
+the process pid to a hook?** Finding from this branch's wired Codex hooks
+(`platforms/codex/hooks.json`):
+
+- `PreToolUse` (`enforce-boundaries.sh`) stdin carries `.tool_name` /
+  `.tool_input` only — **no session id, no pid.**
+- `SessionEnd` (`session-cleanup.sh`) stdin carries `.cwd` only — **no id.**
+- **There is no SessionStart hook.**
+
+So Codex exposes no real id to any currently-wired hook, and capture-at-birth
+(stamping the generic marker) is **not possible today** without Codex either
+adding a session-start event that surfaces the rollout id/pid, or surfacing an
+id on an existing hook's stdin. If/when it does, an early hook can
+`writeRuntimeMarker(<codexPid>, …)` and both the resolver (layer 4) and the
+Codex cleanup hook will resolve it exactly.
+
+**Honest floor today:**
+- `session-cleanup.sh` no longer trusts the clobbered scalar; it resolves only
+  from an exact runtime marker and otherwise **skips** (the dashboard liveness
+  reaper marks the dead session stopped). It never mis-stops a co-tenant.
+- For attribution that must be exact now, pass explicit `--session-id`
+  (sourced from `payload.id` of the matching `~/.codex/sessions/.../rollout-*.jsonl`,
+  as `platforms/codex/scripts/resolve-session.sh` already does on a cwd basis).

package/platforms/claude-code/agents/syntaur-expert.md

@@ -405,7 +405,7 @@ Created by `/grab-assignment` in the current working directory. The SessionStart
 }
 ```
 
-Read by `/plan-assignment`, `/complete-assignment`, and the write boundary hook to determine what the current agent is allowed to do.
+Read by `/plan-assignment`, `/complete-assignment`, and the write boundary hook to determine what the current agent is allowed to do. Note that the `sessionId` scalar above is a shared, **legacy hint** — a co-tenant sharing the workspace can clobber it. The active session id is resolved from the running process (env `$CLAUDE_CODE_SESSION_ID` / the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`, else `syntaur session resolve-id`); the scalar is only a last-resort fallback, never authoritative.
 
 ---
 

package/platforms/claude-code/commands/track-session/track-session.md

@@ -33,11 +33,12 @@ Extract optional flags from the argument string:
 
 ### Step 2: Source the real session id + transcript path
 
-In priority order:
+Resolve the session id from *your* running process, in priority order:
 
-1. Read `.syntaur/context.json` if present. If it contains `sessionId`, use it. Also pick up `transcriptPath` if present.
-2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
-3. If neither source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
+1. `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`) if your runtime injects it.
+2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/<pid>.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
+3. Only as a last resort, fall back to the `sessionId` scalar in `.syntaur/context.json` (and the companion `transcriptPath` if present). This scalar is a shared, legacy hint a co-tenant sharing this workspace can clobber — never treat it as authoritative.
+4. If no source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
 
 DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
 

package/platforms/claude-code/hooks/hooks.json

@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Before compaction, if there is an active Syntaur assignment (check `.syntaur/context.json` for `assignmentDir` and `sessionId`), invoke `/save-session-summary` to write `<assignmentDir>/sessions/<sessionId>/summary.md` so a future session can resume cleanly. Skip silently if no active Syntaur context. Do NOT write to `handoff.md` — that is reserved for cross-ticket handoff at completion."
+            "prompt": "Before compaction, if there is an active Syntaur assignment (check `.syntaur/context.json` for `assignmentDir`), invoke `/save-session-summary` so a future session can resume cleanly. The summary is written under `<assignmentDir>/sessions/<sessionId>/`, where the CLI resolves `<sessionId>` from your running process (env / process tree) — do not read it from the `context.json` scalar (a co-tenant can clobber that hint). Skip silently if no active Syntaur context. Do NOT write to `handoff.md` — that is reserved for cross-ticket handoff at completion."
           }
         ]
       }

package/platforms/claude-code/hooks/session-cleanup.sh

@@ -29,20 +29,28 @@ if [ ! -f "$CONTEXT_FILE" ]; then
   exit 0
 fi
 
-# --- Step 4: Extract context info ---
-SESSION_ID=$(jq -r '.sessionId // empty' "$CONTEXT_FILE" 2>/dev/null)
-MISSION_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
-ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
-
-# Fall back to the SessionEnd stdin payload if context.json didn't have the id.
-# Claude Code passes session_id on stdin for SessionEnd.
+# --- Step 4: Resolve the ENDING session's id ---
+# Prefer the exact, per-process id from the SessionEnd stdin payload (Claude
+# Code's contract passes .session_id). The context.json scalar is shared mutable
+# state a co-tenant can clobber, so it is only a last-resort fallback — reading
+# it first would mark the WRONG session stopped when two sessions share a
+# workspace.
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
 if [ -z "$SESSION_ID" ]; then
-  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+  SESSION_ID=$(jq -r '.sessionId // empty' "$CONTEXT_FILE" 2>/dev/null)
 fi
+MISSION_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
 
 # No real session id available — exit quietly. We never synthesize one.
 [ -z "$SESSION_ID" ] && exit 0
 
+# Defensive: the id becomes a URL path segment — reject anything that isn't a
+# plain id (UUID/ULID charset). Real Claude session ids never trip this.
+case "$SESSION_ID" in
+  *[!A-Za-z0-9_-]*) exit 0 ;;
+esac
+
 # --- Dashboard endpoint resolution (mirror session-start.sh exactly so start
 # and end hooks always target the same host:port) ---
 PORT="${SYNTAUR_DASHBOARD_PORT:-}"

package/platforms/claude-code/skills/clear-assignment/SKILL.md

@@ -90,7 +90,7 @@ Do not delete the `.syntaur/` directory itself — other tooling may use it.
 
 ## Step 5: Close Session (optional)
 
-If the original `context.json` included a `sessionId` and the Syntaur dashboard is running, mark the session as cleared so the dashboard does not keep showing it as active:
+If the Syntaur dashboard is running, mark this session as cleared so the dashboard does not keep showing it as active. Resolve `<session-id>` from *your* running process — prefer `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`), otherwise run `syntaur session resolve-id`. Only if neither yields an id, fall back to the `sessionId` you captured from the original `context.json` in Step 1 (before deletion) — that scalar is a shared, legacy hint a co-tenant can clobber, so don't treat it as authoritative:
 
 ```bash
 curl -s -X PATCH "http://localhost:$(cat ~/.syntaur/dashboard-port 2>/dev/null || echo 4800)/api/agent-sessions/<session-id>/status" \

package/platforms/claude-code/skills/complete-assignment/SKILL.md

@@ -101,7 +101,7 @@ Do NOT uncheck or rewrite superseded todo lines matching `- [x] ~~...~~ (superse
 
 ## Step 6: Close Session (optional)
 
-If `.syntaur/context.json` includes a `sessionId` and the Syntaur dashboard is running, mark the session as completed:
+If the Syntaur dashboard is running, mark this session as completed. Resolve `<session-id>` from *your* running process — prefer `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`), otherwise run `syntaur session resolve-id`; fall back to the `sessionId` scalar in `.syntaur/context.json` only as a last resort (it is a shared, legacy hint a co-tenant can clobber, not authoritative):
 
 ```bash
 curl -s -X PATCH "http://localhost:$(cat ~/.syntaur/dashboard-port 2>/dev/null || echo 4800)/api/agent-sessions/<session-id>/status" \

package/platforms/claude-code/skills/grab-assignment/SKILL.md

@@ -113,14 +113,15 @@ Use absolute paths (expand `~` to the home directory). If `workspace.repository`
 
 ## Step 6: Register Agent Session (real IDs only — no UUIDs)
 
-`syntaur track-session` requires a `--session-id` from the agent runtime. Synthetic UUIDs are rejected. Source the real id in this order:
+`syntaur track-session` requires a `--session-id` from the agent runtime. Synthetic UUIDs are rejected. Source the real per-process id in this order:
 
-1. If `.syntaur/context.json` already has `sessionId` (platform SessionStart hook populated it), use it and the companion `transcriptPath` if present.
+1. Prefer the env var your runtime injects: `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`).
 2. Otherwise, fall back to the per-agent lookup:
-   - **Claude Code**: the most-recently-modified `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` — read its `sessionId`. The transcript path is `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` (omit if the file is absent).
+   - **Claude Code**: the most-recently-modified `~/.claude/sessions/<pid>.json` whose `cwd` matches `$(pwd)` — read its `sessionId`. The transcript path is `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` (omit if the file is absent).
    - **Codex**: the most-recently-modified file under `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` whose first-line `session_meta.payload.cwd` matches `$(pwd)`. Use `payload.id` as the session id and the full rollout path as the transcript path.
    - **Other agents**: use whatever real session identifier the runtime exposes. Do not invent one.
-3. If no real id can be resolved, stop and tell the user to restart the session so the platform hook can populate it, or to run `/rename <assignment-slug>` (Claude Code) and retry.
+3. Only as a last resort, fall back to the `sessionId` scalar already in `.syntaur/context.json` (and the companion `transcriptPath` if present). That scalar is a shared, legacy hint a co-tenant sharing this workspace can clobber — never treat it as authoritative.
+4. If no real id can be resolved, stop and tell the user to restart the session so the platform hook can populate it, or to run `/rename <assignment-slug>` (Claude Code) and retry.
 
 After resolving, merge `sessionId` + `transcriptPath` back into context.json. Then register:
 

package/platforms/claude-code/skills/save-session-summary/SKILL.md

@@ -32,9 +32,14 @@ If the file does not exist, tell the user: "No active assignment found. Run `gra
 
 Extract:
 - `assignmentDir` (absolute path) — required.
-- `sessionId` — required, must be the real agent runtime session id.
 
-If `sessionId` is missing, empty, or `null`, abort with: "Session not tracked. Run `syntaur track-session ...` first." Do not invent or generate a session id.
+**Do not read the session id from `context.json` for identity.** That scalar is
+a shared, legacy hint a co-tenant can clobber. The session id is resolved from
+*your* running process — prefer, in order:
+1. `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`) if your runtime injects it.
+2. Otherwise omit `--session-id` entirely and let `syntaur session save` resolve it (it walks env → process tree → transcript, and falls back to the `context.json` hint only as a last resort).
+
+Never invent or generate a session id.
 
 ## Step 2: Author the summary body
 
@@ -75,13 +80,17 @@ Pass the body to `syntaur session save` (it owns the directory, frontmatter,
 and `created`-preservation):
 
 ```bash
-syntaur session save --session-id <sessionId> --from-file <body.md>
-# or pipe it:  printf '%s' "$BODY" | syntaur session save --session-id <sessionId>
+# Recommended: omit --session-id and let the CLI resolve YOUR own session id.
+printf '%s' "$BODY" | syntaur session save
+# or from a file:  syntaur session save --from-file <body.md>
+# Pass --session-id <id> only to override (e.g. you already have $CLAUDE_CODE_SESSION_ID).
 ```
 
 Resolves the active assignment from `.syntaur/context.json` (or pass
-`--assignment <slug> [--project <slug>]`), and `--session-id` defaults to the
-context's `sessionId`. The command:
+`--assignment <slug> [--project <slug>]`). `--session-id` now defaults to the
+**resolved** session (env → process tree → transcript), falling back to the
+`context.json` hint only as a last resort — so a co-tenant that clobbered the
+shared scalar can't make you write under the wrong id. The command:
 
 - Creates `<assignmentDir>/sessions/<sessionId>/` (idempotent) and writes
   `summary.md` — a **single document per session id**, overwritten in place;

package/platforms/claude-code/skills/track-session/SKILL.md

@@ -29,11 +29,12 @@ Extract optional flags from the argument string:
 
 ### Step 2: Source the real session id + transcript path
 
-In priority order:
+Resolve the session id from *your* running process, in priority order:
 
-1. Read `.syntaur/context.json` if present. If it contains `sessionId`, use it. Also pick up `transcriptPath` if present.
-2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
-3. If neither source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
+1. `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`) if your runtime injects it.
+2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/<pid>.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
+3. Only as a last resort, fall back to the `sessionId` scalar in `.syntaur/context.json` (and the companion `transcriptPath` if present). This scalar is a shared, legacy hint a co-tenant sharing this workspace can clobber — never treat it as authoritative.
+4. If no source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
 
 DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
 

package/platforms/codex/agents/syntaur-operator.md

@@ -133,7 +133,7 @@ Use these commands directly when needed:
 2. Update any missing checkboxes in `assignment.md`.
 3. Append a final timestamped entry to `progress.md` summarizing the work.
 4. Append a new structured handoff entry to `handoff.md`.
-5. Mark the dashboard session completed if `sessionId` exists.
+5. Mark the dashboard session completed. Resolve the session id from your running process (prefer `$CLAUDE_CODE_SESSION_ID` / the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`, otherwise `syntaur session resolve-id`); the `sessionId` scalar in `.syntaur/context.json` is only a clobberable legacy-hint fallback, not authoritative.
 6. Transition the assignment with `syntaur review` or `syntaur complete`.
 7. Remove `.syntaur/context.json` when the assignment is no longer active.
 

package/platforms/codex/commands/save-session-summary.md

@@ -16,7 +16,7 @@ Codex has no `PreCompact` hook event — invoke this command manually.
 
 Follow the `save-session-summary` skill in full. Summary:
 
-1. Read `.syntaur/context.json`. Required: `assignmentDir`, `sessionId`. If `sessionId` is missing, abort with: "Session not tracked. Run `syntaur track-session ...` first." Do not synthesize a session id.
+1. Read `.syntaur/context.json`. Required: `assignmentDir`. Do NOT read the session id from this file for identity — that scalar is a shared, legacy hint a co-tenant sharing this workspace can clobber. Resolve the session id from *your* running process: prefer `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`), otherwise omit `--session-id` and let `syntaur session save` resolve it (env → process tree → transcript, falling back to the context.json hint only as a last resort). Do not synthesize a session id.
 2. Create `<assignmentDir>/sessions/<sessionId>/` only at write time (avoid empty dirs).
 3. Write or overwrite `<assignmentDir>/sessions/<sessionId>/summary.md` with frontmatter (`assignment`, `sessionId`, `created`, `updated`) and body sections: `## Snapshot`, `## What Was Done`, `## What's Next`, `## Open Questions`, `## Load-Bearing Context`. Single document per session id — directory partitions by session.
 4. Do NOT modify `handoff.md`.

package/platforms/codex/scripts/session-cleanup.sh

@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 # Syntaur SessionEnd hook for Codex plugins.
-# Marks active agent sessions as stopped when a Codex session exits.
+# Marks the ENDING agent session as stopped when a Codex session exits.
+#
+# Identity rule: resolve the ending session's id EXACTLY, from a capture-at-birth
+# runtime marker stamped by a session-start/boundary hook (keyed by the Codex
+# process pid). We deliberately do NOT read .sessionId from context.json — that
+# shared scalar is clobbered when two sessions share a workspace, so trusting it
+# would mark the WRONG session stopped. Codex has no SessionStart hook and its
+# SessionEnd stdin carries no id, so when no exact marker resolves we SKIP the
+# PATCH and let the dashboard liveness reaper mark the dead session stopped.
 
 set -o pipefail 2>/dev/null || true
 
@@ -23,17 +31,66 @@ if [ ! -f "$CONTEXT_FILE" ]; then
   exit 0
 fi
 
-SESSION_ID=$(jq -r '.sessionId // empty' "$CONTEXT_FILE" 2>/dev/null)
+RUNTIME_DIR="${SYNTAUR_RUNTIME_SESSIONS_DIR:-$HOME/.syntaur/runtime/sessions}"
+
+# Walk the ancestor-pid chain reading runtime markers. Returns the nearest
+# marker's sessionId on stdout (and success), pid-reuse-guarded by procStart.
+resolve_session_from_markers() {
+  local pid="$PPID"
+  local depth=0
+  while [ "$depth" -lt 12 ]; do
+    case "$pid" in
+      '' | *[!0-9]*) break ;;
+    esac
+    [ "$pid" -le 1 ] && break
+    local marker="$RUNTIME_DIR/$pid.json"
+    if [ -f "$marker" ]; then
+      local sid procstart actual
+      sid=$(jq -r '.sessionId // empty' "$marker" 2>/dev/null)
+      procstart=$(jq -r '.procStart // empty' "$marker" 2>/dev/null)
+      if [ -n "$sid" ]; then
+        if [ -n "$procstart" ]; then
+          # Fail CLOSED: require a readable, exactly-matching live start time;
+          # if ps can't prove the pid wasn't recycled, skip this marker.
+          actual=$(ps -o lstart= -p "$pid" 2>/dev/null | sed 's/^ *//;s/ *$//')
+          if [ -n "$actual" ] && [ "$actual" = "$procstart" ]; then
+            printf '%s' "$sid"
+            return 0
+          fi
+          # else: cannot prove pid identity — skip this marker, keep walking
+        else
+          printf '%s' "$sid"
+          return 0
+        fi
+      fi
+    fi
+    pid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ')
+    depth=$((depth + 1))
+  done
+  return 1
+}
+
+SESSION_ID=$(resolve_session_from_markers || true)
 MISSION_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
 
-if [ -z "$SESSION_ID" ] || [ -z "$MISSION_SLUG" ]; then
-  exit 0
-fi
+# No EXACT id — do not risk stopping the wrong co-tenant session.
+[ -z "$SESSION_ID" ] && exit 0
+
+# Defensive: the id becomes a URL path segment — reject anything that isn't a
+# plain id (UUID/ULID charset). Real ids never trip this.
+case "$SESSION_ID" in
+  *[!A-Za-z0-9_-]*) exit 0 ;;
+esac
 
 PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
+if [ -n "$MISSION_SLUG" ]; then
+  BODY="{\"status\": \"stopped\", \"projectSlug\": \"${MISSION_SLUG}\"}"
+else
+  BODY="{\"status\": \"stopped\"}"
+fi
 curl -sf -X PATCH "http://localhost:${PORT}/api/agent-sessions/${SESSION_ID}/status" \
   -H "Content-Type: application/json" \
-  -d "{\"status\": \"stopped\", \"projectSlug\": \"${MISSION_SLUG}\"}" \
+  -d "$BODY" \
   -o /dev/null 2>/dev/null || true
 
 exit 0

package/platforms/codex/skills/clear-assignment/SKILL.md

@@ -90,7 +90,7 @@ Do not delete the `.syntaur/` directory itself — other tooling may use it.
 
 ## Step 5: Close Session (optional)
 
-If the original `context.json` included a `sessionId` and the Syntaur dashboard is running, mark the session as cleared so the dashboard does not keep showing it as active:
+If the Syntaur dashboard is running, mark this session as cleared so the dashboard does not keep showing it as active. Resolve `<session-id>` from *your* running process — prefer `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`), otherwise run `syntaur session resolve-id`. Only if neither yields an id, fall back to the `sessionId` you captured from the original `context.json` in Step 1 (before deletion) — that scalar is a shared, legacy hint a co-tenant can clobber, so don't treat it as authoritative:
 
 ```bash
 curl -s -X PATCH "http://localhost:$(cat ~/.syntaur/dashboard-port 2>/dev/null || echo 4800)/api/agent-sessions/<session-id>/status" \

package/platforms/codex/skills/complete-assignment/SKILL.md

@@ -101,7 +101,7 @@ Do NOT uncheck or rewrite superseded todo lines matching `- [x] ~~...~~ (superse
 
 ## Step 6: Close Session (optional)
 
-If `.syntaur/context.json` includes a `sessionId` and the Syntaur dashboard is running, mark the session as completed:
+If the Syntaur dashboard is running, mark this session as completed. Resolve `<session-id>` from *your* running process — prefer `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`), otherwise run `syntaur session resolve-id`; fall back to the `sessionId` scalar in `.syntaur/context.json` only as a last resort (it is a shared, legacy hint a co-tenant can clobber, not authoritative):
 
 ```bash
 curl -s -X PATCH "http://localhost:$(cat ~/.syntaur/dashboard-port 2>/dev/null || echo 4800)/api/agent-sessions/<session-id>/status" \

package/platforms/codex/skills/grab-assignment/SKILL.md

@@ -113,14 +113,15 @@ Use absolute paths (expand `~` to the home directory). If `workspace.repository`
 
 ## Step 6: Register Agent Session (real IDs only — no UUIDs)
 
-`syntaur track-session` requires a `--session-id` from the agent runtime. Synthetic UUIDs are rejected. Source the real id in this order:
+`syntaur track-session` requires a `--session-id` from the agent runtime. Synthetic UUIDs are rejected. Source the real per-process id in this order:
 
-1. If `.syntaur/context.json` already has `sessionId` (platform SessionStart hook populated it), use it and the companion `transcriptPath` if present.
+1. Prefer the env var your runtime injects: `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`).
 2. Otherwise, fall back to the per-agent lookup:
-   - **Claude Code**: the most-recently-modified `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` — read its `sessionId`. The transcript path is `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` (omit if the file is absent).
+   - **Claude Code**: the most-recently-modified `~/.claude/sessions/<pid>.json` whose `cwd` matches `$(pwd)` — read its `sessionId`. The transcript path is `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` (omit if the file is absent).
    - **Codex**: the most-recently-modified file under `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` whose first-line `session_meta.payload.cwd` matches `$(pwd)`. Use `payload.id` as the session id and the full rollout path as the transcript path.
    - **Other agents**: use whatever real session identifier the runtime exposes. Do not invent one.
-3. If no real id can be resolved, stop and tell the user to restart the session so the platform hook can populate it, or to run `/rename <assignment-slug>` (Claude Code) and retry.
+3. Only as a last resort, fall back to the `sessionId` scalar already in `.syntaur/context.json` (and the companion `transcriptPath` if present). That scalar is a shared, legacy hint a co-tenant sharing this workspace can clobber — never treat it as authoritative.
+4. If no real id can be resolved, stop and tell the user to restart the session so the platform hook can populate it, or to run `/rename <assignment-slug>` (Claude Code) and retry.
 
 After resolving, merge `sessionId` + `transcriptPath` back into context.json. Then register:
 

package/platforms/codex/skills/save-session-summary/SKILL.md

@@ -32,9 +32,14 @@ If the file does not exist, tell the user: "No active assignment found. Run `gra
 
 Extract:
 - `assignmentDir` (absolute path) — required.
-- `sessionId` — required, must be the real agent runtime session id.
 
-If `sessionId` is missing, empty, or `null`, abort with: "Session not tracked. Run `syntaur track-session ...` first." Do not invent or generate a session id.
+**Do not read the session id from `context.json` for identity.** That scalar is
+a shared, legacy hint a co-tenant can clobber. The session id is resolved from
+*your* running process — prefer, in order:
+1. `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`) if your runtime injects it.
+2. Otherwise omit `--session-id` entirely and let `syntaur session save` resolve it (it walks env → process tree → transcript, and falls back to the `context.json` hint only as a last resort).
+
+Never invent or generate a session id.
 
 ## Step 2: Author the summary body
 
@@ -75,13 +80,17 @@ Pass the body to `syntaur session save` (it owns the directory, frontmatter,
 and `created`-preservation):
 
 ```bash
-syntaur session save --session-id <sessionId> --from-file <body.md>
-# or pipe it:  printf '%s' "$BODY" | syntaur session save --session-id <sessionId>
+# Recommended: omit --session-id and let the CLI resolve YOUR own session id.
+printf '%s' "$BODY" | syntaur session save
+# or from a file:  syntaur session save --from-file <body.md>
+# Pass --session-id <id> only to override (e.g. you already have $CLAUDE_CODE_SESSION_ID).
 ```
 
 Resolves the active assignment from `.syntaur/context.json` (or pass
-`--assignment <slug> [--project <slug>]`), and `--session-id` defaults to the
-context's `sessionId`. The command:
+`--assignment <slug> [--project <slug>]`). `--session-id` now defaults to the
+**resolved** session (env → process tree → transcript), falling back to the
+`context.json` hint only as a last resort — so a co-tenant that clobbered the
+shared scalar can't make you write under the wrong id. The command:
 
 - Creates `<assignmentDir>/sessions/<sessionId>/` (idempotent) and writes
   `summary.md` — a **single document per session id**, overwritten in place;

package/platforms/codex/skills/track-session/SKILL.md

@@ -29,11 +29,12 @@ Extract optional flags from the argument string:
 
 ### Step 2: Source the real session id + transcript path
 
-In priority order:
+Resolve the session id from *your* running process, in priority order:
 
-1. Read `.syntaur/context.json` if present. If it contains `sessionId`, use it. Also pick up `transcriptPath` if present.
-2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
-3. If neither source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
+1. `$CLAUDE_CODE_SESSION_ID` (or the peer `OPENCODE_SESSION_ID` / `PI_SESSION_ID`) if your runtime injects it.
+2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/<pid>.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
+3. Only as a last resort, fall back to the `sessionId` scalar in `.syntaur/context.json` (and the companion `transcriptPath` if present). This scalar is a shared, legacy hint a co-tenant sharing this workspace can clobber — never treat it as authoritative.
+4. If no source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
 
 DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
 

package/platforms/cursor/hooks/README.md

@@ -0,0 +1,49 @@
+# Cursor session-id handshake (Reference Only)
+
+Cursor hooks deliver `conversation_id` on stdin but **cannot inject environment
+variables** into spawned commands (they can only allow/deny), and there is no
+`CURSOR_SESSION_ID` env (open feature request). So the env-var path (layer 2)
+is impossible for Cursor. Instead we use a per-invocation **nonce** — keying on
+a nonce, not cwd, is what keeps it co-tenant-safe.
+
+> **Status:** reference design. The resolver's layer-3 seam
+> (`resolveSideChannelSessionId` in `src/utils/session-id.ts`) is in place and
+> returns `undefined` today. The two pieces below complete the handshake.
+
+## The handshake
+
+1. **CLI emits a nonce in its own argv.** A `syntaur` invocation that needs to
+   self-identify passes e.g. `--session-nonce <random>` (the nonce travels in
+   the command line the Cursor hook can see).
+2. **`beforeShellExecution` hook records the mapping.** A shipped hook that
+   receives `conversation_id` on stdin and sees the spawned command's argv
+   extracts the nonce and writes:
+
+   ```
+   ~/.syntaur/runtime/cursor-nonces/<nonce>.json = { "sessionId": "<conversation_id>" }
+   ```
+
+   ```bash
+   #!/usr/bin/env bash
+   # beforeShellExecution — reference. Reads the hook payload on stdin.
+   payload=$(cat)
+   cid=$(printf '%s' "$payload" | jq -r '.conversation_id // empty')
+   cmd=$(printf '%s' "$payload" | jq -r '.command // .tool_input.command // empty')
+   nonce=$(printf '%s' "$cmd" | sed -n 's/.*--session-nonce \([A-Za-z0-9_-]\{8,\}\).*/\1/p')
+   if [ -n "$cid" ] && [ -n "$nonce" ]; then
+     dir="$HOME/.syntaur/runtime/cursor-nonces"
+     mkdir -p "$dir"
+     printf '{"sessionId":"%s"}' "$cid" > "$dir/$nonce.json"
+   fi
+   echo '{"permission":"allow"}'   # never block on this hook
+   ```
+
+3. **Resolver layer 3 reads its own nonce back.** When the CLI was invoked with
+   `--session-nonce <n>`, `resolveSideChannelSessionId` reads
+   `~/.syntaur/runtime/cursor-nonces/<n>.json` and returns its `sessionId`.
+
+## Verification (needs a live Cursor session — cannot run in CI)
+
+Run a `syntaur` command from a Cursor agent shell with `--session-nonce <n>`;
+confirm `~/.syntaur/runtime/cursor-nonces/<n>.json` is written with the right
+`conversation_id` and that the command attributes to it.

package/platforms/opencode/plugin/syntaur-session-env.js

@@ -0,0 +1,30 @@
+/**
+ * Syntaur OpenCode plugin — inject OPENCODE_SESSION_ID into every spawned
+ * command so `syntaur` (and any other tool) can resolve the caller's OWN
+ * session id from the process (layer 2 of resolveOwnSessionId), instead of the
+ * co-tenant-clobberable .syntaur/context.json scalar.
+ *
+ * REFERENCE ARTIFACT. Syntaur's current OpenCode integration is adapter-file
+ * only (see ../README.md); this is not yet auto-installed. To use:
+ *   1. Drop this file at `~/.config/opencode/plugin/syntaur-session-env.js`
+ *      (or your project's `.opencode/plugin/`).
+ *   2. Restart OpenCode.
+ *
+ * Verify (needs a live OpenCode build): from a tool call, `echo $OPENCODE_SESSION_ID`
+ * prints the conversation/session id.
+ *
+ * Caveat: the V2 `core` bash tool is not yet wired to `shell.env`
+ * (`// TODO` in packages/core/src/tool/bash.ts); the `opencode` ShellTool path
+ * is. Verify against your target OpenCode version. The hook signature below
+ * follows the @opencode-ai/plugin `shell.env` trigger — adjust if the API shifts.
+ */
+export const SyntaurSessionEnv = async () => ({
+  // Fired per spawn with the active session id; mutate the child env in place.
+  'shell.env': async ({ sessionID }, output) => {
+    if (sessionID && output && output.env) {
+      output.env.OPENCODE_SESSION_ID = sessionID;
+    }
+  },
+});
+
+export default SyntaurSessionEnv;