oh-my-opencode 5.0.0-beta.3 → 5.0.0-beta.30

package/.agents/command/publish.md

@@ -1,6 +1,6 @@
 ---
 description: Publish oh-my-opencode to npm via GitHub Actions workflow
-argument-hint: <patch|minor|major>
+argument-hint: <patch|minor|major|explicit-semver>
 ---
 
 
@@ -54,15 +54,16 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ## CRITICAL: ARGUMENT REQUIREMENT
 
-**You MUST receive a version bump type from the user.** Valid options:
+**You MUST receive one release selector from the user.** Valid options:
 - `patch`: Bug fixes, backward-compatible (1.1.7 → 1.1.8)
 - `minor`: New features, backward-compatible (1.1.7 → 1.2.0)
 - `major`: Breaking changes (1.1.7 → 2.0.0)
+- An explicit valid semantic version, including a prerelease such as `5.0.0-beta.9`
 
-**If the user did not provide a bump type argument, STOP IMMEDIATELY and ask:**
-> "To proceed with deployment, please specify a version bump type: `patch`, `minor`, or `major`"
+**If the user did not provide a release selector, STOP IMMEDIATELY and ask:**
+> "To proceed with deployment, specify `patch`, `minor`, `major`, or an explicit semantic version such as `5.0.0-beta.9`."
 
-**DO NOT PROCEED without explicit user confirmation of bump type.**
+Reject any other value. Do not infer or repair malformed versions.
 
 ---
 
@@ -72,7 +73,7 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ```
 [
-  { "id": "confirm-bump", "content": "Confirm version bump type with user (patch/minor/major)", "status": "in_progress", "priority": "high" },
+  { "id": "confirm-release-input", "content": "Confirm release selector with user (patch/minor/major or explicit semver)", "status": "in_progress", "priority": "high" },
   { "id": "check-uncommitted", "content": "Check for uncommitted changes and commit if needed", "status": "pending", "priority": "high" },
   { "id": "sync-remote", "content": "Sync with remote (pull --rebase && push if unpushed commits)", "status": "pending", "priority": "high" },
   { "id": "run-workflow", "content": "Trigger GitHub Actions publish workflow", "status": "pending", "priority": "high" },
@@ -92,9 +93,23 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ---
 
-## STEP 1: CONFIRM BUMP TYPE
+## STEP 1: CONFIRM AND CLASSIFY THE RELEASE SELECTOR
 
-If the user already named a bump type (argument or message), that IS the confirmation — state it and continue immediately. Only ask and wait when no bump type was given.
+If the user already supplied the selector in the command argument or message, that IS the confirmation. Parse it exactly once:
+
+```bash
+RELEASE_INPUT="${ARGUMENTS}"
+if [[ "$RELEASE_INPUT" =~ ^(patch|minor|major)$ ]]; then
+  RELEASE_KIND=bump
+elif [[ "$RELEASE_INPUT" =~ ^([0-9]+\.){2}[0-9]+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$ ]]; then
+  RELEASE_KIND=version
+else
+  echo "Invalid release selector: $RELEASE_INPUT" >&2
+  exit 1
+fi
+```
+
+Only ask and wait when no selector was provided.
 
 ---
 
@@ -125,16 +140,29 @@ This ensures the GitHub Actions workflow runs on the latest code including all l
 
 ## STEP 3: TRIGGER GITHUB ACTIONS WORKFLOW
 
-Run the publish workflow:
-```bash
-gh workflow run publish -f bump={bump_type}
-```
+Dispatch from `dev`, pass bump selectors through `bump`, and pass exact versions through `version`. The required `bump` input remains `patch` for explicit-version dispatches but is ignored by the workflow because `version` takes precedence.
 
-Wait 3 seconds, then get the run ID:
 ```bash
-gh run list --workflow=publish --limit=1 --json databaseId,status --jq '.[0]'
+if [ "$RELEASE_KIND" = bump ]; then
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f "bump=${RELEASE_INPUT}")"
+else
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f bump=patch -f "version=${RELEASE_INPUT}")"
+fi
+
+if ! [[ "$RUN_URL" =~ ^https://github.com/code-yeongyu/oh-my-openagent/actions/runs/[0-9]+$ ]]; then
+  echo "Publish dispatch did not return an exact workflow run URL: $RUN_URL" >&2
+  exit 1
+fi
+RUN_ID="${RUN_URL##*/}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "Publish dispatch returned an invalid run ID: $RUN_ID" >&2
+  exit 1
+fi
+gh run view "${RUN_ID}" --json databaseId,status,url --jq '{databaseId,status,url}'
 ```
 
+The returned run ID owns this release attempt. Never replace it with a latest-run lookup.
+
 ---
 
 ## STEP 4: WAIT FOR WORKFLOW COMPLETION
@@ -150,14 +178,14 @@ The publish run is a single workflow with sequential stages. Expected timeline (
 
 Poll job-level status every 30 seconds and report stage transitions to the user:
 ```bash
-gh run view {run_id} --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
+gh run view "${RUN_ID}" --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
 ```
 
 **IMPORTANT: Use polling loop, NOT sleep commands.** Use the waiting time to draft the enhanced release summary (Step 6) — do not sit idle, and do not start any review activity.
 
 If conclusion is `failure`, show error and stop:
 ```bash
-gh run view {run_id} --log-failed
+gh run view "${RUN_ID}" --log-failed
 ```
 
 ---

package/.agents/skills/publish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: publish
-description: "Publish oh-my-opencode to npm by triggering the GitHub Actions publish workflow and verifying its artifacts. Ship-only: never runs pre-publish-review or re-reviews merged code unless the user explicitly asks. Argument: <patch|minor|major>. Triggers: publish, release, deploy, npm publish."
+description: "Publish oh-my-opencode to npm by triggering the GitHub Actions publish workflow and verifying its artifacts. Ship-only: never runs pre-publish-review or re-reviews merged code unless the user explicitly asks. Argument: <patch|minor|major|explicit-semver>. Triggers: publish, release, deploy, npm publish."
 ---
 
 You are the release manager for oh-my-opencode. Execute the FULL publish workflow from start to finish.
@@ -53,15 +53,16 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ## CRITICAL: ARGUMENT REQUIREMENT
 
-**You MUST receive a version bump type from the user.** Valid options:
+**You MUST receive one release selector from the user.** Valid options:
 - `patch`: Bug fixes, backward-compatible (1.1.7 → 1.1.8)
 - `minor`: New features, backward-compatible (1.1.7 → 1.2.0)
 - `major`: Breaking changes (1.1.7 → 2.0.0)
+- An explicit valid semantic version, including a prerelease such as `5.0.0-beta.9`
 
-**If the user did not provide a bump type argument, STOP IMMEDIATELY and ask:**
-> "To proceed with deployment, please specify a version bump type: `patch`, `minor`, or `major`"
+**If the user did not provide a release selector, STOP IMMEDIATELY and ask:**
+> "To proceed with deployment, specify `patch`, `minor`, `major`, or an explicit semantic version such as `5.0.0-beta.9`."
 
-**DO NOT PROCEED without explicit user confirmation of bump type.**
+Reject any other value. Do not infer or repair malformed versions.
 
 ---
 
@@ -71,7 +72,7 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ```
 [
-  { "id": "confirm-bump", "content": "Confirm version bump type with user (patch/minor/major)", "status": "in_progress", "priority": "high" },
+  { "id": "confirm-release-input", "content": "Confirm release selector with user (patch/minor/major or explicit semver)", "status": "in_progress", "priority": "high" },
   { "id": "check-uncommitted", "content": "Check for uncommitted changes and commit if needed", "status": "pending", "priority": "high" },
   { "id": "sync-remote", "content": "Sync with remote (pull --rebase && push if unpushed commits)", "status": "pending", "priority": "high" },
   { "id": "run-workflow", "content": "Trigger GitHub Actions publish workflow", "status": "pending", "priority": "high" },
@@ -91,9 +92,23 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ---
 
-## STEP 1: CONFIRM BUMP TYPE
+## STEP 1: CONFIRM AND CLASSIFY THE RELEASE SELECTOR
 
-If the user already named a bump type (argument or message), that IS the confirmation — state it and continue immediately. Only ask and wait when no bump type was given.
+If the user already supplied the selector in the command argument or message, that IS the confirmation. Parse it exactly once:
+
+```bash
+RELEASE_INPUT="${ARGUMENTS}"
+if [[ "$RELEASE_INPUT" =~ ^(patch|minor|major)$ ]]; then
+  RELEASE_KIND=bump
+elif [[ "$RELEASE_INPUT" =~ ^([0-9]+\.){2}[0-9]+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$ ]]; then
+  RELEASE_KIND=version
+else
+  echo "Invalid release selector: $RELEASE_INPUT" >&2
+  exit 1
+fi
+```
+
+Only ask and wait when no selector was provided.
 
 ---
 
@@ -124,16 +139,29 @@ This ensures the GitHub Actions workflow runs on the latest code including all l
 
 ## STEP 3: TRIGGER GITHUB ACTIONS WORKFLOW
 
-Run the publish workflow:
-```bash
-gh workflow run publish -f bump={bump_type}
-```
+Dispatch from `dev`, pass bump selectors through `bump`, and pass exact versions through `version`. The required `bump` input remains `patch` for explicit-version dispatches but is ignored by the workflow because `version` takes precedence.
 
-Wait 3 seconds, then get the run ID:
 ```bash
-gh run list --workflow=publish --limit=1 --json databaseId,status --jq '.[0]'
+if [ "$RELEASE_KIND" = bump ]; then
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f "bump=${RELEASE_INPUT}")"
+else
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f bump=patch -f "version=${RELEASE_INPUT}")"
+fi
+
+if ! [[ "$RUN_URL" =~ ^https://github.com/code-yeongyu/oh-my-openagent/actions/runs/[0-9]+$ ]]; then
+  echo "Publish dispatch did not return an exact workflow run URL: $RUN_URL" >&2
+  exit 1
+fi
+RUN_ID="${RUN_URL##*/}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "Publish dispatch returned an invalid run ID: $RUN_ID" >&2
+  exit 1
+fi
+gh run view "${RUN_ID}" --json databaseId,status,url --jq '{databaseId,status,url}'
 ```
 
+The returned run ID owns this release attempt. Never replace it with a latest-run lookup.
+
 ---
 
 ## STEP 4: WAIT FOR WORKFLOW COMPLETION
@@ -149,14 +177,14 @@ The publish run is a single workflow with sequential stages. Expected timeline (
 
 Poll job-level status every 30 seconds and report stage transitions to the user:
 ```bash
-gh run view {run_id} --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
+gh run view "${RUN_ID}" --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
 ```
 
 **IMPORTANT: Use polling loop, NOT sleep commands.** Use the waiting time to draft the enhanced release summary (Step 6) — do not sit idle, and do not start any review activity.
 
 If conclusion is `failure`, show error and stop:
 ```bash
-gh run view {run_id} --log-failed
+gh run view "${RUN_ID}" --log-failed
 ```
 
 ---

package/.agents/skills/senpi-qa/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: senpi-qa
+description: "QA the omo Senpi adapter (packages/omo-senpi, packages/senpi-task) against the REAL senpi binary in strict isolation, and write every artifact to the one canonical evidence path .omo/evidence/omo-senpi-adapter/<slug>/. The live drivers under packages/omo-senpi/scripts/qa/ create their own isolated SENPI_CODING_AGENT_DIR and ignore the caller's, so the real ~/.senpi/agent is never written. Ships scripts/resolve-evidence-dir.mjs, which is the ONLY sanctioned way to pick an evidence directory: it rejects traversal, separators, absolute paths, and stray roots such as local-ignore/qa-evidence. Use whenever someone changes anything under packages/omo-senpi or packages/senpi-task, or wants to QA, smoke-test, verify, or debug the Senpi adapter, the task/team engine, the DAG, task RPC, or skill delivery. Triggers: senpi qa, qa senpi, senpi-qa, test senpi adapter, verify senpi task, senpi task e2e, senpi team e2e, task dag qa, live senpi driver, senpi evidence path."
+---
+
+# Senpi QA
+
+QA the omo Senpi adapter (`packages/omo-senpi/`) and the task engine
+(`packages/senpi-task/`) by driving the REAL `senpi` binary. Unit tests never
+count as live QA here: `bun run test:senpi` is the package gate, the drivers in
+`packages/omo-senpi/scripts/qa/` are the harness proof.
+
+## Golden rules
+
+- **Evidence lives at exactly one path.** Every artifact goes under
+  `.omo/evidence/omo-senpi-adapter/<slug>/`. Pick it with
+  `scripts/resolve-evidence-dir.mjs` and nothing else — a hand-typed path is how
+  runs end up somewhere like `local-ignore/qa-evidence/`, which no reviewer reads
+  and the PR cannot cite.
+- **The real agent dir stays untouched.** The live drivers build their own
+  isolated `SENPI_CODING_AGENT_DIR` and deliberately IGNORE a caller-provided
+  one, so `~/.senpi/agent` is never used as the sandbox. Report the driver's
+  `realSenpiUntouched` / changed-path fields and the isolated agent-dir path;
+  treat a whole-directory digest as supporting evidence, not proof by itself.
+- **No binary means SKIP, not silence.** When `senpi` is absent the live drivers
+  report `SKIP` or `FAIL` in their final JSON rather than degrading to the real
+  home. A `SKIP` is not a pass — say so in the evidence README.
+- **The captured JSON is the evidence.** No file on disk means the QA did not
+  happen, which means no commit and no push.
+
+## Resolve the evidence directory first
+
+```bash
+ev="$(node .agents/skills/senpi-qa/scripts/resolve-evidence-dir.mjs \
+  --repo-root "$(git rev-parse --show-toplevel)" --slug <YYYYMMDD>-<short-slug>)"
+mkdir -p "$ev"
+```
+
+The resolver returns an absolute path and creates nothing, so the caller decides
+when the directory appears. A slug is ONE relative segment of lowercase letters,
+digits, and hyphens (`20260820-senpi-qa-contract`). Separators, `.`/`..`,
+traversal, absolute paths, and a non-git root are rejected with a non-zero exit
+and a message naming the offending slug.
+
+## Router: pick your case
+
+| You changed… | Run | Proves |
+|---|---|---|
+| Any adapter code, as the fast precondition | `node packages/omo-senpi/scripts/qa/drive.mjs --self-test` | the driver + isolation harness itself works |
+| Adapter wiring reaching a live session | `node packages/omo-senpi/scripts/qa/drive.mjs` | a real senpi run with the plugin loaded, isolated agent dir, and no attributed real-home changes |
+| Task lifecycle (single + batch) | `SENPI_BIN="$(command -v senpi)" node packages/omo-senpi/scripts/qa/task-e2e.mjs` | live task start/stream/terminal states |
+| Team delivery, shutdown, reclaim, restart recovery | `SENPI_BIN="$(command -v senpi)" node packages/omo-senpi/scripts/qa/team-e2e.mjs` | injection delivery and exactly-once recovery |
+| Task RPC driver scripts | `node packages/omo-senpi/scripts/qa/task-rpc-e2e.mjs --self-test` | the RPC surface contract |
+| Skill delivery into a task | `SENPI_BIN="$(command -v senpi)" node packages/omo-senpi/scripts/qa/task-load-skills-e2e.mjs` | skills reach the child |
+| Continuation behavior | `node packages/omo-senpi/scripts/qa/probe-continuation.mjs` | turns continue as expected |
+| DAG state machine / runners | `bun test packages/senpi-task` | unit + chaos invariants (NOT live proof) |
+
+Point a driver's output at the resolved directory, e.g.:
+
+```bash
+TASK_E2E_OUT_DIR="$ev/live-task-dag" SENPI_BIN="$(command -v senpi)" \
+  node packages/omo-senpi/scripts/qa/task-e2e.mjs
+```
+
+## Package gate
+
+```bash
+tsgo --noEmit -p packages/omo-senpi/tsconfig.json
+bun run test:senpi
+```
+
+## Write the evidence README
+
+Every run leaves `$ev/README.md` a reviewer can read without rerunning anything.
+The required sections are the repo-wide evidence rules in the root
+[`AGENTS.md`](../../../AGENTS.md) (what was tested / observed / why it is enough /
+what was omitted). For Senpi, record the driver's changed-path/isolation fields
+and sandbox agent-dir path. Some drivers report sandbox paths without removing
+them; the caller must delete every task-owned sandbox and verify child PIDs are
+terminal before writing the cleanup receipt.

package/.agents/skills/senpi-qa/scripts/resolve-evidence-dir.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// resolve-evidence-dir.mjs - pick the canonical evidence directory for a live Senpi QA run.
+//
+// Live Senpi QA artifacts belong under .omo/evidence/omo-senpi-adapter/<slug>/ and nowhere else.
+// That path is the repository-standard location every reviewer and AGENTS.md rule points at, so a
+// hand-typed alternative (local-ignore/qa-evidence/..., a temp dir, a traversal) silently strands
+// the evidence where the PR cannot cite it. Resolving through this script makes the path a checked
+// contract instead of a convention.
+//
+// The resolver COMPUTES and VALIDATES only; creating the directory stays the caller's decision, so
+// a rejected slug never leaves a stray directory behind.
+//
+//   node resolve-evidence-dir.mjs --repo-root "$(git rev-parse --show-toplevel)" --slug 20260820-my-run
+//
+// Prints the absolute path to stdout. Exit 0 iff the root is a git worktree and the slug is safe.
+import { existsSync, realpathSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const EVIDENCE_RELATIVE_ROOT = join(".omo", "evidence", "omo-senpi-adapter")
+
+// One relative segment: lowercase alphanumerics joined by single hyphens. This is what makes the
+// path predictable - it also rejects every separator, traversal, and absolute form outright, since
+// none of them can match.
+const SAFE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/**
+ * @param {{ repoRoot: string, slug: string }} input
+ * @returns {string} absolute evidence directory; NOT created
+ */
+export function resolveEvidenceDir({ repoRoot, slug }) {
+  if (typeof repoRoot !== "string" || repoRoot.length === 0) {
+    throw new Error("repoRoot must be a non-empty path to a git worktree")
+  }
+  if (!existsSync(join(repoRoot, ".git"))) {
+    throw new Error(`repoRoot is not a git worktree: ${repoRoot}`)
+  }
+  if (typeof slug !== "string" || !SAFE_SLUG.test(slug)) {
+    throw new Error(
+      `slug must be one lowercase alphanumeric-and-hyphen segment (got ${JSON.stringify(slug)}); ` +
+        `evidence lives under ${EVIDENCE_RELATIVE_ROOT}/<slug>`,
+    )
+  }
+  return resolve(repoRoot, EVIDENCE_RELATIVE_ROOT, slug)
+}
+
+const isDirectRun =
+  process.argv[1] !== undefined &&
+  existsSync(process.argv[1]) &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+
+if (isDirectRun) {
+  const args = process.argv.slice(2)
+  const read = (flag) => {
+    const at = args.indexOf(flag)
+    return at === -1 ? undefined : args[at + 1]
+  }
+  try {
+    const dir = resolveEvidenceDir({ repoRoot: read("--repo-root") ?? process.cwd(), slug: read("--slug") })
+    process.stdout.write(`${dir}\n`)
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  }
+}

package/.agents/skills/senpi-qa/scripts/resolve-evidence-dir.test.mjs

@@ -0,0 +1,171 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, relative } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+import { EVIDENCE_RELATIVE_ROOT, resolveEvidenceDir } from "./resolve-evidence-dir.mjs"
+
+const cleanupRoots = []
+const cliPath = fileURLToPath(new URL("./resolve-evidence-dir.mjs", import.meta.url))
+
+afterEach(() => {
+  for (const root of cleanupRoots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function makeGitRoot() {
+  const root = mkdtempSync(join(tmpdir(), "senpi-qa-evidence-"))
+  cleanupRoots.push(root)
+  mkdirSync(join(root, ".git"))
+  return root
+}
+
+describe("resolveEvidenceDir", () => {
+  test("#given a git worktree and a safe slug #when resolved #then it returns the canonical adapter evidence directory", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when
+    const resolved = resolveEvidenceDir({ repoRoot, slug: "20260820-senpi-qa-contract" })
+
+    // then
+    expect(resolved).toBe(join(repoRoot, ".omo", "evidence", "omo-senpi-adapter", "20260820-senpi-qa-contract"))
+  })
+
+  test("#given a relative git worktree path #when resolved #then it still returns an absolute evidence directory", () => {
+    // given
+    const repoRoot = makeGitRoot()
+    const relativeRoot = relative(process.cwd(), repoRoot)
+
+    // when
+    const resolved = resolveEvidenceDir({ repoRoot: relativeRoot, slug: "20260820-relative-root" })
+
+    // then
+    expect(resolved).toBe(join(repoRoot, ".omo", "evidence", "omo-senpi-adapter", "20260820-relative-root"))
+  })
+
+  test("#given a resolved evidence path #when the resolver returns #then it has created no directory", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when
+    const resolved = resolveEvidenceDir({ repoRoot, slug: "20260820-senpi-qa-contract" })
+
+    // then
+    expect(existsSync(resolved)).toBe(false)
+    expect(existsSync(join(repoRoot, ".omo"))).toBe(false)
+  })
+
+  test("#given the adapter evidence root #when it is the declared relative root #then it stays under .omo/evidence", () => {
+    // given / when / then
+    expect(EVIDENCE_RELATIVE_ROOT).toBe(join(".omo", "evidence", "omo-senpi-adapter"))
+  })
+
+  test("#given an unsafe slug #when resolved #then it is rejected before any path is produced", () => {
+    // given
+    const repoRoot = makeGitRoot()
+    const unsafeSlugs = [
+      "",
+      "   ",
+      ".",
+      "..",
+      "../escape",
+      "nested/slug",
+      "nested\\slug",
+      "/absolute",
+      join(repoRoot, "absolute"),
+      "local-ignore/qa-evidence/20260819-senpi",
+      "..%2Fescape",
+      "-leading-hyphen",
+      "trailing-hyphen-",
+      "Upper-Case",
+      "under_score",
+    ]
+
+    // when / then
+    for (const slug of unsafeSlugs) {
+      expect(() => resolveEvidenceDir({ repoRoot, slug }), `must reject ${JSON.stringify(slug)}`).toThrow()
+    }
+  })
+
+  test("#given a directory that is not a git worktree #when resolved #then it is rejected", () => {
+    // given
+    const notARepo = mkdtempSync(join(tmpdir(), "senpi-qa-not-git-"))
+    cleanupRoots.push(notARepo)
+
+    // when / then
+    expect(() => resolveEvidenceDir({ repoRoot: notARepo, slug: "20260820-senpi-qa-contract" })).toThrow(/git/i)
+  })
+
+  test("#given a rejected slug #when the error surfaces #then it names the offending slug for the operator", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when / then
+    expect(() => resolveEvidenceDir({ repoRoot, slug: "local-ignore/qa-evidence/x" })).toThrow(
+      /local-ignore\/qa-evidence\/x/,
+    )
+  })
+
+  test("#given the documented Node CLI #when valid and invalid slugs run #then stdout and exit codes enforce the contract", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when
+    const valid = spawnSync("node", [cliPath, "--repo-root", repoRoot, "--slug", "20260820-node-cli"], {
+      encoding: "utf8",
+    })
+    const invalid = spawnSync(
+      "node",
+      [cliPath, "--repo-root", repoRoot, "--slug", "local-ignore/qa-evidence/x"],
+      { encoding: "utf8" },
+    )
+
+    // then
+    expect(valid.status).toBe(0)
+    expect(valid.stdout.trim()).toBe(join(repoRoot, EVIDENCE_RELATIVE_ROOT, "20260820-node-cli"))
+    expect(invalid.status).toBe(1)
+    expect(invalid.stderr).toContain("local-ignore/qa-evidence/x")
+  })
+
+  test("#given a symlink to the documented Node CLI #when invoked #then the entrypoint still enforces the contract", () => {
+    // given
+    const repoRoot = makeGitRoot()
+    const symlinkPath = join(repoRoot, "resolve-evidence-dir.mjs")
+    symlinkSync(cliPath, symlinkPath)
+
+    // when
+    const result = spawnSync(
+      "node",
+      [symlinkPath, "--repo-root", repoRoot, "--slug", "20260820-symlink-cli"],
+      { encoding: "utf8" },
+    )
+
+    // then
+    expect(result.status).toBe(0)
+    expect(result.stdout.trim()).toBe(join(repoRoot, EVIDENCE_RELATIVE_ROOT, "20260820-symlink-cli"))
+  })
+
+  test("#given an embedding runner with a missing argv path #when the module is imported #then exports still load", () => {
+    // given
+    const missingEntrypoint = join(tmpdir(), `missing-senpi-qa-entrypoint-${process.pid}.mjs`)
+    const moduleUrl = pathToFileURL(cliPath).href
+
+    // when
+    const result = spawnSync(
+      "node",
+      [
+        "--input-type=module",
+        "--eval",
+        `process.argv[1] = ${JSON.stringify(missingEntrypoint)}; await import(${JSON.stringify(moduleUrl)})`,
+      ],
+      { encoding: "utf8" },
+    )
+
+    // then
+    expect(result.status).toBe(0)
+    expect(result.stdout).toBe("")
+    expect(result.stderr).toBe("")
+  })
+})

package/.agents/skills/work-with-pr/SKILL.md

@@ -196,12 +196,20 @@ while true:
 
 ### Gate A: CI Checks
 
-CI is the fastest feedback loop. Wait for it to complete, then parse results.
+CI is the fastest feedback loop. Subscribe to its completion via `monitor` — never block a model round-trip on `gh pr checks --watch`.
 
-```bash
-# Wait for checks to start (GitHub needs a moment after push)
-# Then watch for completion
-gh pr checks "$PR_NUMBER" --watch --fail-fast
+```
+# Subscribe to CI completion — the monitor event wakes the session when checks finish.
+# Do NOT use `gh pr checks --watch` as a blocking tool call; it burns a full model
+# round-trip (~29s) on every poll. Instead, register a monitor and end the turn:
+monitor({
+  description: "CI completion for PR $PR_NUMBER",
+  command: "gh pr checks $PR_NUMBER --watch --fail-fast",
+  filter: "completed|fail|cancel"
+})
+# → end turn; the monitor's matching line arrives as an injected event.
+# For a single midpoint status peek (at most once), use:
+#   gh pr checks "$PR_NUMBER"  # one-shot, no --watch
 ```
 
 **On failure**: Get the failed run logs to understand what broke:
@@ -243,20 +251,21 @@ fi
 
 **On issues**: Cubic's review body contains structured issue descriptions. Parse them, determine which are valid (some may be false positives), and fix the valid ones per the iteration discipline below.
 
-Cubic reviews are triggered automatically on PR updates. After pushing a fix, wait for the new review to appear before checking again. Use `gh api` polling with a conditional loop:
+Cubic reviews are triggered automatically on PR updates. After pushing a fix, subscribe to the new review arriving — never spin a `for _ in $(seq 1 30)` polling loop that burns model round-trips.
 
-```bash
-# Wait for a NEW Cubic review after push. If none arrives within the bound,
-# Cubic is out of quota (or not running) → skip Gate B rather than spin forever.
+```
+# Subscribe to a NEW Cubic review after push. The monitor exits when a review
+# newer than PUSH_TIME appears, or times out (quota exhausted → Gate B SKIPPED).
 PUSH_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-for _ in $(seq 1 30); do
-  LATEST_REVIEW_TIME=$(gh api "repos/${REPO}/pulls/${PR_NUMBER}/reviews" \
-    --jq '[.[] | select(.user.login == "cubic-dev-ai[bot]")] | last | .submitted_at')
-  [[ "$LATEST_REVIEW_TIME" > "$PUSH_TIME" ]] && break
-  timeout 20 gh pr checks "$PR_NUMBER" --watch >/dev/null 2>&1 || true  # spend the interval usefully
-done
-# Loop exhausted without a newer review → treat Gate B as SKIPPED (quota exhausted)
-[[ "$LATEST_REVIEW_TIME" > "$PUSH_TIME" ]] || echo "Cubic: SKIPPED (no review within bound — quota exhausted)"
+monitor({
+  description: "Cubic review for PR $PR_NUMBER",
+  command: "LATEST=$(gh api repos/${REPO}/pulls/${PR_NUMBER}/reviews --jq '[.[] | select(.user.login == "cubic-dev-ai[bot]")] | last | .submitted_at // empty'); [ -n \"$LATEST\" ] && [ \"$LATEST\" > \"$PUSH_TIME\" ] && echo NEW_REVIEW || echo WAITING",
+  filter: "NEW_REVIEW",
+  timeout_ms: 600000   # 10 min bound — if no review arrives, Gate B is SKIPPED (quota exhausted)
+})
+# → end turn; if the monitor times out without NEW_REVIEW, treat Gate B as SKIPPED.
+# For a single midpoint peek (at most once), use:
+#   gh api "repos/${REPO}/pulls/${PR_NUMBER}/reviews" --jq '[.[] | select(.user.login == "cubic-dev-ai[bot]")] | last | .submitted_at'
 ```
 
 ### Iteration discipline
@@ -292,13 +301,18 @@ gh pr merge "$PR_NUMBER" --merge --auto --delete-branch
 # are green, fall back to a direct merge: gh pr merge "$PR_NUMBER" --merge --delete-branch
 ```
 
-Then WAIT until the merge has actually completed before you report done or clean up - never walk away while the PR is still merging:
+Then subscribe to the merge completing — never block a model round-trip on an `until [ ... MERGED ]` polling loop:
 
-```bash
-# Block until the PR is actually MERGED (auto-merge lands once all required checks pass)
-until [ "$(gh pr view "$PR_NUMBER" --json state -q .state)" = "MERGED" ]; do
-  gh pr checks "$PR_NUMBER" --watch --fail-fast >/dev/null 2>&1 || true   # spend the interval on the checks
-done
+```
+# Subscribe to merge completion. The monitor exits when gh pr view returns MERGED.
+monitor({
+  description: "Merge completion for PR $PR_NUMBER",
+  command: "[ \"$(gh pr view $PR_NUMBER --json state -q .state)\" = \"MERGED\" ] && echo MERGED || echo WAITING",
+  filter: "MERGED",
+  timeout_ms: 1800000   # 30 min bound for auto-merge to land after all gates pass
+})
+# → end turn; the MERGED event wakes the session for the cleanup step.
+# If the monitor times out, check merge state once: gh pr view "$PR_NUMBER" --json state -q .state
 ```
 
 If the user opted out of merging, skip the merge but STILL run the cleanup below: the worktree is removed either way.