fix(git-wrappers): no --login must use the caller's own credential, not a guessed shared login (#1352)

Co-authored-by: fargo <[email protected]>

.mosaic/repo.json

@@ -0,0 +1,4 @@
+{
+  "integration_trunk": "next",
+  "release_branch": "main"
+}

.woodpecker/ci.yml

@@ -21,11 +21,19 @@ variables:
   - &enable_pnpm 'corepack enable'
 
 when:
-  # PR + manual CI run on any branch — the pull_request pipeline is the merge gate.
+  # PR + manual CI run on any branch: the pull_request pipeline is the merge
-  # push CI is restricted to protected branches (main) so a feature-branch push no
+  # gate (next is protected and the default branch since 2026-08-19).
-  # longer fires a redundant SECOND pipeline alongside its PR pipeline. This ~halves
+  # Push CI runs on main only. next deliberately runs NO push ci: post-merge
-  # CI load on the storage-constrained runner with zero loss of gating (branch
+  # verification on next is carried by publish.yml's `verify` step
-  # protection requires no push/ci status context; main still gets full push CI).
+  # (pnpm verify:release), which mirrors this pipeline's complete mandatory
+  # set step-for-step, enforced by scripts/verify-release.test.mjs. PR CI
+  # tests the PR HEAD tree (refs/pull/N/head, measured 2026-08-19), not a
+  # merge ref, so if next advances before a merge the landed tree differs
+  # from the tested one; publish verify re-runs the full set on the landed
+  # tree (PGlite path). Measured 2026-08-19: the 21 most recent push events
+  # on next each ran exactly one pipeline (publish), zero ci.
+  # Keeping push ci off next also avoids a redundant second full-suite run
+  # per merge on the storage-constrained runner.
   - event: [pull_request, manual]
   - event: push
     branch: main

AGENTS.md

@@ -81,6 +81,73 @@ pnpm format:check  # Prettier check
 pnpm build         # Build all packages and applications
 ```
 
+## Branch Model and Merge Process — `main` and `next` (CANONICAL)
+
+**Every contribution targets `next` first. No exceptions.** Features, fixes, tests,
+docs, and policy changes all take the same route; urgency changes queue priority,
+never the route. Agents never commit to or merge into `main`.
+
+| Branch | Role                                                             | Who merges into it                                                          |
+| ------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `next` | Integration trunk — the only PR target for contributions         | The designated merge-gate agent, after all gates pass. Never the PR author. |
+| `main` | Stable/release line — receives promotion merges from `next` only | Jason only (or an agent he explicitly delegates for a named promotion).     |
+
+### Contribution sequencing (in order, no skipping)
+
+1. **Issue first.** Work is tracked in a Gitea issue before a branch exists. The
+   issue number appears in the branch name and the PR body.
+2. **Branch from the current `origin/next` head.** Name it
+   `feat/…`, `fix/…`, `docs/…`, or `test/…` with the issue number
+   (e.g. `docs/1214-branch-process`). Record the base SHA in the PR body.
+3. **Develop with evidence.** Applicable tests accompany the change. Hooks are
+   never bypassed (`--no-verify` is prohibited). Stage explicit paths — never
+   `git add -A`.
+4. **Open the PR against `next`.** The body states: scope, base SHA,
+   verification commands with results, and any known pre-existing failures on
+   the base — documented, not retried to green and not absorbed silently.
+5. **CI must be terminal-green on the exact head.** All bounded Woodpecker
+   steps succeed (`verify-terminal-green` contract). Pipelines for fork PRs
+   start `blocked`; a maintainer approves the run — approving CI is not
+   approving the PR.
+6. **Independent review. Self-merge is prohibited** — for every agent, on every
+   PR, including trivial ones. Where the change touches protected or
+   contract-bearing content, the reviewer verifies the exact head
+   (exact-byte/exact-blob comparison), not a description of it. An `AMEND`
+   verdict returns the PR to its author; the reviewer's gate stays held until
+   a fresh exact head passes.
+7. **Merge into `next`** happens only after CI green + review pass, pinned to
+   the reviewed head SHA (a post-review push voids the review).
+8. **Promotion `next` → `main`** is a deliberate, Jason-owned reconciliation
+   merge — not part of any contribution's lifecycle. Contributors are done at
+   step 7.
+
+### Responsibilities
+
+- **Contributor** — base pinning, green CI, evidence in the PR body,
+  responding to AMEND verdicts, never merging own work.
+- **Reviewer / merge gate** — independent verification on the exact head;
+  holds and lifts gates; executes the merge into `next`.
+- **Orchestrator / adjudicator** — cross-PR sequencing, disposition when PRs
+  collide, conflict adjudication.
+- **Jason** — `next` → `main` promotions, merge-authority grants, collaborator
+  and token provisioning. Agents cannot grant themselves or each other any of
+  these.
+
+### Hotfixes and divergence
+
+- A hotfix follows the same path: branch from `next`, PR to `next`, gates,
+  merge, then an expedited Jason-owned promotion if `main` needs it urgently.
+  Committing the fix to `main` directly is prohibited even under pressure.
+- **Never land work on `main` that is not on `next`.** This has happened
+  (issue #1152's goal controller reached `main` without reaching `next`) and
+  every later PR paid for it. If it happens anyway: transplant the work onto
+  a `next`-based branch with provenance-preserving commits
+  (`git cherry-pick -x` or explicit SHA references in the messages), PR it
+  through the normal gates, and let promotion re-align `main`. Do not
+  hand-patch `main` to compensate.
+- Force-pushing a branch you do not own is prohibited; rebasing your own PR
+  branch is fine before review, and voids any review already given.
+
 ## Database and Local Runtime Safety
 
 - Current local data-layer work uses in-process PGlite; leave `DATABASE_URL` unset.

apps/gateway/src/__tests__/required-security-wiring.test.ts

@@ -0,0 +1,332 @@
+import { type Type } from '@nestjs/common';
+import { Test, type TestingModule } from '@nestjs/testing';
+import type { SlashCommandPayload } from '@mosaicstack/types';
+import { describe, expect, it, vi } from 'vitest';
+import { AgentService, type AgentSession } from '../agent/agent.service.js';
+import { ProviderService } from '../agent/provider.service.js';
+import { AppModule } from '../app.module.js';
+import { CommandAuthorizationService } from '../commands/command-authorization.service.js';
+import { CommandExecutorService } from '../commands/command-executor.service.js';
+import { CommandsModule } from '../commands/commands.module.js';
+import { CommandRuntimeApprovalVerifier } from '../commands/runtime-approval-verifier.js';
+import { PreferencesModule } from '../preferences/preferences.module.js';
+import { SystemOverrideService } from '../preferences/system-override.service.js';
+
+const fakeDb = {
+  $client: { exec: async (): Promise<void> => {} },
+  execute: async (): Promise<{ rows: unknown[] }> => ({ rows: [] }),
+  select: () => ({
+    from: () => ({
+      where: async (): Promise<Array<{ count: number }>> => [{ count: 1 }],
+    }),
+  }),
+  insert: () => ({ values: async (): Promise<void> => {} }),
+};
+
+const fakeProviderService = {
+  onModuleInit: async (): Promise<void> => {},
+  onModuleDestroy: (): void => {},
+  getRegistry: () => ({ getAvailable: () => [], getAll: () => [], find: () => undefined }),
+  getDefaultModel: () => undefined,
+  listAvailableModels: () => [],
+  listProviders: () => [],
+  getAdapter: () => undefined,
+  getProvidersHealth: () => [],
+};
+
+function compileRealAppGraph(): Promise<TestingModule> {
+  return Test.createTestingModule({ imports: [AppModule] })
+    .overrideProvider('DB_HANDLE')
+    .useValue({ db: fakeDb, close: async (): Promise<void> => {} })
+    .overrideProvider('DB')
+    .useValue(fakeDb)
+    .overrideProvider('STORAGE_ADAPTER')
+    .useValue({
+      name: 'required-security-wiring-test',
+      migrate: async (): Promise<void> => {},
+      close: async (): Promise<void> => {},
+    })
+    .overrideProvider('AUTH')
+    .useValue({})
+    .overrideProvider('BRAIN')
+    .useValue({ conversations: {}, agents: {} })
+    .overrideProvider('LOG_SERVICE')
+    .useValue({})
+    .overrideProvider('MEMORY')
+    .useValue({})
+    .overrideProvider('MEMORY_ADAPTER')
+    .useValue({})
+    .overrideProvider(ProviderService)
+    .useValue(fakeProviderService)
+    .compile();
+}
+
+function providerToken(provider: unknown): unknown {
+  return typeof provider === 'function' ? provider : (provider as { provide?: unknown })?.provide;
+}
+
+interface MaskingConsumer {
+  moduleType: Type<unknown>;
+  token: Type<unknown>;
+  useValue: object;
+}
+
+async function compileWithoutProvider(
+  moduleType: Type<unknown>,
+  missingToken: Type<unknown>,
+  maskingConsumer: MaskingConsumer,
+): Promise<{ error: unknown; moduleRef: TestingModule | undefined }> {
+  const touchedModules = new Set([moduleType, maskingConsumer.moduleType]);
+  const originals = Array.from(touchedModules, (touchedModule: Type<unknown>) => ({
+    moduleType: touchedModule,
+    providers: (Reflect.getMetadata('providers', touchedModule) ?? []) as unknown[],
+    exports: (Reflect.getMetadata('exports', touchedModule) ?? []) as unknown[],
+  }));
+
+  for (const original of originals) {
+    const providers = original.providers.flatMap((provider: unknown): unknown[] => {
+      const token = providerToken(provider);
+      if (original.moduleType === moduleType && token === missingToken) return [];
+      if (original.moduleType === maskingConsumer.moduleType && token === maskingConsumer.token) {
+        return [{ provide: maskingConsumer.token, useValue: maskingConsumer.useValue }];
+      }
+      return [provider];
+    });
+    const exports = original.exports.filter(
+      (exported: unknown): boolean =>
+        original.moduleType !== moduleType || providerToken(exported) !== missingToken,
+    );
+    Reflect.defineMetadata('providers', providers, original.moduleType);
+    Reflect.defineMetadata('exports', exports, original.moduleType);
+  }
+
+  let moduleRef: TestingModule | undefined;
+  let error: unknown;
+  try {
+    moduleRef = await compileRealAppGraph();
+  } catch (caught: unknown) {
+    error = caught;
+  } finally {
+    for (const original of originals) {
+      Reflect.defineMetadata('providers', original.providers, original.moduleType);
+      Reflect.defineMetadata('exports', original.exports, original.moduleType);
+    }
+  }
+  return { error, moduleRef };
+}
+
+async function closeIfCompiled(moduleRef: TestingModule | undefined): Promise<void> {
+  if (moduleRef) await moduleRef.close();
+}
+
+describe('required security wiring — real AppModule startup refusal', () => {
+  it('FL-01 positive control: the real graph compiles when CommandAuthorizationService is bound', async () => {
+    const moduleRef = await compileRealAppGraph();
+    try {
+      expect(moduleRef.get(CommandAuthorizationService, { strict: false })).toBeInstanceOf(
+        CommandAuthorizationService,
+      );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('FL-01 negative control: absence read as permission is refused at module compilation', async () => {
+    const { error, moduleRef } = await compileWithoutProvider(
+      CommandsModule,
+      CommandAuthorizationService,
+      {
+        moduleType: CommandsModule,
+        token: CommandRuntimeApprovalVerifier,
+        useValue: {},
+      },
+    );
+    await closeIfCompiled(moduleRef);
+
+    expect(
+      error,
+      'absence read as permission: AppModule compilation accepted a missing CommandAuthorizationService binding',
+    ).toBeInstanceOf(Error);
+    if (!(error instanceof Error)) return;
+    expect(error.message).toContain('CommandExecutorService');
+    expect(error.message).toContain('CommandAuthorizationService');
+  });
+
+  it('FL-11 positive control: the real graph compiles when SystemOverrideService is bound', async () => {
+    const moduleRef = await compileRealAppGraph();
+    try {
+      expect(moduleRef.get(SystemOverrideService, { strict: false })).toBeInstanceOf(
+        SystemOverrideService,
+      );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('FL-11 negative control: absence read as permission is refused at module compilation', async () => {
+    const { error, moduleRef } = await compileWithoutProvider(
+      PreferencesModule,
+      SystemOverrideService,
+      {
+        moduleType: CommandsModule,
+        token: CommandExecutorService,
+        useValue: {},
+      },
+    );
+    await closeIfCompiled(moduleRef);
+
+    expect(
+      error,
+      'absence read as permission: AppModule compilation accepted a missing SystemOverrideService binding',
+    ).toBeInstanceOf(Error);
+    if (!(error instanceof Error)) return;
+    expect(error.message).toContain('AgentService');
+    expect(error.message).toContain('SystemOverrideService');
+  });
+});
+
+const actorScope = { userId: 'security-user', tenantId: 'security-tenant' };
+const conversationId = 'security-conversation';
+
+function directExecutorWithoutAuthorization(systemOverrideSet: ReturnType<typeof vi.fn>) {
+  const registry = {
+    getManifest: vi.fn(() => ({
+      version: 1,
+      commands: [
+        {
+          name: 'system',
+          aliases: [],
+          description: 'Set instruction authority',
+          scope: 'agent' as const,
+          execution: 'socket' as const,
+          available: true,
+        },
+      ],
+      skills: [],
+    })),
+  };
+  return new CommandExecutorService(
+    registry as never,
+    { getSession: vi.fn() } as never,
+    { set: systemOverrideSet, clear: vi.fn() } as never,
+    { collect: vi.fn() } as never,
+    null,
+    { agents: {} } as never,
+    null,
+    null,
+    { getServerStatuses: vi.fn(() => []), getToolDefinitions: vi.fn(() => []) } as never,
+    undefined as never,
+  );
+}
+
+function directAgentWithoutSystemOverride(piPrompt: ReturnType<typeof vi.fn>): {
+  service: AgentService;
+  session: AgentSession;
+} {
+  const service = new AgentService(
+    {
+      getDefaultModel: vi.fn(() => null),
+      getRegistry: vi.fn(() => ({})),
+      findModel: vi.fn(),
+      listAvailableModels: vi.fn(() => []),
+    } as never,
+    {} as never,
+    {} as never,
+    { available: false } as never,
+    {} as never,
+    { getToolDefinitions: vi.fn(() => []) } as never,
+    { loadForSession: vi.fn(async () => ({ metaTools: [], promptAdditions: [] })) } as never,
+    undefined as never,
+    null,
+    { collect: vi.fn().mockResolvedValue(undefined) } as never,
+    null,
+  );
+  const session = {
+    id: conversationId,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: { prompt: piPrompt },
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: process.cwd(),
+    allowedTools: null,
+    userId: actorScope.userId,
+    tenantId: actorScope.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date(0).toISOString(),
+    },
+  } as unknown as AgentSession;
+  const internals = service as unknown as { sessions: Map<string, AgentSession> };
+  internals.sessions.set(conversationId, session);
+  return { service, session };
+}
+
+describe('required security wiring — malformed direct absence has zero effects', () => {
+  it('FL-01 refuses command execution before any command effect when authorization is absent', async () => {
+    const systemOverrideSet = vi.fn().mockResolvedValue(undefined);
+    const executor = directExecutorWithoutAuthorization(systemOverrideSet);
+    const payload: SlashCommandPayload = {
+      command: 'system',
+      args: 'authority that must not be stored',
+      conversationId,
+    };
+    let error: unknown;
+
+    try {
+      await executor.execute(payload, actorScope);
+    } catch (caught: unknown) {
+      error = caught;
+    }
+
+    expect
+      .soft(
+        error,
+        'absence read as permission: direct executor accepted missing command authorization',
+      )
+      .toBeInstanceOf(Error);
+    expect
+      .soft(
+        systemOverrideSet,
+        'absence read as permission: command effect occurred without command authorization',
+      )
+      .not.toHaveBeenCalled();
+  });
+
+  it('FL-11 refuses prompt execution before any provider or session effect when system override authority is absent', async () => {
+    const piPrompt = vi.fn().mockResolvedValue(undefined);
+    const { service, session } = directAgentWithoutSystemOverride(piPrompt);
+    let error: unknown;
+
+    try {
+      await service.prompt(conversationId, 'must not reach provider', actorScope);
+    } catch (caught: unknown) {
+      error = caught;
+    }
+
+    expect
+      .soft(
+        error,
+        'absence read as permission: direct session accepted missing system override authority',
+      )
+      .toBeInstanceOf(Error);
+    expect
+      .soft(
+        piPrompt,
+        'absence read as permission: provider prompt occurred without system override authority',
+      )
+      .not.toHaveBeenCalled();
+    expect
+      .soft(
+        session.promptCount,
+        'absence read as permission: session state changed without system override authority',
+      )
+      .toBe(0);
+  });
+});

apps/gateway/src/agent/__tests__/agent-service-ownership.test.ts

@@ -26,7 +26,7 @@ function makeService(operatorMemory: unknown = null): AgentService {
     {} as never,
     { getToolDefinitions: vi.fn(() => []) } as never,
     { loadForSession: vi.fn(async () => ({ metaTools: [], promptAdditions: [] })) } as never,
-    null,
+    { get: vi.fn().mockResolvedValue(null), renew: vi.fn().mockResolvedValue(undefined) } as never,
     null,
     { collect: vi.fn().mockResolvedValue(undefined) } as never,
     operatorMemory as never,

apps/gateway/src/agent/agent.service.ts

@@ -132,9 +132,8 @@ export class AgentService implements OnModuleDestroy {
     @Inject(CoordService) private readonly coordService: CoordService,
     @Inject(McpClientService) private readonly mcpClientService: McpClientService,
     @Inject(SkillLoaderService) private readonly skillLoaderService: SkillLoaderService,
-    @Optional()
     @Inject(SystemOverrideService)
-    private readonly systemOverride: SystemOverrideService | null,
+    private readonly systemOverride: SystemOverrideService,
     @Optional()
     @Inject(PreferencesService)
     private readonly preferencesService: PreferencesService | null,
@@ -709,23 +708,22 @@ export class AgentService implements OnModuleDestroy {
       throw new Error(`No agent session found: ${sessionId}`);
     }
     this.assertSessionScope(session, scope);
-    session.promptCount += 1;
 
     // Channel attachments are untrusted URI references. Preserve exact,
     // authenticated metadata for the agent without treating it as authority.
     const attachmentContext = this.attachmentContext(attachments);
 
-    // Prepend session-scoped system override if present (renew TTL on each turn)
+    // Prepend session-scoped system override if present (renew TTL on each turn).
+    // Required instruction-authority wiring is consulted before session/provider effects.
     let effectiveMessage = `${message}${attachmentContext}`;
-    if (this.systemOverride) {
+    const override = await this.systemOverride.get(sessionId, scope);
-      const override = await this.systemOverride.get(sessionId, scope);
+    if (override) {
-      if (override) {
+      effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
-        effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
+      await this.systemOverride.renew(sessionId, scope);
-        await this.systemOverride.renew(sessionId, scope);
+      this.logger.debug(`Applied system override for session ${sessionId}`);
-        this.logger.debug(`Applied system override for session ${sessionId}`);
-      }
     }
 
+    session.promptCount += 1;
     try {
       await session.piSession.prompt(effectiveMessage);
     } catch (err) {

apps/gateway/src/commands/command-executor-p8012.spec.ts

@@ -80,6 +80,10 @@ const mockMcpClient = {
   getToolDefinitions: vi.fn(() => []),
 };
 
+const allowAuthorization = {
+  authorize: vi.fn().mockResolvedValue({ allowed: true }),
+};
+
 function buildService(
   redis: typeof mockRedis | null = mockRedis,
   mcpClient: {
@@ -98,6 +102,7 @@ function buildService(
     null,
     mockChatGateway as never,
     mcpClient as never,
+    allowAuthorization as never,
   );
 }
 

apps/gateway/src/commands/command-executor.service.ts

@@ -35,9 +35,8 @@ export class CommandExecutorService {
     @Inject(forwardRef(() => ChatGateway))
     private readonly chatGateway: ChatGateway | null,
     @Inject(McpClientService) private readonly mcpClient: McpClientService,
-    @Optional()
     @Inject(CommandAuthorizationService)
-    private readonly authorization: CommandAuthorizationService | null = null,
+    private readonly authorization: CommandAuthorizationService,
   ) {}
 
   async execute(
@@ -57,13 +56,13 @@ export class CommandExecutorService {
       };
     }
 
-    const authorization = await this.authorization?.authorize(
+    const authorization = await this.authorization.authorize(
       def,
       payload,
       userId,
       payload.approvalId,
     );
-    if (authorization && !authorization.allowed) {
+    if (!authorization.allowed) {
       return { command, conversationId, success: false, message: authorization.reason };
     }
 
@@ -171,7 +170,7 @@ export class CommandExecutorService {
     const def = this.registry
       .getManifest()
       .commands.find((command) => command.name === payload.command);
-    if (!def || !this.authorization) return null;
+    if (!def) return null;
     return this.authorization.createApproval(def, payload, scope.userId);
   }
 

apps/gateway/src/commands/commands.integration.spec.ts

@@ -55,6 +55,10 @@ const mockMcpClient = {
   reconnectServer: vi.fn().mockResolvedValue(undefined),
 };
 
+const allowAuthorization = {
+  authorize: vi.fn().mockResolvedValue({ allowed: true }),
+};
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function buildRegistry(): CommandRegistryService {
@@ -74,6 +78,7 @@ function buildExecutor(registry: CommandRegistryService): CommandExecutorService
     null, // reloadService (optional)
     null, // chatGateway (optional)
     mockMcpClient as never,
+    allowAuthorization as never,
   );
 }
 

apps/gateway/src/reload/reload.service.spec.ts

@@ -159,6 +159,7 @@ describe('ReloadService — /reload command sanitizes plugin errors', () => {
       reloadService,
       mockChatGateway as never,
       mockMcpClient as never,
+      { authorize: vi.fn().mockResolvedValue({ allowed: true }) } as never,
     );
 
     const payload: SlashCommandPayload = { command: 'reload', conversationId: 'conv-1' };

docs/TASKS.md

@@ -1,5 +1,19 @@
 # Tasks — MVP (Top-Level Rollup)
 
+> ---
+>
+> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml`
+>
+> This file is the pre-backlog tracking mechanism. `NS-2` in the north star declares the
+> replacement: every backlog item is a Mosaic Backlog card projected from the YAML. That
+> model replaced this one and nobody retired the old file, so it kept reading as
+> authoritative while going stale.
+>
+> **Do not trust a status in this file.** Verified 2026-08-20: it was already behind the
+> code when it froze five weeks ago.
+>
+> Kept as a record of what was believed. Do not update it; update the YAML.
+
 > Single-writer: orchestrator only. Workers read but never modify.
 >
 > **Mission:** mvp-20260312
@@ -108,7 +122,7 @@ Active workstream is **W1 — Federation v1**. Workers should:
 
 ## north-star doctrine consolidation — doc PR — feat/north-star-doctrine
 
-- Status: applied Mos's consolidated merge-map to docs/fleet/north-star.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
+- Status: applied Mos's consolidated merge-map to docs/fleet/FLEET-DOCTRINE.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
 
 ## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
 

docs/federation/TASKS.md

@@ -1,5 +1,21 @@
 # Tasks — Federation v1
 
+> ---
+>
+> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml`
+>
+> This file is the pre-backlog tracking mechanism. `NS-2` in the north star declares the
+> replacement: every backlog item is a Mosaic Backlog card projected from the YAML. That
+> model replaced this one and nobody retired the old file, so it kept reading as
+> authoritative while going stale.
+>
+> **Do not trust a status in this file.** Verified 2026-08-20: it was already behind the
+> code when it froze five weeks ago. `FED-M3-06` is marked not-started and `get.controller.ts`
+> has existed for eight weeks; `FED-M3-10/11` claim no tests exist while fifteen spec files
+> do. `FED-M2-DEPLOY-IMG-FIX` names `apps/gateway/Dockerfile`, which is not in the repo.
+>
+> Kept as a record of what was believed. Do not update it; update the YAML.
+
 > Single-writer: orchestrator only. Workers read but never modify.
 >
 > **Mission:** federation-v1-20260419

docs/fleet/FLEET-DOCTRINE.md

@@ -1,9 +1,26 @@
-# Mosaic Fleet — North Star
+---
+kind: spec
+parent: docs/fleet/NORTH_STAR.yaml
+status: active
+---
 
+# Mosaic Fleet — Doctrine
+
+> **This is the WHY. `NORTH_STAR.yaml` is the WHAT and WHEN.**
+> Renamed from `north-star.md` on 2026-08-20. It sat one character away from the
+> generated `NORTH_STAR.md` in the same directory, and the two are read by different
+> populations — the PRDs and TASKS files cite this one, while the agent role contracts
+> and the generator spec cite the YAML pair. Same-name-different-thing was the confusion;
+> the content was never in conflict.
+>
+> **Nothing here overrides `NORTH_STAR.yaml`.** Where this document states a plan item,
+> the YAML is authoritative. Where it states a decision, a rationale, or a role
+> definition, this document is the record and the YAML carries none of it.
+>
 > **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312`
-> **Umbrella:** [docs/MISSION-MANIFEST.md](../MISSION-MANIFEST.md) · [docs/PRD.md](../PRD.md) (Mosaic Stack v0.1.0)
+> **Umbrella:** [docs/MISSION-MANIFEST.md](../MISSION-MANIFEST.md)
-> **Status:** doctrine — authored 2026-06-20. Owner of this file: Fleet workstream lead.
+> **Authored:** 2026-06-20. Owner: Fleet workstream lead.
-> This document does **not** modify the MVP rollup; a rollup row is proposed, not written here.
+> This document does **not** modify the MVP rollup.
 
 ## Vision
 
@@ -264,15 +281,17 @@ Dedicated Postgres **instance** vs. dedicated **schema** in the existing instanc
 Recommendation: dedicated schema, existing instance (a migration file, not new infra);
 re-evaluate if isolation or write-volume demands it.
 
-## Phased roadmap
+## Phased roadmap — SUPERSEDED
 
-| Phase                  | Outcome                                                                                                                                                                                                | Status  |
+Superseded 2026-08-20 by [`NORTH_STAR.yaml`](./NORTH_STAR.yaml), whose `goals` carry both
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+a `phase` (build order) and a `tier` (which promise the goal delivers). The five-phase
-| 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                                                                                 | ✅ done |
+table that stood here could not express those as separate axes, and its "Phase 2 —
-| **2 — Observability**  | fleet ps (host+tenant aware join), heartbeat protocol + dogfood stub answers it, agent watch (read-only), agent send --verify receipts                                                                 | ▶ now   |
+Observability ▶ now" row stayed unfalsified for two months because a phase has no exit
-| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)                                                              | planned |
+test. Tiers do: see `AC-NS-0` through `AC-NS-7`.
-| 4 — Unified definition | one agent schema in gateway; mosaic agent --new → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
+
-| 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)**            | planned |
+The phase-2 content itself is not lost — it is specified in
+[`PRD.md`](./PRD.md) (Fleet Phase 2: Operator Observability) and is now tracked as
+goals `I1`–`I5` at tier 0.
 
 ## Decisions of record (2026-06-20, with Jason)
 

docs/fleet/NORTH_STAR.md

@@ -3,7 +3,7 @@
 > **Generated file — do not edit by hand.**
 > Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure
 > generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).
-> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.
+> Edit the YAML, then regenerate. Self-contained Mosaic.
 
 ## Mission
 
@@ -11,7 +11,7 @@ A self-driving Mosaic system that 24/7 unattended converts a machine-readable go
 
 ## Substrate
 
-The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's native Postgres storage service (@mosaicstack/db drizzle; PGlite-embedded by default, full Postgres by config). NOT Hermes.
+The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's native Postgres storage service (@mosaicstack/db drizzle; PGlite-embedded by default, full Postgres by config).
 
 ## Standing objectives
 
@@ -24,16 +24,18 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 - **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
 - **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
 - **NS-9** — Mosaic is a general-purpose multi-agent system: the user declares the SYSTEM TYPE to run (e.g. software delivery, personal assistant, research, business/operations) and the orchestrator provisions the matching persona roster and org structure from a cross-domain baseline persona library; the delivery/coding fleet is one profile among many.
+- **NS-10** — An adoption is not complete until the mechanism it replaces is removed. Two live conventions for one concern is the defect, not a transition state. Measured 2026-08-20: brain-home adopted by 9 modules and not 10; MOSAIC_HOME honored in 4 places, each re-deriving it; backlog cards declared while TASKS.md files stayed authoritative. Every one was decided correctly and left half-applied.
 
 ## Success criteria
 
-- **AC-NS-1** — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
+- **AC-NS-0** (tier 0) — The operator launches an agent on any configured harness with one command, observes its state and sends it work without attaching to a terminal multiplexer.
-- **AC-NS-2** — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
+- **AC-NS-1** (tier 1) — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
-- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
+- **AC-NS-2** (tier 1) — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
-- **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
+- **AC-NS-3** (tier 1) — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
-- **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+- **AC-NS-4** (tier 1) — TTL is enforced on claims; token caps remain advisory until a real meter exists.
-- **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
+- **AC-NS-5** (tier 1) — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
-- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
+- **AC-NS-6** (tier 2) — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
+- **AC-NS-7** (tier 2) — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
 
 ## Workstreams
 
@@ -45,26 +47,44 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
 | D   | Merge-gate — single approver, pr-merge.sh after CI wait                                                     |
 | E   | Meta-loop — session-review + enhancer improvement PRs                                                       |
 | F   | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch                                                |
+| G   | Kill-switch — operator PAUSE honored before dispatch and merge                                              |
 | H   | Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization |
+| I   | Operator surface — launcher, fleet visibility, reliable steering (tier 0)                                   |
+| J   | Web control plane — browser surface over the gateway (tier 1)                                               |
+| K   | Clients — desktop and mobile over the same backend (tier 2)                                                 |
+| L   | Auth profiles — per-provider accounts, per-session selection (tier 2)                                       |
 
 ## Goals (backlog projection)
 
-| id  | title                                                                                                                                             | phase | priority    | depends_on |
+| id  | title                                                                                                                                                                                                                                                                                                                                                                              | tier | phase | priority    | depends_on     |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----- | ----------- | -------------- |
-| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                                                                                            | 1     | must-have   | —          |
+| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                                                                                                                                                                                                                                                                                                                             | 1    | 1     | must-have   | —              |
-| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)                                                                               | 1     | must-have   | A1         |
+| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)                                                                                                                                                                                                                                                                                                                | 1    | 1     | must-have   | A1             |
-| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG                                                                            | 1     | must-have   | A2         |
+| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG                                                                                                                                                                                                                                                                                                             | 1    | 1     | must-have   | A2             |
-| A3b | TTL-bounded claim enforcement (wall-clock) on cards                                                                                               | 1     | must-have   | A3a        |
+| A3b | TTL-bounded claim enforcement (wall-clock) on cards                                                                                                                                                                                                                                                                                                                                | 1    | 1     | must-have   | A3a            |
-| A4  | Advisory spend projection per card (degrades to TTL, no real meter)                                                                               | 1     | should-have | A3a        |
+| A4  | Advisory spend projection per card (degrades to TTL, no real meter)                                                                                                                                                                                                                                                                                                                | 1    | 1     | should-have | A3a            |
-| B1  | Supervisor tick — readiness scan, two-agent-floor health check                                                                                    | 2     | must-have   | A3a        |
+| B1  | Supervisor tick — readiness scan, two-agent-floor health check                                                                                                                                                                                                                                                                                                                     | 1    | 2     | must-have   | A3a            |
-| B2  | Native dispatch/claim — assign ready dependency-satisfied work                                                                                    | 2     | must-have   | A3b, B1    |
+| B2  | Native dispatch/claim — assign ready dependency-satisfied work                                                                                                                                                                                                                                                                                                                     | 1    | 2     | must-have   | A3b, B1        |
-| B3a | Planner decompose — goal added to YAML → cards                                                                                                    | 2     | must-have   | A2, B1     |
+| B3a | Planner decompose — goal added to YAML → cards                                                                                                                                                                                                                                                                                                                                     | 1    | 2     | must-have   | A2, B1         |
-| B3b | Replan request on empty backlog; escalate on no-decompose                                                                                         | 2     | should-have | B3a        |
+| B3b | Replan request on empty backlog; escalate on no-decompose                                                                                                                                                                                                                                                                                                                          | 1    | 2     | should-have | B3a            |
-| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge                                                                                  | 2     | must-have   | B2         |
+| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge                                                                                                                                                                                                                                                                                                                   | 1    | 2     | must-have   | B2             |
-| H1  | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)                                             | 1     | must-have   | A1         |
+| H1  | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)                                                                                                                                                                                                                                                                              | 2    | 1     | must-have   | A1             |
-| H2  | System-type profiles — declarative mapping of system type to persona roster + topology                                                            | 2     | must-have   | H1         |
+| H2  | System-type profiles — declarative mapping of system type to persona roster + topology                                                                                                                                                                                                                                                                                             | 2    | 2     | must-have   | H1             |
-| H3  | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure                                          | 2     | must-have   | H2         |
+| H3  | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure                                                                                                                                                                                                                                                                           | 2    | 2     | must-have   | H2             |
-| H4  | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides) | 2     | must-have   | H1         |
+| H4  | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides)                                                                                                                                                                                                                                  | 2    | 2     | must-have   | H1             |
+| A5  | NORTH_STAR schema validator — every goal's workstream declared, every workstream has a goal, every depends_on id exists, every tier has a success criterion; runs in CI beside the Markdown regeneration check                                                                                                                                                                     | 0    | 1     | must-have   | A1             |
+| I1  | One home resolver — a single function resolving MOSAIC_HOME with a sane default, adopted by every module. Today brain-home.ts is imported by 9 modules while 10 still use DEFAULT_MOSAIC_HOME, and MOSAIC_HOME is re-derived ad hoc in 4 places. NS-10 applies - finish the adoption and delete the second path                                                                    | 0    | 1     | must-have   | —              |
+| I2  | mosaic fleet ps sees the fleet that is actually running. Three measured blockers: the roster declares socket `mosaic-fleet` which does not exist, the 18 live sessions are on the default socket, and nothing writes a roster because seats are launched outside the CLI. Make the socket configurable and the roster written at launch, or make ps read tmux + seat dirs directly | 0    | 1     | must-have   | I1             |
+| I3  | Migrate fleet steering onto mosaic agent send --verify (exists, FLEET-OBS-005, spec FR-5) and retire tools/tmux/agent-send.sh, which forges the sender (D33) and returns an uninformative rc (D16, D34). FR-5 predates those defects by a month                                                                                                                                    | 0    | 1     | must-have   | I1             |
+| I4  | mosaic fleet absorbs what launch-seat.sh does and launch-seat.sh is deprecated: compose the prompt file set, force the skill set, wire the style hook, fail closed on any unreadable input, export per-seat git identity, and register the seat in the roster. launch-seat.sh was a manual method; it is the reference implementation, not the destination                         | 0    | 1     | must-have   | I1, I5         |
+| I5  | Harness probe matrix — verify a working prompt-injection path for claude, codex, opencode and pi, and refuse any runtime whose path is unverified. AC-NS-0 clause 1 ("any configured harness") rests on this. The probe work in docs/plans/2026-08-19_launch-seat-multi-runtime.md (brain, untracked) transfers; its launch-seat.sh target does not                                | 0    | 1     | must-have   | —              |
+| I6  | Finish the heartbeat responder (FLEET-OBS-002, the only Phase-2 task still in-progress; spec FR-2). Health must mean "answered a heartbeat", not "pane alive" — pane state measured two seats wrong on 2026-08-20                                                                                                                                                                  | 0    | 1     | must-have   | —              |
+| I7  | Independent review and live-fleet dogfood of the Phase-2 verbs (FLEET-OBS-008), then land them (FLEET-OBS-009). Implementation is done and verification is not; "done" in a task file frozen five weeks is not evidence                                                                                                                                                            | 0    | 1     | must-have   | I2, I3, I4, I6 |
+| I8  | Neutralize misleading documentation — supersede headers on docs that state a stale status, a false blocker or a retired mechanism. Cheap, and it is tier 0 because a stale doc does not merely fail to help an agent, it actively misroutes one. Rebuilding the documentation is a separate and later job                                                                          | 0    | 1     | must-have   | —              |
+| I9  | Study t3code's agent-attach and multi-provider auth methods and record what transfers. Reference only — Mosaic implements its own within the stack, never adopts the code and never takes the dependency. Informs HOW I/J/K/L are built, not whether                                                                                                                               | 0    | 1     | should-have | —              |
+| J1  | Web control plane over the gateway — fleet visibility and steering in a browser, same data source as I2                                                                                                                                                                                                                                                                            | 1    | 3     | must-have   | I2             |
+| K1  | Desktop and mobile clients against the gateway, authenticated                                                                                                                                                                                                                                                                                                                      | 2    | 4     | must-have   | J1             |
+| L1  | Per-provider auth profiles with per-session selection                                                                                                                                                                                                                                                                                                                              | 2    | 4     | must-have   | I4             |
 
 ## Assumptions (vetoable)
 

docs/fleet/NORTH_STAR.yaml

@@ -6,7 +6,7 @@
 # packages/mosaic/src/commands/fleet.ts (renderNorthStarMarkdown). Edit the YAML,
 # never the .md.
 #
-# Self-contained Mosaic. NO Hermes runtime dependency. The backlog of record is
+# Self-contained Mosaic. The backlog of record is
 # the Mosaic Backlog on Mosaic's OWN native Postgres storage service.
 
 version: 1
@@ -24,7 +24,7 @@ substrate:
   note: >-
     The Mosaic Backlog is the backlog of record + dispatch engine, built on
     Mosaic's native Postgres storage service (@mosaicstack/db drizzle;
-    PGlite-embedded by default, full Postgres by config). NOT Hermes.
+    PGlite-embedded by default, full Postgres by config).
 
 standing_objectives:
   - id: NS-1
@@ -69,32 +69,53 @@ standing_objectives:
       business/operations) and the orchestrator provisions the matching persona
       roster and org structure from a cross-domain baseline persona library; the
       delivery/coding fleet is one profile among many.
+  - id: NS-10
+    text: >-
+      An adoption is not complete until the mechanism it replaces is removed.
+      Two live conventions for one concern is the defect, not a transition
+      state. Measured 2026-08-20: brain-home adopted by 9 modules and not 10;
+      MOSAIC_HOME honored in 4 places, each re-deriving it; backlog cards
+      declared while TASKS.md files stayed authoritative. Every one was decided
+      correctly and left half-applied.
 
 success_criteria:
+  - id: AC-NS-0
+    tier: 0
+    text: >-
+      The operator launches an agent on any configured harness with one
+      command, observes its state and sends it work without attaching to a
+      terminal multiplexer.
   - id: AC-NS-1
+    tier: 1
     text: >-
       The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer)
       healthy across reboot.
   - id: AC-NS-2
+    tier: 1
     text: >-
       A goal added to this YAML is decomposed to cards and either merged or
       escalated, with no human in the loop.
   - id: AC-NS-3
+    tier: 1
     text: >-
       No PR merges with failure/error/no-status/timeout CI, and none bypass
       pr-merge.sh.
   - id: AC-NS-4
+    tier: 1
     text: >-
       TTL is enforced on claims; token caps remain advisory until a real meter
       exists.
   - id: AC-NS-5
+    tier: 1
     text: >-
       Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
   - id: AC-NS-6
+    tier: 2
     text: >-
       A user can declare a system type and the fleet provisions the matching
       persona roster + topology from the baseline library, with no code change.
   - id: AC-NS-7
+    tier: 2
     text: >-
       A user-customized persona (edited or added via the orchestrator) survives
       mosaic update: baseline reseed never clobbers user overrides.
@@ -112,80 +133,186 @@ workstreams:
     title: Meta-loop — session-review + enhancer improvement PRs
   - id: F
     title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
+  - id: G
+    title: Kill-switch — operator PAUSE honored before dispatch and merge
   - id: H
     title: Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization
+  - id: I
+    title: Operator surface — launcher, fleet visibility, reliable steering (tier 0)
+  - id: J
+    title: Web control plane — browser surface over the gateway (tier 1)
+  - id: K
+    title: Clients — desktop and mobile over the same backend (tier 2)
+  - id: L
+    title: Auth profiles — per-provider accounts, per-session selection (tier 2)
+
+# NOTE: workstreams C, D, E and F are declared but currently project no goals.
+# That is planning debt, not an editing error: their goals have not been written
+# yet. The A5 validator below reports it rather than letting it stay invisible.
 
 goals:
   - id: A1
     title: Machine-readable NORTH_STAR.yaml + Markdown projection
     phase: 1
+    tier: 1
     priority: must-have
     depends_on: []
   - id: A2
     title: Mosaic Backlog schema + storage-service card store (drizzle/PGlite)
     phase: 1
+    tier: 1
     priority: must-have
     depends_on: [A1]
   - id: A3a
     title: Card lifecycle — create/claim/release with stable ids + depends_on DAG
     phase: 1
+    tier: 1
     priority: must-have
     depends_on: [A2]
   - id: A3b
     title: TTL-bounded claim enforcement (wall-clock) on cards
     phase: 1
+    tier: 1
     priority: must-have
     depends_on: [A3a]
   - id: A4
     title: Advisory spend projection per card (degrades to TTL, no real meter)
     phase: 1
+    tier: 1
     priority: should-have
     depends_on: [A3a]
   - id: B1
     title: Supervisor tick — readiness scan, two-agent-floor health check
     phase: 2
+    tier: 1
     priority: must-have
     depends_on: [A3a]
   - id: B2
     title: Native dispatch/claim — assign ready dependency-satisfied work
     phase: 2
+    tier: 1
     priority: must-have
     depends_on: [A3b, B1]
   - id: B3a
     title: Planner decompose — goal added to YAML → cards
     phase: 2
+    tier: 1
     priority: must-have
     depends_on: [A2, B1]
   - id: B3b
     title: Replan request on empty backlog; escalate on no-decompose
     phase: 2
+    tier: 1
     priority: should-have
     depends_on: [B3a]
   - id: G1
     title: PAUSE kill-switch + merge-gate honored before dispatch and merge
     phase: 2
+    tier: 1
     priority: must-have
     depends_on: [B2]
   - id: H1
     title: Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)
     phase: 1
+    tier: 2
     priority: must-have
     depends_on: [A1]
   - id: H2
     title: System-type profiles — declarative mapping of system type to persona roster + topology
     phase: 2
+    tier: 2
     priority: must-have
     depends_on: [H1]
   - id: H3
     title: System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure
     phase: 2
+    tier: 2
     priority: must-have
     depends_on: [H2]
   - id: H4
     title: Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides)
     phase: 2
+    tier: 2
     priority: must-have
     depends_on: [H1]
+  - id: A5
+    title: NORTH_STAR schema validator — every goal's workstream declared, every workstream has a goal, every depends_on id exists, every tier has a success criterion; runs in CI beside the Markdown regeneration check
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: [A1]
+  - id: I1
+    title: One home resolver — a single function resolving MOSAIC_HOME with a sane default, adopted by every module. Today brain-home.ts is imported by 9 modules while 10 still use DEFAULT_MOSAIC_HOME, and MOSAIC_HOME is re-derived ad hoc in 4 places. NS-10 applies - finish the adoption and delete the second path
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: []
+  - id: I2
+    title: 'mosaic fleet ps sees the fleet that is actually running. Three measured blockers: the roster declares socket `mosaic-fleet` which does not exist, the 18 live sessions are on the default socket, and nothing writes a roster because seats are launched outside the CLI. Make the socket configurable and the roster written at launch, or make ps read tmux + seat dirs directly'
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: [I1]
+  - id: I3
+    title: Migrate fleet steering onto mosaic agent send --verify (exists, FLEET-OBS-005, spec FR-5) and retire tools/tmux/agent-send.sh, which forges the sender (D33) and returns an uninformative rc (D16, D34). FR-5 predates those defects by a month
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: [I1]
+  - id: I4
+    title: 'mosaic fleet absorbs what launch-seat.sh does and launch-seat.sh is deprecated: compose the prompt file set, force the skill set, wire the style hook, fail closed on any unreadable input, export per-seat git identity, and register the seat in the roster. launch-seat.sh was a manual method; it is the reference implementation, not the destination'
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: [I1, I5]
+  - id: I5
+    title: Harness probe matrix — verify a working prompt-injection path for claude, codex, opencode and pi, and refuse any runtime whose path is unverified. AC-NS-0 clause 1 ("any configured harness") rests on this. The probe work in docs/plans/2026-08-19_launch-seat-multi-runtime.md (brain, untracked) transfers; its launch-seat.sh target does not
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: []
+  - id: I6
+    title: Finish the heartbeat responder (FLEET-OBS-002, the only Phase-2 task still in-progress; spec FR-2). Health must mean "answered a heartbeat", not "pane alive" — pane state measured two seats wrong on 2026-08-20
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: []
+  - id: I7
+    title: Independent review and live-fleet dogfood of the Phase-2 verbs (FLEET-OBS-008), then land them (FLEET-OBS-009). Implementation is done and verification is not; "done" in a task file frozen five weeks is not evidence
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: [I2, I3, I4, I6]
+  - id: I8
+    title: Neutralize misleading documentation — supersede headers on docs that state a stale status, a false blocker or a retired mechanism. Cheap, and it is tier 0 because a stale doc does not merely fail to help an agent, it actively misroutes one. Rebuilding the documentation is a separate and later job
+    phase: 1
+    tier: 0
+    priority: must-have
+    depends_on: []
+  - id: I9
+    title: Study t3code's agent-attach and multi-provider auth methods and record what transfers. Reference only — Mosaic implements its own within the stack, never adopts the code and never takes the dependency. Informs HOW I/J/K/L are built, not whether
+    phase: 1
+    tier: 0
+    priority: should-have
+    depends_on: []
+  - id: J1
+    title: Web control plane over the gateway — fleet visibility and steering in a browser, same data source as I2
+    phase: 3
+    tier: 1
+    priority: must-have
+    depends_on: [I2]
+  - id: K1
+    title: Desktop and mobile clients against the gateway, authenticated
+    phase: 4
+    tier: 2
+    priority: must-have
+    depends_on: [J1]
+  - id: L1
+    title: Per-provider auth profiles with per-session selection
+    phase: 4
+    tier: 2
+    priority: must-have
+    depends_on: [I4]
 
 assumptions:
   - id: ASM-1

docs/fleet/PRD-fleet-suite.md

@@ -1,7 +1,7 @@
 # PRD — Mosaic Fleet Suite (init, configure, operate)
 
 > **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312` · **Phase:** 3→4 productization
-> **North star:** [docs/fleet/north-star.md](./north-star.md) · prior: Phase-2 observability (#579), durable launch (#581), real-agent enablement (#583/#584/#586), releases 0.0.35–0.0.37
+> **North star:** [docs/fleet/FLEET-DOCTRINE.md](./FLEET-DOCTRINE.md) · prior: Phase-2 observability (#579), durable launch (#581), real-agent enablement (#583/#584/#586), releases 0.0.35–0.0.37
 > **Lead:** Jarvis @ `w-jarvis`. **Collaborator:** coder agent @ `dragon-lin` (jwoltje@10.1.10.37:coder0-0).
 > Owner of this file: Fleet workstream lead. Does not modify MVP single-writer control-plane files.
 

docs/fleet/PRD.md

@@ -1,7 +1,7 @@
 # PRD — Fleet Phase 2: Operator Observability
 
 > **Workstream:** W-FLEET under `mvp-20260312` · **Phase:** 2
-> **North star:** [docs/fleet/north-star.md](./north-star.md)
+> **North star:** [docs/fleet/FLEET-DOCTRINE.md](./FLEET-DOCTRINE.md)
 > **Source umbrella PRD:** [docs/PRD.md](../PRD.md) (Mosaic Stack v0.1.0)
 > **Tracks task:** `fleet-observability-1` — restore operator observability into fleet agent sessions.
 

docs/fleet/TASKS.md

@@ -1,10 +1,25 @@
 # Tasks — W-FLEET (Fleet) Phase 2: Observability
 
+> ---
+>
+> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml`
+>
+> This file is the pre-backlog tracking mechanism. `NS-2` in the north star declares the
+> replacement: every backlog item is a Mosaic Backlog card projected from the YAML. That
+> model replaced this one and nobody retired the old file, so it kept reading as
+> authoritative while going stale.
+>
+> **Do not trust a status in this file.** Verified 2026-08-20: it was already behind the
+> code when it froze five weeks ago. The `FLEET-OBS` series was the one thing worth salvaging and
+> is now carried as goals `I2`, `I3`, `I6` and `I7` at tier 0.
+>
+> Kept as a record of what was believed. Do not update it; update the YAML.
+
 > Workstream task file for the Fleet. Single-writer: Fleet workstream lead (orchestrator).
 > Workers read but never modify. This is **not** the MVP rollup (`docs/TASKS.md`) — a
 > rollup row is proposed to the MVP orchestrator, not written here.
 >
-> Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/north-star.md](./north-star.md)
+> Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/FLEET-DOCTRINE.md](./FLEET-DOCTRINE.md)
 > Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
 
 | id            | status      | description                                                                                                      | depends_on            | agent       | pr  | notes                                                                                                                       |

docs/fleet/f4-matrix-connector.md

@@ -1,6 +1,6 @@
 # F4 — Orchestrator chat connector + Matrix (local homeserver)
 
-> **Issue:** #616 · **Doctrine:** `docs/fleet/north-star.md` (#613) — orchestrator-chat-connector decision.
+> **Issue:** #616 · **Doctrine:** `docs/fleet/FLEET-DOCTRINE.md` (#613) — orchestrator-chat-connector decision.
 > **Status:** Phase 1 (abstraction + scaffold) in this PR; Phase 2+ are follow-ups (below).
 
 ## Goal

docs/native-kanban-sot/TASKS.md

@@ -4,7 +4,16 @@
 **Tracking:** [Mosaic Stack issue #751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
 **Execution:** USC web1 only; collision-free GPT coder2/3/4/5 lanes
 **Contract:** `SHARED-CONTRACT.md` + four `contracts/*.v1.ts` files
-**Implementation hold:** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
+
+> **HOLD LIFTED — 2026-08-20.** The stated condition ("no feature slice starts until the
+> canon PR is merged to `main` with terminal-green CI") was **met on 2026-07-14** by
+> `49e8a541` — _docs(#751): Publish native Kanban/SOT canon (#752)_ — which is on both
+> `main` and `next`, and `docs/requirements/native-kanban-sot.md` is present on `main`.
+> The line below was never updated, so for five weeks this file advertised a blocker that
+> did not exist. The status line above ("PUBLICATION IN PROGRESS") is stale for the same
+> reason. This file is a build plan, not a task tracker, and is NOT superseded.
+
+**Implementation hold (SATISFIED — see note above):** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
 
 > This publication file is not a runtime task authority. After cutover, repository `TASKS.md` is generated read-only and never imported.
 

docs/scratchpads/1179-required-security-di.md

@@ -0,0 +1,77 @@
+# #1179 — Required security DI wiring
+
+## Objective
+
+Eliminate the shared fail-open defect class **absence read as permission**:
+
+- FL-01: missing `CommandAuthorizationService` must refuse Nest startup and must not permit command effects.
+- FL-11: missing `SystemOverrideService` must refuse Nest startup and must not omit stored instruction authority while allowing provider/session effects.
+
+## Tracking
+
+- Issue: #1179, child of #1156
+- Branch: `fix/1179-required-security-di`
+- Base: `origin/next` at `216cd72226cd9ee17eea461cfe7cd0e010a22f02`
+
+## Plan
+
+1. RED: compile the real `AppModule` graph with each required provider independently removed, with a positive control for each intact binding.
+2. RED: directly exercise each malformed absence path and assert zero command/provider/session effects.
+3. Stop and report RED to the coordinator before production implementation.
+4. After authorization, make both constructor injections required, remove absence-as-permission branches, and update explicit legitimate optional test seams.
+5. Run focused Gateway tests, typecheck, lint, format, build, independent exact-head verification, and focused security review.
+
+## Immutable path fence
+
+Production changes are confined to:
+
+- `apps/gateway/src/commands/command-executor.service.ts`
+- `apps/gateway/src/agent/agent.service.ts`
+
+Tests and task evidence are confined to:
+
+- `apps/gateway/src/__tests__/required-security-wiring.test.ts`
+- existing direct-constructor specs that require explicit required arguments
+- `docs/scratchpads/1179-required-security-di.md`
+
+No files in #1178, #1072, #1080, or #1054 lanes are in scope. `docs/TASKS.md` is orchestrator-owned and will not be modified.
+
+## Budget
+
+No explicit token ceiling was provided. Working assumption: one narrow Gateway security packet; split and stop if either arm requires unrelated module rewiring.
+
+## Progress
+
+- Intake read from #1179 and parent #1156.
+- Base independently resolved from the issue's pre-native-stage ordering and repository `origin/next` ref; branch HEAD verified byte-for-byte against the remote ref.
+- Real consumers and direct constructors inventoried.
+
+## Tests
+
+### RED
+
+- `required-security-wiring.test.ts`: 4 failed, 2 passed before implementation.
+- Both real-graph negative controls showed module compilation accepted the missing target binding.
+- Direct FL-01 showed one unauthorized command effect; direct FL-11 showed one provider prompt and one session counter mutation.
+
+### GREEN
+
+- `required-security-wiring.test.ts`: 6/6 passed.
+- FL-01-only production revert: exactly the two FL-01 test cases failed; all four other cases, including FL-11, passed.
+- FL-11-only production revert: exactly the two FL-11 test cases failed; all four other cases, including FL-01, passed.
+- Full Gateway suite: 74 files passed, 7 skipped; 831 tests passed, 17 skipped.
+- Gateway typecheck: passed.
+- Gateway lint: passed.
+- Gateway build: passed.
+- Changed-file Prettier check: passed.
+
+### Review
+
+- Codex code review: APPROVE, 0 findings.
+- Codex focused security review: risk `none`, 0 findings.
+- Independent exact-head review remains assigned to Scrappy through the coordinator.
+
+## Risks / blockers
+
+- `AgentModule` / `CommandsModule` / `ChatModule` contain a production cycle; the module test therefore uses the real top-level `AppModule` and replaces only storage/network leaves, preserving the target service in each arm while isolating the separate required consumer that would otherwise mask that arm's defect.
+- No broad module rewrite was required.

packages/mosaic/framework/defaults/AGENTS.md

@@ -84,6 +84,7 @@ is re-seeded a genuinely missing core file is a stop-and-report condition — no
 
 Confirm: required + situational tests passed (primary gate); aligned to `docs/PRD.md`; acceptance
 criteria mapped to evidence; independent code review passed (if code changed); required docs updated;
-scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on `main`, terminal-green
+scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on the integration
+trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), terminal-green
 CI, linked issue closed (or `docs/TASKS.md` equivalent). If blocked by access/tooling, return `blocked`
 with the exact failed wrapper command — do not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.

packages/mosaic/framework/defaults/CONSTITUTION.md

@@ -21,11 +21,25 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
 
 ## Hard Gates
 
+The **integration trunk** is the branch a project declares in its `.mosaic/repo.json` under the
+key `integration_trunk`; `release_branch` names the release target when one exists (`null` for
+single-branch projects). Absent a declaration, the trunk is `main`. The declaration is policy
+data, never shell text: values must be valid local branch names under `git check-ref-format
+--branch` semantics — no remote refs, no revision expressions, no option-like values (leading `-`),
+no path traversal or control characters. A declaration file that fails to parse, an unknown or
+misspelled key, or an invalid value is a hard stop (`blocked`) — never a silent fallback to `main`.
+Prose that mentions branch names designates nothing; only the declaration file does. A project
+declares exactly ONE trunk. **Changing an existing declaration is operator-owned:** a trunk
+redeclaration redirects merge target and branch-protection target at once, so it requires an
+explicit operator action above ordinary PR review. The designation relaxes nothing:
+reviewed-PR-only delivery, squash merge, independent review, queue guards, and terminal-green CI
+bind to the declared trunk exactly as they bind to `main`.
+
 1. Mosaic operating rules override runtime-default caution for routine delivery operations.
 2. Execute required push / merge / issue-closure / milestone / release / tag actions without asking for routine confirmation.
 3. Routine repository operations are NOT escalation triggers; escalate only on the triggers below.
 4. For source-code delivery, completion is forbidden at the PR-open stage.
-5. Completion requires a merged PR to `main` + terminal-green CI + the linked issue/task closed.
+5. Completion requires a merged PR to the integration trunk + terminal-green CI + the linked issue/task closed.
 6. Before any push or merge, run the CI queue guard.
 7. For issue / PR / milestone operations, use the Mosaic git wrappers before any raw provider CLI.
 8. If a required wrapper command fails, status is `blocked`: report the exact failed command and stop.
@@ -35,7 +49,7 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
 12. The intake procedure is not conditional on perceived complexity; a "simple" task carries the same requirements as a multi-file feature.
 13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review merge go-ahead is the coordinator's to give — once the required review gates pass, merge on the coordinator's confirmation; do not wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges.
 14. Never hardcode secrets; never emit credential values in any output (not even partially, not "to confirm").
-15. Trunk-based git only: branch from `main`, merge via a reviewed PR (squash), never push directly to `main`.
+15. Trunk-based git only: branch from the integration trunk, merge via a reviewed PR (squash), never push directly to the trunk.
 16. If you modify source code, an independent review (author ≠ reviewer) must pass before completion.
 
 ## Integrity (quality gates are never bypassed)

packages/mosaic/framework/fleet/roles/board.md

@@ -35,4 +35,4 @@ A standing panel of senior voices, each arguing from a fixed vantage. The board
 deliberately slow and adversarial — its value is catching the expensive mistake
 before a single agent-hour is spent on it.
 
-> Doctrine: `docs/fleet/north-star.md` ('board' role = forge BOD; role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` ('board' role = forge BOD; role library).

packages/mosaic/framework/fleet/roles/code.md

@@ -33,4 +33,4 @@ The code role writes the change and opens the PR; it never touches the merge pat
 The focused builder. It takes one well-scoped card, drives it to green, opens a
 clean PR, and hands off — never reaching past the card it was given.
 
-> Doctrine: `docs/fleet/north-star.md` (role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).

packages/mosaic/framework/fleet/roles/decomposition.md

@@ -35,4 +35,4 @@ The work-breakdown specialist. It takes a phased plan and a DAG and emits a clea
 linked set of single-PR cards on the Mosaic backlog — then steps back and lets the
 executors run.
 
-> Doctrine: `docs/fleet/north-star.md` (role library); spend accounting is a process mandate.
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); spend accounting is a process mandate.

packages/mosaic/framework/fleet/roles/documentation.md

@@ -36,4 +36,4 @@ The scribe of record. It makes sure the docs and the north star's projections
 describe the system as it actually is, and it never lets two writers fight over one
 TASKS file.
 
-> Doctrine: `docs/fleet/north-star.md` (role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).

packages/mosaic/framework/fleet/roles/enhancer.md

@@ -38,4 +38,4 @@ The orchestrator alone optimizes for _this_ delivery; the enhancer optimizes for
 delivery — self-healing the fleet's tools, skills, and harnesses, and routing real defects
 upstream. Together they are the irreducible core; every other role is added on demand.
 
-> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (two-agent floor + role library).

packages/mosaic/framework/fleet/roles/merge-gate.md

@@ -46,4 +46,4 @@ The single, accountable gatekeeper. It waits for green CI (`pr-ci-wait.sh`),
 respects the pause switch, merges only through `pr-merge.sh`, and records every
 decision — so the fleet has exactly one trustworthy door to production.
 
-> Doctrine: `docs/fleet/north-star.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.

packages/mosaic/framework/fleet/roles/operator.md

@@ -35,4 +35,4 @@ The on-call dispatcher. It makes sure every escalation is seen and re-seen until
 handled, and it holds the one switch that can stop the fleet when something is
 wrong.
 
-> Doctrine: `docs/fleet/north-star.md` (role library); pause switch: `fleet/run/PAUSED`.
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); pause switch: `fleet/run/PAUSED`.

packages/mosaic/framework/fleet/roles/orchestrator.md

@@ -43,4 +43,4 @@ A lean, decisive coordinator. It thinks in readiness and throughput, dispatches
 next ready card the instant a dependency clears, and never lets an idle agent sit
 while ready work exists — keeping its own context minimal so the loop never slows.
 
-> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (two-agent floor + role library).

packages/mosaic/framework/fleet/roles/planner.md

@@ -38,4 +38,4 @@ The architect of the mission's shape. It thinks in phases and dependencies, hand
 a clean DAG to decomposition, and reports its plan back to the orchestrator that
 dispatched it.
 
-> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (two-agent floor + role library).

packages/mosaic/framework/fleet/roles/rebase.md

@@ -34,4 +34,4 @@ The rebase role keeps PR branches fresh; it never approves or merges.
 The janitor of the merge queue. It quietly keeps branches current and re-runnable,
 and knows when a conflict is beyond a mechanical rebase and must be escalated.
 
-> Doctrine: `docs/fleet/north-star.md` (role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).

packages/mosaic/framework/fleet/roles/review.md

@@ -35,4 +35,4 @@ The careful reader. It assumes nothing, checks the change against its card and i
 tests, and is willing to say "not yet" — its value is catching the wrong change
 before it reaches the merge-gate.
 
-> Doctrine: `docs/fleet/north-star.md` (role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).

packages/mosaic/framework/fleet/roles/security-review.md

@@ -36,4 +36,4 @@ tree or the merge path.
 The adversary on your side. It reads every diff asking "how does this get exploited
 or leak?" — the second, security-focused pair of eyes before the merge-gate.
 
-> Doctrine: `docs/fleet/north-star.md` (role library); forbidden paths: `pr-merge.sh` guard.
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); forbidden paths: `pr-merge.sh` guard.

packages/mosaic/framework/fleet/roles/session-review.md

@@ -34,4 +34,4 @@ The retrospective analyst. It reads completed sessions and distills them into cl
 actionable signals — the raw material the enhancer uses to make the fleet better
 next time.
 
-> Doctrine: `docs/fleet/north-star.md` (role library); consumed by the enhancer role.
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); consumed by the enhancer role.

packages/mosaic/framework/fleet/roles/site-tester.md

@@ -34,4 +34,4 @@ merge path.
 The skeptic who insists on running it. It trusts observed behavior over claimed
 behavior, and turns "should work" into "verified works" — or a concrete bug report.
 
-> Doctrine: `docs/fleet/north-star.md` (role library).
+> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).

packages/mosaic/framework/guides/BOOTSTRAP.md

@@ -12,7 +12,7 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
 4. Issue tracking is consistent across projects
 5. Documentation standards and API contracts are enforced from day one
 6. PRD requirements are established before coding begins
-7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
+7. Branching/merging is consistent: branch -> integration trunk (default `main`) via PR with squash-only merges
 8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
 
 ## Agent Host Prerequisites
@@ -206,7 +206,7 @@ Every runtime context file should contain:
 6. **Issue tracking** — Issue and commit conventions
 7. **Code review** — Required review process
 8. **Runtime notes** — Runtime-specific behavior references
-9. **Branch and merge policy** — Trunk workflow (`branch -> main` via PR, squash-only)
+9. **Branch and merge policy** — Trunk workflow (branch -> integration trunk via PR, squash-only)
 10. **Autonomy and escalation policy** — Agent owns coding/review/PR/release/deploy lifecycle
 
 ---
@@ -288,15 +288,17 @@ Reserve `0.1.0` for the MVP release milestone.
 
 ---
 
-## Step 5b: Configure Main Branch Protection (Hard Rule)
+## Step 5b: Configure Trunk Branch Protection (Hard Rule)
 
-Apply equivalent settings in Gitea, GitHub, or GitLab:
+Apply equivalent settings in Gitea, GitHub, or GitLab, targeting the project's integration trunk
+(the branch its `.mosaic/repo.json` declares under `integration_trunk`; default `main` — see
+`CONSTITUTION.md` Hard Gates):
 
-1. Protect `main` from direct pushes.
+1. Protect the integration trunk from direct pushes.
-2. Require pull requests to merge into `main`.
+2. Require pull requests to merge into the integration trunk.
 3. Require required CI/status checks to pass before merge.
 4. Require code review approval before merge.
-5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
+5. Allow **squash merge only** for PRs into the integration trunk (disable merge commits and rebase merges for it).
 
 This enforces one merge strategy across human and agent workflows.
 
@@ -513,9 +515,9 @@ After bootstrapping, verify:
 - [ ] Git labels created (epic, feature, bug, task, etc.)
 - [ ] Initial pre-MVP milestone created (0.0.1)
 - [ ] MVP milestone reserved for release (0.1.0)
-- [ ] `main` is protected from direct pushes
+- [ ] The integration trunk is protected from direct pushes
-- [ ] PRs into `main` are required
+- [ ] PRs into the integration trunk are required
-- [ ] Merge method for `main` is squash-only
+- [ ] Merge method for the integration trunk is squash-only
 - [ ] Quality gates run successfully
 - [ ] `.env.example` exists (if project uses env vars)
 - [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)

packages/mosaic/framework/guides/CI-CD-PIPELINES.md

@@ -4,6 +4,11 @@
 
 ## Overview
 
+> **Integration trunk:** the YAML examples in this guide use the default integration trunk `main`
+> in branch conditions and version rules. A project that declares a different trunk in its
+> `.mosaic/repo.json` under `integration_trunk` (see `CONSTITUTION.md` Hard Gates) substitutes its
+> declared trunk wherever `main` appears as the trunk branch.
+
 This guide covers the canonical CI/CD pattern used across projects. The pipeline runs in Woodpecker CI and follows this flow:
 
 ```
@@ -865,7 +870,7 @@ steps:
    ```yaml
    image: git.example.com/org/service@${IMAGE_DIGEST}
    ```
-7. **Test on a short-lived non-main branch first** — open a PR and verify quality gates before merging to `main`
+7. **Test on a short-lived non-trunk branch first** — open a PR and verify quality gates before merging to the integration trunk
 8. **Verify images appear** in Gitea Packages tab after successful pipeline
 
 ## Terminal-Green Full-Step Contract
@@ -906,7 +911,7 @@ For source-code delivery, completion is not allowed at "PR opened" stage.
 
 Required sequence:
 
-1. Merge PR to `main` (squash) via Mosaic wrapper.
+1. Merge PR to the integration trunk (squash) via Mosaic wrapper.
 2. Monitor CI to terminal status:
    ```bash
    ~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>
@@ -1112,5 +1117,5 @@ If a project currently uses Verdaccio (e.g., U-Connect at `npm.uscllc.net`), fol
 
 ### Pipeline runs Docker builds on pull requests
 
-- Verify `when` clause on Docker build steps restricts to `branch: [main]`
+- Verify `when` clause on Docker build steps restricts to the integration trunk (`branch: [main]` by default)
 - Pull requests should only run quality gates, not build/push images

packages/mosaic/framework/guides/CODE-REVIEW.md

@@ -10,9 +10,10 @@ If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD upd
 
 Merge strategy enforcement (HARD RULE):
 
-- PR target for delivery is `main`.
+- The integration trunk is the branch the project's `.mosaic/repo.json` declares under `integration_trunk` (default: `main`) — see `CONSTITUTION.md` Hard Gates.
-- Direct pushes to `main` are prohibited.
+- PR target for delivery is the integration trunk.
-- Merge to `main` MUST be squash-only.
+- Direct pushes to the integration trunk are prohibited.
+- Merge to the integration trunk MUST be squash-only.
 - Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).
 
 An estate MAY carry a documented exception for a repository whose gates are commit hooks rather
@@ -65,6 +66,19 @@ Each of these produced a wrong conclusion before it was written down.
     conclusion drawn from it describes the wrong tree. Confirm `git rev-parse --show-toplevel`
     is the tree you think it is before trusting any git output.
 
+13. **Run the repository's PINNED tool version.** `npx <tool>` resolves a local `node_modules`
+    install when one is present and fetches the latest release when one is not, so the same
+    command answers differently depending on where it ran. A reviewer measuring in a fresh clone
+    or a detached worktree — which is exactly where reviewers measure — has no `node_modules` and
+    silently gets the latest release instead of the pinned one. Measured on mosaicstack#1313: the
+    lockfile pins prettier 3.8.1, under which three guides pass; a version-less `npx` in a
+    worktree resolved 3.9.6, under which the same three fail; and 3.0.0, the floor of the declared
+    `^3.0.0` range, fails a different one. Three versions, three verdicts, identical bytes. Use
+    `node_modules/.bin/<tool>`, or name the version the lockfile pins.
+14. **A formatter or linter declared as a range is a dated verdict, not a fact.** If a lockfile
+    pins it, the gate is reproducible today and will disagree with itself the day the pin moves.
+    Report a formatting failure with the version that produced it, always.
+
 ### Feedback Categories
 
 - **Blocker**: must fix before merge (security, bugs, test failures)
@@ -184,8 +198,8 @@ Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` whenever code/A
 # List the issue being addressed
 ~/.config/mosaic/tools/git/issue-list.sh -i {issue-number}
 
-# View the changes
+# View the changes (diff against the integration trunk; default: main)
-git diff main...HEAD
+git diff {integration_trunk}...HEAD
 ```
 
 ### Providing Feedback
@@ -214,4 +228,4 @@ This pattern appears in 3 places. A shared helper would reduce duplication.
 2. If changes requested, assign back to author
 3. If approved, note approval in issue comments
 4. For merges, ensure CI passes first
-5. Merge PR to `main` with squash strategy only
+5. Merge PR to the integration trunk with squash strategy only

packages/mosaic/framework/guides/E2E-DELIVERY.md

@@ -78,7 +78,7 @@ For implementation work, you MUST run this cycle in order:
 7. `commit` - commit only when the logical unit passes tests and review.
 8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. `push` - push immediately after queue guard passes.
-10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
+10. `PR integration` - if external git provider is available, create/update PR to the integration trunk (the project's declared trunk, default `main`) and merge with required strategy via Mosaic wrappers.
 11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines on the exact PR head to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/tools/git/pr-ci-wait.sh` for PR-based workflow).
 13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
@@ -199,7 +199,7 @@ Before running this checklist, pause and self-interrogate: did I fulfill the use
 10. No unresolved blocker hidden.
 11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
 12. `docs/TASKS.md` status and issue/internal references are updated to match delivered work.
-13. If source code changed and external provider is available: PR merged to `main` (squash), with merge evidence recorded.
+13. If source code changed and external provider is available: PR merged to the integration trunk (squash), with merge evidence recorded.
 14. CI/pipeline status is terminal green for the merged PR/head commit.
 15. Linked external issue is closed (or internal task ref is closed when no provider exists).
 16. If any of items 13-15 fail due access/tooling, report `blocked` with exact failed wrapper command and do not claim completion.

packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md

@@ -253,7 +253,7 @@ status → mission → run → repeat
 
 - [ ] All milestone tasks in TASKS.md are `done`
 - [ ] CI/pipeline green
-- [ ] PR merged to `main`
+- [ ] PR merged to the integration trunk
 - [ ] Issues closed
 - [ ] Update manifest: milestone status → completed
 - [ ] Update scratchpad: session log entry

packages/mosaic/framework/guides/ORCHESTRATOR.md

@@ -15,7 +15,7 @@ mosaic claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md th
 - You MUST keep the TASKS.md file updated with agent and tasks statuses.
 - You MUST keep `docs/` root clean. Reports and working artifacts MUST be stored in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
 - You MUST enforce plan/token usage budgets when provided, and adapt orchestration strategy to remain within limits.
-- You MUST enforce trunk workflow: workers branch from `main`, PR target is `main`, direct push to `main` is forbidden, and PR merges to `main` are squash-only.
+- You MUST enforce trunk workflow: workers branch from the integration trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), PR target is the integration trunk, direct push to the trunk is forbidden, and PR merges to the trunk are squash-only.
 - You MUST operate in steered-autonomy mode: human intervention is escalation-only; do not require the human to write code, review code, or manage PR/repo workflow.
 - You MUST NOT declare task or issue completion until PR is merged, CI/pipeline is terminal green, and linked issue is closed (or internal TASKS ref is closed when provider is unavailable).
 - Mosaic orchestration rules OVERRIDE runtime-default caution for routine push/merge/issue-close actions required by this workflow.
@@ -133,10 +133,10 @@ Milestone versioning (HARD RULE):
 
 Branch and merge strategy (HARD RULE):
 
-- Workers use short-lived task branches from `origin/main`.
+- Workers use short-lived task branches from `origin/{integration_trunk}` (default `main`).
-- Worker task branches merge back via PR to `main` only.
+- Worker task branches merge back via PR to the integration trunk only.
-- Direct pushes to `main` are prohibited.
+- Direct pushes to the integration trunk are prohibited.
-- PR merges to `main` MUST use squash merge.
+- PR merges to the integration trunk MUST use squash merge.
 
 **Available templates:**
 
@@ -427,7 +427,7 @@ git push
     - Before merging, run queue guard:
       `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
     - Ensure PR exists for the task branch (create/update via wrappers if needed):
-      `~/.config/mosaic/tools/git/pr-create.sh ... -B main`
+      `~/.config/mosaic/tools/git/pr-create.sh ... -B {integration_trunk}` (default `main`)
     - Merge via wrapper:
       `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
     - Wait for terminal CI status:
@@ -619,7 +619,7 @@ Construct this from the task row and pass to worker via Task tool:
 
 ## Workflow
 
-1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
+1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/{integration_trunk}) && git rebase origin/{integration_trunk}` ({integration_trunk} = the project's declared trunk, default `main`)
 2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
 3. Read the finding details from the report
 4. Implement the fix following existing code patterns
@@ -637,7 +637,7 @@ Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIR
 For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
 
 - `~/.config/mosaic/tools/git/issue-view.sh -i {N}`
-- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B main`
+- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B {integration_trunk}`
 - Push: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {task_branch}`
 - Merge: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B {pr_head_branch} -R {pr_head_owner/repo} --sha {pr_head_full_sha}`
 - `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
@@ -994,13 +994,13 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
 
 ---
 
-## Merge-to-Main Candidate Protocol (Container Deployments)
+## Merge-to-Trunk Candidate Protocol (Container Deployments)
 
-If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:
+If deployment is in scope and container images are used, every merge to the integration trunk MUST execute this protocol:
 
 1. Build and push immutable candidate image tags:
    - `sha-<shortsha>` (always)
-   - `v{base-version}-rc.{build}` (for `main` merges)
+   - `v{base-version}-rc.{build}` (for integration-trunk merges)
    - `testing` mutable pointer to the same digest
 2. Resolve and record the image digest for each service.
 3. Deploy by digest to testing environment (never deploy by mutable tag alone).

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -257,8 +257,36 @@ assert_owned_tmux_server() {
     fail "tmux server ownership or environment validation failed"
 }
 
-# Validate exact server ownership before querying, cleaning, or creating any
+# Lease-broker socket preflight (#1292). The gated runtime (`mosaic yolo …` →
-# managed session. An unmanaged or contaminated named socket is never repaired.
+# launch-runtime.py) registers with the broker or dies ~4 seconds in, with the
+# diagnostic invisible because tmux destroys the dead pane. This check runs
+# BEFORE any tmux effect — including the ownership probe below — so a host
+# without a broker produces a named, surviving refusal instead of a doomed
+# pane. Exit 75 (EX_TEMPFAIL), distinct from 64 (bad projection) and 69 (host
+# not ready for other reasons); the agent@ unit is Type=oneshot with no
+# Restart=, so the failed unit keeps its message instead of looping. Socket
+# resolution matches launch.ts's defaultLeaseBrokerSocket precedence exactly.
+# This preflight DETECTS and REFUSES — it never starts the broker (activation
+# belongs to the fleet control plane; a component that both detects and fixes
+# cannot be used to measure whether the fix worked).
+broker_socket_path() {
+  if [ -n "${MOSAIC_LEASE_BROKER_SOCKET:-}" ]; then
+    printf '%s\n' "$MOSAIC_LEASE_BROKER_SOCKET"
+    return 0
+  fi
+  local runtime_dir="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+  printf '%s\n' "${runtime_dir}/mosaic-lease/broker.sock"
+}
+
+if [ "$MODE" = "launch" ]; then
+  _broker_socket=$(broker_socket_path)
+  if [ ! -S "$_broker_socket" ]; then
+    echo "[fleet] FAIL_LAUNCH broker-absent: lease broker socket ${_broker_socket} missing; runtime launch denied (#1292)." >&2
+    echo "[fleet] remedy: systemctl --user enable --now mosaic-lease-broker.service  (or reinstall via: mosaic fleet install)" >&2
+    exit 75
+  fi
+fi
+
 assert_owned_tmux_server
 
 if [ "$MODE" = interaction ]; then
@@ -292,6 +320,16 @@ esac
 _build_runtime_bin_prefix() {
   local candidates=()
   if [ -n "$MOSAIC_RUNTIME_BIN" ]; then candidates+=("$MOSAIC_RUNTIME_BIN"); fi
+  # A host with no system Node gets one bootstrapped here by tools/install.sh, which
+  # records it in ~/.profile. The fleet unit runs `env -i ... bash --noprofile --norc`
+  # by design, so ~/.profile is never read and the directory has to be named here.
+  # The npm probe below cannot cover this: it reports a package prefix
+  # (~/.npm-global), never a Node runtime directory. It sits ahead of the npm probe so
+  # the bootstrapped runtime wins on a host that has both — that is the one the installer
+  # verified — while an explicit MOSAIC_RUNTIME_BIN still outranks it.
+  # Runtime binaries are `#!/usr/bin/env node`, so without this the pane resolves the
+  # binary and then dies on `env: 'node': No such file or directory`.
+  candidates+=("$PANE_HOME/.mosaic/node/current/bin")
   if command -v npm >/dev/null 2>&1; then
     local npm_prefix
     npm_prefix=$(npm config get prefix 2>/dev/null) || true

packages/mosaic/framework/tools/fleet/test-agent-session-broker-preflight.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# CI-fit regression suite for the #1292 lease-broker socket preflight in
+# start-agent-session.sh.
+#
+# WHY THIS SUITE IS CI-FIT WHERE test-start-agent-session.sh IS NOT (#1017/#1270
+# context): that older suite's precondition is "the host does not have the pi
+# binary", which a CI image that ships pi violates — its guard correctly
+# refuses to report a pass there, so it is excluded from the chain. THIS suite
+# controls its own preconditions instead of inheriting them from the host: a
+# fake tmux on PATH, a fake mosaic on PATH, a real unix socket created in a
+# tmpdir, a hermetic env (env -i, fake HOME, GIT_CONFIG_GLOBAL severed). It
+# never depends on what the host has installed, so a green here means the same
+# thing on every host. Anyone adding cases: keep that property — no case may
+# depend on host state.
+#
+# The failure this suite is written down to catch (#1292): a seat launched on a
+# host with no lease broker dies ~4 seconds in at registration, with the
+# diagnostic invisible because tmux destroys the dead pane. The preflight runs
+# BEFORE any tmux effect and refuses with a NAMED code (exit 75, EX_TEMPFAIL)
+# so the message survives. The agent@ unit is Type=oneshot with no Restart=,
+# so a failed unit keeps its output instead of looping.
+#
+# Cases:
+#   1. absent socket -> exit 75, message names broker-absent + socket path +
+#      remedy, and NO tmux session was ever created (the doomed-pane half).
+#   2. present socket (real unix socket in tmpdir) -> proceeds PAST the
+#      preflight (the suite then stops at the next precondition, proving the
+#      preflight was not the refusal).
+#   3. explicit MOSAIC_LEASE_BROKER_SOCKET wins over XDG_RUNTIME_DIR default.
+#   4. --stop mode does NOT require the broker (teardown must not be fenced on
+#      a component whose absence is exactly what teardown may follow).
+#
+# Sabotage control, run by the developer (not in-suite): remove the preflight
+# block from start-agent-session.sh, re-run — case 1 fails (a tmux session is
+# created / exit is not 75), cases 2-4 still pass; restore byte-identically.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/agent-session-broker-preflight}"
+FAKE_HOME="$WORK_DIR/home"
+BIN_DIR="$WORK_DIR/bin"
+ENV_DIR="$WORK_DIR/env"
+SOCK_DIR="$WORK_DIR/sockets"
+LOG_FILE="$WORK_DIR/tmux-calls.log"
+
+rm -rf "$WORK_DIR"
+# The script asserts a managed directory tree under MOSAIC_HOME: mosaic/,
+# mosaic/fleet/, mosaic/fleet/agents/ — private (0700/0750-style) modes, no
+# symlinks — plus a per-agent env projection. Build the full tree the launcher
+# expects so the suite reaches the BROKER preflight rather than dying at
+# environment validation.
+mkdir -p "$FAKE_HOME/.config/mosaic/fleet/agents" "$BIN_DIR" "$SOCK_DIR"
+chmod 700 "$FAKE_HOME/.config/mosaic" "$FAKE_HOME/.config/mosaic/fleet/agents"
+chmod 750 "$FAKE_HOME/.config/mosaic/fleet"
+cat > "$FAKE_HOME/.config/mosaic/fleet/agents/preflight-test.env.generated" <<'ENVEOF'
+MOSAIC_AGENT_NAME=preflight-test
+MOSAIC_GIT_IDENTITY=preflight-test
+MOSAIC_AGENT_CLASS=worker
+MOSAIC_AGENT_RUNTIME=pi
+MOSAIC_AGENT_MODEL=
+MOSAIC_AGENT_REASONING=
+MOSAIC_AGENT_TOOL_POLICY=code
+MOSAIC_AGENT_WORKDIR=/tmp
+MOSAIC_TMUX_SOCKET=mosaic-fleet
+ENVEOF
+chmod 600 "$FAKE_HOME/.config/mosaic/fleet/agents/preflight-test.env.generated"
+
+# ─── Fake tmux: records every invocation; new-session marks the marker. ────
+: > "$LOG_FILE"
+cat > "$BIN_DIR/tmux" <<SH
+#!/usr/bin/env bash
+printf 'tmux %s\n' "\$*" >> "$LOG_FILE"
+if [[ "\$*" == *new-session* ]]; then
+  echo "TMUX-NEW-SESSION-INVOKED" >> "$LOG_FILE"
+fi
+exit 0
+SH
+chmod +x "$BIN_DIR/tmux"
+
+# ─── Fake mosaic/pi binaries so the script proceeds past its own lookups. ───
+for bin in mosaic pi claude; do
+  printf '#!/usr/bin/env bash\nexit 0\n' > "$BIN_DIR/$bin"
+  chmod +x "$BIN_DIR/$bin"
+done
+
+# ─── Minimal launch environment the script expects. ────────────────────────
+# (Enough for the preflight to be reached; later stages will still fail in
+# case 2 — that is expected and asserted.)
+run_session_script() {
+  local mode="$1"; shift
+  (
+    cd "$WORK_DIR"
+    env -i HOME="$FAKE_HOME" PATH="$BIN_DIR:/usr/bin:/bin" \
+      GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null \
+      MOSAIC_HOME="$FAKE_HOME/.config/mosaic" \
+      AGENT_NAME=preflight-test \
+      "$@" \
+      bash "$SCRIPT_DIR/start-agent-session.sh" $mode preflight-test
+  )
+}
+
+fail=0
+assert() {
+  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"
+  [[ "$haystack" == *"$needle"* ]] || { echo "FAIL: $desc — missing '$needle' in: $haystack" >&2; fail=1; }
+}
+assert_not_contains() {
+  local desc="$1" haystack="$2" needle="$3"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "FAIL: $desc — must not contain '$needle'" >&2
+    fail=1
+  fi
+  return 0
+}
+
+# ─── 1. Absent socket → named refusal, NO tmux session. ────────────────────
+: > "$LOG_FILE"
+stderr_file="$WORK_DIR/stderr-1.tmp"
+set +e
+out=$(run_session_script "" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent.sock" 2>"$stderr_file")
+rc=$?
+set -e
+assert "absent socket exit code" "75" "$rc"
+err=$(cat "$stderr_file")
+assert_contains "absent socket names the failure" "$err" "FAIL_LAUNCH broker-absent"
+assert_contains "absent socket names the socket path" "$err" "$SOCK_DIR/absent.sock"
+assert_contains "absent socket names a remedy" "$err" "mosaic fleet install"
+log1=$(cat "$LOG_FILE")
+assert_not_contains "absent socket must not create a tmux session" "$log1" "TMUX-NEW-SESSION-INVOKED"
+
+# ─── 2. Present socket → passes the preflight. ─────────────────────────────
+# Expected: ownership/env checks AFTER the preflight may refuse (fixture is
+# minimal by design); the assertion is only that the refusal is NOT
+# broker-absent and the exit is NOT 75.
+# Create a REAL unix socket: a detached python holder binds it and stays alive
+# for the duration (bash cannot create sockets; a foreground python would
+# close the socket on exit and -S on a closed-but-unlinked path fails). Written
+# as a script file + setsid nohup so no job-control/heredoc interaction with
+# set -e can silently kill the suite.
+# AF_UNIX binds cap at 108 path bytes; the suite's workdir exceeds that, so
+# the live socket lives at a SHORT path under /tmp (unique per run, cleaned
+# with the suite). The preflight takes its socket path explicitly, so this
+# stays fully controlled.
+# A real unix socket at a SHORT absolute path (AF_UNIX limit is 108 bytes,
+# so the repo-deep SOCK_DIR cannot host it). The name is composed, not
+# `mktemp -u`: the CI image's mktemp dialect rejects that invocation
+# (pipeline 2562: "mktemp: : Invalid argument"), and no pre-existing file is
+# wanted anyway — the holder binds it fresh.
+LIVE_SOCK="/tmp/mosaic-preflight-$RANDOM-$$.sock"
+trap 'rm -f "$LIVE_SOCK"' EXIT
+rm -f "$SOCK_DIR/live.sock" "$LIVE_SOCK"
+cat > "$SOCK_DIR/holder.py" <<'PY'
+import socket, sys, time
+path = sys.argv[1]
+s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+s.bind(path)
+s.listen(1)
+time.sleep(120)
+PY
+python3 "$SOCK_DIR/holder.py" "$LIVE_SOCK" >/dev/null 2>"$SOCK_DIR/holder.err" &
+HOLDER_PID=$!
+# Wait for the socket object to exist (bind is near-instant, but do not race it).
+for _ in $(seq 1 50); do
+  [ -S "$LIVE_SOCK" ] && break
+  sleep 0.1
+done
+if [ ! -S "$LIVE_SOCK" ]; then
+  echo "FAIL: could not create live socket fixture (holder pid $HOLDER_PID)" >&2
+  ps -p "$HOLDER_PID" -o pid,stat,cmd --no-headers >&2 || echo "(holder exited)" >&2
+  cat "$SOCK_DIR/holder.err" >&2 || true
+  exit 1
+fi
+: > "$LOG_FILE"
+set +e
+out=$(run_session_script "" MOSAIC_LEASE_BROKER_SOCKET="$LIVE_SOCK" 2>"$WORK_DIR/stderr-2.tmp")
+rc=$?
+set -e
+# The preflight PASSED if the failure (whatever later stage refused) is NOT
+# the broker refusal, and tmux was reached or a later precondition named
+# something else.
+err2=$(cat "$WORK_DIR/stderr-2.tmp")
+assert_not_contains "live socket must not refuse broker-absent" "$err2" "broker-absent"
+if [[ "$rc" == "75" ]]; then
+  echo "FAIL: live socket — preflight still refused (exit 75) with a live socket" >&2
+  fail=1
+fi
+
+# ─── 3. Explicit socket env wins over XDG default. ─────────────────────────
+set +e
+out=$(run_session_script "" XDG_RUNTIME_DIR="$SOCK_DIR/no-runtime-here" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent2.sock" 2>"$WORK_DIR/stderr-3.tmp")
+rc=$?
+set -e
+assert "explicit env wins (exit 75)" "75" "$rc"
+assert_contains "explicit env path named" "$(cat "$WORK_DIR/stderr-3.tmp")" "$SOCK_DIR/absent2.sock"
+
+# ─── 4. --stop is not fenced on the broker. ────────────────────────────────
+: > "$LOG_FILE"
+set +e
+out=$(run_session_script "--stop" MOSAIC_LEASE_BROKER_SOCKET="$SOCK_DIR/absent3.sock" 2>"$WORK_DIR/stderr-4.tmp")
+rc=$?
+set -e
+err4=$(cat "$WORK_DIR/stderr-4.tmp")
+assert_not_contains "--stop must not refuse broker-absent" "$err4" "broker-absent"
+if [[ "$rc" == "75" ]]; then
+  echo "FAIL: --stop — exit 75 means teardown was fenced on the broker" >&2
+  fail=1
+fi
+
+kill "$HOLDER_PID" 2>/dev/null || true
+
+if [[ "$fail" -eq 0 ]]; then
+  echo "start-agent-session lease-broker preflight regression passed"
+fi
+exit "$fail"

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh

@@ -520,6 +520,93 @@ for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
   contains_literal "$pane_environment" "$blocked" && fail "runtime pane received $blocked"
 done
 
+# #1256. On a host with no system Node, tools/install.sh bootstraps one into
+# ~/.mosaic/node/ and writes that directory to ~/.profile. The fleet unit runs
+# `env -i ... bash --noprofile --norc`, so ~/.profile is never read — correctly, by
+# design — and _build_runtime_bin_prefix does not list the bootstrap directory. Its
+# `npm config get prefix` branch cannot cover the gap either: the installer points
+# npm's prefix at ~/.npm-global, so that branch contributes the npm-global directory
+# and never the Node one, however it resolves.
+#
+# The property under test is not "the string is in PATH". It is that the pane can
+# EXECUTE a Node-shebang runtime binary — which is what `mosaic` is
+# (`#!/usr/bin/env node`) and what actually failed: measured on a greenfield VM as
+# `env: 'node': No such file or directory` after a clean install that reported success.
+#
+# So this case runs the pane for real and requires it to have run. A PATH-substring
+# assertion would pass on a fix that put the directory in the wrong position, and it
+# would keep passing if the pane later stopped running for some unrelated reason.
+: > "$TMUX_CALLS"
+HOME_NODE="$ROOT/bootstrap-node/.config/mosaic"
+write_generated "$HOME_NODE" "coder-node"
+NODE_PANE_HOME="${HOME_NODE%/.config/mosaic}"
+NODE_BOOTSTRAP_BIN="$NODE_PANE_HOME/.mosaic/node/current/bin"
+mkdir -p "$NODE_BOOTSTRAP_BIN"
+
+# The bootstrapped runtime. It records that it ran, which is the evidence this case
+# turns on: no node reachable from the pane means no marker.
+cat > "$NODE_BOOTSTRAP_BIN/node" <<'SHIM'
+#!/usr/bin/env bash
+set -euo pipefail
+env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
+SHIM
+chmod +x "$NODE_BOOTSTRAP_BIN/node"
+
+# write_generated plants its symlinks under the MOSAIC_HOME it is given; here the
+# pane's HOME is the trusted parent, so the pane's view of "installed" is this
+# directory instead. `pi` is what #1241 resolves against PANE_PATH; `mosaic` is what
+# the pane then executes, and it is a Node script — not a bash script that would run
+# anywhere and quietly hide the defect.
+mkdir -p "$NODE_PANE_HOME/.npm-global/bin"
+ln -sf "$FAKE_BIN/pi" "$NODE_PANE_HOME/.npm-global/bin/pi"
+printf '#!/usr/bin/env node\n' > "$NODE_PANE_HOME/.npm-global/bin/mosaic"
+chmod +x "$NODE_PANE_HOME/.npm-global/bin/mosaic"
+
+# The npm branch is modelled ALIVE and still cannot close the gap, which is the
+# stronger statement. An earlier draft of this case tried to model npm as absent —
+# true on a real bootstrap host, where npm lives only in the Node directory — and it
+# refused to run anywhere npm is in the system path, i.e. most machines. It was also
+# the weaker claim: it would have proven only that a dead branch supplies nothing.
+#
+# On a bootstrap host the installer sets npm's prefix to ~/.npm-global. So even with
+# `command -v npm` true and the branch executing, `npm config get prefix` yields the
+# npm-global directory and never the Node one. The gap does not depend on whether
+# that branch runs.
+NODE_LAUNCHER_BIN="$ROOT/bootstrap-node-launcher-bin"
+mkdir -p "$NODE_LAUNCHER_BIN"
+ln -sf "$FAKE_BIN/tmux" "$NODE_LAUNCHER_BIN/tmux"
+ln -sf "$FAKE_BIN/npm" "$NODE_LAUNCHER_BIN/npm"
+
+/usr/bin/env -i \
+  "HOME=$NODE_PANE_HOME" \
+  "PATH=$NODE_LAUNCHER_BIN:/usr/bin:/bin" \
+  "MOSAIC_HOME=$HOME_NODE" \
+  "MOSAIC_TEST_TMUX_CALLS=$TMUX_CALLS" \
+  "MOSAIC_TEST_HOME=$NODE_PANE_HOME" \
+  "MOSAIC_TEST_NPM_PREFIX=$NODE_PANE_HOME/.npm-global" \
+  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
+  MOSAIC_TEST_EXECUTE_PANE=1 \
+  "MOSAIC_TEST_PANE_PID=$$" \
+  "$START" coder-node
+
+[ -f "$HOME_NODE/fleet/pane-environment" ] || \
+  fail "pane could not execute a Node-shebang runtime: $NODE_BOOTSTRAP_BIN is absent from PANE_PATH (#1256)"
+node_pane_environment=$(tr '\0' '\n' < "$HOME_NODE/fleet/pane-environment")
+# Colon-pad and match a whole element. A regex with `(^|:)` after `.*` looks like it
+# does this and does not: an anchor cannot match mid-pattern, so it silently requires
+# a leading colon and rejects the directory in FIRST position — which is where THIS
+# FIXTURE puts it: it runs under `env -i` with no MOSAIC_RUNTIME_BIN, so the bootstrap
+# directory leads. That is a property of the fixture, not of the fix — in general the
+# directory sits second, after MOSAIC_RUNTIME_BIN. The colon padding makes the
+# assertion position-independent either way, which is why it is written this way and
+# not with an anchor. That produced a failure reading "pane ran but PANE_PATH does not
+# carry <dir>" against a PATH whose first element was that dir.
+node_pane_path=":$(printf '%s\n' "$node_pane_environment" | sed -n 's/^PATH=//p' | head -1):"
+case "$node_pane_path" in
+  *":$NODE_BOOTSTRAP_BIN:"*) ;;
+  *) fail "pane ran but PANE_PATH does not carry $NODE_BOOTSTRAP_BIN (PATH=$node_pane_path)" ;;
+esac
+
 write_interaction_generated() {
   local home="$1"
   local agent="$2"

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -102,9 +102,17 @@ gitea_resolve_api_for_login() {
             return 1
         }
     else
-        GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") \
+        # NO --login: the acting credential is this identity's own token and there
-            || GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+        # is deliberately no tea-config fallback. get_gitea_token_for_login matches
-            echo "Error: Gitea token not found for login '$effective_login' (comment write/read-back)" >&2
+        # by login NAME and performs no authentication check, and with no --login
+        # that name was a HOST GUESS resolving to a shared account. A live shared
+        # token would therefore have authored every seat's comment as that
+        # account, making Gate-16 author-is-not-reviewer unenforceable fleet-wide;
+        # a dead one is only what made the defect visible. get_gitea_token fails
+        # loud on a fleet host when no identity resolves, and that refusal is the
+        # correct outcome, not a case to fall back from.
+        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+            echo "Error: no Gitea credential resolved for the acting identity on host '$host' (comment write/read-back). Set MOSAIC_GIT_IDENTITY=<agent-id>, or pass --login <name> to use a named tea credential." >&2
             return 1
         }
     fi
@@ -335,15 +343,12 @@ 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
+    # A --login override selects a NAMED tea credential and is the only way to
-    # override when given, otherwise the detected default for this repo's host.
+    # reach the tea store. With no --login there is deliberately no guess: the
-    # A --login override always wins. Otherwise name this repo host's login only
+    # comment is attributed to this identity's own credential, resolved by
-    # as a best effort: the login name merely selects a per-login token, and
+    # gitea_resolve_api_for_login. The guess this replaced named a SHARED
-    # gitea_resolve_api_for_login falls back to the host credential
+    # account, selecting an identity the caller never asked to act as.
-    # (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)
 
     # Bind the REST endpoint + token to the effective login, then derive the
     # acting identity from that SAME credential (GET /user). The write below and

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -128,6 +128,7 @@ BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print(
 HEAD_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefName") or "").strip())')"
 HEAD_SHA="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefOid") or "").strip())')"
 HEAD_REPO="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("headRepository") or ""; print((value.get("nameWithOwner") or value.get("full_name") or "") if isinstance(value, dict) else str(value).strip())')"
+BASE_REPO="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("baseRepository") or ""; print((value.get("nameWithOwner") or value.get("full_name") or "") if isinstance(value, dict) else str(value).strip())')"
 PR_TITLE="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("title") or "").strip())')"
 PR_AUTHOR="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("author") or ""; print((value.get("login") or "").strip() if isinstance(value, dict) else str(value).strip())')"
 if [[ "$BASE_BRANCH" != "main" && "$BASE_BRANCH" != "next" ]]; then
@@ -144,10 +145,19 @@ if [[ -n "$EXPECT_HEAD" && "$HEAD_SHA" != "$EXPECT_HEAD" ]]; then
 fi
 
 if [[ "$DRY_RUN" != true ]]; then
+    # CI statuses for a PR live on the BASE repo (Woodpecker posts there),
+    # even when the head branch lives in a fork. Reading status against the
+    # fork repo yields statuses:null -> malformed for every fork PR (#1215,
+    # gate-merge-01 B1). The head repo is used only for head-sha identity;
+    # when metadata carries no base repository, the origin repo is where CI
+    # posts and remains correct for same-repo PRs.
+    if [[ -z "$BASE_REPO" ]]; then
+        BASE_REPO="$(get_repo_owner)/$(get_repo_name)"
+    fi
     "$SCRIPT_DIR/ci-queue-wait.sh" \
         --purpose merge \
         -B "$HEAD_BRANCH" \
-        -R "$HEAD_REPO" \
+        -R "$BASE_REPO" \
         --sha "$HEAD_SHA" \
         -t "${MOSAIC_CI_QUEUE_TIMEOUT_SEC:-900}" \
         -i "${MOSAIC_CI_QUEUE_POLL_SEC:-15}"

packages/mosaic/framework/tools/git/pr-metadata.sh

@@ -209,6 +209,10 @@ base_ref = first_non_empty(
     data.get('base_ref'),
     data.get('base_label'),
 )
+base_repo = first_non_empty(
+    nested(data, 'base', 'repo', 'full_name'),
+    nested(data, 'base', 'repo', 'name_with_owner'),
+)
 
 if not head_ref or not base_ref:
     available = ', '.join(sorted(data.keys()))
@@ -229,6 +233,7 @@ normalized = {
     'headRefOid': head_sha,
     'headRepository': head_repo,
     'baseRefName': base_ref,
+    'baseRepository': base_repo,
     'labels': [l.get('name', '') for l in data.get('labels', []) if isinstance(l, dict)],
     'assignees': [a.get('login', '') for a in data.get('assignees', []) if isinstance(a, dict)],
     'milestone': nested(data, 'milestone', 'title') or '',

packages/mosaic/framework/tools/git/pr-review.sh

@@ -12,7 +12,7 @@
 # concurrent record cannot masquerade as this write and a no-op fails closed.
 #
 # --login override: the default login is resolved from the local tea login list
-# for this repo's host (get_gitea_login_for_host). Pass --login <name> to
+# for this repo's host from the acting identity's own credential. Pass --login <name> to
 # override it for this invocation only. The REST write, the /user identity read,
 # and every read-back are ALL performed with the token of the EFFECTIVE login,
 # so the write and its verification bind to the same identity.
@@ -372,9 +372,17 @@ gitea_resolve_api_for_login() {
             return 1
         }
     else
-        GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") \
+        # NO --login: the acting credential is this identity's own token and there
-            || GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+        # is deliberately no tea-config fallback. get_gitea_token_for_login matches
-            echo "Error: Gitea token not found for login '$effective_login' (review write/read-back)" >&2
+        # by login NAME and performs no authentication check, and with no --login
+        # that name was a HOST GUESS resolving to a shared account. A live shared
+        # token would therefore have authored every seat's review as that
+        # account, making Gate-16 author-is-not-reviewer unenforceable fleet-wide;
+        # a dead one is only what made the defect visible. get_gitea_token fails
+        # loud on a fleet host when no identity resolves, and that refusal is the
+        # correct outcome, not a case to fall back from.
+        GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+            echo "Error: no Gitea credential resolved for the acting identity on host '$host' (review write/read-back). Set MOSAIC_GIT_IDENTITY=<agent-id>, or pass --login <name> to use a named tea credential." >&2
             return 1
         }
     fi
@@ -698,7 +706,7 @@ if [[ "$PLATFORM" == "github" ]]; then
 elif [[ "$PLATFORM" == "gitea" ]]; then
     case $ACTION in
         approve)
-            # Best-effort host for the tea-login GUESS only (gitea_resolve_api_for_login
+            # Best-effort host for credential resolution 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
@@ -706,15 +714,13 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             # 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
+            # A --login override selects a NAMED tea credential and is the only
-            # only as a best effort: the login name merely selects a per-login
+            # way to reach the tea store. With no --login there is deliberately no
-            # token, and gitea_resolve_api_for_login falls back to the host
+            # guess: gitea_resolve_api_for_login resolves this identity's own token.
-            # credential (get_gitea_token) when no tea login is named — so a host
+            # The guess this replaced named a SHARED account, selecting an identity
-            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the caller never asked to act as. The single resolved token is then
-            # the default credential to resolve. The single resolved token is
+            # used for the write, the /user identity, and the read-back.
-            # 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.
@@ -735,7 +741,7 @@ 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
+            # Best-effort host for credential resolution 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
@@ -743,15 +749,13 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             # 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
+            # A --login override selects a NAMED tea credential and is the only
-            # only as a best effort: the login name merely selects a per-login
+            # way to reach the tea store. With no --login there is deliberately no
-            # token, and gitea_resolve_api_for_login falls back to the host
+            # guess: gitea_resolve_api_for_login resolves this identity's own token.
-            # credential (get_gitea_token) when no tea login is named — so a host
+            # The guess this replaced named a SHARED account, selecting an identity
-            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the caller never asked to act as. The single resolved token is then
-            # the default credential to resolve. The single resolved token is
+            # used for the write, the /user identity, and the read-back.
-            # 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
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
@@ -766,7 +770,7 @@ 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
+            # Best-effort host for credential resolution 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
@@ -774,15 +778,13 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             # 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
+            # A --login override selects a NAMED tea credential and is the only
-            # only as a best effort: the login name merely selects a per-login
+            # way to reach the tea store. With no --login there is deliberately no
-            # token, and gitea_resolve_api_for_login falls back to the host
+            # guess: gitea_resolve_api_for_login resolves this identity's own token.
-            # credential (get_gitea_token) when no tea login is named — so a host
+            # The guess this replaced named a SHARED account, selecting an identity
-            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the caller never asked to act as. The single resolved token is then
-            # the default credential to resolve. The single resolved token is
+            # used for the write, the /user identity, and the read-back.
-            # 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
             ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             comment_id=$(gitea_create_comment_verified "$PR_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {

packages/mosaic/framework/tools/git/test-pr-merge-fork-ci-status.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# B1 (stack #1215, gate-merge-01): for a fork PR the merge queue guard must
+# read CI status against the BASE repository. Woodpecker posts statuses on the
+# base repo; pr-metadata's headRepository names the fork, and passing it to
+# ci-queue-wait yields statuses:null -> state=malformed rc=3 on every fork PR.
+#
+# This fixture omits baseRepository entirely (the pre-B1 normalizer's shape),
+# so the guard must fall back to the origin repo — and must NEVER see the fork.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-fork-ci-status}"
+FIXTURE_DIR="$WORK_DIR/tools/git"
+CALL_LOG="$WORK_DIR/queue-call.log"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FIXTURE_DIR"
+cp "$SCRIPT_DIR/pr-merge.sh" "$FIXTURE_DIR/pr-merge.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$FIXTURE_DIR/detect-platform.sh"
+
+cat > "$FIXTURE_DIR/pr-metadata.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' '{"baseRefName":"next","headRefName":"fix/b1-fork-branch","headRefOid":"fedcba9876543210fedcba9876543210fedcba98","headRepository":"stack-mos-dt-0/stack"}'
+SH
+
+cat > "$FIXTURE_DIR/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' "$*" > "${MOSAIC_QUEUE_CALL_LOG:?}"
+exit 42
+SH
+chmod +x "$FIXTURE_DIR"/*.sh
+
+# A git repo with an origin remote, so the origin fallback resolves.
+git init -q "$WORK_DIR/upstream"
+git -C "$WORK_DIR/upstream" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
+
+set +e
+(
+    cd "$WORK_DIR/upstream"
+    export MOSAIC_QUEUE_CALL_LOG="$CALL_LOG"
+    "$FIXTURE_DIR/pr-merge.sh" -n 1215
+) >/dev/null 2>&1
+rc=$?
+set -e
+
+if [[ "$rc" -ne 42 ]]; then
+    echo "FAIL: expected queue stub rc=42 to propagate, got $rc" >&2
+    exit 1
+fi
+if [[ ! -s "$CALL_LOG" ]]; then
+    echo "FAIL: merge wrapper did not invoke the queue guard" >&2
+    exit 1
+fi
+if grep -q -- '-R stack-mos-dt-0/stack' "$CALL_LOG"; then
+    echo "FAIL: queue guard received the FORK repository for CI status (B1 regression)" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if ! grep -q -- '-R mosaicstack/stack' "$CALL_LOG"; then
+    echo "FAIL: queue guard did not receive the base (origin) repository" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if ! grep -q -- '-B fix/b1-fork-branch' "$CALL_LOG"; then
+    echo "FAIL: queue guard did not receive the PR head branch" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if ! grep -q -- '--sha fedcba9876543210fedcba9876543210fedcba98' "$CALL_LOG"; then
+    echo "FAIL: queue guard did not receive the exact PR head SHA" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+
+echo "pr-merge fork-PR CI-status repository regression passed"

packages/mosaic/framework/tools/git/test-pr-merge-queue-branch.sh

@@ -15,7 +15,7 @@ cp "$SCRIPT_DIR/detect-platform.sh" "$FIXTURE_DIR/detect-platform.sh"
 
 cat > "$FIXTURE_DIR/pr-metadata.sh" <<'SH'
 #!/usr/bin/env bash
-printf '%s\n' '{"baseRefName":"main","headRefName":"fix/rm-03-fixture","headRefOid":"0123456789abcdef0123456789abcdef01234567","headRepository":"contributor/widgets-fork"}'
+printf '%s\n' '{"baseRefName":"main","baseRepository":"mosaicstack/stack","headRefName":"fix/rm-03-fixture","headRefOid":"0123456789abcdef0123456789abcdef01234567","headRepository":"contributor/widgets-fork"}'
 SH
 
 cat > "$FIXTURE_DIR/ci-queue-wait.sh" <<'SH'
@@ -52,8 +52,13 @@ if grep -q -- '-B main' "$CALL_LOG"; then
     cat "$CALL_LOG" >&2
     exit 1
 fi
-if ! grep -q -- '-R contributor/widgets-fork' "$CALL_LOG"; then
+if ! grep -q -- '-R mosaicstack/stack' "$CALL_LOG"; then
-    echo "FAIL: merge queue guard did not receive the fork head repository" >&2
+    echo "FAIL: merge queue guard did not receive the BASE repository for CI status" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if grep -q -- '-R contributor/widgets-fork' "$CALL_LOG"; then
+    echo "FAIL: merge queue guard received the fork head repository (B1: statuses are posted on the base repo)" >&2
     cat "$CALL_LOG" >&2
     exit 1
 fi

packages/mosaic/framework/tools/lease-broker/revoke-lease.py

@@ -54,6 +54,22 @@ def main(
     arguments = parser.parse_args(argv)
     source_environment = os.environ if environ is None else environ
 
+    # D29: a session that never held a lease has nothing to revoke, and that is a
+    # SUCCESS, not a failed revocation. The block below is deliberately fail-closed
+    # for a broker that is unreachable, which is right — but it cannot distinguish
+    # "the broker is down" from "there was never a lease", so a bare-launched
+    # session was denied every lifecycle transition, including compaction. Denying
+    # compaction protects nothing there; it converts a recoverable context limit
+    # into a lost session.
+    #
+    # Absence must be TOTAL to qualify. If exactly one variable is present the
+    # session is half-provisioned, which is real misconfiguration, and it still
+    # takes the fail-closed path below.
+    lease_variables = ("MOSAIC_LEASE_BROKER_SOCKET", "MOSAIC_LEASE_SESSION_ID")
+    present = [name for name in lease_variables if source_environment.get(name)]
+    if not present:
+        return 0
+
     try:
         if not arguments.reason or len(arguments.reason) > 128:
             raise ValueError("invalid revoke reason")

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -126,7 +126,16 @@ if [ -z "$SRC_LABEL" ]; then
   src_host=$(hostname -s 2>/dev/null || echo "?")
   src_sess=${MOSAIC_AGENT_NAME:-}
   if [ -z "$src_sess" ]; then
-    src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
+    if [ -n "${TMUX:-}" ]; then
+      # Inside tmux: display-message resolves against this client's own session.
+      src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
+    else
+      # Outside tmux with no name: display-message reports the LAST-ACTIVE
+      # session — someone else's identity (measured 2026-08-20: a nameless
+      # non-tmux sender was stamped "peggy", a live seat, forged silently).
+      # Stamp an explicit unverified label instead; deliberate senders use -S.
+      src_sess="unverified"
+    fi
   fi
   SRC_LABEL="${src_host}:${src_sess}"
 fi

packages/mosaic/framework/tools/tmux/agent-send.test.sh

@@ -61,8 +61,15 @@ no()   { FAIL=$((FAIL+1)); printf 'FAIL %s\n   %s\n' "$1" "$2"; }
 
 # Run the tool with the stub injected; echoes captured payload on stdout.
 run() { AGENT_SEND_SENDER="$STUB" bash "$TOOL" -S a:src -n dsthost "$@"; }
-run_auto() {
+# Hermetic auto-label runs: TMUX is controlled explicitly so results never
-  env -u MOSAIC_AGENT_NAME \
+# depend on whether the caller running this suite sits inside tmux.
+run_auto() {          # models a sender OUTSIDE tmux (no client context)
+  env -u MOSAIC_AGENT_NAME -u TMUX \
+    AGENT_SEND_SENDER="$STUB" PATH="$FAKE_BIN:$PATH" \
+    bash "$TOOL" -n dsthost "$@"
+}
+run_auto_in_tmux() {  # models a sender INSIDE tmux (client context exists)
+  env -u MOSAIC_AGENT_NAME TMUX=/fake/socket \
     AGENT_SEND_SENDER="$STUB" PATH="$FAKE_BIN:$PATH" \
     bash "$TOOL" -n dsthost "$@"
 }
@@ -145,7 +152,9 @@ want="[$src_host:authoritative-agent -> dsthost:mos] env identity"
   || no "MOSAIC_AGENT_NAME is authoritative across sockets" "got=[$got] want=[$want]"
 
 # 9. Without the env identity, self-lookup uses local tmux, not destination -L.
-got=$(FAKE_TMUX_MODE=sessions run_auto -L destination-socket -s mos -m "local fallback")
+#    Sender is INSIDE tmux: the only context where display-message self-lookup
+#    is safe (it resolves against this client's own session).
+got=$(FAKE_TMUX_MODE=sessions run_auto_in_tmux -L destination-socket -s mos -m "local fallback")
 want="[$src_host:local-agent -> dsthost:mos] local fallback"
 [ "$got" = "$want" ] && ok "cross-socket fallback uses local sender session" \
   || no "cross-socket fallback uses local sender session" "got=[$got] want=[$want]"
@@ -153,8 +162,17 @@ want="[$src_host:local-agent -> dsthost:mos] local fallback"
   && ok "cross-socket fallback rejects destination holder identity" \
   || no "cross-socket fallback rejects destination holder identity" "got=[$got]"
 
+# 9b. NO tmux context: display-message answers with the LAST-ACTIVE session —
+#     someone else's identity (forgery vector). The label must be `unverified`,
+#     never a borrowed name, even though a tmux server exists here and the fake
+#     would confidently answer `local-agent`.
+got=$(FAKE_TMUX_MODE=sessions run_auto -s mos -m "no tmux context")
+want="[$src_host:unverified -> dsthost:mos] no tmux context"
+[ "$got" = "$want" ] && ok "no-tmux sender labeled unverified, never borrowed" \
+  || no "no-tmux sender labeled unverified, never borrowed" "got=[$got] want=[$want]"
+
 # 10. If neither env nor local tmux identifies the sender, preserve '?'.
-got=$(FAKE_TMUX_MODE=unavailable run_auto -L destination-socket -s mos -m "unknown fallback")
+got=$(FAKE_TMUX_MODE=unavailable run_auto_in_tmux -L destination-socket -s mos -m "unknown fallback")
 want="[$src_host:? -> dsthost:mos] unknown fallback"
 [ "$got" = "$want" ] && ok "unknown sender falls back to ?" \
   || no "unknown sender falls back to ?" "got=[$got] want=[$want]"

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "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 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.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-edit.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-no-status.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-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.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 && bash framework/tools/_scripts/test-brain-home-check.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.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/lease-broker/revoke_noop_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-edit.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-no-status.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-fork-ci-status.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-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.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 && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/commands/fleet-north-star.spec.ts

@@ -147,11 +147,11 @@ describe('renderNorthStarMarkdown', () => {
         'standing_objectives:',
         '  - { id: NS-1, text: t }',
         'success_criteria:',
-        '  - { id: AC-NS-1, text: t }',
+        '  - { id: AC-NS-1, text: t, tier: 0 }',
         'workstreams:',
         '  - { id: A, title: t }',
         'goals:',
-        '  - { id: A1, title: t, phase: 1, priority: must-have, depends_on: [] }',
+        '  - { id: A1, title: t, phase: 1, tier: 0, priority: must-have, depends_on: [] }',
         'assumptions:',
         '  - { id: ASM-1, vetoable: true, text: t }',
         'spend:',

packages/mosaic/src/commands/fleet-place-unit.spec.ts

@@ -0,0 +1,177 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { placeUnitFile, resolveLeaseBrokerSocketForPreflight } from './fleet.js';
+
+/**
+ * Unit-placement regression harness for #1292.
+ *
+ * The two measured defects this suite pins:
+ *  1. `systemctl enable <name>` does NOT rewrite an existing by-path
+ *     wants-symlink — so placement must remove stale residue explicitly, and
+ *     acceptance asserts on the RESULTING SYMLINK TARGET, never on the enable
+ *     call's argument (asserting the call cannot see where the link ended up).
+ *  2. Node's copyFile FOLLOWS a by-path symlink at the destination and
+ *     overwrites the SEED template. Acceptance asserts on the SEED's bytes
+ *     AND mtime — unchanged — which is the only check that can redden for
+ *     finding 2. The symlink-target assertion catches finding 1; these are
+ *     different defects with different failure modes.
+ *
+ * Fixtures are entirely inside tmpdirs (source template, active systemd dir,
+ * wants dir) — no real host paths are touched by this suite.
+ */
+
+describe('placeUnitFile (#1292 unit placement)', () => {
+  const cleanup: string[] = [];
+  afterEach(async () => {
+    while (cleanup.length > 0) {
+      await rm(cleanup.pop()!, { recursive: true, force: true });
+    }
+  });
+
+  async function fixture() {
+    const root = await mkdtemp(join(tmpdir(), 'place-unit-'));
+    cleanup.push(root);
+    const seedDir = join(root, 'seed');
+    const activeDir = join(root, 'active');
+    await mkdir(seedDir, { recursive: true });
+    await mkdir(activeDir, { recursive: true });
+    const seedTemplate = join(seedDir, 'unit-under-test.service');
+    await writeFile(
+      seedTemplate,
+      '[Unit]\nDescription=seed template\n[Service]\nType=oneshot\nExecStart=/bin/true\n[Install]\nWantedBy=default.target\n',
+    );
+    const activeSource = join(root, 'active-source.service');
+    await writeFile(
+      activeSource,
+      '[Unit]\nDescription=active copy v2\n[Service]\nType=oneshot\nExecStart=/bin/true\n[Install]\nWantedBy=default.target\n',
+    );
+    return { root, seedDir, activeDir, seedTemplate, activeSource };
+  }
+
+  it('places a regular file on a clean host (negative control: no residue anywhere)', async () => {
+    const f = await fixture();
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    expect(result.unlinkedDestinationSymlink).toBe(false);
+    expect(result.removedStaleWantsSymlink).toBe(false);
+    const info = await lstat(join(f.activeDir, 'unit-under-test.service'));
+    expect(info.isSymbolicLink()).toBe(false);
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toContain(
+      'active copy v2',
+    );
+    // Seed untouched by construction — but assert it, so the clean-host case
+    // cannot silently regress into seed-mutation.
+    expect(await readFile(f.seedTemplate, 'utf8')).toContain('seed template');
+  });
+
+  it('by-path residue: unlinks destination symlink, places the file, seed bytes AND mtime unchanged (finding 2)', async () => {
+    const f = await fixture();
+    const seedBefore = await readFile(f.seedTemplate, 'utf8');
+    const mtimeBefore = (await lstat(f.seedTemplate)).mtimeMs;
+    // The fomo-lin convention: by-path enable left a symlink AT the unit name
+    // pointing at the seed template, plus a wants-symlink doing the same.
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    expect(result.unlinkedDestinationSymlink).toBe(true);
+    expect(result.removedStaleWantsSymlink).toBe(true);
+
+    // FINDING 2's check: the seed is byte-identical and its mtime did not move.
+    expect(await readFile(f.seedTemplate, 'utf8')).toBe(seedBefore);
+    expect((await lstat(f.seedTemplate)).mtimeMs).toBe(mtimeBefore);
+
+    // The destination is now a regular file carrying the ACTIVE content.
+    const destInfo = await lstat(join(f.activeDir, 'unit-under-test.service'));
+    expect(destInfo.isSymbolicLink()).toBe(false);
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toContain(
+      'active copy v2',
+    );
+  });
+
+  it('by-path residue: no wants-symlink remains pointing at the seed (finding 1 residue cleared)', async () => {
+    const f = await fixture();
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+
+    // After placement the stale wants link is GONE (enable-by-name recreates
+    // it correctly). A link still present must not point at the seed.
+    try {
+      const link = await lstat(join(wantsDir, 'unit-under-test.service'));
+      if (link.isSymbolicLink()) {
+        const target = await readFile(join(wantsDir, 'unit-under-test.service'), 'utf8').catch(
+          async () => '',
+        );
+        expect(target).not.toContain('seed template');
+      }
+    } catch {
+      // absent wants link — the expected post-placement state
+    }
+  });
+
+  it('idempotence: second placement on a reconciled host is a no-op producing the identical final state', async () => {
+    const f = await fixture();
+    // Reconciled starting state: regular file at the name, wants link to the active copy.
+    await writeFile(
+      join(f.activeDir, 'unit-under-test.service'),
+      await readFile(f.activeSource, 'utf8'),
+    );
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(
+      join(f.activeDir, 'unit-under-test.service'),
+      join(wantsDir, 'unit-under-test.service'),
+    );
+    const before = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+
+    const result = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    // No destructive step fired: no unlink, no wants removal.
+    expect(result.unlinkedDestinationSymlink).toBe(false);
+    expect(result.removedStaleWantsSymlink).toBe(false);
+    // Identical final state.
+    expect(await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8')).toBe(before);
+    const link = await lstat(join(wantsDir, 'unit-under-test.service'));
+    expect(link.isSymbolicLink()).toBe(true);
+  });
+
+  it('double install on by-path residue converges to the identical reconciled state', async () => {
+    const f = await fixture();
+    await symlink(f.seedTemplate, join(f.activeDir, 'unit-under-test.service'));
+    const wantsDir = join(f.activeDir, 'default.target.wants');
+    await mkdir(wantsDir, { recursive: true });
+    await symlink(f.seedTemplate, join(wantsDir, 'unit-under-test.service'));
+
+    await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    const first = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+    const secondRun = await placeUnitFile(f.activeSource, f.activeDir, 'unit-under-test.service');
+    const second = await readFile(join(f.activeDir, 'unit-under-test.service'), 'utf8');
+    expect(secondRun.unlinkedDestinationSymlink).toBe(false);
+    expect(second).toBe(first);
+  });
+});
+
+describe('resolveLeaseBrokerSocketForPreflight (#1292 preflight resolution)', () => {
+  it('explicit MOSAIC_LEASE_BROKER_SOCKET wins', () => {
+    expect(
+      resolveLeaseBrokerSocketForPreflight({ MOSAIC_LEASE_BROKER_SOCKET: '/custom/sock' }, 1000),
+    ).toBe('/custom/sock');
+  });
+  it('XDG_RUNTIME_DIR next', () => {
+    expect(resolveLeaseBrokerSocketForPreflight({ XDG_RUNTIME_DIR: '/run/user/1001' }, 1000)).toBe(
+      '/run/user/1001/mosaic-lease/broker.sock',
+    );
+  });
+  it('falls back to /run/user/<uid>', () => {
+    expect(resolveLeaseBrokerSocketForPreflight({}, 1002)).toBe(
+      '/run/user/1002/mosaic-lease/broker.sock',
+    );
+  });
+});

packages/mosaic/src/commands/fleet-reconciler-command.spec.ts

@@ -73,6 +73,10 @@ function program(
     runner,
     reconcileDeps: {
       homeDirectory: '/home/mosaic',
+      // Deterministic broker presence: without a seam the reconciler probes the
+      // REAL host socket (#1297 F3), making every CLI start test answer the
+      // host's broker state instead of its own property.
+      checkBrokerSocket: async () => true,
       readHolderIdentity: async () => '11111111-1111-4111-8111-111111111111',
       validateRoster: async () => undefined,
       prepareProjections: async () => [{ agentName: 'coder0' }],

packages/mosaic/src/commands/fleet.spec.ts

@@ -1,11 +1,24 @@
-import { chmod, lstat, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import {
+  chmod,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readlink,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { createServer } from 'node:net';
 import { Command } from 'commander';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   acquireRestartLock,
   addAgentToRoster,
+  brokerSocketPresent,
   buildAgentSendCommand,
   buildAgentWatchAttachCommand,
   buildAgentWatchCommand,
@@ -42,6 +55,7 @@ import {
   parseSystemdShow,
   parseTmuxListPanes,
   parseTmuxListSessions,
+  placeUnitFile,
   registerFleetCommand,
   removeAgentFromRoster,
   resolveFleetPaths,
@@ -50,6 +64,7 @@ import {
   RESTART_LOCK_STALE_MS,
   RUNTIME_ACCEPTABLE_COMMANDS,
   serializeRosterToYaml,
+  UnitPlacementError,
   VERIFY_DEFAULT_TIMEOUT_MS,
   VERIFY_POLL_INTERVAL_MS,
   type AgentPsRow,
@@ -836,13 +851,25 @@ describe('fleet command construction', () => {
     };
     const program = new Command();
     program.exitOverride();
-    registerFleetCommand(program, { runner, mosaicHome: home });
+    // #1292: inject a present broker socket so the preflight passes and this
+    // spec keeps testing its ORIGINAL property (holder-before-agent ordering).
+    // The preflight's own refusal behavior has dedicated specs below.
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => true,
+    });
 
     try {
       await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
       await program.parseAsync(['node', 'mosaic', 'fleet', 'stop']);
 
       expect(calls).toEqual([
+        // #1292: fleet start enables + starts the broker FIRST (enable is
+        // idempotent; the unit exists after install), re-checking the socket
+        // before any holder/agent lifecycle effect.
+        ['systemctl', '--user', 'enable', 'mosaic-lease-broker.service'],
+        ['systemctl', '--user', 'start', 'mosaic-lease-broker.service'],
         ['systemctl', '--user', 'start', 'mosaic-tmux-holder.service'],
         ['systemctl', '--user', 'start', '[email protected]'],
         ['systemctl', '--user', 'stop', '[email protected]'],
@@ -853,6 +880,92 @@ describe('fleet command construction', () => {
     }
   });
 
+  it('fleet start refuses with a named error when the broker socket does not appear (#1292)', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    await mkdir(join(home, 'fleet'), { recursive: true });
+    await writeFile(
+      rosterPath,
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
+        '\n',
+      ),
+    );
+    const calls: string[][] = [];
+    const runner: CommandRunner = async (command, args) => {
+      calls.push([command, ...args]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    };
+    const program = new Command();
+    program.exitOverride();
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.join(' '));
+    };
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => false,
+    });
+    try {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      // Refused: no holder/agent starts were issued after the broker attempt.
+      expect(calls).toEqual([
+        ['systemctl', '--user', 'enable', 'mosaic-lease-broker.service'],
+        ['systemctl', '--user', 'start', 'mosaic-lease-broker.service'],
+      ]);
+      expect(errors.join('\n')).toContain('broker-absent');
+      expect(errors.join('\n')).toContain('mosaic fleet install');
+    } finally {
+      console.error = origError;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('fleet start re-probes the broker on the SECOND invocation — no ActiveState trust (#1292 sticky half)', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    await mkdir(join(home, 'fleet'), { recursive: true });
+    await writeFile(
+      rosterPath,
+      ['version: 1', 'transport: tmux', 'agents:', '  - name: coder0', '    runtime: codex'].join(
+        '\n',
+      ),
+    );
+    const calls: string[][] = [];
+    const runner: CommandRunner = async (command, args) => {
+      calls.push([command, ...args]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    };
+    const program = new Command();
+    program.exitOverride();
+    // Broker socket NEVER appears — the second start must refuse exactly like
+    // the first; RemainAfterExit-style stale unit state changes nothing
+    // because the check is the socket, not systemctl.
+    registerFleetCommand(program, {
+      runner,
+      mosaicHome: home,
+      checkBrokerSocket: async () => false,
+    });
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.join(' '));
+    };
+    try {
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      await program.parseAsync(['node', 'mosaic', 'fleet', 'start']);
+      // Two invocations, each refusing after its own broker attempt:
+      expect(
+        calls.filter((c) => c.join(' ') === 'systemctl --user start [email protected]'),
+      ).toHaveLength(0);
+      expect(errors.filter((e) => e.includes('broker-absent')).length).toBeGreaterThanOrEqual(2);
+    } finally {
+      console.error = origError;
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
   it('waits for an in-flight restart to clear before relaunching (re-entry guard)', async () => {
     const home = await tempDir();
     const rosterPath = join(home, 'fleet', 'roster.yaml');
@@ -2066,8 +2179,19 @@ describe('fleet install — auto-enable units for boot-survival', () => {
 
     await enableFleetUnits(runner, minimalRoster, {});
 
+    expect(calls).toContainEqual(['systemctl', '--user', 'enable', 'mosaic-lease-broker.service']);
     expect(calls).toContainEqual(['systemctl', '--user', 'enable', 'mosaic-tmux-holder.service']);
     expect(calls).toContainEqual(['systemctl', '--user', 'enable', '[email protected]']);
+    // The broker must be enabled BEFORE the holder and agents: a start of any
+    // gated runtime without the broker is exactly the #1292 4-second death.
+    const brokerIndex = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-lease-broker.service',
+    );
+    const holderIndex = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-tmux-holder.service',
+    );
+    expect(brokerIndex).toBeGreaterThanOrEqual(0);
+    expect(brokerIndex).toBeLessThan(holderIndex);
   });
 
   it('install still succeeds when systemctl enable returns non-zero (non-fatal)', async () => {
@@ -4362,3 +4486,70 @@ describe('fleet ps — heartbeat path resolution', () => {
     );
   });
 });
+
+describe('#1297 review: the real broker probe, exercised without any seam', () => {
+  it('brokerSocketPresent answers a REAL unix socket via stat().isSocket() (access(S_IFSOCK) threw ERR_OUT_OF_RANGE)', async () => {
+    const dir = await tempDir();
+    const sockPath = join(dir, 'broker.sock');
+    const server = createServer();
+    await new Promise<void>((resolve) => {
+      server.listen(sockPath, resolve);
+    });
+    try {
+      // A live unix socket answers true through the REAL probe — no seam.
+      expect(await brokerSocketPresent({}, { MOSAIC_LEASE_BROKER_SOCKET: sockPath })).toBe(true);
+      // Discrimination is by file type: a regular file that EXISTS is not a
+      // socket. The old implementation could not reach either verdict — it
+      // threw ERR_OUT_OF_RANGE (node >= 24) and the catch answered false.
+      const notASocket = join(dir, 'not-a-sock');
+      await writeFile(notASocket, 'x');
+      expect(await brokerSocketPresent({}, { MOSAIC_LEASE_BROKER_SOCKET: notASocket })).toBe(false);
+      // Absent path: false, not a throw.
+      expect(
+        await brokerSocketPresent({}, { MOSAIC_LEASE_BROKER_SOCKET: join(dir, 'gone.sock') }),
+      ).toBe(false);
+    } finally {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+    }
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  // EACCES-based unlink failure requires a non-root uid: root bypasses
+  // directory mode bits (CAP_DAC_OVERRIDE), so the abort path cannot be
+  // triggered this way under CI's root runner. Skipped there, exercised on
+  // every non-root dev host.
+  const itUnlessRoot =
+    typeof process.getuid === 'function' && process.getuid() === 0 ? it.skip : it;
+  itUnlessRoot(
+    'placeUnitFile aborts with UnitPlacementError when unlink fails — never copies through a live symlink',
+    async () => {
+      const dir = await tempDir();
+      const unitDir = join(dir, 'systemd', 'user');
+      await mkdir(unitDir, { recursive: true });
+      // By-path residue: destination is a symlink pointing somewhere else.
+      const residueTarget = join(dir, 'residue-target');
+      await writeFile(residueTarget, 'RESIDUE-BYTES');
+      const destination = join(unitDir, 'x.service');
+      await symlink(residueTarget, destination);
+      const source = join(dir, 'seed.service');
+      await writeFile(source, 'UNIT-BYTES');
+      // Read-only unit dir: unlink now fails EACCES (test runs as the owner,
+      // not root, so mode bits are enforced).
+      await chmod(unitDir, 0o500);
+      try {
+        await expect(placeUnitFile(source, unitDir, 'x.service')).rejects.toThrow(
+          UnitPlacementError,
+        );
+      } finally {
+        await chmod(unitDir, 0o700);
+      }
+      // The copy-through never happened: residue bytes intact, destination
+      // still the symlink (abort, not overwrite-through).
+      expect(await readFile(residueTarget, 'utf8')).toBe('RESIDUE-BYTES');
+      expect(await readlink(destination)).toBe(residueTarget);
+      await rm(dir, { recursive: true, force: true });
+    },
+  );
+});

packages/mosaic/src/commands/fleet.ts

@@ -1,11 +1,13 @@
-import { constants } from 'node:fs';
+import { constants, type Stats } from 'node:fs';
 import {
   access,
   chmod,
   copyFile,
+  lstat,
   mkdir,
   open,
   readFile,
+  readlink,
   stat,
   unlink,
   writeFile,
@@ -90,6 +92,8 @@ export type SleepFn = (ms: number) => Promise<void>;
 
 export interface FleetCommandDeps {
   runner?: CommandRunner;
+  /** Test seam for the #1292 fleet-start broker preflight (socket presence). */
+  checkBrokerSocket?: (path: string) => Promise<boolean> | boolean;
   /** Injectable interactive runner for commands needing inherited TTY (e.g., `tmux attach`). */
   interactiveRunner?: InteractiveRunner;
   /**
@@ -191,6 +195,10 @@ export interface NorthStarIdText {
   text: string;
 }
 
+export interface NorthStarCriterion extends NorthStarIdText {
+  tier: number;
+}
+
 export interface NorthStarWorkstream {
   id: string;
   title: string;
@@ -200,6 +208,8 @@ export interface NorthStarGoal {
   id: string;
   title: string;
   phase: number;
+  /** Capability tier this goal serves: 0 dogfood, 1 MVP, 2 full vision. Orthogonal to phase, which is build order. */
+  tier: number;
   priority: string;
   depends_on: string[];
 }
@@ -220,7 +230,7 @@ export interface NorthStar {
   mission: string;
   substrate: { note: string };
   standing_objectives: NorthStarIdText[];
-  success_criteria: NorthStarIdText[];
+  success_criteria: NorthStarCriterion[];
   workstreams: NorthStarWorkstream[];
   goals: NorthStarGoal[];
   assumptions: NorthStarAssumption[];
@@ -280,9 +290,13 @@ export function parseNorthStar(rawText: string): NorthStar {
     standing_objectives: requireArray(parsed.standing_objectives, 'standing_objectives').map(
       (row, i) => idText(row, 'standing_objectives', i),
     ),
-    success_criteria: requireArray(parsed.success_criteria, 'success_criteria').map((row, i) =>
+    success_criteria: requireArray(parsed.success_criteria, 'success_criteria').map((row, i) => {
-      idText(row, 'success_criteria', i),
+      const tier = (row as Record<string, unknown>)?.tier;
-    ),
+      if (typeof tier !== 'number') {
+        throw new Error(`NORTH_STAR.yaml: success_criteria[${i}].tier must be a number.`);
+      }
+      return { ...idText(row, 'success_criteria', i), tier };
+    }),
     workstreams: requireArray(parsed.workstreams, 'workstreams').map((row, i) => {
       const ws = row as Record<string, unknown>;
       return {
@@ -300,10 +314,15 @@ export function parseNorthStar(rawText: string): NorthStar {
       if (typeof phase !== 'number') {
         throw new Error(`NORTH_STAR.yaml: goals[${i}].phase must be a number.`);
       }
+      const tier = goal?.tier;
+      if (typeof tier !== 'number') {
+        throw new Error(`NORTH_STAR.yaml: goals[${i}].tier must be a number.`);
+      }
       return {
         id: requireString(goal?.id, `goals[${i}].id`),
         title: requireString(goal?.title, `goals[${i}].title`),
         phase,
+        tier,
         priority: requireString(goal?.priority, `goals[${i}].priority`),
         depends_on: dependsRaw.map((dep, j) => requireString(dep, `goals[${i}].depends_on[${j}]`)),
       };
@@ -349,7 +368,7 @@ function renderMarkdownTable(headers: string[], rows: string[][]): string[] {
  * Pure function of its input — same input always yields byte-identical output,
  * so the round-trip (YAML → render → write) is stable across runs. No clock, no
  * network, no CLI. Layout follows the repo's existing doctrine-doc convention
- * (heading, blockquote banner, then sections + tables, e.g. north-star.md /
+ * (heading, blockquote banner, then sections + tables, e.g. FLEET-DOCTRINE.md /
  * mission-control/BOARD.md).
  */
 export function renderNorthStarMarkdown(ns: NorthStar): string {
@@ -362,7 +381,7 @@ export function renderNorthStarMarkdown(ns: NorthStar): string {
     '> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure',
   );
   lines.push('> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).');
-  lines.push('> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.');
+  lines.push('> Edit the YAML, then regenerate. Self-contained Mosaic.');
   lines.push('');
 
   lines.push('## Mission');
@@ -385,7 +404,7 @@ export function renderNorthStarMarkdown(ns: NorthStar): string {
   lines.push('## Success criteria');
   lines.push('');
   for (const ac of ns.success_criteria) {
-    lines.push(`- **${ac.id}** — ${ac.text}`);
+    lines.push(`- **${ac.id}** (tier ${ac.tier}) — ${ac.text}`);
   }
   lines.push('');
 
@@ -403,10 +422,11 @@ export function renderNorthStarMarkdown(ns: NorthStar): string {
   lines.push('');
   lines.push(
     ...renderMarkdownTable(
-      ['id', 'title', 'phase', 'priority', 'depends_on'],
+      ['id', 'title', 'tier', 'phase', 'priority', 'depends_on'],
       ns.goals.map((goal) => [
         goal.id,
         goal.title,
+        String(goal.tier),
         String(goal.phase),
         goal.priority,
         goal.depends_on.length > 0 ? goal.depends_on.join(', ') : '—',
@@ -799,6 +819,135 @@ export function buildSystemdEnableCommand(unit: string): string[] {
   return ['systemctl', '--user', 'enable', unit];
 }
 
+/**
+ * Place a unit file into the ACTIVE systemd user directory, never through a
+ * symlink (#1292, measured 2026-08-17).
+ *
+ * ⚠ SET-INDEPENDENCE (fomo-lin, 2026-08-17): the set of unit names carrying
+ * by-path residue and the set of unit names this install copies are
+ * INDEPENDENT. Until 0.0.50 they were disjoint only by accident of which
+ * units the install happened to name — fomo-lin survived copy-through solely
+ * because its one by-path symlink (the broker) was the one unit the install
+ * did NOT copy. Adding the broker to the copy set made the intersection
+ * non-empty on the first run. Whoever adds a fifth unit to the placement
+ * list inherits this helper and its unlink step; do not place units with a
+ * bare copyFile.
+ *
+ * A host provisioned by the enable-by-path convention carries a symlink AT
+ * the unit-name path in ~/.config/systemd/user/ pointing at the shipped
+ * template under ~/.config/mosaic/systemd/user/. Node's copyFile FOLLOWS
+ * that link and overwrites the SEED template instead of placing the active
+ * unit (verified with fs.copyFile on a throwaway systemd user instance) —
+ * silent, rc=0, and it mutates the directory every later reseed reads from.
+ * The same measurement showed `systemctl enable <name>` does NOT rewrite an
+ * existing by-path wants-symlink, so reconciliation must be explicit.
+ *
+ * Placement therefore: if the destination is a symlink, unlink it first
+ * (unlink → copy — copy-then-unlink would mutate the seed and then destroy
+ * the evidence that it did); then copy. Also removes a stale
+ * `default.target.wants/<name>` symlink that points outside the active
+ * directory (readlink — NOT readFile, which follows the link and returns the
+ * target's CONTENT), so the subsequent enable-by-name recreates it against
+ * the active copy. Idempotent: on a clean or already-reconciled destination
+ * every step is a no-op (the copy rewrites identical bytes).
+ *
+ * Returns what was done, for assertions and install reporting.
+ */
+export interface PlaceUnitResult {
+  readonly unit: string;
+  readonly destination: string;
+  /** A symlink at the unit-name path was unlinked (by-path residue). */
+  readonly unlinkedDestinationSymlink: boolean;
+  /** A stale wants-symlink pointing outside the active dir was removed. */
+  readonly removedStaleWantsSymlink: boolean;
+}
+
+/**
+ * placeUnitFile failed. Thrown BEFORE any copy: no destination bytes were
+ * written, so a residue target cannot have been clobbered by a copy-through
+ * (#1297 review F2).
+ */
+export class UnitPlacementError extends Error {
+  constructor(
+    readonly unit: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = UnitPlacementError.name;
+  }
+}
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error && typeof error.code === 'string';
+}
+
+export async function placeUnitFile(
+  source: string,
+  systemdUserDir: string,
+  unit: string,
+): Promise<PlaceUnitResult> {
+  const destination = join(systemdUserDir, unit);
+  let unlinkedDestinationSymlink = false;
+  // Destination-absent and unlink-FAILED are different outcomes and must not
+  // share a catch (#1297 review F2): a swallowed unlink error used to fall
+  // through to copyFile through the still-live symlink, silently reintroducing
+  // the exact copy-through this helper exists to prevent.
+  let destinationInfo: Stats | undefined;
+  try {
+    destinationInfo = await lstat(destination);
+  } catch (error) {
+    if (!isErrnoException(error) || error.code !== 'ENOENT') {
+      throw new UnitPlacementError(
+        unit,
+        `cannot inspect destination ${destination}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    // ENOENT: absent destination — nothing to unlink, copy below is safe.
+  }
+  if (destinationInfo?.isSymbolicLink()) {
+    try {
+      await unlink(destination);
+    } catch (error) {
+      // Abort BEFORE the copy: proceeding would run copyFile through the
+      // still-live symlink and overwrite the residue target's bytes.
+      throw new UnitPlacementError(
+        unit,
+        `cannot unlink destination symlink ${destination}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    unlinkedDestinationSymlink = true;
+  }
+  await copyFile(source, destination);
+
+  let removedStaleWantsSymlink = false;
+  const wantsLink = join(systemdUserDir, 'default.target.wants', unit);
+  try {
+    const wantsInfo = await lstat(wantsLink);
+    if (wantsInfo.isSymbolicLink()) {
+      // readlink — NOT readFile: readFile FOLLOWS the link and returns the
+      // target file's CONTENT, which is not the question being asked.
+      let target: string | undefined;
+      try {
+        target = await readlink(wantsLink);
+      } catch {
+        target = undefined;
+      }
+      // Normalize (systemctl writes absolute targets; a relative one resolves
+      // against the wants dir). A wants-symlink pointing anywhere other than
+      // the active copy (the by-path convention points at the seed template)
+      // survives enable-by-name unchanged — remove it so enable recreates it.
+      if (target !== undefined && resolve(dirname(wantsLink), target) !== destination) {
+        await unlink(wantsLink);
+        removedStaleWantsSymlink = true;
+      }
+    }
+  } catch {
+    // absent wants link — nothing to reconcile
+  }
+
+  return { unit, destination, unlinkedDestinationSymlink, removedStaleWantsSymlink };
+}
+
 /**
  * Returns the systemctl --user disable command for a given unit.
  * Used by `fleet remove` so a removed agent's enabled unit cannot resurrect on
@@ -833,6 +982,22 @@ export async function enableFleetUnits(
     let succeeded = 0;
     let failed = 0;
 
+    // The lease broker ships with the fleet and every gated runtime needs it
+    // (#1292): seats die at lease registration without it, and no documented
+    // path ever enabled it. Enabled first — alongside the holder — and the
+    // unit must have been placed by installFleet's placeUnitFile step.
+    const brokerResult = await runner(
+      ...splitCommand(buildSystemdEnableCommand('mosaic-lease-broker.service')),
+    );
+    if (brokerResult.exitCode === 0) {
+      succeeded++;
+    } else {
+      failed++;
+      process.stderr.write(
+        `Warning: could not enable mosaic-lease-broker.service: ${brokerResult.stderr || brokerResult.stdout || 'non-zero exit'}\n`,
+      );
+    }
+
     const holderResult = await runner(
       ...splitCommand(buildSystemdEnableCommand('mosaic-tmux-holder.service')),
     );
@@ -1529,7 +1694,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot);
+      await installFleet(cmd, frameworkRoot, runner);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1540,7 +1705,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .description('Install local fleet tools and user systemd units')
     .option('--no-enable', 'Skip enabling units for boot-survival')
     .action(async (opts: { enable?: boolean }) => {
-      await installFleet(cmd, frameworkRoot);
+      await installFleet(cmd, frameworkRoot, runner);
       // Unit enablement needs agent names only, so it reads either version.
       const roster = await loadRosterReadModel(cmd);
       await enableFleetUnits(runner, roster, opts);
@@ -1593,6 +1758,37 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
             );
             return;
           }
+          if (action === 'start') {
+            // Broker preflight (#1292), re-probed on EVERY invocation: a
+            // gated runtime started without a live lease broker dies ~4s in
+            // while the unit reports active (RemainAfterExit) — enabling +
+            // starting here and then RE-CHECKING the socket refuses loudly
+            // instead of reporting rc0 over a doomed start. This is the
+            // second-start check as much as the first: it never trusts unit
+            // ActiveState.
+            await runChecked(runner, [
+              'systemctl',
+              '--user',
+              'enable',
+              'mosaic-lease-broker.service',
+            ]);
+            await runChecked(runner, [
+              'systemctl',
+              '--user',
+              'start',
+              'mosaic-lease-broker.service',
+            ]);
+            if (!(await brokerSocketPresent(deps))) {
+              console.error(
+                '[fleet] broker-absent: lease broker socket did not appear after enable+start (#1292).',
+              );
+              console.error(
+                '[fleet] remedy: mosaic fleet install (it reconciles either enable convention)',
+              );
+              process.exitCode = 1;
+              return;
+            }
+          }
           if (action === 'restart') {
             // Serialize the holder+agents teardown/relaunch behind the restart lock
             // so a re-entrant restart waits for clean shutdown before relaunching,
@@ -2351,7 +2547,11 @@ export function registerFleetAgentCommands(
     });
 }
 
-async function installFleet(cmd: Command, frameworkRoot: string): Promise<void> {
+async function installFleet(
+  cmd: Command,
+  frameworkRoot: string,
+  runner: CommandRunner,
+): Promise<void> {
   const activePaths = resolveFleetPaths(cmd.opts<{ mosaicHome: string }>().mosaicHome);
   assertDefaultMosaicHomeForSystemd(activePaths.mosaicHome);
   // Read model first: every file this function places is roster-independent, and
@@ -2403,18 +2603,40 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>
   for (const toolPath of executableToolPaths) {
     await chmod(toolPath, 0o755);
   }
-  await copyFile(
+  // Unit placement (#1292): every unit goes through placeUnitFile — never a
-    join(frameworkRoot, 'systemd', 'user', 'mosaic-tmux-holder.service'),
+  // bare copyFile — so a by-path-enable symlink at the destination is
-    join(activePaths.systemdUserDir, 'mosaic-tmux-holder.service'),
+  // unlinked rather than written through (copy-through would silently
+  // overwrite the SEED template, measured 2026-08-17). The lease broker unit
+  // is placed here too: previously the install named three units and omitted
+  // the broker entirely, which is why no documented path ever enabled it.
+  const placedUnits = await Promise.all(
+    [
+      'mosaic-tmux-holder.service',
+      '[email protected]',
+      '[email protected]',
+      'mosaic-lease-broker.service',
+    ].map((unit) =>
+      placeUnitFile(join(frameworkRoot, 'systemd', 'user', unit), activePaths.systemdUserDir, unit),
+    ),
   );
-  await copyFile(
+  const reconciled = placedUnits.filter(
-    join(frameworkRoot, 'systemd', 'user', '[email protected]'),
+    (result) => result.unlinkedDestinationSymlink || result.removedStaleWantsSymlink,
-    join(activePaths.systemdUserDir, '[email protected]'),
-  );
-  await copyFile(
-    join(frameworkRoot, 'systemd', 'user', '[email protected]'),
-    join(activePaths.systemdUserDir, '[email protected]'),
   );
+  if (reconciled.length > 0) {
+    console.log(
+      `Reconciled ${reconciled.length} unit placement(s) from by-path enable residue: ${reconciled.map((r) => r.unit).join(', ')}`,
+    );
+  }
+  // systemd will not see a replaced unit file without a reload; do it once
+  // after all placements, before any enable call below. runCommand never
+  // rejects (it resolves exitCode 127 on spawn error), so a plain await with
+  // an exitCode check matches the rest of this file's systemctl handling.
+  const reloadResult = await runner(...splitCommand(['systemctl', '--user', 'daemon-reload']));
+  if (reloadResult.exitCode !== 0) {
+    process.stderr.write(
+      `Warning: systemctl --user daemon-reload after unit placement failed (non-systemd host?): ${reloadResult.stderr || reloadResult.stdout || 'non-zero exit'}\n`,
+    );
+  }
 
   // On roster v2 the reconciler owns the generated env: `apply` writes it and
   // `regen` rebuilds it, both from projectRosterV2AgentGeneratedEnv. Writing it
@@ -2611,6 +2833,45 @@ function splitCommand(command: string[]): [string, string[]] {
   return [bin, args];
 }
 
+/**
+ * Lease-broker socket presence for the fleet-start preflight (#1292).
+ * Resolution precedence matches launch.ts's defaultLeaseBrokerSocket and
+ * start-agent-session.sh's broker_socket_path: explicit
+ * MOSAIC_LEASE_BROKER_SOCKET, else $XDG_RUNTIME_DIR/mosaic-lease/broker.sock,
+ * else /run/user/<uid>/mosaic-lease/broker.sock. Pure filesystem check — this
+ * deliberately does NOT consult systemd state: a unit can be active
+ * (RemainAfterExit) with no live socket, and the socket is the thing the
+ * gated runtime connects to. Injectable via deps for tests.
+ */
+export function resolveLeaseBrokerSocketForPreflight(
+  env: NodeJS.ProcessEnv = process.env,
+  uid: number = typeof process.getuid === 'function' ? process.getuid() : 0,
+): string {
+  if (env['MOSAIC_LEASE_BROKER_SOCKET']) return env['MOSAIC_LEASE_BROKER_SOCKET'];
+  const runtimeDir = env['XDG_RUNTIME_DIR'] ?? `/run/user/${uid}`;
+  return join(runtimeDir, 'mosaic-lease', 'broker.sock');
+}
+
+export async function brokerSocketPresent(
+  deps: FleetCommandDeps,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<boolean> {
+  const check = deps.checkBrokerSocket;
+  const socketPath = resolveLeaseBrokerSocketForPreflight(env);
+  if (check) return check(socketPath);
+  // S_IFSOCK (0xC000) is a file-TYPE constant, not an access() mode (0-7):
+  // access(path, S_IFSOCK) throws ERR_OUT_OF_RANGE on node >= 24 (measured on
+  // v24.18.0, #1297 review F1) and cannot succeed on any node — the old catch
+  // swallowed the throw, so this probe could NEVER return true and every
+  // un-seamed call reported the broker absent. stat() + isSocket() is the real
+  // check and matches the bash side's [ -S ].
+  try {
+    return (await stat(socketPath)).isSocket();
+  } catch {
+    return false;
+  }
+}
+
 /** All supported fleet profile names. */
 export type FleetProfile =
   | 'general'

packages/mosaic/src/commands/lease-doctor-check.ts

@@ -205,6 +205,12 @@ export async function runLeaseEnforcementDoctorCheck(
     message:
       `Lease-enforcement hooks (${matchedMarkers.join(', ')}) are wired in ~/.claude/settings.json, but ${reasons.join(' and ')}. ` +
       'Every gated tool call will fail closed and BRICK this agent (see #869). ' +
-      'Remediate by activating the lease-broker supervisor (systemd unit + socket) or by removing the enforcement hooks from ~/.claude/settings.json.',
+      // #1292: one remedy, correct under BOTH enable conventions (by-path on
+      // the seed template, and copy-then-enable in the active dir). Written
+      // from the 2026-08-17 symlink measurement: `systemctl enable` by name
+      // does NOT rewrite an existing by-path wants-symlink, so teaching a
+      // manual systemctl line here could leave a host with two competing
+      // wants links. fleet install reconciles either shape.
+      'Remedy: run `mosaic fleet install` (it reconciles either enable convention), or remove the enforcement hooks from ~/.claude/settings.json.',
   };
 }

packages/mosaic/src/fleet/fleet-documentation.spec.ts

@@ -922,8 +922,8 @@ describe('fleet operator documentation', (): void => {
     );
     expect(
       surfaces.filter((surface): boolean => surface.category === 'InlineLiteral'),
-    ).toHaveLength(863);
+    ).toHaveLength(882);
-    expect(surfaces).toHaveLength(887);
+    expect(surfaces).toHaveLength(906);
 
     const rosterSource = await readFile(join(fleetDocs, 'examples', 'roster-v2.yaml'), 'utf8');
     const auxiliary: CodeSurface = {

packages/mosaic/src/fleet/fleet-reconciler.acceptance.spec.ts

@@ -169,6 +169,16 @@ function reconcileDeps(host: FakeLifecycleHost): FleetReconcileDeps {
     applyProjection: async () => undefined,
     readRoster: async () => host.roster,
     acquireMutationLock: async () => async () => undefined,
+    // Hermetic broker observation (#1297 F3): without this, the plan probes
+    // the REAL host filesystem, so the "stable JSON" fixtures answered true
+    // on any machine with a live lease broker and false elsewhere. Pointing
+    // both paths at fixtures that do not exist pins socketPresent:false and
+    // unitInstalled:false on every host, which is what these fixtures assert.
+    brokerSocketEnv: {
+      MOSAIC_LEASE_BROKER_SOCKET: '/nonexistent/mosaic-lease/broker.sock',
+      XDG_CONFIG_HOME: '/nonexistent/mosaic-config',
+      XDG_RUNTIME_DIR: '/nonexistent/run',
+    },
   };
 }
 
@@ -459,6 +469,7 @@ describe('FCM-M3-002 reconciler lifecycle acceptance', (): void => {
       plan: {
         generation: 7,
         holder: 'owned',
+        broker: { unitInstalled: false, socketPresent: false },
         agents: [
           {
             name: 'coder0',

packages/mosaic/src/fleet/fleet-reconciler.spec.ts

@@ -1,6 +1,7 @@
 import { chmod, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { createServer } from 'node:net';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
   acquirePrivateReconcileLock,
@@ -92,6 +93,179 @@ async function run(command: FleetReconcileCommand, overrides: Partial<FleetRecon
 }
 
 describe('fleet roster-owned reconciler', (): void => {
+  // ── #1292: broker as first-class plan member + broker-first start ordering ──
+
+  it('reports broker unit and socket state in the plan (socket is the signal, not unit state)', async (): Promise<void> => {
+    const result = await run('status', {
+      statPath: async () => true,
+      checkBrokerSocket: async () => true,
+    });
+    expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: true });
+  });
+
+  it('reports a dead broker as socketPresent=false even when the unit is installed (enabled-but-dead is the #1292 shape)', async (): Promise<void> => {
+    const result = await run('status', {
+      statPath: async () => true,
+      checkBrokerSocket: async () => false,
+    });
+    expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: false });
+  });
+
+  it('probes the REAL filesystem when no seam is injected — live socket and unit report healthy, absent paths report absent (#1297 F3)', async (): Promise<void> => {
+    const dir = await mkdtemp(join(tmpdir(), 'mosaic-broker-probe-'));
+    cleanup = dir;
+    const configHome = join(dir, 'config');
+    const unitDir = join(configHome, 'systemd', 'user');
+    await mkdir(unitDir, { recursive: true });
+    await writeFile(join(unitDir, 'mosaic-lease-broker.service'), '[Unit]\n');
+    const sockPath = join(dir, 'broker.sock');
+    const server = createServer();
+    await new Promise<void>((resolve) => {
+      server.listen(sockPath, resolve);
+    });
+    try {
+      const result = await run('status', {
+        brokerSocketEnv: {
+          MOSAIC_LEASE_BROKER_SOCKET: sockPath,
+          XDG_CONFIG_HOME: configHome,
+          XDG_RUNTIME_DIR: dir,
+        },
+      });
+      expect(result.plan.broker).toEqual({ unitInstalled: true, socketPresent: true });
+      // Absent paths through the SAME seam-less path answer false — this is
+      // the half the old default got right; healthy is the half it got wrong.
+      const absent = await run('status', {
+        brokerSocketEnv: {
+          MOSAIC_LEASE_BROKER_SOCKET: join(dir, 'gone.sock'),
+          XDG_CONFIG_HOME: join(dir, 'gone-config'),
+        },
+      });
+      expect(absent.plan.broker).toEqual({ unitInstalled: false, socketPresent: false });
+    } finally {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+    }
+  });
+
+  it('command start refuses with a named error when the broker socket does not appear after enable+start (#1297 F3)', async (): Promise<void> => {
+    const calls: string[][] = [];
+    await expect(
+      run('start', {
+        checkBrokerSocket: async () => false,
+        runner: async (command, args) => {
+          calls.push([command, ...args]);
+          if (command === 'tmux' && args.includes('list-sessions')) {
+            return { stdout: '_holder\ncoder0\n', stderr: '', exitCode: 0 };
+          }
+          if (command === 'tmux' && args.includes('show-environment')) {
+            return {
+              stdout:
+                'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+              stderr: '',
+              exitCode: 0,
+            };
+          }
+          return { stdout: '', stderr: '', exitCode: 0 };
+        },
+      }),
+    ).rejects.toThrow(/broker-absent/);
+    // Refused: broker enable+start attempted, no holder/agent unit touched.
+    const agentStarts = calls.filter(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(agentStarts).toHaveLength(0);
+  });
+
+  it('command start enables and starts the broker BEFORE the holder and any agent unit', async (): Promise<void> => {
+    const calls: string[][] = [];
+    const result = await run('start', {
+      // Deterministic broker presence: without the seam this test answers the
+      // HOST's broker state (passes on a machine with a live broker, refuses
+      // on CI), not the ordering property it exists for (#1297 follow-up).
+      checkBrokerSocket: async () => true,
+      runner: async (command, args) => {
+        calls.push([command, ...args]);
+        if (command === 'tmux' && args.includes('list-sessions')) {
+          return { stdout: '_holder\ncoder0\n', stderr: '', exitCode: 0 };
+        }
+        if (command === 'tmux' && args.includes('show-environment')) {
+          return {
+            stdout:
+              'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+            stderr: '',
+            exitCode: 0,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      },
+    });
+    expect(result.lifecycle).toBe('complete');
+    const brokerEnable = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user enable mosaic-lease-broker.service',
+    );
+    const brokerStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-lease-broker.service',
+    );
+    const holderStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-tmux-holder.service',
+    );
+    const agentStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(brokerEnable).toBeGreaterThanOrEqual(0);
+    expect(brokerStart).toBeGreaterThan(brokerEnable);
+    // Holder start may be absent (holder 'owned' in this fixture); if present it must follow the broker.
+    if (holderStart >= 0) expect(holderStart).toBeGreaterThan(brokerStart);
+    expect(agentStart).toBeGreaterThan(brokerStart);
+  });
+
+  it('apply with a running desired agent also enables and starts the broker first', async (): Promise<void> => {
+    const calls: string[][] = [];
+    const runningRoster: FleetRosterV2 = {
+      ...roster,
+      agents: roster.agents.map((agent) =>
+        agent.name === 'coder0'
+          ? { ...agent, lifecycle: { enabled: true, desiredState: 'running' as const } }
+          : agent,
+      ),
+    };
+    const result = await executeFleetReconcile({
+      roster: runningRoster,
+      command: 'apply',
+      expectedGeneration: 7,
+      deps: deps({
+        readRoster: async () => runningRoster,
+        // Deterministic broker presence (see start-ordering test note).
+        checkBrokerSocket: async () => true,
+        runner: async (command, args) => {
+          calls.push([command, ...args]);
+          if (command === 'tmux' && args.includes('list-sessions')) {
+            return { stdout: '_holder\n', stderr: '', exitCode: 0 };
+          }
+          if (command === 'tmux' && args.includes('show-environment')) {
+            return {
+              stdout:
+                'HOME=/home/mosaic\nMOSAIC_FLEET_OWNER=11111111-1111-4111-8111-111111111111\nMOSAIC_TMUX_HOLDER=_holder\nMOSAIC_TMUX_SOCKET=mosaic-fleet\nPATH=/usr/bin:/bin\nPWD=/home/mosaic\n',
+              stderr: '',
+              exitCode: 0,
+            };
+          }
+          return { stdout: '', stderr: '', exitCode: 0 };
+        },
+      }),
+    });
+    expect(result.applied).toBe(true);
+    const brokerStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start mosaic-lease-broker.service',
+    );
+    const agentStart = calls.findIndex(
+      (c) => c.join(' ') === 'systemctl --user start [email protected]',
+    );
+    expect(brokerStart).toBeGreaterThanOrEqual(0);
+    expect(agentStart).toBeGreaterThan(brokerStart);
+  });
+
   it('fails closed on a symlinked fleet ancestor without touching its target', async (): Promise<void> => {
     const home = await lockHome();
     const fleet = join(home, 'fleet');
@@ -375,6 +549,8 @@ describe('fleet roster-owned reconciler', (): void => {
       expectedGeneration: 7,
       deps: deps({
         readRoster: async () => runningRoster,
+        // Deterministic broker presence (see start-ordering test note).
+        checkBrokerSocket: async () => true,
         runner: async (command, args) => {
           calls.push([command, ...args]);
           if (command === 'tmux' && args.includes('list-sessions')) {

packages/mosaic/src/fleet/fleet-reconciler.ts

@@ -1,5 +1,5 @@
 import { constants } from 'node:fs';
-import { lstat, open, readFile, unlink, type FileHandle } from 'node:fs/promises';
+import { lstat, open, readFile, stat, unlink, type FileHandle } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -44,6 +44,10 @@ export interface FleetReconcileDeps {
   readonly overrideDir?: string;
   readonly homeDirectory?: string;
   readonly readHolderIdentity?: () => Promise<string>;
+  /** Test/observation seams for the lease-broker plan member (#1292). */
+  readonly statPath?: (path: string) => Promise<boolean> | boolean;
+  readonly checkBrokerSocket?: (path: string) => Promise<boolean> | boolean;
+  readonly brokerSocketEnv?: NodeJS.ProcessEnv;
   readonly validateRoster?: (roster: FleetRosterV2) => Promise<void>;
   readonly prepareProjections?: (roster: FleetRosterV2) => Promise<readonly unknown[]>;
   readonly applyProjection?: (prepared: unknown) => Promise<unknown>;
@@ -75,6 +79,17 @@ export interface FleetReconcileObservedAgent {
 export interface FleetReconcilePlan {
   readonly generation: number;
   readonly holder: 'owned' | 'missing' | 'ownership-mismatch';
+  /**
+   * Lease broker observation (#1292): every gated runtime registers with the
+   * broker or dies ~4s in — a broker not in the plan cannot be reported as
+   * drifted, which made "broker died an hour ago" and "broker fine"
+   * produce identical output. `unitInstalled` = unit file present in the
+   * active dir; `socketPresent` = live broker at the resolved socket path.
+   */
+  readonly broker: {
+    readonly unitInstalled: boolean;
+    readonly socketPresent: boolean;
+  };
   readonly agents: readonly FleetReconcileObservedAgent[];
   readonly unmanagedSessions: readonly string[];
 }
@@ -246,7 +261,17 @@ export async function executeFleetReconcile(
             lifecycle: 'complete',
             plan,
           };
-        } catch {
+        } catch (error: unknown) {
+          // A named lifecycle precondition (broker-absent after enable+start,
+          // #1297 F3) must surface as itself — converting it to the generic
+          // recoverable result would hide the diagnosis and report a clean
+          // refusal where a loud one is the point.
+          if (
+            error instanceof FleetReconcileError &&
+            error.code === 'lifecycle-precondition-failed'
+          ) {
+            throw error;
+          }
           result = {
             applied: false,
             authoritativeRoster: 'unchanged',
@@ -315,6 +340,63 @@ function isObservational(command: FleetReconcileCommand): boolean {
   return command === 'plan' || command === 'status' || command === 'verify' || command === 'doctor';
 }
 
+/**
+ * Observe the lease broker for the plan (#1292). Unit presence via systemctl
+ * is-system-running is NOT the signal — a unit can be enabled-but-dead. The
+ * authoritative signal is the socket the gated runtimes connect to, matching
+ * broker-supervisor.ts's `checkBrokerSupervisorHealth` (healthy ===
+ * socketPresent). Injectable so tests drive every branch without a broker.
+ */
+function resolveBrokerSocketPath(env: NodeJS.ProcessEnv): string {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+  const runtimeDir = env['XDG_RUNTIME_DIR'] ?? `/run/user/${uid}`;
+  return env['MOSAIC_LEASE_BROKER_SOCKET'] ?? join(runtimeDir, 'mosaic-lease', 'broker.sock');
+}
+
+/**
+ * Probe the broker socket. Seams take precedence, but with no seam injected
+ * the REAL stat().isSocket() runs (#1297 review F3): production passes no
+ * seams, and defaulting to false made plan/status/doctor report a healthy
+ * broker as absent — a dead broker was indistinguishable from noise.
+ */
+async function brokerSocketPresent(
+  deps: FleetReconcileDeps,
+  env: NodeJS.ProcessEnv,
+): Promise<boolean> {
+  const socketPath = resolveBrokerSocketPath(env);
+  const check = deps.checkBrokerSocket;
+  if (check) return check(socketPath);
+  try {
+    return (await stat(socketPath)).isSocket();
+  } catch {
+    return false;
+  }
+}
+
+async function observeBroker(deps: FleetReconcileDeps): Promise<FleetReconcilePlan['broker']> {
+  const homeDirectory = deps.homeDirectory ?? homedir();
+  const env = (deps.brokerSocketEnv ?? process.env) as NodeJS.ProcessEnv;
+  const configHome = env['XDG_CONFIG_HOME'] ?? join(homeDirectory, '.config');
+  const unitPath = join(configHome, 'systemd', 'user', 'mosaic-lease-broker.service');
+  const statPath = deps.statPath;
+  let unitInstalled = false;
+  let socketPresent = false;
+  try {
+    // Same principle as the socket probe: no seam → look at the real
+    // filesystem. A unit file placed by installFleet (or a by-path residue
+    // symlink resolving to it) satisfies stat().isFile().
+    unitInstalled = statPath ? await statPath(unitPath) : (await stat(unitPath)).isFile();
+  } catch {
+    unitInstalled = false;
+  }
+  try {
+    socketPresent = await brokerSocketPresent(deps, env);
+  } catch {
+    socketPresent = false;
+  }
+  return { unitInstalled, socketPresent };
+}
+
 async function observeFleet(
   roster: FleetRosterV2,
   deps: FleetReconcileDeps,
@@ -325,10 +407,12 @@ async function observeFleet(
     '-F',
     '#{session_name}',
   ]);
+  const broker = await observeBroker(deps);
   if (sessionsResult.exitCode !== 0) {
     return {
       generation: roster.generation,
       holder: 'missing',
+      broker,
       agents: await observeAgents(roster, deps, new Set<string>()),
       unmanagedSessions: [],
     };
@@ -351,6 +435,7 @@ async function observeFleet(
   return {
     generation: roster.generation,
     holder,
+    broker,
     agents: await observeAgents(roster, deps, sessions),
     unmanagedSessions: Object.freeze(unmanagedSessions.sort()),
   };
@@ -507,6 +592,17 @@ async function executeExplicitLifecycle(
   plan: FleetReconcilePlan,
   agents: readonly FleetRosterV2Agent[],
 ): Promise<FleetReconcileResult> {
+  const lifecycleApplyFailed = (): FleetReconcileResult => ({
+    applied: false,
+    authoritativeRoster: 'unchanged',
+    projections: 'not-applied',
+    lifecycle: 'incomplete',
+    plan,
+    recovery: {
+      code: 'lifecycle-apply-failed',
+      action: 'rerun-after-inspecting-owned-resources',
+    },
+  });
   if (request.command === 'start') {
     for (const agent of agents) {
       if (!agent.lifecycle.enabled) {
@@ -517,6 +613,40 @@ async function executeExplicitLifecycle(
       }
     }
   }
+  // Broker FIRST (#1292): a gated runtime started without a running lease
+  // broker dies ~4 seconds in at registration — enable the unit (install
+  // places it) and start it before any holder/agent lifecycle effect.
+  try {
+    if (request.command === 'start') {
+      await runChecked(request.deps, 'systemctl', [
+        '--user',
+        'enable',
+        'mosaic-lease-broker.service',
+      ]);
+      await runChecked(request.deps, 'systemctl', [
+        '--user',
+        'start',
+        'mosaic-lease-broker.service',
+      ]);
+    }
+  } catch {
+    return lifecycleApplyFailed();
+  }
+  if (request.command === 'start') {
+    // Socket re-check after start, as a NAMED precondition (#1297 review
+    // F3) — the same protection the v1 path in commands/fleet.ts has had all
+    // along: the unit reporting active is not the signal; the socket is.
+    // Deliberately outside the try/catch above: a swallowed FleetReconcileError
+    // here read as a generic recoverable failure, hiding the named refusal.
+    // Runs BEFORE any holder/agent unit is touched so nothing doomed starts.
+    const env = (request.deps.brokerSocketEnv ?? process.env) as NodeJS.ProcessEnv;
+    if (!(await brokerSocketPresent(request.deps, env))) {
+      throw new FleetReconcileError(
+        'lifecycle-precondition-failed',
+        'broker-absent: lease broker socket did not appear after enable+start (#1292; #1297 F3). Remedy: mosaic fleet install.',
+      );
+    }
+  }
   try {
     if (request.command === 'start' && plan.holder === 'missing') {
       await runChecked(request.deps, 'systemctl', [
@@ -533,17 +663,7 @@ async function executeExplicitLifecycle(
       ]);
     }
   } catch {
-    return {
+    return lifecycleApplyFailed();
-      applied: false,
-      authoritativeRoster: 'unchanged',
-      projections: 'not-applied',
-      lifecycle: 'incomplete',
-      plan,
-      recovery: {
-        code: 'lifecycle-apply-failed',
-        action: 'rerun-after-inspecting-owned-resources',
-      },
-    };
   }
   return {
     applied: true,
@@ -563,6 +683,22 @@ async function applyDesiredLifecycle(
     (agent: FleetRosterV2Agent): boolean =>
       agent.lifecycle.enabled && agent.lifecycle.desiredState === 'running',
   );
+  // Broker before any running agent, same ordering and reason as the
+  // command-driven path above (#1292).
+  if (needsRunningAgent) {
+    await runChecked(deps, 'systemctl', ['--user', 'enable', 'mosaic-lease-broker.service']);
+    await runChecked(deps, 'systemctl', ['--user', 'start', 'mosaic-lease-broker.service']);
+    // Same socket re-check as the explicit start path (#1297 F3): apply with
+    // running desired agents starts gated runtimes too, and a broker that
+    // starts but never binds dooms them the same way.
+    const env = (deps.brokerSocketEnv ?? process.env) as NodeJS.ProcessEnv;
+    if (!(await brokerSocketPresent(deps, env))) {
+      throw new FleetReconcileError(
+        'lifecycle-precondition-failed',
+        'broker-absent: lease broker socket did not appear after enable+start (#1292; #1297 F3). Remedy: mosaic fleet install.',
+      );
+    }
+  }
   if (needsRunningAgent && plan.holder === 'missing') {
     await runChecked(deps, 'systemctl', ['--user', 'start', 'mosaic-tmux-holder.service']);
   }

packages/mosaic/src/lease-broker/revoke_noop_unittest.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""D29 contracts: no lease is a no-op success; half-provisioned still fails closed."""
+
+from __future__ import annotations
+
+import importlib.util
+import unittest
+from pathlib import Path
+
+TOOLS = Path(__file__).parents[2] / "framework/tools/lease-broker"
+REVOKE_PATH = TOOLS / "revoke-lease.py"
+
+_spec = importlib.util.spec_from_file_location("revoke_lease", REVOKE_PATH)
+assert _spec and _spec.loader
+revoke_lease = importlib.util.module_from_spec(_spec)
+import sys as _sys
+
+_sys.path.insert(0, str(TOOLS))
+_spec.loader.exec_module(revoke_lease)
+
+ARGV = ["--runtime", "claude", "--reason", "pre-compact"]
+VALID_SESSION = "a" * 64
+
+
+def _explode(*_args, **_kwargs):
+    raise AssertionError("broker must not be contacted when no lease is held")
+
+
+class RevokeWithoutLease(unittest.TestCase):
+    def test_no_lease_variables_is_a_noop_success(self) -> None:
+        """The D29 case: bare-launched session, nothing to revoke, must not deny."""
+        self.assertEqual(
+            revoke_lease.main(ARGV, environ={}, request=_explode),
+            0,
+        )
+
+    def test_no_lease_does_not_contact_the_broker(self) -> None:
+        """A no-op must be vacuous: no socket, no generation bump, no transport."""
+        revoke_lease.main(ARGV, environ={"HOME": "/nonexistent"}, request=_explode)
+
+    def test_socket_without_session_still_fails_closed(self) -> None:
+        """Half-provisioned is misconfiguration, not absence. Fail-closed stands."""
+        self.assertEqual(
+            revoke_lease.main(
+                ARGV,
+                environ={"MOSAIC_LEASE_BROKER_SOCKET": "/tmp/nonexistent.sock"},
+                request=_explode,
+            ),
+            2,
+        )
+
+    def test_session_without_socket_still_fails_closed(self) -> None:
+        """The mirror case, so the guard cannot be satisfied by either half alone."""
+        self.assertEqual(
+            revoke_lease.main(
+                ARGV,
+                environ={"MOSAIC_LEASE_SESSION_ID": VALID_SESSION},
+                request=_explode,
+            ),
+            2,
+        )
+
+    def test_empty_string_counts_as_absent(self) -> None:
+        """An exported-but-empty variable is not a lease."""
+        self.assertEqual(
+            revoke_lease.main(
+                ARGV,
+                environ={
+                    "MOSAIC_LEASE_BROKER_SOCKET": "",
+                    "MOSAIC_LEASE_SESSION_ID": "",
+                },
+                request=_explode,
+            ),
+            0,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/mosaic/src/mutator-gate/runtime_tools_unittest.py

@@ -337,7 +337,13 @@ class ExecutableEntrypointTest(unittest.TestCase):
             runpy.run_path(str(TOOLS_DIR / "launch-runtime.py"), run_name="__main__")
         self.assertEqual(raised.exception.code, 64)
 
-    def test_revoker_entrypoint_denies_when_identity_environment_is_absent(self) -> None:
+    def test_revoker_entrypoint_noops_when_identity_environment_is_absent(self) -> None:
+        # D29 supersession. This assertion previously pinned rc=2. Absent identity
+        # means no lease was ever held, so there is nothing to revoke and the correct
+        # result is no-op success. The old pin was written in e4d7d45 (WI-3), the same
+        # commit that shipped launch-runtime.py's lease-var provisioning, on the
+        # assumption that an envless revoker was unreachable. D29 falsified that in
+        # production. Behavioural pins live in src/lease-broker/revoke_noop_unittest.py.
         with patch.object(
             sys,
             "argv",
@@ -352,9 +358,42 @@ class ExecutableEntrypointTest(unittest.TestCase):
             io.StringIO()
         ), self.assertRaises(SystemExit) as raised:
             runpy.run_path(str(TOOLS_DIR / "revoke-lease.py"), run_name="__main__")
-        self.assertEqual(raised.exception.code, 2)
+        self.assertEqual(raised.exception.code, 0)
+
+    def test_revoker_entrypoint_denies_when_identity_environment_is_half_provisioned(
+        self,
+    ) -> None:
+        # The no-op above is reachable ONLY when identity is TOTALLY absent. A
+        # half-provisioned environment is a machinery-present failure and must still
+        # fail closed. main() already pins this; the entrypoint did not, and the
+        # entrypoint is what the runtime extension actually spawns.
+        half_provisioned = (
+            {"MOSAIC_LEASE_BROKER_SOCKET": "/run/test/broker.sock"},
+            {"MOSAIC_LEASE_SESSION_ID": "d" * 64},
+        )
+        for environment in half_provisioned:
+            with self.subTest(environment=environment), patch.object(
+                sys,
+                "argv",
+                [
+                    str(TOOLS_DIR / "revoke-lease.py"),
+                    "--runtime",
+                    "claude",
+                    "--reason",
+                    "pre-compact",
+                ],
+            ), patch.dict(os.environ, environment, clear=True), redirect_stderr(
+                io.StringIO()
+            ), self.assertRaises(SystemExit) as raised:
+                runpy.run_path(str(TOOLS_DIR / "revoke-lease.py"), run_name="__main__")
+            self.assertEqual(raised.exception.code, 2)
 
     def test_gate_entrypoint_denies_when_identity_environment_is_absent(self) -> None:
+        # Deliberately NOT changed alongside its revoker twin above. The asymmetry is
+        # intentional: the gate's deny-on-absent is the authorization path and is
+        # load-bearing, so absent identity must fail closed here. The revoker's rc=2
+        # was inert in the same case (no session id means no broker call is possible),
+        # which is why only the revoker moved under D29. Do not "restore symmetry".
         class Stdin:
             buffer = io.BytesIO(b'{"tool_name":"Bash"}')
 
@@ -703,8 +742,11 @@ class LeaseRevocationTest(unittest.TestCase):
             "MOSAIC_RUNTIME_GENERATION": "1",
         }
         malformed_session = {**good, "MOSAIC_LEASE_SESSION_ID": "not-a-session"}
+        # D29 exemption: the `({}, ...)` case was removed from this list. An empty
+        # environment is absence-of-lease, not an identity/reply/transport failure, and
+        # its correct result is no-op success (pinned in revoke_noop_unittest.py). The
+        # five cases below are all machinery-present failures and stay fail-closed.
         cases = [
-            ({}, lambda *_args: {"ok": True, "state": "UNVERIFIED"}),
             (malformed_session, lambda *_args: {"ok": True, "state": "UNVERIFIED"}),
             (good, lambda *_args: {"ok": False, "state": "UNVERIFIED"}),
             (good, lambda *_args: {"ok": True, "state": "VERIFIED"}),

packages/mosaic/src/stages/finalize-path.spec.ts

@@ -0,0 +1,152 @@
+/**
+ * setupPath profile management (issue #1327, MOSAIC-IMPROVEMENTS 4c / D25).
+ *
+ * The profile append used to be guarded on the binDir value it was about to
+ * write, which is blind to accumulation across different Mosaic homes: every
+ * wizard run against a fresh temp home appended a permanent block to the
+ * operator's real shell profile (1,061 measured appends on sb-it-1-dt).
+ *
+ * Arms below map to the requirements:
+ *   S1 sentinel-managed block, rewritten in place
+ *   S2 a non-default target home never touches the operator profile
+ *   S3 byte-identical profile across repeated runs
+ *   S4 legacy unmarked `# Mosaic` blocks collapse into the managed block
+ *   S5 the Windows ($env:Path) arm shares the same block logic
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir, homedir } from 'node:os';
+
+let profilePathMock: string | null = null;
+
+vi.mock('../platform/detect.js', () => ({
+  getShellProfilePath: (): string | null => profilePathMock,
+}));
+
+import { setupPath, managedBlockFor, stripLegacyPathBlocks } from './finalize.js';
+
+// The real resolved default on this host. Tests use it as the comparator a
+// non-default home must fail against, exactly as the wizard would.
+const REAL_DEFAULT_HOME = join(homedir(), '.config', 'mosaic');
+
+function tempHome(prefix: string): string {
+  const dir = join(tmpdir(), prefix);
+  mkdirSync(join(dir, 'bin'), { recursive: true });
+  return dir;
+}
+
+describe('setupPath profile management (#1327)', () => {
+  let workDir: string;
+  let profileFile: string;
+  let defaultLikeHome: string;
+  let otherHome: string;
+  const baseline = '# existing operator content\nexport EDITOR=vim\n';
+
+  beforeEach(() => {
+    workDir = mkdtempSync(join(tmpdir(), 'setuppath-spec-'));
+    profileFile = join(workDir, '.bashrc');
+    writeFileSync(profileFile, baseline, 'utf-8');
+    profilePathMock = profileFile;
+    defaultLikeHome = tempHome(join(workDir, 'home-a', '.config', 'mosaic'));
+    otherHome = tempHome(join(workDir, 'home-b', '.config', 'mosaic'));
+  });
+
+  afterEach(() => {
+    profilePathMock = null;
+    rmSync(workDir, { recursive: true, force: true });
+  });
+
+  // S2 — the arm that MUST fail against the pre-fix code: a home that is not
+  // the resolved default may not modify the operator profile at all.
+  it('does not touch the operator profile when the target home is not the resolved default', () => {
+    const action = setupPath(otherHome, REAL_DEFAULT_HOME);
+    expect(action).toBe('skipped');
+    expect(readFileSync(profileFile, 'utf-8')).toBe(baseline);
+  });
+
+  it('returns skipped when no shell profile can be resolved', () => {
+    profilePathMock = null;
+    const action = setupPath(defaultLikeHome, defaultLikeHome);
+    expect(action).toBe('skipped');
+  });
+
+  // S1 + S3 — two distinct homes (each run as the resolved default in turn,
+  // the shape of two legitimate installs against one operator profile) and
+  // repeated runs against the same home both leave exactly one block.
+  it('leaves exactly one managed block after runs against two distinct homes', () => {
+    const first = setupPath(defaultLikeHome, defaultLikeHome);
+    expect(first).toBe('added');
+
+    const second = setupPath(otherHome, otherHome);
+    expect(second).toBe('added');
+
+    const content = readFileSync(profileFile, 'utf-8');
+    const beginCount = content.split('# >>> mosaic begin >>>').length - 1;
+    const endCount = content.split('# <<< mosaic end <<<').length - 1;
+    expect(beginCount).toBe(1);
+    expect(endCount).toBe(1);
+    expect(content).toContain(join(otherHome, 'bin'));
+    expect(content).toContain(baseline);
+  });
+
+  it('is byte-identical across repeated runs against the same home', () => {
+    setupPath(defaultLikeHome, defaultLikeHome);
+    const afterFirst = readFileSync(profileFile, 'utf-8');
+
+    const again = setupPath(defaultLikeHome, defaultLikeHome);
+    expect(again).toBe('already');
+    expect(readFileSync(profileFile, 'utf-8')).toBe(afterFirst);
+  });
+
+  // S4 — pre-existing unmarked blocks from the old append logic collapse
+  // into the single managed block instead of accumulating beside it.
+  it('collapses legacy unmarked # Mosaic blocks into the managed block', () => {
+    const legacy =
+      '# existing operator content\n' +
+      '# Mosaic\n' +
+      'export PATH="/tmp/mosaic-dead-wizard-1/bin:$PATH"\n' +
+      'export EDITOR=vim\n' +
+      '# Mosaic\n' +
+      'export PATH="/tmp/mosaic-dead-wizard-2/bin:$PATH"\n';
+    writeFileSync(profileFile, legacy, 'utf-8');
+
+    const action = setupPath(defaultLikeHome, defaultLikeHome);
+    expect(action).toBe('added');
+
+    const content = readFileSync(profileFile, 'utf-8');
+    expect(content).not.toContain('/tmp/mosaic-dead-wizard-1/bin');
+    expect(content).not.toContain('/tmp/mosaic-dead-wizard-2/bin');
+    expect(content).toContain('export EDITOR=vim');
+    expect(content.split('# >>> mosaic begin >>>').length - 1).toBe(1);
+    expect(content).toContain(join(defaultLikeHome, 'bin'));
+  });
+});
+
+describe('managed block helpers (#1327)', () => {
+  // S5 — the Windows arm shares markers and shape with the POSIX arm.
+  it('builds the $env:Path variant inside the same markers', () => {
+    const block = managedBlockFor('C:\\Users\\op\\.config\\mosaic\\bin', true);
+    expect(block).toContain('# >>> mosaic begin >>>');
+    expect(block).toContain('# <<< mosaic end <<<');
+    expect(block).toContain('$env:Path = "C:\\Users\\op\\.config\\mosaic\\bin;$env:Path"');
+  });
+
+  it('builds the POSIX export variant inside the same markers', () => {
+    const block = managedBlockFor('/home/op/.config/mosaic/bin', false);
+    expect(block).toContain('# >>> mosaic begin >>>');
+    expect(block).toContain('export PATH="/home/op/.config/mosaic/bin:$PATH"');
+    expect(block).toContain('# <<< mosaic end <<<');
+  });
+
+  it('strips legacy $env:Path pairs on the Windows arm', () => {
+    const legacy =
+      '# Mosaic\n$env:Path = "C:\\tmp\\dead\\bin;$env:Path"\n' +
+      '# Mosaic\n$env:Path = "C:\\tmp\\dead2\\bin;$env:Path"\n' +
+      'Write-Host hi\n';
+    const stripped = stripLegacyPathBlocks(legacy, true);
+    expect(stripped).not.toContain('C:\\tmp\\dead');
+    expect(stripped).toContain('Write-Host hi');
+  });
+});

packages/mosaic/src/stages/finalize.ts

@@ -1,11 +1,12 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { platform } from 'node:os';
 import type { WizardPrompter } from '../prompter/interface.js';
 import type { ConfigService } from '../config/config-service.js';
 import type { WizardState } from '../types.js';
 import { getShellProfilePath } from '../platform/detect.js';
+import { DEFAULT_MOSAIC_HOME } from '../constants.js';
 import { ManifestError } from '../framework/manifest.js';
 import {
   getDefaultSkillPaths,
@@ -144,32 +145,87 @@ function runDoctor(mosaicHome: string): DoctorResult {
 
 type PathAction = 'already' | 'added' | 'skipped';
 
-function setupPath(mosaicHome: string, _p: WizardPrompter): PathAction {
+const PATH_BLOCK_BEGIN = '# >>> mosaic begin >>>';
-  const binDir = join(mosaicHome, 'bin');
+const PATH_BLOCK_END = '# <<< mosaic end <<<';
-  const currentPath = process.env['PATH'] ?? '';
+const PATH_BLOCK_NOTE = '# Managed by the Mosaic installer; this block is rewritten on install.';
 
-  if (currentPath.includes(binDir)) {
+/**
-    return 'already';
+ * The managed PATH block written into the operator's shell profile.
+ *
+ * The block is delimited by begin/end sentinels so any number of installs,
+ * against any homes, collapse to exactly one block: the writer replaces the
+ * region between the sentinels instead of appending a second copy (#1327).
+ */
+export function managedBlockFor(binDir: string, isWindows: boolean): string {
+  const exportLine = isWindows
+    ? `$env:Path = "${binDir};$env:Path"`
+    : `export PATH="${binDir}:$PATH"`;
+  return `${PATH_BLOCK_BEGIN}\n${PATH_BLOCK_NOTE}\n${exportLine}\n${PATH_BLOCK_END}\n`;
+}
+
+/**
+ * Remove legacy unmarked `# Mosaic` PATH pairs appended by pre-#1327
+ * installs. Only the exact two-line shape this installer used to write is
+ * removed; any other `# Mosaic` comment line is left alone.
+ */
+export function stripLegacyPathBlocks(content: string, isWindows: boolean): string {
+  const legacyExport = isWindows ? /^\$env:Path = ".*;\$env:Path"$/ : /^export PATH=".*:\$PATH"$/;
+  const lines = content.split('\n');
+  const kept: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? '';
+    const next = i + 1 < lines.length ? lines[i + 1] : undefined;
+    if (line === '# Mosaic' && next !== undefined && legacyExport.test(next)) {
+      i += 1;
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+/** Drop the region between the managed-block sentinels, first occurrence. */
+function withoutManagedBlock(content: string): string {
+  const beginIdx = content.indexOf(PATH_BLOCK_BEGIN);
+  if (beginIdx < 0) return content;
+  const endIdx = content.indexOf(PATH_BLOCK_END, beginIdx);
+  if (endIdx < 0) return content;
+  return content.slice(0, beginIdx) + content.slice(endIdx + PATH_BLOCK_END.length);
+}
+
+export function setupPath(mosaicHome: string, resolvedDefaultHome: string): PathAction {
+  // Never write outside the home under test (#1327 S2): a wizard run against
+  // a non-default home (test harnesses, throwaway installs) must not mutate
+  // the operator's real shell profile.
+  if (mosaicHome !== resolvedDefaultHome) {
+    return 'skipped';
   }
 
+  const binDir = join(mosaicHome, 'bin');
   const profilePath = getShellProfilePath();
   if (!profilePath) return 'skipped';
 
   const isWindows = platform() === 'win32';
-  const exportLine = isWindows
+  const block = managedBlockFor(binDir, isWindows);
-    ? `\n# Mosaic\n$env:Path = "${binDir};$env:Path"\n`
-    : `\n# Mosaic\nexport PATH="${binDir}:$PATH"\n`;
 
-  // Check if already in profile
+  let content = '';
   if (existsSync(profilePath)) {
-    const content = readFileSync(profilePath, 'utf-8');
+    content = readFileSync(profilePath, 'utf-8');
-    if (content.includes(binDir)) {
+  }
-      return 'already';
+
-    }
+  // Migration (#1327 S4): legacy unmarked blocks collapse into the managed
+  // block, and an existing managed block is rewritten in place rather than
+  // appended beside itself (S1/S3).
+  const base = stripLegacyPathBlocks(withoutManagedBlock(content), isWindows);
+  const trimmed = base.replace(/\n+$/, '');
+  const next = trimmed.length === 0 ? block : `${trimmed}\n${block}`;
+
+  if (next === content) {
+    return 'already';
   }
 
   try {
-    appendFileSync(profilePath, exportLine, 'utf-8');
+    writeFileSync(profilePath, next, 'utf-8');
     return 'added';
   } catch {
     return 'skipped';
@@ -286,7 +342,7 @@ export async function finalizeStage(
   }
 
   // 7. PATH setup
-  const pathAction = setupPath(state.mosaicHome, p);
+  const pathAction = setupPath(state.mosaicHome, DEFAULT_MOSAIC_HOME);
 
   let summaryShown = false;
   const showSummary = () => {

scratchpads/2026-08-17-fleet-identity-comms-mosaic-tree.md

@@ -0,0 +1,73 @@
+# 2026-08-17 — Fleet identity, comms delivery, and the ~/.mosaic tree (continuation record)
+
+> **Status:** active continuation record | **Owner:** Jason (rulings) / fleet (delivery) | **Created:** 2026-08-17, sb-it-1-dt session with Jarvis (jarvis-brain)
+> **Audience:** the homelab agents continuing this effort tonight. Read this whole file before acting; it supersedes nothing but preserves structure and decisions that must not be lost.
+
+---
+
+## Why this exists
+
+A session on sb-it-1-dt (2026-08-17) produced three architecture decisions (two awaiting Jason's ruling), one incident postmortem (#1295), interim guardrail edits in the user-owned `~/.mosaic/` contract tree, and one new tool (`ensure-watcher.sh`). The work spans jarvis-brain (P0, not retained) and this repo (the product). **This file is the stack-side anchor so continuation does not depend on jarvis-brain surviving.**
+
+## 1. The `~/.mosaic` tree model — as-built, preserve this structure
+
+Three-tree split (this is design intent, not accident; keep it through all framework work):
+
+| Tree                | Owner     | Rule                                                                                                          |
+| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| `~/.config/mosaic/` | framework | upgrade-managed templates; NEVER user-edited; `mosaic upgrade` may overwrite                                  |
+| `~/.mosaic/`        | user      | working contracts, guides, fleet agents; upgrades reconcile with **deny-wins** (user edits never overwritten) |
+| repo satellites     | repos     | bootstrapped per-repo `.mosaic/` state                                                                        |
+
+As-built inventory of `~/.mosaic` on sb-it-1-dt (2026-08-17):
+
+- **Contract core:** `CONSTITUTION.md` (L0 law), `AGENTS.md` (dispatcher + guide router + Fleet Comms Watcher requirement), `SOUL.md` (generic base for ALL fleet agents, zero persona — includes the new **Fleet Boundaries** section), `STANDARDS.md` (universal standards — includes new **session identity** + **comms watcher hygiene** sections), `SYSTEM.md` (pure communication contract, byte-identical to jarvis-brain's prompt-testing `sr_opus_5_system_prompt.md`), `USER.md`, `TOOLS.md`.
+- **`guides/`** — user-owned working copies (E2E-DELIVERY, ORCHESTRATOR(+PROTOCOL,+LEARNINGS), WAKE-DOCTRINE, VAULT-SECRETS, etc.).
+- **`fleet/agents/`** — the per-agent store (this is MOSAIC-D-002's substrate, already in use):
+  - real agent dirs: `fargo/`, `orchestrator/`, `probe/`, `vision/`, `weekly-update/` — shape: `profile.json` (harness/account/overlay pointer) + `overlay.json` + `SOUL.md` (persona) + `scratch/` `work/` `notes/` subdirs (hygiene rules in root SOUL.md)
+  - `*.env.generated` launch overlays: `luna` `sol` `terra` (carry `MOSAIC_AGENT_NAME`, `_CLASS`, `_RUNTIME`, `_MODEL`, `_REASONING`, `_TOOL_POLICY`) — these are the mosaic-fleet seat launch envs; `inbox.env`, `itops.env` also present
+  - `probe/` is the validated layout proof: auth-bundle symlink chain, per-agent sessions, plugin-store symlink (from 2026-08-07)
+- **`auth/`, `config/`, `memory/`, `plugins/`, `skills/`, `skills-local/`** — per-tree copies/links for runtime isolation.
+- Related but outside the tree: watcher units at `~/.config/systemd/user/<agent>-comms-watcher.service`; watcher seen-state at `~/.local/state/comms-watcher-<agent>/`.
+
+## 2. Decisions register (2026-08-17 session)
+
+Full strict records live in jarvis-brain `docs/decisions/mosaic-stack/` (render on its dashboard); both are **Pending Jason's ruling**. Summaries so the content survives P0:
+
+- **MOSAIC-D-001 — SYSTEM.md as canonical harness system prompt.** Static core (Constitution+AGENTS+USER+overlays) in one tracked file; launcher renders dynamic tail (mission/PRD/fleet/persona). Delivery: `--append-system-prompt` (repeatable) for pi/claude; symlinked core file for codex (`$CODEX_HOME/instructions.md`) and opencode (`AGENTS.md`); their dynamic tail via initial prompt (needs live verification). Static-first order is the cache win. `SYSTEM.md` in `~/.mosaic` today is the communication-contract file — D-001's SYSTEM.md is the broader composition; naming to reconcile at implementation.
+- **MOSAIC-D-002 — per-agent harness homes + mechanical profiles.** Launch with targeted config-dir env vars (e.g. `PI_CODING_AGENT_DIR=~/.mosaic/fleet/agents/<name>/pi`), NOT literal HOME. SOUL.md identity mechanically generated from roster (single writer; kills the hand-copy drift measured in `agents/vision/SOUL.md` on jarvis-brain: declared Jarvis, answered Vision). Composes: SYSTEM core → per-agent SOUL → dynamic tail. `MOSAIC_AGENT_NAME` stays load-bearing for comms.
+- **Comms delivery tooling belongs in the STACK framework, not jarvis-brain** (decided in discussion; supersedes the interim placement). jarvis-brain keeps only the transport _data_ (`comms/` tree) while it lives. Agents launch from their own repos (terra from `~/src/stack` etc.) — delivery is transport-repo-relative, so this works; but every installed watcher unit's ExecStart currently points into `~/src/jarvis-brain/scripts/` — that dependency is the P0 trap to remove. Migration = move tools + regenerate units, in one step.
+- **Watcher provisioning is instantiation duty, never running-agent duty.** Interim landed as jarvis-brain `scripts/comms/ensure-watcher.sh` (idempotent ensure + `--status` boot check + interim identity warnings: missing target session, pane `MOSAIC_AGENT_NAME` mismatch via `/proc/<child>/environ`, bare-runtime NOTE). Framework move: fold into `mosaic agent --new` + fleet launch + `mosaic doctor` drift check.
+- **Prose guardrails landed (interim fences until mechanical fixes):** `~/.mosaic/SOUL.md` Fleet Boundaries (wrong-session tripwire; comms ownership; cross-agent investigation requires tasking) · `STANDARDS.md` session identity + watcher hygiene · `AGENTS.md` Fleet Comms Watcher requirement (P0-interim script path marked transitional).
+
+## 3. Incident → #1295 (already tracked here)
+
+`https://git.mosaicstack.dev/mosaicstack/stack/issues/1295` — docs-seat incident: cwd-keyed session files served three lives (dev chat → goals seat → 22 watcher injections into a wedged process); name-based watcher delivery with no identity verification; wedge after pi 0.84.1→0.84.2 update passes every liveness instrument. Proposed fixes enumerated there; provisioning follow-up in comment ID 23027.
+
+## 4. Open work queue (suggested sequence)
+
+1. **Comms tooling migration PR** (lane `next`): move `comms-watcher.sh`, `install-watcher.sh`, `ensure-watcher.sh` into the framework tree → deploy `~/.config/mosaic/tools/comms/`; regenerate existing units' ExecStart to framework paths (one-command sweep); keep `COMMS_WATCH_REPO` per-host config (points at a brain checkout until the queue transport lands). Reference: jarvis-brain commit `701c353b1`.
+2. **Ensure-on-instantiation**: `mosaic agent --new` / fleet launch call ensure semantics; `mosaic doctor` gains the drift check (`--status --all` semantics + `fred`'s hand-written unit as the known drift case; also note daphne/docs/happy/pepper/sanity/tiny/fargo currently have no watcher — cover or consciously exempt).
+3. **MOSAIC-D-002 implementation** (after ruling): per-agent homes via targeted env vars; roster-generated SOUL.md single-writer; extend the existing `*.env.generated` pattern; launch ledger keeps `config_home` audit.
+4. **MOSAIC-D-001 implementation** (after ruling): SYSTEM.md sourcing + per-harness delivery + `compose-contract` becomes render-core+tail with drift check; bench cache-ordering before/after (jarvis-brain `domains/software-dev/mosaic-stack/prompt-testing` has the bench).
+5. **Queue transport + forced separation** (longer term): supersedes watcher path; identity-verification and wedge-detection remain valid regardless of transport.
+6. **Docs inheritance**: jarvis-brain AGENTS.md's durable comms guidance (E7 pi-glyph delivery gotchas, capture-pane rules, comms protocol) must be inherited into stack docs before P0 retirement.
+
+## 5. Rules for tonight's agents
+
+- Lane: **`next`** only; nothing to `main` without Jason (standing ruling).
+- Attribution caveat #1280: Gitea/git identity from this host may misattribute (issue #1295 showed as created by `@mos-dt-0`); prefer per-invocation `git -c user.name=<seat>` and verify what the remote recorded.
+- Do not delete `sb-it-1-dt:docs]` (untracked file at repo root) — it is cited fleet-wide as incident evidence.
+- Edit user contracts in `~/.mosaic/`, never the templates in `~/.config/mosaic/`.
+- Do not restart other fleet seats unilaterally (goals/scrappy/sanity restart decisions are fred's/Jason's per the docs-seat report).
+
+## 6. Artifact map
+
+| Artifact                                                           | Where                                                                                                                    |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| Decision records D-001/D-002 (strict, pending ruling)              | jarvis-brain `docs/decisions/mosaic-stack/2026-08-17_mosaic-d-00{1,2}_*.md`                                              |
+| Incident issue + provisioning comment                              | stack #1295 + comment 23027                                                                                              |
+| ensure-watcher.sh (reference implementation)                       | jarvis-brain `scripts/comms/ensure-watcher.sh` (commit `701c353b1`)                                                      |
+| Bench for prompt A/B (pi, thinking levels, footer-token semantics) | jarvis-brain `domains/software-dev/mosaic-stack/prompt-testing/` + `docs/reports/2026-08-17-prompt-testing-glm-bench.md` |
+| Launcher inspection basis                                          | `@mosaicstack/mosaic` 0.0.49 `dist/commands/launch.js` (composeContract / ensureRuntimeConfig / harness-home isolation)  |
+| Guardrail edits                                                    | `~/.mosaic/{SOUL,AGENTS,STANDARDS}.md` on sb-it-1-dt (2026-08-17 16:53–17:04)                                            |