@jentrix/runner 0.5.3

package/README.md

@@ -0,0 +1,385 @@
+# Jentrix reference agents
+
+## Install the self-hosted workflow runner
+
+`agents/` is the single distributable runner artifact; its bundle contains the
+existing workflow runner and both provider adapters. Install it beside the
+matching Jentrix CLI (Node 20+):
+
+```bash
+npm install -g @jentrix/cli@0.4.0 @jentrix/runner@0.4.0
+jentrix login
+claude auth login   # and/or: codex login
+jentrix runner doctor
+jentrix runner setup --workspace my-workspace --runtime claude # or: codex
+jentrix runner up              # foreground
+jentrix runner up --once       # drain, then exit
+```
+
+Setup is preview-first and never installs a provider CLI, automates provider
+login, publishes a release, resolves an approval, or launches work. It writes
+`~/.config/stacks/runner.json` atomically at mode `0600`, using the existing
+worker enrollment/bootstrap/attestation identities. The file contains revocable
+credentials: do not copy or log it. Claude/Codex account identity is not printed
+or stored, probes make no model call, and orchestration credentials are scrubbed
+from provider child environments. See the [CLI local runner guide](../docs/cli.md#local-workflow-runner)
+for every blocker and the protocol compatibility matrix.
+Packaged polling binds the inherited webhook listener to loopback; SIGINT/SIGTERM
+stop new claims, drain active work, and exit without changing runner config.
+
+Small agents that operate Jentrix through the **same public surface any third-party agent gets** — same auth, scopes, and contracts. They exist to dogfood the agent platform end-to-end (P4.2) and double as living documentation: if a platform contract breaks, these break. Most (`standup`, `bug-triage`, `crm-follow-up`, `workflow-runner`) drive the **MCP tool surface** directly. One — `cli-standup` — is the deliberate exception: it drives the [`jentrix` CLI](../docs/cli.md) from **bash only** (no `mcp__jentrix__*` tools), proving the CLI is a first-class, low-context agent substrate over that same surface.
+
+They run on either of two interchangeable runtimes (same prompts, same MCP server, same attribution badges — the platform is runtime-neutral):
+
+| `STACKS_AGENT_PROVIDER` | Runtime | Auth |
+| --- | --- | --- |
+| `claude` (default) | [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript) | `ANTHROPIC_API_KEY` |
+| `codex` | [OpenAI Codex SDK](https://developers.openai.com/codex/sdk) | `codex login` — your **ChatGPT subscription**, no API key |
+
+For the MCP-direct agents, the Codex runtime injects the Jentrix MCP server per-run via config overrides (your `~/.codex/config.toml` is never edited) and runs with the shell tool disabled and a read-only sandbox, so both runtimes see the same world: Jentrix tools only. **The `cli-standup` agent is the exception** — it deliberately injects no MCP server and, on Codex, keeps the shell enabled under a `workspace-write` sandbox (it needs a shell to run `jentrix`); its own section below covers that runtime and its security model in full.
+
+This is a **standalone package** — it is not part of the app's dependency tree, build, or CI. Install and run it separately:
+
+```bash
+cd agents
+pnpm install
+cp .env.example .env   # fill in STACKS_TOKEN (+ ANTHROPIC_API_KEY, or set STACKS_AGENT_PROVIDER=codex)
+```
+
+`tsx` loads nothing automatically — export the env vars (`set -a; source .env; set +a`) or run via `node --env-file=.env --import tsx <agent>.ts`. The two `workflow-runner` scripts are the exception: they load `.env`, stamp `STACKS_APP_REVISION` from the checkout's current Git HEAD on every launch, and derive `STACKS_SCHEMA_REVISION` from this checkout's newest `prisma/migrations` directory at start-up — so maintain **neither** value in `.env`. Set one only to pin a rollback. The runner also refuses to start when a configured checkout cannot ground a stage (parked on a `harness/` branch, detached, behind upstream, or the wrong repo); `STACKS_RUNNER_ALLOW_STALE_CHECKOUT=1` overrides the first two. Both stamps and the control plane's `/api/health` verdict are logged in the first few lines of start-up output.
+
+## Setup: mint a token
+
+On `/account/tokens`, create a PAT per agent with least privilege:
+
+| Agent | Scopes | Identity suggestion |
+| --- | --- | --- |
+| `standup` | `read` | 📋 Standup Bot |
+| `cli-standup` | `read` | 📋 CLI Standup Bot |
+| `bug-triage` | `read`, `write` | 🐛 Triage Bot |
+| `crm-follow-up` | `read`, `write` | 🤝 Follow-up Bot |
+| `workflow-runner` (runner) | `read`, `write`, `admin` | 🛠️ Runner |
+| `workflow-runner` (planner) | `read`, `write` | 🧠 Planner |
+| `workflow-runner` (reviewer) | `read`, `write` | 🔎 Reviewer |
+
+Pin each token to one workspace, and set the **agent display name + emoji** — every action the agent takes is then badged with that identity in activity feeds and comments (P4.1), and `/account/tokens` shows its daily usage (P2.8).
+
+> **`workflow-runner` auth is changing (M12.4b).** The three runner/planner/reviewer PATs above are the **deprecated** standing-PAT path. Prefer `STACKS_RUNNER_MODE=self-hosted` (the M11.1 bootstrap + claim-URL flow — one-time bootstrap token, short-lived role tokens) or, on the Jentrix-operated plane, `managed` (workload identity, zero standing PATs). See [Authentication — no standing PATs](#authentication--no-standing-pats-on-the-managed-path-m124b-age-174) below. The scopes column still describes the least privilege each role's short-lived token carries.
+
+## The agents
+
+### `pnpm bug-triage` — webhook-driven triage (long-running server)
+
+Closes the full agent loop: **webhook out → agent → MCP tools in**.
+
+1. In workspace settings, create a webhook for `task.created` pointing at this server (default `:8787`; use a tunnel for a deployed Jentrix). Put its secret in `STACKS_WEBHOOK_SECRET`.
+2. The receiver verifies the HMAC signature (`X-Stacks-Signature`, timestamp-bound — the exact scheme documented in CLAUDE.md §P2.6), acks fast, and queues one agent run per created task.
+3. The agent: `get_task` → skips non-BUGS tasks → infers and sets severity (`update_bug_report`) → searches for duplicates (`search_tasks`, P3.1) and links them (`add_task_link` `DUPLICATES`/`RELATES_TO`, P1.2) → asks for repro steps in a comment when missing.
+
+Webhook retries can redeliver — the comment uses an `idempotencyKey` derived from the delivery id (P2.4), so a retry replays instead of double-commenting.
+
+### `pnpm crm-follow-up` — scheduled pipeline sweep (cron)
+
+Walks CRM boards via `get_board_snapshot`, finds deals with a close date within 7 days (or past) and no *human* activity in 72h (`list_activity` with the `source` filter), and posts a clearly-marked **draft** follow-up comment on up to 5 deals — the human stays in the loop and sends the actual email. Idempotency keys are stable per deal per day, so re-running the cron never duplicates drafts.
+
+```cron
+0 7 * * *  cd /path/to/agents && pnpm crm-follow-up
+```
+
+### `pnpm standup` — daily digest (cron, read-only)
+
+Diffs the last 24h of `list_activity`, querying humans (`source: "ui"`) and agents (`source: "mcp"`) separately, and emits a short markdown digest — stdout by default, Slack when `SLACK_WEBHOOK_URL` is set. Runs safely on a `read`-only token: the server rejects any mutation it could be talked into.
+
+```cron
+0 8 * * 1-5  cd /path/to/agents && pnpm standup
+```
+
+### `pnpm cli-standup` — the same digest, bash-only (CLI instead of MCP tools)
+
+The bash-only counterpart of `standup`, and the proof that the [`jentrix` CLI](../docs/cli.md) is a first-class agent substrate. Same job — a read-only 24h digest splitting humans (`source: "ui"`) from agents (`source: "mcp"`) — but the runtime gets **Bash and nothing else**: no `mcp__jentrix__*` tools. It operates Jentrix purely through the `jentrix` binary on its PATH, discovering the surface lazily (`jentrix --help`, `stacks <group> --help`) and piping `--json` output through `jq`, instead of carrying the full tool surface in context.
+
+Setup:
+
+1. **Install the CLI** so `jentrix` is on PATH (see [docs/cli.md](../docs/cli.md#install)):
+   ```bash
+   npm install -g @jentrix/cli
+   # or from a checkout: cd ../cli && pnpm install && pnpm pack && npm install -g ./jentrix-cli-*.tgz
+   jentrix --version   # confirms it's on PATH
+   ```
+2. **Env** (same names as every agent): a **read-only** `STACKS_TOKEN` and `STACKS_MCP_URL`. The CLI reads these directly — the agent never passes `--token`/`--url` and never prints the token.
+   ```bash
+   export STACKS_TOKEN=tm_your_read_scoped_token
+   export STACKS_MCP_URL=http://localhost:3000/api/mcp
+   ```
+3. **Run** on either runtime:
+   ```bash
+   pnpm cli-standup                              # Claude runtime (ANTHROPIC_API_KEY / Claude login)
+   STACKS_AGENT_PROVIDER=codex pnpm cli-standup  # OpenAI Codex runtime — see the caveat below
+   ```
+
+```cron
+0 8 * * 1-5  cd /path/to/agents && pnpm cli-standup
+```
+
+**Security model — the boundary is the server-side read-scoped token.** This is the one thing to get right, so state it plainly: the load-bearing boundary is the **read-scoped `STACKS_TOKEN`, enforced server-side**. Because the agent authenticates with a token that carries only the `read` scope, the Jentrix server rejects *every* mutation the shell could ever be talked into — a write attempt returns a `FORBIDDEN` envelope (CLI exit 3), no matter what command runs (P2.1, token scopes). The digest never needs to write anything, so this scope is sufficient *and* it is the safety guarantee. For a stronger confinement, also **workspace-pin the token** (`ApiToken.workspaceId`) so even reads are limited to one workspace. Mint a dedicated token for this agent — do not reuse a broader one.
+
+**The on-host command guard is best-effort defense-in-depth, not a sound sandbox.** On the Claude runtime, `tools: ["Bash"]` offers *only* the shell (no Read/Write/Edit/WebSearch) and a `canUseTool` guard (`bashReadOnlyGuard`) inspects every Bash command, allowing only what *looks like* a read-only `stacks … --json | jq` pipeline: an allow-list of read-only heads (`jentrix`, `jq`, `echo`, `cat`, `grep`, `head`, `sort`, `wc`, …), and best-effort rejection of the obvious write/exfil surfaces — output redirection, `curl`/`wget`/`nc`, `rm`/`mv`/`cp`/`tee`, `node`/`git`/arbitrary interpreters, unquoted command substitution, the write-capable text tools `sed`/`awk`/`perl`/`find`/`xargs`, `sort -o`, the config-writing `jentrix login`/`jentrix logout`, and — importantly — any `--url`/`--token` override (which would point the CLI, carrying the injected token, at an arbitrary host). This raises the on-host bar above "just the prompt" and keeps the agent honest, and it is careful *not* to over-block legitimate reads (jq comparison operators like `>`/`<` and jq's own internal `|` are allowed, because the agent must actually work) — the allow and deny cases are unit-tested in `cli-standup.smoke.test.ts`. But parsing arbitrary shell from a string is not soundly decidable, so **this guard is explicitly not a security boundary**: a determined prompt-injection could still craft a command that reads Jentrix data (within the token's scope) and attempts to exfiltrate it. That residual risk is precisely why the agent runs on a *dedicated, read-scoped, ideally workspace-pinned* token — the blast radius of any such attempt is bounded to reading data that token can already see, and it can change nothing.
+
+**The Codex runtime is weaker still — a trusted-operator convenience.** The tools-only agents run Codex with the shell *disabled* and a `read-only` sandbox, but the CLI agent *needs* the shell to run `jentrix` and *needs* network for `jentrix` to reach the server — and Codex's `read-only` sandbox disables network. So the Codex CLI agent runs the shell under a **`workspace-write` sandbox with `networkAccessEnabled`** (writes jailed to a throwaway scratch cwd). Codex exposes no per-command `canUseTool` hook, so there is *no* on-host command guard at all on this runtime: the read-scoped token still blocks any Jentrix *mutation* and the jail blocks writes outside the scratch dir, but a networked shell that inherits the process env could read Jentrix data (within scope) and exfiltrate it or leak env values. **For an untrusted or least-privilege deployment, use the Claude runtime** (Bash-only + the best-effort guard) or the MCP `standup` agent; treat the Codex CLI path as a trusted-operator convenience, and always with a dedicated read-scoped token.
+
+<!-- BEGIN GENERATED: mcp-tool-count:agent-token-cost -->
+**Token cost — CLI vs MCP standup (measured on this repo's 242-tool surface).** The MCP `standup` agent injects **every** tool definition into the model's context up front: name + description + JSON input-schema + annotations for all 242 tools. The CLI `cli-standup` agent carries **no** tool schemas — only its system prompt — and pays for discovery at *run* time via `jentrix --help` (only for the commands it actually uses). Measured from the checked-in artifacts (bytes → tokens at ~3.7 chars/token, the ratio being the point):
+
+| Context loaded up front | Bytes | ≈ Tokens |
+| --- | --- | --- |
+| MCP agent — all 242 tool definitions | 387 KB | ~105k |
+| CLI agent — `CLI_STANDUP_SYSTEM_PROMPT` only | 2 KB | ~510 |
+
+That is a **~205× smaller** Jentrix-specific up-front context.
+<!-- END GENERATED: mcp-tool-count:agent-token-cost -->
+
+Reproduce the two numbers directly:
+
+```bash
+# MCP: bytes of the tool definitions an MCP client injects (name+description+inputSchema+annotations)
+node -e 'const s=require("../cli/surface.json");let b=0;for(const t of s.tools)b+=JSON.stringify({name:t.name,description:t.description,inputSchema:t.inputSchema,annotations:t.annotations}).length;console.log(b,"bytes ≈",Math.round(b/3.7),"tokens")'
+# CLI: bytes of the agent's system prompt (its entire Jentrix-specific context)
+node -e 'const s=require("fs").readFileSync("cli-standup.ts","utf8").match(/CLI_STANDUP_SYSTEM_PROMPT = `([\s\S]*?)`;/)[1];console.log(s.length,"bytes ≈",Math.round(s.length/3.7),"tokens")'
+```
+
+At run time the CLI agent instead spends a few `--help` round-trips — `jentrix --help` ≈ 860 tokens, a group's `--help` ≈ 60–100, a leaf's `--help` (e.g. `jentrix activity list --help`) ≈ 1,500 — so a session touching three or four commands spends ~2–3 K discovery tokens *for the commands it uses*, versus the full surface shown above loaded unconditionally. The trade-off is latency (extra round-trips) for a dramatically smaller, more focused context — the low-context, lazy-discovery mode the CLI was built to enable.
+
+### `pnpm workflow-runner` — review-loop driver (M7 + harness, long-running server)
+
+Drives the **plan → review → execute → review** loop ([docs/agent-workflows.md](../docs/agent-workflows.md)) and — when a turn belongs to a **Harness Automation stage** ([docs/harness.md](../docs/harness.md)) — the harness execution protocol. Packaged startup uses setup-written durable role bindings; the server's claimed release route must match before a model turn. The old `STACKS_AGENT_PROVIDER` startup remains for one explicitly deprecated compatibility window and logs a warning. Three separate short-lived tokens preserve role authority:
+
+1. In workspace settings, create a webhook for `agent.handoff` pointing at this server (default `:8788`). Put its secret in `STACKS_WEBHOOK_SECRET`.
+2. On each signed handoff it **claims** the current turn with the **runner principal** (`claim_agent_job` → `runId`), then spawns the selected Claude or Codex runtime with that role's own token and the `stacks-review-loop` skill, passing the `runId`.
+3. It **heartbeats** the run (runner principal) while the session works, and calls **`fail_agent_job`** on a provider error so the job blocks for a human instead of stalling.
+
+Three principals, by design (claim ≠ submit principal — the turn-guard checks the *submitting* token): **runner** (`read,write,admin`), **planner** (`read,write`, also executes), **reviewer** (`read,write`). Human turns (the pre-execution and final-acceptance gates) are not actioned here — a person resolves them in the Control Tower. Handoffs are serialized per process so retried deliveries never race a claim.
+
+#### Authentication — no standing PATs on the managed path (M12.4b, AGE-174)
+
+The runner never reads a standing PAT directly. Role tokens are provisioned by a mode-selected provider (`lib/runner-auth.ts`) and **refreshed at every drive**, so a long-running server that authenticates with short-lived tokens never presents an expired one. Select the mode with `STACKS_RUNNER_MODE`:
+
+| `STACKS_RUNNER_MODE` | Who runs it | How it authenticates | Env |
+| --- | --- | --- | --- |
+| `managed` | the Jentrix-operated plane | **workload identity + per-run capability tokens** (M12.4a) — the worker holds a short-lived, auto-rotated SVID and trades it for run/workspace/role-scoped capability tokens at the control-plane exchange. **Zero standing PATs.** | `STACKS_TOKEN_EXCHANGE_URL`, `STACKS_WORKLOAD_SVID`, `STACKS_RUN_ID`, `STACKS_WORKSPACE_ID` |
+| `self-hosted` | a runner on your own box | the **M11.1 bootstrap + claim-URL flow**: a one-time `STACKS_BOOTSTRAP_TOKEN` is redeemed at a single-use, short-TTL claim URL for short-lived role tokens (spent once, then refreshed with a rotating refresh credential). **No standing PAT.** | `STACKS_BOOTSTRAP_TOKEN`, `STACKS_CLAIM_URL` |
+
+`STACKS_RUNNER_MODE` is **required** — the pre-M12.4 standing-PAT path
+(`STACKS_RUNNER_TOKEN` / `STACKS_PLANNER_TOKEN` / `STACKS_REVIEWER_TOKEN`)
+was deleted (D4, 2026-07); those env vars are never read.
+
+Create a self-hosted bootstrap with an existing workspace-admin bearer. The
+planner and reviewer must already be the harness agents, each with exactly one
+non-revoked linked API-token row (an expired row is accepted as a rotation
+anchor; no raw standing bearer is required):
+
+```bash
+curl -X POST "$STACKS_APP_URL/api/agents/bootstrap" \
+  -H "Authorization: Bearer $STACKS_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"workspaceId":"...","plannerAgentId":"...","reviewerAgentId":"...","runnerEvidenceTier":"INTEGRATION_LOCAL"}'
+```
+
+The response shows `bootstrapToken` once plus its `claimUrl`. Set those as
+`STACKS_BOOTSTRAP_TOKEN` and `STACKS_CLAIM_URL`, then start the runner with
+`STACKS_RUNNER_MODE=self-hosted`. The bootstrap expires after 15 minutes and is
+single-use. Role bearers last one hour; one rotating refresh credential keeps
+them current for 24 hours. Issuing the bootstrap immediately invalidates the old
+raw planner and reviewer PAT values while preserving their database ids and
+agent links.
+
+The rotating refresh credential is persisted to `.runner-auth-state.json`
+(override with `STACKS_AUTH_STATE_PATH`; gitignored, written 0600) so a
+respawned once-mode process resumes the chain instead of re-presenting the spent
+bootstrap. **You never need to delete that file by hand** (AGE-922): a refresh
+credential the server rejects with a 401 is dropped from disk AND from memory,
+and the claim retries once on the `STACKS_BOOTSTRAP_TOKEN` currently in your
+env — so minting a fresh grant is sufficient on its own. A 401 that survives
+that fallback means the bootstrap itself is spent, expired, or revoked, and the
+error says so.
+
+`runnerEvidenceTier` is `INTEGRATION_LOCAL` — the only tier a self-hosted
+grant can mint (the local `PROD_TOPOLOGY_LOCAL` kind/Calico/gVisor lane was
+deleted in 2026-07; the next tier up is `MANAGED_STAGING`, which is a managed
+substrate, not a laptop cluster). The ceiling is stored on the single-use
+grant and copied to the short-lived runner token, so setting a runner
+environment variable cannot upgrade its authority.
+
+The **runner never reads a standing-PAT env var** — the deprecated legacy provider was deleted outright (D4, 2026-07). The managed provider (`lib/managed-auth.ts`) additionally fails closed (`StandingPatOnManagedPathError`) the instant a standing PAT is present in its environment, and a grep test (`runner-auth.smoke.test.ts`) fails if any managed-path module so much as names one.
+
+**Codex model is pinned.** The Codex runtime reads `~/.codex/config.toml` as its base config, so the runner always pins the model + reasoning effort explicitly (`STACKS_CODEX_MODEL`, default `gpt-5.5`; `STACKS_CODEX_EFFORT`, default `medium`) — an interactive `codex` model switch on the host must never silently re-model an unattended role. Every claim records the pinned model on the run (`claim_agent_job.model`), so the ledger answers which model planned, executed, or reviewed each round.
+
+**Codex checkout permissions follow the role.** Review turns receive the stage checkout read-only, so the reviewer verifies claims against the actual tree without modifying it. Executor turns receive workspace-write access only to their isolated harness worktree so they can implement the stage. Tools-only turns stay read-only with the shell disabled. The Codex child environment is scrubbed of the orchestrator's other credentials; the per-turn bearer is the only Jentrix credential it receives.
+
+**Poll mode (webhook-less).** A deployed Jentrix cannot deliver webhooks to a localhost runner — the outbound SSRF guard rightly refuses private destinations — so without a public tunnel the webhook leg can never fire. Set `STACKS_POLL_MS` (e.g. `15000`) and the runner drives the SAME loop by polling instead: each tick lists the agent-turn phases and submits pending PLANNER/REVIEWER turns to the same bounded agent-turn pool the webhook path uses (the full job view is re-read fresh before each drive; `claim_agent_job`'s server-side CAS is the double-claim guard), and watches executor-driven + FINAL_ACCEPTANCE-parked harness jobs for the post-validation commit boundary on the dedicated commit pool (so a commit-gate wait never blocks the reviewer turn that unblocks it). With no `STACKS_WEBHOOK_SECRET` configured the webhook endpoint answers 503; webhook and poll modes can also run together.
+
+For single-run or production bring-up, set `STACKS_POLL_HARNESS_RUN_ID` as well.
+The poller then fails closed to that exact harness for both agent turns and commit
+gate watches; generic jobs and historical runs in the workspace are ignored.
+
+**Bounded concurrency + shared job-id dedup (Concurrent Harness Execution, Stage 4).** The runner drives work through **two bounded pools** (`lib/runner-pool.ts`) instead of a single serialized promise chain:
+
+- **`STACKS_RUNNER_MAX_CONCURRENT_JOBS`** (default **1**, hard cap **16**) bounds planner/reviewer/executor **agent turns**.
+- **`STACKS_RUNNER_MAX_CONCURRENT_COMMITS`** (default **1**, hard cap **8**) bounds the post-validation **commit/push continuations** on a **dedicated** pool, so a freshly-approved commit is never queued behind a long model turn — the low-latency commit path is preserved even when the agent-turn pool is full. A commit continuation runs in its own **job-scoped worktree** (see *Per-job worktrees*) and can therefore run concurrently with another job's agent turn (different dirs/branches, no shared-index or branch-switch race).
+
+Each value **parses to a finite documented maximum** (`parseBoundedMax`): an unset / non-integer / `< 1` value falls back to the default (never unbounded), and anything above the hard cap is clamped down. Both the **webhook and the poll input submit to the SAME two pool objects**, so the queued/running **job-id dedup registry spans both inputs** — a duplicate webhook delivery, a retried delivery, or a racing poll drive for one job **collapses before consuming a slot** (`submit()` returns false; `claim_agent_job`'s server-side CAS stays the final ownership guard). A slot is released when the invocation settles **or** when the per-task **watchdog** (`WATCHDOG_MS`) detaches a hung provider session; a watchdog-detached job **stays attempt-guarded in the registry** (a same-jobId re-delivery stays collapsed, so it can never share the orphan's worktree — a retry mints a *new* jobId → a *new* worktree), while the orphan's late writes lose to the superseding claim server-side. At `STACKS_RUNNER_MAX_CONCURRENT_JOBS=2`, two same-repo jobs each get their own worktree and commit on their own resolved branches; a third job waits until a slot frees, and observed concurrency never exceeds the bound. The runner logs a `[runner-pool]` telemetry line on every enqueue/dedupe/start/settle reporting **both queue depths, both active slot counts, both registry sizes, the oldest in-flight job age, the claim-to-execution (queue) latency, and the branch-ownership-conflict count**. Proven end-to-end in `runner-pool.smoke.test.ts`.
+
+#### Harness stage execution (H10.6)
+
+The `agent.handoff` webhook carries only the `jobId`, so on an **execution** turn the runner polls `get_agent_job` and routes to the harness protocol when the job's `harness` block is present (a `stage_execution` job). A harness stage rides the M7 plan → review → execute → review loop, so the runner has **two** phases (`lib/harness-runner.ts`):
+
+**Execution turn** (`driveHarnessStage`, on the `EXECUTING` handoff — it does **not** commit, because the local commit is only authorizable once the stage is validated):
+
+- runs the **executor** session in the stage's **per-job worktree** (see *Per-job worktrees* below — never the shared checkout; the run's repo → `STACKS_RUNNER_REPOS`; an **unmapped repo aborts** before any agent/git/credential action — the shell-capable path is bounded to configured checkouts),
+- **executes the stage plan's declared `verificationCommands` itself** in an ephemeral managed container (HAI S3 — the stage worktree is the only writable host mount, the environment is an explicit non-secret allowlist, network egress is always denied, commands run one at a time, and each has `verificationTimeoutMs`, default 15 min). Set a repo-compatible, preferably digest-pinned `STACKS_VERIFICATION_IMAGE` (`STACKS_SANDBOX_IMAGE` is the fallback); the runner starts a real preflight container **before claiming the turn**, so missing Docker/image support burns zero model turns. The image must contain the lockfile-pinned pnpm release and dependency tree: the sealed manifest points Corepack at that cache and disables pnpm 11's `verifyDepsBeforeRun=install` auto-install so verification cannot drift to or hang on the denied registry. Each captured output is submitted as a `TEST_EVIDENCE` artifact **with a runner attestation** (command, exit code, timeout flag, output hashes, evidence tier — default `INTEGRATION_LOCAL`, capped server-side by the runner token's `ApiToken.maxEvidenceTier` ceiling) bound to the diff capture's checksum, via the **runner token** (the claiming identity — the server rejects any other issuer). The executor's prose is **never** test evidence; if a declared command is not run, the structured report says so (`testsNotRun`) and the stage honestly fails its gate,
+- captures the complete diff—including non-ignored untracked files, via temporary intent-to-add entries that are removed immediately—as a **`submit_harness_artifact`** `DIFF_OR_PATCH` artifact and links everything in **`submit_harness_stage_result`** (changed files, branch, diff lines, the honestly-populated `commandsRun`/`testsRun`/`testsNotRun`/`risks` — **no** commit yet), so the validation gate has its required evidence kinds (the `EXECUTION_SUMMARY` is written by `submit_harness_stage_result` itself), and
+- satisfies the generic **`submit_execution_result`** so the M7 state machine advances to the reviewer turn.
+
+Two things every execution turn gets regardless of what the stage declares:
+
+- **The harness-flow gate.** `pnpm test:harness-flow` (`HARNESS_FLOW_GATE_COMMAND`) is appended to the declared commands as the **last** one, so every executor job proves the machinery carrying it still converges — sweep-only liveness, decision-table totality, review-round/park accounting. It runs through the same attested path as any other command: real exit code, runner attestation, and a failure landing in `risks`/`testsNotRun` for the validation gate and the reviewer. A stage that already declares it is not run twice.
+- **Project context** (`lib/project-context.ts`), injected into the planner, executor, *and* reviewer prompts: `CLAUDE.md` named as the contract the review is judged against (Claude legs also load it natively — `settingSources: ['project']`; `AGENTS.md` symlinks to it for the Codex legs), plus the base-branch commits the checkout does **not** have. A worktree is cut from its base ref once and never rebased, so parallel work on the same repo is otherwise invisible to every role. Best-effort: a git failure degrades to the conventions block and never costs a turn.
+
+Local verification caps at `INTEGRATION_LOCAL` — there is no local lane for a
+stronger tier (the 2026-07 `PROD_TOPOLOGY_LOCAL` kind/Calico/gVisor experiment
+was deleted; the next real tier is `MANAGED_STAGING`, a managed substrate).
+A stage plan demanding a stronger tier is rejected at decomposition and parked
+at launch (F2), never burned against the attest-time ceiling.
+
+**Commit boundary** (`driveHarnessStageCommit` → `driveHarnessCommit`). A stage is validated *later* than its execution turn — after the reviewer and the human `FINAL_ACCEPTANCE` gate — so Jentrix emits **`harness.stage_validated`** when the commit boundary is ready. The runner subscribes to that webhook (alongside `agent.handoff`) and drives the commit boundary then (it also runs it opportunistically right after the execution turn when an ALLOW policy auto-approved the gate). This phase has no active M7 turn, so it does not claim/heartbeat — it freeze-probes via `get_harness`. It:
+
+- **authorizes** the local commit with **`authorize_harness_local_commit`** *before* `git commit` (a `repo:commit` permission check that honors freeze/leases/policy — it mints **no** credential and approves **no** gate; it throws on a non-validated/frozen/blocked stage). The runner passes the **resolved branch + the pre-commit changed paths + diff size** so branch-scoped leases and the `high_risk_change` policy evaluate the actual target *before* the commit,
+- reports the commit SHA + the committed files via **`submit_harness_stage_result`** (with the claimed `jobId` so the report binds to this attempt — the local-commit evidence the boundary needs to advance to `COMMITTED`), and
+- after the commit boundary authorizes push/PR (the stage reaches `COMMITTED`), brokers a **single-use** `repo:push` / `repo:pr_create` credential through the injected `brokerPushCredential` seam, performs the `git push`, and opens the PR through the injected `createPullRequest` seam — **never a standing raw repo token**. A pending commit gate or a blocked stage **stops the runner** (it never forces or self-approves a human gate).
+
+**Freeze** is honored by this external process: `heartbeat_agent_job` returns `{ frozen: true }` when the run is frozen, and the runner **aborts the in-flight subprocess** and performs no further submit / commit-evidence / credential / push / PR until resume (it re-checks freeze at every boundary, including after each credential broker and before each external git write).
+
+The reference runner ships `brokerPushCredential` and `createPullRequest` as **fail-closed no-ops** (they return no token / no PR): the MCP boundary deliberately never hands out raw push material (`request_credential_grant` returns a grant *handle*, not a token), so a tools-only reference runner has no standing repo token — when no broker is wired the stage simply stays `COMMITTED` on Jentrix and the governed delivery path (or a human) performs the externally-visible write. The smoke test wires a stubbed single-use broker + PR opener to exercise the **full** push/PR handoff; a real deployment wires those seams to its brokered `repo:push` / `repo:pr_create` source and PR-create API call.
+
+#### Per-job worktrees (Concurrent Harness Execution, Stage 3)
+
+Each stage attempt (`AgentJob`) executes in its **own native-Git worktree** derived from the run's checkout — the executor's working directory, from which the diff/test evidence is captured, which a same-job revision turn reuses, and which the **reviewer receives read-only**. The mechanics live in the dependency-free S1 helper (`packages/execution/src/worktree.ts`); the runner's policy layer is `lib/harness-worktree.ts` (wired in `workflow-runner.ts`, faked in the smoke tests):
+
+- **Branch source.** A worktree is created on the stage branch from the stage's `executionBaseRef` (never the checkout HEAD — a missing ref is an actionable error, fetch only that ref through the broker), or checks out the existing stage-branch tip on a retry; a restart **adopts** the existing worktree only when Git metadata and the sibling ownership marker agree, else it fails closed.
+- **Ownership before a retry.** Because the null/legacy fallback branch `harness/{taskKey}-stage-{number}` and the `{slug}` stage-id substitution let legacy, null, custom, and same-anchor runs resolve to the **same** branch, the runner never assumes a branch template is globally unique. Before reusing a stage branch it prunes, lists worktrees, resolves the owner marker, and reads **fresh Jentrix state**: a live/current owner → an actionable conflict naming the owning branch/job; a confirmed-superseded owner (lease taken over, or a newer stage job replaced it and the old job has no active run or pending commit) → the old worktree is **detached** (files preserved, marker stamped `superseded-detached`) and the branch reused; unprovable → fail closed, nothing reset/renamed/stolen.
+- **Per-repo bootstrap + ignored config.** `STACKS_RUNNER_REPOS` stays back-compatible with string values *and* accepts an operator object `{ cwd, bootstrap: [[argv]], copyIgnoredFiles, worktreeRoot }`. Bootstrap argv run **after** containment/ownership validation and are idempotent (may re-run on adoption). `copyIgnoredFiles` copies **only** allowlisted repo-relative files that `git check-ignore` confirms are ignored, owner-only, never logged/artifacted, deleted with the worktree; **nothing is copied by default**.
+- **Cleanup + operator listing.** A worktree is removed only on a safe terminal Jentrix state with no active run (`git clean -fdX` ignored output → `git worktree remove` → prune); it **survives** freeze, `PRE_EXECUTION`/`FINAL_ACCEPTANCE`/`COMMIT` gates, same-job revisions, and a process restart. A source-dirty or orphaned worktree is retained and reported. Run `pnpm harness-worktrees` to list runner-owned worktrees with job/stage/age/source-cleanliness (and local paths) before any manual removal — those absolute paths are printed to stdout only, never persisted into Jentrix.
+
+## Scripts (not agents)
+
+Not everything in `scripts/` drives a model. `harness-template.ts` is a plain
+CI client: argv in, one MCP `tools/call` out.
+
+### `scripts/harness-template.ts` — the harness-template CI client (M18.3 R8)
+
+Drives the harness-template MCP tools non-interactively, so a pipeline can
+validate, publish, preview and launch a reusable harness pipeline without a
+browser. It is a **thin shell, not a second API** — the server does the
+authorization, the validation, the optimistic-concurrency check and the launch
+freeze, and everything decidable without I/O lives in the pure
+`scripts/harness-template-core.ts`. A packaged operator CLI binary is an
+explicit non-goal: MCP is the scripting surface.
+
+Run it as `pnpm harness-template <command>` (or `npx tsx
+scripts/harness-template.ts`, or `pnpm --dir agents harness-template` from the
+repo root).
+
+The whole file is covered, entrypoint included. `main(argv, deps)` is exported
+and every dependency on the outside world — env, file read/write, stdout/stderr,
+the MCP connection — is injectable, so the app's
+`tests/cli/harness-template-client.test.ts` drives the SHIPPED executable
+against the real in-process MCP server: exit codes, the token bootstrap, the
+`--output` write, the session close, the envelope on stderr. Importing the
+module runs nothing (an `isEntrypoint` guard), which is both what makes that
+possible and what the suite asserts. The root `pnpm typecheck` follows the same
+import, so this file is type-checked by the app gate as well as by
+`pnpm --dir agents typecheck`.
+
+```bash
+export STACKS_TOKEN=tm_…            # a PAT with the admin scope
+export STACKS_MCP_URL=https://tm.jentrix.ai/api/mcp   # optional; this is the default
+
+pnpm harness-template list --workspace ws_123
+npx tsx scripts/harness-template.ts list --workspace ws_123
+npx tsx scripts/harness-template.ts validate --template ht_123
+npx tsx scripts/harness-template.ts publish  --template ht_123 \
+  --expected-updated-at "$(npx tsx scripts/harness-template.ts get --template ht_123 --json | jq -r .template.updatedAt)"
+npx tsx scripts/harness-template.ts preview  --template ht_123 --repo acme/app --json
+npx tsx scripts/harness-template.ts launch   --template ht_123 --repo acme/app --dry-run \
+  --expected-checksum "$CHECKSUM" --idempotency-key "$GITHUB_RUN_ID"
+```
+
+Commands: `list`, `get`, `validate`, `publish`, `export`, `import`, `preview`,
+`launch`. `--json` emits the raw structured result for a downstream `jq`;
+`--dry-run` on `preview`/`launch` selects the INERT launch (identical rows plus
+a linked `SimulationRun`, every execution leg refused at the claim).
+
+Three properties matter more than the flag list:
+
+- **No auth flag exists.** The token comes from `STACKS_TOKEN` only. An
+  argument is visible in shell history, in `ps`, and in the CI log of every job
+  that echoes its command line.
+- **Secret-shaped argv is refused before it connects** (PRD §11 R8: "raw
+  provider keys must not appear in arguments"). The refusal names the flag and
+  the remedy, and never echoes the value back into the log. A template
+  references credentials by ALIAS, bound once to a pre-created credential
+  record; the authoritative refusal is still server-side, where the ops core
+  runs the platform redactor over every definition it stores.
+- **Exit codes gate a pipeline honestly.** `0` success, `1` server refusal (its
+  structured envelope printed verbatim to stderr), `2` bad invocation, `3` the
+  call succeeded and the ANSWER was no — `validate` found errors that block
+  publishing, or `preview` found blockers that refuse the launch. Without that
+  third code, `validate && publish` would publish exactly what validation
+  refused.
+
+`publish` requires `--expected-updated-at` and every create-style command
+requires `--idempotency-key`, because the MCP boundary requires them: a CI job
+retries, and two pipelines edit the same template without seeing each other.
+The client checks first only so a misconfigured job learns without a round
+trip; it can never grant what the server refuses. Full tool reference:
+`harness-specs/13-mcp-tool-reference.md` § Harness templates.
+
+## Platform features these exercise
+
+| Feature | Where |
+| --- | --- |
+| Scoped PATs + workspace pinning (P2.1) | all three (least-privilege table above) |
+| Structured `{ error: { code, hint } }` envelopes (P0.4) | system prompts tell the agent to follow hints |
+| Idempotency keys (P2.4) | bug-triage (per delivery), crm-follow-up (per deal/day) |
+| Orientation + search tools (P2.3, P3.1) | `get_board_snapshot`, `search_tasks` |
+| Cross-kind task links (P1.2) | bug-triage duplicate detection |
+| Outbound webhooks + HMAC (P2.6) | bug-triage receiver |
+| Activity source attribution (P2.8) | standup + crm-follow-up `source` filters |
+| Agent identity badges (P4.1) | token displayName/emoji on every mutation |
+| CLI as an agent substrate (Jentrix CLI plan) | cli-standup — bash + `jentrix`, lazy `--help` discovery, read-scope-only |
+| Harness templates over MCP (M18.3 R8) | `scripts/harness-template.ts` — one ops core, driven from CI |
+
+## Sanity check
+
+`pnpm typecheck` type-checks the package. `pnpm test` runs the deterministic smoke tests on Node's built-in test runner via `tsx` — no real Claude/Codex/GitHub, so they pass in CI with no agent providers:
+
+- **`harness-runner.smoke.test.ts`** drives a fake repo with mocked MCP calls, a mocked agent turn, mocked git, and a stubbed credential broker. It proves a stage executes and records evidence + commit, that a **frozen heartbeat stops all work before any submit/commit/credential/push**, and that the push/PR handoff uses a single-use brokered credential (never a standing repo token).
+- **`scripts/harness-template.ts`** is the exception that proves the rule: it drives no model, so it is covered from the app side instead. `pnpm test tests/cli/harness-template-client.test.ts` (in the repo root) imports the executable, drives `main(argv, deps)` against the real in-process MCP server, and asserts the `harness-template` script wiring in this package.json.
+- **`cli-standup.smoke.test.ts`** constructs the CLI agent's per-provider runtime config (no live model call) and asserts the restriction directly: the Claude runtime offers **only** the `Bash` built-in and wires no MCP server; the Codex runtime keeps the shell but jails writes to a scratch cwd with network on; and the system prompt teaches `--help` discovery + `--json`/jq rather than guessing flags.
+- **`pnpm test:sealed`** is the same suite MINUS `harness-worktree.smoke.test.ts`, for the managed sealed verification lane (AGE-906). Those 15 tests build real git checkouts (`git()` / `makeCheckout`), and the sealed lane can never satisfy them: it runs a **tar copy** of the worktree, whose `.git` is a pointer file into the host repo, and the verification image ships no `git` binary — so they fail `spawnSync git ENOENT`. That is the same hazard `checkCommandLaneFeasibility`'s F3 rule already refuses for `git` *verification commands*, one level down (a suite spawning git internally). Measured sealed: **211 pass, 15 fail, all 15 in that one file**; `test:sealed` is 211/211. Installing git in the image would convert `ENOENT` into a subtler wrong answer, not a pass — the repo state genuinely is not there. Keep running the full `pnpm test` in CI and locally, where git and a real checkout exist.
+- **`runner-auth.smoke.test.ts`** proves the M12.4b PAT retirement: the **managed plane drives a full harness stage using only workload-identity-minted capability tokens** (every MCP call carries a `cap_…` token, never a `tm_` PAT, with zero standing PATs in the env); a **grep asserts no managed-path module names a standing-PAT env var**; the managed provider **fails closed** if a standing PAT leaks into its environment; the **self-hosted bootstrap + claim-URL** flow spends the one-time bootstrap token exactly once then refreshes; and standing PATs **never select an auth path** (D4 — an unset mode fails closed even with PATs present).
+
+For a live smoke test, point `.env` at a dev server (`pnpm dev` in the repo root, seeded via `pnpm db:seed`), mint a token with the dev helper, and run `pnpm standup`:
+
+```bash
+TOKEN=$(curl -s -X POST localhost:3000/api/dev/mcp-token \
+  -H 'content-type: application/json' \
+  -d '{"name":"standup dev","displayName":"Standup Bot","emoji":"📋"}' | jq -r .token)
+STACKS_TOKEN=$TOKEN pnpm standup                              # Claude runtime
+STACKS_TOKEN=$TOKEN STACKS_AGENT_PROVIDER=codex pnpm standup  # ChatGPT subscription
+```
+
+The bash-only `cli-standup` needs the `jentrix` CLI on PATH (install it per [docs/cli.md](../docs/cli.md#install)); with the same dev token exported it runs the identical digest through the CLI:
+
+```bash
+STACKS_TOKEN=$TOKEN pnpm cli-standup   # discovers commands via `jentrix --help`, no MCP tools
+```

package/dist/chunk-A6NTXRVS.js

@@ -0,0 +1,7 @@
+// lib/version.ts
+var RUNNER_VERSION = "0.5.3";
+
+export {
+  RUNNER_VERSION
+};
+//# sourceMappingURL=chunk-A6NTXRVS.js.map

package/dist/chunk-A6NTXRVS.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../lib/version.ts"],
+  "sourcesContent": ["export const RUNNER_VERSION = \"0.5.3\";\n"],
+  "mappings": ";AAAO,IAAM,iBAAiB;",
+  "names": []
+}

package/dist/chunk-N2UNVXHV.js

@@ -0,0 +1,184 @@
+// lib/runner-config.ts
+import { constants, promises as fs } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { homedir } from "node:os";
+var RUNNER_CONFIG_SCHEMA_VERSION = 1;
+function runnerConfigPath(env = process.env, home = homedir()) {
+  const override = env.STACKS_RUNNER_CONFIG?.trim();
+  if (override) {
+    if (!isAbsolute(override)) {
+      throw new Error(
+        "RUNNER_CONFIG_INVALID: STACKS_RUNNER_CONFIG must be absolute."
+      );
+    }
+    return override;
+  }
+  return join(home, ".config", "stacks", "runner.json");
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateConfig(value) {
+  if (!isRecord(value) || value.schemaVersion !== RUNNER_CONFIG_SCHEMA_VERSION) {
+    throw new Error(
+      "RUNNER_CONFIG_INVALID: unsupported or missing config schema version."
+    );
+  }
+  const required = [
+    "protocolVersion",
+    "runnerVersion",
+    "jentrixBaseUrl",
+    "mcpUrl",
+    "workspaceId",
+    "workerId",
+    "heartbeatToken",
+    "bootstrapToken",
+    "claimUrl"
+  ];
+  for (const key of required) {
+    if (key === "protocolVersion" && typeof value[key] !== "number" || key !== "protocolVersion" && (typeof value[key] !== "string" || String(value[key]).length === 0)) {
+      throw new Error(`RUNNER_CONFIG_INVALID: config field ${key} is missing.`);
+    }
+  }
+  if (!isRecord(value.executables) || !isRecord(value.roleBindings)) {
+    throw new Error(
+      "RUNNER_CONFIG_INVALID: executable paths or role bindings are missing."
+    );
+  }
+  for (const [key, path] of Object.entries(value.executables)) {
+    if (key !== "claude" && key !== "codex" || typeof path !== "string" || !isAbsolute(path)) {
+      throw new Error(
+        "RUNNER_CONFIG_INVALID: executable paths must be absolute."
+      );
+    }
+  }
+  for (const role of ["planner", "executor", "reviewer"]) {
+    const binding = value.roleBindings[role];
+    if (!isRecord(binding)) {
+      throw new Error(
+        `RUNNER_CONFIG_INVALID: ${role} role binding is missing.`
+      );
+    }
+    for (const key of [
+      "agentId",
+      "runtimeAdapterKey",
+      "provider",
+      "providerConnectionId",
+      "model",
+      "source"
+    ]) {
+      if (typeof binding[key] !== "string" || binding[key].length === 0) {
+        throw new Error(`RUNNER_CONFIG_INVALID: ${role}.${key} is missing.`);
+      }
+    }
+    if (binding.runtimeAdapterKey !== "claude" && binding.runtimeAdapterKey !== "codex") {
+      throw new Error(
+        `RUNNER_CONFIG_INVALID: ${role} names an unknown runtime adapter.`
+      );
+    }
+    if (binding.source !== "active_release" && binding.source !== "worker_draft") {
+      throw new Error(`RUNNER_CONFIG_INVALID: ${role}.source is invalid.`);
+    }
+    if (typeof binding.requiresClaimCredential !== "boolean") {
+      throw new Error(
+        `RUNNER_CONFIG_INVALID: ${role}.requiresClaimCredential is missing.`
+      );
+    }
+  }
+  return value;
+}
+async function assertPrivate(path) {
+  if (process.platform === "win32") return;
+  const mode = (await fs.stat(path)).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new Error(
+      `RUNNER_CONFIG_INVALID: ${path} must be mode 0600; run: chmod 600 ${JSON.stringify(path)}`
+    );
+  }
+}
+async function readRunnerConfig(path = runnerConfigPath()) {
+  await assertPrivate(path);
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(path, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`RUNNER_CONFIG_INVALID: ${path} is not valid JSON.`);
+    }
+    throw error;
+  }
+  return validateConfig(parsed);
+}
+async function runnerConfigSummary(path = runnerConfigPath()) {
+  try {
+    const config = await readRunnerConfig(path);
+    return {
+      path,
+      configured: true,
+      workspaceId: config.workspaceId,
+      workerId: config.workerId,
+      blocker: null
+    };
+  } catch (error) {
+    const code = error?.code;
+    if (code === "ENOENT") {
+      return {
+        path,
+        configured: false,
+        workspaceId: null,
+        workerId: null,
+        blocker: {
+          code: "BOOTSTRAP_REQUIRED",
+          message: "runner setup has not been applied.",
+          nextCommand: "jentrix runner setup"
+        }
+      };
+    }
+    return {
+      path,
+      configured: false,
+      workspaceId: null,
+      workerId: null,
+      blocker: {
+        code: "RUNNER_CONFIG_INVALID",
+        message: error instanceof Error ? error.message : "runner config is invalid.",
+        nextCommand: "jentrix runner setup"
+      }
+    };
+  }
+}
+async function writeRunnerConfigAtomic(config, path = runnerConfigPath()) {
+  validateConfig(config);
+  const dir = dirname(path);
+  await fs.mkdir(dir, { recursive: true, mode: 448 });
+  if (process.platform !== "win32") await fs.chmod(dir, 448);
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    const handle = await fs.open(
+      temp,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+      384
+    );
+    try {
+      await handle.writeFile(`${JSON.stringify(config, null, 2)}
+`, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    if (process.platform !== "win32") await fs.chmod(temp, 384);
+    await fs.rename(temp, path);
+  } catch (error) {
+    await fs.unlink(temp).catch(() => void 0);
+    throw error;
+  }
+}
+
+export {
+  RUNNER_CONFIG_SCHEMA_VERSION,
+  runnerConfigPath,
+  readRunnerConfig,
+  runnerConfigSummary,
+  writeRunnerConfigAtomic
+};
+//# sourceMappingURL=chunk-N2UNVXHV.js.map