@mmerterden/multi-agent-pipeline 17.6.0 → 18.0.0

package/CHANGELOG.md

@@ -14,6 +14,133 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [18.0.0] - 2026-09-17
+
+Major, for two behaviour changes rather than a renamed command: a run's state now
+has ONE canonical directory, and four publish paths refuse to send when the leak
+gate cannot be loaded.
+
+### Added
+
+- **`multi-agent-pipeline verify`** answers "is this install the thing that was
+  published". The install is a copy, and from the moment `install.js` writes it
+  the two halves drift independently: an edit in the installed tree is behaviour
+  with no source, and a file the installer skipped is a script the docs describe
+  and nobody has. `manifest.json` (SHA-256 per shipped file, version, source
+  commit) is built at pack time by `prepack` and never committed - a manifest in
+  git is stale one commit after it is written, and a stale manifest reports
+  honest edits as tampering.
+
+  `commands/` is compared by presence, not bytes, because `install.js` rewrites
+  each description into the user's `outputLanguage`: measured here, all 57
+  command files differ and 56 of them differ by nothing else. Dev-only files are
+  excluded, or 252 smokes and linters read as "the installer skipped this".
+
+  What a green result proves is stated in the output's own reference: the bytes
+  match what the publisher recorded. Not who published them - the manifest, the
+  signature and the verifier travel in the same tarball, so provenance belongs
+  to npm's integrity field. Signing is optional, and an unverifiable signature
+  says so rather than claiming valid.
+
+- **`cost-analyze.mjs`** - projection, anomaly, burn and diff. `cost-budget-check`
+  watches one run against one ceiling, which is blind to both ways a budget
+  actually empties: a drift no single run trips, and one session that burns a
+  week in an hour while every run stays under its cap.
+
+  The series is not where the schema says it is. `tracker-state.json` carries
+  per-phase token fields that are written only when a phase reports them; of 98
+  trackers on a working machine, zero carry any. The dense series is the host's
+  own transcripts, so that is what this reads - and the consequences are printed
+  rather than buried: it covers everything Claude Code did on the machine, the
+  figures are LIST-price estimates rather than a bill, and a host with no
+  transcripts reports UNMEASURED instead of zero.
+
+  Anomalies use the median and the MAD, because the expensive session the check
+  exists to find is the observation that inflates a mean and a standard
+  deviation - it hides inside the statistic measured against it.
+
+- **`install --unattended`** writes a documented permission profile, and prints
+  it with a reason per line before writing. autopilot passes
+  `--permission-prompts none`, which stops Claude Code asking and grants
+  nothing; on a fresh machine the run stops at the first tool call with no
+  prompt for anyone to answer, which is indistinguishable from an empty queue. A
+  default install still writes no permissions at all.
+
+- **`doctor --profile=server`** adds four checks that only matter when nobody is
+  at the keyboard: the unattended contract, the permission posture, the
+  scheduler, and the keychain. The default run is unchanged - same 17 checks,
+  same verdict - because a laptop told it fails a server check learns to ignore
+  doctor.
+
+- **`docs/server-readiness.md`** sets up nothing and says so first. It covers the
+  permission posture, why the scheduler is a LaunchAgent rather than a
+  LaunchDaemon (the keychain is locked until login, and that failure arrives
+  much later wearing a 401), and which credential each phase needs.
+
+- **`scorecard-snapshot.mjs --diff`** keeps what the scorecard said and reports
+  what moved. Deliberately no 0-100 score: the scorecard reports twelve measured
+  metrics AND four it refuses to measure, and one figure would hide both halves.
+
+### Changed
+
+- **A run's state has one canonical directory.** `{project}/{taskId}/` is
+  canonical and the flat `{taskId}/` is read for compatibility; every reader
+  resolves through `lib/run-paths.sh` / `scripts/_run-paths.mjs`, so a run that
+  exists in both layouts is counted once.
+
+- **Five publish paths refuse rather than send when the leak gate is missing.**
+  Jira comments and descriptions, PR review bodies and inline comments, the
+  GitHub issue progress comment, the issue-CREATION path, and Confluence page
+  create/update all run their outbound text through `lib/outbound-gate.mjs`
+  first. A missing gate file refuses; opening the gate because the gate is not
+  there would be the one failure mode that matters. The count is part of the
+  gate: a sixth publisher cannot ship without the smoke's list naming it.
+
+- **`set -e` on the four destructive scripts, and deliberately not on the two
+  collectors.** `gc-abandoned`, `gc-worktrees`, `purge` and `worktree-finalize`
+  delete things, so the command after an unnoticed failure is the dangerous one.
+  `pre-push-check` runs the gates and counts failures, and `pre-commit-check` is
+  a hook built out of greps that are supposed to find nothing - under `-e` the
+  first clean detector would end the scan and report "no secrets" for a file it
+  never finished reading.
+
+### Fixed
+
+- **A script that dies now prints one line instead of a stack dump, and releases
+  what it held.** `lib/fatal.mjs` catches the sync throw, the rejection nobody
+  awaited and the throw from inside a callback; the last two are invisible to a
+  try/catch around `main()`. `write-state` releases its advisory lock on the way
+  out, so the next writer never has to judge a lock on age alone. EPIPE is
+  deliberately not fatal: `runs-index.mjs --json | head` is the ordinary way to
+  read a large output.
+
+- **Build junk no longer reaches an install.** A CI runner shipped 147 files
+  where every developer tree shipped 146, for four rounds, and the extra was
+  `__pycache__/*.pyc` - untracked, so no diff of the source could show it, and
+  copied verbatim into all three install trees. `copyDir` now filters
+  `__pycache__`, `*.pyc` and `.DS_Store` on every path.
+
+- **`jq` is required rather than optional on the nine paths that publish or
+  decide.** A missing `jq` renders as empty DATA and the work carries on with
+  it; those nine now exit 3.
+
+- **The autopilot runner survives a month unwatched.** `runner.log` is truncated
+  in place past 5MB (renaming it leaves launchd's `O_APPEND` descriptor writing
+  into the renamed file while the new one stays empty - the rotation that looks
+  right and silently stops logging), three consecutive empty attempts stop new
+  work being taken, and one JSON line per tick goes to `ticks.jsonl`.
+
+- **`github-ssh-setup.sh` no longer waits forever on a headless machine**, and
+  `write-state.mjs` gained `--if-rev=<n>` compare-and-swap so a second writer
+  cannot silently overwrite the first.
+
+- **A direct-run guard that compared `import.meta.url` to `file://${argv[1]}`**
+  is false whenever argv[1] is not already resolved - a `/var` path that
+  resolves to `/private/var`, or the symlink `install --link` writes. The script
+  then does nothing at all, silently.
+
+---
+
 ## [17.6.0] - 2026-09-15
 
 ### Added

package/README.md

@@ -17,7 +17,7 @@ Runs natively on Claude Code, Copilot CLI and Codex CLI. macOS only. Zero runtim
 ### Prerequisites
 
 - **Node.js >= 20.11** - required; the pipeline's own tooling runs on it.
-- **`jq`** - optional but recommended. Thirteen shell helpers reach for it and skip in silence without it: cost summaries, the phase tracker's JSON reads, convention extraction, skill signing. The install prints a note when it is missing.
+- **`jq`** - required for nine paths, optional for the rest. 78 shell files call it. The nine that publish or decide - the autopilot queue, Jira comments, PR reviews, issue updates, the plan file, both Figma fetchers, log search and Jira auth - now refuse with exit 3 rather than run, because a missing `jq` renders as empty DATA and the work carries on with it. Everywhere else it still degrades. The install prints a note when it is missing.
 - **`gh`** - for GitHub issue and PR work. Its built-in `--jq` is independent of the `jq` binary.
 
 ## Quick Start
@@ -33,6 +33,41 @@ npx @mmerterden/multi-agent-pipeline install --all       # all three
 /multi-agent:setup          # keychain token scan + git identity + default stack
 ```
 
+### No `npx` on that machine?
+
+`npx` ships with npm, and npm ships with Node - so "npx: command not found" almost
+always means Node is missing from that shell, not that anything is wrong with the
+package. Check first, then pick the row that matches:
+
+```bash
+node -v; npm -v; command -v node npm npx
+```
+
+| What you see | What to do |
+|---|---|
+| nothing at all | Install Node >= 20.11: `brew install node`, or the LTS installer from nodejs.org |
+| `node` works, `npx` does not | `npm i -g @mmerterden/multi-agent-pipeline` then `multi-agent-pipeline install --claude` |
+| nvm is installed but the shell does not see it | `source ~/.nvm/nvm.sh && nvm use --lts`, or just open a new terminal |
+| npm is ancient (< 5.2, which predates npx) | `npm i -g npm@latest`, or use the global-install row above |
+
+And the path that needs neither `npx` nor a global install - clone and run the
+installer directly:
+
+```bash
+git clone https://github.com/mmerterden/multi-agent-pipeline.git
+cd multi-agent-pipeline
+node index.js install --claude        # add --dry-run first to see what it would write
+```
+
+`npm exec @mmerterden/multi-agent-pipeline install --claude` also works on any npm
+7+ without `npx` on `PATH`.
+
+**One error that is not an npx problem.** This package declares `os: ["darwin"]`,
+so npm refuses to install it anywhere else and says `npm ERR! notsup Unsupported
+platform`. That is deliberate ([ADR-0012](./docs/adr/0012-macos-only.md)), not a
+missing tool: every credential read shells `security`, every iOS build
+`xcodebuild`, every piece of visual evidence `simctl`.
+
 Tool flags combine (`--claude --codex`). With no tool flag at all, the installer targets Claude Code only. Other flags: `--dry-run` (show what would be written, write nothing), `--platform=ios|android|all` (skip the stack skills you do not need), `--link` (symlink instead of copy, for local development).
 
 Run a task - the input type is auto-detected:
@@ -72,6 +107,13 @@ checkout):
 
 `/multi-agent:analysis` runs its own shorter chain and, since v16.12.0, reviews what it wrote before publishing it: the draft goes through the same three-reviewer set and triage as a code diff, a blocking finding returns it to synthesis with dispatch closed, and the gaps that survive are either searched, asked about, or recorded with an owner. It used to publish behind a structural validator alone.
 
+### 18.0.0: one state directory, and a way to ask whether your install is real
+
+- **`multi-agent-pipeline verify`.** The install is a copy, and from the moment it is written the two halves drift independently: an edit in the installed tree is behaviour with no source, and a file the installer skipped is a script the docs describe and nobody has. `verify` compares both against a manifest built at pack time. What a green result proves is stated plainly - the bytes match what the publisher recorded, not who published them.
+- **Cost, past the single run.** The per-task ceiling cannot see the two ways a budget actually empties: a drift that trips nothing, and one session that burns a week in an hour while every run stays under its cap. `cost-analyze` projects, finds days out of family by median absolute deviation, and reports acceleration - as LIST-price estimates, which it says on every run rather than in a footnote.
+- **A run's state lives in one place.** `{project}/{taskId}/` is canonical, the flat layout is still read, and a run that exists in both is counted once.
+- **Server readiness, entirely opt-in.** `doctor --profile=server` adds four checks that only matter when nobody is at the keyboard, `install --unattended` writes a permission profile after printing it, and the autopilot runner now survives a month unwatched. The default install writes no permissions and the default doctor run is unchanged, because a laptop told it fails a server check learns to ignore doctor.
+
 ### Your package manager, your hooks, your MCP surface
 
 Three smaller things in 17.6.0, each closing a gap where the pipeline assumed instead of looking:

package/README.tr.md

@@ -33,6 +33,40 @@ npx @mmerterden/multi-agent-pipeline install --all       # üçü birden
 /multi-agent:setup          # keychain token taraması + git kimliği + varsayılan stack
 ```
 
+### O makinede `npx` yoksa
+
+`npx` npm ile, npm de Node ile gelir - yani "npx: command not found" neredeyse her
+zaman o kabukta Node olmadığı anlamına gelir, pakette bir sorun olduğu değil. Önce
+bak, sonra sana uyan satırı uygula:
+
+```bash
+node -v; npm -v; command -v node npm npx
+```
+
+| Gördüğün | Yapılacak |
+|---|---|
+| hiçbiri yok | Node >= 20.11 kur: `brew install node` ya da nodejs.org'dan LTS installer |
+| `node` çalışıyor, `npx` çalışmıyor | `npm i -g @mmerterden/multi-agent-pipeline` sonra `multi-agent-pipeline install --claude` |
+| nvm kurulu ama kabuk görmüyor | `source ~/.nvm/nvm.sh && nvm use --lts`, ya da yeni bir terminal aç |
+| npm çok eski (< 5.2, npx'ten önceki sürümler) | `npm i -g npm@latest`, ya da üstteki global kurulum satırı |
+
+Ne `npx` ne de global kurulum isteyen yol - klonla ve installer'ı doğrudan çalıştır:
+
+```bash
+git clone https://github.com/mmerterden/multi-agent-pipeline.git
+cd multi-agent-pipeline
+node index.js install --claude        # önce --dry-run ile ne yazacağını görebilirsin
+```
+
+`npm exec @mmerterden/multi-agent-pipeline install --claude` de, `PATH`'te `npx`
+olmayan her npm 7+ üzerinde çalışır.
+
+**npx sorunu olmayan bir hata.** Bu paket `os: ["darwin"]` beyan eder; npm başka
+hiçbir yerde kurmaz ve `npm ERR! notsup Unsupported platform` der. Bu kasıtlıdır
+([ADR-0012](./docs/adr/0012-macos-only.md)), eksik bir araç değil: her credential
+okuması `security`, her iOS build'i `xcodebuild`, her görsel kanıt `simctl`
+çağırıyor.
+
 Tool flag'leri birleştirilebilir (`--claude --codex`). Hiç tool flag'i verilmezse installer sadece Claude Code'u hedefler. Diğer flag'ler: `--dry-run` (ne yazılacağını gösterir, hiçbir şey yazmaz), `--platform=ios|android|all` (ihtiyacın olmayan stack skill'lerini atlar), `--link` (kopyalamak yerine symlink, lokal geliştirme için).
 
 Bir görev çalıştır - girdi tipi otomatik algılanır:
@@ -72,6 +106,13 @@ mu):
 
 `/multi-agent:analysis` kendi kısa zincirini koşar ve v16.12.0'dan beri yazdığını yayınlamadan önce review ediyor: taslak, bir kod diff'iyle aynı üç-reviewer setinden ve triyajdan geçiyor, bloklayıcı bulgu dokümanı sentez fazına geri gönderip dispatch'i kapatıyor, hayatta kalan boşluklar ya aranıyor ya sana soruluyor ya da sahibiyle birlikte kayda giriyor. Önceden yalnızca yapısal bir validator'ın arkasından yayınlıyordu.
 
+### 18.0.0: tek bir durum dizini, ve kurulumun gerçekten o kurulum olup olmadığını sorma yolu
+
+- **`multi-agent-pipeline verify`.** Kurulum bir kopyadır ve yazıldığı andan itibaren iki taraf birbirinden bağımsız kayar: kurulu ağaçtaki bir düzenleme kaynağı olmayan bir davranıştır, kurulumun atladığı dosya ise dokümanın anlattığı ama kimsede olmayan bir script. `verify` ikisini de paketleme anında üretilen bir manifest'e karşı karşılaştırır. Yeşil sonucun ne kanıtladığı açıkça yazılıdır: baytlar yayıncının kaydettiğiyle aynıdır, kimin yayınladığı değil.
+- **Maliyet, tek koşunun ötesinde.** Görev başına tavan, bütçeyi gerçekten bitiren iki şeyi göremez: hiçbir koşuyu aşmayan kayma, ve her koşu tavanın altında kalırken bir saatte bir haftayı yakan tek oturum. `cost-analyze` projeksiyon yapar, medyan mutlak sapmayla aileden ayrılan günü bulur ve ivmeyi raporlar - liste fiyatından tahmin olarak, ve bunu dipnotta değil her koşuda söyler.
+- **Bir koşunun durumu tek yerde.** `{project}/{taskId}/` kanonik, düz yerleşim hâlâ okunuyor, ve iki yerde birden duran koşu bir kez sayılıyor.
+- **Sunucu hazırlığı, tamamen opt-in.** `doctor --profile=server` yalnızca klavyede kimse yokken anlamı olan dört kontrol ekler, `install --unattended` izin profilini yazmadan önce gösterir, autopilot runner artık bir ay gözetimsiz ayakta kalır. Varsayılan kurulum hiçbir izin yazmaz ve varsayılan doctor koşusu değişmez: sunucu kontrolünden kaldığı söylenen bir dizüstü, doctor'ı görmezden gelmeyi öğrenir.
+
 ### Paket yöneticisi, hook'lar ve MCP yüzeyi
 
 17.6.0'da üç küçük iş; üçü de pipeline'ın bakmak yerine varsaydığı bir yeri kapatıyor:

package/docs/adr/0011-dormant-ci.md

@@ -1,6 +1,6 @@
 # 11. CI stays in the repository but dormant; the pre-push gate is primary
 
-**Status:** Accepted · 2026-08-31 · amended 2026-09-13
+**Status:** Accepted · 2026-08-31 · amended 2026-09-13 · amended 2026-09-17
 
 > **Amendment, 2026-09-13 (ADR-0012, macOS only).** Linux and Windows support
 > was removed. `package.json` now declares `os: ["darwin"]`, which npm enforces
@@ -91,6 +91,30 @@ gate already covers everything except the three items listed above.
 only macOS, disappears when the laptop is closed, and a self-hosted runner on a
 public repository executes code from any fork's pull request.
 
+> **Amendment, 2026-09-17.** Two of those three reasons have moved.
+>
+> "Covers only macOS" stopped being a cost when ADR-0012 removed the other
+> platforms: macOS is now the only target, so a macOS-only runner covers all of
+> it.
+>
+> The fork argument is weaker than it was but is NOT gone, and the difference is
+> worth stating precisely because the plan that revisited this got it wrong.
+> The repository is private, which is the important half. It is not
+> fork-free: measured on 2026-09-17 it has **one fork**, owned by another
+> account. GitHub requires approval before a fork's pull request runs a
+> workflow, so the exposure is gated - but the gate is a setting and an
+> approval given by reflex puts that code on the runner, with the runner's
+> keychain.
+>
+> "Disappears when the laptop is closed" is the reason this is still not the
+> default. It becomes a real option only on a machine that stays awake, which
+> is what `docs/server-readiness.md` describes and why that page is a
+> prerequisite rather than a companion.
+>
+> The decision is unchanged: CI stays dormant and the pre-push gate stays
+> primary. What changed is that a self-hosted runner is now a supported option
+> for someone who has read that page, rather than a rejected one.
+
 **Delete the workflows.** Honest but lossy. The files encode which steps matter
 and in what order, and the possible issue-triggered direction would have to
 rebuild them from nothing.

package/docs/server-readiness.md

@@ -0,0 +1,188 @@
+# Running multi-agent on a machine nobody is sitting at
+
+This describes what a Mac has to have before an unattended run works, and what
+breaks if it does not. **Nothing here is set up by reading it** - `install`
+still writes nothing about permissions and no scheduler is loaded unless you
+ask for one. That is deliberate: every item below changes what runs on a
+machine without a human, and none of it should happen because someone ran an
+installer.
+
+Scope is macOS. Linux and Windows were removed on purpose (ADR-0012) and
+nothing here reintroduces them.
+
+The mechanical half of this page is `doctor --profile=server`, which checks
+four of the conditions below and says which are missing. Read that first; this
+page explains why each one matters and what to do about it.
+
+## The failure this page exists for
+
+An unattended run does not fail loudly. It **stops without saying so**, and
+every way it does that looks identical from outside: a process that is running,
+printing nothing, finishing never.
+
+Four causes, in the order they bite.
+
+## 1. The permission posture
+
+autopilot spawns its child with `--permission-prompts none`. That stops Claude
+Code from ASKING, and it does not grant anything - the tools the child then
+calls still have to be allowed. On the maintainer's machine they are, because
+`Bash`, `Edit`, `Write` and `Agent` sit in the global allow list from years of
+interactive use. On a fresh machine they do not, and the first tool call ends
+the run.
+
+There is no DEFAULT that fixes this and should not be: writing a permission
+posture into someone's settings during an install is the one action an
+installer must never take silently. There is now a flag that asks for it:
+
+```bash
+npx @mmerterden/multi-agent-pipeline install --unattended --dry-run   # see it first
+npx @mmerterden/multi-agent-pipeline install --unattended             # write it
+```
+
+It prints the whole profile with a reason per line before writing anything, and
+it is additive: an entry you added by hand survives, a narrower `Bash(...)` rule
+is kept alongside, unrelated settings are untouched, and a second run changes
+nothing. A `settings.json` that does not parse is refused rather than
+overwritten.
+
+By hand, the same thing is:
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "permissions": {
+    "allow": ["Bash", "Edit", "Write", "Agent"]
+  }
+}
+```
+
+Grant the narrowest set the work needs. A server that only reviews does not
+need `Write` - though note that the shipped profile is deliberately broad,
+because a run builds and tests whatever the target repo uses and a narrow list
+is the one the first unfamiliar repo stops at.
+
+`doctor --profile=server` reports this as `unattended-permissions`, against the
+same rule the writer applies.
+
+## 2. The scheduler, and why it is a LaunchAgent
+
+Something has to start the work. The template ships as a **LaunchAgent**
+(`install/templates/multi-agent-autopilot.plist.template`), loaded in the
+user's session at login - not a LaunchDaemon at boot.
+
+That is a keychain decision, not a preference. Every credential the pipeline
+reads lives in the login keychain, and the login keychain is **locked until the
+user logs in**. A daemon started at boot gets a locked one: each credential
+read fails, and those failures surface much later as 401s that blame the token.
+The lock is the cause and nothing in the error says so.
+
+So the machine needs to reach a logged-in session by itself:
+
+- **System Settings → Users & Groups → Automatic login**, for the account that
+  owns the agent.
+- A **keychain with no lock timeout** for that account, or the agent survives
+  a login and dies at the first idle period:
+  ```
+  security set-keychain-settings -l ~/Library/Keychains/login.keychain-db
+  ```
+  (no `-t`, so there is no timeout; `-l` still locks on sleep.)
+
+Automatic login means physical access to the machine is access to the
+credentials. On a server in a locked room that is the trade being made; on a
+laptop it is not.
+
+`doctor --profile=server` reports these as `scheduler` and `keychain-unlock`.
+
+## 3. The unattended contract
+
+`MULTI_AGENT_UNATTENDED=1` is how a run states that nobody is watching.
+`multi-agent-refs/unattended-contract.md` lists exactly which entry points read
+it and what each resolves to - four of them, named, because a claim of coverage
+that is not true is worse than a short list.
+
+The variable does **not** grant permissions and does not suppress errors. It
+only stops a process from waiting for an answer that is not coming.
+
+`doctor --profile=server` reports this as `unattended-contract`.
+
+## 4. Which credential each phase needs
+
+A server fails differently from a laptop here: an interactive run asks for a
+missing token, an unattended one does not.
+
+| Phase | Needs | Absent |
+|---|---|---|
+| 0 Init | `github` (issue intake), `jira` (ticket intake) | the run cannot resolve its input and stops at the picker |
+| 1-2 Analysis, Plan | `figma` or `figma_mcp` when the task names a design | halts by contract rather than guessing at layout |
+| 3 Dev | none beyond git access | - |
+| 4 Review | `github` for PR comments | findings are computed and never posted |
+| 5 Test | none | - |
+| 6 Commit | git push credential | the branch stays local, which reads as "no PR yet" |
+| 7 Report | `jira`, `confluence` as configured | the report is composed and dropped |
+
+`credential-store.sh doctor` lists what is mapped. `doctor --probe` additionally
+checks each one is alive, which costs network calls and is why it is opt-in.
+
+## 4b. What the runner does when nobody is looking
+
+Three behaviours that are invisible on a laptop and decide whether a server
+survives a month.
+
+**The log.** launchd appends the runner's stdout to `runner.log` forever. Each
+tick truncates it past `MA_AP_LOG_MAX_BYTES` (5MB by default), keeping the last
+256KB in `runner.log.1`. It truncates the SAME file rather than renaming it,
+because launchd holds it open with `O_APPEND` - rename it and that descriptor
+keeps writing into the renamed file while the new one stays empty, which is the
+rotation that looks correct and silently stops logging.
+
+**The breaker.** An expired token, a `claude` that no longer launches, a full
+disk: every queued item fails the same way, minutes apart, until the queue is
+empty and the ledger is a list of identical failures with no indication which
+came first. After `MA_AP_BREAKER_LIMIT` consecutive attempts that produced
+nothing (3 by default, 0 disables), the runner stops taking new work, writes the
+reason into `queue.json` so `autopilot-status` shows it, and says what to check.
+One successful attempt clears it. A run waiting for a person (`needs-input`) and
+an item arming refused (`blocked-*`) are deliberately not failures.
+
+**Telemetry.** `ticks.jsonl` gets one JSON line per tick. The human log answers
+"what happened just now"; a server is only ever asked "how has this been
+behaving for a week".
+
+## 5. Self-hosted CI runner
+
+ADR-0011 rejected a self-hosted runner because "a self-hosted runner on a
+public repository executes code from any fork's pull request". Half of that has
+changed and half has not, and the difference matters before wiring a runner to
+a machine that holds credentials.
+
+Measured, not assumed: the repo is **private**, and it has **one fork**, owned
+by another account. "Zero forks" is a claim worth not making - GitHub requires
+approval before a fork's pull request runs a workflow, but that protection is a
+SETTING, and a self-hosted runner turns "someone approved a workflow run by
+reflex" into code on this machine with this keychain.
+
+So: a runner here is defensible on a private single-owner repo, and it is
+defensible only while fork-PR approval stays on and every approval is treated
+as a decision rather than a formality.
+
+The same machine can host the runner:
+
+```
+mkdir ~/actions-runner && cd ~/actions-runner
+# download and configure per GitHub's instructions for the repo
+./svc.sh install && ./svc.sh start
+```
+
+Two things to keep in mind. The runner service runs in the same session as the
+autopilot agent, so a long CI job and a pipeline run compete for the same CPU
+and the same `~/.claude` state root. And the runner inherits that session's
+keychain, which means a workflow can read the credentials - acceptable on a
+single-owner machine, not on a shared one.
+
+## What this page does NOT cover
+
+- Turning any of it on. Every step here is the operator's to take.
+- Linux, Windows, systemd, Docker. Out of scope and staying there.
+- Multi-user servers. Everything above assumes one account owns the install,
+  the keychain and the queue.

package/index.js

@@ -69,6 +69,15 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error("uninstall failed:", e.message);
     process.exit(1);
   });
+} else if (command === "verify") {
+  // The manifest and this command are the answer to "is my install the thing
+  // that was published". Kept out of PLATFORM_EXEMPT on purpose: verifying an
+  // install on a host the pipeline refuses to run on answers a question nobody
+  // has.
+  const { main } = await import(
+    pathToFileURL(join(__dirname, "pipeline", "scripts", "verify.mjs")).href
+  );
+  await main();
 } else if (command === "help") {
   console.log(`
   multi-agent-pipeline - 8-phase AI development pipeline
@@ -93,6 +102,12 @@ if (command === "--version" || command === "-v" || command === "version") {
     npx @mmerterden/multi-agent-pipeline uninstall --all-data ALSO remove pipeline settings + logs/state/metrics
     npx @mmerterden/multi-agent-pipeline uninstall --cursor   Legacy pre-v10.7 adapter-file cleanup (also --copilot-chat / --antigravity; --target=<path> overrides cwd)
 
+  Verify (is this install the thing that was published):
+    npx @mmerterden/multi-agent-pipeline verify            Package hashes + ~/.claude drift
+    npx @mmerterden/multi-agent-pipeline verify --package  Package integrity only
+    npx @mmerterden/multi-agent-pipeline verify --install  Install drift only
+    npx @mmerterden/multi-agent-pipeline verify --json
+
   Help:
     npx @mmerterden/multi-agent-pipeline help
     npx @mmerterden/multi-agent-pipeline --version    Print the installed version
@@ -111,7 +126,7 @@ if (command === "--version" || command === "-v" || command === "version") {
   `);
 } else {
   console.error(`Unknown command: ${command}`);
-  console.error("Valid commands: install, uninstall, delete, help, version (--version/-v)");
+  console.error("Valid commands: install, uninstall, delete, verify, help, version (--version/-v)");
   console.error("Run with 'help' for usage.");
   process.exit(1);
 }

package/install/_common.mjs

@@ -141,6 +141,34 @@ export function removePipelineAgentFiles(destDir, agentsSrc) {
  * @param {string} dest
  * @param {{ exclude?: Array<string|RegExp>, useSymlinks?: boolean }} [opts]
  */
+/**
+ * Build and editor droppings that live inside a source tree and must never
+ * reach a user's install. Python writes `__pycache__/<mod>.cpython-NNN.pyc`
+ * next to any script it IMPORTS, so a tree that has merely been used has them;
+ * the Finder writes .DS_Store into any directory it has displayed.
+ *
+ * This is not cosmetic. The installed file count is a gate in this repo, and a
+ * CI runner on Python 3.14 shipped 147 files where every developer tree shipped
+ * 146 - for four rounds the difference looked like a fixture bug, because the
+ * extra file was untracked and therefore invisible to every diff of the SOURCE.
+ * Filtering here fixes the user-visible half too: a .pyc compiled against one
+ * interpreter is worse than useless on another.
+ *
+ * @param {string} rel  path relative to the copy root, posix-separated
+ * @returns {boolean}
+ */
+function isCopyJunk(rel) {
+  return (
+    rel === ".DS_Store" ||
+    rel.endsWith("/.DS_Store") ||
+    rel === "__pycache__" ||
+    rel.startsWith("__pycache__/") ||
+    rel.includes("/__pycache__/") ||
+    rel.endsWith("/__pycache__") ||
+    rel.endsWith(".pyc")
+  );
+}
+
 export function copyDir(src, dest, opts = {}) {
   const { exclude = [], useSymlinks = false, skipExisting = false } = opts;
   if (useSymlinks) {
@@ -156,26 +184,23 @@ export function copyDir(src, dest, opts = {}) {
   // user-owned trees (rules/) so an update adds new baseline files but preserves
   // the user's locally-evolved copies. cpSync with force:false + errorOnExist:false
   // silently skips existing files.
+  // Normalize to forward slashes so exclude patterns (written posix-style)
+  // also match on win32, where cpSync hands back backslash paths.
+  const relOf = (source) => source.slice(src.length).split("\\").join("/").replace(/^\//, "");
+  // Junk is filtered on EVERY path, including the two that take no exclude
+  // list: the point is that the caller never has to remember it.
+  const filter = (source) => {
+    const rel = relOf(source);
+    if (isCopyJunk(rel)) return false;
+    return !exclude.some((pat) =>
+      typeof pat === "string" ? rel === pat || rel.startsWith(pat + "/") : pat.test(rel),
+    );
+  };
   if (skipExisting) {
-    cpSync(src, dest, { recursive: true, force: false, errorOnExist: false });
+    cpSync(src, dest, { recursive: true, force: false, errorOnExist: false, filter });
     return;
   }
-  if (exclude.length === 0) {
-    cpSync(src, dest, { recursive: true, force: true });
-    return;
-  }
-  cpSync(src, dest, {
-    recursive: true,
-    force: true,
-    filter: (source) => {
-      // Normalize to forward slashes so exclude patterns (written posix-style)
-      // also match on win32, where cpSync hands back backslash paths.
-      const rel = source.slice(src.length).split("\\").join("/").replace(/^\//, "");
-      return !exclude.some((pat) =>
-        typeof pat === "string" ? rel === pat || rel.startsWith(pat + "/") : pat.test(rel),
-      );
-    },
-  });
+  cpSync(src, dest, { recursive: true, force: true, filter });
 }
 
 /**

package/install/_dev-only-files.mjs

@@ -58,6 +58,10 @@ export const MAINTAINER_SMOKES = new RegExp(
 const DEV_ONLY_TOOLING = Object.freeze([
   "run-smokes.mjs",
   "scorecard.mjs",
+  // Runs scorecard.mjs from the repo root and diffs its snapshots. In an
+  // install that root is $HOME, so the scorecard it shells out to is not
+  // there - shipping it would hand the user a command that cannot work.
+  "scorecard-snapshot.mjs",
   "lint-skills.mjs",
   "lint-personas.mjs", // imports install/_codex-agents.mjs, which never ships to scripts/
   "lint-mcp-refs.mjs",
@@ -66,6 +70,10 @@ const DEV_ONLY_TOOLING = Object.freeze([
   "validate-schemas.mjs", // validates the repo's own schema files, needs ajv
   "sync-parity-check.sh",
   "benchmark-phase-0.sh",
+  // Publish-time only: `prepack` runs it from the repo root to write
+  // manifest.json into the tarball. It shells `npm pack` against that root,
+  // which in an install is $HOME - so an installed copy could only ever fail.
+  "make-manifest.mjs",
 ]);
 
 /** Eval harnesses (`eval-*.mjs`) read `pipeline/eval/**`, which never ships. */