squadrant 0.9.0

package/scripts/migrate-to-squadrant.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+#
+# migrate-to-squadrant.sh — one-time live cutover from claude-cockpit → squadrant.
+#
+# Renames the runtime config dir, hub vault, daemon launchd label, and rewrites
+# config.json to the new brand. Idempotent (safe to re-run) and supports
+# --dry-run (prints every action and a concrete config-rewrite preview WITHOUT
+# mutating anything).
+#
+# This is run MANUALLY by the user at cutover — it terminates the live captain
+# session and bounces the daemon. The old daemon keeps running old `dist` until
+# this script runs, so nothing live breaks before then.
+#
+# Usage:
+#   scripts/migrate-to-squadrant.sh --dry-run   # preview, mutate nothing
+#   scripts/migrate-to-squadrant.sh             # perform the cutover
+#
+set -euo pipefail
+
+DRY_RUN=0
+case "${1:-}" in
+  --dry-run) DRY_RUN=1 ;;
+  "" ) ;;
+  * ) echo "usage: $0 [--dry-run]" >&2; exit 2 ;;
+esac
+
+OLD_CONFIG="$HOME/.config/cockpit"
+NEW_CONFIG="$HOME/.config/squadrant"
+OLD_HUB="$HOME/cockpit-hub"
+NEW_HUB="$HOME/squadrant-hub"
+OLD_LABEL="com.cockpit.daemon"
+NEW_LABEL="com.squadrant.daemon"
+OLD_PLIST="$HOME/Library/LaunchAgents/${OLD_LABEL}.plist"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+UID_NUM="$(id -u)"
+TS="$(date +%Y%m%d-%H%M%S)"
+BACKUP="$HOME/squadrant-migration-backup-${TS}.tgz"
+
+step() { printf '\n\033[1m== %s\033[0m\n' "$*"; }
+run() { printf '  $ %s\n' "$*"; [ "$DRY_RUN" -eq 1 ] || eval "$@"; }
+note() { printf '  · %s\n' "$*"; }
+
+# ---- config.json rewrite (pure, no claude-cockpit collisions: none of the
+#      rules match inside "claude-cockpit", so the real repo path is untouched).
+rewrite_config() {  # $1=src json  $2=mode (apply <dest> | preview)
+  local src="$1" mode="$2" dest="${3:-}"
+  SRC="$src" MODE="$mode" DEST="$dest" python3 - <<'PY'
+import json, os, sys
+src, mode, dest = os.environ["SRC"], os.environ["MODE"], os.environ["DEST"]
+with open(src) as f:
+    d = json.load(f)
+RULES = [("cockpit-hub", "squadrant-hub"),
+         (".config/cockpit", ".config/squadrant"),
+         ("⚓ cockpit-captain", "⚓ squadrant-captain")]
+changes = []
+def fix(s):
+    out = s
+    for a, b in RULES:
+        out = out.replace(a, b)
+    if out != s:
+        changes.append((s, out))
+    return out
+def walk(o):
+    if isinstance(o, dict):
+        return {k: walk(v) for k, v in o.items()}
+    if isinstance(o, list):
+        return [walk(v) for v in o]
+    if isinstance(o, str):
+        return fix(o)
+    return o
+d = walk(d)
+if "_cockpitVersion" in d:
+    d["_squadrantVersion"] = d.pop("_cockpitVersion")
+    changes.append(("key:_cockpitVersion", "key:_squadrantVersion"))
+if mode == "preview":
+    print(f"  rewrites that WOULD apply to {src} ({len(changes)}):")
+    for a, b in changes:
+        print(f"    - {a!r}\n    + {b!r}")
+else:
+    with open(dest, "w") as f:
+        json.dump(d, f, indent=2)
+        f.write("\n")
+    print(f"  rewrote {dest} ({len(changes)} value/key changes)")
+PY
+}
+
+printf '\033[1mSquadrant migration%s\033[0m\n' "$([ "$DRY_RUN" -eq 1 ] && echo ' (DRY RUN — nothing will change)')"
+note "repo:        $REPO_ROOT"
+note "config:      $OLD_CONFIG  ->  $NEW_CONFIG"
+note "hub:         $OLD_HUB  ->  $NEW_HUB"
+note "daemon:      $OLD_LABEL  ->  $NEW_LABEL"
+
+# Already migrated? (new dir present, old gone) — nothing to do.
+if [ -d "$NEW_CONFIG" ] && [ ! -d "$OLD_CONFIG" ]; then
+  step "Already migrated — $NEW_CONFIG exists and $OLD_CONFIG is gone. Nothing to do."
+  exit 0
+fi
+
+step "1. Backup ~/.config/cockpit and ~/cockpit-hub"
+# Archive with paths RELATIVE to $HOME so rollback is `tar xzf <backup> -C $HOME`.
+BACKUP_RELS=()
+[ -d "$OLD_CONFIG" ] && BACKUP_RELS+=(".config/cockpit")
+[ -d "$OLD_HUB" ] && BACKUP_RELS+=("cockpit-hub")
+if [ "${#BACKUP_RELS[@]}" -gt 0 ]; then
+  run "tar czf '$BACKUP' -C '$HOME' ${BACKUP_RELS[*]}"
+  note "backup -> $BACKUP   (rollback: tar xzf '$BACKUP' -C '$HOME' + reload old plist)"
+else
+  note "no source dirs to back up (fresh machine?)"
+fi
+
+step "2. Stop captains + bootout the old daemon"
+note "Captains are cmux workspaces — close them in cmux, or let the relaunch below recreate them."
+run "launchctl bootout gui/${UID_NUM}/${OLD_LABEL} 2>/dev/null || true"
+
+step "3. Move config dir and hub vault"
+if [ -d "$OLD_CONFIG" ] && [ ! -d "$NEW_CONFIG" ]; then run "mv '$OLD_CONFIG' '$NEW_CONFIG'"; else note "config move skipped (old absent or new exists)"; fi
+if [ -d "$OLD_HUB" ] && [ ! -d "$NEW_HUB" ]; then run "mv '$OLD_HUB' '$NEW_HUB'"; else note "hub move skipped (old absent or new exists)"; fi
+
+step "4. Rewrite config.json (cockpit-hub→squadrant-hub, .config/cockpit→.config/squadrant, ⚓ cockpit-captain→⚓ squadrant-captain, _cockpitVersion key)"
+if [ "$DRY_RUN" -eq 1 ]; then
+  CFG_SRC="$OLD_CONFIG/config.json"; [ -f "$CFG_SRC" ] || CFG_SRC="$NEW_CONFIG/config.json"
+  if [ -f "$CFG_SRC" ]; then rewrite_config "$CFG_SRC" preview; else note "no config.json found to preview"; fi
+else
+  CFG="$NEW_CONFIG/config.json"
+  if [ -f "$CFG" ]; then
+    cp "$CFG" "${CFG}.pre-squadrant.bak"
+    rewrite_config "$CFG" apply "$CFG"
+    python3 -c "import json;json.load(open('$CFG'))" && note "config.json valid JSON"
+  else
+    note "no config.json found at $CFG — skipping rewrite"
+  fi
+fi
+
+step "5. Remove old launchd plist (the rebuilt daemon installs com.squadrant.daemon.plist on first run)"
+[ -f "$OLD_PLIST" ] && run "rm -f '$OLD_PLIST'" || note "old plist absent"
+
+step "6. Build the rebranded binary + relink the global 'squadrant'/'squad' bin"
+run "pnpm -C '$REPO_ROOT' build"
+run "pnpm -C '$REPO_ROOT' link --global"
+note "removes the old global 'cockpit' bin; 'squadrant' and 'squad' now resolve to $REPO_ROOT/dist/index.js"
+
+step "7. Bootstrap the new daemon"
+note "Any 'squadrant' invocation triggers ensureDaemon, which writes com.squadrant.daemon.plist and bootstraps it."
+run "node '$REPO_ROOT/dist/index.js' --version"
+
+step "Done"
+cat <<EOF
+  Checklist:
+    1. Verify daemon:   launchctl print gui/${UID_NUM}/${NEW_LABEL} | head
+    2. Verify CLI:      squadrant --version   (expect 0.9.0)   and   squad --help
+    3. Relaunch captains:  squadrant launch <project>   (recreates the ⚓ squadrant-captain workspaces)
+    4. Tail the log:    tail -f ${NEW_CONFIG}/squadrantd.log
+  Rollback (if needed):
+    launchctl bootout gui/${UID_NUM}/${NEW_LABEL} 2>/dev/null || true
+    rm -rf ${NEW_CONFIG} ${NEW_HUB}
+    tar xzf ${BACKUP} -C ${HOME}
+    # then reinstall the old plist + relink the old 'cockpit' bin
+EOF

package/scripts/notify-relay-placement-smoke.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Live E2E for #117: spawnInjector("hidden") must NOT create a split-pane and
+// must NOT steal focus. Drives the real built cmux driver against a throwaway
+// cmux workspace, then inspects `cmux tree` to assert:
+//   1. the workspace has exactly ONE pane (a split would create a second)
+//   2. the relay surface exists as a background tab in that pane
+//   3. the surface selected before spawn is still [selected] afterward
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+
+const CMUX = "/Applications/cmux.app/Contents/Resources/bin/cmux";
+const cmux = (args) => execFileSync(CMUX, args, { encoding: "utf-8" }).trim();
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const { createCmuxDriver } = await import(
+  "file://" + join(__dirname, "..", "dist", "runtimes", "cmux.js")
+);
+
+let failures = 0;
+const assert = (cond, label) => {
+  console.log(`  ${cond ? "✓" : "✗"} ${label}`);
+  if (!cond) failures++;
+};
+
+const out = cmux(["new-workspace", "--cwd", "/tmp", "--command", "bash"]);
+const ws = out.match(/workspace:\d+/)?.[0];
+cmux(["rename-workspace", "--workspace", ws, "zz-117-smoke"]);
+const driver = createCmuxDriver();
+
+try {
+  const treeBefore = cmux(["tree", "--workspace", ws]);
+  const capSurface = treeBefore.match(/(surface:\d+)\s+\[terminal\][^\n]*\[selected\]/)?.[1];
+  console.log(`workspace=${ws} captain surface=${capSurface}`);
+
+  const pane = await driver.spawnInjector({
+    captainWorkspace: { id: ws, name: "zz-117-smoke", status: "running" },
+    command: "echo notify-relay-stub; sleep 30",
+    title: "✉ notify-relay",
+    placement: "hidden",
+  });
+  console.log(`spawnInjector returned ${pane.surfaceId}`);
+
+  const tree = cmux(["tree", "--workspace", ws]);
+  console.log("--- tree after spawnInjector(hidden) ---\n" + tree);
+
+  const paneCount = (tree.match(/^\s*[├└]?[─ ]*pane\s+pane:\d+/gm) || []).length;
+  assert(paneCount === 1, `exactly ONE pane — no split (got ${paneCount})`);
+
+  const surfaces = (tree.match(/surface:\d+/g) || []);
+  assert(surfaces.includes(pane.surfaceId), `relay surface ${pane.surfaceId} present as a tab`);
+
+  const selected = tree.match(/(surface:\d+)\s+\[terminal\][^\n]*\[selected\]/)?.[1];
+  assert(selected === capSurface, `captain surface ${capSurface} still [selected] (relay did NOT steal focus; got ${selected})`);
+
+  console.log(`\n${failures === 0 ? "✔ PLACEMENT SMOKE PASSED" : `✗ ${failures} FAILURES`}`);
+} finally {
+  cmux(["close-workspace", "--workspace", ws]);
+  process.exit(failures > 0 ? 1 : 0);
+}

package/scripts/read-handoff.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Usage: read-handoff.sh <spoke-vault-path> [--keep]
+# Reads and prints handoff.json, then deletes it (unless --keep).
+# Captain calls this on session startup to load previous context.
+set -euo pipefail
+
+VAULT="${1:?Usage: read-handoff.sh <vault-path> [--keep]}"
+KEEP="${2:-}"
+HANDOFF_FILE="$VAULT/handoff.json"
+
+if [ ! -f "$HANDOFF_FILE" ]; then
+  echo '{"exists": false}'
+  exit 0
+fi
+
+# Print the handoff content
+cat "$HANDOFF_FILE"
+
+# Delete unless --keep flag
+if [ "$KEEP" != "--keep" ]; then
+  rm "$HANDOFF_FILE"
+fi

package/scripts/record-learning.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Usage: record-learning.sh <spoke-vault-path> <category> <content> [tags]
+# Tags: comma-separated keywords for selective loading (e.g., "cairo,escrow,pvp")
+set -euo pipefail
+VAULT="${1:?Usage: record-learning.sh <vault-path> <category> <content> [tags]}"
+CATEGORY="${2:?}"
+CONTENT="${3:?}"
+TAGS="${4:-}"
+DATE=$(date +"%Y-%m-%d")
+TIMESTAMP=$(date +"%H%M%S")
+SLUG=$(echo "$CONTENT" | head -c 40 | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]//g')
+FILENAME="${VAULT}/learnings/${DATE}-${SLUG}-${TIMESTAMP}.md"
+mkdir -p "${VAULT}/learnings"
+cat > "$FILENAME" << EOF
+---
+type: learning
+date: ${DATE}
+category: ${CATEGORY}
+applied: false
+times_loaded: 0
+times_useful: 0
+tags: [${TAGS}]
+---
+
+## What happened
+${CONTENT}
+
+## Suggestion
+
+EOF
+echo "Recorded learning: $FILENAME"

package/scripts/record-side-handoff.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Usage: record-side-handoff.sh <spoke-vault-path> <topic> <role> <summary>
+# Writes a durable handoff record to {spokeVault}/side-handoffs/<topic-slug>.md
+set -euo pipefail
+
+VAULT="${1:?Usage: record-side-handoff.sh <vault-path> <topic> <role> <summary>}"
+TOPIC="${2:?}"
+ROLE="${3:?}"
+SUMMARY="${4:?}"
+DATE=$(date +"%Y-%m-%d")
+SLUG=$(echo "$TOPIC" | head -c 60 | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]//g')
+FILENAME="${VAULT}/side-handoffs/${SLUG}.md"
+
+mkdir -p "${VAULT}/side-handoffs"
+
+cat > "$FILENAME" << EOF
+---
+type: side-handoff
+role: ${ROLE}
+date: ${DATE}
+topic: ${TOPIC}
+---
+
+## Summary
+${SUMMARY}
+
+## Full handoff
+
+(Appended by side-session — see squadrant relay for the captain's copy.)
+EOF
+
+echo "Recorded side handoff: $FILENAME"

package/scripts/smoke-push-notify.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// scripts/smoke-push-notify.mjs
+//
+// Live(ish) smoke for #109: spins up a real squadrantd from the worktree
+// dist on a temp socket, injects a capturing `notify`, seeds a task, then
+// drives the same control events that `squadrant crew signal done|blocked|
+// failed` would emit. Asserts that each terminal/attention transition
+// produced exactly one captain-bound notification with the spec'd
+// CREW … [<provider>/<taskId-8>]: … format. Also probes redundancy
+// (a second done is a no-op) and notifier-down resilience (a throwing
+// notify must not crash the daemon).
+//
+// We use `notify` capture rather than shelling out to the production
+// `squadrant runtime send` because (a) the unit suite already covers the
+// shell-out path, and (b) restarting the launchd-managed daemon to point
+// at the worktree build would interrupt unrelated in-flight sessions
+// (squadrant memory: "never auto-restart running captain/crew sessions").
+// This smoke validates startSquadrantd → createDaemon → notify wiring
+// end-to-end through the real socket; the shell-out is one execFileSync
+// call away in the default `notify` and is covered by the cmux notifier
+// tests.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const distEntry = pathToFileURL(join(__dirname, "..", "dist", "control", "squadrantd.js")).href;
+const distProto = pathToFileURL(join(__dirname, "..", "dist", "control", "protocol.js")).href;
+const { startSquadrantd } = await import(distEntry);
+const { sendRequest } = await import(distProto);
+
+const evidencePath = join(__dirname, "..", ".phase-3-5-smoke-evidence.local");
+const log = [];
+const record = (m) => { log.push(m); process.stdout.write(m + "\n"); };
+
+const dir = mkdtempSync(join(tmpdir(), "cp-phase35-"));
+const sock = join(dir, "c.sock");
+const captured = []; // {project, message}
+
+const handle = startSquadrantd({
+  stateRoot: join(dir, "state"),
+  sockPath: sock,
+  sweepMs: 0,
+  notify: (args) => { captured.push({ project: args.project, message: args.message }); },
+});
+
+const baseRec = (id, overrides = {}) => ({
+  id, project: "p", provider: "claude", mode: "interactive",
+  state: "submitted", task: "ship the phase 3.5 push notifications",
+  createdAt: 1, lastHeartbeat: 1, lastEvent: "",
+  heartbeatBudgetMs: 1000,
+  attempts: [{ attemptId: "a0", startedAt: 1, lastHeartbeatAt: 1 }],
+  ...overrides,
+});
+
+let failures = 0;
+const assert = (cond, label) => {
+  if (cond) { record(`  ✓ ${label}`); }
+  else { record(`  ✗ ${label}`); failures++; }
+};
+
+try {
+  record(`# Phase 3.5 smoke (#109) — ${new Date().toISOString()}`);
+  record(`socket: ${sock}`);
+
+  // ── done ──────────────────────────────────────────────────────────────
+  record("\n[1] task.done → CREW DONE");
+  await sendRequest(sock, { kind: "seed", record: baseRec("done-abc12345", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "p",
+    event: { type: "task.done", id: "done-abc12345", resultRef: "/tmp/r1" } });
+  const done = captured.filter((c) => c.message.startsWith("CREW DONE"));
+  assert(done.length === 1, `exactly one CREW DONE captured (got ${done.length})`);
+  assert(done[0]?.project === "p", `project=p (got ${done[0]?.project})`);
+  assert(/^CREW DONE \[claude\/done-abc/.test(done[0]?.message ?? ""),
+    `message tag matches spec: ${done[0]?.message}`);
+
+  // Re-apply done → state machine absorbs, no second notify.
+  await sendRequest(sock, { kind: "event", project: "p",
+    event: { type: "task.done", id: "done-abc12345", resultRef: "/tmp/r1" } });
+  assert(captured.filter((c) => c.message.startsWith("CREW DONE")).length === 1,
+    "redundant task.done does NOT re-notify");
+
+  // ── blocked ───────────────────────────────────────────────────────────
+  record("\n[2] task.blocked → CREW BLOCKED");
+  await sendRequest(sock, { kind: "seed", record: baseRec("blocked-1xyz", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "p",
+    event: { type: "task.blocked", id: "blocked-1xyz", reason: "need-input",
+      question: "which database backend should I target?" } });
+  const blk = captured.filter((c) => c.message.startsWith("CREW BLOCKED"));
+  assert(blk.length === 1, `exactly one CREW BLOCKED captured (got ${blk.length})`);
+  assert((blk[0]?.message ?? "").includes("which database backend"),
+    `question surfaced: ${blk[0]?.message}`);
+
+  // ── failed ────────────────────────────────────────────────────────────
+  record("\n[3] task.failed → CREW FAILED");
+  await sendRequest(sock, { kind: "seed", record: baseRec("failed-9q", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "p",
+    event: { type: "task.failed", id: "failed-9q", error: "child exited with code 137 (OOM)" } });
+  const fld = captured.filter((c) => c.message.startsWith("CREW FAILED"));
+  assert(fld.length === 1, `exactly one CREW FAILED captured (got ${fld.length})`);
+  assert((fld[0]?.message ?? "").includes("OOM"), `error surfaced: ${fld[0]?.message}`);
+
+  // ── liveness → no notify ──────────────────────────────────────────────
+  record("\n[4] task.progress / heartbeat → no notify");
+  await sendRequest(sock, { kind: "seed", record: baseRec("live-7t", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "p",
+    event: { type: "task.progress", id: "live-7t" } });
+  await sendRequest(sock, { kind: "event", project: "p",
+    event: { type: "heartbeat", id: "live-7t" } });
+  const liveCount = captured.length;
+  assert(liveCount === 3, `liveness produced 0 new notifications (total still ${liveCount})`);
+
+  // ── notifier-down resilience ──────────────────────────────────────────
+  // Stop this daemon, restart with a notify that throws — daemon must
+  // still apply events to the store.
+  record("\n[5] notifier throwing → daemon survives, store still updated");
+  handle.stop();
+  const handle2 = startSquadrantd({
+    stateRoot: join(dir, "state"),
+    sockPath: sock,
+    sweepMs: 0,
+    notify: () => { throw new Error("cmux pane crashed"); },
+  });
+  try {
+    await sendRequest(sock, { kind: "seed", record: baseRec("bang-pq", { state: "working" }) });
+    const r = await sendRequest(sock, { kind: "event", project: "p",
+      event: { type: "task.done", id: "bang-pq", resultRef: "/tmp/r-bang" } });
+    assert(r?.state === "done", `event still applied (state=${r?.state})`);
+    const after = await sendRequest(sock, { kind: "status", project: "p", id: "bang-pq" });
+    assert(after?.state === "done", `store reflects new state after throwing notify`);
+  } finally {
+    handle2.stop();
+  }
+
+  record(`\nresult: ${failures === 0 ? "PASS" : "FAIL"} (failures=${failures})`);
+} catch (err) {
+  record(`\nUNCAUGHT: ${err?.stack || err}`);
+  failures++;
+} finally {
+  try { handle.stop?.(); } catch { /* ignore */ }
+  writeFileSync(evidencePath, log.join("\n") + "\n");
+  record(`\nevidence written: ${evidencePath}`);
+  rmSync(dir, { recursive: true, force: true });
+  process.exit(failures === 0 ? 0 : 1);
+}

package/scripts/spawn-crew-pane.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Deprecated direct script — use `squadrant crew spawn <project> <task>` instead.
+# This shim forwards to the CLI for backward compat with existing call-sites.
+set -euo pipefail
+
+if [ "$#" -lt 2 ]; then
+  echo "Usage: spawn-crew-pane.sh <project> <task> [direction] [agent]" >&2
+  echo "Note: prefer 'squadrant crew spawn <project> \"<task>\"' directly." >&2
+  exit 64
+fi
+
+PROJECT="$1"
+TASK="$2"
+DIRECTION="${3:-tab}"
+AGENT="${4:-claude}"
+
+exec squadrant crew spawn "$PROJECT" "$TASK" --direction "$DIRECTION" --agent "$AGENT"