Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jason WoltjeandClaude Fable 5
|
18f960d3e1 |
@@ -82,6 +82,7 @@ is re-seeded a genuinely missing core file is a stop-and-report condition — no
|
||||
|
||||
Confirm: required + situational tests passed (primary gate); aligned to `docs/PRD.md`; acceptance
|
||||
criteria mapped to evidence; independent code review passed (if code changed); required docs updated;
|
||||
scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on `main`, terminal-green
|
||||
scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on the integration
|
||||
trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), terminal-green
|
||||
CI, linked issue closed (or `docs/TASKS.md` equivalent). If blocked by access/tooling, return `blocked`
|
||||
with the exact failed wrapper command — do not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.
|
||||
|
||||
@@ -21,11 +21,23 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
|
||||
|
||||
## Hard Gates
|
||||
|
||||
The **integration trunk** is the branch a project designates in its root `AGENTS.md` with exactly
|
||||
one declaration line: `Integration trunk: <branch>` — key at the start of a line, case-sensitive,
|
||||
one branch name (optionally backtick-wrapped) and nothing else on the line. Absent a declaration,
|
||||
the trunk is `main`. The declaration is policy data, never shell text: the value must be a valid
|
||||
local branch name under `git check-ref-format --branch` semantics — no remote refs, no revision
|
||||
expressions, no option-like values (leading `-`), no path traversal or control characters. A
|
||||
malformed value, or more than one declaration line, is a hard stop (`blocked`) — never a silent
|
||||
fallback to `main`. Ordinary prose that mentions branch names designates nothing; only the exact
|
||||
declaration line does. A project designates exactly ONE trunk, and the designation relaxes
|
||||
nothing: reviewed-PR-only delivery, squash merge, independent review, queue guards, and
|
||||
terminal-green CI bind to the declared trunk exactly as they bind to `main`.
|
||||
|
||||
1. Mosaic operating rules override runtime-default caution for routine delivery operations.
|
||||
2. Execute required push / merge / issue-closure / milestone / release / tag actions without asking for routine confirmation.
|
||||
3. Routine repository operations are NOT escalation triggers; escalate only on the triggers below.
|
||||
4. For source-code delivery, completion is forbidden at the PR-open stage.
|
||||
5. Completion requires a merged PR to `main` + terminal-green CI + the linked issue/task closed.
|
||||
5. Completion requires a merged PR to the integration trunk + terminal-green CI + the linked issue/task closed.
|
||||
6. Before any push or merge, run the CI queue guard.
|
||||
7. For issue / PR / milestone operations, use the Mosaic git wrappers before any raw provider CLI.
|
||||
8. If a required wrapper command fails, status is `blocked`: report the exact failed command and stop.
|
||||
@@ -35,7 +47,7 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
|
||||
12. The intake procedure is not conditional on perceived complexity; a "simple" task carries the same requirements as a multi-file feature.
|
||||
13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review merge go-ahead is the coordinator's to give — once the required review gates pass, merge on the coordinator's confirmation; do not wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges.
|
||||
14. Never hardcode secrets; never emit credential values in any output (not even partially, not "to confirm").
|
||||
15. Trunk-based git only: branch from `main`, merge via a reviewed PR (squash), never push directly to `main`.
|
||||
15. Trunk-based git only: branch from the integration trunk, merge via a reviewed PR (squash), never push directly to the trunk.
|
||||
16. If you modify source code, an independent review (author ≠ reviewer) must pass before completion.
|
||||
|
||||
## Integrity (quality gates are never bypassed)
|
||||
|
||||
@@ -12,7 +12,7 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
|
||||
4. Issue tracking is consistent across projects
|
||||
5. Documentation standards and API contracts are enforced from day one
|
||||
6. PRD requirements are established before coding begins
|
||||
7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
|
||||
7. Branching/merging is consistent: branch -> integration trunk (default `main`) via PR with squash-only merges
|
||||
8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
|
||||
|
||||
## Agent Host Prerequisites
|
||||
@@ -206,7 +206,7 @@ Every runtime context file should contain:
|
||||
6. **Issue tracking** — Issue and commit conventions
|
||||
7. **Code review** — Required review process
|
||||
8. **Runtime notes** — Runtime-specific behavior references
|
||||
9. **Branch and merge policy** — Trunk workflow (`branch -> main` via PR, squash-only)
|
||||
9. **Branch and merge policy** — Trunk workflow (branch -> integration trunk via PR, squash-only)
|
||||
10. **Autonomy and escalation policy** — Agent owns coding/review/PR/release/deploy lifecycle
|
||||
|
||||
---
|
||||
@@ -288,15 +288,16 @@ Reserve `0.1.0` for the MVP release milestone.
|
||||
|
||||
---
|
||||
|
||||
## Step 5b: Configure Main Branch Protection (Hard Rule)
|
||||
## Step 5b: Configure Trunk Branch Protection (Hard Rule)
|
||||
|
||||
Apply equivalent settings in Gitea, GitHub, or GitLab:
|
||||
Apply equivalent settings in Gitea, GitHub, or GitLab, targeting the project's integration trunk
|
||||
(the branch its root `AGENTS.md` declares; default `main` — see `CONSTITUTION.md` Hard Gates):
|
||||
|
||||
1. Protect `main` from direct pushes.
|
||||
2. Require pull requests to merge into `main`.
|
||||
1. Protect the integration trunk from direct pushes.
|
||||
2. Require pull requests to merge into the integration trunk.
|
||||
3. Require required CI/status checks to pass before merge.
|
||||
4. Require code review approval before merge.
|
||||
5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
|
||||
5. Allow **squash merge only** for PRs into the integration trunk (disable merge commits and rebase merges for it).
|
||||
|
||||
This enforces one merge strategy across human and agent workflows.
|
||||
|
||||
@@ -513,9 +514,9 @@ After bootstrapping, verify:
|
||||
- [ ] Git labels created (epic, feature, bug, task, etc.)
|
||||
- [ ] Initial pre-MVP milestone created (0.0.1)
|
||||
- [ ] MVP milestone reserved for release (0.1.0)
|
||||
- [ ] `main` is protected from direct pushes
|
||||
- [ ] PRs into `main` are required
|
||||
- [ ] Merge method for `main` is squash-only
|
||||
- [ ] The integration trunk is protected from direct pushes
|
||||
- [ ] PRs into the integration trunk are required
|
||||
- [ ] Merge method for the integration trunk is squash-only
|
||||
- [ ] Quality gates run successfully
|
||||
- [ ] `.env.example` exists (if project uses env vars)
|
||||
- [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
|
||||
|
||||
@@ -4,6 +4,11 @@
|
||||
|
||||
## Overview
|
||||
|
||||
> **Integration trunk:** the YAML examples in this guide use the default integration trunk `main`
|
||||
> in branch conditions and version rules. A project that declares a different trunk in its root
|
||||
> `AGENTS.md` (see `CONSTITUTION.md` Hard Gates) substitutes its declared trunk wherever `main`
|
||||
> appears as the trunk branch.
|
||||
|
||||
This guide covers the canonical CI/CD pattern used across projects. The pipeline runs in Woodpecker CI and follows this flow:
|
||||
|
||||
```
|
||||
@@ -865,7 +870,7 @@ steps:
|
||||
```yaml
|
||||
image: git.example.com/org/service@${IMAGE_DIGEST}
|
||||
```
|
||||
7. **Test on a short-lived non-main branch first** — open a PR and verify quality gates before merging to `main`
|
||||
7. **Test on a short-lived non-trunk branch first** — open a PR and verify quality gates before merging to the integration trunk
|
||||
8. **Verify images appear** in Gitea Packages tab after successful pipeline
|
||||
|
||||
## Terminal-Green Full-Step Contract
|
||||
@@ -906,7 +911,7 @@ For source-code delivery, completion is not allowed at "PR opened" stage.
|
||||
|
||||
Required sequence:
|
||||
|
||||
1. Merge PR to `main` (squash) via Mosaic wrapper.
|
||||
1. Merge PR to the integration trunk (squash) via Mosaic wrapper.
|
||||
2. Monitor CI to terminal status:
|
||||
```bash
|
||||
~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>
|
||||
@@ -1112,5 +1117,5 @@ If a project currently uses Verdaccio (e.g., U-Connect at `npm.uscllc.net`), fol
|
||||
|
||||
### Pipeline runs Docker builds on pull requests
|
||||
|
||||
- Verify `when` clause on Docker build steps restricts to `branch: [main]`
|
||||
- Verify `when` clause on Docker build steps restricts to the integration trunk (`branch: [main]` by default)
|
||||
- Pull requests should only run quality gates, not build/push images
|
||||
|
||||
@@ -10,9 +10,10 @@ If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD upd
|
||||
|
||||
Merge strategy enforcement (HARD RULE):
|
||||
|
||||
- PR target for delivery is `main`.
|
||||
- Direct pushes to `main` are prohibited.
|
||||
- Merge to `main` MUST be squash-only.
|
||||
- The integration trunk is the branch the project's root `AGENTS.md` declares (default: `main`) — see `CONSTITUTION.md` Hard Gates.
|
||||
- PR target for delivery is the integration trunk.
|
||||
- Direct pushes to the integration trunk are prohibited.
|
||||
- Merge to the integration trunk MUST be squash-only.
|
||||
- Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).
|
||||
|
||||
## Review Checklist
|
||||
@@ -114,8 +115,8 @@ Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` whenever code/A
|
||||
# List the issue being addressed
|
||||
~/.config/mosaic/tools/git/issue-list.sh -i {issue-number}
|
||||
|
||||
# View the changes
|
||||
git diff main...HEAD
|
||||
# View the changes (diff against the integration trunk; default: main)
|
||||
git diff {integration_trunk}...HEAD
|
||||
```
|
||||
|
||||
### Providing Feedback
|
||||
@@ -151,4 +152,4 @@ This pattern appears in 3 places. A shared helper would reduce duplication.
|
||||
2. If changes requested, assign back to author
|
||||
3. If approved, note approval in issue comments
|
||||
4. For merges, ensure CI passes first
|
||||
5. Merge PR to `main` with squash strategy only
|
||||
5. Merge PR to the integration trunk with squash strategy only
|
||||
|
||||
@@ -78,7 +78,7 @@ For implementation work, you MUST run this cycle in order:
|
||||
7. `commit` - commit only when the logical unit passes tests and review.
|
||||
8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
|
||||
9. `push` - push immediately after queue guard passes.
|
||||
10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
|
||||
10. `PR integration` - if external git provider is available, create/update PR to the integration trunk (the project's declared trunk, default `main`) and merge with required strategy via Mosaic wrappers.
|
||||
11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines on the exact PR head to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
|
||||
12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/tools/git/pr-ci-wait.sh` for PR-based workflow).
|
||||
13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
|
||||
@@ -199,7 +199,7 @@ Before running this checklist, pause and self-interrogate: did I fulfill the use
|
||||
10. No unresolved blocker hidden.
|
||||
11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
|
||||
12. `docs/TASKS.md` status and issue/internal references are updated to match delivered work.
|
||||
13. If source code changed and external provider is available: PR merged to `main` (squash), with merge evidence recorded.
|
||||
13. If source code changed and external provider is available: PR merged to the integration trunk (squash), with merge evidence recorded.
|
||||
14. CI/pipeline status is terminal green for the merged PR/head commit.
|
||||
15. Linked external issue is closed (or internal task ref is closed when no provider exists).
|
||||
16. If any of items 13-15 fail due access/tooling, report `blocked` with exact failed wrapper command and do not claim completion.
|
||||
|
||||
@@ -253,7 +253,7 @@ status → mission → run → repeat
|
||||
|
||||
- [ ] All milestone tasks in TASKS.md are `done`
|
||||
- [ ] CI/pipeline green
|
||||
- [ ] PR merged to `main`
|
||||
- [ ] PR merged to the integration trunk
|
||||
- [ ] Issues closed
|
||||
- [ ] Update manifest: milestone status → completed
|
||||
- [ ] Update scratchpad: session log entry
|
||||
|
||||
@@ -15,7 +15,7 @@ mosaic claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md th
|
||||
- You MUST keep the TASKS.md file updated with agent and tasks statuses.
|
||||
- You MUST keep `docs/` root clean. Reports and working artifacts MUST be stored in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
||||
- You MUST enforce plan/token usage budgets when provided, and adapt orchestration strategy to remain within limits.
|
||||
- You MUST enforce trunk workflow: workers branch from `main`, PR target is `main`, direct push to `main` is forbidden, and PR merges to `main` are squash-only.
|
||||
- You MUST enforce trunk workflow: workers branch from the integration trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), PR target is the integration trunk, direct push to the trunk is forbidden, and PR merges to the trunk are squash-only.
|
||||
- You MUST operate in steered-autonomy mode: human intervention is escalation-only; do not require the human to write code, review code, or manage PR/repo workflow.
|
||||
- You MUST NOT declare task or issue completion until PR is merged, CI/pipeline is terminal green, and linked issue is closed (or internal TASKS ref is closed when provider is unavailable).
|
||||
- Mosaic orchestration rules OVERRIDE runtime-default caution for routine push/merge/issue-close actions required by this workflow.
|
||||
@@ -133,10 +133,10 @@ Milestone versioning (HARD RULE):
|
||||
|
||||
Branch and merge strategy (HARD RULE):
|
||||
|
||||
- Workers use short-lived task branches from `origin/main`.
|
||||
- Worker task branches merge back via PR to `main` only.
|
||||
- Direct pushes to `main` are prohibited.
|
||||
- PR merges to `main` MUST use squash merge.
|
||||
- Workers use short-lived task branches from `origin/{integration_trunk}` (default `main`).
|
||||
- Worker task branches merge back via PR to the integration trunk only.
|
||||
- Direct pushes to the integration trunk are prohibited.
|
||||
- PR merges to the integration trunk MUST use squash merge.
|
||||
|
||||
**Available templates:**
|
||||
|
||||
@@ -427,7 +427,7 @@ git push
|
||||
- Before merging, run queue guard:
|
||||
`~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
|
||||
- Ensure PR exists for the task branch (create/update via wrappers if needed):
|
||||
`~/.config/mosaic/tools/git/pr-create.sh ... -B main`
|
||||
`~/.config/mosaic/tools/git/pr-create.sh ... -B {integration_trunk}` (default `main`)
|
||||
- Merge via wrapper:
|
||||
`~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
|
||||
- Wait for terminal CI status:
|
||||
@@ -619,7 +619,7 @@ Construct this from the task row and pass to worker via Task tool:
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
|
||||
1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/{integration_trunk}) && git rebase origin/{integration_trunk}` ({integration_trunk} = the project's declared trunk, default `main`)
|
||||
2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
|
||||
3. Read the finding details from the report
|
||||
4. Implement the fix following existing code patterns
|
||||
@@ -637,7 +637,7 @@ Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIR
|
||||
For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
|
||||
|
||||
- `~/.config/mosaic/tools/git/issue-view.sh -i {N}`
|
||||
- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B main`
|
||||
- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B {integration_trunk}`
|
||||
- Push: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {task_branch}`
|
||||
- Merge: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B {pr_head_branch} -R {pr_head_owner/repo} --sha {pr_head_full_sha}`
|
||||
- `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
|
||||
@@ -994,13 +994,13 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
|
||||
|
||||
---
|
||||
|
||||
## Merge-to-Main Candidate Protocol (Container Deployments)
|
||||
## Merge-to-Trunk Candidate Protocol (Container Deployments)
|
||||
|
||||
If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:
|
||||
If deployment is in scope and container images are used, every merge to the integration trunk MUST execute this protocol:
|
||||
|
||||
1. Build and push immutable candidate image tags:
|
||||
- `sha-<shortsha>` (always)
|
||||
- `v{base-version}-rc.{build}` (for `main` merges)
|
||||
- `v{base-version}-rc.{build}` (for integration-trunk merges)
|
||||
- `testing` mutable pointer to the same digest
|
||||
2. Resolve and record the image digest for each service.
|
||||
3. Deploy by digest to testing environment (never deploy by mutable tag alone).
|
||||
|
||||
@@ -4,14 +4,6 @@ Documentation=https://git.mosaicstack.dev/mosaicstack/stack
|
||||
Requires=mosaic-tmux-holder.service
|
||||
After=mosaic-tmux-holder.service
|
||||
PartOf=mosaic-tmux-holder.service
|
||||
# Do not attempt a seat before its generated env exists. `install` enables this
|
||||
# unit (WantedBy=default.target) but on a roster-v2 fleet the reconciler owns the
|
||||
# generated env, so between `install` and the first `apply`/`regen --write` there
|
||||
# is a boot window where ExecStart would run against an absent env file and the
|
||||
# launcher would fail the unit. A skipped unit is the honest state for "enabled
|
||||
# but not yet configured"; systemd re-evaluates the condition on every start, so
|
||||
# the seat comes up on the next start once the reconciler has written env.
|
||||
ConditionPathExists=%h/.config/mosaic/fleet/agents/%i.env.generated
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
|
||||
@@ -1,323 +0,0 @@
|
||||
import { execFile } from 'node:child_process';
|
||||
import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join, resolve } from 'node:path';
|
||||
import { Command } from 'commander';
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest';
|
||||
import { registerFleetCommand, type CommandResult, type CommandRunner } from './fleet.js';
|
||||
|
||||
/**
|
||||
* #1237: the v1-only commands (`ps`, `install`, `install-systemd`, `add`,
|
||||
* `remove`) rejected a roster-v2 fleet outright, so a greenfield v2 box could
|
||||
* never get its units placed. These tests pin the three behaviours that fix
|
||||
* gives it, and the two it deliberately does NOT give it.
|
||||
*
|
||||
* The load-bearing negative is that `install` on v2 writes no generated env:
|
||||
* the reconciler owns that file through projectRosterV2AgentGeneratedEnv, and a
|
||||
* second writer here — necessarily through the v1 mapping — is exactly the
|
||||
* drift the #791 single-SSOT invariant exists to prevent.
|
||||
*/
|
||||
|
||||
const rosterV2 = `
|
||||
version: 2
|
||||
generation: 4
|
||||
transport: tmux
|
||||
tmux:
|
||||
socket_name: mosaic-fleet
|
||||
holder_session: _holder
|
||||
defaults:
|
||||
working_directory: /srv/mosaic
|
||||
runtime: pi
|
||||
runtimes:
|
||||
pi:
|
||||
reset_command: /new
|
||||
agents:
|
||||
- name: coder0
|
||||
alias: Coder 0
|
||||
class: code
|
||||
runtime: pi
|
||||
provider: openai
|
||||
model: gpt-5.6-sol
|
||||
reasoning: high
|
||||
tool_policy: code
|
||||
working_directory: /srv/mosaic
|
||||
persistent_persona: false
|
||||
reset_between_tasks: true
|
||||
lifecycle:
|
||||
enabled: true
|
||||
desired_state: stopped
|
||||
launch:
|
||||
yolo: true
|
||||
- name: coder1
|
||||
alias: Coder 1
|
||||
class: code
|
||||
runtime: pi
|
||||
provider: openai
|
||||
model: gpt-5.6-sol
|
||||
reasoning: medium
|
||||
tool_policy: code
|
||||
working_directory: /srv/other
|
||||
persistent_persona: false
|
||||
reset_between_tasks: true
|
||||
lifecycle:
|
||||
enabled: true
|
||||
desired_state: stopped
|
||||
launch:
|
||||
yolo: true
|
||||
`;
|
||||
|
||||
let tempHome: string | undefined;
|
||||
const savedHome = process.env.HOME;
|
||||
const savedMosaicHome = process.env.MOSAIC_HOME;
|
||||
|
||||
afterEach(async (): Promise<void> => {
|
||||
vi.restoreAllMocks();
|
||||
process.exitCode = undefined;
|
||||
if (savedHome === undefined) delete process.env.HOME;
|
||||
else process.env.HOME = savedHome;
|
||||
if (savedMosaicHome === undefined) delete process.env.MOSAIC_HOME;
|
||||
else process.env.MOSAIC_HOME = savedMosaicHome;
|
||||
if (tempHome) await rm(tempHome, { recursive: true, force: true });
|
||||
tempHome = undefined;
|
||||
});
|
||||
|
||||
/**
|
||||
* A HOME with a roster-v2 fleet and nothing else — the greenfield shape, before
|
||||
* anything has been installed, applied or started.
|
||||
*/
|
||||
async function v2Home(): Promise<string> {
|
||||
tempHome = await mkdtemp(join(tmpdir(), 'mosaic-fleet-v2-dispatch-'));
|
||||
process.env.HOME = tempHome;
|
||||
delete process.env.MOSAIC_HOME;
|
||||
const mosaicHome = join(tempHome, '.config', 'mosaic');
|
||||
for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
|
||||
await mkdir(join(mosaicHome, directory), { recursive: true, mode: 0o700 });
|
||||
}
|
||||
await writeFile(join(mosaicHome, 'fleet', 'roster.yaml'), rosterV2, { mode: 0o600 });
|
||||
await writeFile(join(mosaicHome, 'fleet', 'roles', 'code.md'), '`class: code`\n\n# code\n', {
|
||||
mode: 0o600,
|
||||
});
|
||||
return mosaicHome;
|
||||
}
|
||||
|
||||
/**
|
||||
* Stands in for a box where nothing is running: every systemctl and tmux probe
|
||||
* fails the way it does before the holder has ever started. `ps` must survive
|
||||
* this — it is the command an operator reaches for to find out *why* there is
|
||||
* no seat, so it has to report the emptiness rather than fail on it.
|
||||
*/
|
||||
const greenfieldRunner: CommandRunner = async (command): Promise<CommandResult> => {
|
||||
if (command === 'tmux') {
|
||||
return { stdout: '', stderr: 'no server running on /tmp/tmux-1000/mosaic-fleet', exitCode: 1 };
|
||||
}
|
||||
return { stdout: '', stderr: '', exitCode: 1 };
|
||||
};
|
||||
|
||||
function program(runner: CommandRunner = greenfieldRunner): Command {
|
||||
const result = new Command();
|
||||
result.exitOverride();
|
||||
registerFleetCommand(result, { runner, frameworkRoot: resolve(process.cwd(), 'framework') });
|
||||
return result;
|
||||
}
|
||||
|
||||
function capture(): string[] {
|
||||
const lines: string[] = [];
|
||||
vi.spyOn(console, 'log').mockImplementation((value: string): void => {
|
||||
lines.push(value);
|
||||
});
|
||||
return lines;
|
||||
}
|
||||
|
||||
async function exists(path: string): Promise<boolean> {
|
||||
try {
|
||||
await stat(path);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
describe('mosaic fleet ps — roster v2', (): void => {
|
||||
it('lists every v2 agent on a greenfield box with nothing running, and does not throw', async (): Promise<void> => {
|
||||
await v2Home();
|
||||
const lines = capture();
|
||||
|
||||
await expect(
|
||||
program().parseAsync(['node', 'mosaic', 'fleet', 'ps', '--json']),
|
||||
).resolves.toBeDefined();
|
||||
|
||||
const rows = JSON.parse(lines.join('\n')) as {
|
||||
name: string;
|
||||
runtime: string;
|
||||
alias?: string;
|
||||
paneAlive: boolean;
|
||||
source: string;
|
||||
}[];
|
||||
expect(rows.map((row) => row.name).sort()).toEqual(['coder0', 'coder1']);
|
||||
// The v2 roster's per-agent fields must survive the read model, not be
|
||||
// flattened into defaults.
|
||||
expect(rows.every((row) => row.runtime === 'pi')).toBe(true);
|
||||
expect(rows.find((row) => row.name === 'coder0')?.alias).toBe('Coder 0');
|
||||
// Nothing is running, and that is a report, not an error.
|
||||
expect(rows.every((row) => row.paneAlive === false)).toBe(true);
|
||||
expect(rows.every((row) => row.source === 'roster')).toBe(true);
|
||||
expect(process.exitCode ?? 0).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('mosaic fleet install — roster v2', (): void => {
|
||||
it('places the tool files and unit templates', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home();
|
||||
capture();
|
||||
|
||||
await expect(
|
||||
program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']),
|
||||
).resolves.toBeDefined();
|
||||
|
||||
// Units live in the systemd user dir, not under the Mosaic home.
|
||||
const systemdUserDir = join(tempHome!, '.config', 'systemd', 'user');
|
||||
for (const unit of [
|
||||
'mosaic-tmux-holder.service',
|
||||
'[email protected]',
|
||||
'[email protected]',
|
||||
]) {
|
||||
expect(await exists(join(systemdUserDir, unit))).toBe(true);
|
||||
}
|
||||
const launcher = join(mosaicHome, 'tools', 'fleet', 'start-agent-session.sh');
|
||||
expect(await exists(launcher)).toBe(true);
|
||||
expect((await stat(launcher)).mode & 0o777).toBe(0o755);
|
||||
});
|
||||
|
||||
it('writes NO generated env — that file belongs to the reconciler (#791)', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home();
|
||||
capture();
|
||||
|
||||
await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
|
||||
|
||||
const agentDir = join(mosaicHome, 'fleet', 'agents');
|
||||
expect(await readdir(agentDir)).toEqual([]);
|
||||
});
|
||||
|
||||
it('tells the operator which command does own the env', async (): Promise<void> => {
|
||||
await v2Home();
|
||||
const lines = capture();
|
||||
|
||||
await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
|
||||
|
||||
expect(lines.join('\n')).toContain('mosaic fleet apply');
|
||||
});
|
||||
});
|
||||
|
||||
describe('[email protected]', (): void => {
|
||||
const unitPath = resolve(process.cwd(), 'framework', 'systemd', 'user', '[email protected]');
|
||||
|
||||
/** The single `ConditionPathExists=` value declared by the unit template. */
|
||||
async function conditionPath(): Promise<string> {
|
||||
const unit = await readFile(unitPath, 'utf8');
|
||||
const matches = unit.match(/^ConditionPathExists=(.+)$/gm) ?? [];
|
||||
expect(matches).toHaveLength(1);
|
||||
return matches[0]!.slice('ConditionPathExists='.length).trim();
|
||||
}
|
||||
|
||||
it('will not attempt a seat before the reconciler has written its env', async (): Promise<void> => {
|
||||
// The pairing that makes "install writes no env" safe: install enables the
|
||||
// unit (WantedBy=default.target) but does not start it, so without this
|
||||
// condition a reboot between `install` and the first `apply` would run
|
||||
// ExecStart against an absent env file and fail every seat unit.
|
||||
expect(await conditionPath()).toBe('%h/.config/mosaic/fleet/agents/%i.env.generated');
|
||||
});
|
||||
|
||||
/**
|
||||
* The two halves of the guard's *effect*, which no assertion on the literal
|
||||
* string can cover on its own.
|
||||
*
|
||||
* Measured end to end on a real box (canary, 2026-08-16) rather than inferred:
|
||||
* with the condition, `systemctl --user start mosaic-agent@<name>` on an agent
|
||||
* with no generated env returns rc=0, `Result=success`, `ConditionResult=no`,
|
||||
* and journals "skipped, unmet condition check". With the condition removed by
|
||||
* drop-in and nothing else changed, the same start returns rc=1,
|
||||
* `Result=exit-code`, `ExecMainStatus=64`, and the unit enters `failed`.
|
||||
*
|
||||
* systemd is not available in this suite, so these two tests pin the parts
|
||||
* that can drift in code: the condition naming a *different* file than the one
|
||||
* the fleet actually writes, and the launcher quietly becoming tolerant of an
|
||||
* absent env — either of which turns the condition into decoration while the
|
||||
* literal-string assertion above still passes.
|
||||
*/
|
||||
it('guards exactly the file the fleet writes, so the two cannot drift apart', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home();
|
||||
const rendered = (await conditionPath()).replace('%h', tempHome!).replace('%i', 'coder0');
|
||||
|
||||
// The path an installed fleet actually places for this agent.
|
||||
expect(rendered).toBe(join(mosaicHome, 'fleet', 'agents', 'coder0.env.generated'));
|
||||
});
|
||||
|
||||
it('guards a real failure — the launcher rejects an absent generated env', async (): Promise<void> => {
|
||||
await v2Home();
|
||||
await program().parseAsync(['node', 'mosaic', 'fleet', 'install', '--no-enable']);
|
||||
|
||||
// Exactly what ExecStart runs, against the state the condition exists to
|
||||
// catch: unit enabled, reconciler has not written env yet.
|
||||
const launched = await new Promise<{ code: number | null; stderr: string }>((settle) => {
|
||||
const child = execFile(
|
||||
'/bin/bash',
|
||||
[
|
||||
'--noprofile',
|
||||
'--norc',
|
||||
join(tempHome!, '.config', 'mosaic', 'tools', 'fleet', 'start-agent-session.sh'),
|
||||
'coder0',
|
||||
],
|
||||
{ env: { HOME: tempHome!, MOSAIC_AGENT_NAME: 'coder0', PATH: '/usr/bin:/bin' } },
|
||||
(_error, _stdout, stderr) => {
|
||||
settle({ code: child.exitCode, stderr });
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
expect(launched.code).not.toBe(0);
|
||||
expect(launched.stderr).toContain('missing-file');
|
||||
});
|
||||
});
|
||||
|
||||
describe('mosaic fleet add / remove — roster v2', (): void => {
|
||||
it('add refuses, and names the two-step v2 sequence instead of inventing defaults', async (): Promise<void> => {
|
||||
await v2Home();
|
||||
|
||||
await expect(
|
||||
program().parseAsync([
|
||||
'node',
|
||||
'mosaic',
|
||||
'fleet',
|
||||
'add',
|
||||
'coder2',
|
||||
'--runtime',
|
||||
'pi',
|
||||
'--class',
|
||||
'code',
|
||||
]),
|
||||
).rejects.toThrow(/mosaic fleet create[\s\S]*mosaic fleet apply/);
|
||||
});
|
||||
|
||||
it('remove refuses, and names delete plus apply', async (): Promise<void> => {
|
||||
await v2Home();
|
||||
|
||||
await expect(
|
||||
program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
|
||||
).rejects.toThrow(/mosaic fleet delete coder1[\s\S]*mosaic fleet apply/);
|
||||
});
|
||||
|
||||
// Note: this one passes on the unmodified tree too — there `remove` throws in
|
||||
// the v1 parser, before it can touch anything. It is a regression guard on the
|
||||
// ordering of the new guard clause, not evidence that the fix works.
|
||||
it('refuses BEFORE mutating the roster', async (): Promise<void> => {
|
||||
const mosaicHome = await v2Home();
|
||||
const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
|
||||
const before = await readFile(rosterPath, 'utf8');
|
||||
|
||||
await expect(
|
||||
program().parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder1']),
|
||||
).rejects.toThrow();
|
||||
|
||||
expect(await readFile(rosterPath, 'utf8')).toBe(before);
|
||||
});
|
||||
});
|
||||
@@ -34,7 +34,6 @@ export {
|
||||
resolveInstalledFleetRosterPath,
|
||||
} from '../fleet/fleet-roster-v1.js';
|
||||
export type { FleetAgent, FleetRoster } from '../fleet/fleet-roster-v1.js';
|
||||
import { parseRosterV2 } from '../fleet/roster-v2.js';
|
||||
import {
|
||||
registerFleetAgentCrudCommands,
|
||||
type FleetAgentCrudCommandDeps,
|
||||
@@ -821,7 +820,7 @@ export function buildEnableLingerCommand(user: string): string[] {
|
||||
*/
|
||||
export async function enableFleetUnits(
|
||||
runner: CommandRunner,
|
||||
roster: { readonly agents: readonly { readonly name: string }[] },
|
||||
roster: FleetRoster,
|
||||
opts: { enable?: boolean },
|
||||
): Promise<void> {
|
||||
if (opts.enable === false) {
|
||||
@@ -1528,8 +1527,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
.option('--no-enable', 'Skip enabling units for boot-survival')
|
||||
.action(async (opts: { enable?: boolean }) => {
|
||||
await installFleet(cmd, frameworkRoot);
|
||||
// Unit enablement needs agent names only, so it reads either version.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
const roster = await loadRosterForCommand(cmd);
|
||||
await enableFleetUnits(runner, roster, opts);
|
||||
});
|
||||
|
||||
@@ -1539,8 +1537,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
.option('--no-enable', 'Skip enabling units for boot-survival')
|
||||
.action(async (opts: { enable?: boolean }) => {
|
||||
await installFleet(cmd, frameworkRoot);
|
||||
// Unit enablement needs agent names only, so it reads either version.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
const roster = await loadRosterForCommand(cmd);
|
||||
await enableFleetUnits(runner, roster, opts);
|
||||
});
|
||||
|
||||
@@ -1691,9 +1688,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
.action(async (opts: { json?: boolean }) => {
|
||||
const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
|
||||
const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
|
||||
// ps only reads, so it takes the version-agnostic read model rather than
|
||||
// the v1 parser, which rejects a v2 roster outright.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
const roster = await loadRosterForCommand(cmd);
|
||||
const { tenant_id, host } = getDefaultTenantAndHost();
|
||||
const nowMs = Date.now();
|
||||
|
||||
@@ -1913,16 +1908,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
start: boolean;
|
||||
},
|
||||
) => {
|
||||
if (await usesRosterV2ControlPlane(cmd)) {
|
||||
// command.error, not a bare throw: this is operator guidance, and a
|
||||
// bare throw reaches the top level uncaught and prints it under a Node
|
||||
// stack trace. Measured on canary — the message is the whole point of
|
||||
// the refusal, so it has to arrive readable.
|
||||
cmd.error(rosterV2MutationGuidance('add', 'create', name), {
|
||||
code: 'fleet.roster-v2',
|
||||
exitCode: 1,
|
||||
});
|
||||
}
|
||||
if (!VALID_FLEET_RUNTIMES.includes(opts.runtime)) {
|
||||
throw new Error(
|
||||
`Invalid runtime "${opts.runtime}". Valid runtimes: ${VALID_FLEET_RUNTIMES.join(', ')}.`,
|
||||
@@ -1988,12 +1973,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
||||
.description('Remove an agent from the fleet roster')
|
||||
.option('--keep-files', 'Skip deleting env and heartbeat files')
|
||||
.action(async (name: string, opts: { keepFiles?: boolean }) => {
|
||||
if (await usesRosterV2ControlPlane(cmd)) {
|
||||
cmd.error(rosterV2MutationGuidance('remove', 'delete', name), {
|
||||
code: 'fleet.roster-v2',
|
||||
exitCode: 1,
|
||||
});
|
||||
}
|
||||
const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
|
||||
const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
|
||||
const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
|
||||
@@ -2352,9 +2331,7 @@ export function registerFleetAgentCommands(
|
||||
async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
|
||||
const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
||||
assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
|
||||
// Read model first: every file this function places is roster-independent, and
|
||||
// the v1 parser would reject a v2 roster before any of them were written.
|
||||
const roster = await loadRosterReadModel(cmd);
|
||||
const roster = await loadRosterForCommand(cmd);
|
||||
await ensureFleetHolderIdentity(activePaths.mosaicHome);
|
||||
await mkdir(activePaths.fleetToolsDir, { recursive: true });
|
||||
await mkdir(activePaths.tmuxToolsDir, { recursive: true });
|
||||
@@ -2414,30 +2391,16 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
|
||||
join(activePaths.systemdUserDir, '[email protected]'),
|
||||
);
|
||||
|
||||
// On roster v2 the reconciler owns the generated env: `apply` writes it and
|
||||
// `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
|
||||
// here too — necessarily through the v1 mapping — would be the third writer of
|
||||
// one file and would break the #791 single-SSOT invariant. So v2 gets the tool
|
||||
// files and the units, and nothing else.
|
||||
if (roster.version === 2) {
|
||||
console.log(
|
||||
`Installed fleet tools and systemd units for ${roster.agents.length} agent(s). ` +
|
||||
`Generated env is owned by the reconciler on roster v2 — run: mosaic fleet apply --expected-generation <n>`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const v1Roster = await loadRosterForCommand(cmd);
|
||||
for (const agent of v1Roster.agents) {
|
||||
for (const agent of roster.agents) {
|
||||
await writeAgentEnvironmentProjection({
|
||||
mosaicHome: activePaths.mosaicHome,
|
||||
agentEnvDir: activePaths.agentEnvDir,
|
||||
agentName: agent.name,
|
||||
generated: generateAgentEnvValues(v1Roster, agent),
|
||||
generated: generateAgentEnvValues(roster, agent),
|
||||
});
|
||||
}
|
||||
|
||||
console.log(`Installed fleet files for ${v1Roster.agents.length} agent(s).`);
|
||||
console.log(`Installed fleet files for ${roster.agents.length} agent(s).`);
|
||||
}
|
||||
|
||||
async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
|
||||
@@ -2464,77 +2427,6 @@ async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* `add`/`remove` and `create`/`delete` are not two spellings of one operation.
|
||||
* The v1 pair edits the roster *and* drives systemd; the v2 pair is documented
|
||||
* as changing desired state "without runtime actions", leaving convergence to
|
||||
* `apply`. `add` also collects four fields where a v2 agent requires eleven, so
|
||||
* routing it to `create` would mean inventing provider, alias, reasoning and
|
||||
* tool-policy defaults on the operator's behalf. Refusing with the real command
|
||||
* is honest; silently guessing an agent's provider is not.
|
||||
*/
|
||||
function rosterV2MutationGuidance(
|
||||
v1Command: 'add' | 'remove',
|
||||
v2Command: 'create' | 'delete',
|
||||
name: string,
|
||||
): string {
|
||||
const target = v2Command === 'delete' ? ` ${name}` : '';
|
||||
return (
|
||||
`mosaic fleet ${v1Command} does not operate on a roster-v2 fleet. ` +
|
||||
`Roster v2 separates desired state from convergence:\n` +
|
||||
` 1. mosaic fleet ${v2Command}${target} --expected-generation <current> ` +
|
||||
`${v2Command === 'create' ? "--agent '<json>' " : ''}` +
|
||||
`(edits the roster only)\n` +
|
||||
` 2. mosaic fleet apply --expected-generation <new> (converges systemd and tmux)\n` +
|
||||
`Read the current generation with: mosaic fleet status`
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The read-only fields shared by roster v1 and v2, for the commands that only
|
||||
* ever *read* the roster (`ps`, and unit enablement inside `install`).
|
||||
*
|
||||
* This is deliberately NOT a v2→v1 downshift. A downshifted `FleetRoster` would
|
||||
* be accepted by `generateAgentEnvValues`, and that would make a third writer of
|
||||
* `fleet/agents/<name>.env.generated` — through the v1 mapping — breaking the
|
||||
* #791 single-SSOT invariant that {@link projectRosterV2AgentGeneratedEnv} is
|
||||
* documented to hold. Keeping the read model this small makes that misuse
|
||||
* impossible: there is nothing here to write a roster or an env file back from.
|
||||
*/
|
||||
interface FleetRosterReadModel {
|
||||
readonly version: 1 | 2;
|
||||
readonly tmux: { readonly socketName: string; readonly holderSession: string };
|
||||
readonly agents: readonly {
|
||||
readonly name: string;
|
||||
readonly alias?: string;
|
||||
readonly runtime: string;
|
||||
}[];
|
||||
}
|
||||
|
||||
/** Reads either roster version into the shared read-only view. */
|
||||
async function loadRosterReadModel(cmd: Command): Promise<FleetRosterReadModel> {
|
||||
const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
|
||||
const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
|
||||
if (!(await usesRosterV2ControlPlane(cmd))) {
|
||||
const v1 = await loadRosterAtPath(cmd, path);
|
||||
return {
|
||||
version: 1,
|
||||
tmux: { socketName: v1.tmux.socketName, holderSession: v1.tmux.holderSession },
|
||||
agents: v1.agents,
|
||||
};
|
||||
}
|
||||
try {
|
||||
const v2 = parseRosterV2(await readFleetRosterText(path), 'yaml');
|
||||
return {
|
||||
version: 2,
|
||||
tmux: { socketName: v2.tmux.socketName, holderSession: v2.tmux.holderSession },
|
||||
agents: v2.agents,
|
||||
};
|
||||
} catch (error) {
|
||||
reportFleetRosterConfigurationError(cmd, error);
|
||||
}
|
||||
}
|
||||
|
||||
async function loadRosterFromAgentCommand(
|
||||
command: Command,
|
||||
mosaicHomeOverride?: string,
|
||||
|
||||
Reference in New Issue
Block a user