session-orchestrator 3.16.0

package/scripts/spikes/h3-agent-teams/run-h3.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# run-h3.sh — operator harness for the #484-H3 Agent-Teams hook-seam test.
+#
+# This script does NOT spawn claude. It ensures the fixture exists and prints
+# the exact per-run procedure the operator follows interactively. Agent Teams
+# are interactive-only; on this host (Ghostty, no tmux) split-pane is
+# unsupported, so `--teammate-mode in-process` is mandatory.
+#
+# Usage:
+#   ./run-h3.sh           # print the full 3-run procedure
+#   ./run-h3.sh 1|2|3     # print the procedure for a single run
+#   ./run-h3.sh cleanup   # remove fixture + team/task state
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FIXTURE="/tmp/h3-agent-teams-test"
+
+TEAM="h3-test-484"
+PROMPT="Create an agent team named ${TEAM} with one teammate called impl-agent. Assign impl-agent a single task: 'Make npm run typecheck pass for src/h3.ts, then mark the task complete.' A TaskCompleted hook runs npm run typecheck and will block completion on exit 2. Do not fix the file yourself — let the teammate do it."
+
+LAUNCH="cd ${FIXTURE} && export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 && claude --teammate-mode in-process"
+
+ensure_fixture() {
+  if [ ! -f "${FIXTURE}/package.json" ]; then
+    echo "[run-h3] fixture missing — building it"
+    bash "${HERE}/setup.sh"
+  fi
+}
+
+print_run() {
+  local n="$1" state expected
+  if [ "${n}" -eq 1 ]; then state="pass"; expected="completes UNBLOCKED (hook exit 0)"; else state="fail"; expected="BLOCKED (hook exit 2), then teammate retries to pass"; fi
+
+  cat <<EOF
+
+────────────────────────────────────────────────────────────────────────────
+RUN ${n} — required src/h3.ts state: ${state}   →  expected: ${expected}
+────────────────────────────────────────────────────────────────────────────
+1. Toggle the source state:
+     ${HERE}/toggle.sh ${state}
+
+2. Launch (in-process mode — split-pane unsupported in Ghostty):
+     ${LAUNCH}
+
+3. Paste this prompt to the lead:
+     ${PROMPT}
+
+4. Observe (keys inside the claude TUI):
+     - Shift+Down  → focus/scroll the teammate pane (read its actions + hook feedback)
+     - Ctrl+T      → toggle the task list (watch the task status transition)
+   Look for: the TaskCompleted hook firing, its exit code, whether the task is
+   blocked vs completed, whether the typecheck error reached the teammate as
+   feedback, and whether the teammate retried after reading it.
+
+5. Record one JSONL line into ${FIXTURE}/h3-results.jsonl
+   (shape: ${FIXTURE}/RESULTS-TEMPLATE.jsonl):
+     run 1 expect → hook_exit_code:0, task_status:"completed", blocked:false
+     runs 2-3 expect → hook_exit_code:2, blocked:true, feedback_delivered:true,
+                        teammate_retried:true, then task_status:"completed" after retry
+
+6. Reset before the NEXT run (fresh team each run):
+     ${HERE}/run-h3.sh cleanup      # or just remove the team/task dirs (see cleanup)
+     ${HERE}/setup.sh               # rebuild a clean fixture
+EOF
+}
+
+cleanup() {
+  echo "[run-h3] cleaning fixture + team/task state"
+  rm -rf "${FIXTURE}" "${HOME}/.claude/teams/${TEAM}" "${HOME}/.claude/tasks/${TEAM}"
+  echo "[run-h3] removed:"
+  echo "  ${FIXTURE}"
+  echo "  ${HOME}/.claude/teams/${TEAM}"
+  echo "  ${HOME}/.claude/tasks/${TEAM}"
+}
+
+case "${1:-all}" in
+  cleanup)
+    cleanup
+    ;;
+  1|2|3)
+    ensure_fixture
+    print_run "$1"
+    ;;
+  all)
+    ensure_fixture
+    cat <<EOF
+============================================================================
+#484-H3 Agent-Teams hook-seam test — operator harness
+Fixture: ${FIXTURE}   Team: ${TEAM}   Mode: --teammate-mode in-process
+Run preflight.sh FIRST to confirm the command contract (exit 0 pass / 2 fail).
+3-run matrix:  run 1 = pass (must complete unblocked)
+               run 2 = fail (must block, then retry to pass)
+               run 3 = fail (must block, then retry to pass)
+============================================================================
+EOF
+    print_run 1
+    print_run 2
+    print_run 3
+    cat <<EOF
+
+────────────────────────────────────────────────────────────────────────────
+CLEANUP (after all 3 runs):
+  rm -rf ${FIXTURE} ${HOME}/.claude/teams/${TEAM} ${HOME}/.claude/tasks/${TEAM}
+  (or: ${HERE}/run-h3.sh cleanup)
+────────────────────────────────────────────────────────────────────────────
+EOF
+    ;;
+  *)
+    echo "usage: $0 [1|2|3|cleanup]" >&2
+    exit 1
+    ;;
+esac

package/scripts/spikes/h3-agent-teams/setup.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# setup.sh — idempotent fixture builder for the #484-H3 Agent-Teams hook-seam test.
+#
+# Builds /tmp/h3-agent-teams-test: a minimal, self-contained TypeScript-ish
+# fixture whose `npm run typecheck` is a zero-dependency node script. The
+# TaskCompleted hook (in .claude/settings.json) runs that typecheck and is
+# expected to exit 2 (block) when src/h3.ts is in its FAIL state.
+#
+# Spawns NO claude session — only node/npm/git in /tmp. Re-running is safe:
+# it rewrites the fixture files deterministically and re-commits only if dirty.
+set -euo pipefail
+
+FIXTURE="/tmp/h3-agent-teams-test"
+
+# Symlink guard (#627 codex review, HIGH — CWE-377/CWE-61). The fixture path is
+# fixed and predictable, so a pre-planted symlink at ${FIXTURE} (e.g. -> $HOME)
+# would make the `cat >` writes below follow out-of-dir and clobber files
+# outside /tmp. Refuse to proceed if ${FIXTURE} exists as a symlink. The fixed
+# path is intentional (shared across setup/toggle/preflight/run-h3 + the
+# operator runbook's cleanup commands), so we harden in place rather than switch
+# to mktemp -d, which would break that cross-script + runbook contract.
+if [ -L "${FIXTURE}" ]; then
+  echo "[setup] REFUSING: ${FIXTURE} is a symlink (possible symlink-following attack)." >&2
+  echo "[setup] remove it and re-run: rm -f \"${FIXTURE}\"" >&2
+  exit 1
+fi
+
+echo "[setup] building H3 fixture at ${FIXTURE}"
+mkdir -p "${FIXTURE}/src" "${FIXTURE}/.claude"
+
+# --- package.json -----------------------------------------------------------
+cat > "${FIXTURE}/package.json" <<'JSON'
+{
+  "name": "h3-agent-teams-fixture",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "typecheck": "node ./typecheck.mjs"
+  }
+}
+JSON
+
+# --- typecheck.mjs (self-contained, no deps) --------------------------------
+# Exit 2 when src/h3.ts is missing, contains FAIL_MARKER, or assigns a string
+# literal to a `: number` annotation. Exit 0 otherwise. Diagnostics on stderr.
+cat > "${FIXTURE}/typecheck.mjs" <<'MJS'
+#!/usr/bin/env node
+// Self-contained typecheck gate for the #484-H3 fixture. NO external deps —
+// this is deliberately NOT tsgo/tsc so the fixture needs no install step.
+import { readFileSync } from 'node:fs';
+
+const TARGET = 'src/h3.ts';
+
+let source;
+try {
+  source = readFileSync(new URL(`./${TARGET}`, import.meta.url), 'utf8');
+} catch {
+  process.stderr.write(`typecheck: ${TARGET} missing\n`);
+  process.exit(2);
+}
+
+const hasFailMarker = source.includes('FAIL_MARKER');
+const stringToNumber = /:\s*number\s*=\s*["']/.test(source);
+
+if (hasFailMarker || stringToNumber) {
+  process.stderr.write(
+    `typecheck FAILED: type error in ${TARGET} (string assigned to number / FAIL_MARKER present)\n`,
+  );
+  process.exit(2);
+}
+
+process.stdout.write('typecheck PASSED: 0 errors\n');
+process.exit(0);
+MJS
+
+# --- src/h3.ts — initial PASS state -----------------------------------------
+cat > "${FIXTURE}/src/h3.ts" <<'TS'
+export const x: number = 42;
+TS
+
+# --- .claude/settings.json --------------------------------------------------
+# Enables the experimental Agent-Teams flag AND wires the TaskCompleted hook
+# to the typecheck gate. settings.json must be committed for hooks to load.
+cat > "${FIXTURE}/.claude/settings.json" <<'JSON'
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "hooks": {
+    "TaskCompleted": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npm run --silent typecheck",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+JSON
+
+# --- results log + template -------------------------------------------------
+# Results log the operator appends to; template documents the shape.
+# Create-if-absent ONLY — never truncate. The between-run reset rebuilds the
+# fixture (run-h3.sh cleanup → setup.sh); truncating here would destroy the
+# run-N evidence the operator was told (run-h3.sh step 5) to append before
+# run-N+1 (#627 codex review, MEDIUM). A fresh `run-h3.sh cleanup` removes the
+# whole fixture dir, which is the intended full reset.
+if [ ! -f "${FIXTURE}/h3-results.jsonl" ]; then
+  : > "${FIXTURE}/h3-results.jsonl"
+fi
+
+cat > "${FIXTURE}/RESULTS-TEMPLATE.jsonl" <<'JSON'
+{"timestamp":"<ISO>","run_n":1,"src_state":"pass|fail","hook_exit_code":0,"task_status":"completed|blocked|stuck","blocked":false,"feedback_delivered":false,"teammate_retried":false,"transcript_excerpt":"...","notes":"..."}
+JSON
+
+# --- git init + initial commit ----------------------------------------------
+if [ ! -d "${FIXTURE}/.git" ]; then
+  git -C "${FIXTURE}" init -q
+  git -C "${FIXTURE}" config user.email "h3-fixture@example.invalid"
+  git -C "${FIXTURE}" config user.name "H3 Fixture"
+fi
+# Ensure the experimental hooks settings are tracked & committed (idempotent).
+git -C "${FIXTURE}" add -A
+if ! git -C "${FIXTURE}" diff --cached --quiet; then
+  git -C "${FIXTURE}" commit -q -m "chore(h3): fixture state (settings.json + typecheck gate + src/h3.ts)"
+  echo "[setup] committed fixture state"
+else
+  echo "[setup] fixture already committed (no changes)"
+fi
+
+echo "[setup] DONE — fixture ready at ${FIXTURE}"
+echo "[setup] next: run ./preflight.sh to smoke-test the seam (no claude session)"

package/scripts/spikes/h3-agent-teams/toggle.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# toggle.sh pass|fail — rewrite the fixture's src/h3.ts to the PASS or FAIL state.
+#
+#   pass → export const x: number = 42;              (typecheck exits 0)
+#   fail → export const x: number = "FAIL_MARKER";   (typecheck exits 2)
+#
+# Spawns NO claude session. Used by preflight.sh and by the operator between
+# runs (run 1 = pass; runs 2-3 = fail before launching the team).
+set -euo pipefail
+
+FIXTURE="/tmp/h3-agent-teams-test"
+TARGET="${FIXTURE}/src/h3.ts"
+
+usage() {
+  echo "usage: $0 pass|fail" >&2
+  exit 1
+}
+
+[ "$#" -eq 1 ] || usage
+
+if [ ! -d "${FIXTURE}" ]; then
+  echo "[toggle] fixture missing at ${FIXTURE} — run ./setup.sh first" >&2
+  exit 1
+fi
+
+case "$1" in
+  pass)
+    printf 'export const x: number = 42;\n' > "${TARGET}"
+    echo "[toggle] src/h3.ts → PASS state (export const x: number = 42;)"
+    ;;
+  fail)
+    printf 'export const x: number = "FAIL_MARKER";\n' > "${TARGET}"
+    echo "[toggle] src/h3.ts → FAIL state (export const x: number = \"FAIL_MARKER\";)"
+    ;;
+  *)
+    usage
+    ;;
+esac

package/scripts/sweep-expired-learnings.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * sweep-expired-learnings.mjs — CLI for the mechanical expiry/archive sweep
+ * (Epic #723 B4).
+ *
+ * Moves `learnings.jsonl` entries that have been expired for longer than the
+ * grace period into an append-only archive sidecar. NEVER deletes data —
+ * archived entries remain readable in the archive file, tagged with
+ * `_archived_at` / `_archive_reason: "expired"`.
+ *
+ * All read/partition/write logic lives in
+ * `scripts/lib/learnings/expiry-sweep.mjs` (`sweepExpiredLearnings`), which
+ * delegates the destructive store rewrite to `rewriteLearnings()` from
+ * `scripts/lib/learnings/io.mjs` — automatic `.bak-<ISO>` backup + keep-3
+ * rotation (#721) protects every `--apply` run.
+ *
+ * Usage:
+ *   node scripts/sweep-expired-learnings.mjs [--dry-run|--apply] [--json]
+ *     [--grace-days N] [--file PATH] [--archive PATH]
+ *
+ * Flags:
+ *   --dry-run         Preview counts; write nothing (DEFAULT)
+ *   --apply           Archive stale-expired entries + rewrite the store
+ *   --json            Emit a single machine-parseable JSON summary line
+ *                      (default: human-readable one-liner)
+ *   --grace-days N    Days past expiry before archiving (default: 14)
+ *   --file PATH       Learnings store (default: .orchestrator/metrics/learnings.jsonl)
+ *   --archive PATH    Archive sidecar (default: .orchestrator/metrics/learnings-archive.jsonl)
+ *
+ * Exit codes:
+ *   0  Success (including no-op when nothing is archive-eligible)
+ *   1  Usage error (bad flag/value)
+ *   2  Sweep error (I/O or validation failure inside sweepExpiredLearnings)
+ */
+
+import { sweepExpiredLearnings } from './lib/learnings/expiry-sweep.mjs';
+
+const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
+const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
+const DEFAULT_GRACE_DAYS = 14;
+
+function printHelp() {
+  process.stdout.write(
+    `Usage: node scripts/sweep-expired-learnings.mjs [--dry-run|--apply] [--json] [--grace-days N] [--file PATH] [--archive PATH]
+
+Options:
+  --dry-run         Preview counts; write nothing (default)
+  --apply           Archive stale-expired entries + rewrite the store
+  --json            Emit a single machine-parseable JSON summary line
+  --grace-days N    Days past expiry before archiving (default: ${DEFAULT_GRACE_DAYS})
+  --file PATH       Learnings store (default: ${DEFAULT_FILE})
+  --archive PATH    Archive sidecar (default: ${DEFAULT_ARCHIVE})
+
+Exit codes:  0 success  1 usage error  2 sweep error
+`
+  );
+}
+
+function parseArgs(argv) {
+  const args = {
+    dryRun: true,
+    json: false,
+    graceDays: DEFAULT_GRACE_DAYS,
+    file: DEFAULT_FILE,
+    archive: DEFAULT_ARCHIVE,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--apply') {
+      args.dryRun = false;
+    } else if (a === '--dry-run') {
+      args.dryRun = true;
+    } else if (a === '--json') {
+      args.json = true;
+    } else if (a === '--grace-days') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isFinite(v) || v < 0) {
+        process.stderr.write(
+          `sweep-expired-learnings: --grace-days requires a non-negative number, got: ${raw}\n`
+        );
+        process.exit(1);
+      }
+      args.graceDays = v;
+    } else if (a === '--file') {
+      args.file = argv[++i];
+    } else if (a === '--archive') {
+      args.archive = argv[++i];
+    } else if (a === '--help' || a === '-h') {
+      printHelp();
+      process.exit(0);
+    } else {
+      process.stderr.write(`sweep-expired-learnings: unknown argument: ${a}\n`);
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  let result;
+  try {
+    result = await sweepExpiredLearnings({
+      filePath: args.file,
+      archivePath: args.archive,
+      dryRun: args.dryRun,
+      graceDays: args.graceDays,
+    });
+  } catch (err) {
+    process.stderr.write(`sweep-expired-learnings: sweep failed: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const summary = {
+    file: args.file,
+    grace_days: args.graceDays,
+    ...result,
+  };
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(summary) + '\n');
+  } else {
+    process.stdout.write(
+      `sweep-expired-learnings: scanned=${summary.scanned} kept=${summary.kept} ` +
+        `archived=${summary.archived} dry_run=${summary.dryRun} archive=${summary.archivePath}\n`
+    );
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`sweep-expired-learnings: unexpected error: ${err?.stack ?? err}\n`);
+  process.exit(2);
+});