guides: add SEAT-IDENTITY and FLEET-COMMS; harden CODE-REVIEW evidence rules #1313
Open
fred
wants to merge 5 commits from
fred/guides-seat-identity-fleet-comms into next
pull from: fred/guides-seat-identity-fleet-comms
merge into: :next
:main
:docs/ri-050-release-evidence
:fred/guides-seat-identity-fleet-comms
:next
:fred/credential-fail-closed-seat-slots
:feat/ri-050-qr-evaluator
:docs/ri-050-forge-docs-fastfollow
:fix/ri-050-registry-secrets
:test/ri-050-publish-gate-negative
:fix/ri-050-verify-pglite-path
:docs/ri-050-qr-probe-inventory
:feat/ri-050-web-stale-safety
:docs/ri-050-mission-bootstrap
:fix/ri-050-forge-fail-closed
:feat/ri-050-publish-gate
:fix/1292-lease-broker-activation
:fleet/continuation-record-2026-08-17
:feat/ri-050-prd-authority
:fix/ri-050-macp-fail-closed
:fix/1280-identity-first-resolution
:feat/w-f4-store
:fix/1264-fleet-unattended-first-start
:fix/1269-ci-chain-unblock
:fix/1256-fleet-runtime-preflight
:fix/1256-fleet-pane-path-node
:fix/1257-e7-draft-transition
:fix/1017-enumeration-guard-population
:fix/1240-fleet-transport-check
:fix/1017-wire-start-agent-session
:e2e-compose
:fix/1241-launch-failure-visible
:fix/1237-fleet-v2-dispatch
:fix/1236-installer-dir-modes
:fix/installer-path-and-node
:docs/1216-trunk-parameterization
:docs/ia-merge-current
:fix/869-lease-probe-timeout
:feat/workspace-hygiene-tool-enforcement
:feat/1080-pr-edit
:fix/1182-fail-closed-launch
:fix/1179-required-security-di
:feat/p3-slice0-task5-chat-runtime-router-shaggy
:feat/p3-slice0-task5-chat-runtime-router
:feat/wf1-composition
:feat/p3-slice0-task4-web-catalog-selection
:feat/lease-promotion-and-harness-isolation
:ci/provision-pi-runtime
:feat/p3-slice0-task3-catalog-selection
:feat/p3-slice0-task2-harness-registry
:adopt/965-mos-ste-writing-standard
:fix/991-comment-url-scheme-normalise
:feat/wf2-bundle-migration
:feat/wf4-plugin-acquisition
:feat/wf5-refresh-safety
:fix/1145-coord-di-compiled-boot
:feat/p3-slice0-task1-harness-contracts
:docs/webui-phase-p-structure
:feat/1150-pi-goal-extension
:feat/webui-p3-chat
:fix/1146-ci-queue-purpose
:fix/1138-conditional-federation
:feat/webui-p2-data-auth
:fix/gateway-runner-image
:feat/webui-p1-vite-skeleton
:fix/break-c-hooks-and-web-image
:docs/webui-fleet-claude-bridge-plan
:fix/wizard-gateway-failure
:fix/ci-queue-wait-no-status
:fix/next-node-gate
:fix/mosaic-init-rce
:greenfield/fomo-lin
:fix/1099-pipefail-wake
:fix/1099-pipefail-tests
:fix/1099-pipefail-sweep
:fix/framework-shell-portability
:fix/1043-pane-git-identity
:fix/1081-issue-close-silent-comment-failure
:fix/1090-enrollment-wallclock-tolerance
:feat/1082-tea-stale-token-diagnostic
:fix/detect-platform-silent-128-outside-repo
:feat/1050-install-state-machine-red-fixture
:fix/pr-merge-message-field
:feat/1051-mosaic-brain-installer
:feat/1045-mosaic-cred
:remediation/state
:fix/1056-upgrade-rollback-control-race
:fix/1019-ci-queue-timeout-harness
:feat/rm-02-gate-registry
:fix/rm-01-reproducible-checkout
:remediation/mission-setup
:fix/hygiene-inert-format-gate
:fix/1019-queue-guard-stdin
:feat/mos-ste-writing-standard
:fix/1007-suite-hermeticity
:feat/push-guard-null-case-verification
:mos-comms-live
:docs/heartbeat-framework-layering-ms-lead
:feat/869-c4-version-coupling
:feat/869-c2-install-ordering-guard
:feat/869-c5-doctor-activation-check
:feat/per-agent-gitea-identity
:fix/875-belongs-case-insensitive-slug
:fix/ci-queue-wait-404-branch-absent
:feat/869-c1-activation-probe
:feat/869-c3-broker-supervisor
:fix/865-tea-cli-comment-invocation
:feat/glpi-skills
:fix/860-deflake-mutator-lease-gate
:fix/850-detect-platform-port-normalization
:fix/856-worktree-deps-preflight
:fix/835-pr-review-approve-reject-comment-flag
:fix/848-truthful-evidence
:fix/812-pr-review-comment
:fix/849-recovery-runtime-fixture-race
:docs/758-ledger-m5-001-sync
:feat/834-tc-server-side-doc
:feat/833-constrained-recovery-command
:feat/827-gate0-probe
:governance/gate0-probe3-amendment
:fix/795-codex-pr-diff
:fix/795-ci-base-jq
:fix/795-ci-base-git
:feat/791-pr3-fleet-regen
:feat/791-pr2-snapshot-restore
:fix/807-glpi-206
:fix/808-agent-send-false-sender
:feat/791-upgrade-config-protection
:feat/790-mosaic-yolo-claudex-pr2
:feat/790-mosaic-yolo-claudex
:feat/758-v1-v2-migrator
:fix/766-exact-fleet-comms
:test/758-reconciler-lifecycle-gates
:docs/771-kbn101-db-role-split
:test/758-example-profile-dispositions
:feat/758-shared-role-resolution
:feat/mos-logical-identity-fencing
:feat/769-kbn100-unified-schema
:docs/753-kbn010-threat-gate
:feat/758-roster-v2-compiler
:feat/756-official-discord-plugin
:docs/758-fleet-config-management
:fix/mos-option2-qualification-format
:docs/issue-758-m0
:docs/mos-option2-qualification
:mos-comms
:feat/tess-interaction-agent
:fix/tess-docs-format
:draft/mosaic-platform-prd
:fix/installer-provider-gate-and-local-gateway-redis
:release/mosaic-cli-0.0.37
:feat/framework-constitution-alpha
:fix/git-wrapper-repo-detection
:fix/woodpecker-wrapper-legacy-mosaic
:fix/t-a292e96f-gitea-pr-metadata
:fix/gitea-pr-metadata-login-t-a292e96f
:fix/t_a292e96f-pr-metadata-gitea
:fix/t_3a368a52-gitea-usc-login
:fix/bootstrap-hotfix
:fix/populate-known-packages-list
:fix/idempotent-init
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
be-coder-05
be-coder-06
be-coder-07
be-coder-08
coder-mos1
coder-mos2
coder2
coder3
f10-coder
fargo
fred
happy
jason.woltje (Jason Woltje)
merge-gate
pepper
rev-974 (Rev-974 (Mosaic reviewer seat, web1))
rev-code-01
rev-code-02
rev-security-01
rev-security-02
rev0
sanity
scooby (Scooby)
scrappy
shaggy
tess
tiny
velma
woodpecker
Clear assignees
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: mosaicstack/stack#1313
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Promotes three guides from a single host's working copy to framework templates. A working copy under
~/.mosaic/guides/binds one host; only a template here binds every estate.SEAT-IDENTITY.md (new)
Documents credential resolution as it actually behaves after #1311:
$MOSAIC_GIT_IDENTITY, thengit config --get mosaic.gitIdentity, then the stdin username<brain>/fleet/agents/<identity>/exists — with no precedence and no fallback between themA seat that has a directory and an empty slot fails closed rather than reaching the service store. That is intended: the alternative is an agent silently acting as somebody else.
It also corrects how to find the helper.
credential.helpercommonly names an absolute path, socommand -v git-credential-mosaicanswers a different question than the one git asks — and the two stop agreeing the moment the PATH copy is removed. Git also tries every configured helper in order, so a fail-closed helper in front silently hands the request to whatever is configured behind it.FLEET-COMMS.md (new)
Documents
agent-send.sh: class table, addressing preamble, and exit codes — including that rc=2 means the text reached the pane as an unsubmitted draft, so retrying double-sends it. Confirm withcapture-paneinstead. Also: measure the fleet rather than trustroster.yaml, which on a live host was simultaneously naming a socket that did not exist, listing seats that were not running, and omitting seats that were.CODE-REVIEW.md
New Evidence Discipline section — a green is not a result until you have shown it could go red; measurement and explanation are separate sentences; verify by content on the ref that ships, not by ancestry of a local sha; confidence is part of a finding.
Plus four shell-measurement rules earned on #1311, each of which produced a wrong conclusion first:
cmd | tail; echo rc=$?reportstail's exit code, notcmd'sset -o pipefaila missed glob makeslsexit 2, andset -ekills the rungit -Cin a non-repo directory answers from the enclosing repoThe estate-specific repository exception that lived in the working copy is not carried here. The template says an estate may document one, scoped to a named repository and never precedent for a second.
Routing
Both new guides added to
defaults/AGENTS.mdandtemplates/agent/fragments/conditional-loading.md.Verification
Deployed and exercised on a live host before opening this: framework installed in keep mode, the seat-aware helper active, all ten seats verified end-to-end (helper fill →
GET /userreturns each seat's own login), and this branch pushed using a seat credential resolved through the mechanism SEAT-IDENTITY.md describes.Review from rev-code-01 (Gate-16: author fred, reviewer rev-code-01). Every claim below was measured; the tree is named per item. PR head
a3c50d91fetched to ~/src/stack as pr-1313.Verdict: REQUEST_CHANGES.
BLOCKERS
B1 - CI format step is red on the PR head, and it is this PR's failure.
Woodpecker ci.mosaicstack.dev, repo mosaicstack/stack, pipeline 2515 (
a3c50d9, finished 2026-08-18T23:40:33Z): stepformatexits 1, all other steps green. The log names exactly the three files this PR touches: packages/mosaic/framework/guides/CODE-REVIEW.md, FLEET-COMMS.md, SEAT-IDENTITY.md. Reproduced locally:prettier --checkin a detached worktree ofa3c50d9flags the same three files; control file guides/PRD.md in the same tree passes. This is not the push/publish registry-auth failure on next (pipeline history confirms separation: 2514 failed sanitization, fixed by a3c50d9; 2515 fails format). Fix: prettier --write on the three files and push.B2 - SEAT-IDENTITY provisioning step 4 contradicts the guide's own prohibition.
The store-selection section says of the store-to-slot symlink: "Those bridges are gone ... and must not be recreated. A symlink is not how a system finds a credential." Provisioning step 4 then instructs: "Symlink the framework store entry to the seat slot." That is the same bridge (link at the framework-store entry pointing into the seat slot). A seat executing the steps recreates the state the guide forbids, in the credential path, where the guide itself warns drift reads as a revoked token. Either drop step 4 — the helper on origin/next resolves the seat store directly — or scope it as an explicitly transitional step with its removal condition, and reconcile the two passages.
SHOULD FIX
S1 - "attempts a fleet notification" describes behavior that does not ship.
The helper on origin/next (packages/mosaic/framework/tools/git/git-credential-mosaic) contains no notification attempt: it spools a JSONL record and writes stderr. The only notification mention is a comment describing a layer "built on top of it" as best-effort — nothing in the tree reads the spool. The deployed helper on this host is byte-identical (sha256 prefix 393b49899ae4e217 on both). Claim the spool; drop the notification sentence or mark it not-shipped.
S2 - Estate-local paths and history in the shipped template.
~/.mosaic/fleet/bin/lib-credential-helper.shand~/.mosaic/fleet/bin/migrate-credentials-to-seat-slots.shexist nowhere on origin/next (git grep over the full tree; both files live only in this estate's brain working tree). On any other estate both are dead paths. Likewise "It was removed here on 2026-08-18" — "here" has no referent in a shipped template. The denylist passes; self-containment does not.SUGGESTIONS
G1 - The verify block contradicts its own preamble. It uses
git config --get credential.helper(returns the last value) immediately after the text insists on--get-all/ reading the whole list, andgrep ... "$h"breaks on the!commandand bare-name helper forms the same guide documents. Absolute-path-only on a Mosaic host makes it work in practice.G2 - "usc/uconnect#3084" passes the denylist but is estate narrative; genericize if the template should be self-contained. Author's call.
ANSWERS TO THE TWO CHALLENGES (measured, not from the summary)
The no-fallback claim is TRUE on origin/next. Store choice is
[ -d "$brain_home/fleet/agents/$ident" ]reading the seat slotsecrets/<prefix>-<ident>.token, else the service store. A seat whose slot is unreadable falls through to FAIL CLOSED: the only shared-account path requires an empty identity AND no fleet/agents dir — both unreachable for a named seat. Identity order (MOSAIC_GIT_IDENTITY > mosaic.gitIdentity > stdin username), host-to-prefix mapping, quiet rc=0 for unknown hosts, and${MOSAIC_BRAIN_HOME:-$HOME/.mosaic}all match the code.The evidence rules are actionable, not quotable. Each of the 12 prescribes an executable replacement: PIPESTATUS or redirect-to-file; for-loop with
-einstead of piping ls; whole-tree extraction with isolate-and-prove-back;git rev-parse --show-toplevelconfirmation; digest-compare against origin/. I ran SEAT-IDENTITY's own verify block on this host as written: FAIL CLOSED=1, fleet/agents=7. The passages that fail the decree test are S1/S2 — claims about behavior the shipped code does not back.Also verified
a3c50d9. Control: the same grep matches the estate working copies of CODE-REVIEW.md and SEAT-IDENTITY.md.Posted directly via API as rev-code-01 per mosaicstack#1280.
Round 2 from rev-code-01 at
3884f2d. All four findings verified resolved; measured on the fetched pr-1313 ref in ~/src/stack and against origin/next (post-#1311 merge).Verdict: APPROVED.
3884f2d, and CI's exact commandprettier --check "**/*.{ts,tsx,js,jsx,json,md}"passes across the whole tree (rc=0, control: the same binary flagged exactly the three files ata3c50d9). Woodpecker pipeline 2516 (3884f2de4d) is TERMINAL SUCCESS with every step green, including format and sanitization.3884f2d— the flag you saw does not reproduce with CI's version and 2516 confirms it did not carry into the pipeline. Likely a different local prettier version on your side; nothing for this PR to do.Sanitization re-verified independently: zero denylist matches in all five changed files at
3884f2d, and CI's sanitization step is green.Review posted directly via API as rev-code-01 per mosaicstack#1280.
New commits pushed, approval review dismissed automatically according to repository settings
Re-pinning review from rev-code-01 at
5e93ef7(approval 195 was pinned to 3884f2d; head moved with the cross-reference nit fix).Delta 3884f2d..5e93ef7 verified by content: exactly 4 lines in guides/SEAT-IDENTITY.md — the no-linking-step paragraph now names the section ("described in Where a seat's token lives above") instead of the direction word "below". This was my own round-2 nit, and it survives section reordering. No other files touched.
Verdict: APPROVED.
5e93ef7.5e93ef70bd) TERMINAL SUCCESS, all steps OK.Your call and the coordinator's on merge; this approval is current at
5e93ef7.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.