Fix headless broker readiness

.trajectories/completed/2026-05/traj_0o6gb2wvk59t.json

@@ -0,0 +1,89 @@
+{
+  "id": "traj_0o6gb2wvk59t",
+  "version": 1,
+  "task": {
+    "title": "Fresh end-to-end validation for headless readiness"
+  },
+  "status": "completed",
+  "startedAt": "2026-05-15T10:55:49.188Z",
+  "completedAt": "2026-05-15T11:11:52.324Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-15T10:56:20.988Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_agsepzuxybr2",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-15T10:56:20.988Z",
+      "endedAt": "2026-05-15T11:11:52.324Z",
+      "events": [
+        {
+          "ts": 1778842580989,
+          "type": "decision",
+          "content": "Validate via four independent surfaces: Validate via four independent surfaces",
+          "raw": {
+            "question": "Validate via four independent surfaces",
+            "chosen": "Validate via four independent surfaces",
+            "alternatives": [],
+            "reasoning": "For a fresh end-to-end pass, unit tests alone are not enough. Run the full Vitest suite, broker integration tests, direct built-CLI headless lifecycle, and packaged Bun standalone smoke so both Node and compiled binary invocation shapes are exercised."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1778842631500,
+          "type": "reflection",
+          "content": "Full Vitest suite passed: 66 files, 849 tests. Continuing into built CLI and broker integration surfaces.",
+          "raw": {
+            "confidence": 0.85
+          },
+          "significance": "high",
+          "tags": [
+            "confidence:0.85"
+          ]
+        },
+        {
+          "ts": 1778842685777,
+          "type": "decision",
+          "content": "Fix broker integration harness strict typing before running E2E: Fix broker integration harness strict typing before running E2E",
+          "raw": {
+            "question": "Fix broker integration harness strict typing before running E2E",
+            "chosen": "Fix broker integration harness strict typing before running E2E",
+            "alternatives": [],
+            "reasoning": "Fresh validation uncovered that the broker integration suite could not compile because createWorkspace().apiKey is typed optional. The harness now throws if the workspace response lacks an API key instead of assigning undefined to RELAY_API_KEY."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1778843512026,
+          "type": "reflection",
+          "content": "Fresh E2E pass results: full Vitest, clean build, built CLI headless lifecycle, packaged standalone smoke, and npm tarball validation passed. Broker integration runner now compiles with the harness fix, but the broad live broker suite still has pre-existing runtime failures/skips unrelated to this headless change, including stale PID-file expectations.",
+          "raw": {
+            "confidence": 0.88
+          },
+          "significance": "high",
+          "tags": [
+            "confidence:0.88"
+          ]
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Ran a fresh end-to-end validation pass for headless broker readiness. Fixed the broker integration harness strict typing issue discovered during validation, verified full Vitest/build/direct headless CLI/standalone smoke/package tarball validation, and documented the remaining broad broker integration suite limitations.",
+    "approach": "Standard approach",
+    "confidence": 0.88
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relay-broker-headless-reliability-doc",
+  "tags": [],
+  "_trace": {
+    "startRef": "ccd34408916ca0ae9b897aad20ddeb7b8fb1a171",
+    "endRef": "ccd34408916ca0ae9b897aad20ddeb7b8fb1a171"
+  }
+}

.trajectories/completed/2026-05/traj_0o6gb2wvk59t.md

@@ -0,0 +1,38 @@
+# Trajectory: Fresh end-to-end validation for headless readiness
+
+> **Status:** ✅ Completed
+> **Confidence:** 88%
+> **Started:** May 15, 2026 at 12:55 PM
+> **Completed:** May 15, 2026 at 01:11 PM
+
+---
+
+## Summary
+
+Ran a fresh end-to-end validation pass for headless broker readiness. Fixed the broker integration harness strict typing issue discovered during validation, verified full Vitest/build/direct headless CLI/standalone smoke/package tarball validation, and documented the remaining broad broker integration suite limitations.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Validate via four independent surfaces
+- **Chose:** Validate via four independent surfaces
+- **Reasoning:** For a fresh end-to-end pass, unit tests alone are not enough. Run the full Vitest suite, broker integration tests, direct built-CLI headless lifecycle, and packaged Bun standalone smoke so both Node and compiled binary invocation shapes are exercised.
+
+### Fix broker integration harness strict typing before running E2E
+- **Chose:** Fix broker integration harness strict typing before running E2E
+- **Reasoning:** Fresh validation uncovered that the broker integration suite could not compile because createWorkspace().apiKey is typed optional. The harness now throws if the workspace response lacks an API key instead of assigning undefined to RELAY_API_KEY.
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Validate via four independent surfaces: Validate via four independent surfaces
+- Full Vitest suite passed: 66 files, 849 tests. Continuing into built CLI and broker integration surfaces.
+- Fix broker integration harness strict typing before running E2E: Fix broker integration harness strict typing before running E2E
+- Fresh E2E pass results: full Vitest, clean build, built CLI headless lifecycle, packaged standalone smoke, and npm tarball validation passed. Broker integration runner now compiles with the harness fix, but the broad live broker suite still has pre-existing runtime failures/skips unrelated to this headless change, including stale PID-file expectations.

.trajectories/completed/2026-05/traj_4chzkm724ufo.json

@@ -0,0 +1,76 @@
+{
+  "id": "traj_4chzkm724ufo",
+  "version": 1,
+  "task": {
+    "title": "Fix headless orchestrator worktree CLI E2E issues"
+  },
+  "status": "completed",
+  "startedAt": "2026-05-15T11:44:28.338Z",
+  "completedAt": "2026-05-15T11:51:05.319Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-15T11:44:28.513Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_4065ik4d57ah",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-15T11:44:28.513Z",
+      "endedAt": "2026-05-15T11:51:05.319Z",
+      "events": [
+        {
+          "ts": 1778845468515,
+          "type": "decision",
+          "content": "Investigate failed worktree E2E before editing: Investigate failed worktree E2E before editing",
+          "raw": {
+            "question": "Investigate failed worktree E2E before editing",
+            "chosen": "Investigate failed worktree E2E before editing",
+            "alternatives": [],
+            "reasoning": "The documented skill command failed in a real skills PR worktree with stale connection metadata and STOPPED status; need distinguish environmental port collision from CLI/doc defects before changing guidance."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1778845739665,
+          "type": "decision",
+          "content": "Fixed orphan cleanup process matching: Fixed orphan cleanup process matching",
+          "raw": {
+            "question": "Fixed orphan cleanup process matching",
+            "chosen": "Fixed orphan cleanup process matching",
+            "alternatives": [],
+            "reasoning": "The worktree E2E harness was killed by agent-relay down --force because orphan cleanup grepped ps output for projectRoot and agent-relay-broker anywhere in the command line; shell wrappers can contain both strings without being broker processes. The fix parses ps output and only targets commands whose executable basename is agent-relay-broker."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1778845804918,
+          "type": "reflection",
+          "content": "Worktree E2E now passes after fixing orphan cleanup false-positive process matching. The CLI scenario leaves .agent-relay/ and .mcp.json as expected runtime artifacts, so verification worktrees need cleanup before status checks.",
+          "raw": {
+            "focalPoints": ["worktree-e2e", "orphan-cleanup", "runtime-artifacts"],
+            "confidence": 0.85
+          },
+          "significance": "high",
+          "tags": ["focal:worktree-e2e", "focal:orphan-cleanup", "focal:runtime-artifacts", "confidence:0.85"]
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Fixed a headless CLI worktree E2E failure where orphan cleanup could match and terminate the caller shell when its command line contained both the worktree path and agent-relay-broker. Added robust ps parsing so down/up orphan cleanup only targets actual agent-relay-broker executables, added a regression test, refreshed build, reran the skills PR worktree CLI lifecycle end to end, and documented cleanup of generated .agent-relay/.mcp.json artifacts in the headless orchestrator skill.",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relay-broker-headless-reliability-doc",
+  "tags": [],
+  "_trace": {
+    "startRef": "4da9b3491972b448a1c5d482371247157b458c2b",
+    "endRef": "4da9b3491972b448a1c5d482371247157b458c2b"
+  }
+}

.trajectories/completed/2026-05/traj_4chzkm724ufo.md

@@ -0,0 +1,40 @@
+# Trajectory: Fix headless orchestrator worktree CLI E2E issues
+
+> **Status:** ✅ Completed
+> **Confidence:** 90%
+> **Started:** May 15, 2026 at 01:44 PM
+> **Completed:** May 15, 2026 at 01:51 PM
+
+---
+
+## Summary
+
+Fixed a headless CLI worktree E2E failure where orphan cleanup could match and terminate the caller shell when its command line contained both the worktree path and agent-relay-broker. Added robust ps parsing so down/up orphan cleanup only targets actual agent-relay-broker executables, added a regression test, refreshed build, reran the skills PR worktree CLI lifecycle end to end, and documented cleanup of generated .agent-relay/.mcp.json artifacts in the headless orchestrator skill.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Investigate failed worktree E2E before editing
+
+- **Chose:** Investigate failed worktree E2E before editing
+- **Reasoning:** The documented skill command failed in a real skills PR worktree with stale connection metadata and STOPPED status; need distinguish environmental port collision from CLI/doc defects before changing guidance.
+
+### Fixed orphan cleanup process matching
+
+- **Chose:** Fixed orphan cleanup process matching
+- **Reasoning:** The worktree E2E harness was killed by agent-relay down --force because orphan cleanup grepped ps output for projectRoot and agent-relay-broker anywhere in the command line; shell wrappers can contain both strings without being broker processes. The fix parses ps output and only targets commands whose executable basename is agent-relay-broker.
+
+---
+
+## Chapters
+
+### 1. Work
+
+_Agent: default_
+
+- Investigate failed worktree E2E before editing: Investigate failed worktree E2E before editing
+- Fixed orphan cleanup process matching: Fixed orphan cleanup process matching
+- Worktree E2E now passes after fixing orphan cleanup false-positive process matching. The CLI scenario leaves .agent-relay/ and .mcp.json as expected runtime artifacts, so verification worktrees need cleanup before status checks.

.trajectories/completed/2026-05/traj_4vucir4qvqa2.json

@@ -0,0 +1,75 @@
+{
+  "id": "traj_4vucir4qvqa2",
+  "version": 1,
+  "task": {
+    "title": "Harden headless broker readiness semantics"
+  },
+  "status": "completed",
+  "startedAt": "2026-05-15T09:46:07.617Z",
+  "completedAt": "2026-05-15T09:59:00.460Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-15T09:53:03.774Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_kfz7mc7l9gg4",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-15T09:53:03.774Z",
+      "endedAt": "2026-05-15T09:59:00.460Z",
+      "events": [
+        {
+          "ts": 1778838783775,
+          "type": "decision",
+          "content": "Gate detached broker start on API readiness and report STARTING separately: Gate detached broker start on API readiness and report STARTING separately",
+          "raw": {
+            "question": "Gate detached broker start on API readiness and report STARTING separately",
+            "chosen": "Gate detached broker start on API readiness and report STARTING separately",
+            "alternatives": [],
+            "reasoning": "Headless orchestrators need command success to mean usable broker, and live-process/API-unready must not be collapsed into STOPPED."
+          },
+          "significance": "high"
+        },
+        {
+          "ts": 1778839134173,
+          "type": "reflection",
+          "content": "Readiness hardening implemented and verified with focused command tests, typecheck, lint, and diff checks; remaining lint output is pre-existing complexity/depth warnings outside the new readiness helper.",
+          "raw": {
+            "focalPoints": [
+              "readiness semantics",
+              "detached start",
+              "status truthfulness",
+              "verification"
+            ],
+            "confidence": 0.9
+          },
+          "significance": "high",
+          "tags": [
+            "focal:readiness semantics",
+            "focal:detached start",
+            "focal:status truthfulness",
+            "focal:verification",
+            "confidence:0.9"
+          ]
+        }
+      ]
+    }
+  ],
+  "retrospective": {
+    "summary": "Hardened headless broker startup so detached up waits for API readiness, status --wait-for distinguishes STARTING from STOPPED and exits non-zero on timeout, and docs/skills/tests now encode the readiness contract.",
+    "approach": "Standard approach",
+    "confidence": 0.92
+  },
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relay-broker-headless-reliability-doc",
+  "tags": [],
+  "_trace": {
+    "startRef": "67d37e44cecdab1be65a8ee2bf3fb9a60e61c162",
+    "endRef": "67d37e44cecdab1be65a8ee2bf3fb9a60e61c162"
+  }
+}

.trajectories/completed/2026-05/traj_4vucir4qvqa2.md

@@ -0,0 +1,32 @@
+# Trajectory: Harden headless broker readiness semantics
+
+> **Status:** ✅ Completed
+> **Confidence:** 92%
+> **Started:** May 15, 2026 at 11:46 AM
+> **Completed:** May 15, 2026 at 11:59 AM
+
+---
+
+## Summary
+
+Hardened headless broker startup so detached up waits for API readiness, status --wait-for distinguishes STARTING from STOPPED and exits non-zero on timeout, and docs/skills/tests now encode the readiness contract.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Gate detached broker start on API readiness and report STARTING separately
+- **Chose:** Gate detached broker start on API readiness and report STARTING separately
+- **Reasoning:** Headless orchestrators need command success to mean usable broker, and live-process/API-unready must not be collapsed into STOPPED.
+
+---
+
+## Chapters
+
+### 1. Work
+*Agent: default*
+
+- Gate detached broker start on API readiness and report STARTING separately: Gate detached broker start on API readiness and report STARTING separately
+- Readiness hardening implemented and verified with focused command tests, typecheck, lint, and diff checks; remaining lint output is pre-existing complexity/depth warnings outside the new readiness helper.