Internal infrastructure · field manual v3 · 2026-07-11

Judge the harness without reading the code.

This manual exists so one human can decide what is working, what is worth paying for, and what must change - without reading code and without running the fleet.

Built code or a working artifact exists Open incomplete, branch-only, off-path, or integration-dark Concept a ruled design or proposal without the system yet
01 — The two jobs, and the honest frame

The two jobs, and the honest frame

The harness has two jobs. Keep the fleet safe: money, credentials, outbound traffic, and irreversible actions should not be free-for-all agent choice. Make the work legible: when many models move in parallel, the operator should see decisions, not transcripts. The through-line is simple: spend agent effort freely; spend the operator's attention carefully.

Honest frame before any capability: much of this is built and unit-tested, but the whole is not a system yet. Parts live on separate lines; the safety door is not the real door; nothing is production until an explicit promote-and-lock. Consolidation is not "merge the leftovers." Consolidation is where the first real system is built.

02 — StarGate

StarGate - governed egress, budget, and credentials

Open
The judgment you can make hereDo we still treat "safety built" as "safety live," or do we refuse that fiction until cutover?

What it does

StarGate is meant to be the single doorway for anything that leaves the machine: model calls, launches, budgets, and credentials. In the design, agents do not hold provider keys; they ask a separate always-on service, which reserves spend, scrubs secrets, records attempts, and returns a trusted outcome - not the agent's self-report of success.

Why it matters

At ~20 parallel projects, direct keys-in-environment is how one confused agent burns a subscription, leaks a secret, or double-charges a retry. A real door turns "hope every agent obeys doctrine" into "the only path that can spend." That is money protection and blast-radius control for the whole constellation.

The decision + tradeoff

It is a separate service, not a library agents import. A library can be skipped; a service can become the only path with keys. Tradeoff: the fleet now depends on an always-on process, a chokepoint, and a cutover plan. Fail-closed safety implies a possible single point that can halt work when the door is down or misconfigured.

The open judgment calls

  1. Is fail-closed worth making the whole fleet halt when the door is down? Stakes: safety vs. operator velocity under outage. Only you can price that.
  2. When do we cut keys out of agent environments? Guardrails exist; agents still egress with env keys today. Product judgment: the safety is not live yet. Unit-green is not integration-green. Cutover before promote-and-lock risks locking the wrong door.
  3. How deep is "jail" enough? The hard OS/network jail framing was re-scoped: the real enforcement is keys-out-of-agent-env plus worktree isolation, with canaries that prove holes rather than a full attacker-escape story. Is that depth enough for your threat model (confused agent, not nation-state)?
  4. Do your own loopback dev services that carry live keys sit inside the fence or outside it? Stakes: whether "dev convenience" becomes a permanent bypass class.
03 — The broker

The broker - queue, episodes, and completion truth

Open
The judgment you can make hereIs "work finished" a machine fact, or still a story agents tell?

What it does

The broker is the fleet's inbox and outbox for work packets. It enqueues, chains, and assembles episodes (coherent terminal packages of what ran), and maintains a completion mirror that is supposed to record machine-derived labels - not prose "done."

Why it matters

Without a broker, twenty projects become twenty chat tabs and no shared memory of what terminated, what is still live, and what claimed success without effect. That is how hollow wins and duplicate launches hide until money or trust is gone.

The decision + tradeoff

Trust completion from observed/trusted emitters (service codes, exits, independent gates), not agent text. Tradeoff: agents can look "finished" in chat while the ledger stays incomplete until wiring is total. Episode assembly is only partially on the live path; the status table is still hand-updated in places - so the control plane's own map can lag reality.

The open judgment calls

  1. How much operator time is acceptable while the progress table is hand-updated rather than a generated view over real episodes? Until every lane's terminal path assembles an episode, "COMPLETE" can mean "tests passed on a branch," not "the fleet knows."
  2. Hollow-success accounting already proved trusted-only ledgers can accept empty wins. Do you treat that as a blocking product defect for any standing adoption, or as a known R-class risk until effect-confirmation is universal?
04 — The card loop

The card loop - operator decisions in eight seconds, not eight logs

Built
The judgment you can make hereDoes this surface make you faster and safer at deciding, or does it only prettify noise?

What it does

When a packet arrives, the system joins product context, plans a face-budgeted card shape, generates the card, lints it for product-plane failures, and falls back if generation fails. The cockpit is the decision surface: verdict, collapsed evidence, actions - not a transcript dump.

Why it matters

The scarce resource is not tokens; it is your attention. Cards are the bet that multi-agent work can be operator-decidable at glance: approve, hold, send back, reverse. That is the product interface for one person supervising many streams.

The decision + tradeoff

Planner chooses shapes; generator realizes them - data affordances drive layout, not free-form model layout. Tradeoff: more machinery and more failure modes before a card is trustworthy. Soak scores can look excellent while contract gaps remain (soak ≠ contract). Adversarial families (stale doctrine, poisoned transcript, secret-bearing errors, empty context) must fail safe before standing adoption.

The open judgment calls

  1. Is a high soak rate enough to trust the loop, or is full contract + adversarial re-soak the bar for daily use?
  2. Which actions may auto-stage vs. require hold-to-confirm (dispatch, publish, reversal, standing-rule change)? That is product law, not a model preference.
  3. The work-graph (session map at goal/spec altitude) is still unbuilt. Do cards alone carry you to ~20 projects, or is the map a prerequisite for multi-altitude control?
05 — Wiki + judges

Wiki + judges - doctrine that learns without silent poison

Built
The judgment you can make hereShould the fleet auto-write its own memory, and under what evidence rules?

What it does

The wiki is a gated knowledge store for failures, handoffs, and doctrine. Writes are schema-checked; hydration brings pages into work with skip-tracking and handoff integrity. A two-judge, cross-family pipeline can auto-publish on agree (shadow-default today); demotion and retraction exist so wrong pages get marked and consumers warned - never silent delete.

Why it matters

At fleet scale, the same failure re-taught from scratch is pure burn. Shared doctrine multiplies leverage - but a wrong page multiplied is also leverage for harm. Judges and demotion are the business case for learning without institutionalizing error.

The decision + tradeoff

Cross-family agreement for publish; never same-family sole authority; never-delete demotion net. Tradeoff: slower knowledge growth, more cards when judges split, and shadow mode means auto-publish is not yet the live teacher of the fleet.

The open judgment calls

  1. When does shadow auto-publish go live? Early live publish compounds doctrine; late live publish leaves agents re-deriving expensive lessons.
  2. Bulk historical failure migration is deferred. Is deferred triage acceptable, or does an un-migrated past become a silent training gap?
  3. Doctrine mirroring across repos is still open. Drift between "what we ruled" and "what the wiki says" is a trust-boundary risk - who owns the single taxonomy?
06 — Rings, replay, scoring

Rings, replay, scoring - prove the harness before it governs you

Built
The judgment you can make hereAre we ready to let the harness gate activation, or only ready to measure itself?

What it does

FleetOS was built in rings: scaffold and routing; trust-boundary hooks (lane profiles, terminal grammar, scope guard); claims and indexing; wiki substrate; then canaries, historical task extraction, replay harness, calibration, requirement ledgers, contract differencing, and shadow scoring that compares candidate behavior to incumbents without promoting on vibes. Activation gates that would hard-gate live work stay dark until density justifies them.

Why it matters

Without replay and shadow scoring, "improve the harness" is opinion. With them, you can refuse promotions that only look better on one cherry-picked run, and you can catch fixture drift and regressions before they become doctrine. That protects the business case of the harness itself: money spent on build should buy measured reliability.

The decision + tradeoff

Build measurement and canaries before activation gates. Tradeoff: a long period where sophisticated machinery exists but does not yet govern day-to-day agent freedom. Ring progress marked complete on a fleet main can coexist with product inventory that still says "unmerged parts" - different definitions of "done" for components vs. integrated product.

The open judgment calls

  1. When do activation gates leave dark mode? Too early freezes a partial system; too late leaves discipline optional.
  2. How do we reconcile "component complete on fleet main" with "no consolidated product whole"? One story must own the word "done."
  3. Settled for now on ring ordering itself - measure before hard activation - unless you want to reverse and force live gates earlier for safety theater.
07 — The constellation

The constellation - multi-model fleet as different problem-finders

Built
The judgment you can make hereAre we buying diversity of judgment, or just paying for more tokens?

What it does

Several frontier systems run in parallel roles: a control plane for coherence and integration; a bulk implementer/mechanic; a divergent structurer; a high-precision bulk coder; cheap bulk extractors; an adversarial design judge for expensive-to-undo calls; a Google-family UX lens; and multiple headless Claude accounts as capacity. Fusion rule: divergent finders never sole-review - parallel authorities adjudicate.

Why it matters

One model's blind spot is another's specialty. At 20 projects, that diversity is how you catch consent/state bugs, UX honesty issues, and exploit classes without making one subscription the single brain. Dispatch wrappers, worktree isolation, and stall classification (OK / stalled / blocked) exist so launches are repeatable - but stall truth is still often human-session, not fully machine-closed.

The decision + tradeoff

Spend across providers for prism diversity; fuse rather than average. Tradeoff: operational complexity, subscription sprawl, and role tables that can rot (e.g. test-writer role still named after a path that is dead or unreliable). Launchers are doctrine-hardened, not yet one enforced control plane through StarGate.

The open judgment calls

  1. Is the fusion tax (always multi-judge expensive targets) worth it at every milestone, or only at promote-class decisions?
  2. Who is the real test-writer now that the legacy path is dead and the replacement still fails silently sometimes? Role aspirational ≠ role staffed.
  3. How much launch diversity stays outside StarGate until cutover? Every off-path launcher is a future scrub/budget hole.
08 — Homer

Homer - the completion gate that blocks "done" theater

Built
The judgment you can make hereKeep paying for a third-party completion conscience, or replace it once our own ledger is honest enough?

What it does

Homer sits on concrete work claims and blocks premature "done." It wants receipts: evidence that builds, tests, or effects actually happened. It is configured to fail open if it is down (so it cannot strand the fleet), and keep-in-path conditions include secret scrubbing on outbound checks and a local done-ledger mirror.

Why it matters

Agents love terminal confidence. Premature done is how bugs ship, how gates get skipped, and how you lose hours re-finding work that was declared finished. Relative to subscription spend, Homer's cost was ruled non-decisive; its product value is attention and honesty.

The decision + tradeoff

External gate with fail-open + local mirror, not "trust the agent's last sentence." Tradeoff: another dependency and another receipt ritual; fail-open means a outage removes the brake.

The open judgment calls

  1. If the owned done-ledger becomes strong, do we keep Homer forever as independent conscience, or demote it? Stakes: single-vendor completion truth vs. redundant checks.
  2. Settled for now: economics alone are not a kill criterion relative to subscription burn.
09 — External findings

External findings - scanners feed; they do not rule

Open
The judgment you can make hereAre vendors advisors or authorities in our safety story?

What it does

External review tools are absorbed as finding feeds. A normalizer fingerprints, maps severity, dedups, and seeds locally run checks. Unmappable items quarantine (never drop); unreproduced items decay to digest; autofix is only a new governed dispatch, never self-executing authority.

Why it matters

At volume, scanners create noise that can either drown the operator or become fake certainty. Treating vendor text as premise is how you ship theater. Seeding local proof is how external signal becomes leverage without capture.

The decision + tradeoff

Vendor assertion never premise; local reproduction decides. Tradeoff: slower close on findings, more quarantine backlog, and a fusion board (finder / authority / local proof + receipt strip) still designed rather than built.

The open judgment calls

  1. What severity auto-blocks promote vs. only opens a card?
  2. When is the fusion board required before any main-path promote?
10 — Dual StarGate

Dual StarGate - two homes, one intended door

Open
The judgment you can make hereWhich tree is truth, and when does the other die?

What it does

There is an extracted StarGate home and an in-tree copy used in daily product work, with MCP routing that has already shown live handshake failure. Coverage proofs and "every call site scrubbed" claims do not hold while both exist and keys remain in agent environments.

Why it matters

Dual doors mean dual rot. The dangerous product story is "we have StarGate" while agents still spend around it. Silent rot is the business risk: green unit gates affirm provenance, not live effect.

The decision + tradeoff

Extraction aimed at a clean product path; daily reality kept an in-tree twin for velocity. Tradeoff: inventory lies easily, integration-dark stays invisible, MCP "built" ≠ MCP usable.

The open judgment calls

  1. Which home is canonical, and what is the kill date for the other?
  2. Is MCP the operator path, CLI, or both - and what is the acceptance test for "usable"?
  3. No standing adoption story should claim a single door until one home + key cutover is true.
11 — Multi-project capacity plane

Multi-project capacity plane - the headline unbuilt gap

Concept
The judgment you can make hereThis is the biggest open product/architecture call for the actual ~20-project goal.

What it does (today: almost nothing as a system)

Cards and work-graphs (even planned) operate at session/fleet-UI altitude. Missing is project as a first-class capacity object: leases and TTLs, cross-project budget/GPU/subscription arbitration, a worktree pool with exclusive claims across projects, a cross-project result bus, and a scheduler that can run voice, UX, bench, and infra work without you manually juggling queues.

Why it matters

Without this plane, "20 parallel projects" is a human job wearing a harness costume. You become the scheduler, the budget court, and the conflict resolver. That caps leverage and reintroduces the exact attention tax the harness was meant to remove. Money and GPU sit ungoverned across projects even if single-dispatch budgets exist someday inside StarGate.

The decision + tradeoff

So far the build optimized per-fleet safety and legibility, not cross-project OS. Tradeoff: deep machinery for one fleet's honesty, shallow machinery for portfolio capacity. Building dashboards next without this plane would polish the wrong altitude.

The open judgment calls

  1. Is multi-project capacity the next first-class program, or do we finish one vertical integrated slice first and accept human scheduling until then? Stakes: time-to-MVP honesty vs. time-to-portfolio leverage.
  2. What is a "project" in the lease model - repo, customer, experiment, subscription budget bucket?
  3. Who wins when two projects contend for the same GPU or the same high-tier model quota - static priority, operator auction, or hard partitions?
  4. Should worktree pools be global (dangerous cross-talk) or partitioned (more idle capacity)?
12 — Promotion model

Promotion model - freeze a product path; keep a dev tree

Concept
The judgment you can make hereWhat does "production-ready harness" mean as an installable fact, not a feeling?

What it does

Nothing here is production until an explicit promote + lock: a versioned immutable bundle (exact commits of both engines, schemas, lane/policy/wiki versions, build artifacts, contract/E2E/adversarial/Homer receipts), installed to a frozen product path with atomic current pointer and one-command rollback. Dev continues in a separate tree that must never be imported or executed by the product path. No key cutover before that.

Why it matters

Without promotion, every day is a moving target; "it worked in a session" is not a release. With promotion, you can canary, roll back, and finally move credentials into the service identity alone. That is the business gate between expensive sandbox and trusted operator infrastructure.

The decision + tradeoff

Release = immutable bundle + atomic pointer, not "merge to main and hope." Tradeoff: ceremony and dual environments; slower cutover; explicit refusal to run product from dirty worktrees.

The open judgment calls

  1. What exact bundle contents and install root do you accept as law?
  2. Who signs the promote, and what minimum suite is non-negotiable?
  3. How long must the prior release stay for rollback?
  4. Settled: no credential cutover before promote+lock - reverse only if you consciously accept keys-around-the-door as temporary production risk (not recommended by the current design).
13 — Dispatch lifecycle contract

Dispatch lifecycle contract - intent is not effect is not acceptance

Concept
The judgment you can make hereWho is allowed to say "success," and at which step?

What it does

The intended seam: FleetOS owns intent, approval, context, semantic acceptance, and presentation. StarGate owns authorization, credentials, budget, attempts, effects, and execution receipts. The ID chain is meant to be: intent -> logical dispatch -> attempt -> effect receipt -> acceptance. StarGate "success" means execution observed, never task accepted. Homer/FleetOS close acceptance. Durable outbox/inbox and reconciliation - not a shared mutable brain, not an alternate launch path.

Why it matters

If both engines invent terminal states, you get double launches, false done, and un-attributable spend. That is the root architectural risk of two rich systems grown in parallel. Fixing it is what makes consolidation a system-build rather than a git ceremony.

The decision + tradeoff

Split brains by authority class; reconcile by events. Tradeoff: more protocol design up front; temporary pain while broker and control plane still overlap in the wild; wrappers that look like dispatch without being the lifecycle.

The open judgment calls

  1. Freeze this contract before branch consolidation, or consolidate first and discover conflicts live? Reviewers argue contract-first; velocity argues merge-first. Stakes: rework cost vs. calendar time.
  2. Is any alternate launch path allowed after promote (emergency break-glass), and who audits it?
  3. Where does stall/limit classification become machine-closed so "dispatch verified" stops meaning "wrapper returned"?
14 — Consolidation

Consolidation - the first real system (not a merge checklist)

Concept
The judgment you can make hereAre we measuring code inventory or product evidence?

What it does

Today: advanced parts, early product evidence. Consolidation must freeze the cross-engine state machine, IDs, APIs/events, and release layout; integrate branches into one line with cross-repo contract tests; prove one vertical slice from operator intent through execution to evidence-backed acceptance and card; add durability anchors and instrumentation; only then full adversarial soak including crash/retry/reconciliation; then release candidate -> promote -> credential canary.

Why it matters

Until then, every "BUILT+VERIFIED" claim is local. Off-path chokepoints rot; dual homes hide holes; hand-updated progress can disagree with inventory. The disaster consolidation prevents is adopting a costume of safety.

The decision + tradeoff

Contract-led integrate, then one full vertical slice, then promote. Tradeoff: deferred multi-project OS and deferred lush work-graph until the action loop is real. Correct: do not let the map precede the working loop.

The open judgment calls

  1. Accept that MVP is "not close" in product terms despite rich components? Honesty here drives spend and expectation.
  2. Order of remaining product waves after contract freeze - vertical slice first vs. multi-project capacity first (see capacity section; they compete for attention).
  3. What single definition of "done" replaces the dual story of fleet component complete vs. product unmerged?
15 — How to use this manual tomorrow

How to use this manual tomorrow

  • Functionality: Prefer "is it on the live path?" over "did tests pass somewhere."
  • Product: Prefer "does this cut my attention tax at 20 projects?" over "is the module impressive?"
  • Business: Prefer "what burn or leak does this prevent when keys are real?" over "unit green."
  • Architecture: Prefer "what did we give up, and is the reverse still possible?" over "what files landed."

The harness is already rich enough to mislead. The operator job is not to learn the tree. The operator job is to decide which doors become real, which maps get built, and which "complete" claims survive contact with a single frozen product path.