syntaur 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {
@@ -23,6 +23,17 @@
     "syntaur": "./bin/syntaur.js"
   },
   "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./launch": {
+      "types": "./dist/launch/index.d.ts",
+      "import": "./dist/launch/index.js"
+    },
+    "./dist/dashboard/server.js": "./dist/dashboard/server.js"
+  },
   "files": [
     "dist",
     "bin",
@@ -32,7 +43,8 @@
     ".claude-plugin",
     "examples",
     "dashboard/dist",
-    "statusline"
+    "statusline",
+    "scripts/install-macos-url-handler.mjs"
   ],
   "scripts": {
     "build": "tsup",
@@ -44,6 +56,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "mirror-skills": "node scripts/mirror-skills-to-platforms.mjs",
+    "postinstall": "node scripts/install-macos-url-handler.mjs",
     "prepack": "node scripts/mirror-skills-to-platforms.mjs",
     "prepublishOnly": "npm run build && npm ci --prefix dashboard && npm run build --prefix dashboard",
     "try": "node scripts/try.mjs",

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

@@ -51,12 +51,13 @@ syntaur track-session \
   --session-id "$SESSION_ID" \
   --transcript-path "$TRANSCRIPT_PATH" \
   --path "$(pwd)" \
+  --pid "$(ps -o ppid= -p $$ | tr -d ' ')" \
   [--description "<text>"] \
   [--project <slug>] \
   [--assignment <slug>]
 ```
 
-Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
+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 prints one of:
 - `Registered standalone agent session <sessionId>.`

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

@@ -77,6 +77,17 @@ jq \
 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.
+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")
@@ -88,10 +99,12 @@ BODY=$(jq -cn \
   --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)' 2>/dev/null)
+   + (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

package/platforms/claude-code/references/protocol-summary.md

@@ -93,6 +93,6 @@ Protocol version: **2.0**
 
 Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
 
-- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`.
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [--transcribe] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. `--transcribe` is video-only and writes a sibling `<id>.transcript.md` (requires `ELEVENLABS_API_KEY` + `ffmpeg`).
 - `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
 - Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

package/platforms/claude-code/skills/capture-artifacts/SKILL.md

@@ -46,7 +46,7 @@ Linkage to a specific criterion is **optional**. Untagged artifacts are fine —
 
 ```bash
 # File-based (screenshot, video, asciinema, http transcript)
-syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] \
+syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] [--transcribe] \
   [--project <slug> <assignment-slug>]
 
 # Text-only (no --file)
@@ -59,6 +59,7 @@ Rules:
 - `--kind=http` accepts either `--file` (a transcript) or `--note` (an inline summary). At least one is required.
 - All other kinds (`screenshot`, `video`, `asciinema`) require `--file`. The CLI rejects nonexistent / non-file paths.
 - `--criterion <index>` is optional — pass the **0-based** index into the `## Acceptance Criteria` checklist when you want to anchor the artifact to a specific criterion.
+- `--transcribe` is video-only and writes a sibling `<id>.transcript.md` (requires `ELEVENLABS_API_KEY` + `ffmpeg`). `proof build` renders the transcript next to the player; clicking a phrase seeks the video.
 - If you have a `.syntaur/context.json` in the cwd, the positional target argument is unnecessary; otherwise pass `--project <slug> <assignment-slug>` or a bare assignment UUID.
 
 The CLI copies the file (if any) under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>` and inserts a row in `~/.syntaur/syntaur.db`. Output prints the artifact id and absolute path.

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

@@ -129,6 +129,8 @@ If the command fails, report the error. Common failures:
 - Assignment is not in `in_progress` status
 - Project not found
 
+**Side effect:** Source todos that were promoted into this assignment via `syntaur todo promote --new-assignment` (or the dashboard `Promote to assignment` flow) automatically flip from `in_progress` to `completed` when this transition runs. If you later `reopen` the assignment, those auto-completed todos flip back to `in_progress`. Todos that the user manually marked `completed` after the auto-complete fired are left untouched on reopen.
+
 ## Step 8: Clean Up Context
 
 Delete the context file:

package/platforms/claude-code/skills/syntaur-protocol/references/protocol-summary.md

@@ -85,6 +85,6 @@ Protocol version: **2.0**
 
 Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
 
-- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. For `--kind=http`, supply `--file` (transcript) or `--note` (inline summary).
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [--transcribe] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. For `--kind=http`, supply `--file` (transcript) or `--note` (inline summary). `--transcribe` is video-only and writes a sibling `<id>.transcript.md` (requires `ELEVENLABS_API_KEY` + `ffmpeg`).
 - `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
 - Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

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

@@ -47,12 +47,13 @@ syntaur track-session \
   --session-id "$SESSION_ID" \
   --transcript-path "$TRANSCRIPT_PATH" \
   --path "$(pwd)" \
+  --pid "$(ps -o ppid= -p $$ | tr -d ' ')" \
   [--description "<text>"] \
   [--project <slug>] \
   [--assignment <slug>]
 ```
 
-Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
+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 prints one of:
 - `Registered standalone agent session <sessionId>.`

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

@@ -95,7 +95,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 <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 track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <real-id> --transcript-path <rollout-path> --path <cwd> [--pid <n>]` (both `--session-id` and `--transcript-path` must come from the matching Codex rollout file — never synthesize. Pass `--pid "$$"` so the dashboard can detect liveness and gate Resume off while this session is still running.)
 - `syntaur setup-adapter codex --project <project-slug> --assignment <assignment-slug>`
 - `syntaur plan version --assignment <slug> [--project <slug>]` — bump to `plan-v<N>.md` per Plan Versioning playbook
 - `syntaur session resume [--json]` — re-orient on the active assignment from latest session summary + context.json + open handoff (idempotent)
@@ -115,7 +115,7 @@ Use these commands directly when needed:
 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)"`.
+7. Register the session: `syntaur track-session --project <slug> --assignment <slug> --agent codex --session-id <id> --transcript-path <path> --path "$(pwd)" --pid "$$"` (passing `--pid "$$"` lets the dashboard show Resume disabled while this session is still running).
 8. If needed, run `syntaur setup-adapter codex --project <slug> --assignment <slug>`.
 
 ### Plan an assignment

package/platforms/codex/references/protocol-summary.md

@@ -93,6 +93,6 @@ Protocol version: **2.0**
 
 Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
 
-- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`.
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [--transcribe] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. `--transcribe` is video-only and writes a sibling `<id>.transcript.md` (requires `ELEVENLABS_API_KEY` + `ffmpeg`).
 - `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
 - Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

package/platforms/codex/skills/capture-artifacts/SKILL.md

@@ -46,7 +46,7 @@ Linkage to a specific criterion is **optional**. Untagged artifacts are fine —
 
 ```bash
 # File-based (screenshot, video, asciinema, http transcript)
-syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] \
+syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] [--transcribe] \
   [--project <slug> <assignment-slug>]
 
 # Text-only (no --file)
@@ -59,6 +59,7 @@ Rules:
 - `--kind=http` accepts either `--file` (a transcript) or `--note` (an inline summary). At least one is required.
 - All other kinds (`screenshot`, `video`, `asciinema`) require `--file`. The CLI rejects nonexistent / non-file paths.
 - `--criterion <index>` is optional — pass the **0-based** index into the `## Acceptance Criteria` checklist when you want to anchor the artifact to a specific criterion.
+- `--transcribe` is video-only and writes a sibling `<id>.transcript.md` (requires `ELEVENLABS_API_KEY` + `ffmpeg`). `proof build` renders the transcript next to the player; clicking a phrase seeks the video.
 - If you have a `.syntaur/context.json` in the cwd, the positional target argument is unnecessary; otherwise pass `--project <slug> <assignment-slug>` or a bare assignment UUID.
 
 The CLI copies the file (if any) under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>` and inserts a row in `~/.syntaur/syntaur.db`. Output prints the artifact id and absolute path.

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

@@ -129,6 +129,8 @@ If the command fails, report the error. Common failures:
 - Assignment is not in `in_progress` status
 - Project not found
 
+**Side effect:** Source todos that were promoted into this assignment via `syntaur todo promote --new-assignment` (or the dashboard `Promote to assignment` flow) automatically flip from `in_progress` to `completed` when this transition runs. If you later `reopen` the assignment, those auto-completed todos flip back to `in_progress`. Todos that the user manually marked `completed` after the auto-complete fired are left untouched on reopen.
+
 ## Step 8: Clean Up Context
 
 Delete the context file:

package/platforms/codex/skills/syntaur-protocol/references/protocol-summary.md

@@ -85,6 +85,6 @@ Protocol version: **2.0**
 
 Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
 
-- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. For `--kind=http`, supply `--file` (transcript) or `--note` (inline summary).
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [--transcribe] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. For `--kind=http`, supply `--file` (transcript) or `--note` (inline summary). `--transcribe` is video-only and writes a sibling `<id>.transcript.md` (requires `ELEVENLABS_API_KEY` + `ffmpeg`).
 - `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
 - Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

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

@@ -47,12 +47,13 @@ syntaur track-session \
   --session-id "$SESSION_ID" \
   --transcript-path "$TRANSCRIPT_PATH" \
   --path "$(pwd)" \
+  --pid "$(ps -o ppid= -p $$ | tr -d ' ')" \
   [--description "<text>"] \
   [--project <slug>] \
   [--assignment <slug>]
 ```
 
-Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
+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 prints one of:
 - `Registered standalone agent session <sessionId>.`