Merge remote-tracking branch 'origin/next' into fix/1280-identity-first-resolution

# Conflicts: # packages/mosaic/package.json
Merge pull request 'fix(ci): unwire test-start-agent-session.sh, restore its signed exclusion — unblocks every PR on next' (#1270 ) from fix/1269-ci-chain-unblock into next
2026-08-17 16:24:43 -05:00 · 2026-08-17 20:44:59 +00:00 · 2026-08-17 15:19:04 -05:00 · 2026-08-17 15:18:54 -05:00 · 2026-08-16 18:03:02 -05:00 · 2026-08-16 17:58:49 -05:00
36 changed files with 1247 additions and 1650 deletions
@@ -9,19 +9,19 @@ This book is the canonical home for installation, configuration, deployment, rou
 - [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
 - [Documentation sitemap](../SITEMAP.md) — resolvable current navigation and authority-gated migration summary.
 - [Product requirements](../PRD.md) — normative requirements, currently marked draft.
- [Operations index](operations/README.md) — current local procedures, unattended fleet first-start handling, and explicitly held operational outlines.
+- [Operations index](operations/README.md) — current local procedures and explicitly held operational outlines.
 - [Security index](security/README.md) — current SSO provider configuration.

 ## Chapter map

-| Chapter                               | Scope                                                               | Status                                                                                         |
-| ------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `installation/`                       | Prerequisites, installation, and first deployment.                  | Scaffold only.                                                                                 |
-| `configuration/`                      | Environment, provider, tier, and runtime configuration.             | Scaffold only.                                                                                 |
-| `deployment/`                         | Topologies, rollout, migration, and upgrade procedures.             | Scaffold only.                                                                                 |
-| [`operations/`](operations/README.md) | Health, observability, routine operation, and maintenance.          | Local upgrade/recovery and fleet first start are current; connector lease operations are held. |
-| [`security/`](security/README.md)     | Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned.                                        |
-| `recovery/`                           | Incident response, backup, rollback, and recovery.                  | Scaffold only.                                                                                 |
+| Chapter                               | Scope                                                               | Status                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `installation/`                       | Prerequisites, installation, and first deployment.                  | Scaffold only.                                                          |
+| `configuration/`                      | Environment, provider, tier, and runtime configuration.             | Scaffold only.                                                          |
+| `deployment/`                         | Topologies, rollout, migration, and upgrade procedures.             | Scaffold only.                                                          |
+| [`operations/`](operations/README.md) | Health, observability, routine operation, and maintenance.          | Local upgrade/recovery is current; connector lease operations are held. |
+| [`security/`](security/README.md)     | Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned.                 |
+| `recovery/`                           | Incident response, backup, rollback, and recovery.                  | Scaffold only.                                                          |

 Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.

@@ -5,7 +5,6 @@
 ## Current procedures

 - [Upgrade safety and recovery](upgrade-safety-and-recovery.md) — installed-CLI and local-PGlite upgrade, rollback, and framework-configuration recovery.
- [Fleet unattended first start](fleet-unattended-first-start.md) — systemd/no-TTY identity initialization, failure handling, and isolated verification.

 ## Held procedures

@@ -1,70 +0,0 @@
-# Fleet Unattended First-Start Operations
-
-> **Status:** Current after issue #1264 lands. This runbook covers only Mosaic's first-run identity
-> gate; it does not install runtimes or credentials.
-
-## Operational contract
-
-A systemd fleet unit launches under a sanitized environment with no TTY. The generated environment
-sets `MOSAIC_AGENT_NAME`; Mosaic resolves that exact value against the canonical installed roster
-before writing identity files.
-
-If top-level identity contracts are missing, Mosaic atomically seeds them from the shipped generic
-sources:
-
-| Destination            | Source                          | New-file mode |
-| ---------------------- | ------------------------------- | ------------- |
-| `$MOSAIC_HOME/SOUL.md` | `$MOSAIC_HOME/defaults/SOUL.md` | `0600`        |
-| `$MOSAIC_HOME/USER.md` | `$MOSAIC_HOME/defaults/USER.md` | `0600`        |
-
-Creation is no-clobber and safe under concurrent seat starts. Existing regular files remain
-byte-for-byte and mode-for-mode unchanged. The runtime composer then injects the exact roster name
-and class; the generic source files grant no seat authority.
-
-## Failure handling
-
-The fleet path never falls back to an interactive wizard. It exits nonzero before runtime execution
-when:
-
- `MOSAIC_AGENT_NAME` is not an exact roster member;
- a defined ambient `MOSAIC_AGENT_CLASS` is blank/whitespace or disagrees with that member's
-  canonical class;
- a missing destination has no safe regular default source;
- a source or existing destination is a symlink (including dangling), directory, unavailable, or over the bounded size;
- the fleet communications helper/roster cannot be validated; or
- `USER.md` cannot be securely re-read at the point where its content is composed.
-
-Diagnostics begin with:
-
-```text
-[mosaic] ERROR: unattended fleet identity initialization failed: ...
-```
-
-Repair the exact named source, destination, roster, or helper and retry only that roster member. Do
-not delete or replace an existing personalized `SOUL.md`/`USER.md` merely to clear the check.
-
-## Verification without a live seat
-
-The source gate is:
-
-```bash
-pnpm --filter @mosaicstack/mosaic... build && \
-  pnpm --filter @mosaicstack/mosaic exec vitest run \
-    src/commands/launch-first-start.spec.ts
-```
-
-The build leg is load-bearing: `dist/` is ignored, so a direct Vitest invocation could otherwise run
-absent or stale CLI output. The gate runs the exact-source built CLI in subprocesses with piped stdin,
-temporary homes, a canonical fixture roster, fake runtime/broker executables, and no provider call. It
-covers no-TTY launch, exact identity,
-private modes, no-clobber, missing/symlink defaults, unknown members, blank/mismatched class,
-portable standalone composition/wizard preservation, and concurrent first start.
-
-Do not use this fixture as proof that a real provider credential is present or that a package has
-been deployed. Those require separate environment-specific evidence.
-
-## Related
-
- [User workflow](../../USER-GUIDE/workflows/fleet-unattended-first-start.md)
- [Developer architecture](../../DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md)
- [Verification report](../../reports/qa/2026-08-16-1264-unattended-first-start.md)
@@ -26,7 +26,6 @@ This book is the canonical home for architecture, package and application guides

 - [Lease-broker operations and verification](testing/lease-broker-operations.md) — safe static/test commands plus explicitly held live operations.
 - [Channel adapters](integrations/channel-adapters.md) — current shared contracts and Discord reference boundary; future adapter parity is draft.
- [Fleet first-start identity](architecture/fleet-first-start-identity.md) — no-TTY launch boundary, roster authority, and no-clobber filesystem design.

 Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.

@@ -11,7 +11,6 @@ This chapter is the canonical home for Mosaic Stack's system model, component bo
 - [`mutator-class-gate.md`](mutator-class-gate.md) — default-deny tool authorization, runtime adapters, launch choke point, and parser assurance boundary.
 - [`compaction-revocation.md`](compaction-revocation.md) — Claude/Pi observer lifecycle, runtime generations, revocation, and the bounded residual stale window.
 - [`channel-protocol.md`](channel-protocol.md) — current shared channel DTOs and Discord compatibility baseline, with unimplemented adapter work explicitly marked draft.
- [`fleet-first-start-identity.md`](fleet-first-start-identity.md) — roster-owned identity bootstrap for concurrent no-TTY fleet launches.
 - [`decisions/mos-runtime-portability-m1.md`](decisions/mos-runtime-portability-m1.md) — current logical identity, connector lease, grant, audit, and fencing decision; connector activation remains held.

 These pages are current security-contract references and are consumed by the lease-broker acceptance suites. Their live deployment gaps remain explicitly labeled in the pages; this migration does not change runtime behavior.
@@ -1,81 +0,0 @@
-# Fleet First-Start Identity Boundary
-
-> **Status:** Implemented by issue #1264. Requirements: `FCM-REQ-12`, `AC-FCM-10`.
-
-## Problem
-
-`launchRuntime()` called `checkSoul()` before runtime execution. A missing top-level `SOUL.md`
-caused `checkSoul()` to spawn a child `mosaic wizard` with inherited stdio. Under a systemd-created
-fleet pane with no TTY, that child blocked or failed before the runtime boundary even though generic
-`defaults/SOUL.md` and `defaults/USER.md` already shipped in the same `MOSAIC_HOME`.
-
-## Chosen boundary
-
-The fix remains at `checkSoul()` and does not add flags to `yolo`, fleet commands, systemd units, or
-`start-agent-session.sh`:
-
-1. A present, nonblank, whitespace-exact `MOSAIC_AGENT_NAME` selects the fleet path.
-2. `resolveFleetIdentity()` must resolve that exact member through the existing roster/helper
-   boundary, and any defined `MOSAIC_AGENT_CLASS` (including blank/whitespace) must canonicalize to
-   the roster class, before any identity seed. Only undefined means absent.
-3. `lstatSync()` preflights every destination directory entry without following links, so a dangling
-   link is rejected before its counterpart can be published.
-4. Safe bounded snapshots are read from only the missing contracts under `defaults/`.
-5. Each snapshot is written to a random owner-private temporary file in `MOSAIC_HOME`.
-6. `linkSync()` publishes the complete file without overwriting an existing path. `EEXIST` means a
-   concurrent seat or operator won; the existing path is preserved and revalidated.
-7. Temporary files are removed, and both installed contracts are re-opened through the no-symlink
-   secure-file reader before launch continues.
-8. `composeContract()` independently re-resolves the roster, securely reads fleet `USER.md` through
-   a Linux descriptor at the point of use, and injects exact member identity and communications data.
-
-A standalone launch with no `MOSAIC_AGENT_NAME` retains the portable tolerant USER read and the
-interactive wizard. Fleet-only no-follow enforcement must not make supported standalone macOS
-composition depend on Linux `/proc` descriptor traversal.
-
-## Identity and authority
-
-The copied defaults deliberately say “Mosaic agent”; they are a generic behavioral base. They are
-not the source of a fleet seat's identity. The canonical roster controls:
-
- exact agent/session name;
- canonical role/class and persona;
- peer rows and point of contact;
- tmux socket and helper target; and
- communications generation.
-
-An unknown/padded ambient name, mismatched class, or explicitly blank/whitespace class fails before
-any file is seeded. This avoids replacing the interactive wall with a fleet of indistinguishable or
-ambiently invented identities.
-
-## Concurrency and filesystem properties
-
- Sources and final destinations are bounded regular files beneath `MOSAIC_HOME`; target and dangling
-  symlinks are not followed.
- New files have mode `0600`.
- Hard-link publication is same-filesystem, atomic, and no-clobber.
- A temporary path is removed only when this process successfully created it.
- All required source snapshots are validated before the first destination is published, preventing
-  a missing second default from leaving a partial seed.
- Existing operator files are never chmodded or rewritten.
-
-## Verification
-
-`src/commands/launch-first-start.spec.ts` uses the production-kind boundary: the real built CLI in a
-no-TTY subprocess, not a direct wizard test. The package `test:vitest` gate builds Mosaic before
-Vitest, while the clean-checkout command builds its workspace dependencies first, so ignored
-`dist/cli.js` cannot be absent or stale. A fake lease launcher records whether execution reached the
-runtime boundary and captures the composed prompt.
-Positive and negative cases prove the check can both proceed and refuse. Fleet composition coverage
-replaces a previously validated `USER.md` with an external symlink and proves point-of-use refusal;
-a standalone unreadable-optional-USER case proves the portable tolerant branch remains separate.
-
-Real Pi authentication and provider task execution remain environment tests, not claims of this
-fixture.
-
-## Non-goals
-
- Runtime installation or pane-PATH resolution (#1256/#1258).
- The held `~/.mosaic` launch-composition layer in PR #1213.
- Personalizing the operator's standalone identity without a wizard.
- Changing fleet systemd or shell launcher code.
@@ -146,29 +146,6 @@ lands. M0 consists only of these normative requirements, the complete task DAG,
 documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards
 are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.

-### Unattended fleet first-start amendment (#1264)
-
-`FCM-REQ-11` is reserved by #1256's concurrent runtime-preflight delivery. This amendment therefore
-uses the next non-colliding identifiers.
-
-1. `FCM-REQ-12`: A roster-owned fleet launch SHALL NOT invoke an interactive identity wizard when
-   top-level `SOUL.md` or `USER.md` is absent. It SHALL initialize only missing top-level identity
-   contracts from the shipped generic `defaults/` contracts without overwriting operator-owned
-   bytes. The canonical roster member remains the sole source of the seat's exact name and class;
-   generic defaults grant no fleet identity or authority. Missing or unsafe defaults SHALL fail
-   closed with actionable diagnostics before runtime execution. Non-fleet launches retain the
-   interactive identity flow.
-2. `AC-FCM-10`: A systemd-equivalent no-TTY test with a clean temporary Mosaic home SHALL prove a
-   named fleet seat reaches the runtime boundary without starting `mosaic wizard`, creates
-   byte-equal owner-private `SOUL.md` and `USER.md` seeds, and receives its exact roster name/class in
-   composed context. Tests SHALL also prove no-clobber behavior, concurrent/idempotent first start,
-   fail-closed invalid defaults, and preservation of the standalone interactive path.
-
-`ASSUMPTION:` `MOSAIC_AGENT_NAME` is the existing launch discriminator for roster-owned fleet
-processes. This amendment does not add a second fleet flag because generated fleet environments
-already set that value and the runtime composer independently resolves it against the canonical
-roster before execution.
-
 ---

 ## Exact Cross-Harness Fleet Communications Contract (#766)
@@ -38,13 +38,11 @@ These paths remain canonical because current source/tests consume them or becaus
 - [Quickstart](USER-GUIDE/getting-started/quickstart.md) — installed-CLI first-use route with local PGlite safety boundaries.
 - [Web dashboard](USER-GUIDE/product/web-dashboard.md) — current routes, views, chat persistence, settings, and admin behavior.
 - [Discord conversations](USER-GUIDE/workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow.
- [Fleet unattended first start](USER-GUIDE/workflows/fleet-unattended-first-start.md) — no-TTY identity bootstrap and exact roster identity.

 ## Administrator documentation

 - [Administrator operations](ADMIN-GUIDE/operations/README.md) — current local procedures and explicitly held outlines.
 - [Upgrade safety and recovery](ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md) — installed-CLI/local-PGlite upgrade and framework recovery.
- [Fleet unattended first-start operations](ADMIN-GUIDE/operations/fleet-unattended-first-start.md) — systemd identity initialization, refusal paths, and isolated verification.
 - [Mos connector lease operations](ADMIN-GUIDE/operations/mos-connector-lease-operations.md) — held/non-operative M1 outline while policy remains deny-all.
 - [Administrator security](ADMIN-GUIDE/security/README.md) — current security chapter index.
 - [SSO providers](ADMIN-GUIDE/security/sso-providers.md) — Authentik, WorkOS, and Keycloak configuration and discovery.
@@ -58,7 +56,6 @@ These paths remain canonical because current source/tests consume them or becaus
 - [Lease-broker security](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, ancestry, filesystem, observer, and residual boundaries.
 - [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny tool authorization and launch choke point.
 - [Compaction revocation](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — lifecycle observers, generation fencing, and residual stale window.
- [Fleet first-start identity](DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md) — roster authority and atomic no-clobber identity seeding.
 - [Architecture decisions](DEVELOPER-GUIDE/architecture/decisions/README.md) — implemented and accepted boundaries.
 - [Mos runtime portability M1](DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md) — logical identity, connector lease, grants, audit, and fencing.
 - [Architecture RFCs](DEVELOPER-GUIDE/architecture/rfcs/README.md) — draft proposals without operational authority.
@@ -78,7 +75,6 @@ These paths remain canonical because current source/tests consume them or becaus
 - [Archived planning](archive/planning/README.md) — historical briefs, board reviews, and work-package specifications.
 - [Archived work records](archive/work-records/README.md) — historical task scratchpads without live consumers.
 - [P8-003 performance report](reports/qa/p8-003-performance-optimization.md) — historical implementation evidence, not a current SLO.
- [Issue #1264 unattended fleet first-start verification](reports/qa/2026-08-16-1264-unattended-first-start.md) — RED/GREEN no-TTY CLI evidence and explicit untested bounds.
 - [Plans index](plans/README.md) — approved intent and implementation/audit plans.
 - [Documentation information-architecture design](plans/2026-08-10-docs-information-architecture-design.md) — approved documentation structure decision.
 - [Documentation catalog-audit plan](plans/2026-08-10-docs-catalog-audit.md) — evidence method and migration acceptance criteria.
@@ -11,7 +11,6 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
 - [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session.
 - [Web dashboard](product/web-dashboard.md) — current routes, navigation, chat persistence, projects/tasks views, settings, and admin behavior.
 - [Discord conversations](workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow.
- [Fleet unattended first start](workflows/fleet-unattended-first-start.md) — no-TTY identity bootstrap, exact roster identity, and separate runtime prerequisites.

 ## Chapter map

@@ -19,7 +18,7 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
 | ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
 | `getting-started/` | First-use setup, orientation, and quickstarts.                | Quickstart is current; additional pages are planned. |
 | `concepts/`        | User-facing terminology, product concepts, and mental models. | Scaffold only.                                       |
-| `workflows/`       | Task-oriented procedures for using Mosaic Stack.              | Discord and fleet first-start workflows are current. |
+| `workflows/`       | Task-oriented procedures for using Mosaic Stack.              | Discord conversation workflow is current.            |
 | `product/`         | Current product surfaces and visible behavior.                | Web dashboard reference is current.                  |
 | `troubleshooting/` | User-visible failures, diagnostics, and fixes.                | Scaffold only.                                       |

@@ -28,7 +27,6 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
 - [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path.
 - [Web dashboard](product/web-dashboard.md) — verified current Next.js dashboard behavior and limitations.
 - [Discord conversations](workflows/discord-conversations.md) — verified current Discord user workflow.
- [Fleet unattended first start](workflows/fleet-unattended-first-start.md) — verified no-TTY first-start behavior and prerequisite boundaries.

 Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.

@@ -1,61 +0,0 @@
-# Fleet Unattended First Start
-
-> **Status:** Current for roster-owned local fleet launches after issue #1264 lands. Runtime
-> installation and provider authentication remain separate prerequisites.
-
-A fleet seat started by systemd has no operator at its pane. On its first launch, Mosaic must not
-stop at the interactive identity wizard.
-
-## What happens on first start
-
-When `MOSAIC_AGENT_NAME` names an exact member of the installed fleet roster and top-level identity
-contracts are absent, the launcher:
-
-1. validates the exact roster member, its canonical class, and the installed fleet communications
-   helper;
-2. reads the shipped generic contracts from
-   `~/.config/mosaic/defaults/SOUL.md` and `defaults/USER.md`;
-3. creates only the missing top-level `SOUL.md` and `USER.md` as owner-private files;
-4. preserves any existing top-level identity file byte-for-byte; and
-5. launches the runtime with the roster member's exact agent/session name and role/class in composed
-   context.
-
-The generic defaults do **not** make every seat the same identity. They provide a shared behavioral
-base. The canonical roster row supplies each seat's exact name, class, peers, socket, and authority.
-
-## Operator behavior
-
-A normal standalone launch without a fleet identity retains its portable configuration path and still
-uses the interactive wizard when `SOUL.md` is absent:
-
-```bash
-mosaic pi
-```
-
-A roster-owned seat may be started without attaching to its pane:
-
-```bash
-mosaic fleet start <exact-roster-name>
-```
-
-Mosaic refuses before runtime execution if the requested member is absent, its explicitly supplied
-ambient class is blank or conflicts with the roster, a required default is missing or unsafe, or an existing identity contract
-is not a safe regular file. Repair the named component and retry the same exact roster member; do not
-copy another seat's personalized identity.
-
-## Separate prerequisites
-
-This behavior clears the Mosaic identity-wizard wall only. A clean host still needs:
-
- the declared runtime installed on the pane PATH;
- the fleet transport and generated unit assets; and
- runtime/provider authentication appropriate to that seat.
-
-Those checks are separate so a successful identity bootstrap is not reported as a fully authenticated
-agent session.
-
-## Related
-
- [Administrator runbook](../../ADMIN-GUIDE/operations/fleet-unattended-first-start.md)
- [Developer architecture](../../DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md)
- [Verification report](../../reports/qa/2026-08-16-1264-unattended-first-start.md)
@@ -12,13 +12,11 @@ Use the canonical guide, API contract, source, and tests to determine current be
 - [Issue #756 documentation checklist](documentation/756-discord-plugin-checklist.md) — historical completion checklist for the official Discord plugin workstream.
 - [Framework consistency audit — 2026-02-17](documentation/AUDIT-2026-02-17-framework-consistency.md) — historical framework consistency and remediation snapshot.
 - [Compaction-refresh #830 checklist](compaction-refresh/830-documentation-checklist.md) — historical incomplete-at-snapshot documentation checklist.
- [Issue #1264 documentation checklist](documentation/1264-documentation-checklist.md) — current in-repo user/admin/developer/report coverage and review gate.

 ## Code-review evidence

 - [Issue #756 independent code review](code-review/756-code-review.md) — historical exact-scope review of the official Discord plugin workstream.
 - [Gateway security-hardening code review — 2026-03-13](code-review/gateway-security-20260313.md) — historical no-blocker review snapshot.
- [Issue #1264 independent code and security review](code-review/1264-code-review.md) — initial finding, remediation, clean re-review, and remaining formal PR-review gate.

 ## Security evidence

@@ -28,7 +26,6 @@ Use the canonical guide, API contract, source, and tests to determine current be

 - [P8-003 performance optimization report](qa/p8-003-performance-optimization.md) — historical implementation evidence; not a current SLO or production benchmark.
 - [Gateway security-hardening QA report — 2026-03-13](qa/gateway-security-20260313.md) — historical test report with its original live-smoke-test limitation.
- [Issue #1264 unattended fleet first-start verification](qa/2026-08-16-1264-unattended-first-start.md) — RED/GREEN no-TTY CLI evidence, baseline gates, and explicit real-provider limitation.

 ## Native Kanban/SOT evidence

@@ -1,97 +0,0 @@
-# Issue #1264 Code and Security Review
-
-> Branch: `fix/1264-fleet-unattended-first-start` | Base:
-> `origin/next@476db12b92971634b67fd2057b7577ee5894e449`
-
-## Initial automated review
-
-Codex reviewed the pre-PR uncommitted delta with:
-
-```bash
-~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted \
-  -o /tmp/1264-codex-code-review.json
-```
-
-Result: `request-changes`, confidence `0.93`, 20 files, one should-fix. `checkSoul()` trimmed
-`MOSAIC_AGENT_NAME` for pre-seed resolution while composition used the original value, so a padded
-name could seed files before later refusal.
-
-Remediation rejected blank/leading/trailing-whitespace values before roster lookup or writes and
-added three built-CLI no-side-effect regressions. Automated re-review approved that delta with no
-findings (confidence `0.86`). Initial security review reported risk `none` (confidence `0.91`).
-
-## Formal exact-head review
-
-Daphne reviewed PR #1268 at exact head `43fa0477877e0d0f110da8d11c3033b40ddeb191` and filed Gitea
-review ID 168 as `REQUEST_CHANGES`. The review was source/PR-only; the canary remained untouched.
-
-Blocking groups:
-
-1. class mismatch was validated after first-start mutation;
-2. secure `USER.md` validation was discarded before ordinary path-following composition;
-3. `existsSync()` treated a dangling destination symlink as missing, allowing counterpart partial
-   publication; and
-4. the built-CLI/evidence chain allowed stale ignored `dist/`, cited an unshipped canary object, and
-   carried conflicting test totals/pane wording.
-
-The diagnostic's defaults-only repair advice was also inaccurate for roster/class/destination
-failures.
-
-## Formal-review remediation
-
-All four blocking groups received regressions before production changes. The RED run produced four
-failures while 1,568 existing tests passed. Remediation then:
-
- validates canonical name and class before seeding;
- preflights destination directory entries with `lstatSync()` so target and dangling symlinks fail
-  before publication;
- securely reads `USER.md` through an `O_NOFOLLOW` descriptor at composition time;
- adds a Mosaic build before package Vitest and a dependency build in the clean-checkout command;
- replaces defaults-only advice with neutral named-component repair guidance; and
- reconciles shipping canary provenance, pane chronology, commands, and totals.
-
-Remediation code review:
-
-```bash
-~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted \
-  -o /tmp/1264-remediation-code-review.json
-```
-
-Result: `approve`, confidence `0.88`, 6 files, no findings. Summary: the fail-closed destination
-checks, class-validation order, secure composition, and build-before-Vitest path are coherent.
-
-Remediation security review:
-
-```bash
-~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted \
-  -o /tmp/1264-remediation-security-review.json
-```
-
-Result: risk `none`, confidence `0.93`, 9 files, no critical/high/medium/low findings. The sandbox
-could not run Vitest because Vite attempted to create a temporary config artifact on its read-only
-mount (`EROFS`); executor-owned focused and full results are recorded in the QA report.
-
-## Second exact-head review
-
-Daphne reviewed exact head `9dc90be7e13b1cd609f6df97d43d890ef5392ca0` and filed Gitea review
-ID 169 as `REQUEST_CHANGES`. Review 169 confirmed all review-168 closures, then found:
-
-1. the new point-of-use reader was Linux-only but had been applied to every standalone USER read,
-   breaking supported non-fleet macOS composition; and
-2. explicit blank/whitespace `MOSAIC_AGENT_CLASS` was treated as absent and could seed before
-   runtime, while only undefined should mean absent.
-
-Red-first remediation preserves legacy `readOptional()` for standalone composition, keeps descriptor
-no-follow consumption fleet-only, moves the replacement-symlink case under a valid fleet identity,
-and rejects defined blank/whitespace classes before seeding. Three blank-class CLI cases and one
-tolerant standalone composition case failed before the source change and pass after it.
-
-Review-169 remediation code review approved at confidence `0.90` (4 files, no findings). Security
-review reported risk `none` at confidence `0.90` (4 files, no findings). The review sandbox retained
-its known Vite `EROFS` limitation; executor-owned tests are in the QA report.
-
-## Remaining review gate
-
-Daphne must re-review the next exact pushed head. This report cannot record that future verdict
-without changing the reviewed head, so the authoritative terminal verdict belongs to PR #1268's
-Gitea review record. Fred and goals are excluded as reviewers.
@@ -1,32 +0,0 @@
-# #1264 Documentation Completion Checklist
-
-## Required artifacts
-
- [x] `docs/PRD.md` updated with `FCM-REQ-12` and `AC-FCM-10`.
- [x] User workflow documents unattended fleet first start and separate prerequisites.
- [x] Administrator operations page documents source/destination ownership, failure handling, and an
-      exact-source build-before-Vitest verification gate.
- [x] Developer architecture page documents control flow, identity authority, concurrency, and non-goals.
- [x] `docs/SITEMAP.md` and book indexes updated.
- [x] QA evidence is under `docs/reports/qa/`; working notes are under `docs/scratchpads/`.
- [x] Framework defaults README reflects fleet-versus-standalone behavior.
-
-## API coverage
-
- [x] No HTTP/API endpoint or DTO changed; OpenAPI and endpoint indexes are not applicable.
-
-## Structural standards
-
- [x] User, administrator, developer, report, and sitemap indexes link the new pages.
- [x] No noncanonical file was added at the `docs/` root.
- [x] Canonical documentation remains in-repo; no external publication was requested or performed.
-
-## Review gate
-
- [x] Initial padded-name finding remediated and automated re-review approved.
- [x] Daphne formal review ID 168 completed on exact first head `43fa0477` and requested changes.
- [x] Four review-168 groups reproduced red and remediated; automated reviews are clean.
- [x] Daphne review ID 169 completed on exact head `9dc90be7` and confirmed review-168 closures.
- [x] Review-169 standalone-portability and blank-class blockers reproduced red and remediated;
-      automated reviews are clean.
- [ ] Daphne exact-second-remediation-head re-review completed after push (Fred/goals excluded).
@@ -1,220 +0,0 @@
-# #1264 Unattended Fleet First-Start Verification
-
-> Status: **IN PROGRESS — review-169 remediation complete locally; push/re-review pending** |
-> Executor: goals | Date: 2026-08-16 | Target: isolated local fixtures only
-
-## Objective
-
-Verify that a named fleet seat launched through a systemd-equivalent, no-TTY environment on a clean
-host reaches its runtime boundary without an interactive Mosaic identity wizard. Preserve standalone
-wizard behavior and canonical-roster ownership of exact seat identity.
-
-## Source evidence accepted for local verification
-
-Daphne's canary Run-7 report is reachable from jarvis-brain `origin/main` at
-`8bf94afeb8c7d5df96cdd4a4508e75a1d2999710`,
-`docs/reports/2026-08-16_sbx-canary-greenfield-e2e.md`. The earlier local object
-`6c0b6fc70ae6a179a1b7ff9dedfc54e9adccd19a` is not reachable from an origin ref and is not used as
-shipping provenance. Run 7 measured:
-
-```text
-systemd -> start-agent-session.sh -> mosaic yolo pi (PID 3726)
-                                  -> child mosaic wizard (PID 3762)
-```
-
-The pane was preserved when Run 7 was captured. Formal review ID 168 records that an authorized
-rollback occurred later. This task never accessed or altered the canary VM, pane, snapshot, or
-rollback state. Product behavior is independently tested here with temporary roots and fake runtime
-executables.
-
-## Controls
-
- Original base: `origin/next@476db12b92971634b67fd2057b7577ee5894e449`.
- PR: #1268, first pushed head `43fa0477877e0d0f110da8d11c3033b40ddeb191`.
- `DATABASE_URL` remains unset for local tests.
- No runtime/provider credential or token value, VM, installed Mosaic tree, unit, timer, PATH profile,
-  or live tmux session is read or mutated. Standard Gitea/Woodpecker wrappers authenticate metadata
-  reads/writes without exposing credential values.
- Tiny's runtime-preflight and `start-agent-session.sh` PATH work remain out of scope.
- Held PR #1213 is not a dependency.
-
-## Requirements-to-evidence map
-
-| Acceptance criterion                                                   | Method                                                          | Evidence                      |
-| ---------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------- |
-| No-TTY fleet first start avoids wizard and reaches runtime             | Exact-source built CLI with piped stdin                         | CLI GREEN                     |
-| Missing top-level identity files are initialized from shipped defaults | Exact-byte and `0600` assertions                                | CLI + filesystem GREEN        |
-| Exact seat identity remains roster-owned                               | Captured argv; mismatched/blank class no-side-effect refusals   | CLI GREEN                     |
-| Existing operator identity is never overwritten                        | Custom bytes/mode with defaults removed                         | CLI + filesystem GREEN        |
-| Concurrent/repeated first start is safe                                | Four parallel CLIs plus repeated launch                         | CLI GREEN                     |
-| Missing/unsafe defaults and destinations fail before partial mutation  | Missing, target/dangling symlink, oversized, invalid-root cases | Filesystem/CLI GREEN          |
-| Validated `USER.md` cannot be replaced by an external symlink          | Seed, replace, compose at point of use                          | Composition GREEN             |
-| Standalone launch retains wizard                                       | Same built CLI without fleet identity                           | CLI GREEN                     |
-| Built-CLI evidence cannot use stale ignored `dist/`                    | Build-with-dependencies gate before Vitest                      | Package script + command gate |
-
-## Initial RED
-
-Production source remained unchanged after adding the first reproducer. The CLI was built from
-`origin/next@476db12` before the test.
-
-```bash
-env -u DATABASE_URL pnpm --filter @mosaicstack/mosaic exec vitest run \
-  src/commands/launch-first-start.spec.ts
-```
-
-Exit `1`; one file and one test failed. Output included:
-
-```text
-[mosaic] SOUL.md not found. Running setup wizard...
-◆  What would you like to do?
-[mosaic] Setup failed. Run: mosaic wizard
-AssertionError: expected 1 to be +0
-```
-
-The fake runtime-boundary capture was not created. Complete stdout/stderr was retained at
-`/tmp/1264-red.out` during that work session.
-
-## Formal-review remediation RED
-
-Daphne's exact-head review ID 168 requested changes at `43fa0477`. Before changing production code,
-new regressions were run against an exact-source build. Four tests failed while the existing 1,568
-passed:
-
-1. valid roster name plus mismatched ambient class seeded both files before refusal;
-2. dangling `SOUL.md` allowed `USER.md` to be published before refusal;
-3. dangling `USER.md` allowed `SOUL.md` to be published before refusal; and
-4. replacing a securely validated `USER.md` with an external symlink was followed by composition.
-
-This establishes that all four review-168 findings were observable on the pushed implementation.
-
-Daphne's review ID 169 then found two more exact-head failures at `9dc90be7`. Before production
-changes, four new assertions failed:
-
-1. standalone composition routed an unreadable optional `USER.md` through the Linux-only descriptor
-   reader instead of the legacy portable tolerant path; and
-2. explicit `MOSAIC_AGENT_CLASS` values `""`, `" "`, and tab were treated as absent, seeded both
-   identity files, and reached runtime.
-
-The replacement-symlink case was also moved under a valid roster identity so it tests the fleet-only
-security boundary rather than standalone behavior.
-
-## Final GREEN
-
-The production-kind command builds Mosaic and all workspace dependencies before invoking Vitest,
-because `dist/` is ignored and may otherwise be absent or stale:
-
-```bash
-env -u DATABASE_URL sh -c '
-  pnpm --filter @mosaicstack/mosaic... build &&
-  pnpm --filter @mosaicstack/mosaic exec vitest run \
-    src/commands/fleet-first-start-identity.spec.ts \
-    src/commands/launch-first-start.spec.ts \
-    src/commands/launch.spec.ts \
-    src/commands/compose-contract.spec.ts \
-    src/config/file-adapter.test.ts \
-    src/cli-smoke.spec.ts
-'
-```
-
-Exit `0`: `6/6` files, `128/128` tests.
-
- 15 real-CLI/no-TTY tests cover exact roster name/class, byte-equal `0600` seeds, no-clobber,
-  partial seed, missing/symlink defaults, unknown/padded/blank name, mismatched or explicitly blank
-  class, standalone wizard preservation, and four concurrent starts.
- 12 direct filesystem tests cover complete publication, existing operators, idempotence, source
-  prevalidation, target and dangling destination links, invalid roots, oversized input, and
-  unexpected link errors.
- Composition coverage deterministically replaces a valid fleet seat's validated `USER.md` with an
-  external symlink and requires refusal at point of use. A separate standalone case proves tolerant
-  optional composition remains outside the Linux-only fleet reader.
-
-Full package gate (which rebuilds Mosaic itself after the clean-checkout dependency build):
-
-```bash
-env -u DATABASE_URL pnpm --filter @mosaicstack/mosaic run test:vitest
-```
-
-Exit `0`: `88/88` files, `1,577/1,577` tests.
-
-Focused helper + point-of-use coverage:
-
-```text
-2 files, 53/53 tests
-Statements 97.84% | Branches 91.66% | Functions 100% | Lines 97.84%
-Exit 0
-```
-
-Final repository gates after remediation:
-
-```text
-pnpm preflight    exit 0
-pnpm typecheck    45/45 tasks, exit 0
-pnpm lint         25/25 tasks, exit 0
-pnpm build        25/25 tasks, exit 0
-pnpm format:check exit 0
-git diff --check  exit 0
-```
-
-Pre-PR targeted shell runs on the unchanged shell surfaces also passed:
-
-```text
-bash framework/tools/fleet/test-start-agent-session.sh                 exit 0 locally
-bash framework/tools/quality/scripts/test-install-migration.sh         21 passed, 0 failed
-bash framework/tools/_scripts/test-mosaic-init-rce.sh                   PASS
-```
-
-The aggregate local `test:framework-shell` run stopped at `invariant_r_unittest.py`: installed
-operator-global Pi is `0.84.2`, while the invariant is measured for `0.84.1`. Later aggregate stages
-remain unmeasured except the targeted suites above. Root `pnpm test` remains locally **UNTESTED**
-because this checkout prohibits the PostgreSQL-dependent gateway isolation path.
-
-## Review and security evidence
-
- Initial Codex review found padded-name mutation-before-refusal; it was fixed with three
-  no-side-effect regressions.
- Codex review of the formal-review remediation: `approve`, confidence `0.88`, 6 files, no findings.
- Codex security review of the remediation: risk `none`, confidence `0.93`, 9 files, no findings.
-  Its sandbox could not execute Vitest because Vite attempted a write on a read-only mount; the
-  executor-owned results above are the test evidence.
- Daphne formal review ID 168 at exact head `43fa0477`: `REQUEST_CHANGES`, four blocking groups; all
-  closed by review 169.
- Daphne formal review ID 169 at exact head `9dc90be7`: `REQUEST_CHANGES`, two blocking groups
-  (standalone portability and explicit blank class). Both now have red-first regressions and local
-  green remediation.
- Codex review of review-169 remediation: `approve`, confidence `0.90`, 4 files, no findings.
- Codex security review of review-169 remediation: risk `none`, confidence `0.90`, 4 files, no
-  findings. Exact-new-head Daphne re-review is pending until that head is pushed.
-
-## CI evidence and external blocker
-
-Pipeline 2445 ran against exact first head `43fa0477`:
-
- install, sanitization, upgrade guard, typecheck, lint, and format passed;
- Mosaic Vitest passed `88/88`, `1,568/1,568`; and
- the test step emitted exactly one `FAIL:` line:
-
-```text
-FAIL: host provides 'pi' in the system path; missing-binary cases are not measurable here
-```
-
-That line comes from the inherited `test-start-agent-session.sh` CI-fit guard, not #1264. Fred filed
-the correction as PR #1270. Its pipeline 2448 is terminal green and proves the four formerly masked
-suites execute, but #1270 is not merged, so `next` still carries the failing chain. A new #1268
-pipeline 2449 at `9dc90be7` reproduced the same single inherited `FAIL:` after Mosaic passed
-`1,573/1,573`. A new pipeline is pending the review-169 remediation push. Terminal-green #1268 CI is
-not claimed.
-
-PR #1268's envelope was read back as `user.login=mos-dt-0`; its commit is explicitly authored and
-committed by `goals <[email protected]>`. No goals Gitea login exists on this host, and no
-other principal was borrowed. The cross-wrapper principal defect is tracked in #1272.
-
-## Explicitly untested
-
- Canary VM remediation/restart: **UNTESTED and prohibited**.
- Real Pi authentication/provider prompt and task execution: **UNTESTED**.
- PR #1213 composition layer: **UNTESTED and not required**.
- Deployment/published npm behavior: **UNTESTED until merge/release**.
- Local PostgreSQL execution/migration: **UNTESTED and prohibited**.
-
-The local gate proves Mosaic crosses its identity boundary and reaches a fake lease-runtime boundary;
-it does not claim provider readiness, deployment, or a currently running canary seat.
@@ -1,104 +0,0 @@
-# #1264 — Unattended fleet first start
-
-## Tracking
-
- Issue: `mosaicstack/stack#1264`
- PR: `mosaicstack/stack#1268`
- Branch: `fix/1264-fleet-unattended-first-start`
- Base: `origin/next@476db12b92971634b67fd2057b7577ee5894e449`
- First pushed head: `43fa0477877e0d0f110da8d11c3033b40ddeb191`
- Current remediation worktree: `/var/home/jason.woltje/agent-work/1264-review2-remediation`
- Coordinator: Fred; reviewer must be neither Fred nor this implementation seat.
- `docs/TASKS.md` is orchestrator-owned and is not modified by this worker.
-
-The original `/var/home/jason.woltje/agent-work/1264-unattended-first-start` and first remediation
-worktrees were removed without force after each pushed head and clean state were verified. The
-Fred-authorized plain-Git worktree exception was reused for exact-head review remediation because
-`/src` remains unavailable.
-
-## Objective
-
-A roster-owned fleet seat launched from systemd on a clean host must cross Mosaic's first-run identity
-gate without a human or TTY, while retaining exact name/class from the canonical roster and
-preserving the standalone interactive wizard.
-
-## Intake and boundaries
-
- Shipping canary provenance is jarvis-brain `origin/main` commit
-  `8bf94afeb8c7d5df96cdd4a4508e75a1d2999710`. The earlier local `6c0b6fc...` object is not used.
- The Run-7 pane was preserved when evidence was captured; formal review records a later authorized
-  rollback. This task never accessed or altered the canary.
- Tiny's concurrent runtime-preflight, `start-agent-session.sh`, and #1258 PATH seam remain untouched.
- Held PR #1213 is not a dependency.
- No runtime/provider credential values or provider calls, installed-host changes, PostgreSQL, unit,
-  timer, or profile mutation. Tests use temporary roots and fake executables only; Gitea/Woodpecker
-  metadata operations use standard wrappers without exposing credentials.
-
-## Requirements and design
-
- PRD IDs: `FCM-REQ-12`, `AC-FCM-10`; `FCM-REQ-11` is reserved by #1256.
- A present fleet name must be nonblank, whitespace-exact, and resolve through the canonical roster.
- Any defined ambient class, including blank/whitespace, must canonicalize to the roster class before
-  mutation; only undefined means absent.
- Preflight all destination directory entries with no-follow existence semantics so dangling links
-  fail before counterpart publication.
- Seed only missing top-level files from bounded regular defaults with owner-private, atomic,
-  no-clobber hard links.
- Generic defaults are behavior, not identity or authority.
- Securely consume fleet `USER.md` through a Linux descriptor at composition time.
- Standalone composition retains the portable tolerant USER read and missing identity retains the
-  wizard.
-
-## Progress
-
- [x] Issue, canary report, Tiny collision state, and PRD read/amended.
- [x] Initial production-kind RED captured with a real built CLI and no TTY.
- [x] Implementation, tests, user/admin/developer docs, QA, and indexes delivered.
- [x] Initial automated review finding (padded name before write) remediated.
- [x] Commit `43fa0477` pushed; PR #1268 opened against `next`; original worktree removed cleanly.
- [x] Daphne formal review ID 168 completed on exact first head: `REQUEST_CHANGES` with four groups.
- [x] All four review-168 groups reproduced red before remediation and passed at `9dc90be7`.
- [x] Daphne review ID 169 completed on `9dc90be7`: review-168 closures confirmed; two new blockers.
- [x] Review-169 portability and blank-class blockers reproduced red and now pass locally.
- [x] Review-169 Codex review approved; security review risk `none`.
- [ ] Commit/push second remediation with explicit goals author/committer; verify remote object/content.
- [ ] Daphne exact-new-head re-review.
- [ ] Terminal #1268 CI. Pipeline 2445's only `FAIL:` was the inherited Pi-PATH CI-fit guard; PR
-  #1270's pipeline 2448 is green, but #1270 is not merged.
- [ ] Remove the clean remediation worktree after push.
-
-## Test evidence
-
-### Initial RED
-
-The built `origin/next` CLI entered `mosaic wizard`, rendered `What would you like to do?`, exited 1,
-and never created the fake runtime-boundary capture.
-
-### Formal-review RED
-
-Against exact first-head production code, four new tests failed while 1,568 existing tests passed:
-class mismatch mutated before refusal; each dangling destination left its counterpart; and a
-replacement `USER.md` symlink was consumed by composition. Review-169 RED then proved standalone
-composition hit the Linux-only reader and three explicit blank/whitespace class cases seeded and
-launched.
-
-### Final local GREEN
-
- Exact-source focused gate: `6/6` files, `128/128` tests.
- Full exact-source Mosaic Vitest: `88/88` files, `1,577/1,577` tests.
- Helper + point-of-use coverage: `53/53`; 97.84% statements/lines, 91.66% branches, 100% functions.
- Root preflight passed; typecheck `45/45`, lint `25/25`, build `25/25`.
- Initial targeted shell gates passed: start-agent-session, install migration `21/21`, init-RCE.
- Local aggregate framework shell stops at operator-global Pi `0.84.2` versus measured `0.84.1`.
- Local root `pnpm test` remains unrun because the checkout prohibits its PostgreSQL-dependent path.
-
-The full evidence and command boundaries are in
-`docs/reports/qa/2026-08-16-1264-unattended-first-start.md`.
-
-## Review / delivery notes
-
- Review-168 remediation Codex review: approve `0.88`; security risk `none` `0.93`.
- Review-169 remediation Codex review: approve `0.90`; security risk `none` `0.90`.
- PR envelope reads `mos-dt-0`; the commit reads goals/goals. No goals Gitea principal exists on this
-  host, so no other principal will be borrowed. Tracked in #1272.
- PR #1270 is pushed, not merged. Do not represent `next` or #1268 CI as green until measured.
@@ -7,10 +7,6 @@
 - [DOCS-IA-001 — information architecture](DOCS-IA-001.md) — completed structure-design and documentation-contract record.
 - [DOCS-IA-002 — catalog audit and migration](DOCS-IA-002-catalog-audit.md) — active coordinator progress, autonomous lane state, verification evidence, and authority blockers.

-## Active implementation records
-
- [Issue #1264 — unattended fleet first start](1264-unattended-first-start.md) — plan, RED/GREEN evidence, collision boundaries, and PR lifecycle state.
-
 Completed scratchpads may remain here when they provide useful delivery provenance. Their conclusions must be reflected in the owning canonical page before the scratchpad is treated as complete.

 ## Related
@@ -102,7 +102,7 @@ mosaic yolo pi             # Launch Pi in yolo mode
 The launcher:

 1. Verifies `~/.config/mosaic` exists
-2. Resolves identity: standalone launches auto-run `mosaic init` when `SOUL.md` is missing; exact roster-owned fleet launches validate name/class, atomically seed only missing `SOUL.md`/`USER.md` from generic `defaults/`, securely consume `USER.md`, and never prompt
+2. Verifies `SOUL.md` exists (auto-runs `mosaic init` if missing)
 3. Injects `AGENTS.md` into the runtime
 4. Forwards all arguments to the runtime CLI

@@ -30,7 +30,7 @@ The Gitea API token is **never passed on a curl command line.** An `Authorizatio

 ### `--login` override

-Both `pr-review.sh` and `issue-comment.sh` accept an optional `--login <name>` flag that overrides the automatically detected Gitea login for that single invocation. The override selects **which credential the REST write, the `/user` identity lookup, and the read-back all use** — its token is resolved from the tea config for that login name (`get_gitea_token_for_login`), falling back to the repo host's credential when no login is named. The resolved login is **host- and port-bound**: the login's configured URL host **and effective port** (the scheme's default port — 80 for `http`, 443 for `https` — applies when a port is omitted, symmetrically on both sides) must match the repo remote's, so a login name shared across hosts (or an override configured for a different Gitea, including one on a different port of the same host) can never send one host's credential to another — a host or port mismatch fails closed rather than leaking a cross-host token. Resolving the acting identity and the read-back from the _same_ login that performs the write is essential: a write performed under an overridden login must be verified against that login's identity, not the host default's. Callers who need a different login than the host default should pass `--login <reviewer-login>`.
+Both `pr-review.sh` and `issue-comment.sh` accept an optional `--login <name>` flag that overrides the automatically detected Gitea login for that single invocation (as of #1280, `pr-create.sh`, `pr-merge.sh` and `issue-create.sh` accept it too, and it wins over `MOSAIC_GIT_IDENTITY` everywhere). The override selects **which credential the REST write, the `/user` identity lookup, and the read-back all use** — its token is resolved from the tea config for that login name (`get_gitea_token_for_login`), falling back to the repo host's credential when no login is named. The resolved login is **host- and port-bound**: the login's configured URL host **and effective port** (the scheme's default port — 80 for `http`, 443 for `https` — applies when a port is omitted, symmetrically on both sides) must match the repo remote's, so a login name shared across hosts (or an override configured for a different Gitea, including one on a different port of the same host) can never send one host's credential to another — a host or port mismatch fails closed rather than leaking a cross-host token. Resolving the acting identity and the read-back from the _same_ login that performs the write is essential: a write performed under an overridden login must be verified against that login's identity, not the host default's. Callers who need a different login than the host default should pass `--login <reviewer-login>`.

 As a durable successor to this mechanism, consider giving each reviewer/approver slot its own dedicated Gitea login credential, so that author≠reviewer holds at the credential level rather than relying on wrapper-level `--login` bookkeeping. This is a recommendation for future hardening, not something implemented by this flag.

@@ -58,6 +58,36 @@ token file present, both tools fall through to the existing shared-account path
 unchanged, so this feature is a no-op on any host that hasn't provisioned per-slot
 tokens.

+### Identity-first principal resolution in the wrappers (#1280)
+
+`resolve_gitea_principal()` (detect-platform.sh) gives the write wrappers —
+`pr-create.sh`, `pr-merge.sh`, `pr-review.sh`, `issue-create.sh`, `issue-comment.sh` —
+ONE precedence for choosing the acting principal:
+
+1. an explicit `--login <name>` (now accepted by all five; operator intent beats
+   environment), then
+2. the per-agent identity above (`MOSAIC_GIT_IDENTITY` env / worktree
+   `mosaic.gitIdentity`) when a per-slot token exists — the wrapper then writes via the
+   REST API with that identity's token and never consults `tea`, so the tea login list
+   cannot shadow the requested principal, then
+3. the tea login list — the LAST resort, never the first, because it enumerates
+   whatever logins the host happens to hold and knows nothing about which seat is
+   calling.
+
+A requested identity whose per-slot token is absent, or a `--login` whose token cannot
+resolve host-bound, **fails loud** (nonzero, naming the identity/login and the expected
+slot) instead of silently writing under whatever account `tea` has configured — that
+silent fallthrough is defect #1280 (reviews, comments, merges, PRs and issues filed
+under the wrong account). `pr-merge.sh --dry-run` reports the principal the merge would
+act as, resolved exactly as the real merge resolves it. ⚠ A **workstation-global**
+`mosaic.gitIdentity` shadows every seat on that host (a fresh clone with no local value
+resolves the global one) — set it per-worktree, not with `--global`.
+
+The resolver is covered by `test-gitea-principal-resolution.sh`; the happy-path
+ordering (identity arm REACHED, not sitting behind a tea failure) by
+`test-pr-create-identity-first.sh`; merge credential binding by
+`test-pr-merge-principal-resolution.sh`.
+
 ### Enabling it for a clone

 The framework installer syncs `git-credential-mosaic` to
@@ -497,6 +497,32 @@ get_gitea_url_for_host() {
    return 1
 }

+# Map a Gitea host to the per-agent identity-token slot PREFIX ("gitea-usc" /
+# "gitea-mosaicstack") used by identity-first principal resolution
+# (MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity; #1280). Returns 1 for
+# hosts with no per-slot scheme — callers treat that as "identity does not
+# bind here" and fall through to existing behavior, never as an error. This is
+# the single source of truth for the slot layout: get_gitea_token and
+# resolve_gitea_principal both derive their slot paths from here, so the two
+# resolutions can never disagree about where an identity's credential lives.
+gitea_identity_slot_prefix() {
+    case "$1" in
+        git.uscllc.com)      echo "gitea-usc" ;;
+        git.mosaicstack.dev) echo "gitea-mosaicstack" ;;
+        *) return 1 ;;
+    esac
+}
+
+# Resolve the per-slot token FILE PATH for an identity on a host. Prints the
+# absolute path on success; returns 1 (no output) when the host has no per-slot
+# scheme. Prints a PATH only — never a token value.
+gitea_identity_token_slot() {
+    local identity="$1" host="$2" prefix
+    [[ -n "$identity" ]] || return 1
+    prefix=$(gitea_identity_slot_prefix "$host") || return 1
+    printf '%s\n' "$HOME/.config/mosaic/secrets/gitea-tokens/${prefix}-${identity}.token"
+}
+
 # Resolve a Gitea API token for the given host.
 # Priority: Mosaic credential loader → GITEA_TOKEN env → ~/.git-credentials
 get_gitea_token() {
@@ -517,13 +543,8 @@ get_gitea_token() {
        _ident_src="git config mosaic.gitIdentity"
    fi
    if [[ -n "$_ident" ]]; then
-        local _idpfx=""
-        case "$host" in
-            git.uscllc.com)      _idpfx=gitea-usc ;;
-            git.mosaicstack.dev) _idpfx=gitea-mosaicstack ;;
-        esac
-        if [[ -n "$_idpfx" ]]; then
-            local _idtok="$HOME/.config/mosaic/secrets/gitea-tokens/${_idpfx}-${_ident}.token"
+        local _idtok=""
+        if _idtok="$(gitea_identity_token_slot "$_ident" "$host" 2>/dev/null)"; then
            if [[ -r "$_idtok" ]]; then
                cat "$_idtok"
                return 0
@@ -1465,6 +1486,81 @@ raise SystemExit(1)
 PY
 }

+# resolve_gitea_principal — identity-first acting-principal resolution shared by
+# the git wrappers (#1280). The defect this fixes: wrappers resolved their
+# acting principal from tea's login list FIRST, and that list enumerates
+# whatever logins happen to be configured on the host — it knows nothing about
+# which seat is calling — so a wrapper invoked with MOSAIC_GIT_IDENTITY=fargo
+# still wrote under whichever account tea held (mos-dt-0), and the correct
+# identity-aware code sat behind arms that only ran when the tea path failed.
+# Precedence here is the contract:
+#   1. an explicit login override ($1, the wrapper's --login) — operator intent
+#      beats environment;
+#   2. MOSAIC_GIT_IDENTITY env, else per-worktree `git config mosaic.gitIdentity`
+#      (mirroring get_gitea_token exactly, so resolver and token resolution can
+#      never disagree) — binds only on hosts with a per-slot token scheme;
+#   3. the tea login list — LAST resort, never the first.
+#
+# Prints exactly one line, three tab-separated fields (machine-readable for
+# wrapper dispatch and tests):
+#   mode        "login" | "identity" | "default"
+#   principal   login name (login) | identity name (identity) | tea login or "" (default)
+#   source      "tea-login:<name>" | "identity-slot:<path>" | "tea-default" | "host-credential"
+#
+# Fails LOUD (nonzero, empty stdout, stderr diagnostic) when an explicit
+# override cannot be honored — a refusal is a good day; silently falling
+# through to whoever tea has configured is the exact defect this resolves:
+#   - login mode: no host-bound token for that tea login. The existence check
+#     runs the same tea-config lookup tea itself uses; the token VALUE is
+#     discarded (never printed, never used).
+#   - identity mode: no per-slot token file for that identity on a recognized
+#     host — the diagnostic names the identity, its source, and the expected
+#     slot path. An identity requested on a host with NO per-slot scheme does
+#     not bind (matching get_gitea_token's containment) and falls to default.
+#
+# NEVER prints a token value — principal names and slot paths only.
+# $1 = explicit login override ("" when absent), $2 = host (default: the
+# origin remote's host).
+resolve_gitea_principal() {
+    local login_override="${1:-}" host="${2:-}" ident ident_src slot login
+    [[ -n "$host" ]] || { host=$(get_remote_host) || return 1; }
+
+    if [[ -n "$login_override" ]]; then
+        get_gitea_token_for_login "$login_override" "$host" >/dev/null || {
+            echo "Error: --login '$login_override' has no host-matched token on host '$host' (tea config lookup); refusing to fall back to any other principal (#1280 identity-first resolution)." >&2
+            return 1
+        }
+        printf 'login\t%s\ttea-login:%s\n' "$login_override" "$login_override"
+        return 0
+    fi
+
+    ident="${MOSAIC_GIT_IDENTITY:-}"
+    ident_src="MOSAIC_GIT_IDENTITY"
+    if [[ -z "$ident" ]]; then
+        ident="$(git config --get mosaic.gitIdentity 2>/dev/null || true)"
+        ident_src="git config mosaic.gitIdentity"
+    fi
+    if [[ -n "$ident" ]] && slot="$(gitea_identity_token_slot "$ident" "$host" 2>/dev/null)"; then
+        if [[ -r "$slot" ]]; then
+            printf 'identity\t%s\tidentity-slot:%s\n' "$ident" "$slot"
+            return 0
+        fi
+        echo "Error: git identity '$ident' requested (via $ident_src) for host '$host', but no per-slot token at $slot (#1280 identity-first resolution)." >&2
+        echo "       Refusing to fall back to the tea login list or shared credentials. Provision the per-slot token, or unset the identity." >&2
+        return 1
+    fi
+
+    # No override requested: tea's login list is the LAST resort. Absence is
+    # not an error here — callers fall back to the host credential, exactly as
+    # they did before this resolver existed (preserved behavior).
+    if login=$(get_gitea_login_for_host "$host" 2>/dev/null); then
+        printf 'default\t%s\ttea-default\n' "$login"
+    else
+        printf 'default\t\thost-credential\n'
+    fi
+    return 0
+}
+
 # Resolve HTTPS basic auth credentials for a Gitea host from ~/.git-credentials.
 # Prints "username:password" for direct curl -u consumption. Callers must not log it.
 get_gitea_basic_auth() {
@@ -76,27 +76,36 @@ fi
 detect_platform >/dev/null

 # Resolve and cache the Gitea REST endpoint + token for the current remote,
-# bound to a SPECIFIC login identity ($1). Populates GITEA_API_ROOT (…/api/v1),
-# GITEA_API_BASE (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
+# bound to a SPECIFIC acting principal ($1) selected identity-first (#1280):
+# an explicit --login wins, else MOSAIC_GIT_IDENTITY / git config
+# mosaic.gitIdentity binds the per-slot credential, else the tea login list
+# (last resort). Populates GITEA_API_ROOT (…/api/v1), GITEA_API_BASE
+# (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
 #
-# The token is resolved for the EFFECTIVE login (the --login override when
-# given, otherwise the detected default) so that the single credential used for
-# the write ALSO drives the /user identity read and the read-back — write token
-# and read-back token are the same identity by construction (this is the
-# credential-ordering fix: a --login override is no longer written under one
-# credential and verified under a different default one). Falls back to the
-# host-scoped credential ONLY when NO --login override was supplied (the
-# best-effort default path). When $2 is "explicit" the login came from a
-# caller-supplied --login: that exact login's token MUST resolve, and we FAIL
-# CLOSED rather than silently downgrading the write to the host default
-# identity — otherwise a caller relying on a dedicated per-role credential would
-# be told the write succeeded as requested while it was attributed to the shared
-# default. Returns non-zero (clear stderr) on any resolution failure.
+# The token is resolved for the EFFECTIVE principal so that the single
+# credential used for the write ALSO drives the /user identity read and the
+# read-back — write token and read-back token are the same identity by
+# construction (this is the credential-ordering fix: a --login override is no
+# longer written under one credential and verified under a different default
+# one). When $2 is "identity" the principal ($1) is a requested git identity:
+# the token MUST resolve from that identity's per-slot token (get_gitea_token's
+# identity arm), failing closed rather than borrowing the tea default login —
+# the tea login list must never shadow a requested identity (#1280). When $2
+# is "explicit" the principal came from a caller-supplied --login: that exact
+# login's token MUST resolve, and we FAIL CLOSED rather than silently
+# downgrading the write to the host default identity. Otherwise the best-effort
+# default path applies (per-login token, else the host-scoped credential).
+# Returns non-zero (clear stderr) on any resolution failure.
 gitea_resolve_api_for_login() {
    local effective_login="$1" override_explicit="${2:-}" host configured_url repo

    host=$(get_remote_host)
-    if [[ -n "$override_explicit" ]]; then
+    if [[ "$override_explicit" == "identity" ]]; then
+        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+            echo "Error: could not resolve the per-slot token for requested git identity '$effective_login' on host '$host'; refusing to fall back to the tea login list or shared credentials (comment write/read-back, #1280)." >&2
+            return 1
+        }
+    elif [[ -n "$override_explicit" ]]; then
        GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
            echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (comment write/read-back)" >&2
            return 1
@@ -318,23 +327,31 @@ if [[ "$PLATFORM" == "github" ]]; then
    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
    echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    # Resolve the login this comment should be attributed to: the --login
-    # override when given, otherwise the detected default for this repo's host.
-    # A --login override always wins. Otherwise name this repo host's login only
-    # as a best effort: the login name merely selects a per-login token, and
-    # gitea_resolve_api_for_login falls back to the host credential
-    # (get_gitea_token) when no tea login is named, so the default credential
-    # still resolves even when the host tea has no matching login entry.
-    EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
-    [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login 2>/dev/null || true)
+    # Resolve the acting principal identity-first (#1280): an explicit --login
+    # wins; otherwise MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
+    # selects the principal when a per-slot token exists (fail-loud when it
+    # does not); the tea login list is the LAST resort — it knows nothing about
+    # which seat is calling, so resolving from it first wrote under whichever
+    # account tea had configured (the #1280 family).
+    principal_host=$(get_remote_host)
+    if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$principal_host")"; then
+        # resolve_gitea_principal already printed the fail-loud diagnostic.
+        exit 1
+    fi
+    PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
+    PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"

-    # Bind the REST endpoint + token to the effective login, then derive the
+    # Bind the REST endpoint + token to the resolved principal, then derive the
    # acting identity from that SAME credential (GET /user). The write below and
    # its read-back both use this credential, so the write is verified against
-    # the identity that actually performed it. Passing "explicit" when --login
-    # was supplied forbids the host-default fallback: an unresolvable explicit
-    # override fails closed instead of writing under the default identity.
-    gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
+    # the identity that actually performed it.
+    if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+        gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+    elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+        gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+    else
+        gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+    fi
    ACTING_LOGIN=$(gitea_authenticated_login) || exit 1

    comment_id=$(gitea_create_comment_verified "$ISSUE_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {
@@ -1,6 +1,15 @@
 #!/bin/bash
 # issue-create.sh - Create issues on Gitea or GitHub
-# Usage: issue-create.sh -t "Title" [-b "Body"] [-l "label1,label2"] [-m "milestone"]
+# Usage: issue-create.sh -t "Title" [-b "Body"] [-l "label1,label2"] [-m "milestone"] [--login <name>]
+#
+# Acting principal is resolved identity-first (#1280): an explicit --login
+# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
+# mosaic.gitIdentity selects the principal when a per-slot token exists (and
+# the wrapper then creates the issue through the REST API with that identity's
+# token — tea is never invoked, so the tea login list cannot shadow the
+# requested principal); the tea login list is the LAST resort. A requested
+# identity with no per-slot token fails LOUD rather than writing under
+# whichever account tea happens to hold.

 set -e

@@ -16,6 +25,14 @@ INTERACTIVE=false

 # get_remote_host and get_gitea_token are provided by detect-platform.sh

+# Acting-principal mode set in the Gitea branch below (from
+# resolve_gitea_principal): "login" when --login was given, "identity" when a
+# git identity bound, "default" otherwise. PRINCIPAL_MODE=login makes the API
+# arm resolve the --login principal's token too, so an explicit --login keeps
+# winning even on the tea-FAILURE fallback arm.
+PRINCIPAL_MODE=""
+PRINCIPAL_NAME=""
+
 gitea_issue_create_api() {
    local host repo token url payload
    host=$(get_remote_host) || {
@@ -26,10 +43,19 @@ gitea_issue_create_api() {
        echo "Error: could not determine repo owner/name for API fallback" >&2
        return 1
    }
-    token=$(get_gitea_token "$host") || {
-        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-        return 1
-    }
+    if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+        token=$(get_gitea_token_for_login "$PRINCIPAL_NAME" "$host") || {
+            echo "Error: could not resolve a host-matched Gitea token for --login '$PRINCIPAL_NAME' on host '$host' (API path)" >&2
+            return 1
+        }
+    else
+        # Identity-first when MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
+        # is set (per-slot token, fail-loud on absence); shared default otherwise.
+        token=$(get_gitea_token "$host") || {
+            echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
+            return 1
+        }
+    fi

    if [[ -n "$LABELS" || -n "$MILESTONE" ]]; then
        echo "Warning: API fallback currently applies title/body only; labels/milestone require authenticated tea setup." >&2
@@ -67,6 +93,7 @@ Options:
    -b, --body BODY         Issue body/description
    -l, --labels LABELS     Comma-separated labels (e.g., "bug,feature")
    -m, --milestone NAME    Milestone name to assign
+        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
    -i, --interactive       Prompt for missing issue fields
    -h, --help              Show this help message

@@ -97,6 +124,10 @@ while [[ $# -gt 0 ]]; do
            MILESTONE="$2"
            shift 2
            ;;
+        --login)
+            LOGIN_OVERRIDE="$2"
+            shift 2
+            ;;
        -i|--interactive)
            INTERACTIVE=true
            shift
@@ -134,13 +165,37 @@ case "$PLATFORM" in
        "${CMD[@]}"
        ;;
    gitea)
+        # Resolve the acting principal identity-first (#1280). The tea login
+        # list is the LAST resort: it knows nothing about which seat is calling,
+        # and a login resolved from it first is what attributed issues to the
+        # wrong account even when MOSAIC_GIT_IDENTITY was set.
+        principal_host=$(get_remote_host 2>/dev/null || true)
+        if ! principal_resolved="$(resolve_gitea_principal "${LOGIN_OVERRIDE:-}" "$principal_host")"; then
+            # resolve_gitea_principal already printed the fail-loud diagnostic.
+            exit 1
+        fi
+        PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
+        PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
+
+        if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+            # HAPPY PATH for a requested identity: create through the REST API
+            # with the per-slot token and never invoke tea — the identity arm
+            # must be REACHED, not sit behind a tea failure (#1280).
+            gitea_issue_create_api
+            exit $?
+        fi
+
        if command -v tea >/dev/null 2>&1; then
            REPO_SLUG=$(get_repo_slug)
-            GITEA_LOGIN_NAME=$(get_gitea_login) || {
-                echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
-                gitea_issue_create_api
-                exit $?
-            }
+            if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+                GITEA_LOGIN_NAME="$PRINCIPAL_NAME"
+            else
+                GITEA_LOGIN_NAME=$(get_gitea_login) || {
+                    echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
+                    gitea_issue_create_api
+                    exit $?
+                }
+            fi
            if ! get_gitea_authenticated_user "$GITEA_LOGIN_NAME" >/dev/null; then
                echo "Warning: Tea authenticated-user validation failed (possible stale user/login); trying Gitea API fallback..." >&2
                gitea_issue_create_api
@@ -1,6 +1,15 @@
 #!/bin/bash
 # pr-create.sh - Create pull requests on Gitea or GitHub
-# Usage: pr-create.sh -t "Title" [-b "Body"] [-B base] [-H head] [-l "labels"] [-m "milestone"]
+# Usage: pr-create.sh -t "Title" [-b "Body"] [-B base] [-H head] [-l "labels"] [-m "milestone"] [--login <name>]
+#
+# Acting principal is resolved identity-first (#1280): an explicit --login
+# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
+# mosaic.gitIdentity selects the principal when a per-slot token exists (and
+# the wrapper then creates the PR through the REST API with that identity's
+# token — tea is never invoked, so the tea login list cannot shadow the
+# requested principal); the tea login list is the LAST resort. A requested
+# identity with no per-slot token fails LOUD rather than writing under
+# whichever account tea happens to hold.

 set -e

@@ -19,6 +28,15 @@ ISSUE=""

 # get_remote_host, get_gitea_token, get_repo_info, and get_gitea_repo_args are provided by detect-platform.sh

+# Acting-principal mode set in the Gitea branch below (from
+# resolve_gitea_principal): "login" when --login was given, "identity" when a
+# git identity bound, "default" otherwise. PRINCIPAL_MODE=login makes the API
+# arm resolve the --login principal's token too, so an explicit --login keeps
+# winning even on the tea-FAILURE fallback arm (otherwise the fallback would
+# silently re-resolve to the environment identity or shared credential).
+PRINCIPAL_MODE=""
+PRINCIPAL_NAME=""
+
 gitea_pr_create_api() {
    local host repo token url payload
    host=$(get_remote_host) || {
@@ -29,10 +47,19 @@ gitea_pr_create_api() {
        echo "Error: could not determine repo owner/name for API fallback" >&2
        return 1
    }
-    token=$(get_gitea_token "$host") || {
-        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-        return 1
-    }
+    if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+        token=$(get_gitea_token_for_login "$PRINCIPAL_NAME" "$host") || {
+            echo "Error: could not resolve a host-matched Gitea token for --login '$PRINCIPAL_NAME' on host '$host' (API path)" >&2
+            return 1
+        }
+    else
+        # Identity-first when MOSAIC_GIT_IDENTITY / git config mosaic.gitIdentity
+        # is set (per-slot token, fail-loud on absence); shared default otherwise.
+        token=$(get_gitea_token "$host") || {
+            echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
+            return 1
+        }
+    fi

    if [[ -n "$LABELS" || -n "$MILESTONE" || "$DRAFT" == true ]]; then
        echo "Warning: API fallback applies title/body/head/base only; labels/milestone/draft require authenticated tea setup." >&2
@@ -76,6 +103,7 @@ Options:
    -H, --head BRANCH       Head branch with changes (default: current branch)
    -l, --labels LABELS     Comma-separated labels
    -m, --milestone NAME    Milestone name
+        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
    -i, --issue NUMBER      Link to issue (auto-generates title if not provided)
    -d, --draft             Create as draft PR
    -h, --help              Show this help message
@@ -116,6 +144,10 @@ while [[ $# -gt 0 ]]; do
            MILESTONE="$2"
            shift 2
            ;;
+        --login)
+            LOGIN_OVERRIDE="$2"
+            shift 2
+            ;;
        -i|--issue)
            ISSUE="$2"
            shift 2
@@ -174,15 +206,41 @@ case "$PLATFORM" in
        "${CMD[@]}"
        ;;
    gitea)
+        # Resolve the acting principal identity-first (#1280). The tea login
+        # list is the LAST resort: it knows nothing about which seat is calling,
+        # and a login resolved from it first is what attributed PRs to the wrong
+        # account even when MOSAIC_GIT_IDENTITY was set.
+        principal_host=$(get_remote_host 2>/dev/null || true)
+        if ! principal_resolved="$(resolve_gitea_principal "${LOGIN_OVERRIDE:-}" "$principal_host")"; then
+            # resolve_gitea_principal already printed the fail-loud diagnostic.
+            exit 1
+        fi
+        PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
+        PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
+
+        if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+            # HAPPY PATH for a requested identity: the per-slot token IS the
+            # credential, so create through the REST API directly and never
+            # invoke tea — the identity arm must be REACHED, not sit behind a
+            # tea failure (#1280). Fail-loud on a missing slot already happened
+            # in resolve_gitea_principal.
+            gitea_pr_create_api
+            exit $?
+        fi
+
        # tea pull create syntax. Always pass --repo because tea repo inference
        # is unreliable in Mosaic worktrees/profile shells. Use arrays instead
        # of eval so markdown backticks/body content are not shell-executed.
        REPO_SLUG=$(get_repo_slug)
-        GITEA_LOGIN_NAME=$(get_gitea_login) || {
-            echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
-            gitea_pr_create_api
-            exit $?
-        }
+        if [[ "$PRINCIPAL_MODE" == "login" ]]; then
+            GITEA_LOGIN_NAME="$PRINCIPAL_NAME"
+        else
+            GITEA_LOGIN_NAME=$(get_gitea_login) || {
+                echo "Warning: could not resolve Gitea login for tea; trying Gitea API fallback..." >&2
+                gitea_pr_create_api
+                exit $?
+            }
+        fi
        if ! get_gitea_authenticated_user "$GITEA_LOGIN_NAME" >/dev/null; then
            echo "Warning: Tea authenticated-user validation failed (possible stale user/login); trying Gitea API fallback..." >&2
            gitea_pr_create_api
@@ -1,6 +1,13 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL] [--login <name>]
+#
+# Acting principal is resolved identity-first (#1280): an explicit --login
+# wins; otherwise MOSAIC_GIT_IDENTITY / per-worktree git config
+# mosaic.gitIdentity selects the credential (per-slot token, fail-loud when
+# absent); the shared host credential is the last resort. The merge is
+# performed with the resolved credential only — never a cross-principal
+# fallback (an HTTP 401 from the identity-bound token is a hard stop).

 set -euo pipefail

@@ -16,6 +23,7 @@ DRY_RUN=false
 EXPECT_HEAD=""
 CO_AUTHOR_TRAILERS=false
 ESCALATE_TO=""
+LOGIN_OVERRIDE=""

 usage() {
    cat <<EOF
@@ -31,6 +39,7 @@ Options:
        --expect-head SHA   Refuse unless the PR head matches this full commit SHA
        --co-author-trailers Build verified trailers from linked PR commit authors
        --escalate-to NAME  Named principal for an unresolved-author BLOCK
+        --login NAME        Act as this Gitea tea login (wins over MOSAIC_GIT_IDENTITY)
    -h, --help              Show this help message

 Examples:
@@ -39,6 +48,7 @@ Examples:
    $(basename "$0") -n 42 -d                 # Squash merge and delete branch
    $(basename "$0") -n 42 --expect-head 0123456789abcdef0123456789abcdef01234567
    $(basename "$0") -n 42 --co-author-trailers --escalate-to tl-mosaic
+    $(basename "$0") -n 42 --login fred-ms    # Merge under the fred-ms tea login
 EOF
    exit "${1:-1}"
 }
@@ -82,6 +92,14 @@ while [[ $# -gt 0 ]]; do
            ESCALATE_TO="$2"
            shift 2
            ;;
+        --login|-l)
+            if [[ $# -lt 2 ]]; then
+                echo "Error: --login requires one tea login name." >&2
+                exit 1
+            fi
+            LOGIN_OVERRIDE="$2"
+            shift 2
+            ;;
        -h|--help)
            usage 0
            ;;
@@ -572,9 +590,22 @@ PY
 merge_gitea_with_api() {
    local host="$1" token attempt_rc

-    if ! token=$(get_gitea_token "$host"); then
-        echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
-        return 1
+    # Identity-first principal resolution (#1280): an explicit --login wins
+    # over MOSAIC_GIT_IDENTITY (operator intent beats environment); otherwise
+    # get_gitea_token resolves the identity's per-slot token when an identity
+    # is requested (fail-loud when absent) and the shared host credential only
+    # when no identity is set. No cross-principal fallback: whatever resolves
+    # here is the ONLY credential the merge is attempted with.
+    if [[ -n "$LOGIN_OVERRIDE" ]]; then
+        if ! token=$(get_gitea_token_for_login "$LOGIN_OVERRIDE" "$host"); then
+            echo "Error: --login '$LOGIN_OVERRIDE' has no host-matched token on host '$host'; refusing to merge under any other principal (#1280 identity-first resolution)." >&2
+            return 1
+        fi
+    else
+        if ! token=$(get_gitea_token "$host"); then
+            echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
+            return 1
+        fi
    fi
    if [[ -z "$token" ]]; then
        echo "Error: Required Gitea token resolved empty; refusing merge without changing principals." >&2
@@ -602,10 +633,25 @@ if [[ "$DRY_RUN" == true ]]; then
            echo "Error: Cannot determine host from origin remote URL" >&2
            exit 1
        }
+        # Report the acting principal the merge WOULD use, resolved the same
+        # way the real merge resolves it (#1280) — a dry run that names a
+        # different principal than the merge would act as is a lie.
+        if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$HOST")"; then
+            # Fail-loud diagnostic already printed (unresolvable --login or a
+            # requested identity with no per-slot token).
+            exit 1
+        fi
+        DRY_PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
+        DRY_PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
+        case "$DRY_PRINCIPAL_MODE" in
+            login)    DRY_PRINCIPAL_DESC="tea login '$DRY_PRINCIPAL_NAME'" ;;
+            identity) DRY_PRINCIPAL_DESC="git identity '$DRY_PRINCIPAL_NAME' (per-slot credential)" ;;
+            *)        DRY_PRINCIPAL_DESC="default host credential" ;;
+        esac
        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST as $DRY_PRINCIPAL_DESC with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
        else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST as $DRY_PRINCIPAL_DESC with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
        fi
    else
        echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."
@@ -76,7 +76,7 @@ while [[ $# -gt 0 ]]; do
            echo "  -n, --number   PR number (required)"
            echo "  -a, --action   Review action: approve, request-changes, comment (required)"
            echo "  -c, --comment  Review comment (required for request-changes)"
-            echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
+            echo "  -l, --login    Override the detected Gitea tea login (all actions; wins over MOSAIC_GIT_IDENTITY)"
            echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
            echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
            echo "  -h, --help     Show this help"
@@ -346,7 +346,14 @@ gitea_resolve_api_for_login() {
    else
        host=$(get_remote_host)
    fi
-    if [[ -n "$override_explicit" ]]; then
+    if [[ "$override_explicit" == "identity" ]]; then
+        # Requested git identity (#1280): the per-slot token MUST resolve via
+        # get_gitea_token's identity arm; never borrow the tea default login.
+        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+            echo "Error: could not resolve the per-slot token for requested git identity '$effective_login' on host '$host'; refusing to fall back to the tea login list or shared credentials (review write/read-back, #1280)." >&2
+            return 1
+        }
+    elif [[ -n "$override_explicit" ]]; then
        GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
            echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (review write/read-back)" >&2
            return 1
@@ -676,29 +683,32 @@ if [[ "$PLATFORM" == "github" ]]; then
            ;;
    esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
+    # Resolve the acting principal ONCE for every action, identity-first
+    # (#1280): an explicit --login wins; otherwise MOSAIC_GIT_IDENTITY /
+    # per-worktree git config mosaic.gitIdentity selects the principal when a
+    # per-slot token exists (fail-loud when it does not); the tea login list is
+    # the LAST resort — it enumerates whatever logins this host happens to hold
+    # and knows nothing about which seat is calling, so resolving from it first
+    # wrote under whichever account tea had configured (the #1280 family).
+    principal_host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
+    if ! principal_resolved="$(resolve_gitea_principal "$LOGIN_OVERRIDE" "$principal_host")"; then
+        # resolve_gitea_principal already printed the fail-loud diagnostic.
+        exit 1
+    fi
+    PRINCIPAL_MODE="$(printf '%s' "$principal_resolved" | cut -f1)"
+    PRINCIPAL_NAME="$(printf '%s' "$principal_resolved" | cut -f2)"
    case $ACTION in
        approve)
-            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
-            # below re-derives the real host from HOST_OVERRIDE/remote independently and
-            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
-            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
-            # under `set -e`, with no origin and no -H, previously killed the script
-            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
-            # that support running with no usable origin at all).
-            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-            # A --login override always wins. Otherwise name this host's login
-            # only as a best effort: the login name merely selects a per-login
-            # token, and gitea_resolve_api_for_login falls back to the host
-            # credential (get_gitea_token) when no tea login is named — so a host
-            # tea's login list need not enumerate exotic (e.g. ported) hosts for
-            # the default credential to resolve. The single resolved token is
-            # then used for the write, the /user identity, and the read-back.
-            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
-            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
-            # Bind the REST endpoint + token to the effective login, then derive
-            # the acting identity from that SAME credential so the review submit
-            # and its read-back verify against the identity that performed them.
-            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
+            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
+            # PRINCIPAL_NAME were resolved once above from --login >
+            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
+            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+            else
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+            fi
            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
            head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
            # The review body (if any) travels with the review itself in the REST
@@ -715,24 +725,16 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                echo "Error: Comment required for request-changes"
                exit 1
            fi
-            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
-            # below re-derives the real host from HOST_OVERRIDE/remote independently and
-            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
-            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
-            # under `set -e`, with no origin and no -H, previously killed the script
-            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
-            # that support running with no usable origin at all).
-            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-            # A --login override always wins. Otherwise name this host's login
-            # only as a best effort: the login name merely selects a per-login
-            # token, and gitea_resolve_api_for_login falls back to the host
-            # credential (get_gitea_token) when no tea login is named — so a host
-            # tea's login list need not enumerate exotic (e.g. ported) hosts for
-            # the default credential to resolve. The single resolved token is
-            # then used for the write, the /user identity, and the read-back.
-            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
-            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
-            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
+            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
+            # PRINCIPAL_NAME were resolved once above from --login >
+            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
+            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+            else
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+            fi
            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
            head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
            review_id=$(gitea_submit_review_verified "$PR_NUMBER" "REQUEST_CHANGES" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
@@ -746,24 +748,16 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                echo "Error: Comment required"
                exit 1
            fi
-            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
-            # below re-derives the real host from HOST_OVERRIDE/remote independently and
-            # is authoritative). Prefer an explicit -H/--host; otherwise best-effort
-            # git-remote inference, tolerating its ABSENCE (a bare `get_remote_host` here
-            # under `set -e`, with no origin and no -H, previously killed the script
-            # SILENTLY — exit 1, zero output — even though -r/-H are exactly the flags
-            # that support running with no usable origin at all).
-            host="${HOST_OVERRIDE:-$(get_remote_host 2>/dev/null || true)}"
-            # A --login override always wins. Otherwise name this host's login
-            # only as a best effort: the login name merely selects a per-login
-            # token, and gitea_resolve_api_for_login falls back to the host
-            # credential (get_gitea_token) when no tea login is named — so a host
-            # tea's login list need not enumerate exotic (e.g. ported) hosts for
-            # the default credential to resolve. The single resolved token is
-            # then used for the write, the /user identity, and the read-back.
-            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
-            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
-            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" "${LOGIN_OVERRIDE:+explicit}" || exit 1
+            # Identity-first principal resolution (#1280): PRINCIPAL_MODE /
+            # PRINCIPAL_NAME were resolved once above from --login >
+            # MOSAIC_GIT_IDENTITY / git config > tea login list (last resort).
+            if [[ "$PRINCIPAL_MODE" == "identity" ]]; then
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" identity || exit 1
+            elif [[ "$PRINCIPAL_MODE" == "login" ]]; then
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" explicit || exit 1
+            else
+                gitea_resolve_api_for_login "$PRINCIPAL_NAME" "" || exit 1
+            fi
            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
            comment_id=$(gitea_create_comment_verified "$PR_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {
                echo "Error: could not create and verify a comment on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# Regression harness for detect-platform.sh's resolve_gitea_principal() — the
+# identity-first acting-principal resolution shared by the git wrappers
+# (mosaicstack/stack #1280).
+#
+# The contract under test (precedence: --login > MOSAIC_GIT_IDENTITY /
+# git config mosaic.gitIdentity > tea login list, which is the LAST resort):
+#   1. identity env + per-slot token present -> mode=identity, principal=
+#      identity name, source names the identity's slot PATH (never a token
+#      value).
+#   2. identity env + per-slot token ABSENT -> FAIL LOUD: nonzero, empty
+#      stdout, stderr naming the identity and the expected slot path.
+#   3. identity env + --login -> --login wins (login mode resolves even when
+#      the identity has no slot — operator intent beats environment).
+#   4. identity unset + no --login -> default mode: the tea login list
+#      resolves the principal exactly as before (preserved behavior).
+#   5. no identity + no host-matching tea login -> default/host-credential
+#      (preserved behavior; absence is not an error on the default path).
+#   6. identity on an UNRECOGNIZED host (no per-slot scheme) -> does not bind;
+#      default mode (containment, mirroring get_gitea_token).
+#   7. --login with no host-bound token for that login -> FAIL LOUD, stderr
+#      naming the login and the host.
+#   8. git config mosaic.gitIdentity is honored when the env var is unset.
+#   9. The resolver NEVER emits a token value — stdout/stderr of every
+#      successful resolution must not contain the slot file's contents.
+#
+# Uses a stubbed tea binary, stubbed tea config.yml, stubbed credentials.json
+# and stubbed per-slot token files under a fake HOME. NEVER reads real secrets.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/gitea-principal-resolution}"
+FAKE_HOME="$WORK_DIR/home"
+REPO_DIR="$WORK_DIR/repo"
+BIN_DIR="$WORK_DIR/bin"
+CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" "$REPO_DIR" "$BIN_DIR"
+
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
+
+cat > "$CREDENTIALS_FILE" <<'JSON'
+{
+  "gitea": {
+    "mosaicstack": {
+      "url": "https://git.mosaicstack.dev",
+      "token": "shared-mosaicstack-token"
+    },
+    "usc": {
+      "url": "https://git.uscllc.com",
+      "token": "shared-usc-token"
+    }
+  }
+}
+JSON
+
+# tea's own config store: the source get_gitea_token_for_login reads. Logins
+# "alice" (mosaicstack) and "bob-usc" (usc) carry sentinel token values that
+# the assertions prove are NEVER emitted by the resolver.
+cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
+logins:
+- name: alice
+  url: https://git.mosaicstack.dev
+  token: SECRET-alice-tea-token
+- name: bob-usc
+  url: https://git.uscllc.com
+  token: SECRET-bob-usc-tea-token
+YAML
+
+# Stubbed tea: only what login resolution needs (`login list --output json`).
+cat > "$BIN_DIR/tea" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$*" == "login list --output json" ]]; then
+    cat <<'JSON'
+[
+  {"name":"alice","url":"https://git.mosaicstack.dev","default":true},
+  {"name":"bob-usc","url":"https://git.uscllc.com"}
+]
+JSON
+    exit 0
+fi
+exit 0
+SH
+chmod +x "$BIN_DIR/tea"
+
+# Per-slot identity token with a sentinel value the assertions prove is never
+# emitted (proving "token came from the identity's slot BY PATH, not by value").
+echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
+
+fail=0
+assert_eq() {
+  local desc="$1" expected="$2" actual="$3"
+  if [[ "$expected" != "$actual" ]]; then
+    echo "FAIL: $desc — expected '$expected', got '$actual'" >&2
+    fail=1
+  fi
+}
+assert_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  if [[ "$haystack" != *"$needle"* ]]; then
+    echo "FAIL: $desc — missing '$needle' in: $haystack" >&2
+    fail=1
+  fi
+}
+assert_not_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "FAIL: $desc — must not contain '$needle', got: $haystack" >&2
+    fail=1
+  fi
+}
+
+# Runs resolve_gitea_principal for $1=login_override $2=host inside REPO_DIR
+# (per-worktree git config resolves there) under a fake HOME, stubbed tea, and
+# stubbed credentials. Extra env (e.g. MOSAIC_GIT_IDENTITY) via $@.
+call_resolver() {
+  local login="$1" host="$2"; shift 2
+  (
+    cd "$REPO_DIR"
+    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+      DETECT_PLATFORM_SH="$SCRIPT_DIR/detect-platform.sh" "$@" \
+      bash -c 'source "$DETECT_PLATFORM_SH"; resolve_gitea_principal "$1" "$2"' _ "$login" "$host"
+  )
+}
+
+field() { printf '%s' "$1" | cut -f"$2"; }
+
+# ---------------------------------------------------------------------------
+# 1. Identity env + slot present -> identity mode, slot named BY PATH, and no
+#    token value ever emitted.
+# ---------------------------------------------------------------------------
+git -C "$REPO_DIR" config --unset mosaic.gitIdentity 2>/dev/null || true
+out=$(call_resolver "" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentX)
+assert_eq "identity mode"            "identity" "$(field "$out" 1)"
+assert_eq "identity principal"       "agentX"   "$(field "$out" 2)"
+assert_eq "identity slot source" \
+  "identity-slot:$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token" \
+  "$(field "$out" 3)"
+assert_not_contains "identity stdout leaks token" "$out" "SECRET"
+
+# ---------------------------------------------------------------------------
+# 2. Identity env + slot ABSENT -> fail loud: nonzero, empty stdout, stderr
+#    naming the identity and the expected slot path.
+# ---------------------------------------------------------------------------
+stderr_file="$WORK_DIR/stderr.tmp"
+set +e
+out=$(call_resolver "" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]]; then
+  echo "FAIL: missing slot — expected nonzero return, got 0 (stdout='$out')" >&2
+  fail=1
+fi
+if [[ -n "$out" ]]; then
+  echo "FAIL: missing slot — expected empty stdout, got '$out'" >&2
+  fail=1
+fi
+err=$(cat "$stderr_file")
+assert_contains "missing slot names identity"  "$err" "agentNoSlot"
+assert_contains "missing slot names slot path" "$err" \
+  "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"
+assert_not_contains "missing-slot stderr leaks token" "$err" "SECRET"
+
+# ---------------------------------------------------------------------------
+# 3. Identity + --login -> --login wins. Also wins when the identity has NO
+#    slot (no identity check may veto an explicit login).
+# ---------------------------------------------------------------------------
+out=$(call_resolver "alice" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentX)
+assert_eq "login beats identity (mode)"      "login" "$(field "$out" 1)"
+assert_eq "login beats identity (principal)" "alice" "$(field "$out" 2)"
+assert_eq "login source" "tea-login:alice" "$(field "$out" 3)"
+out=$(call_resolver "alice" "git.mosaicstack.dev" MOSAIC_GIT_IDENTITY=agentNoSlot)
+assert_eq "login beats slot-less identity" "login" "$(field "$out" 1)"
+
+# ---------------------------------------------------------------------------
+# 4. No identity, no --login -> default mode via the tea login list
+#    (preserved behavior).
+# ---------------------------------------------------------------------------
+out=$(call_resolver "" "git.mosaicstack.dev")
+assert_eq "default mode"          "default" "$(field "$out" 1)"
+assert_eq "default principal"     "alice"   "$(field "$out" 2)"
+assert_eq "default source"        "tea-default" "$(field "$out" 3)"
+
+# ---------------------------------------------------------------------------
+# 5. No identity, no --login, no host-matching tea login -> default with the
+#    host credential (absence is not an error on the default path).
+# ---------------------------------------------------------------------------
+out=$(call_resolver "" "git.unknown.test")
+assert_eq "no-match default mode"  "default" "$(field "$out" 1)"
+assert_eq "no-match default principal" "" "$(field "$out" 2)"
+assert_eq "no-match default source" "host-credential" "$(field "$out" 3)"
+
+# ---------------------------------------------------------------------------
+# 6. Identity on an UNRECOGNIZED host -> does not bind; default mode
+#    (containment, mirroring get_gitea_token's scope).
+# ---------------------------------------------------------------------------
+out=$(call_resolver "" "github.com" MOSAIC_GIT_IDENTITY=agentX)
+assert_eq "unrecognized host falls to default" "default" "$(field "$out" 1)"
+
+# ---------------------------------------------------------------------------
+# 7. --login with no host-bound token for that login -> fail loud, stderr
+#    naming the login and the host.
+# ---------------------------------------------------------------------------
+: > "$stderr_file"
+set +e
+out=$(call_resolver "ghost-login" "git.mosaicstack.dev" 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]]; then
+  echo "FAIL: unknown --login — expected nonzero return, got 0 (stdout='$out')" >&2
+  fail=1
+fi
+err=$(cat "$stderr_file")
+assert_contains "unknown login names login" "$err" "ghost-login"
+assert_contains "unknown login names host"  "$err" "git.mosaicstack.dev"
+# A cross-host login (exists, but for usc) must ALSO fail loud for mosaicstack.
+set +e
+out=$(call_resolver "bob-usc" "git.mosaicstack.dev" 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]]; then
+  echo "FAIL: cross-host --login — expected nonzero return, got 0" >&2
+  fail=1
+fi
+
+# ---------------------------------------------------------------------------
+# 8. git config mosaic.gitIdentity honored when env is unset.
+# ---------------------------------------------------------------------------
+git -C "$REPO_DIR" config mosaic.gitIdentity agentX
+out=$(call_resolver "" "git.mosaicstack.dev")
+assert_eq "git-config identity mode" "identity" "$(field "$out" 1)"
+assert_eq "git-config identity principal" "agentX" "$(field "$out" 2)"
+git -C "$REPO_DIR" config --unset mosaic.gitIdentity
+
+# ---------------------------------------------------------------------------
+# 9. Cross-host slot layout: the usc slot path is chosen for the usc host.
+# ---------------------------------------------------------------------------
+echo -n "SECRET-agentX-usc-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentX.token"
+out=$(call_resolver "" "git.uscllc.com" MOSAIC_GIT_IDENTITY=agentX)
+assert_eq "usc identity mode" "identity" "$(field "$out" 1)"
+assert_eq "usc slot source" \
+  "identity-slot:$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-usc-agentX.token" \
+  "$(field "$out" 3)"
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "resolve_gitea_principal identity-first resolution regression passed"
+fi
+
+exit "$fail"
@@ -77,12 +77,30 @@ exit 0
 SH
 chmod +x "$BIN_DIR/tea"

+# TRIPWIRE provider stub: this harness tests argv construction, so ANY curl
+# call is a failure of that contract (and, before this stub existed, a LIVE
+# write — the #1282–#1287 incident: the seat's real HOME leaked a global
+# mosaic.gitIdentity, flipping the wrapper into identity mode whose real
+# per-slot token created real issues on the forge). Fail loudly instead.
+cat > "$BIN_DIR/curl" <<'SH'
+#!/usr/bin/env bash
+echo "FAIL: body-safety harness reached a provider request — this test must never curl" >&2
+exit 99
+SH
+chmod +x "$BIN_DIR/curl"
+
+# Hermetic invocation: fake HOME (no credentials, no tea config, no token
+# slots) and GIT_CONFIG_GLOBAL severed — `git config --get mosaic.gitIdentity`
+# otherwise resolves the WORKSTATION's global identity (mos-dt-0 on the seat
+# that wrote this) and reroutes the wrapper into identity mode (#1280 family).
 (
    cd "$REPO_DIR"
-    PATH="$BIN_DIR:$PATH" \
-    MOSAIC_TEST_RECEIVED="$RECEIVED_FILE" \
-    "$SCRIPT_DIR/issue-create.sh" -t "Body safety test" -b "$BODY"
+    env -i HOME="$WORK_DIR/home" PATH="$BIN_DIR:$PATH" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_TEST_RECEIVED="$RECEIVED_FILE" \
+      "$SCRIPT_DIR/issue-create.sh" -t "Body safety test" -b "$BODY"
 ) >/dev/null
+mkdir -p "$WORK_DIR/home"

 # 1. No command substitution executed anywhere in the pipeline.
 if [[ -e "$SENTINEL" ]]; then
@@ -47,14 +47,31 @@ SH
 chmod +x "$BIN_DIR/tea" "$BIN_DIR/curl"

 run_wrapper() {
+  # Hermetic: fake HOME (fixture credentials only, no token slots, no tea
+  # config) and GIT_CONFIG_GLOBAL severed — `git config --get
+  # mosaic.gitIdentity` otherwise resolves the WORKSTATION's global identity
+  # and reroutes the wrapper into identity mode before the tea paths this
+  # harness exercises (#1280 family; see test-issue-create-body-safety.sh).
+  # An `env …` prefix (used for MOSAIC_TEA_STALE_USER) is re-wrapped, not
+  # doubled: arguments beginning with "env" are shifted past.
+  local env_pairs=()
+  if [[ "${1:-}" == "env" ]]; then
+    shift
+    while [[ "$#" -gt 0 && "$1" == *=* ]]; do
+      env_pairs+=("$1")
+      shift
+    done
+  fi
  (
    cd "$REPO_DIR"
-    PATH="$BIN_DIR:$PATH" \
-    MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-    MOSAIC_TEST_LOG="$LOG_FILE" \
-    "$@"
+    env -i HOME="$WORK_DIR/home" PATH="$BIN_DIR:$PATH" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+      MOSAIC_TEST_LOG="$LOG_FILE" "${env_pairs[@]}" \
+      "$@"
  )
 }
+mkdir -p "$WORK_DIR/home"

 : > "$LOG_FILE"
 printf 'Interactive title\nInteractive body\nlabel-a,label-b\nM1\n' | run_wrapper "$SCRIPT_DIR/issue-create.sh" -i >/dev/null
@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# Load-bearing regression harness for pr-create.sh identity-first principal
+# resolution (mosaicstack/stack #1280).
+#
+# The failure this harness is written down to catch: `MOSAIC_GIT_IDENTITY=fargo
+# pr-create.sh …` produces a PR attributed to `mos-dt-0` (whichever account the
+# tea login list happens to hold). Before #1280 the identity-aware code existed
+# but sat on the API arm that only ran when the tea path FAILED — tea succeeded,
+# so the identity arm never executed, and every test that did not check ORDERING
+# passed. This harness checks ordering directly:
+#
+#   1. identity set + slot present -> the PR is created via the REST API with
+#      the identity's per-slot token (asserted by sentinel value AT the fake
+#      provider), and tea's `pr create` is NEVER invoked.
+#   2. identity set + slot ABSENT -> nonzero, stderr naming the identity and
+#      the expected slot path; neither tea `pr create` nor any API request
+#      fires. No silent fallback to the tea login list.
+#   3. identity set + --login -> --login wins: tea runs WITH the explicit
+#      --login, no API request.
+#   4. nothing set -> preserved behavior: tea path with the tea-list login.
+#
+# Uses a stubbed tea, a stubbed curl provider, stubbed credentials.json and
+# per-slot token under a fake HOME. NEVER reads real secrets or hits a live
+# forge — all assertions are against the stubs' logs.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-identity-first}"
+FAKE_HOME="$WORK_DIR/home"
+REPO_DIR="$WORK_DIR/repo"
+TOOLS_DIR="$WORK_DIR/tools"
+BIN_DIR="$WORK_DIR/bin"
+LOG_FILE="$WORK_DIR/calls.log"
+CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" \
+  "$REPO_DIR" "$TOOLS_DIR/git" "$TOOLS_DIR/_lib" "$BIN_DIR"
+
+# Fixture: the real scripts under test, copied so sibling stubs (and the
+# ../_lib credential loader) resolve inside the fixture tree.
+cp "$SCRIPT_DIR/pr-create.sh" "$TOOLS_DIR/git/pr-create.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS_DIR/git/detect-platform.sh"
+cp "$SCRIPT_DIR/../_lib/credentials.sh" "$TOOLS_DIR/_lib/credentials.sh"
+chmod +x "$TOOLS_DIR/git/pr-create.sh"
+
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
+
+cat > "$CREDENTIALS_FILE" <<'JSON'
+{
+  "gitea": {
+    "mosaicstack": {
+      "url": "https://git.mosaicstack.dev",
+      "token": "shared-mosaicstack-token"
+    }
+  }
+}
+JSON
+
+cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
+logins:
+- name: alice
+  url: https://git.mosaicstack.dev
+  token: SECRET-alice-tea-token
+YAML
+
+echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
+
+: > "$LOG_FILE"
+
+# Stubbed tea: records every invocation; `login list` feeds login resolution;
+# `api --login <n> /user` feeds get_gitea_authenticated_user; `pr create` marks
+# the marker file (its presence fails the identity-mode assertions).
+cat > "$BIN_DIR/tea" <<SH
+#!/usr/bin/env bash
+set -euo pipefail
+printf 'TEA: %s\n' "\$*" >> "$LOG_FILE"
+if [[ "\$*" == "login list --output json" ]]; then
+    cat <<'JSON'
+[
+  {"name":"alice","url":"https://git.mosaicstack.dev","default":true}
+]
+JSON
+    exit 0
+fi
+if [[ "\${1:-}" == "api" ]]; then
+    printf '%s\n' '{"login":"alice"}'
+    exit 0
+fi
+if [[ "\$*" == pr\ create* ]]; then
+    echo "TEA-PR-CREATE-INVOKED" >> "$LOG_FILE"
+    exit 0
+fi
+exit 0
+SH
+chmod +x "$BIN_DIR/tea"
+
+# Stubbed provider: records the URL and the Authorization header VALUE it
+# received, answers 201 with a created-PR object. The sentinel token values are
+# synthetic fixtures — asserting them at the provider proves WHICH slot's
+# credential carried the write.
+cat > "$BIN_DIR/curl" <<SH
+#!/usr/bin/env bash
+set -euo pipefail
+url=""
+auth=""
+while [[ \$# -gt 0 ]]; do
+    case "\$1" in
+        -H)
+            case "\$2" in
+                Authorization*) auth="\$2" ;;
+            esac
+            shift 2
+            ;;
+        *)  [[ -n "\$1" && "\$1" != -* ]] && url="\$1"
+            shift
+            ;;
+    esac
+done
+printf 'CURL-URL: %s\nCURL-AUTH: %s\n' "\$url" "\$auth" >> "$LOG_FILE"
+cat <<'JSON'
+{"number": 1299, "html_url": "https://git.mosaicstack.dev/mosaicstack/stack/pulls/1299"}
+JSON
+exit 0
+SH
+chmod +x "$BIN_DIR/curl"
+
+fail=0
+assert_contains() {
+  local desc="$1" needle="$2"
+  if ! grep -qF -- "$needle" "$LOG_FILE"; then
+    echo "FAIL: $desc — log does not contain '$needle':" >&2
+    cat "$LOG_FILE" >&2
+    fail=1
+  fi
+}
+assert_not_contains() {
+  local desc="$1" needle="$2"
+  if grep -qF -- "$needle" "$LOG_FILE"; then
+    echo "FAIL: $desc — log must not contain '$needle':" >&2
+    cat "$LOG_FILE" >&2
+    fail=1
+  fi
+}
+
+EXTRA_ARGS=""
+run_pr_create() {
+  # "$@" carries ONLY environment assignments (VAR=value); EXTRA_ARGS (if
+  # set) carries wrapper arguments, so `env` never mistakes a wrapper flag
+  # like --login for one of its own.
+  (
+    cd "$REPO_DIR"
+    # shellcheck disable=SC2086 # EXTRA_ARGS is deliberately word-split wrapper args
+    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" "$@" \
+      bash "$TOOLS_DIR/git/pr-create.sh" -t "Test PR" -B next -H fix/test $EXTRA_ARGS
+  )
+}
+
+# ---------------------------------------------------------------------------
+# 1. HAPPY PATH (the load-bearing ordering test): identity set + slot present
+#    -> REST API with the per-slot token; tea `pr create` NEVER invoked.
+# ---------------------------------------------------------------------------
+set +e
+out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentX 2>"$WORK_DIR/stderr-1.tmp")
+rc=$?
+set -e
+if [[ "$rc" -ne 0 ]]; then
+  echo "FAIL: identity happy path — expected rc=0, got $rc" >&2
+  cat "$WORK_DIR/stderr-1.tmp" >&2
+  fail=1
+fi
+assert_contains "identity happy path reaches the API" "CURL-URL: https://git.mosaicstack.dev/api/v1/repos/mosaicstack/stack/pulls"
+assert_contains "identity happy path carries the slot token" "CURL-AUTH: Authorization: token SECRET-agentX-slot-token"
+assert_not_contains "identity happy path must NOT invoke tea pr create" "TEA-PR-CREATE-INVOKED"
+
+# ---------------------------------------------------------------------------
+# 2. Identity set + slot ABSENT -> fail loud BEFORE any write: nonzero, stderr
+#    naming identity + slot path, no tea pr create, no API request.
+# ---------------------------------------------------------------------------
+: > "$LOG_FILE"
+set +e
+out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$WORK_DIR/stderr-2.tmp")
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]]; then
+  echo "FAIL: missing slot — expected nonzero return, got 0 (stdout='$out')" >&2
+  fail=1
+fi
+err=$(cat "$WORK_DIR/stderr-2.tmp")
+if [[ "$err" != *"agentNoSlot"* ]]; then
+  echo "FAIL: missing slot — stderr does not name the identity:" >&2
+  echo "$err" >&2
+  fail=1
+fi
+if [[ "$err" != *"$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"* ]]; then
+  echo "FAIL: missing slot — stderr does not name the expected slot path:" >&2
+  echo "$err" >&2
+  fail=1
+fi
+assert_not_contains "missing slot must not reach tea pr create" "TEA-PR-CREATE-INVOKED"
+assert_not_contains "missing slot must not reach the API" "CURL-URL"
+
+# ---------------------------------------------------------------------------
+# 3. Identity set + --login -> --login wins: tea runs WITH the explicit login.
+# ---------------------------------------------------------------------------
+: > "$LOG_FILE"
+EXTRA_ARGS="--login alice"
+set +e
+out=$(run_pr_create MOSAIC_GIT_IDENTITY=agentX 2>"$WORK_DIR/stderr-3.tmp")
+rc=$?
+set -e
+EXTRA_ARGS=""
+if [[ "$rc" -ne 0 ]]; then
+  echo "FAIL: login override — expected rc=0, got $rc" >&2
+  cat "$WORK_DIR/stderr-3.tmp" >&2
+  fail=1
+fi
+assert_contains "login override drives tea with the explicit login" "TEA: pr create --repo mosaicstack/stack --login alice"
+assert_not_contains "login override must not hit the API" "CURL-URL"
+
+# ---------------------------------------------------------------------------
+# 4. Nothing set -> preserved behavior: tea path with the tea-list login.
+# ---------------------------------------------------------------------------
+: > "$LOG_FILE"
+set +e
+out=$(run_pr_create 2>"$WORK_DIR/stderr-4.tmp")
+rc=$?
+set -e
+if [[ "$rc" -ne 0 ]]; then
+  echo "FAIL: default path — expected rc=0, got $rc" >&2
+  cat "$WORK_DIR/stderr-4.tmp" >&2
+  fail=1
+fi
+assert_contains "default path still uses the tea-list login" "TEA: pr create --repo mosaicstack/stack --login alice"
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "pr-create identity-first happy-path regression passed"
+fi
+
+exit "$fail"
@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Regression harness for pr-merge.sh identity-first principal resolution
+# (mosaicstack/stack #1280).
+#
+# Covers:
+#   1. --dry-run reports the acting principal the merge WOULD use, resolved the
+#      same way the real merge resolves it: --login > MOSAIC_GIT_IDENTITY /
+#      git config mosaic.gitIdentity > shared host credential. (The pre-#1280
+#      deployed copy reported a tea login that the merge would not act as.)
+#   2. --dry-run fails closed when the requested principal has no credential:
+#      unknown --login, or an identity with no per-slot token (stderr names
+#      the login / the identity and its slot path).
+#   3. The real merge POST carries the resolved principal's credential and no
+#      other: --login merges with that login's tea-config token; an identity
+#      merges with the per-slot token; an unresolvable --login never reaches
+#      the provider.
+#
+# Fixture pattern from test-pr-merge-head-pin.sh: the scripts under test are
+# copied into a fixture tree with stubbed pr-metadata.sh / ci-queue-wait.sh
+# siblings; the provider is a stubbed curl that records the credential it
+# received. NEVER reads real secrets or hits a live forge.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-principal-resolution}"
+FAKE_HOME="$WORK_DIR/home"
+REPO_DIR="$WORK_DIR/repo"
+TOOLS_DIR="$WORK_DIR/tools"
+BIN_DIR="$WORK_DIR/bin"
+LOG_FILE="$WORK_DIR/calls.log"
+CREDENTIALS_FILE="$FAKE_HOME/.config/mosaic/credentials.json"
+SHA=0123456789abcdef0123456789abcdef01234567
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens" "$FAKE_HOME/.config/tea" \
+  "$REPO_DIR" "$TOOLS_DIR/git" "$TOOLS_DIR/_lib" "$BIN_DIR"
+
+cp "$SCRIPT_DIR/pr-merge.sh" "$TOOLS_DIR/git/pr-merge.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$TOOLS_DIR/git/detect-platform.sh"
+cp "$SCRIPT_DIR/../_lib/credentials.sh" "$TOOLS_DIR/_lib/credentials.sh"
+chmod +x "$TOOLS_DIR/git/pr-merge.sh"
+
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
+
+# Stubbed siblings pr-merge.sh resolves relative to its own SCRIPT_DIR.
+cat > "$TOOLS_DIR/git/pr-metadata.sh" <<SH
+#!/usr/bin/env bash
+printf '%s\n' '{"baseRefName":"next","headRefName":"fix/pinned","headRefOid":"$SHA","headRepository":"mosaicstack/stack","title":"Test PR","author":{"login":"contributor"}}'
+SH
+cat > "$TOOLS_DIR/git/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+chmod +x "$TOOLS_DIR/git/pr-metadata.sh" "$TOOLS_DIR/git/ci-queue-wait.sh"
+
+cat > "$CREDENTIALS_FILE" <<'JSON'
+{
+  "gitea": {
+    "mosaicstack": {
+      "url": "https://git.mosaicstack.dev",
+      "token": "shared-mosaicstack-token"
+    }
+  }
+}
+JSON
+
+cat > "$FAKE_HOME/.config/tea/config.yml" <<'YAML'
+logins:
+- name: fred-ms
+  url: https://git.mosaicstack.dev
+  token: SECRET-fred-ms-tea-token
+YAML
+
+echo -n "SECRET-agentX-slot-token" > "$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentX.token"
+
+: > "$LOG_FILE"
+
+# Stubbed tea for login-list resolution only.
+cat > "$BIN_DIR/tea" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$*" == "login list --output json" ]]; then
+    cat <<'JSON'
+[
+  {"name":"fred-ms","url":"https://git.mosaicstack.dev","default":true}
+]
+JSON
+    exit 0
+fi
+exit 0
+SH
+chmod +x "$BIN_DIR/tea"
+
+# Stubbed provider. pr-merge passes curl config on STDIN with -K -; the stub
+# reads stdin, records the Authorization header it received, answers 200.
+cat > "$BIN_DIR/curl" <<SH
+#!/usr/bin/env bash
+set -euo pipefail
+url=""
+out_file=""
+stdin_config=""
+if [[ ! -t 0 ]]; then
+    stdin_config="\$(cat || true)"
+fi
+while [[ \$# -gt 0 ]]; do
+    case "\$1" in
+        -o) out_file="\$2"; shift 2 ;;
+        -K|-w|--max-filesize|--max-time|--connect-timeout|-sS) shift 2 ;;
+        *)  [[ -n "\$1" && "\$1" != -* && -z "\$url" ]] && url="\$1"
+            shift
+            ;;
+    esac
+done
+auth="\$(printf '%s' "\$stdin_config" | grep -o 'Authorization: token [^"]*' || true)"
+printf 'CURL-URL: %s\nCURL-AUTH: %s\n' "\$url" "\$auth" >> "$LOG_FILE"
+[[ -n "\$out_file" ]] && printf '{}' > "\$out_file"
+printf '200\n'
+exit 0
+SH
+chmod +x "$BIN_DIR/curl"
+
+fail=0
+assert_contains_log() {
+  local desc="$1" needle="$2"
+  if ! grep -qF -- "$needle" "$LOG_FILE"; then
+    echo "FAIL: $desc — log does not contain '$needle':" >&2
+    cat "$LOG_FILE" >&2
+    fail=1
+  fi
+}
+assert_not_contains_log() {
+  local desc="$1" needle="$2"
+  if grep -qF -- "$needle" "$LOG_FILE"; then
+    echo "FAIL: $desc — log must not contain '$needle':" >&2
+    cat "$LOG_FILE" >&2
+    fail=1
+  fi
+}
+
+run_pr_merge() {
+  local extra_args="$1"; shift
+  (
+    cd "$REPO_DIR"
+    # shellcheck disable=SC2086 # extra_args is deliberately word-split wrapper args
+    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:$PATH" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" "$@" \
+      bash "$TOOLS_DIR/git/pr-merge.sh" -n 42 $extra_args
+  )
+}
+
+# ---------------------------------------------------------------------------
+# 1. --dry-run reports the resolved acting principal truthfully.
+# ---------------------------------------------------------------------------
+out=$(run_pr_merge "--dry-run" MOSAIC_GIT_IDENTITY=agentX)
+if [[ "$out" != *"as git identity 'agentX' (per-slot credential)"* ]]; then
+  echo "FAIL: dry-run identity — principal not reported: $out" >&2
+  fail=1
+fi
+
+out=$(run_pr_merge "--dry-run --login fred-ms" MOSAIC_GIT_IDENTITY=agentX)
+if [[ "$out" != *"as tea login 'fred-ms'"* ]]; then
+  echo "FAIL: dry-run login override — login not reported (must beat env identity): $out" >&2
+  fail=1
+fi
+
+out=$(run_pr_merge "--dry-run")
+if [[ "$out" != *"as default host credential"* ]]; then
+  echo "FAIL: dry-run default — not reported: $out" >&2
+  fail=1
+fi
+
+# ---------------------------------------------------------------------------
+# 2. --dry-run fails closed when the requested principal has no credential.
+# ---------------------------------------------------------------------------
+stderr_file="$WORK_DIR/stderr.tmp"
+set +e
+out=$(run_pr_merge "--dry-run --login ghost" 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]] || [[ "$(cat "$stderr_file")" != *"ghost"* ]]; then
+  echo "FAIL: dry-run unknown --login — expected fail-loud naming 'ghost', rc=$rc" >&2
+  cat "$stderr_file" >&2
+  fail=1
+fi
+
+: > "$stderr_file"
+set +e
+out=$(run_pr_merge "--dry-run" MOSAIC_GIT_IDENTITY=agentNoSlot 2>"$stderr_file")
+rc=$?
+set -e
+err=$(cat "$stderr_file")
+if [[ "$rc" -eq 0 ]] || [[ "$err" != *"agentNoSlot"* ]] \
+  || [[ "$err" != *"$FAKE_HOME/.config/mosaic/secrets/gitea-tokens/gitea-mosaicstack-agentNoSlot.token"* ]]; then
+  echo "FAIL: dry-run identity without slot — expected fail-loud naming identity + slot path, rc=$rc" >&2
+  echo "$err" >&2
+  fail=1
+fi
+
+# ---------------------------------------------------------------------------
+# 3. The real merge POST carries the resolved principal's credential ONLY.
+# ---------------------------------------------------------------------------
+: > "$LOG_FILE"
+set +e
+out=$(run_pr_merge "--login fred-ms" MOSAIC_GIT_IDENTITY=agentX 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -ne 0 ]]; then
+  echo "FAIL: merge with --login — expected rc=0, got $rc" >&2
+  cat "$stderr_file" >&2
+  fail=1
+fi
+assert_contains_log "merge --login uses the login token" "CURL-AUTH: Authorization: token SECRET-fred-ms-tea-token"
+assert_not_contains_log "merge --login must not use the identity slot token" "SECRET-agentX-slot-token"
+assert_not_contains_log "merge --login must not use the shared token" "shared-mosaicstack-token"
+
+: > "$LOG_FILE"
+set +e
+out=$(run_pr_merge "" MOSAIC_GIT_IDENTITY=agentX 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -ne 0 ]]; then
+  echo "FAIL: merge with identity — expected rc=0, got $rc" >&2
+  cat "$stderr_file" >&2
+  fail=1
+fi
+assert_contains_log "merge identity uses the per-slot token" "CURL-AUTH: Authorization: token SECRET-agentX-slot-token"
+assert_not_contains_log "merge identity must not use the shared token" "shared-mosaicstack-token"
+
+: > "$LOG_FILE"
+set +e
+out=$(run_pr_merge "--login ghost" 2>"$stderr_file")
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]]; then
+  echo "FAIL: merge with unknown --login — expected nonzero, got 0" >&2
+  fail=1
+fi
+assert_not_contains_log "merge with unknown --login must not reach the provider" "CURL-URL"
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "pr-merge identity-first principal resolution regression passed"
+fi
+
+exit "$fail"
@@ -39,3 +39,20 @@ packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires rea
 # recorded judgement. These lines ARE that judgement, signed.)
 packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
 packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate
+
+# --- tools/fleet: precondition is unsatisfiable in the CI image (#1271) ---
+# Signed by fred (sb-it-1-dt, 2026-08-16) at origin/next 476db12.
+# This suite asserts the launcher's behaviour when `mosaic` and `pi` are MISSING.
+# It shims fakes 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 at all. The suite's own guard (line 103) says so and
+# fails rather than reporting a pass it cannot back. That guard is correct.
+# The error was wiring the suite into CI: #1017 (c56483eb) enumerated it and
+# dropped this exclusion, and the CI image provides `pi` in the system path, so
+# it has failed on every pipeline since. Measured 2026-08-16 across pipelines
+# 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in
+# each full log, identical, this assertion; control `zzz-not-present-zzz` -> 0.
+# Burn-down and the full measurement are tracked in #1271; unwired by PR #1270.
+# Because test:framework-shell is one && chain and this sat at position 44 of 48,
+# the four suites after it had not run at all since the merge.
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | precondition unsatisfiable in the CI image: asserts missing-binary behaviour, but PANE_PATH always ends in the system path and the image provides `pi` there; guard at line 103 fails by design rather than passing unmeasured. Burn down by controlling the tail of PANE_PATH inside the test. NOT by removing `pi` from the image: the CI image installs @earendil-works/[email protected] deliberately (measured in pipeline 2444's test-step log), and other suites depend on that pin. Burn-down tracked in #1271
@@ -24,9 +24,8 @@
    "build": "tsc",
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
-    "test": "pnpm run test:vitest && pnpm run test:framework-shell",
-    "test:vitest": "pnpm run build && vitest run --passWithNoTests",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
+    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-gitea-principal-resolution.sh && bash framework/tools/git/test-pr-create-identity-first.sh && bash framework/tools/git/test-pr-merge-principal-resolution.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -15,7 +15,6 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { FileConfigAdapter } from '../config/file-adapter.js';
-import { seedFleetIdentityDefaults } from './fleet-first-start-identity.js';
 import { composeContract } from './launch.js';

 /**
@@ -320,7 +319,6 @@ describe('composeContract — overlay composer', () => {
        ].join('\n'),
      );
      process.env['MOSAIC_AGENT_NAME'] = 'exact-self';
-      expect(seedFleetIdentityDefaults(installedHome)).toEqual(['SOUL.md', 'USER.md']);

      const composed = composeContract('pi', installedHome);
      expect(composed).toContain(sourceTools);
@@ -334,49 +332,6 @@ describe('composeContract — overlay composer', () => {
    }
  });

-  it('refuses a fleet USER.md replacement symlink at the point of composition', () => {
-    mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
-    writeFileSync(
-      join(fixture.home, 'fleet', 'roster.yaml'),
-      [
-        'version: 1',
-        'transport: tmux',
-        'agents:',
-        '  - name: exact-user-seat',
-        '    runtime: pi',
-        '    class: worker',
-        '',
-      ].join('\n'),
-    );
-    process.env['MOSAIC_AGENT_NAME'] = 'exact-user-seat';
-    process.env['MOSAIC_AGENT_CLASS'] = 'worker';
-    writeFileSync(join(fixture.home, 'defaults', 'SOUL.md'), '# Generic soul\n');
-    writeFileSync(join(fixture.home, 'defaults', 'USER.md'), '# Generic user\n');
-    expect(seedFleetIdentityDefaults(fixture.home)).toEqual(['SOUL.md']);
-
-    const userPath = join(fixture.home, 'USER.md');
-    const external = join(fixture.root, 'attacker-user.md');
-    writeFileSync(external, 'UNSAFE-REPLACEMENT-USER-CONTENT\n');
-    rmSync(userPath);
-    symlinkSync(external, userPath);
-
-    expect(() => composeContract('pi', fixture.home)).toThrow(
-      `fleet identity installed is unavailable or unsafe: ${userPath}`,
-    );
-    expect(readFileSync(external, 'utf8')).toBe('UNSAFE-REPLACEMENT-USER-CONTENT\n');
-  });
-
-  it('preserves tolerant standalone composition when optional USER.md is unreadable', () => {
-    const userPath = join(fixture.home, 'USER.md');
-    rmSync(userPath);
-    mkdirSync(userPath);
-
-    const out = composeContract('pi', fixture.home);
-
-    expect(out).toContain(AGENTS);
-    expect(out).not.toContain('# User Profile');
-  });
-
  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
    'never injects installed TOOLS.md through a target symlink for %s',
    (runtime) => {
@@ -1,182 +0,0 @@
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  lstatSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  statSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
-import {
-  linkIdentityContractNoClobber,
-  seedFleetIdentityDefaults,
-} from './fleet-first-start-identity.js';
-
-const roots: string[] = [];
-const DEFAULT_SOUL = '# Generic soul\n';
-const DEFAULT_USER = '# Generic user\n';
-
-function writeFixture(path: string, content: string | Buffer, mode: number = 0o600): void {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  writeFileSync(path, content, { mode });
-  chmodSync(path, mode);
-}
-
-function createMosaicHome(): string {
-  const root = mkdtempSync(join(tmpdir(), 'mosaic-identity-seed-'));
-  roots.push(root);
-  const mosaicHome = join(root, 'home', '.config', 'mosaic');
-  writeFixture(join(mosaicHome, 'defaults', 'SOUL.md'), DEFAULT_SOUL);
-  writeFixture(join(mosaicHome, 'defaults', 'USER.md'), DEFAULT_USER);
-  return mosaicHome;
-}
-
-function temporarySeeds(mosaicHome: string): string[] {
-  return readdirSync(mosaicHome).filter((entry) => entry.includes('.fleet-seed-'));
-}
-
-afterEach((): void => {
-  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
-});
-
-describe('linkIdentityContractNoClobber', () => {
-  it('returns false and preserves a destination that already exists', () => {
-    const mosaicHome = createMosaicHome();
-    const source = join(mosaicHome, 'source.tmp');
-    const destination = join(mosaicHome, 'destination.md');
-    writeFixture(source, 'candidate\n');
-    writeFixture(destination, 'operator\n');
-
-    expect(linkIdentityContractNoClobber(source, destination)).toBe(false);
-    expect(readFileSync(destination, 'utf8')).toBe('operator\n');
-  });
-
-  it('does not misclassify an unexpected link failure as a concurrent winner', () => {
-    const mosaicHome = createMosaicHome();
-    const missingSource = join(mosaicHome, 'missing.tmp');
-
-    expect(() =>
-      linkIdentityContractNoClobber(missingSource, join(mosaicHome, 'destination.md')),
-    ).toThrow();
-  });
-});
-
-describe('seedFleetIdentityDefaults', () => {
-  it('publishes complete owner-private default snapshots', () => {
-    const mosaicHome = createMosaicHome();
-
-    expect(seedFleetIdentityDefaults(mosaicHome)).toEqual(['SOUL.md', 'USER.md']);
-
-    for (const [entry, expected] of [
-      ['SOUL.md', DEFAULT_SOUL],
-      ['USER.md', DEFAULT_USER],
-    ] as const) {
-      const path = join(mosaicHome, entry);
-      expect(readFileSync(path, 'utf8')).toBe(expected);
-      expect(statSync(path).mode & 0o777).toBe(0o600);
-    }
-    expect(temporarySeeds(mosaicHome)).toEqual([]);
-  });
-
-  it('preserves an existing regular contract byte-for-byte and mode-for-mode', () => {
-    const mosaicHome = createMosaicHome();
-    const customSoul = '# Operator-owned soul\n';
-    writeFixture(join(mosaicHome, 'SOUL.md'), customSoul, 0o640);
-
-    expect(seedFleetIdentityDefaults(mosaicHome)).toEqual(['USER.md']);
-    expect(readFileSync(join(mosaicHome, 'SOUL.md'), 'utf8')).toBe(customSoul);
-    expect(statSync(join(mosaicHome, 'SOUL.md')).mode & 0o777).toBe(0o640);
-  });
-
-  it('is idempotent after both installed contracts exist', () => {
-    const mosaicHome = createMosaicHome();
-
-    expect(seedFleetIdentityDefaults(mosaicHome)).toEqual(['SOUL.md', 'USER.md']);
-    expect(seedFleetIdentityDefaults(mosaicHome)).toEqual([]);
-    expect(temporarySeeds(mosaicHome)).toEqual([]);
-  });
-
-  it('validates every required source before publishing any destination', () => {
-    const mosaicHome = createMosaicHome();
-    const missing = join(mosaicHome, 'defaults', 'USER.md');
-    rmSync(missing);
-
-    expect(() => seedFleetIdentityDefaults(mosaicHome)).toThrow(
-      `fleet identity default is unavailable or unsafe: ${missing}`,
-    );
-    expect(existsSync(join(mosaicHome, 'SOUL.md'))).toBe(false);
-    expect(existsSync(join(mosaicHome, 'USER.md'))).toBe(false);
-  });
-
-  it('fails closed when the configured Mosaic home is not a directory', () => {
-    const root = mkdtempSync(join(tmpdir(), 'mosaic-identity-invalid-home-'));
-    roots.push(root);
-    const mosaicHome = join(root, 'mosaic-home');
-    writeFixture(mosaicHome, 'not a directory\n');
-
-    expect(() => seedFleetIdentityDefaults(mosaicHome)).toThrow(
-      `fleet identity installed is unavailable or unsafe: ${join(mosaicHome, 'SOUL.md')}`,
-    );
-  });
-
-  it('refuses a symlinked default instead of following it', () => {
-    const mosaicHome = createMosaicHome();
-    const source = join(mosaicHome, 'defaults', 'SOUL.md');
-    rmSync(source);
-    symlinkSync(join(mosaicHome, 'defaults', 'USER.md'), source);
-
-    expect(() => seedFleetIdentityDefaults(mosaicHome)).toThrow(
-      `fleet identity default is unavailable or unsafe: ${source}`,
-    );
-    expect(existsSync(join(mosaicHome, 'SOUL.md'))).toBe(false);
-  });
-
-  it('refuses an existing symlinked destination without replacing it', () => {
-    const mosaicHome = createMosaicHome();
-    const destination = join(mosaicHome, 'SOUL.md');
-    symlinkSync(join(mosaicHome, 'defaults', 'SOUL.md'), destination);
-
-    expect(() => seedFleetIdentityDefaults(mosaicHome)).toThrow(
-      `fleet identity installed is unavailable or unsafe: ${destination}`,
-    );
-    expect(lstatSync(destination).isSymbolicLink()).toBe(true);
-    expect(existsSync(join(mosaicHome, 'USER.md'))).toBe(false);
-  });
-
-  it.each(['SOUL.md', 'USER.md'] as const)(
-    'rejects a dangling %s destination before publishing its counterpart',
-    (entry) => {
-      const mosaicHome = createMosaicHome();
-      const destination = join(mosaicHome, entry);
-      const counterpart = join(mosaicHome, entry === 'SOUL.md' ? 'USER.md' : 'SOUL.md');
-      symlinkSync(join(mosaicHome, 'missing-identity-target'), destination);
-
-      expect(existsSync(destination)).toBe(false);
-      expect(lstatSync(destination).isSymbolicLink()).toBe(true);
-      expect(() => seedFleetIdentityDefaults(mosaicHome)).toThrow(
-        `fleet identity installed is unavailable or unsafe: ${destination}`,
-      );
-      expect(lstatSync(destination).isSymbolicLink()).toBe(true);
-      expect(existsSync(counterpart)).toBe(false);
-    },
-  );
-
-  it('rejects an oversized source before publishing a partial identity', () => {
-    const mosaicHome = createMosaicHome();
-    const source = join(mosaicHome, 'defaults', 'USER.md');
-    writeFixture(source, Buffer.alloc(256 * 1024 + 1, 0x61));
-
-    expect(() => seedFleetIdentityDefaults(mosaicHome)).toThrow(
-      `fleet identity default is unavailable or unsafe: ${source}`,
-    );
-    expect(existsSync(join(mosaicHome, 'SOUL.md'))).toBe(false);
-    expect(existsSync(join(mosaicHome, 'USER.md'))).toBe(false);
-  });
-});
@@ -1,120 +0,0 @@
-import { randomBytes } from 'node:crypto';
-import { linkSync, lstatSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { readRegularFileSecure } from '../fleet/secure-file.js';
-
-const MAX_IDENTITY_CONTRACT_BYTES = 256 * 1024;
-export const FLEET_IDENTITY_DEFAULTS = ['SOUL.md', 'USER.md'] as const;
-
-function isFilesystemError(error: unknown, code: string): boolean {
-  return error instanceof Error && 'code' in error && error.code === code;
-}
-
-/** @internal Publish a complete temporary file without replacing any path. */
-export function linkIdentityContractNoClobber(source: string, destination: string): boolean {
-  try {
-    linkSync(source, destination);
-    return true;
-  } catch (error: unknown) {
-    if (isFilesystemError(error, 'EEXIST')) return false;
-    throw error;
-  }
-}
-
-function unsafeIdentityError(kind: 'default' | 'installed', path: string, error: unknown): Error {
-  const reason = error instanceof Error ? error.message : String(error);
-  return new Error(`fleet identity ${kind} is unavailable or unsafe: ${path} (${reason})`);
-}
-
-function readIdentityContract(
-  mosaicHome: string,
-  path: string,
-  kind: 'default' | 'installed',
-): Buffer {
-  try {
-    return readRegularFileSecure(path, {
-      root: mosaicHome,
-      maxBytes: MAX_IDENTITY_CONTRACT_BYTES,
-    }).content;
-  } catch (error: unknown) {
-    throw unsafeIdentityError(kind, path, error);
-  }
-}
-
-function installedEntryExists(path: string): boolean {
-  try {
-    lstatSync(path);
-    return true;
-  } catch (error: unknown) {
-    if (isFilesystemError(error, 'ENOENT')) return false;
-    throw unsafeIdentityError('installed', path, error);
-  }
-}
-
-/** Secure fleet point-of-use read for a top-level identity contract. */
-export function readInstalledIdentityContractAtPointOfUse(
-  mosaicHome: string,
-  entry: (typeof FLEET_IDENTITY_DEFAULTS)[number],
-): Buffer {
-  const configuredPath = join(mosaicHome, entry);
-  try {
-    // Preserve the launcher's established support for a symlinked Mosaic home,
-    // while pinning this read to the resolved directory. O_NOFOLLOW still
-    // rejects replacement of the identity file itself (or any child ancestor).
-    const canonicalHome = realpathSync(mosaicHome);
-    return readRegularFileSecure(join(canonicalHome, entry), {
-      root: canonicalHome,
-      maxBytes: MAX_IDENTITY_CONTRACT_BYTES,
-    }).content;
-  } catch (error: unknown) {
-    throw unsafeIdentityError('installed', configuredPath, error);
-  }
-}
-
-/**
- * Seed the generic identity base required by unattended fleet launches.
- *
- * Exact seat identity remains roster-owned and is injected later by the
- * runtime composer. Each destination appears atomically through a hard link to
- * a complete owner-private temporary file; a concurrent first seat may win the
- * link without allowing either process to overwrite operator content.
- */
-export function seedFleetIdentityDefaults(mosaicHome: string): string[] {
-  const snapshots = new Map<(typeof FLEET_IDENTITY_DEFAULTS)[number], Buffer>();
-
-  for (const entry of FLEET_IDENTITY_DEFAULTS) {
-    const destination = join(mosaicHome, entry);
-    if (installedEntryExists(destination)) {
-      readIdentityContract(mosaicHome, destination, 'installed');
-      continue;
-    }
-    const source = join(mosaicHome, 'defaults', entry);
-    snapshots.set(entry, readIdentityContract(mosaicHome, source, 'default'));
-  }
-
-  const seeded: string[] = [];
-  for (const [entry, content] of snapshots) {
-    const destination = join(mosaicHome, entry);
-    const temporary = join(
-      mosaicHome,
-      `.${entry}.fleet-seed-${process.pid.toString()}-${randomBytes(6).toString('hex')}`,
-    );
-    let temporaryCreated = false;
-    try {
-      writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
-      temporaryCreated = true;
-      if (linkIdentityContractNoClobber(temporary, destination)) {
-        seeded.push(entry);
-      } else {
-        readIdentityContract(mosaicHome, destination, 'installed');
-      }
-    } finally {
-      if (temporaryCreated) rmSync(temporary, { force: true });
-    }
-  }
-
-  for (const entry of FLEET_IDENTITY_DEFAULTS) {
-    readIdentityContract(mosaicHome, join(mosaicHome, entry), 'installed');
-  }
-  return seeded;
-}
@@ -1,393 +0,0 @@
-import { spawn, spawnSync, type SpawnSyncReturns } from 'node:child_process';
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  statSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
-
-const CLI_PATH = fileURLToPath(new URL('../../dist/cli.js', import.meta.url));
-const DEFAULT_SOUL_PATH = fileURLToPath(
-  new URL('../../framework/defaults/SOUL.md', import.meta.url),
-);
-const DEFAULT_USER_PATH = fileURLToPath(
-  new URL('../../framework/defaults/USER.md', import.meta.url),
-);
-
-interface GreenfieldFixture {
-  readonly root: string;
-  readonly home: string;
-  readonly mosaicHome: string;
-  readonly binDir: string;
-  readonly capturePath: string;
-}
-
-interface AsyncLaunchResult {
-  readonly status: number | null;
-  readonly signal: NodeJS.Signals | null;
-  readonly stdout: string;
-  readonly stderr: string;
-}
-
-const fixtures: string[] = [];
-
-function writeFixture(path: string, content: string, mode: number = 0o600): void {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  writeFileSync(path, content, { encoding: 'utf8', mode });
-  chmodSync(path, mode);
-}
-
-function createGreenfieldFixture(): GreenfieldFixture {
-  const root = mkdtempSync(join(tmpdir(), 'mosaic-first-start-'));
-  fixtures.push(root);
-  const home = join(root, 'home');
-  const mosaicHome = join(home, '.config', 'mosaic');
-  const binDir = join(root, 'bin');
-  const capturePath = join(root, 'runtime-boundary.json');
-
-  mkdirSync(binDir, { recursive: true, mode: 0o700 });
-  writeFixture(join(mosaicHome, 'AGENTS.md'), '# Agent dispatcher\n');
-  writeFixture(join(mosaicHome, 'runtime', 'pi', 'RUNTIME.md'), '# Pi runtime\n');
-  writeFixture(join(mosaicHome, 'defaults', 'SOUL.md'), readFileSync(DEFAULT_SOUL_PATH, 'utf8'));
-  writeFixture(join(mosaicHome, 'defaults', 'USER.md'), readFileSync(DEFAULT_USER_PATH, 'utf8'));
-  writeFixture(
-    join(mosaicHome, 'fleet', 'roster.yaml'),
-    `version: 1
-transport: tmux
-tmux:
-  socket_name: mosaic-fleet
-  holder_session: _holder
-defaults:
-  working_directory: ~
-runtimes:
-  pi:
-    reset_command: /new
-agents:
-  - name: unattended-seat
-    runtime: pi
-    class: worker
-`,
-  );
-  writeFixture(
-    join(mosaicHome, 'tools', 'tmux', 'agent-send.sh'),
-    '#!/usr/bin/env bash\nexit 0\n',
-    0o755,
-  );
-  writeFixture(
-    join(mosaicHome, 'tools', 'lease-broker', 'launch-runtime.py'),
-    `#!/usr/bin/env python3
-import json
-import os
-import pathlib
-import sys
-pathlib.Path(os.environ["MOSAIC_TEST_RUNTIME_CAPTURE"]).write_text(
-    json.dumps({"argv": sys.argv[1:]}), encoding="utf-8"
-)
-`,
-    0o755,
-  );
-  // checkRuntime() must find Pi, while the fake broker boundary prevents this
-  // executable from running or making a provider call.
-  writeFixture(join(binDir, 'pi'), '#!/usr/bin/env bash\nexit 97\n', 0o755);
-
-  return { root, home, mosaicHome, binDir, capturePath };
-}
-
-function launchEnvironment(
-  fixture: GreenfieldFixture,
-  capturePath: string,
-  fleet: boolean = true,
-  agentName: string = 'unattended-seat',
-  agentClass: string = 'worker',
-): NodeJS.ProcessEnv {
-  return {
-    HOME: fixture.home,
-    MOSAIC_HOME: fixture.mosaicHome,
-    ...(fleet
-      ? {
-          MOSAIC_AGENT_NAME: agentName,
-          MOSAIC_AGENT_CLASS: agentClass,
-        }
-      : {}),
-    MOSAIC_TEST_RUNTIME_CAPTURE: capturePath,
-    PATH: `${fixture.binDir}:/usr/bin:/bin`,
-  };
-}
-
-function launchSync(
-  fixture: GreenfieldFixture,
-  options: {
-    readonly capturePath?: string;
-    readonly fleet?: boolean;
-    readonly agentName?: string;
-    readonly agentClass?: string;
-  } = {},
-): SpawnSyncReturns<string> {
-  const capturePath = options.capturePath ?? fixture.capturePath;
-  return spawnSync(process.execPath, [CLI_PATH, 'yolo', 'pi'], {
-    cwd: fixture.root,
-    encoding: 'utf8',
-    input: '',
-    timeout: 10_000,
-    env: launchEnvironment(
-      fixture,
-      capturePath,
-      options.fleet ?? true,
-      options.agentName ?? 'unattended-seat',
-      options.agentClass ?? 'worker',
-    ),
-  });
-}
-
-function launchAsync(fixture: GreenfieldFixture, capturePath: string): Promise<AsyncLaunchResult> {
-  return new Promise<AsyncLaunchResult>((resolve, reject): void => {
-    const child = spawn(process.execPath, [CLI_PATH, 'yolo', 'pi'], {
-      cwd: fixture.root,
-      env: launchEnvironment(fixture, capturePath),
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-    child.stdout.on('data', (chunk: string): void => {
-      stdout += chunk;
-    });
-    child.stderr.on('data', (chunk: string): void => {
-      stderr += chunk;
-    });
-    child.on('error', reject);
-    child.on('close', (status: number | null, signal: NodeJS.Signals | null): void => {
-      resolve({ status, signal, stdout, stderr });
-    });
-    child.stdin.end();
-  });
-}
-
-function outputOf(result: { readonly stdout: string; readonly stderr: string }): string {
-  return `${result.stdout}${result.stderr}`;
-}
-
-function assertPrivateDefaultSeeds(fixture: GreenfieldFixture): void {
-  const soul = join(fixture.mosaicHome, 'SOUL.md');
-  const user = join(fixture.mosaicHome, 'USER.md');
-  expect(readFileSync(soul, 'utf8')).toBe(readFileSync(DEFAULT_SOUL_PATH, 'utf8'));
-  expect(readFileSync(user, 'utf8')).toBe(readFileSync(DEFAULT_USER_PATH, 'utf8'));
-  expect(statSync(soul).mode & 0o777).toBe(0o600);
-  expect(statSync(user).mode & 0o777).toBe(0o600);
-}
-
-function capturedArguments(path: string): string[] {
-  const capture = JSON.parse(readFileSync(path, 'utf8')) as { argv: string[] };
-  return capture.argv;
-}
-
-afterEach((): void => {
-  for (const root of fixtures.splice(0)) {
-    rmSync(root, { recursive: true, force: true });
-  }
-});
-
-describe('fleet unattended first start (#1264)', () => {
-  it('reaches the runtime boundary without a TTY or identity wizard on a clean install', () => {
-    const fixture = createGreenfieldFixture();
-    const result = launchSync(fixture);
-    const output = outputOf(result);
-
-    expect(result.error, output).toBeUndefined();
-    expect(result.status, output).toBe(0);
-    expect(output).toContain('Initialized unattended fleet identity defaults: SOUL.md, USER.md');
-    expect(output).not.toContain('Running setup wizard');
-    expect(output).not.toContain('What would you like to do?');
-    expect(existsSync(fixture.capturePath), output).toBe(true);
-    assertPrivateDefaultSeeds(fixture);
-
-    const argv = capturedArguments(fixture.capturePath);
-    expect(argv).toContain('--runtime');
-    expect(argv.join('\n')).toContain('Agent/session: `unattended-seat`');
-    expect(argv.join('\n')).toContain('Role/class: `worker`');
-  });
-
-  it('preserves existing operator identity bytes without requiring defaults', () => {
-    const fixture = createGreenfieldFixture();
-    const customSoul = '# Operator soul\nNever replace this.\n';
-    const customUser = '# Operator user\nNever replace this either.\n';
-    writeFixture(join(fixture.mosaicHome, 'SOUL.md'), customSoul, 0o640);
-    writeFixture(join(fixture.mosaicHome, 'USER.md'), customUser, 0o600);
-    rmSync(join(fixture.mosaicHome, 'defaults'), { recursive: true, force: true });
-
-    const first = launchSync(fixture);
-    const secondCapture = join(fixture.root, 'runtime-boundary-second.json');
-    const second = launchSync(fixture, { capturePath: secondCapture });
-
-    expect(first.status, outputOf(first)).toBe(0);
-    expect(second.status, outputOf(second)).toBe(0);
-    expect(readFileSync(join(fixture.mosaicHome, 'SOUL.md'), 'utf8')).toBe(customSoul);
-    expect(readFileSync(join(fixture.mosaicHome, 'USER.md'), 'utf8')).toBe(customUser);
-    expect(statSync(join(fixture.mosaicHome, 'SOUL.md')).mode & 0o777).toBe(0o640);
-    expect(existsSync(fixture.capturePath)).toBe(true);
-    expect(existsSync(secondCapture)).toBe(true);
-  });
-
-  it('seeds only the missing identity contract and leaves a custom SOUL byte-exact', () => {
-    const fixture = createGreenfieldFixture();
-    const customSoul = '# Exact custom soul bytes\n';
-    writeFixture(join(fixture.mosaicHome, 'SOUL.md'), customSoul, 0o640);
-
-    const result = launchSync(fixture);
-
-    expect(result.status, outputOf(result)).toBe(0);
-    expect(outputOf(result)).toContain('Initialized unattended fleet identity defaults: USER.md');
-    expect(readFileSync(join(fixture.mosaicHome, 'SOUL.md'), 'utf8')).toBe(customSoul);
-    expect(statSync(join(fixture.mosaicHome, 'SOUL.md')).mode & 0o777).toBe(0o640);
-    expect(readFileSync(join(fixture.mosaicHome, 'USER.md'), 'utf8')).toBe(
-      readFileSync(DEFAULT_USER_PATH, 'utf8'),
-    );
-  });
-
-  it('fails closed without a wizard or partial seed when a required default is missing', () => {
-    const fixture = createGreenfieldFixture();
-    const missingDefault = join(fixture.mosaicHome, 'defaults', 'USER.md');
-    rmSync(missingDefault);
-
-    const result = launchSync(fixture);
-    const output = outputOf(result);
-
-    expect(result.status, output).toBe(1);
-    expect(output).toContain('unattended fleet identity initialization failed');
-    expect(output).toContain(missingDefault);
-    expect(output).not.toContain('Running setup wizard');
-    expect(output).not.toContain('What would you like to do?');
-    expect(existsSync(fixture.capturePath)).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'USER.md'))).toBe(false);
-  });
-
-  it('rejects a symlinked identity default without following it or prompting', () => {
-    const fixture = createGreenfieldFixture();
-    const soulDefault = join(fixture.mosaicHome, 'defaults', 'SOUL.md');
-    rmSync(soulDefault);
-    symlinkSync(DEFAULT_SOUL_PATH, soulDefault);
-
-    const result = launchSync(fixture);
-    const output = outputOf(result);
-
-    expect(result.status, output).toBe(1);
-    expect(output).toContain(`fleet identity default is unavailable or unsafe: ${soulDefault}`);
-    expect(output).not.toContain('Running setup wizard');
-    expect(existsSync(fixture.capturePath)).toBe(false);
-  });
-
-  it('refuses an unknown ambient fleet name before seeding or prompting', () => {
-    const fixture = createGreenfieldFixture();
-
-    const result = launchSync(fixture, { agentName: 'not-in-the-roster' });
-    const output = outputOf(result);
-
-    expect(result.status, output).toBe(1);
-    expect(output).toContain('canonical fleet identity is unavailable');
-    expect(output).toContain('Agent "not-in-the-roster" is not in the fleet roster');
-    expect(output).not.toContain('Running setup wizard');
-    expect(existsSync(fixture.capturePath)).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'USER.md'))).toBe(false);
-  });
-
-  it('refuses a mismatched ambient fleet class before seeding or prompting', () => {
-    const fixture = createGreenfieldFixture();
-
-    const result = launchSync(fixture, { agentClass: 'reviewer' });
-    const output = outputOf(result);
-
-    expect(result.status, output).toBe(1);
-    expect(output).toContain('Refusing split identity authority');
-    expect(output).not.toContain('Running setup wizard');
-    expect(existsSync(fixture.capturePath)).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'USER.md'))).toBe(false);
-  });
-
-  it.each(['', ' ', '\t'])(
-    'refuses explicit blank ambient fleet class %j before seeding',
-    (agentClass: string) => {
-      const fixture = createGreenfieldFixture();
-
-      const result = launchSync(fixture, { agentClass });
-      const output = outputOf(result);
-
-      expect(result.status, output).toBe(1);
-      expect(output).toContain('Refusing split identity authority');
-      expect(output).not.toContain('Running setup wizard');
-      expect(existsSync(fixture.capturePath)).toBe(false);
-      expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-      expect(existsSync(join(fixture.mosaicHome, 'USER.md'))).toBe(false);
-    },
-  );
-
-  it.each([' unattended-seat', 'unattended-seat ', ''])(
-    'refuses non-exact ambient fleet name %j before seeding',
-    (agentName: string) => {
-      const fixture = createGreenfieldFixture();
-
-      const result = launchSync(fixture, { agentName });
-      const output = outputOf(result);
-
-      expect(result.status, output).toBe(1);
-      expect(output).toContain(
-        'MOSAIC_AGENT_NAME must be a non-empty exact roster name with no surrounding whitespace',
-      );
-      expect(output).not.toContain('Running setup wizard');
-      expect(existsSync(fixture.capturePath)).toBe(false);
-      expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-      expect(existsSync(join(fixture.mosaicHome, 'USER.md'))).toBe(false);
-    },
-  );
-
-  it('keeps the interactive wizard path for a standalone launch', () => {
-    const fixture = createGreenfieldFixture();
-
-    const result = launchSync(fixture, { fleet: false });
-    const output = outputOf(result);
-
-    expect(result.status, output).toBe(1);
-    expect(output).toContain('[mosaic] SOUL.md not found. Running setup wizard...');
-    expect(output).toContain('What would you like to do?');
-    expect(output).toContain('[mosaic] Setup failed. Run: mosaic wizard');
-    expect(existsSync(fixture.capturePath)).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-  });
-
-  it('allows concurrent no-TTY seats to initialize the same defaults without clobber or residue', async () => {
-    const fixture = createGreenfieldFixture();
-    const captures = Array.from({ length: 4 }, (_, index) =>
-      join(fixture.root, `runtime-boundary-${index.toString()}.json`),
-    );
-
-    const results = await Promise.all(
-      captures.map(
-        async (capturePath): Promise<AsyncLaunchResult> => launchAsync(fixture, capturePath),
-      ),
-    );
-
-    for (const result of results) {
-      expect(result.status, outputOf(result)).toBe(0);
-      expect(result.signal, outputOf(result)).toBeNull();
-      expect(outputOf(result)).not.toContain('Running setup wizard');
-    }
-    assertPrivateDefaultSeeds(fixture);
-    expect(captures.every((capturePath) => existsSync(capturePath))).toBe(true);
-    expect(
-      readdirSync(fixture.mosaicHome).filter((entry) => entry.includes('.fleet-seed-')),
-    ).toEqual([]);
-  });
-});
@@ -30,10 +30,6 @@ import { readRegularFileSecure } from '../fleet/secure-file.js';
 import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
 import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
-import {
-  readInstalledIdentityContractAtPointOfUse,
-  seedFleetIdentityDefaults,
-} from './fleet-first-start-identity.js';
 import { runLeaseEnforcementDoctorCheck } from './lease-doctor-check.js';

 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
@@ -234,55 +230,8 @@ function checkRuntime(cmd: string): void {
  }
 }

-function assertAmbientFleetClassMatches(canonicalName: string, canonicalClass: string): void {
-  const configuredClass = process.env['MOSAIC_AGENT_CLASS'];
-  if (configuredClass === undefined) return;
-
-  const ambientClass = canonicalizeRoleClass(configuredClass).canonicalClass;
-  if (ambientClass !== canonicalClass) {
-    throw new Error(
-      `Ambient MOSAIC_AGENT_CLASS resolves to "${ambientClass}" but canonical roster member "${canonicalName}" resolves to "${canonicalClass}". Refusing split identity authority.`,
-    );
-  }
-}
-
 function checkSoul(): void {
  const soulPath = join(MOSAIC_HOME, 'SOUL.md');
-  const fleetAgentName = process.env['MOSAIC_AGENT_NAME'];
-  if (fleetAgentName !== undefined) {
-    try {
-      if (fleetAgentName.length === 0 || fleetAgentName !== fleetAgentName.trim()) {
-        throw new Error(
-          'MOSAIC_AGENT_NAME must be a non-empty exact roster name with no surrounding whitespace',
-        );
-      }
-      const fleetIdentity = resolveFleetIdentity(MOSAIC_HOME, fleetAgentName);
-      if (!fleetIdentity.ok || !fleetIdentity.identity) {
-        throw new Error(
-          `canonical fleet identity is unavailable: ${fleetIdentity.error ?? 'exact roster member was not resolved'}`,
-        );
-      }
-      assertAmbientFleetClassMatches(
-        fleetIdentity.identity.member.name,
-        fleetIdentity.identity.member.className,
-      );
-      const seeded = seedFleetIdentityDefaults(MOSAIC_HOME);
-      if (seeded.length > 0) {
-        console.log(
-          `[mosaic] Initialized unattended fleet identity defaults: ${seeded.join(', ')}. Exact seat identity remains roster-owned.`,
-        );
-      }
-      return;
-    } catch (error: unknown) {
-      const reason = error instanceof Error ? error.message : String(error);
-      console.error(`[mosaic] ERROR: unattended fleet identity initialization failed: ${reason}`);
-      console.error(
-        '[mosaic] Repair the named fleet roster, launch identity, installed contract, or shipped default, then retry.',
-      );
-      process.exit(1);
-    }
-  }
-
  if (!existsSync(soulPath)) {
    console.log('[mosaic] SOUL.md not found. Running setup wizard...');

@@ -583,27 +532,26 @@ For required push/merge/issue-close/release actions, execute without routine con
  parts.push(readFileSync(join(mosaicHome, 'AGENTS.md'), 'utf-8'));

  // USER.md (+ USER.local.md operator overlay, appended directly under the
-  // profile its base owns). Fleet first start is Linux/systemd-owned and uses
-  // the no-follow reader at point of use. Standalone launches retain the
-  // portable tolerant path used on macOS and other supported hosts.
-  const fleetAgentName = process.env['MOSAIC_AGENT_NAME'];
-  const user =
-    fleetAgentName === undefined
-      ? readOptional(join(mosaicHome, 'USER.md'))
-      : readInstalledIdentityContractAtPointOfUse(mosaicHome, 'USER.md').toString('utf8');
+  // profile its base owns).
+  const user = readOptional(join(mosaicHome, 'USER.md'));
  if (user) parts.push('\n\n# User Profile\n\n' + user);
  const userLocal = readOptional(join(mosaicHome, 'USER.local.md'));
  if (userLocal.trim()) {
    parts.push('\n\n## Operator Overlay (USER.local.md)\n\n' + userLocal);
  }

-  const fleetIdentity = resolveFleetIdentity(mosaicHome, fleetAgentName);
+  const fleetIdentity = resolveFleetIdentity(mosaicHome, process.env['MOSAIC_AGENT_NAME']);
  if (!fleetIdentity.ok) {
    throw new Error(`Fleet communications contract unavailable: ${fleetIdentity.error}`);
  }
  const canonicalMember = fleetIdentity.identity?.member;
-  if (canonicalMember) {
-    assertAmbientFleetClassMatches(canonicalMember.name, canonicalMember.className);
+  if (canonicalMember && process.env['MOSAIC_AGENT_CLASS']?.trim()) {
+    const ambientClass = canonicalizeRoleClass(process.env['MOSAIC_AGENT_CLASS']).canonicalClass;
+    if (ambientClass !== canonicalMember.className) {
+      throw new Error(
+        `Ambient MOSAIC_AGENT_CLASS resolves to "${ambientClass}" but canonical roster member "${canonicalMember.name}" resolves to "${canonicalMember.className}". Refusing split identity authority.`,
+      );
+    }
  }

  // TOOLS.md
Author	SHA1	Message	Date
fargo	8eb8e7cfce	Merge remote-tracking branch 'origin/next' into fix/1280-identity-first-resolution ci/woodpecker/pr/ci Pipeline was successful Details # Conflicts: # packages/mosaic/package.json	2026-08-17 16:24:43 -05:00
jason.woltje	8199261caa	Merge pull request 'fix(ci): unwire test-start-agent-session.sh, restore its signed exclusion — unblocks every PR on next' (#1270 ) from fix/1269-ci-chain-unblock into next ci/woodpecker/push/publish Pipeline failed Details Reviewed-on: #1270	2026-08-17 20:44:59 +00:00
fargo	d789a43cae	test(git): hermetic fixtures for issue-create harnesses (#1282-#1287) ci/woodpecker/pr/ci Pipeline was canceled Details test-issue-create-body-safety.sh and test-issue-create-interactive-auth.sh inherited the seat's real HOME and global git config. With the #1280 fix activating identity mode BEFORE the tea path, a workstation-global mosaic.gitIdentity resolved inside the fixture repo, and the wrapper's API fallback posted to the LIVE forge with a real per-slot token — six real issues (#1282-#1287, authored mos-dt-0, closed with provenance by fred within the hour). Neutralize the source the resolver actually reads, and prove it by making the resolution fail. A control that does not make the thing fail has not been shown to control it. The earlier attempted neutralization pinned MOSAIC_CREDENTIALS_FILE to a fake — a real guard aimed at an adjacent input: the identity arm reads the per-slot token file directly and never consults credentials.json. Hence env -i with a fake HOME and GIT_CONFIG_GLOBAL=/dev/null (severing the global identity) rather than one more targeted variable, plus a curl tripwire stub in the body-safety harness so ANY provider request is a loud test failure instead of a live write.	2026-08-17 15:19:04 -05:00
fargo	19ad93999f	fix(git): identity-first principal resolution across write wrappers (#1280 ) MOSAIC_GIT_IDENTITY=fargo produced objects attributed to mos-dt-0: every write wrapper resolved its acting principal from tea's login list, which enumerates whatever logins the host happens to hold and knows nothing about which seat is calling. The identity-aware code was present and correct but unreachable on the happy path — it sat on arms that only ran when tea failed. One shared resolver, not twenty patches: resolve_gitea_principal() in detect-platform.sh implements the precedence (explicit --login beats MOSAIC_GIT_IDENTITY / worktree git config mosaic.gitIdentity; the tea login list is the LAST resort), fails loud (nonzero, naming the identity or login and the expected slot path) when the requested principal has no credential, and never prints a token value. gitea_identity_token_slot() is the single source of truth for the slot layout, shared with get_gitea_token, so resolver and token resolution cannot disagree. Call-site conversions (the proving five): pr-review.sh (principal resolved once for every action; the comment action now honors --login), issue-comment.sh, pr-create.sh (identity mode reaches the REST API on the HAPPY path — tea is never consulted, so the login list cannot shadow the identity; --login wins even on the tea-failure fallback arm), issue-create.sh (same), pr-merge.sh (gains --login; --dry-run reports the principal the merge WOULD act as, resolved exactly as the merge resolves it; no cross-principal fallback — an identity-bound 401 is a hard stop). Remaining wrappers are call-site conversions onto the same resolver, measured: write-path issue-assign, issue-close, issue-edit, issue-reopen, milestone-close, milestone-create, pr-close; read-path issue-list, milestone-list, pr-list, pr-view (issue-view mixed). pr-diff, pr-metadata, pr-ci-wait and ci-queue-wait already inherit identity-first resolution via get_gitea_token. Known interaction: on a host with a workstation-GLOBAL mosaic.gitIdentity, this fix activates identity mode for every seat that has not set a local one — correct behavior driven by a wrong configuration (measured: #1282-#1287, six accidental live issues, closed with provenance by fred). Set mosaic.gitIdentity per-worktree, never --global. Tests: test-gitea-principal-resolution.sh (resolver matrix — identity present/absent, --login precedence, env vs git-config, unrecognized-host containment, slot-path-by-path-never-by-value); test-pr-create-identity- first.sh (the load-bearing ordering test: identity arm REACHED on the happy path with tea never invoked, fail-loud BEFORE any write on a missing slot, --login wins, default preserved); test-pr-merge-principal- resolution.sh (dry-run truthfulness, merge credential binding, unknown --login never reaches the provider). All wired into test:framework-shell. Sabotage control: precedence inverted to tea-list-first inside the resolver -> exactly the three new suites redden with the #1280 signatures (identity resolves to the tea-list account; missing slot returns rc=0 with silent fallthrough) while all 11 pre-existing git suites stay green; restored byte-identical (sha256 verified); all 14 green again.	2026-08-17 15:18:54 -05:00
fred	57a2f2b40e	docs(ci): point the exclusion at tracking issue #1271 , not the closed first filing ci/woodpecker/pr/ci Pipeline was successful Details 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 ) ci/woodpecker/pr/ci Pipeline was canceled Details 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