syntaur 0.34.0 → 0.35.0

package/platforms/pi/README.md

@@ -0,0 +1,50 @@
+# Pi Integration (Reference Only)
+
+Syntaur resolves the **real** agent session id from the running process, not the
+shared `.syntaur/context.json` scalar (a co-tenant clobbers it). For Pi, the job
+is to inject `PI_SESSION_ID` per spawn so the CLI's `resolveOwnSessionId` picks
+it up at layer 2. See `../SESSION-ID-RESOLUTION.md` for the full design.
+
+> **Status:** Syntaur already ships a Pi extension at
+> `extensions/syntaur/index.ts` (it tracks the dashboard session via
+> `ctx.sessionId`). That extension does **not** yet inject `PI_SESSION_ID` into
+> spawned commands — adding the `spawnHook` below to it is the remaining piece
+> so Pi commands self-identify to `resolveOwnSessionId` (layer 2). This file
+> documents that injector and its verification gate.
+
+## Injector — a `spawnHook` extension
+
+Pi extensions (`@earendil-works/pi-coding-agent`, see its `docs/extensions.md`)
+can capture the session id at `session_start` and inject env on every spawned
+command via a bash `spawnHook`:
+
+```js
+// syntaur-session-env extension (reference; verify against your Pi version)
+export default {
+  name: 'syntaur-session-env',
+  session_start(ctx) {
+    // Capture the real id once, at session start.
+    this.sessionId = ctx.sessionManager.getSessionId();
+  },
+  // Injected into the environment of every spawned shell command.
+  spawnHook() {
+    return this.sessionId ? { env: { PI_SESSION_ID: this.sessionId } } : {};
+  },
+};
+```
+
+Alternatively, if Pi's start hook exposes the process pid, stamp the generic
+marker `~/.syntaur/runtime/sessions/<pid>.json` (see `../SESSION-ID-RESOLUTION.md`)
+and the resolver's layer-4 ancestor walk will find it without env injection.
+
+## Verification (needs a live Pi build — cannot run in CI)
+
+From a Pi tool call:
+
+```bash
+echo "$PI_SESSION_ID"   # prints the real Pi session id
+```
+
+`PI_SESSION_ID` is already in the resolver's layer-2 precedence list
+(`src/utils/session-id.ts`), so once injected, `syntaur session save` (etc.)
+attribute to the correct session automatically.

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