syntaur 0.3.0 → 0.3.3

package/package.json

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

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

@@ -5,5 +5,9 @@
     "name": "Brennen",
     "email": ""
   },
-  "version": "0.1.7"
+  "version": "0.1.8",
+  "statusLine": {
+    "type": "command",
+    "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/statusline.sh"
+  }
 }

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

@@ -191,7 +191,7 @@ Only the assigned agent may write to its own assignment folder.
 ### Session Tracking
 | Command | Description |
 |---------|-------------|
-| `syntaur track-session --project M --assignment A --agent N` | Register agent session |
+| `syntaur track-session --project M --assignment A --agent N --session-id <real-id> --transcript-path <path>` | Register agent session. `--session-id` is required and must be the agent runtime's real id (Claude: `~/.claude/sessions/<pid>.json` or SessionStart hook payload; Codex: `payload.id` from `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`). Do not synthesize. |
 
 All commands support `--dir <path>` to override the default `~/.syntaur/projects/` directory.
 
@@ -218,6 +218,7 @@ plugin/
     track-session/track-session.md  # Register tmux sessions
   hooks/
     hooks.json                   # Hook definitions
+    session-start.sh             # Merge real session_id + transcript_path into existing .syntaur/context.json
     session-cleanup.sh           # Mark sessions stopped on exit
     enforce-boundaries.sh        # Write boundary enforcement
   references/
@@ -241,6 +242,7 @@ plugin/
 | Hook | Event | Behavior |
 |------|-------|----------|
 | PostToolUse: ExitPlanMode | User exits plan mode | Prompts to write the plan to the next unused `plan-v<N>.md` (or `plan.md` if none exists) and append a linked todo in the `## Todos` section of `assignment.md` |
+| SessionStart | Claude Code session starts | Runs session-start.sh to merge the real `session_id` + `transcript_path` into an EXISTING `.syntaur/context.json`. Does nothing if context.json is absent (no active assignment). |
 | SessionEnd | Claude Code session exits | Runs session-cleanup.sh to mark session as stopped |
 | PreToolUse: enforce-boundaries | Edit/Write/MultiEdit | Validates target path is within assignment boundaries |
 
@@ -370,7 +372,7 @@ syntaur dashboard
 
 ## Context File (.syntaur/context.json)
 
-Created by `/grab-assignment` in the current working directory. Contains:
+Created by `/grab-assignment` in the current working directory. The SessionStart hook merges `sessionId` / `transcriptPath` into this file on each Claude Code session start — it never creates the file, only enriches an existing one. Contents:
 ```json
 {
   "projectSlug": "my-first-project",
@@ -381,7 +383,8 @@ Created by `/grab-assignment` in the current working directory. Contains:
   "title": "Design the schema",
   "branch": "feature/design-the-schema",
   "grabbedAt": "2026-03-18T14:30:00Z",
-  "sessionId": "uuid-v4"
+  "sessionId": "<real-claude-session-id>",
+  "transcriptPath": "/Users/you/.claude/projects/<encoded-cwd>/<session-id>.jsonl"
 }
 ```
 

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

@@ -11,6 +11,8 @@ arguments:
 
 Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
 
+Only real Claude Code session IDs are accepted — no synthesis. The real id is written to `.syntaur/context.json` by the SessionStart hook, with `~/.claude/sessions/<pid>.json` as the fallback source.
+
 ## Usage
 
 - `/track-session` — register a standalone session
@@ -29,37 +31,60 @@ Extract optional flags from the argument string:
 - `--project <slug>` — project to link to
 - `--assignment <slug>` — assignment to link to
 
-### Step 2: Run the CLI command
+### Step 2: Source the real session id + transcript path
+
+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."
+
+DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
 
-Run the track-session CLI command via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+### Step 3: Run the CLI command
+
+Run the track-session CLI via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
 
 ```bash
-syntaur track-session --agent claude --path $(pwd) [--description "<text>"] [--project <slug>] [--assignment <slug>]
+syntaur track-session \
+  --agent claude \
+  --session-id "$SESSION_ID" \
+  --transcript-path "$TRANSCRIPT_PATH" \
+  --path "$(pwd)" \
+  [--description "<text>"] \
+  [--project <slug>] \
+  [--assignment <slug>]
 ```
 
-### Step 3: Parse the session ID
+Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
 
-The CLI output will be one of:
+The CLI prints one of:
 - `Registered standalone agent session <sessionId>.`
 - `Registered agent session <sessionId> for <assignment> in <project>.`
 
-Extract the session ID from the output.
+Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
 
-### Step 4: Write context file
+### Step 4: Merge context.json
 
-Write the session ID to `.syntaur/context.json` so the SessionEnd hook can mark it stopped when this conversation ends:
+Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `/track-session` runs find them). Merge, don't overwrite:
 
-- If `.syntaur/context.json` already exists, read it and add `"sessionId": "<id>"` to the existing JSON
-- If it doesn't exist, create the `.syntaur/` directory and write:
-  ```json
-  {
-    "sessionId": "<id>"
-  }
-  ```
+```bash
+mkdir -p .syntaur
+if [ -f .syntaur/context.json ]; then
+  jq --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '. + {sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  jq -n --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '{sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    > .syntaur/context.json
+fi
+```
 
 ### Step 5: Confirm
 
 Tell the user:
-- The session was registered (include the short session ID)
-- It will be auto-stopped when this conversation ends
-- If linked to a project, mention which project/assignment
+- The session was registered (include the short session id).
+- It will be auto-stopped when this conversation ends via the SessionEnd hook.
+- If linked to a project, mention which project/assignment.

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

@@ -12,6 +12,17 @@
         ]
       }
     ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

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

@@ -34,39 +34,29 @@ 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)
 
-PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
-
-# --- Step 5: If no session was registered, try to auto-register (requires project+assignment) ---
+# Fall back to the SessionEnd stdin payload if context.json didn't have the id.
+# Claude Code passes session_id on stdin for SessionEnd.
 if [ -z "$SESSION_ID" ]; then
-  # Can only auto-register if we have project and assignment context
-  if [ -z "$MISSION_SLUG" ] || [ -z "$ASSIGNMENT_SLUG" ]; then
-    exit 0
-  fi
-
-  # Generate a session ID for the log entry
-  SESSION_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo "ses-$(date +%s)")
-  # Lowercase the UUID (uuidgen on macOS outputs uppercase)
-  SESSION_ID=$(echo "$SESSION_ID" | tr '[:upper:]' '[:lower:]')
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+fi
 
-  RESPONSE=$(curl -sf -X POST "http://localhost:${PORT}/api/agent-sessions" \
-    -H "Content-Type: application/json" \
-    -d "{\"projectSlug\": \"${MISSION_SLUG}\", \"assignmentSlug\": \"${ASSIGNMENT_SLUG}\", \"agent\": \"claude\", \"sessionId\": \"${SESSION_ID}\", \"path\": \"${CWD}\"}" \
-    2>/dev/null) || true
+# No real session id available — exit quietly. We never synthesize one.
+[ -z "$SESSION_ID" ] && exit 0
 
-  # If registration succeeded, update the context file with the session ID
-  if [ -n "$RESPONSE" ]; then
-    jq --arg sid "$SESSION_ID" '. + {sessionId: $sid}' "$CONTEXT_FILE" > "${CONTEXT_FILE}.tmp" 2>/dev/null \
-      && mv "${CONTEXT_FILE}.tmp" "$CONTEXT_FILE" 2>/dev/null || true
-  fi
+# --- Dashboard endpoint resolution (mirror session-start.sh exactly so start
+# and end hooks always target the same host:port) ---
+PORT="${SYNTAUR_DASHBOARD_PORT:-}"
+if [ -z "$PORT" ]; then
+  PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
 fi
 
-# --- Step 6: Mark session as stopped via dashboard API ---
+# --- Step 5: Mark session as stopped via dashboard API ---
 BODY="{\"status\": \"stopped\"}"
 if [ -n "$MISSION_SLUG" ]; then
   BODY="{\"status\": \"stopped\", \"projectSlug\": \"${MISSION_SLUG}\"}"
 fi
 
-curl -sf -X PATCH "http://localhost:${PORT}/api/agent-sessions/${SESSION_ID}/status" \
+curl -sf --max-time 3 -X PATCH "http://127.0.0.1:${PORT}/api/agent-sessions/${SESSION_ID}/status" \
   -H "Content-Type: application/json" \
   -d "$BODY" \
   -o /dev/null 2>/dev/null || true

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Syntaur SessionStart Hook
+# (1) Merges the real Claude Code session_id + transcript_path into an
+#     EXISTING .syntaur/context.json. Never creates context.json — that would
+#     break grab-assignment's "context.json implies active assignment" semantic.
+# (2) Pre-registers a minimal row in the dashboard sessions table so
+#     SessionEnd's PATCH /status always has a row to target. Best-effort —
+#     silently ignores dashboard-unreachable.
+#
+# Reads JSON from stdin per Claude Code SessionStart contract:
+#   { "session_id": "...", "transcript_path": "...", "cwd": "...", ... }
+#
+# Always exits 0.
+
+set -o pipefail 2>/dev/null || true
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+
+[ -z "$SESSION_ID" ] && exit 0
+[ -z "$CWD" ] && exit 0
+
+CONTEXT_FILE="$CWD/.syntaur/context.json"
+
+# REQUIRED invariant: only operate on an EXISTING context file. If the current
+# cwd has no active Syntaur assignment, leave the filesystem untouched.
+[ ! -f "$CONTEXT_FILE" ] && exit 0
+
+# --- (1) Merge session fields into context.json.
+# Always replace both sessionId and transcriptPath together. If the incoming
+# transcript_path is empty, explicitly null the stored transcriptPath so a new
+# session never inherits a stale transcript path from the prior session.
+TMP="${CONTEXT_FILE}.tmp.$$"
+jq \
+  --arg sid "$SESSION_ID" \
+  --arg tp "$TRANSCRIPT_PATH" \
+  '. + {sessionId: $sid, transcriptPath: (if ($tp | length) > 0 then $tp else null end)}' \
+  "$CONTEXT_FILE" > "$TMP" 2>/dev/null \
+  && mv "$TMP" "$CONTEXT_FILE" 2>/dev/null \
+  || rm -f "$TMP"
+
+# --- (2) Best-effort pre-registration in the dashboard.
+# Read project/assignment context if present so the pre-registered row is
+# already linked. Upsert semantics on the server mean this is idempotent with
+# later /track-session or grab-assignment calls.
+MISSION_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+
+PORT="${SYNTAUR_DASHBOARD_PORT:-}"
+if [ -z "$PORT" ]; then
+  PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
+fi
+
+BODY=$(jq -cn \
+  --arg sid "$SESSION_ID" \
+  --arg tp "$TRANSCRIPT_PATH" \
+  --arg proj "$MISSION_SLUG" \
+  --arg assn "$ASSIGNMENT_SLUG" \
+  --arg path "$CWD" \
+  '{ agent: "claude", sessionId: $sid, path: $path }
+   + (if ($tp   | length) > 0 then {transcriptPath: $tp}    else {} end)
+   + (if ($proj | length) > 0 then {projectSlug: $proj}     else {} end)
+   + (if ($assn | length) > 0 then {assignmentSlug: $assn}  else {} end)' 2>/dev/null)
+
+if [ -n "$BODY" ]; then
+  # --max-time bounds the hook's wall-clock cost if the dashboard socket
+  # accepts but then hangs. The hook itself is registered with timeout: 5.
+  curl -sf --max-time 3 -X POST "http://127.0.0.1:${PORT}/api/agent-sessions" \
+    -H "Content-Type: application/json" \
+    -d "$BODY" \
+    -o /dev/null 2>/dev/null || true
+fi
+
+exit 0

package/platforms/claude-code/hooks/statusline.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Syntaur Claude Code statusLine.
+#
+# Renders a single line with:
+#   <branch> · <worktree-basename> · <assignment> · <sessionId-suffix>
+#
+# Reads JSON from stdin per Claude Code statusLine contract:
+#   { "session_id": "...", "cwd": "...", "workspace": { "current_dir": "..." }, ... }
+#
+# Empty segments are omitted. Never fails the terminal — always exits 0.
+
+set -o pipefail 2>/dev/null || true
+
+INPUT=$(cat)
+
+# Degrade cleanly if jq is unavailable.
+if ! command -v jq >/dev/null 2>&1; then
+  printf '%s' '(syntaur: jq missing)'
+  exit 0
+fi
+
+SESSION_ID=""
+CWD=""
+
+if [ -n "$INPUT" ]; then
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+  CWD=$(printf '%s' "$INPUT" | jq -r '.workspace.current_dir // .cwd // empty' 2>/dev/null)
+fi
+
+# Fall back to the shell's CWD if the payload omits it.
+[ -z "$CWD" ] && CWD="$PWD"
+
+# --- Segment 1: branch ---
+BRANCH=""
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+  BRANCH=$(git -C "$CWD" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  if [ "$BRANCH" = "HEAD" ] || [ -z "$BRANCH" ]; then
+    SHORT=$(git -C "$CWD" rev-parse --short HEAD 2>/dev/null)
+    if [ -n "$SHORT" ]; then
+      BRANCH="detached@$SHORT"
+    else
+      BRANCH=""
+    fi
+  fi
+fi
+
+# --- Segment 2: worktree basename ---
+WORKTREE=""
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+  WT_PATH=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null)
+  if [ -n "$WT_PATH" ]; then
+    WORKTREE=$(basename "$WT_PATH")
+  fi
+fi
+
+# --- Segment 3: active syntaur assignment ---
+ASSIGNMENT=""
+CONTEXT_FILE="$CWD/.syntaur/context.json"
+if [ -f "$CONTEXT_FILE" ]; then
+  PROJECT_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+  ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+  ASSIGNMENT_DIR=$(jq -r '.assignmentDir // empty' "$CONTEXT_FILE" 2>/dev/null)
+
+  TITLE=""
+  if [ -n "$ASSIGNMENT_DIR" ] && [ -f "$ASSIGNMENT_DIR/assignment.md" ]; then
+    TITLE=$(awk '/^title:/{sub(/^title:[[:space:]]*"?/,""); sub(/"?[[:space:]]*$/,""); print; exit}' "$ASSIGNMENT_DIR/assignment.md" 2>/dev/null)
+  fi
+
+  LABEL=""
+  if [ -n "$PROJECT_SLUG" ] && [ -n "$ASSIGNMENT_SLUG" ]; then
+    LABEL="$PROJECT_SLUG/$ASSIGNMENT_SLUG"
+  elif [ -n "$ASSIGNMENT_SLUG" ]; then
+    # Standalone assignment — assignmentSlug is the UUID folder name. Take the
+    # first 8 chars for terseness.
+    UUID_PREFIX="${ASSIGNMENT_SLUG:0:8}"
+    LABEL="standalone/$UUID_PREFIX"
+  fi
+
+  if [ -n "$LABEL" ] && [ -n "$TITLE" ]; then
+    ASSIGNMENT="$LABEL — $TITLE"
+  elif [ -n "$LABEL" ]; then
+    ASSIGNMENT="$LABEL"
+  fi
+fi
+
+# --- Segment 4: session id suffix ---
+SESSION_SUFFIX=""
+if [ -n "$SESSION_ID" ]; then
+  LEN=${#SESSION_ID}
+  if [ "$LEN" -gt 8 ]; then
+    SESSION_SUFFIX="…${SESSION_ID: -8}"
+  else
+    SESSION_SUFFIX="$SESSION_ID"
+  fi
+fi
+
+# --- Join segments with ' · ', suppressing empties. ---
+OUT=""
+for seg in "$BRANCH" "$WORKTREE" "$ASSIGNMENT" "$SESSION_SUFFIX"; do
+  if [ -n "$seg" ]; then
+    if [ -z "$OUT" ]; then
+      OUT="$seg"
+    else
+      OUT="$OUT · $seg"
+    fi
+  fi
+done
+
+printf '%s' "$OUT"
+exit 0

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

@@ -27,8 +27,9 @@ Parse the arguments:
 ## Pre-flight Check
 
 1. Check if `.syntaur/context.json` already exists in the current working directory.
-   - If it exists, read it and warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new assignment will replace this context. Proceed?"
+   - If it exists AND contains BOTH `projectSlug` and `assignmentSlug`, read it and warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new assignment will replace this context. Proceed?"
    - If the user says no, stop.
+   - If the file exists but only has session fields (`sessionId`, `transcriptPath`) and no project/assignment, do NOT warn — that context was populated by the SessionStart hook and is not an "active assignment" marker. Proceed silently and merge new assignment fields in Step 5.
 
 ## Step 1: Discover the Project
 
@@ -113,15 +114,17 @@ workspace:
   worktreePath: /absolute/path/to/cwd
 ```
 
-## Step 5: Create Context File
+## Step 5: Create or Merge Context File
 
-Write `.syntaur/context.json` in the current working directory with the assignment context. First ensure the directory exists:
+Merge assignment context into `.syntaur/context.json`. Do NOT overwrite: if the file already exists (e.g., the SessionStart hook populated `sessionId` + `transcriptPath`), preserve those fields.
+
+First ensure the directory exists:
 
 ```bash
 mkdir -p .syntaur
 ```
 
-Then write the JSON file with this structure:
+Prepare the assignment payload:
 
 ```json
 {
@@ -136,26 +139,38 @@ Then write the JSON file with this structure:
 }
 ```
 
+Merge it on top of whatever context.json already contains:
+
+```bash
+if [ -f .syntaur/context.json ]; then
+  jq --slurpfile new <(echo "$NEW_CONTEXT_JSON") '. + $new[0]' .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  echo "$NEW_CONTEXT_JSON" > .syntaur/context.json
+fi
+```
+
+This preserves any `sessionId` / `transcriptPath` the SessionStart hook wrote, while layering assignment fields on top.
+
 Use absolute paths (expand `~` to the actual home directory). Note: `workspace.repository` may be a remote URL (e.g., `https://github.com/...`) -- only use it as `workspaceRoot` if it starts with `/` (local path). If it is a URL, set `workspaceRoot` to the current working directory.
 
 **IMPORTANT:** The `workspaceRoot` must NEVER be null when the agent will be writing code. If no workspace was configured, default to the current working directory.
 
 ## Step 5.5: Register Agent Session
 
-After creating the context file, register this session in the project's agent session log so it appears in the dashboard.
+After merging context, register this session in the dashboard.
 
-1. Find the current Claude Code session ID by reading from `~/.claude/sessions/`. These are JSON files keyed by PID containing `sessionId`, `cwd`, etc. Find the most recently modified file whose `cwd` matches the current working directory:
-```bash
-ls -t ~/.claude/sessions/*.json | head -5
-```
-Read the most recent file(s) and find the one whose `cwd` matches `$(pwd)`. Extract the `sessionId` field — this is the real Claude Code session ID that can be used with `claude --resume <sessionId>` to resume this exact conversation.
+1. **Source the real Claude session_id + transcript_path.** In priority order:
+   1. If `.syntaur/context.json` already has `sessionId` (SessionStart hook populated it), use that ID and read `transcriptPath` from the same file.
+   2. Otherwise, fall back to `~/.claude/sessions/*.json`: `ls -t ~/.claude/sessions/*.json | head -5`, read each, and pick the most recently modified entry whose `cwd` matches `$(pwd)`. Extract `sessionId`. The transcript path for Claude Code lives at `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` — construct that path if you need it.
+   3. If neither source yields a real ID, DO NOT synthesize one. 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 <assignment-slug>` and retry."
 
-If you cannot find a matching session file (e.g., no file matches the cwd, or the sessions directory is empty), ask the user to run `/rename <assignment-slug>` to name the current session after the assignment. Then store the assignment slug as the session name in context.json (`"sessionName": "<assignment-slug>"`) instead of `sessionId`. The user can later resume with `claude --resume <assignment-slug>`.
+2. **Merge `sessionId` and `transcriptPath` back into context.json** (safe even if already present — jq merge is idempotent).
 
-2. Run the track-session command (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
-```bash
-syntaur track-session --project <projectSlug> --assignment <assignmentSlug> --agent claude --session-id <claude-session-id> --path $(pwd)
-```
+3. **Run the track-session CLI** (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`). Both `--session-id` and real path are required:
+   ```bash
+   syntaur track-session --project <projectSlug> --assignment <assignmentSlug> --agent claude --session-id <real-session-id> --transcript-path <transcript-path> --path $(pwd)
+   ```
 
 3. Update the `.syntaur/context.json` context file to include the session ID. Add `"sessionId": "<claude-session-id>"` to the JSON object you wrote in Step 5.
 

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

@@ -46,13 +46,20 @@ For each file found, read it and follow its directives. Playbooks may contain ru
 
 Read the following files to understand the assignment:
 
-1. Read `<assignmentDir>/assignment.md` -- extract the objective, acceptance criteria, context section, and any Q&A
-2. Read `<projectDir>/agent.md` -- extract conventions and boundaries
-3. Read `<projectDir>/claude.md` if it exists -- extract Claude-specific instructions
-4. Read `<projectDir>/project.md` -- extract the project goal for broader context
-
-If the assignment has dependencies (`dependsOn` in frontmatter), read the handoff.md from each dependency's assignment folder for integration context:
+1. Read `<assignmentDir>/assignment.md` -- extract the objective, acceptance criteria, context section, and the `## Todos` list
+2. Read `<assignmentDir>/comments.md` if it exists -- inherited questions, notes, and feedback
+3. Read `<projectDir>/project.md` -- extract the project goal for broader context
+4. Read `<projectDir>/manifest.md` -- navigation index for the project
+
+Per-project `agent.md` and `claude.md` were removed in v0.2.0. The agent-level
+conventions now live in the repo root `CLAUDE.md` / `AGENTS.md` and in
+`~/.syntaur/playbooks/`, which Step 1.5 already loaded.
+
+If the assignment has dependencies (`dependsOn` in frontmatter), read each
+dependency's `handoff.md` and `decision-record.md` for integration context and
+upstream decisions:
 - `<projectDir>/assignments/<dep-slug>/handoff.md`
+- `<projectDir>/assignments/<dep-slug>/decision-record.md`
 
 ## Step 3: Explore Workspace (if set)
 
@@ -144,5 +151,6 @@ After writing the plan:
 
 **Remind the agent about recordkeeping during implementation:**
 - Check off acceptance criteria in `assignment.md` as each one is completed, not in a batch at the end
-- Update the `## Progress` section in `assignment.md` after each meaningful milestone
-- The assignment file is a live document — it should reflect current state at all times
+- Append timestamped milestones to `progress.md` (separate append-only file) — not to `assignment.md`
+- Use `syntaur comment <slug-or-uuid> "body" --type note|question|feedback` to add a comment to `comments.md`
+- `assignment.md` is a live document — keep its status, todos, and acceptance checkboxes reflecting current state at all times

package/platforms/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Run Syntaur project and assignment workflows from Codex, including claiming work, planning, completing handoffs, session tracking, and write-boundary enforcement.",
   "author": {
     "name": "Brennen"

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

@@ -93,7 +93,7 @@ Use these commands directly when needed:
 - `syntaur comment <assignment-slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>] [--project <slug>]` — append to `comments.md`
 - `syntaur request <target-slug-or-uuid> "text" [--from <source>] [--project <slug>]` — append to target's `## Todos`, annotated `(from: <source>)`
 - `syntaur uninstall [--all] [--yes]`
-- `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <id> --path <cwd>`
+- `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <real-id> --transcript-path <rollout-path> --path <cwd>` (both `--session-id` and `--transcript-path` must come from the matching Codex rollout file — never synthesize)
 - `syntaur setup-adapter codex --project <project-slug> --assignment <assignment-slug>`
 
 ## Standard Workflows
@@ -103,9 +103,11 @@ Use these commands directly when needed:
 1. Discover the project and pending assignments.
 2. Run `syntaur assign ... --agent codex`.
 3. Run `syntaur start ...`.
-4. Create `.syntaur/context.json` in the working directory.
-5. Register the session with `syntaur track-session`.
-6. If needed, run `syntaur setup-adapter codex --project <slug> --assignment <slug>`.
+4. Create (or merge into) `.syntaur/context.json` in the working directory. If a prior context file exists, preserve its fields.
+5. Resolve the real Codex session id and rollout path: `bash ./scripts/resolve-session.sh "$(pwd)"` (relative to the plugin root). Parse `session_id=<id>` and `transcript_path=<abs path>`. If the helper exits non-zero, there is no matching Codex rollout in this cwd — start the Codex session first, then retry. Never `uuidgen`.
+6. Merge `sessionId` + `transcriptPath` into `.syntaur/context.json`.
+7. Register the session: `syntaur track-session --project <slug> --assignment <slug> --agent codex --session-id <id> --transcript-path <path> --path "$(pwd)"`.
+8. If needed, run `syntaur setup-adapter codex --project <slug> --assignment <slug>`.
 
 ### Plan an assignment
 

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Syntaur Codex resolve-session helper
+# Finds the most-recent Codex rollout file whose session_meta.payload.cwd
+# matches $1 (default $PWD) and emits two lines to stdout:
+#   session_id=<id>
+#   transcript_path=<absolute path>
+# Exits non-zero with nothing on stdout if no match.
+#
+# Override the search root via CODEX_SESSIONS_DIR (default: $HOME/.codex/sessions).
+# Known limitation: if multiple concurrent Codex sessions share the same cwd,
+# this picks the newest-by-mtime. Users can bypass by passing --session-id and
+# --transcript-path explicitly to `syntaur track-session`.
+
+set -o pipefail 2>/dev/null || true
+
+command -v jq >/dev/null 2>&1 || { exit 1; }
+
+TARGET_CWD="${1:-$PWD}"
+SESSIONS_ROOT="${CODEX_SESSIONS_DIR:-$HOME/.codex/sessions}"
+
+shopt -s nullglob 2>/dev/null || true
+
+# Expand the glob explicitly via bash. If no files match, `files` stays empty
+# and we exit without invoking ls — guards against `ls -1t` falling back to
+# listing the current directory when the glob strips to zero operands.
+files=("$SESSIONS_ROOT"/*/*/*/rollout-*.jsonl)
+[ "${#files[@]}" -eq 0 ] && exit 1
+
+MATCHED_FILE=""
+MATCHED_ID=""
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  FIRST=$(head -n 1 "$f" 2>/dev/null)
+  [ -z "$FIRST" ] && continue
+  SESSION_CWD=$(printf '%s' "$FIRST" | jq -r 'select(.type=="session_meta") | .payload.cwd // empty' 2>/dev/null)
+  SESSION_ID=$(printf '%s' "$FIRST" | jq -r 'select(.type=="session_meta") | .payload.id // empty' 2>/dev/null)
+  if [ "$SESSION_CWD" = "$TARGET_CWD" ] && [ -n "$SESSION_ID" ]; then
+    MATCHED_FILE="$f"
+    MATCHED_ID="$SESSION_ID"
+    break
+  fi
+done < <(ls -1t "${files[@]}" 2>/dev/null)
+
+[ -z "$MATCHED_FILE" ] && exit 1
+
+printf 'session_id=%s\n' "$MATCHED_ID"
+printf 'transcript_path=%s\n' "$MATCHED_FILE"
+exit 0