9 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
fred	3884f2de4d	guides: address rev-code-01's review of #1313 (B1, B2, S1, S2) ... All four findings reproduced before fixing. rev-code-01 was right on each. B2 (blocker, mine). SEAT-IDENTITY provisioning step 4 said to symlink the framework store entry to the seat slot, while the same file says those bridges must not be recreated. The same bridge, told both ways, in one document. I rewrote the resolution and token-location sections when the deploy made them stale and did not carry the change into the numbered steps. Step 4 is gone and the file now says explicitly that no provisioning step links the store to the slot, so the omission cannot read as an oversight. S1 (mine). The guide claimed the helper "attempts a fleet notification" on refusal. The shipped helper does no such thing — its only reference to notification is a comment saying an alert built on the record is best-effort, and there is no send or wake call anywhere in the file. Now: it writes a durable record, the record is what exists, and nobody should wait for a notification that nothing sends. A guide that promises an alert is worse than one that promises nothing. S2. Estate-local content removed from files that ship to every estate: the ~/.mosaic/fleet/bin script paths (dead paths elsewhere) and the 2026-08-18 dates, which dated a specific host's migration rather than describing behavior. The bridge-removal passage now states the ORDERING that matters — remove bridges only after a seat-aware helper can reach the slot, never before — which is the part that transfers. B1. prettier reformatted all three files. Reproduced the pipeline 2515 failure locally before and confirmed clean after; the other three guides prettier flags are untouched by this branch (0 changes vs origin/next) and are pre-existing. Sanitization gate re-run and passing. Verified for the record, since I could not verify my own work: rev-code-01 confirmed the no-fallback claim TRUE against helper content on origin/next, and judged the evidence rules actionable on the grounds that each names an executable replacement.	2026-08-18 18:51:15 -05:00
fred	a3c50d91ca	guides: genericize the operator name in SEAT-IDENTITY provisioning ... Pipeline 2514 failed the sanitization gate on 'Jason mints the token into the seat slot'. The denylist is jarvis|jason|woltje|... and a shipped framework file must not carry operator identity. My mistake: I generalized the estate paths and seat names when promoting this guide and did not check the operator name. Now reads 'the estate operator', with the accompanying rule that an agent does not ask another agent to mint one either. Verified by running tools/quality/scripts/verify-sanitized.sh locally rather than guessing at the pattern: gate passes.	2026-08-18 18:28:37 -05:00
fred	2fd102e6af	guides: state the decree, drop the mechanism ... The #1280 prohibition carried an explanation of how the tools misattribute and why the failure is invisible from inside them. A reader who is not going to use the tool cannot act on any of it. Same for rule 2's closing clause about what reviews commonly miss. Both cut to the decree and the corrective action. Rules 1 and 3-12 keep their trailing sentences: those are corrective actions or the detail that makes the case recognizable, not justification.	2026-08-18 18:25:47 -05:00
fred	efb3c3a10c	guides: add SEAT-IDENTITY and FLEET-COMMS; harden CODE-REVIEW evidence rules ... Three guides that existed only as one host's working copy, promoted to framework templates so every estate gets them. A working copy under ~/.mosaic binds one host; only a template here binds all of them. SEAT-IDENTITY.md (new) documents how a seat's git credential is actually resolved after #1311: identity from MOSAIC_GIT_IDENTITY, then mosaic.gitIdentity, then the stdin username; host mapped to a store prefix; then ONE of two stores chosen by whether the seat directory exists, with no precedence and no fallback between them. A seat with a directory and an empty slot fails closed rather than reaching the service store, and that is the point. It also corrects how to find the helper. credential.helper commonly names an absolute path, so `command -v git-credential-mosaic` answers 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. The guide says to read the whole list. FLEET-COMMS.md (new) documents agent-send.sh: the class table, the addressing preamble, and the exit codes — including that rc=2 means the text reached the pane as an unsubmitted draft, so retrying double-sends it. Confirm with capture-pane instead. It also says to measure the fleet rather than trust roster.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 gains an 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 rather than by ancestry of a local sha, and 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=$?` reports tail's status, a missed glob under pipefail exits 2 and kills the run under set -e, nonzero-with-no-output is an environment question before it is a code question, and `git -C` in a non-repo directory answers from the enclosing repo. The 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. Both new guides are added to the two routing tables that agents read.	2026-08-18 18:15:50 -05:00
fred	c703cc50eb	git-credential-mosaic: escape the escalation record, and stop naming a record that was never written ... Both defects found in review by rev-code-01 on #1311. F3 — the JSONL record interpolated every field with a bare %s. An identity comes from git config or the environment and a cwd is whatever directory git ran in, so either can contain a quote or a backslash. One such refusal turned the day's spool into unparseable JSONL, and the operator would only discover it while reading the record that explains an outage. Fields are now JSON-escaped. F2 — the diagnostic printed "record: <spool>/<date>.jsonl" unconditionally, but the record is only written inside the branch where mkdir -p succeeded. When the spool cannot be created the helper named a file that does not exist, on exactly the hosts where the escalation was lost. It now reports the real path or says NOT WRITTEN. Also: prettier on README.md, which was the format-step failure on pipeline 2508. It reflowed only the two tables this branch added. Tests: cases 14 and 15 cover both. Verified discriminating — against the previous helper with these same tests, case 14 fails with the unparseable record printed and case 15 fails on both assertions; against this one both pass. The first draft of case 14 used `ls "$spool"/*.jsonl | head -1`, which under `set -o pipefail` exits 2 on a missed glob and killed the suite with zero output — the same silent-nonzero failure rev-code-01 hit from a partial tools/ extraction and the reason this file exists. Replaced with a glob loop and a comment.	2026-08-18 17:04:55 -05:00
fred	3d2b712355	git credentials: fail closed, and read a seat's token from its own slot ... Two changes to one rule: a credential is resolved from exactly one place, and an identity that cannot be resolved is refused rather than substituted. FAIL CLOSED. Both readers ended in an unconditional fall-through to the shared Gitea account whenever an identity did not resolve. Every seat in a fleet therefore pushed, opened PRs and filed reviews under one account, and a record made that way cannot be traced to the agent that made it afterwards. The fallback now applies only where there is no attribution to lose: a host with no fleet. Where seats exist, an unresolvable request emits nothing, exits nonzero, explains itself on stderr, and — in the git helper — appends a record naming the identity, host, reason and cwd, and no token value, to ${MOSAIC_CREDENTIAL_SPOOL:-~/.local/state/mosaic-credential-escalations}. A host runs a fleet when <brain>/fleet/agents exists, which is the signal packages/mosaic/src/fleet/brain-home.ts already uses to decide a brain is active, resolved the same way (MOSAIC_BRAIN_HOME, else ~/.mosaic). This is what keeps the change a no-op for an operator who has not provisioned per-slot tokens: no fleet directory, shared account, unchanged. It is also why there is no environment variable to restore the old behavior — one would reintroduce the substitution being removed. STORE SELECTION. Both readers hardcoded ~/.config/mosaic/secrets/gitea-tokens, so a seat's own secrets/ slot was invisible to the framework: a seat could hold a valid credential and still be served the shared account. The store is now chosen by what the identity is. An identity with a directory under <brain>/fleet/agents/ is a seat and is read only from <brain>/fleet/agents/<id>/secrets/; any other identity is a service identity and is read from the framework store. There is no precedence between them and no fallback from one to the other, so a seat with an empty slot is refused even when a same-named token sits in the framework store. Two copies of one credential are drift rather than redundancy, and drift surfaces as the stale copy returning 401, which reads as a revoked token and sends whoever debugs it somewhere else. detect-platform.sh is in scope alongside git-credential-mosaic because they are the two readers of these tokens. Patching only the git helper would make "one credential, one location" true for push and fetch and false for pr-create.sh, issue-create.sh and pr-review.sh, which is the harder failure to notice. TESTS. The three assertions that pinned the shared-account fall-through are now fail-closed assertions, and a refusal is checked four independent ways: nonzero exit, empty stdout, a stderr diagnostic naming identity and host, and no shared token value anywhere in the output. The exit code alone would pass against a helper that emitted the credential and then failed. Added: seat-slot resolution, the no-cross-store-fallback case with a control proving the framework-store file it declines to read is readable, no-identity on a fleet host, the fleet gate firing on the default ~/.mosaic and not only on an injected MOSAIC_BRAIN_HOME, and a cross-host leak check. Both suites were run against the pre-change code as a control and fail there on exactly the shared-token emission. shellcheck is not installed on the authoring host, so the rewritten helper is unlinted locally and CI is the first lint of it.	2026-08-18 16:19:43 -05:00
fred	57a2f2b40e	docs(ci): point the exclusion at tracking issue #1271, not the closed first filing ... The first PR for this change was filed under the retired mos-dt-0 principal (pr-create.sh has no --login flag and find_tea_login_for_host returns the first host match) and was closed and refiled as #1270. That left in-tree references pointing at a closed duplicate PR rather than at the burn-down issue, which is the wrong target for them anyway: the open design question belongs on #1271.	2026-08-16 18:03:02 -05:00
fred	93c1de51e1	fix(ci): unwire test-start-agent-session.sh, restore its signed exclusion (#1269) ... The `test` step has failed on every `next` pipeline since #1017 on exactly one assertion, and it is the same one on unrelated PRs: FAIL: host provides 'pi' in the system path; missing-binary cases are not measurable here (framework/tools/fleet/test-start-agent-session.sh:103) Measured 2026-08-16 across pipelines 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in each full log, identical, this line. Control `zzz-not-present-zzz` -> 0 on all three. Cause. #1241 (5c35a250) added the guard: the suite shims fake mosaic/pi/npm into $FAKE_BIN, but the constructed PANE_PATH always ends in the real system path, so on a host that installs those binaries the missing-binary cases cannot be measured and a green run would mean nothing. The guard says so instead of passing. Its own pipeline 2430 was green only because the suite was CI-excluded at the time, so the guard had never run in CI. #1017 (c56483eb) then enumerated it and dropped the exclusion. The CI image installs @earendil-works/[email protected].1 on purpose, so the precondition is unsatisfiable there. Both commits are mine. The guard is correct and is not being softened. A check that cannot measure its property and reports success is the failure mode this repo has been cataloguing all week; the error was wiring the suite into an image that violates its precondition, so the wiring is what gets reverted. Second effect, which is the reason this cost a day rather than an hour: test:framework-shell is one && chain and this sat at position 44 of 48, so glpi/test-list-http-status.sh, orchestrator/test-board-roll.sh, woodpecker/test-ci-wait-exit-matrix.sh and _scripts/test-fleet-transport-check.sh have not run at all since the merge. The pipeline reported one failure, never "one failure plus four unrun". All four are green when run directly on sb-it-1-dt, so the mask hid nothing broken -- but that is a local result on one host, not a CI-image result. Verification, with controls: - enumeration guard OK (population 52, enumerated 36, signed-excluded 16). - control A, exclusion line removed while unwired -> FAIL UNENUMERATED. - control B, exclusion line kept while rewired -> FAIL CONTRADICTORY EXCLUSION. The gate discriminates in both directions, so its OK is load-bearing. - the four formerly-masked suites: rc=0 each, run directly. - the full chain cannot be run to completion on sb-it-1-dt: it stops earlier, at the lease-broker Invariant R test, because this host carries the quarantined operator-global pi 0.84.2 against a measured 0.84.1. That is host-specific and out of scope here -- CI pins 0.84.1, and the single FAIL line in those three pipelines proves positions 1-43 passed there. Burn-down is to control the tail of PANE_PATH inside the test, not to remove pi from the image. Recorded in the exclusion reason and in #1269.	2026-08-16 17:58:49 -05:00
fred	07373ede4d	docs(install): record the two trust/portability assumptions in install_node ... Comment-only, no behaviour change. Both raised by scooby in the #1229 review as non-blocking findings worth writing down rather than fixing here. F-A: the SHASUMS256.txt check gives integrity, not authenticity. TLS to $NODE_DIST_BASE is the whole trust root, and MOSAIC_NODE_DIST_BASE widens it to any mirror with no signature backstop. GPG-verifying SHASUMS256.txt.sig is filed as its own follow-up so it gets its own review. F-C: the uname map pulls the glibc build, so musl hosts fail — visibly, via node_is_suitable, not silently.	2026-08-15 21:50:14 -05:00