@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/multi-agent-refs/unattended-contract.md

@@ -0,0 +1,129 @@
+# Unattended contract (`MULTI_AGENT_UNATTENDED=1`)
+
+<!-- toc -->
+- [What the variable means](#what-the-variable-means)
+- [The three effects](#the-three-effects)
+- [What it does NOT do](#what-it-does-not-do)
+- [Who honours it](#who-honours-it)
+- [The model side already has a contract](#the-model-side-already-has-a-contract)
+- [Default behaviour is unchanged, and a gate says so](#default-behaviour-is-unchanged-and-a-gate-says-so)
+- [The permission posture](#the-permission-posture)
+<!-- /toc -->
+
+## What the variable means
+
+`MULTI_AGENT_UNATTENDED=1` is the operator stating that **nobody is watching
+this process**, and it is the only way to state it reliably.
+
+The usual test for that is `[ -t 0 ]`: no terminal, no human. It is wrong in
+both directions on a server. A run under `screen`, `tmux`, `ssh -t` or a login
+shell HAS a terminal and still has nobody in front of it, so the test says
+"ask" and the process waits for an answer that will never come - printing
+nothing, exiting never, and looking exactly like slow work. That is the failure
+this contract exists to remove, and it is not hypothetical: two setup scripts
+shipped that way.
+
+The variable is opt-in and defaults to absent. Nothing in this file describes
+behaviour that changes on a machine that does not set it.
+
+## The three effects
+
+**1. No prompt blocks.** Every shell entry point that asks a question either
+resolves it from a documented default or refuses with a reason on stderr and a
+non-zero exit. Waiting is never one of the outcomes. Refusing beats hanging:
+one of them can be read in a log.
+
+**2. Output is greppable.** Colour is off even when stdout is a terminal.
+ANSI escapes in a log file make it unsearchable, and on a server the terminal
+that is attached is not the one anyone reads.
+
+**3. A secret is never a prompt.** Credentials arrive through stdin or a file
+path, never through an interactive read and never through an environment
+variable. An env value is inherited by every child process and is visible to
+`ps e` on some systems; a pipe stays in the one process that needs it.
+
+## What it does NOT do
+
+- It does not grant permissions. An unattended run still needs a permission
+  posture, which is a separate opt-in (`install --unattended`) and a separate
+  doctor check.
+- It does not suppress errors. A run that cannot proceed still fails; it just
+  fails visibly instead of hanging.
+- It does not change any default. With the variable unset, every script below
+  behaves exactly as it did before this contract existed.
+
+## Who honours it
+
+Paths below are install-relative: `lib/` and `scripts/` under the host root,
+which is `~/.claude`, `~/.copilot` or `~/.codex` depending on the install. A
+ref that ships to users must not name a checkout path, because a run happens
+in the user's worktree and the checkout is not there.
+
+| Entry point | Without the variable | With `MULTI_AGENT_UNATTENDED=1` |
+|---|---|---|
+| `lib/ask-choice.sh` | TTY: renders the menu and reads. No TTY: first option, notice on stderr | First option (or `ASK_CHOICE_DEFAULT`), never prompts |
+| `scripts/github-ssh-setup.sh` | TTY: three questions. No TTY: refuses, naming `SSH_SETUP_EMAIL` | Refuses the same way even with a terminal |
+| `scripts/keychain-save.sh` | TTY: menu + secret prompt. No TTY: refuses, naming `--stdin` / `--json` | Refuses the same way even with a terminal |
+| `scripts/phase-banner.sh` | Colour when stdout is a TTY and `TERM != dumb` | Plain text |
+
+Anything not in this table does not read the variable. That is deliberate: a
+list of four that is true beats a claim of coverage that is not.
+
+## The model side already has a contract
+
+The prompt-level question - what an agent does when it would call
+`AskUserQuestion` and no one can answer - is `refs/picker-contract.md`, section
+"Autopilot / non-interactive contract", and it predates this file. It resolves
+from the remembered choice first, then the documented default, and records
+which rule fired so the run stays readable afterwards.
+
+The two are different layers and should not be merged. The picker contract
+governs a model deciding; this file governs a process waiting. A run on a
+server needs both, and only one of them can be enforced by a gate.
+
+## Default behaviour is unchanged, and a gate says so
+
+`smoke-unattended-profile.sh` (a maintainer gate, not shipped) asserts both directions. With the variable set,
+each entry point above resolves or refuses under a hard timeout. With it unset,
+each one produces byte-identical output to the behaviour it had before - the
+assertion that matters most, because the whole point is that a local
+interactive machine is not affected by any of this.
+
+## The permission posture
+
+Everything above concerns a process that would otherwise WAIT. There is a second
+way an unattended run stops, and it does not wait at all.
+
+autopilot spawns its child with `--permission-prompts none`. That stops Claude
+Code from ASKING; it grants nothing. The tools the child then calls still have
+to be allowed, and on a fresh machine they are not - so the run stops at the
+first tool call, with no prompt anywhere for a person to answer. From the
+outside it is indistinguishable from a queue with nothing to do.
+
+`install --unattended` writes the profile that closes it:
+
+```bash
+npx @mmerterden/multi-agent-pipeline install --unattended --dry-run   # show it
+npx @mmerterden/multi-agent-pipeline install --unattended             # write it
+```
+
+Three properties, each one a promise to somebody who did not ask for this:
+
+1. A DEFAULT install writes no permissions at all. Widening a permission set is
+   not something an installer does to a person who wanted files copied.
+2. The profile is printed in full, with a reason per line, BEFORE anything is
+   written. "The installer changed my permissions" must never be a thing
+   discovered afterwards.
+3. It is additive and idempotent. An entry a person added by hand survives, a
+   narrower 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.
+
+The entries are broad, and that breadth is what unattended operation costs
+rather than an oversight: a run builds and tests whatever the target repo uses,
+so an allowlist narrow enough to be interesting is one the first unfamiliar repo
+stops at. `doctor --profile=server` reports `unattended-permissions` against the
+same rule the writer applies, so the two cannot disagree.
+
+`smoke-unattended-install-profile.sh` asserts all of it, including that a plain
+install still writes nothing.

package/pipeline/preferences-template.json

@@ -76,7 +76,7 @@
     },
     "usageLog": {
       "enabled": false,
-      "endpoint": "https://mmerterden.vercel.app/api/usage/ingest",
+      "endpoint": "https://mmerterden.com/api/usage/ingest",
       "token": ""
     },
     "derivedSkillSources": [],

package/pipeline/schemas/agent-state.schema.json

@@ -97,7 +97,9 @@
           "enum": ["remote", "local"],
           "description": "Where the candidate ref list came from. local means the fetch failed and the list is the local cache plus local heads - possibly stale, possibly incomplete."
         },
-        "chosen": { "type": "string" },
+        "chosen": {
+          "type": "string"
+        },
         "ambiguous": {
           "type": "boolean",
           "description": "Two or more candidates tied at the top score. Autopilot may not record derived when this is true."
@@ -107,8 +109,13 @@
           "additionalProperties": false,
           "description": "The release-branch template inferred from the refs that exist, never from a built-in table.",
           "properties": {
-            "template": { "type": "string" },
-            "members": { "type": "integer", "minimum": 0 }
+            "template": {
+              "type": "string"
+            },
+            "members": {
+              "type": "integer",
+              "minimum": 0
+            }
           }
         },
         "candidates": {
@@ -118,9 +125,18 @@
             "additionalProperties": false,
             "required": ["branch"],
             "properties": {
-              "branch": { "type": "string" },
-              "score": { "type": "number" },
-              "refs": { "type": "array", "items": { "type": "string" } },
+              "branch": {
+                "type": "string"
+              },
+              "score": {
+                "type": "number"
+              },
+              "refs": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
               "evidence": {
                 "type": "array",
                 "items": {
@@ -140,26 +156,121 @@
                         "ref-provenance"
                       ]
                     },
-                    "detail": { "type": "string" }
+                    "detail": {
+                      "type": "string"
+                    }
                   }
                 }
               }
             }
           }
         },
-        "notes": { "type": "array", "items": { "type": "string" } },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "askedOnIssue": {
           "type": ["object", "null"],
           "additionalProperties": false,
           "description": "The one comment autopilot is allowed to post when the derivation is ambiguous, gated by prefs.global.baseBranchEvidence.autopilotAsksOnIssue (default false). A question, never a state change: no transition, no close, no assignee. Posting it trips circuit-breaker trigger 6 and the run waits for resume.",
           "properties": {
-            "target": { "type": "string" },
-            "url": { "type": "string" },
-            "at": { "type": "string", "format": "date-time" }
+            "target": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            },
+            "at": {
+              "type": "string",
+              "format": "date-time"
+            }
           }
         }
       }
     },
+    "maturity": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How ready the fetched item was to be developed. Produced by lib/issue-fetcher.sh, which owns the gap codes and their localized wording. Declared as of v17.6.0 - it had been written by every issue-shaped run since long before and read by Phase 0, Phase 4 and the clarifier, while this schema forbade it under additionalProperties: false.",
+      "properties": {
+        "score": {
+          "type": ["integer", "null"],
+          "minimum": 0,
+          "maximum": 100,
+          "description": "100 minus 40 per blocker and 10 per warning. Null for free-text input: there is no item to be immature."
+        },
+        "blockers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Stable gap codes that stop a run: status_closed, already_resolved, description_empty."
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Stable gap codes that do not stop a run on their own."
+        },
+        "summary": {
+          "type": "string",
+          "description": "The blockers and warnings rendered in outputLanguage. The one place this wording exists; maturity-followup.mjs quotes it rather than re-deriving it."
+        },
+        "accepted": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Gap codes a human explicitly waved through at the interactive maturity step. Recording WHICH gap was accepted is what separates an informed continue from a skipped check."
+        }
+      }
+    },
+    "maturityFollowup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gaps", "askedAt"],
+      "description": "v17.6.0+ - the record of an autopilot run having asked about an immature item (refs/features/maturity-followup.md). Absent means never asked, which is what makes the first pass distinguishable from every pass after it.",
+      "properties": {
+        "gaps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Sorted and deduplicated, so the next pass's comparison is stable rather than order-dependent."
+        },
+        "askedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["jira", "github", "confluence", "analysis", "unknown"]
+            },
+            "key": {
+              "type": ["string", "null"]
+            },
+            "url": {
+              "type": ["string", "null"]
+            }
+          }
+        },
+        "commentUrl": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "waitingFor": {
+      "type": "string",
+      "enum": ["maturity", "user-channels-choice"],
+      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. Declared as of v17.6.0: Phase 7's channels pause has written it since long before, and resume/SKILL.md never read it, so that pause was resumable only in prose. resume reads this first and falls back to currentPhase + 1 when it is absent. maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 7's channels menu, with the stored channelsInput."
+    },
     "workspaceSource": {
       "type": "string",
       "enum": ["asked", "command", "autopilot"],

package/pipeline/schemas/prefs.schema.json

@@ -969,6 +969,28 @@
             }
           }
         },
+        "maturityFollowup": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v17.6.0+ - what to do about an item the maturity check finds is not ready (refs/features/maturity-followup.md). The check has always produced a machine-readable gap list and then thrown it away: a blocker halted the run, the queue moved on, and the item stayed exactly as immature as it was found.",
+          "properties": {
+            "askInteractively": {
+              "type": "boolean",
+              "default": true,
+              "description": "An interactive blocker asks at the maturity step - open the item and fix it, continue without it (recording which gap was waved through), or abort - instead of ending the run with a summary. False restores the old halt."
+            },
+            "autopilotCommentsOnIssue": {
+              "type": "boolean",
+              "default": false,
+              "description": "OFF by default, and an outward-facing write. When on, an autopilot run posts ONE comment on the Jira or GitHub item asking for what is missing, then halts on the circuit breaker and waits for resume. A question, never a state change: no transition, no resolution, no assignee, no label, no close. The body uses Ref:, never Closes:/Fixes:/Resolves:, and its copy follows outputLanguage. It never comments twice for the same gap set - a changed item is re-checked, and only a DIFFERENT gap set earns a second comment."
+            },
+            "commentOnWarnings": {
+              "type": "boolean",
+              "default": false,
+              "description": "Treat warnings like blockers. Off by default because warnings have always auto-continued under autopilot, and converting them to halts in a release would stall queues overnight on items that ran fine yesterday. The gaps are recorded either way."
+            }
+          }
+        },
         "baseBranchEvidence": {
           "type": "object",
           "additionalProperties": false,
@@ -1975,6 +1997,19 @@
               "description": "Prefix of the identity label a created issue carries. The label is how a second run, on a second machine or by a second analyst, finds the tree it already made instead of opening a duplicate."
             }
           }
+        },
+        "mcpSurface": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v17.6.0+ - how many MCP servers this host has registered. Every registered server's tool list is charged against the context window on EVERY turn, and the user adds them one at a time without ever seeing the running total; our own toolkit contributes 99 tools by itself. `doctor` reports the count, it never disables anything.",
+          "properties": {
+            "infoAbove": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 8,
+              "description": "Report the registered-server count once it exceeds this. The number is JUDGEMENT, not a measurement - it exists so the threshold is visible and adjustable instead of hidden in the script. 0 reports the count always."
+            }
+          }
         }
       }
     },

package/pipeline/schemas/token-budget.json

@@ -13,7 +13,7 @@
       "max_tokens": 6500
     },
     "phase-3-dev": {
-      "max_tokens": 9300
+      "max_tokens": 9450
     },
     "phase-4-review": {
       "max_tokens": 15150
@@ -28,5 +28,5 @@
       "max_tokens": 6350
     }
   },
-  "total_max_tokens": 63000
+  "total_max_tokens": 63150
 }