model-orchestrator 0.1.35 → 1.0.1

package/templates/advanced/vm/README.md

@@ -1,19 +1,19 @@
-# vm/: the box that runs it unattended
+# vm/: templates for your always-on Linux machine
 
-Level 3 = levels 1 and 2 plus a machine that is always on. A small Linux VM (any cloud's free ARM tier is enough) that holds the CLIs, a model gateway, and the scheduled jobs. Your laptop stays the interactive driver; the box owns the schedule.
+Level 3 adds deployment templates to levels 1 and 2. Provide a Linux machine sized for your workload to hold the CLIs, a model gateway, and the scheduled jobs. Your laptop stays the interactive driver; the machine owns the schedule after you configure it.
 
 Generated {{DATE}} for: `{{AI_IDS}}`. Installed at `{{INSTALL_DIR}}`; the systemd unit and the audit script carry that path.
 
-## The one architectural property
+## Keep provider credentials in the gateway
 
-**Only the gateway holds provider credentials.** Nothing else on the box does: not the orchestrator, not the scheduler, not a job. Every surface reaches models through the gateway, so rotating a key is a change in exactly one place. The gateway is bound to loopback (or a private mesh network), never to `0.0.0.0`.
+For metered API calls, inject provider credentials into the gateway and have jobs use its authenticated endpoint. Subscription CLIs keep their own vendor login state. Bind the gateway to loopback or the configured private network; never expose it publicly without explicit authorization and access controls.
 
 ## What runs where
 
 | Surface | Role | Reaches models via |
 |---|---|---|
 | The orchestrator CLI ({{PRIMARY_NAME}}) | interactive driver when you SSH in; dispatch brain for jobs | its own subscription, off the gateway |
-| `cli-run` lanes ({{CLI_RUN_LANES}}) | the other agent CLIs, headless | their own subscriptions (Lane A) |
+| `cli-run` lanes ({{CLI_RUN_LANES}}) | the other agent CLIs, headless | their own subscriptions (subscription lanes) |
 | The gateway (`docker-compose.yml`) | one OpenAI-compatible endpoint fronting every metered provider | provider keys from the environment |
 | A local model runtime (if selected) | the privacy lane | nothing leaves the box |
 | Scheduled jobs (`jobs/`) | the weekly gap-analysis audit (lane: `{{AUDIT_LANE}}`), and anything else recurring | the gateway, or `cli-run` |
@@ -22,25 +22,29 @@ Generated {{DATE}} for: `{{AI_IDS}}`. Installed at `{{INSTALL_DIR}}`; the system
 
 ## Setup, in order
 
-1. Provision a box. Ubuntu, 2+ vCPU, 8 GB is comfortable. Put it on a private mesh network if you can; do not open ports to the internet.
+The model-orchestrator installer writes these files only. When you separately invoke the generated `setup-vm.sh`, that manual deployment script installs the configured system dependencies and npm vendor CLIs. Review it before running it.
+
+1. Provision a machine sized for your workload and put it on the configured private network.
 2. `bash setup-vm.sh`. It installs system deps and the npm-installable CLIs, then **prints** the vendor shell installers for the rest. Read those scripts before running them.
 3. Sign each CLI in, using the flow its vendor gives you. Run these inside `tmux` so a dropped SSH session does not kill the prompt. Headless Linux has no keyring by default; `setup-vm.sh` installs one so the CLIs stop re-prompting.
 {{VM_SIGNIN}}
 4. Put provider keys in your secrets manager and export the names listed in `ENVIRONMENT.md` into the gateway's environment at start time. Never write a value into a file in this folder. The gateway config was rendered from the API keys you said you hold, not from your CLI subscriptions: those are different entitlements.
-5. `docker compose up -d`, then list the lanes without putting the key in argv (the key must be a single token, `^[A-Za-z0-9._-]+$`, because it is interpolated into curl's config grammar):
+5. From this `vm/` folder, run `bash setup-vm.sh --start-services` with those environment variables injected. It starts Compose and validates `GATEWAY_MASTER_KEY` as a single token matching `^[A-Za-z0-9._-]+$`. {{VM_LOCAL_SETUP}}
+
+   To inspect configured aliases afterward, keep the key out of argv:
    ```bash
    printf 'header = "Authorization: Bearer %s"\n' "$GATEWAY_MASTER_KEY" | curl -s --config - http://127.0.0.1:4000/v1/models
    ```
-6. Install the weekly audit: `jobs/README.md`.
+6. Install the weekly audit: `jobs/README.md`. Set the service's literal `PATH` to include the directories that hold your Node and selected CLI executables before enabling the timer.
 7. Copy `box-CLAUDE.md` to `~/CLAUDE.md` on the box (or your agent's equivalent rules file) so a session there inherits the house rules without you present.
 
 ## The dispatch shape
 
-1. **Deterministic pre-triage, zero tokens:** a keyword table sends the obvious cases (bulk patterns → the cheap lane, URLs and current events → the live lane, "review this" → the reviewer, "write this up" → the orchestrator).
-2. **Judgment dispatch:** everything else is routed by the orchestrator against `ROUTING.md` and `DELEGATION_MATRIX.md`, with a logged reason.
-3. **Free lane first, escalate on signal.** Every job starts on its $0 lane and climbs only on failure, low confidence, or an explicit "expensive to get wrong".
-4. **Unattended means no escalation to a human-gated tier.** An unresolved irreversible call is surfaced (a message, a ticket comment), never executed.
-5. **Writes stay locked to one writer.** Every other engine proposes; one writer records.
+1. When the task is obvious, use the routing table or `aunx route` suggestion to identify the candidate tier, then verify tools and scope.
+2. When judgment is needed, apply `ROUTING.md` and `DELEGATION_MATRIX.md` and record the selected route with a reason.
+3. When a cheaper eligible route can satisfy the checks, select it; when checks fail or required capability is absent, diagnose and choose an authorized fallback.
+4. When an unattended action exceeds the existing mandate, preserve the result and return the needed approval through the configured channel.
+5. When recording shared state, keep one writer and have other workers return proposed updates.
 
 ## The closed loop (name what watches it)
 
@@ -52,11 +56,12 @@ Generated {{DATE}} for: `{{AI_IDS}}`. Installed at `{{INSTALL_DIR}}`; the system
 
 "Nothing watches it" is a valid answer and usually the valuable one. Writing it down turns an invisible gap into a tracked one.
 
-## Never on this box
+## Keep the server within its scope
 
-- Vendor scripts run blind. Read first.
-- An unpinned image or package. `docker-compose.yml` and `setup-vm.sh` pin versions; bump them on purpose, never by restarting.
-- A provider key in a file in this folder, in shell history, in argv, or in a container image.
-- A service bound to `0.0.0.0`.
-- Private notes, client data, or personal records sent to a metered bulk lane. See `PRIVACY_GATES.md`.
-- A payment card attached to a compute lane "to unlock a tier". Free credit only unless a human says otherwise.
+- Read vendor scripts before executing them.
+- Update pinned packages and images deliberately, with a verification plan.
+- Keep provider secrets in the manager and out of argv, logs and generated files.
+- Bind services to loopback or the approved private network.
+- Apply the named data-processing permissions in `PRIVACY_GATES.md` before dispatch.
+- Obtain authorization before adding a paid resource or a payment method.
+- When optional companion tools are absent, use the local runtime, official documentation and project files specified by the protocols.

package/templates/advanced/vm/box-CLAUDE.md

@@ -1,28 +1,29 @@
-# CLAUDE.md for the box
+# Project instructions for the server
 
-Copy to `~/CLAUDE.md` on the machine (or your agent's equivalent rules file). A session here inherits these without a human present.
+When activating an unattended machine, copy these rules to the agent's documented instructions path and verify that a fresh session loads them.
 
-## Cost rule
-Prefer the cheapest tier that does the job well. Delegate grunt work through the dispatch layer; keep the reasoning in-session.
+## Choose the route
 
-Send to the cheap tier via the gateway or `cli-run`: bulk classification and tagging, reformatting, extraction, first-pass summaries, mechanical transforms, explicit rough drafts.
+When work is classification, extraction, formatting or other bounded volume, select an eligible cheap model. When it requires architecture, writing code, review or current sources, use the tier and tools named in `{{RULES_PATH}}/ROUTING.md` and `{{RULES_PATH}}/DELEGATION_MATRIX.md`.
 
-Never send to the cheap tier: anything that will be published in a person's own voice, code that gets committed, anything needing current vendor-specific knowledge, anything where being wrong is expensive, anything time-sensitive.
+When dispatch fails, inspect its class and report the cause. Continue locally only when the session has the required scope, tools and capacity.
 
-## On dispatch failure
-Report it and fall back to doing the work in-session. Never silently retry the same lane.
+## Keep service ingress private
 
-## Zero ingress
-Nothing binds to `0.0.0.0`. Nothing publishes a container port to the public interface. New services go on loopback or the private mesh.
+Bind services to loopback or the configured private network. Never publish a container port on the public interface without explicit authorization and the required access controls.
 
-## Unattended means no human-gated escalation
-An unresolved call that is irreversible or rewrites a standing rule gets surfaced (a message, a ticket comment) and stops. It is never executed on the strength of a model's confidence.
+## Handle unattended decisions
 
-## One writer
-Scheduled jobs and other engines propose. One writer records. If you are not that writer, produce a file and name it in your report.
+When an action exceeds the existing mandate, preserve the checked result and return the needed approval through the configured channel. Continue independent authorized work. Never execute an irreversible action solely on a model's confidence.
 
-## Secrets
-Names in the environment, values in the secrets manager. Never print one, never pass one in argv, never write one to disk here.
+## Record with one writer
 
-## Routing
-`{{RULES_PATH}}/ROUTING.md` and `{{RULES_PATH}}/DELEGATION_MATRIX.md` are the rules. `{{RULES_PATH}}/protocols/` are the procedures.
+When scheduled jobs or other engines produce evidence, return proposed updates to the designated record writer. Keep raw machine logs separate from curated records.
+
+## Protect secrets
+
+Load secret values from the configured manager at runtime. Never print them, put them in argv, or write them into this generated folder.
+
+## Run and verify
+
+When building, follow `{{RULES_PATH}}/protocols/build-protocol.md`. For background work, arm the five-minute heartbeat at launch and diagnose two checks without progress. When optional companions are absent, use the local runtime, official docs and project records described by each protocol.

package/templates/advanced/vm/docker-compose.yml

@@ -1,4 +1,5 @@
-# The gateway is the ONLY holder of provider credentials on this box.
+# This gateway receives provider credentials from its own launch environment.
+# The weekly audit uses a separate environment containing only the gateway bearer.
 # It is bound to loopback. Put it behind a private mesh network if other
 # machines need it; never publish it on 0.0.0.0.
 services:

package/templates/advanced/vm/jobs/README.md

@@ -4,12 +4,14 @@ Scheduled work on the box, as user-level systemd timers. Each job is a timer + s
 
 | Job | Schedule | Does | Lane | Watched by |
 |---|---|---|---|---|
-| `weekly-audit` | Monday 09:00 | collects live state (gateway lanes, timers, CLI versions), composes a brief with the protocol and `DELEGATION_MATRIX.md`, and asks a cli-run lane for the gap report | `{{AUDIT_LANE}}` (first enabled lane at install time; edit `AUDIT_LANE` in the script to change it) | nothing yet: wire a notifier and update this line |
+| `weekly-audit` | Monday 09:00 | collects live state (gateway lanes, timers, CLI versions), composes a brief with the protocol and `DELEGATION_MATRIX.md`, and asks a cli-run lane for the gap report | `{{AUDIT_LANE}}` (first enabled route at install time; edit `AUDIT_LANE` in the script to change it) | nothing yet: wire a notifier and update this line |
 
 Paths in the service and the script were rendered for this install: `{{INSTALL_DIR}}`. If you move the folder, re-run the installer or edit both files.
 
 ## Install a job
 
+Before copying the unit, run `command -v node` and `command -v <selected-cli>` in the account that will run the timer. The service sets `PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`; add the absolute parent directories of your actual Node and vendor CLI executables to its `Environment="PATH=..."` line when needed. The script resolves `node` and vendor commands through that PATH. systemd does not expand `$PATH`, `$HOME` or `~` in this setting, so write complete directories and retain the system entries. Shell profile files and interactive version-manager initialization are not loaded.
+
 ```bash
 mkdir -p ~/.config/systemd/user
 cp weekly-audit.service weekly-audit.timer ~/.config/systemd/user/
@@ -19,7 +21,27 @@ systemctl --user list-timers        # it should be listed with a next-run time
 loginctl enable-linger "$USER"      # so user timers run without a login session
 ```
 
-The service reads `GATEWAY_MASTER_KEY` from an `EnvironmentFile` that lives outside this folder (mode 600). Point the `EnvironmentFile=` line at yours before installing. The key must be a single token matching `^[A-Za-z0-9._-]+$`; the script refuses anything else.
+The service reads only `GATEWAY_MASTER_KEY` from `~/.config/ai-orchestrator/weekly-audit.env`, outside this folder with mode 600. Provision that audit-only file from your secrets manager and point `EnvironmentFile=` at it before installing. Keep the gateway's provider-key environment separate. Existing installs must replace or edit their copied service, then run `systemctl --user daemon-reload`; updating the source template alone does not update the installed unit. The key must be a single token matching `^[A-Za-z0-9._-]+$`; any embedded or trailing newline is refused.
+
+Sign the selected vendor CLI in under the same user before enabling the timer. The job preserves `HOME`, `PATH`, stored sign-in state and unrelated authentication variables, but removes `GATEWAY_MASTER_KEY`, `LITELLM_MASTER_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, and `OPENROUTER_API_KEY` from all child environments. An API-only lane dependent on a removed variable needs vendor-supported stored authentication, such as `hermes auth add <provider>`, before scheduling it. Those provider keys belong in the gateway launch environment.
+
+## Invocation, dependencies, reads and writes
+
+The Monday timer starts the user service, which runs Bash on `vm/jobs/weekly-audit.sh`. The script queries the local gateway using curl, collects user timers and installed CLI versions, assembles a brief, and invokes `node bin/cli-run.mjs` with the selected audit lane. Dependencies are Bash, Node, curl, jq, pgrep, standard shell utilities, the systemd user session, and the selected signed-in CLI. The gateway probe may fail without preventing the report: that section becomes `UNVERIFIED`.
+
+The script reads `protocols/gap-analysis.md`, `DELEGATION_MATRIX.md` (falling back to `ORCHESTRATOR.md`), and collected live state. It writes `reports/live-state-<stamp>.md`, the `live-state.md` symlink, `audit-brief-<stamp>.md`, and a dated report or retained failed output. Credential headers travel only through a pipe into curl's stdin. No gateway credential temp file is created.
+
+## The closed loop
+
+The timer schedules the job; the script records unknown probes in its brief; the worker returns a report; a clean, non-empty result replaces the dated report. The journal records its exit code and report path. **Watched by: nothing.** The operator must inspect the journal and report after a failed service or add a notifier, then update the table above. Automatic notification and remediation are not configured.
+
+## Failure modes
+
+- **Invalid key:** exit 2 before collection; correct the audit-only environment through the secrets manager.
+- **Missing environment file:** systemd cannot start the service; provision the file and check its path and permissions.
+- **Failed probe:** the live-state section says `UNVERIFIED`; check the named dependency and retry.
+- **Missing lane or sign-in:** cli-run returns its failure code, retaining failed output and preserving the last good report. Configure that user's vendor sign-in and PATH.
+- **Timeout:** the watchdog stops probe descendants, and the service's whole-job deadline kills its cgroup. A killed run can leave a non-secret report temp file; a later run sweeps report temps older than a day.
 
 ## Verify a job ran
 
@@ -29,11 +51,18 @@ journalctl --user -u weekly-audit.service -n 50
 ls -la {{INSTALL_DIR}}/reports/
 ```
 
+For a manual check, start `systemctl --user start weekly-audit.service`, then run the checks above. Confirm a new dated report contains the expected gap analysis and read any `UNVERIFIED` sections before treating the run as healthy. Verify the service uses the audit-only environment by inspecting its `EnvironmentFile=` path, never by printing environment values. Test coverage in the package's `test/security-vm.test.js` uses synthetic runtime credentials and stub CLIs to check stdin delivery, child environment isolation, invalid keys, and report preservation; it calls no vendor service.
+
 ## What the job guarantees
 
 - **Bounded:** every probe (gateway, `systemctl`, each CLI `--version`) runs under a 10 s watchdog; the model call under 600 s; the unit under `TimeoutStartSec=900`, which kills the whole cgroup.
 - **Previous report preserved:** output goes to a temp file and is renamed over `audit-<date>.md` only on a clean, non-empty run. A failed run leaves `failed-audit-<stamp>-rc<N>.md` beside it and the last good report untouched.
 - **Boundary:** the lane runs with the strongest restriction it offers ({{AUDIT_LANE_BOUNDARY_NOTE}}). The brief's denied-actions list is an instruction, not an enforcement, for lanes without a sandbox flag.
 - **Honest unknowns:** a probe that times out writes an `UNVERIFIED` line, which the brief tells the lane to treat as unknown, never clean.
+- **Credential separation:** the gateway bearer is never written to a temp file or passed on argv, and gateway/provider keys are absent from version probes and the report worker's environment. Stored vendor sign-ins remain available.
 
 A timer that has never been seen to fire is not known to work. Run `systemctl --user start weekly-audit.service` once by hand and read the journal before trusting the schedule.
+
+## Source of truth
+
+The installed `vm/jobs/weekly-audit.sh`, `weekly-audit.service`, and `weekly-audit.timer` define behavior; the copied unit in `~/.config/systemd/user/` is what systemd runs. This README describes that job end to end. Live scheduling and vendor authentication remain UNVERIFIED until the manual run succeeds on your VM.

package/templates/advanced/vm/jobs/weekly-audit.service

@@ -5,8 +5,13 @@ After=network-online.target
 [Service]
 Type=oneshot
 WorkingDirectory={{INSTALL_DIR_SYSTEMD}}
-# Names come from a file OUTSIDE this repo, mode 600. Edit the path.
-EnvironmentFile=%h/.config/ai-orchestrator/gateway.env
+# Add absolute Node and vendor CLI directories if they live outside these defaults.
+# systemd does not expand shell variables in Environment=.
+Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+# Audit-only file OUTSIDE this repo, mode 600: GATEWAY_MASTER_KEY only.
+# Provider credentials stay in the separate gateway/Compose environment.
+# Vendor CLIs use this user's stored sign-in state. Edit the path if needed.
+EnvironmentFile=%h/.config/ai-orchestrator/weekly-audit.env
 ExecStart=/bin/bash "{{INSTALL_DIR_SYSTEMD}}/vm/jobs/weekly-audit.sh"
 # Whole-job deadline: collection probes (6 x 10 s) + the 600 s model call + cleanup.
 # On expiry systemd kills the whole cgroup, so nothing the job spawned survives.

package/templates/advanced/vm/jobs/weekly-audit.sh

@@ -14,6 +14,20 @@ AUDIT_LANE="{{AUDIT_LANE}}"
 AUDIT_LANE_FLAGS="{{AUDIT_LANE_FLAGS}}"
 PROBE_SECS="${PROBE_SECS:-10}"      # per collection probe
 RUNNER_SECS="${RUNNER_SECS:-600}"   # the model call; TimeoutStartSec in the unit covers the whole job
+# Keep the probe credential in this shell only. Gateway provider keys belong to
+# Compose, not to collection tools or the scheduled vendor CLI. Stored vendor
+# sign-ins, HOME, PATH, and unrelated authentication variables remain available.
+KEY="${GATEWAY_MASTER_KEY:-}"
+export -n KEY
+unset GATEWAY_MASTER_KEY LITELLM_MASTER_KEY ANTHROPIC_API_KEY OPENAI_API_KEY GEMINI_API_KEY XAI_API_KEY OPENROUTER_API_KEY
+
+# A shell pattern checks the whole value, including embedded/trailing newlines.
+# Line-oriented grep accepts a valid line even when another line is malformed.
+case "$KEY" in
+  *[!A-Za-z0-9._-]*)
+    echo "weekly-audit: GATEWAY_MASTER_KEY must match ^[A-Za-z0-9._-]+$ (generate it with: openssl rand -hex 32)" >&2
+    exit 2 ;;
+esac
 {{AUDIT_LANE_GUARD}}
 cd "$INSTALL_DIR" || { echo "weekly-audit: $INSTALL_DIR missing" >&2; exit 2; }
 mkdir -p reports
@@ -47,7 +61,9 @@ killtree() {
 bounded() {
   local secs="$1"; shift
   local fired; fired="$(mktemp "${TMPDIR:-/tmp}/wa-fired.XXXXXX" 2>/dev/null)" && rm -f "$fired"
-  ( "$@" ) & local pid=$!
+  # Bash otherwise replaces stdin with /dev/null for asynchronous commands.
+  # Preserve the caller's pipe explicitly so curl can read its config on stdin.
+  ( "$@" ) <&0 & local pid=$!
   ( sleep "$secs"; [ -n "$fired" ] && : > "$fired"; killtree "$pid" ) >/dev/null 2>&1 & local wd=$!
   wait "$pid" 2>/dev/null; local rc=$?
   killtree "$wd" >/dev/null 2>&1; wait "$wd" 2>/dev/null
@@ -55,29 +71,19 @@ bounded() {
   return $rc
 }
 
-# The gateway key must be a single token: it is interpolated into curl's config
-# grammar, and a quote or newline in it would become a second directive.
-KEY="${GATEWAY_MASTER_KEY:-}"
-if [ -n "$KEY" ] && ! printf '%s' "$KEY" | grep -Eq '^[A-Za-z0-9._-]+$'; then
-  echo "weekly-audit: GATEWAY_MASTER_KEY must match ^[A-Za-z0-9._-]+$ (generate it with: openssl rand -hex 32)" >&2
-  exit 2
-fi
-
 DATE="$(date -u +%F)"
 STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
 {
   echo "# live state $DATE"; echo
   echo "## gateway lanes"
   if [ -n "$KEY" ]; then
-    # The key never enters argv: curl reads the header from a 0600 config file that
-    # exists only for this probe. curl's own timeouts AND the watchdog bound it.
-    CFG="$(umask 077 && mktemp "${TMPDIR:-/tmp}/audit-curl-XXXXXX")"
-    printf 'header = "Authorization: Bearer %s"\n' "$KEY" > "$CFG"
-    if ! bounded "$PROBE_SECS" curl -s --connect-timeout 5 --max-time "$PROBE_SECS" --max-filesize 1048576 --config "$CFG" http://127.0.0.1:4000/v1/models \
+    # No secret file or argv value: the builtin printf feeds curl through a pipe.
+    # curl's own timeouts AND the watchdog bound it, including a hung reader.
+    if ! printf 'header = "Authorization: Bearer %s"\n' "$KEY" \
+      | bounded "$PROBE_SECS" curl -s --connect-timeout 5 --max-time "$PROBE_SECS" --max-filesize 1048576 --config - http://127.0.0.1:4000/v1/models \
       | jq -r '.data[].id' 2>/dev/null; then
       echo "UNVERIFIED: gateway unreachable or timed out within ${PROBE_SECS}s"
     fi
-    rm -f "$CFG"
   else
     echo "UNVERIFIED: GATEWAY_MASTER_KEY not set; gateway not queried"
   fi
@@ -91,13 +97,14 @@ STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
     fi
   done
 } > "reports/live-state-$STAMP.md"
+unset KEY
 ln -sfn "live-state-$STAMP.md" reports/live-state.md
 
-# The brief the lane actually reads: the protocol, the intended configuration,
+# The brief the worker actually reads: the protocol, the intended configuration,
 # and the live state it is meant to diff against.
 BRIEF="reports/audit-brief-$STAMP.md"
 {
-  echo "## Task bundle"
+  echo "## Task brief"
   echo "**Purpose.** Weekly gap analysis: compare the live state below with the intended configuration and name what is missing, dead, or drifted."
   echo "**Task class.** read_only"
   echo "**Denied actions.** Do not run commands, do not modify files, do not call any network service. Enforcement: {{AUDIT_LANE_BOUNDARY_NOTE}}."

package/templates/advanced/vm/setup-vm.sh

@@ -8,6 +8,53 @@ set -euo pipefail
 say() { printf '\n[setup-vm] %s\n' "$*"; }
 have() { command -v "$1" >/dev/null 2>&1; }
 
+# Run this phase explicitly after the dependency setup, sign-ins and secret injection.
+# The package installer only writes this script; it never invokes either phase.
+if [ "${1:-}" = "--start-services" ]; then
+  LOCAL_MODEL={{VM_LOCAL_MODEL_SH}}
+  KEY="${GATEWAY_MASTER_KEY:-}"
+  if [[ ! "$KEY" =~ ^[A-Za-z0-9._-]+$ ]]; then
+    echo 'setup-vm: GATEWAY_MASTER_KEY must match ^[A-Za-z0-9._-]+$' >&2
+    exit 2
+  fi
+  for cmd in docker curl jq; do
+    have "$cmd" || { echo "setup-vm: install $cmd before --start-services" >&2; exit 1; }
+  done
+  cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
+  docker compose up -d
+  if [ -n "$LOCAL_MODEL" ]; then
+    ready=0
+    for attempt in {1..12}; do
+      if docker compose exec -T ollama ollama list >/dev/null 2>&1; then ready=1; break; fi
+      sleep 5
+    done
+    [ "$ready" -eq 1 ] || { echo 'setup-vm: Ollama service did not become ready' >&2; exit 1; }
+    docker compose exec -T ollama ollama pull "$LOCAL_MODEL"
+    ready=0
+    for attempt in {1..12}; do
+      # The key goes to curl on stdin, never argv, a file or printed output.
+      # A model list alone proves only that an alias is configured, not that it can answer.
+      if printf 'header = "Authorization: Bearer %s"\n' "$KEY" | \
+        curl --silent --fail --connect-timeout 5 --max-time 60 --config - \
+          --header 'Content-Type: application/json' \
+          --data '{"model":"local-small","messages":[{"role":"user","content":"Say ready."}],"max_tokens":16,"stream":false}' \
+          http://127.0.0.1:4000/v1/chat/completions | \
+        jq -e '.choices[0].message.content | type == "string" and length > 0' >/dev/null 2>&1; then
+        ready=1; break
+      fi
+      sleep 5
+    done
+    [ "$ready" -eq 1 ] || { echo 'setup-vm: local-small inference did not become ready; inspect docker compose logs' >&2; exit 1; }
+    say 'local-small inference verified'
+  fi
+  say 'services started; see jobs/README.md for the scheduled job'
+  exit 0
+fi
+if [ "$#" -ne 0 ]; then
+  echo 'usage: bash setup-vm.sh [--start-services]' >&2
+  exit 2
+fi
+
 say "system packages"
 sudo apt-get update -y
 sudo apt-get install -y curl git tmux jq ca-certificates gnupg build-essential \
@@ -41,6 +88,6 @@ for pkg in {{NPM_PACKAGES}}; do
 done
 
 say "vendor shell installers (read, then run yourself):"
-{{SCRIPT_INSTALLERS}}
+{{VM_SCRIPT_INSTALLERS}}
 
-say "next: sign in to each CLI inside tmux (device-code flows), export the names in ENVIRONMENT.md, then: docker compose up -d"
+say "next: sign in to each CLI inside tmux (device-code flows), inject the names in ENVIRONMENT.md, then: bash setup-vm.sh --start-services"

package/templates/agents/README.md

@@ -1,13 +1,13 @@
 # templates/agents/
 
-Loading surfaces for the primary agent. The installer writes exactly one of these, based on `--primary`:
+Loading surfaces for the main agent. The installer writes exactly one of these, based on `--primary`:
 
 | Primary | Written | Why |
 |---|---|---|
 | `claude-code` | `.claude/agents/*.md` + `CLAUDE.snippet.md` | Claude Code loads project-level subagents from that folder |
 | `agy` | `.agents/agents/*.md` + `GEMINI.snippet.md` | Antigravity custom agents live there |
 | `codex`, `qwen` | `AGENTS.snippet.md` / `QWEN.snippet.md` | those CLIs read a rules file but have no subagent folder |
-| `grok`, `hermes` | nothing agent-specific | rules travel with the prompt or the task bundle |
+| `grok`, `hermes` | nothing agent-specific | rules travel with the prompt or the task brief |
 | a chat app | `PASTE-INTO-YOUR-AGENT.md` | no files to load; paste into custom instructions |
 
 `snippets/` are rendered with the chosen agent's name and rules file. Nothing here is appended to a file the user already has. `snippets/route-gate.mjs`, `snippets/subagent-context.mjs`, `snippets/route-metrics.mjs`, and `snippets/settings.hooks.snippet.json` are claude-code only: three hooks and the settings block that wires them, installed to `.claude/hooks/` and next to `CLAUDE.snippet.md`.

package/templates/agents/agy/README.md

@@ -1,5 +1,22 @@
-# .agents/agents/
+# Antigravity project agents
 
-Antigravity CLI custom agents, one per tier plus three checks (`finding-verifier`, `done-verifier`, `reader`), in the `.agents/agents/<name>.md` format (YAML frontmatter + system prompt). `model` is a tier (`flash`, `pro`) or `inherit`. `subagent: true` lets a coordinator call them through `invoke_subagent`, which takes an array and launches concurrently; `mainAgent: true` lets you launch them directly with `agy --agent <name>`.
+When using Antigravity custom agents, load these definitions from `.agents/agents/<name>.md`. A coordinator can call them through `invoke_subagent`; `mainAgent: true` also supports `agy --agent <name>`.
 
-`commandExecutionPolicy` is `auto` for `builder` (it has to run builds and tests; deletes and other destructive commands still ask before running) and `off` for the read-only agents: `code-reviewer`, `finding-verifier`, `live-researcher`, `done-verifier`, `reader`. `model` is a tier: `pro` for deep-planner, `flash` for the rest. `done-verifier` and `reader` never write and, with `commandExecutionPolicy: off`, cannot execute any command at all here, mutating or not: unlike its claude-code counterpart, which does carry an unrestricted `Bash` and stays read-only by its prompt rather than by the tool grant, agy's `done-verifier` is mechanically blocked from shelling out and probes artifacts through whatever read or fetch capability it has instead. Neither is `bulk-worker`, which classifies, tags and transforms items and does write.
+The definitions omit the optional model field and inherit your configuration. To pin an available alias, add `model:` to a definition: Antigravity exposes `pro` for planning and `flash` for working and cheap tiers. Check your access, the live roster and tool reach before assigning a build.
+
+| Agent | Tier | Effort guidance |
+|---|---|---|
+| deep-planner | planning model | xhigh where supported |
+| builder | working model | high |
+| code-reviewer | working model | high |
+| finding-verifier | working model | high |
+| live-researcher | working model | medium |
+| bulk-worker | cheap model | low |
+| done-verifier | cheap model | low |
+| reader | cheap model | low |
+
+`builder` has `commandExecutionPolicy: auto` so standard builds and checks can run, while destructive operations remain subject to the vendor's permission policy. Review and reading agents use `commandExecutionPolicy: off`.
+
+`code-reviewer`, `finding-verifier`, `done-verifier` and `reader` use read-only tools with command execution disabled. Their Claude Code counterparts carrying Bash have a prompt-enforced read-only boundary instead. When an Antigravity agent needs a shell probe, hand the exact probe to an authorized worker and report the unverified check until its evidence returns.
+
+When optional companion software is absent, use available read, fetch and local-runtime capabilities through the authorized owner. `bulk-worker` owns classification and transformation; `reader` returns source facts and digests.

package/templates/agents/agy/builder.md

@@ -1,17 +1,21 @@
 ---
 name: builder
-description: Well-specified execution of a bounded sub-part of a build.
-model: flash
+description: Implements the section assigned by the task brief; writes code, edits files and runs the required checks.
 subagent: true
 mainAgent: true
 commandExecutionPolicy: auto   # standard build/test commands run unattended; destructive commands, like deletes, still ask before running
 ---
 
+Tier: working model. This agent inherits the model your Antigravity configuration selects. Antigravity exposes `pro` and `flash`; the working and cheap tiers both map to `flash` when you choose an explicit alias. To pin one, add a `model:` line here after checking your access.
+
 # builder
 
-Well-specified execution of a bounded sub-part of a build.
+When a task brief assigns implementation, read its context file and acceptance checks first. Confirm the assigned paths, interfaces, capabilities and current runtime access.
 
-Rules:
-- Stay inside the task bundle you were given. Anything not granted is denied.
-- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
-- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.
+- When a plan has an implementation gap within scope, state the assumption and verify it. When the gap changes architecture or authority, return the needed decision.
+- Write the assigned section using the project's conventions and existing dependencies.
+- When the build depends on a changing interface, consult current official docs or installed source and run a check.
+- When the sandbox refuses a write, hand the required patch to an authorized writer and continue independent work.
+- When authorized to split work, give each child the whole scope and its own section. Merge the result and name conflicts.
+- When checks pass, report changed paths, coverage against the brief and evidence. Leave independent audit to the assigned reviewer.
+- Keep context targeted and return concise results with source paths.

package/templates/agents/agy/bulk-worker.md

@@ -1,17 +1,19 @@
 ---
 name: bulk-worker
-description: High-volume mechanical work: classify, tag, extract, reformat, summarize many items.
-model: flash
+description: Classifies, tags, extracts, reformats or summarizes many similar items with a cheap model and bounded scope.
 subagent: true
 mainAgent: true
 commandExecutionPolicy: off
 ---
 
+Tier: cheap model. This agent inherits the model your Antigravity configuration selects. Antigravity exposes `pro` and `flash`; the working and cheap tiers both map to `flash` when you choose an explicit alias. To pin one, add a `model:` line here after checking your access.
+
 # bulk-worker
 
-High-volume mechanical work: classify, tag, extract, reformat, summarize many items.
+When a brief assigns many similar items, use its categories or output schema consistently across the full authorized set.
 
-Rules:
-- Stay inside the task bundle you were given. Anything not granted is denied.
-- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
-- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.
+- Read the context and scope before processing.
+- When the categories are unclear or items stop fitting, report the mismatch and the affected items before continuing dependent work.
+- Return structured output with one row or item per input, using short identifiers instead of repeating full input text.
+- Write only to destinations the brief authorizes.
+- Check input coverage and output shape, then report omissions and unverified items.

package/templates/agents/agy/code-reviewer.md

@@ -1,17 +1,23 @@
 ---
 name: code-reviewer
-description: Read-only code review; findings ranked by severity with a concrete failure scenario each.
-model: flash
+description: Reviews code for concrete security and correctness failures; command execution disabled; read-only tools.
 subagent: true
 mainAgent: true
 commandExecutionPolicy: off
 ---
 
+Tier: working model. This agent inherits the model your Antigravity configuration selects. Antigravity exposes `pro` and `flash`; the working and cheap tiers both map to `flash` when you choose an explicit alias. To pin one, add a `model:` line here after checking your access.
+
 # code-reviewer
 
-Read-only code review; findings ranked by severity with a concrete failure scenario each.
+When assigned a review, read the task brief, context file, final diff and acceptance checks. Review the merged artifact against scope in the single audit step.
+
+Command execution is disabled by `commandExecutionPolicy: off`. Use available read and fetch tools. When a check needs a command, return the needed authorized probe as UNVERIFIABLE or INCONCLUSIVE rather than running it.
 
-Rules:
-- Stay inside the task bundle you were given. Anything not granted is denied.
-- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
-- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.
+- Trace each suspected failure to concrete input, state, caller and affected behavior.
+- Check guards, tests and framework behavior that could disprove the claim.
+- Rank reproducible security and correctness findings by severity; cite the file and line, trigger, consequence and proposed fix.
+- When a scanner flags a line, inspect the actual object before repeating the finding.
+- When reviewing code you authored, hand the review to an independent author and model family.
+- When the code is clean, return CLEAN with the checked scope and limits.
+- Suggest fixes and return evidence; fixes are assigned separately.

package/templates/agents/agy/deep-planner.md

@@ -1,17 +1,20 @@
 ---
 name: deep-planner
-description: Ambiguous or high-stakes thinking: architecture, strategy, hard debugging. Returns a plan; never edits code.
-model: pro
+description: Resolves architecture, strategy and unknown causes from a prepared context file; returns an executable plan.
 subagent: true
 mainAgent: true
 commandExecutionPolicy: off
 ---
 
+Tier: planning model. This agent inherits the model your Antigravity configuration selects. Antigravity exposes `pro` and `flash`; the working and cheap tiers both map to `flash` when you choose an explicit alias. To pin one, add a `model:` line here after checking your access.
+
 # deep-planner
 
-Ambiguous or high-stakes thinking: architecture, strategy, hard debugging. Returns a plan; never edits code.
+When the task needs architecture, strategy or an unknown cause resolved, read the prepared context file and acceptance checks, then test the key assumptions.
 
-Rules:
-- Stay inside the task bundle you were given. Anything not granted is denied.
-- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
-- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.
+- Compare the mechanism-distinct options that fit the request and recommend one with concrete tradeoffs.
+- Use the prepared map for retrieval evidence; when a claim is uncertain, request a targeted probe.
+- At Assign, compare available lanes by reasoning, tool reach, context window and capacity, then record the choice and reason.
+- Return a plan with file boundaries, interfaces, risky assumptions, verification and order of work.
+- Keep this session read-only. Your result is a plan or analysis; code changes belong to the assigned builder.
+- Cite the evidence supporting decisions and keep the report sized to the executor's needs.