syntaur 0.45.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.45.0",
+  "version": "0.47.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

@@ -18,6 +18,32 @@ Each agent's job is only to make its real id reachable by layer 2, 3, or 4 — i
 to **normalize the key**, never to synthesize an id. Per-agent status and the
 exact injector below.
 
+## Session TRACKING vs id resolution (scanner is the universal floor)
+
+Id resolution (above) answers "what is MY session id, right now, in-process."
+Session **tracking** — every session eventually appearing in the sessions DB —
+no longer depends on it:
+
+- **Floor — filesystem scanner** (`syntaur session scan`,
+  `src/sessions/scanner.ts`): walks each registry target's `sessions` descriptor
+  (`AgentTarget.sessions` in `src/targets/registry.ts`; claude + codex today),
+  upserts every discovered session with its real transcript timestamps, links
+  project/assignment from `<cwd>/.syntaur/context.json`, derives liveness
+  (lsof transcript-open, else mtime freshness), and sweeps stale `active` rows
+  to `stopped` (`ended` backdated to last mtime). Runs on the dashboard's
+  autodiscovery interval (and at start) plus standalone via the CLI. This is
+  **Codex's only tracking path** (no SessionStart hook) and the retroactive
+  backfill for everything.
+- **Fast path — hooks**: Claude's SessionStart/SessionEnd hooks are thin
+  wrappers over `syntaur session register|stop --from-hook` (direct DB writes,
+  zero tokens, no dashboard needed). Every session registers — standalone ones
+  included.
+- **Birth path — launcher**: `executeLaunchPlan` writes a runtime marker for
+  any agent it spawns (pending — no sessionId — for fresh/fork; with the id for
+  resume-mode, plus an immediate DB row).
+- Config: `session.autoTrack: all | workspaces-only | off` in
+  `~/.syntaur/config.md` (default `all`) gates all three paths.
+
 ## Generic runtime marker (layer 4)
 
 Any agent whose start/early hook learns the real id but cannot inject env can
@@ -33,6 +59,11 @@ stamp a marker that both the resolver and the Codex cleanup hook read:
 Helpers: `writeRuntimeMarker` / `readRuntimeMarker` in `src/utils/session-id.ts`.
 Override the dir in tests/hooks via `$SYNTAUR_RUNTIME_SESSIONS_DIR`.
 
+The launch path also writes **pending** markers (no `sessionId`) at spawn time
+for fresh/fork launches — ids are never synthesized. `readRuntimeMarker`
+rejects pending markers, so they never resolve an id until backfilled; the
+scanner registers those sessions from their transcripts instead.
+
 ---
 
 ## Claude Code — EXACT (shipped, no new runtime code)
@@ -40,8 +71,10 @@ Override the dir in tests/hooks via `$SYNTAUR_RUNTIME_SESSIONS_DIR`.
 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.**
+resolve to the same id. The SessionStart hook (now a thin wrapper over
+`syntaur session register --from-hook`) registers EVERY session directly in the
+DB and 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)
 
@@ -109,9 +142,13 @@ id on an existing hook's stdin. If/when it does, an early hook can
 Codex cleanup hook will resolve it exactly.
 
 **Honest floor today:**
+- The **session scanner** is Codex's tracking path: its `sessions` descriptor
+  walks `~/.codex/sessions/**/rollout-*.jsonl` and registers every session with
+  real timestamps — no hook required.
 - `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.
+  from an exact runtime marker and otherwise **skips** (the scanner's sweep
+  marks the dead session stopped on its next tick). 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/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
     "name": "Brennen",
     "email": ""
   },
-  "version": "0.45.0",
+  "version": "0.47.0",
   "skills": [
     "./skills/syntaur-protocol",
     "./skills/grab-assignment",

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

@@ -1,72 +1,33 @@
 #!/usr/bin/env bash
-# Syntaur SessionEnd Hook
-# Logs and marks agent sessions as "stopped" when a Claude Code session exits.
-# If the session was never registered but has an active assignment, registers it first.
-# Reads JSON from stdin, always exits 0.
+# Syntaur SessionEnd Hook — thin wrapper around `syntaur session stop`.
+# The CLI resolves the ENDING session's id (stdin .session_id first, the shared
+# context.json scalar only as a fallback) and marks the row stopped with a
+# direct DB write. No dashboard required. Reads JSON from stdin, always exits 0.
 
-# --- Safety: never fail ---
 set -o pipefail 2>/dev/null || true
 
-# --- Step 1: Check for jq ---
-if ! command -v jq &>/dev/null; then
-  exit 0
-fi
+command -v jq >/dev/null 2>&1 || exit 0
 
-# --- Step 2: Read stdin ---
 INPUT=$(cat)
-if [ -z "$INPUT" ]; then
-  exit 0
-fi
-
-# --- Step 3: Find context file ---
-CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
-if [ -z "$CWD" ]; then
-  exit 0
-fi
-
-CONTEXT_FILE="$CWD/.syntaur/context.json"
-if [ ! -f "$CONTEXT_FILE" ]; then
-  exit 0
-fi
-
-# --- 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=$(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:-}"
-if [ -z "$PORT" ]; then
-  PORT=$(cat "$HOME/.syntaur/dashboard-port" 2>/dev/null || echo "4800")
-fi
-
-# --- 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 --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
+[ -z "$INPUT" ] && exit 0
+
+command -v syntaur >/dev/null 2>&1 || exit 0
+
+# Bounded SIGKILL watchdog (portable — no `timeout` on stock macOS). ~4s stays
+# under the hook's `timeout: 5` budget. A stale CLI without the subcommand
+# exits non-zero — swallowed; the scanner sweeps the row on its next tick.
+syntaur_bounded_stop() {
+  local cpid kpid rc
+  printf '%s' "$INPUT" | syntaur session stop --from-hook >/dev/null 2>&1 &
+  cpid=$!
+  ( sleep 4; kill -KILL "$cpid" 2>/dev/null ) >/dev/null 2>&1 &
+  kpid=$!
+  wait "$cpid" 2>/dev/null
+  rc=$?
+  kill -KILL "$kpid" 2>/dev/null
+  wait "$kpid" 2>/dev/null
+  return "$rc"
+}
+syntaur_bounded_stop || true
 
 exit 0

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

@@ -1,11 +1,11 @@
 #!/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.
+# Syntaur SessionStart Hook — thin wrapper around `syntaur session register`.
+#
+# Registers EVERY session (standalone sessions included — no context.json
+# required). The CLI does the deterministic work: parses the stdin payload,
+# merges session fields into an EXISTING .syntaur/context.json (never creates
+# one), and writes the session row directly to the sessions DB. No dashboard
+# required.
 #
 # Reads JSON from stdin per Claude Code SessionStart contract:
 #   { "session_id": "...", "transcript_path": "...", "cwd": "...", ... }
@@ -19,20 +19,26 @@ command -v jq >/dev/null 2>&1 || exit 0
 INPUT=$(cat)
 [ -z "$INPUT" ] && exit 0
 
-# Run `syntaur --version` with a PORTABLE ~1s watchdog (background + kill) so it
-# is bounded even where `timeout`/`gtimeout` are absent (stock macOS). Prints the
-# trimmed version on success; prints nothing and returns non-zero if it hangs or
-# fails. 1s + the dashboard curl's --max-time 3 stays under the hook's 5s budget.
-syntaur_bounded_version() {
+# Run a syntaur CLI invocation with a PORTABLE SIGKILL watchdog (background +
+# kill) so it is bounded even where `timeout`/`gtimeout` are absent (stock
+# macOS). $1 = deadline in seconds; remaining args = the syntaur subcommand.
+# Stdin is forwarded; stdout is captured to a temp file and printed on success.
+# Returns non-zero if the CLI is absent, hangs past the deadline, or fails —
+# including a stale installed CLI that predates the subcommand.
+syntaur_bounded() {
   command -v syntaur >/dev/null 2>&1 || return 1
-  local out cpid kpid rc
-  out="${TMPDIR:-/tmp}/syntaur-ver.$$"
-  syntaur --version >"$out" 2>/dev/null &
+  local deadline out cpid kpid rc
+  deadline=$1
+  shift
+  out="${TMPDIR:-/tmp}/syntaur-hook.$$"
+  # `<&0` forwards the caller's stdin explicitly — background commands default
+  # to stdin-from-/dev/null in non-interactive shells, which would silently
+  # drop the piped hook payload.
+  syntaur "$@" <&0 >"$out" 2>/dev/null &
   cpid=$!
   # Hard deadline via SIGKILL (uncatchable — a TERM-ignoring or hung CLI cannot
-  # block us) at ~1s, guaranteeing the `wait` below returns. `--version` is a
-  # node process with no descendants in practice, so killing it is complete.
-  ( sleep 1; kill -KILL "$cpid" 2>/dev/null ) >/dev/null 2>&1 &
+  # block us), guaranteeing the `wait` below returns.
+  ( sleep "$deadline"; kill -KILL "$cpid" 2>/dev/null ) >/dev/null 2>&1 &
   kpid=$!
   wait "$cpid" 2>/dev/null
   rc=$?
@@ -40,7 +46,7 @@ syntaur_bounded_version() {
   kill -KILL "$kpid" 2>/dev/null
   wait "$kpid" 2>/dev/null
   if [ "$rc" -eq 0 ]; then
-    tr -d '[:space:]' <"$out" 2>/dev/null
+    cat "$out" 2>/dev/null
     rm -f "$out"
     return 0
   fi
@@ -50,15 +56,14 @@ syntaur_bounded_version() {
 
 # --- Best-effort, non-blocking: warn when the installed plugin is stale vs the
 # running CLI (the CLI updates via npm; the marketplace plugin copy does not).
-# Plugin-global, so it runs BEFORE the context-dependent early exits below. Any
-# failure → do nothing. NEVER changes the exit status (the hook always exits 0).
+# Any failure → do nothing. NEVER changes the exit status (always exits 0).
 syntaur_plugin_drift_warn() {
   local marker marker_ver cli_ver msg
   marker="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/syntaur}/.syntaur-install.json"
   [ -f "$marker" ] || return 0
   marker_ver=$(jq -r '.packageVersion // empty' "$marker" 2>/dev/null)
   [ -n "$marker_ver" ] || return 0
-  cli_ver=$(syntaur_bounded_version) || return 0
+  cli_ver=$(syntaur_bounded 1 --version | tr -d '[:space:]') || return 0
   [ -n "$cli_ver" ] || return 0
   [ "$marker_ver" = "$cli_ver" ] && return 0
   msg="Syntaur plugin v${marker_ver} differs from the installed CLI v${cli_ver} — run \`syntaur install-plugin --force\` to refresh."
@@ -66,100 +71,21 @@ syntaur_plugin_drift_warn() {
 }
 syntaur_plugin_drift_warn || true
 
-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.
-#
-# Also resolve the latest session-summary path (mid-assignment continuity) so
-# the resuming agent's first protocol-read can pick it up. Selection rule:
-# the summary.md with the most recent file mtime under
-# <assignmentDir>/sessions/*/summary.md. Null if none exists.
-ASSIGNMENT_DIR_RAW=$(jq -r '.assignmentDir // empty' "$CONTEXT_FILE" 2>/dev/null)
-ASSIGNMENT_DIR="${ASSIGNMENT_DIR_RAW/#\~/$HOME}"
-
-LATEST_SUMMARY=""
-if [ -n "$ASSIGNMENT_DIR" ] && [ -d "$ASSIGNMENT_DIR/sessions" ]; then
-  # Prefer GNU-style stat formatting if available (Linux); fall back to BSD
-  # (macOS). Resolve newest-by-mtime portably.
-  while IFS= read -r -d '' f; do
-    if M=$(stat -f '%m' "$f" 2>/dev/null) || M=$(stat -c '%Y' "$f" 2>/dev/null); then
-      printf '%s\t%s\n' "$M" "$f"
-    fi
-  done < <(find "$ASSIGNMENT_DIR/sessions" -mindepth 2 -maxdepth 2 -type f -name 'summary.md' -print0 2>/dev/null) \
-    | sort -rn -k1,1 \
-    | head -1 \
-    | cut -f2- > "${CONTEXT_FILE}.summary.tmp.$$" 2>/dev/null
-  LATEST_SUMMARY=$(cat "${CONTEXT_FILE}.summary.tmp.$$" 2>/dev/null || true)
-  rm -f "${CONTEXT_FILE}.summary.tmp.$$"
-fi
-
-TMP="${CONTEXT_FILE}.tmp.$$"
-jq \
-  --arg sid "$SESSION_ID" \
-  --arg tp "$TRANSCRIPT_PATH" \
-  --arg lsp "$LATEST_SUMMARY" \
-  '. + {sessionId: $sid, transcriptPath: (if ($tp | length) > 0 then $tp else null end), latestSessionSummaryPath: (if ($lsp | length) > 0 then $lsp 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)
-
 # Capture the terminal-session PID that owns this Claude process. Claude
 # Code's SessionStart payload does NOT include a parent PID, so we approximate
-# by walking up one level from the hook's own PID — that is, the shell the
-# hook was spawned by, which is the shell that owns claude. The server uses
-# this for liveness checks (and an auto-captured ps lstart= for recycling
-# defense). If `ps` is unavailable or returns nothing we just omit the field.
+# by walking up one level from the hook's own PID — the shell that owns claude.
 PID="$(ps -o ppid= -p $$ 2>/dev/null | tr -d '[:space:]' || true)"
 if [ -n "$PID" ] && ! printf '%s' "$PID" | grep -q '^[0-9]\+$'; then
   PID=""
 fi
 
-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" \
-  --arg pid "$PID" \
-  '{ 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)
-   + (if ($pid  | length) > 0 then {pid: ($pid | tonumber)} 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
+# Register EVERY session via the CLI (context.json merge + direct DB write).
+# ~4s deadline stays under the hook's `timeout: 5` budget. A stale CLI without
+# the subcommand exits non-zero — swallowed; the scanner is the safety net.
+if [ -n "$PID" ]; then
+  printf '%s' "$INPUT" | syntaur_bounded 4 session register --from-hook --pid "$PID" >/dev/null 2>&1 || true
+else
+  printf '%s' "$INPUT" | syntaur_bounded 4 session register --from-hook >/dev/null 2>&1 || true
 fi
 
 exit 0

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

@@ -5,84 +5,36 @@ description: Use when the user asks to track, register, or log this Claude Code
 
 # Track Session
 
-Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
+Attach a description and/or a project+assignment link to the current agent session's row in the Syntaur dashboard.
 
-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.
+Plain registration is automatic now — the SessionStart hook registers every session (and the background scanner backfills any the hook missed), so this skill only matters for the one remaining manual case: adding a description or an explicit project/assignment link. The CLI self-resolves the calling session's id (env → process-tree markers → transcript scan); never pass a synthesized id.
 
 ## Usage
 
 User arguments: `$ARGUMENTS`
 
-- (no args) — register a standalone session
-- `--description "<text>"` — with a description
-- `--project <slug> --assignment <slug>` — linked to a project
+- (no args) — upsert the session row as-is (rarely needed; the hook already did this)
+- `--description "<text>"` — attach a description
+- `--project <slug> --assignment <slug>` — link to a project assignment
 - `--description "<text>" --project <slug> --assignment <slug>` — both
 
 ## Workflow
 
-### Step 1: Parse arguments
-
-Extract optional flags from the argument string:
-- `--description "<text>"` or `--description <text>` — session description
-- `--project <slug>` — project to link to
-- `--assignment <slug>` — assignment to link to
-
-### Step 2: Source the real session id + transcript path
-
-Resolve the session id from *your* running process, in priority order:
-
-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.
-
-### Step 3: Run the CLI command
-
-Run the track-session CLI via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+Run one Bash call (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`), passing through whatever optional flags the user gave:
 
 ```bash
-syntaur track-session \
-  --agent claude \
-  --session-id "$SESSION_ID" \
-  --transcript-path "$TRANSCRIPT_PATH" \
-  --path "$(pwd)" \
-  --pid "$(ps -o ppid= -p $$ | tr -d ' ')" \
+syntaur track-session --agent claude \
   [--description "<text>"] \
-  [--project <slug>] \
-  [--assignment <slug>]
+  [--project <slug>] [--assignment <slug>]
 ```
 
-Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved. The `--pid` value is the shell PID that owns the Claude process — the dashboard uses it to disable Resume while this session may still be writing the transcript, forcing users to Fork instead. If `ps` is unavailable, omit `--pid` too.
+The CLI resolves the session id, transcript-derived path, owning pid, and HEAD sha itself, and prints one of:
 
-The CLI prints one of:
 - `Registered standalone agent session <sessionId>.`
 - `Registered agent session <sessionId> for <assignment> in <project>.`
 
-Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
-
-### Step 4: Merge context.json
-
-Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `track-session` runs find them). Merge, don't overwrite:
-
-```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
-```
+Registration is idempotent — re-running with the same session id safely upserts the description/link onto the existing row.
 
-### Step 5: Confirm
+If it errors with "Could not resolve a session id", restart the Claude session so the SessionStart hook can register it (or pass `--session-id <id>` with a real agent-generated id — never synthesize one).
 
-Tell the user:
-- 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.
+Confirm to the user: the row was updated (include the short session id), it auto-stops at SessionEnd, and which project/assignment it is linked to, if any.

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

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "Run Syntaur project and assignment workflows from Codex, including claiming work, planning, completing handoffs, session/server tracking, save-session-summary continuity, and write-boundary enforcement.",
   "author": {
     "name": "Brennen"

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

@@ -5,84 +5,36 @@ description: Use when the user asks to track, register, or log this Claude Code
 
 # Track Session
 
-Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
+Attach a description and/or a project+assignment link to the current agent session's row in the Syntaur dashboard.
 
-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.
+Plain registration is automatic now — the SessionStart hook registers every session (and the background scanner backfills any the hook missed), so this skill only matters for the one remaining manual case: adding a description or an explicit project/assignment link. The CLI self-resolves the calling session's id (env → process-tree markers → transcript scan); never pass a synthesized id.
 
 ## Usage
 
 User arguments: `$ARGUMENTS`
 
-- (no args) — register a standalone session
-- `--description "<text>"` — with a description
-- `--project <slug> --assignment <slug>` — linked to a project
+- (no args) — upsert the session row as-is (rarely needed; the hook already did this)
+- `--description "<text>"` — attach a description
+- `--project <slug> --assignment <slug>` — link to a project assignment
 - `--description "<text>" --project <slug> --assignment <slug>` — both
 
 ## Workflow
 
-### Step 1: Parse arguments
-
-Extract optional flags from the argument string:
-- `--description "<text>"` or `--description <text>` — session description
-- `--project <slug>` — project to link to
-- `--assignment <slug>` — assignment to link to
-
-### Step 2: Source the real session id + transcript path
-
-Resolve the session id from *your* running process, in priority order:
-
-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.
-
-### Step 3: Run the CLI command
-
-Run the track-session CLI via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+Run one Bash call (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`), passing through whatever optional flags the user gave:
 
 ```bash
-syntaur track-session \
-  --agent claude \
-  --session-id "$SESSION_ID" \
-  --transcript-path "$TRANSCRIPT_PATH" \
-  --path "$(pwd)" \
-  --pid "$(ps -o ppid= -p $$ | tr -d ' ')" \
+syntaur track-session --agent claude \
   [--description "<text>"] \
-  [--project <slug>] \
-  [--assignment <slug>]
+  [--project <slug>] [--assignment <slug>]
 ```
 
-Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved. The `--pid` value is the shell PID that owns the Claude process — the dashboard uses it to disable Resume while this session may still be writing the transcript, forcing users to Fork instead. If `ps` is unavailable, omit `--pid` too.
+The CLI resolves the session id, transcript-derived path, owning pid, and HEAD sha itself, and prints one of:
 
-The CLI prints one of:
 - `Registered standalone agent session <sessionId>.`
 - `Registered agent session <sessionId> for <assignment> in <project>.`
 
-Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
-
-### Step 4: Merge context.json
-
-Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `track-session` runs find them). Merge, don't overwrite:
-
-```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
-```
+Registration is idempotent — re-running with the same session id safely upserts the description/link onto the existing row.
 
-### Step 5: Confirm
+If it errors with "Could not resolve a session id", restart the Claude session so the SessionStart hook can register it (or pass `--session-id <id>` with a real agent-generated id — never synthesize one).
 
-Tell the user:
-- 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.
+Confirm to the user: the row was updated (include the short session id), it auto-stops at SessionEnd, and which project/assignment it is linked to, if any.