syntaur 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {
@@ -29,7 +29,11 @@
     ".agents",
     "platforms",
     "examples",
-    "dashboard/dist"
+    "dashboard/dist",
+    "statusline",
+    "vendor/syntaur-skills/skills/**",
+    "vendor/syntaur-skills/LICENSE",
+    "vendor/syntaur-skills/README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -40,7 +44,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "prepack": "node scripts/verify-vendored-skills.mjs",
     "prepublishOnly": "npm run build && npm ci --prefix dashboard && npm run build --prefix dashboard",
+    "postinstall": "node scripts/postinstall-submodules.mjs",
     "try": "node scripts/try.mjs",
     "untry": "npm unlink -g syntaur && npm install -g syntaur@latest && echo '\\n✓ global syntaur restored to latest published version'"
   },

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

@@ -5,5 +5,5 @@
     "name": "Brennen",
     "email": ""
   },
-  "version": "0.1.7"
+  "version": "0.1.8"
 }

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

@@ -12,10 +12,12 @@ When answering questions, read the actual source files rather than relying solel
 
 ## Key Source Files
 
-- **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md`
+- **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md` (or `~/.claude/skills/syntaur-protocol/references/protocol-summary.md` for the installed skill version)
 - **File ownership:** `${CLAUDE_PLUGIN_ROOT}/references/file-ownership.md`
 - **Plugin manifest:** `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
-- **Skills:** `${CLAUDE_PLUGIN_ROOT}/skills/`
+- **Protocol skills (installed by `syntaur install-plugin`):** `~/.claude/skills/{syntaur-protocol,grab-assignment,plan-assignment,complete-assignment,create-assignment,create-project}/`
+- **Protocol skills source (vendored via submodule):** `<syntaur-repo>/vendor/syntaur-skills/skills/` — standalone repo at https://github.com/prong-horn/syntaur-skills
+- **Slash commands (ship in plugin):** `${CLAUDE_PLUGIN_ROOT}/commands/` — thin wrappers that invoke the corresponding installed skill
 - **Hooks:** `${CLAUDE_PLUGIN_ROOT}/hooks/`
 
 For the live CLI surface, run `syntaur --help` in the user environment.
@@ -191,7 +193,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.
 
@@ -204,27 +206,38 @@ The Syntaur Claude Code plugin is installed by `syntaur install-plugin`, which r
 ```
 plugin/
   .claude-plugin/
-    plugin.json              # Plugin metadata
+    plugin.json                         # Plugin metadata
   agents/
-    syntaur-expert.md        # This agent
-  skills/
-    syntaur-protocol/SKILL.md    # Core protocol rules (background)
-    grab-assignment/SKILL.md     # Claim a pending assignment
-    create-project/SKILL.md      # Create new project
-    create-assignment/SKILL.md   # Create new assignment
-    plan-assignment/SKILL.md     # Write implementation plan
-    complete-assignment/SKILL.md # Handoff and complete
+    syntaur-expert.md                   # This agent
   commands/
-    track-session/track-session.md  # Register tmux sessions
+    grab-assignment/grab-assignment.md         # Slash wrapper for grab-assignment skill
+    plan-assignment/plan-assignment.md         # Slash wrapper for plan-assignment skill
+    complete-assignment/complete-assignment.md # Slash wrapper for complete-assignment skill
+    create-assignment/create-assignment.md     # Slash wrapper for create-assignment skill
+    create-project/create-project.md           # Slash wrapper for create-project skill
+    track-session/track-session.md             # Claude-specific session registration
+    doctor-syntaur/...                         # Diagnose install
+    track-server/...                           # Register a running server
   hooks/
-    hooks.json                   # Hook definitions
-    session-cleanup.sh           # Mark sessions stopped on exit
-    enforce-boundaries.sh        # Write boundary enforcement
+    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/
-    protocol-summary.md          # One-page protocol quick reference
-    file-ownership.md            # Write boundary rules
+    protocol-summary.md         # One-page protocol quick reference
+    file-ownership.md           # Write boundary rules
+
+~/.claude/skills/               # Installed by `syntaur install-plugin` (vendored from syntaur-skills repo)
+  syntaur-protocol/SKILL.md     # Auto-activates on Syntaur file contexts
+  grab-assignment/SKILL.md
+  plan-assignment/SKILL.md
+  complete-assignment/SKILL.md
+  create-assignment/SKILL.md
+  create-project/SKILL.md
 ```
 
+Slash commands (`/grab-assignment` etc.) are thin wrappers that delegate to the installed skills. This lets the same protocol skills work in Claude Code (via slash command + auto-activation) and Codex (via auto-activation only).
+
 ### Skills Summary
 
 | Skill | Trigger | Purpose |
@@ -241,6 +254,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 +384,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 +395,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/complete-assignment/complete-assignment.md

@@ -0,0 +1,20 @@
+---
+name: complete-assignment
+description: Append a progress entry + handoff and transition the current Syntaur assignment to review or completed
+arguments:
+  - name: args
+    description: "Optional — see the complete-assignment skill for supported flags"
+    required: false
+---
+
+# /complete-assignment
+
+Thin wrapper that invokes the `complete-assignment` skill. The skill lives in `~/.claude/skills/complete-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — verifying acceptance criteria and todos, appending a progress.md entry, writing a handoff.md section, and calling `syntaur review` or `syntaur complete`.
+
+## Instructions
+
+Invoke the `complete-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/create-assignment/create-assignment.md

@@ -0,0 +1,20 @@
+---
+name: create-assignment
+description: Create a new Syntaur assignment (project-nested or standalone one-off)
+arguments:
+  - name: args
+    description: "Title and flags. See the create-assignment skill for supported forms (e.g. --project <slug>, --one-off, --type <type>)."
+    required: false
+---
+
+# /create-assignment
+
+Thin wrapper that invokes the `create-assignment` skill. The skill lives in `~/.claude/skills/create-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — picking project-nested or standalone, validating the type, scaffolding assignment.md / progress.md / comments.md.
+
+## Instructions
+
+Invoke the `create-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/create-project/create-project.md

@@ -0,0 +1,20 @@
+---
+name: create-project
+description: Create a new Syntaur project with full scaffolding
+arguments:
+  - name: args
+    description: "Title and optional flags (--slug, --dir, --workspace). See the create-project skill for full usage."
+    required: false
+---
+
+# /create-project
+
+Thin wrapper that invokes the `create-project` skill. The skill lives in `~/.claude/skills/create-project/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — calling `syntaur create-project`, reading the generated project.md, and guiding next steps.
+
+## Instructions
+
+Invoke the `create-project` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/grab-assignment/grab-assignment.md

@@ -0,0 +1,20 @@
+---
+name: grab-assignment
+description: Claim a Syntaur assignment and load it into the current working context
+arguments:
+  - name: args
+    description: "Project slug and optional assignment slug, or --id <uuid> for standalone. See the grab-assignment skill for full forms."
+    required: false
+---
+
+# /grab-assignment
+
+Thin wrapper that invokes the `grab-assignment` skill. The skill lives in `~/.claude/skills/grab-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — discovering pending assignments, merging `.syntaur/context.json`, registering the agent session, reading the assignment.
+
+## Instructions
+
+Invoke the `grab-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/plan-assignment/plan-assignment.md

@@ -0,0 +1,20 @@
+---
+name: plan-assignment
+description: Create a detailed implementation plan for the current Syntaur assignment
+arguments:
+  - name: args
+    description: "Optional — see the plan-assignment skill for supported flags"
+    required: false
+---
+
+# /plan-assignment
+
+Thin wrapper that invokes the `plan-assignment` skill. The skill lives in `~/.claude/skills/plan-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — picking the next `plan-v<N>.md`, writing it, appending a `## Todos` entry, marking any prior plan todo superseded, and recording key decisions in `decision-record.md`.
+
+## Instructions
+
+Invoke the `plan-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

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