docs(l0): parameterize hard gates on the project's integration trunk (#1216, Option A) (#1217)

Co-authored-by: Ghost <>

.mosaic/repo.json

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

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);
-      if (override) {
-        effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
-        await this.systemOverride.renew(sessionId, scope);
-        this.logger.debug(`Applied system override for session ${sessionId}`);
-      }
+    const override = await this.systemOverride.get(sessionId, scope);
+    if (override) {
+      effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
+      await this.systemOverride.renew(sessionId, scope);
+      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/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/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.
-2. Require pull requests to merge into `main`.
+1. Protect the integration trunk from direct pushes.
+2. Require pull requests to merge into the integration trunk.
 3. Require required CI/status checks to pass before merge.
 4. Require code review approval before merge.
-5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
+5. Allow **squash merge only** for PRs into the integration trunk (disable merge commits and rebase merges for it).
 
 This enforces one merge strategy across human and agent workflows.
 
@@ -513,9 +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
-- [ ] PRs into `main` are required
-- [ ] Merge method for `main` is squash-only
+- [ ] The integration trunk is protected from direct pushes
+- [ ] PRs into the integration trunk are required
+- [ ] Merge method for the integration trunk is squash-only
 - [ ] Quality gates run successfully
 - [ ] `.env.example` exists (if project uses env vars)
 - [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)

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`.
-- Direct pushes to `main` are prohibited.
-- Merge to `main` MUST be squash-only.
+- The integration trunk is the branch the project's `.mosaic/repo.json` declares under `integration_trunk` (default: `main`) — see `CONSTITUTION.md` Hard Gates.
+- PR target for delivery is the integration trunk.
+- Direct pushes to the integration trunk are prohibited.
+- Merge to the integration trunk MUST be squash-only.
 - Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).
 
 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
-git diff main...HEAD
+# View the changes (diff against the integration trunk; default: main)
+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`.
-- Worker task branches merge back via PR to `main` only.
-- Direct pushes to `main` are prohibited.
-- PR merges to `main` MUST use squash merge.
+- Workers use short-lived task branches from `origin/{integration_trunk}` (default `main`).
+- Worker task branches merge back via PR to the integration trunk only.
+- Direct pushes to the integration trunk are prohibited.
+- PR merges to the integration trunk MUST use squash merge.
 
 **Available templates:**
 
@@ -427,7 +427,7 @@ git push
     - Before merging, run queue guard:
       `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
     - Ensure PR exists for the task branch (create/update via wrappers if needed):
-      `~/.config/mosaic/tools/git/pr-create.sh ... -B main`
+      `~/.config/mosaic/tools/git/pr-create.sh ... -B {integration_trunk}` (default `main`)
     - Merge via wrapper:
       `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
     - Wait for terminal CI status:
@@ -619,7 +619,7 @@ Construct this from the task row and pass to worker via Task tool:
 
 ## Workflow
 
-1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
+1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/{integration_trunk}) && git rebase origin/{integration_trunk}` ({integration_trunk} = the project's declared trunk, default `main`)
 2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
 3. Read the finding details from the report
 4. Implement the fix following existing code patterns
@@ -637,7 +637,7 @@ Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIR
 For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
 
 - `~/.config/mosaic/tools/git/issue-view.sh -i {N}`
-- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B main`
+- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B {integration_trunk}`
 - Push: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {task_branch}`
 - Merge: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B {pr_head_branch} -R {pr_head_owner/repo} --sha {pr_head_full_sha}`
 - `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
@@ -994,13 +994,13 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
 
 ---
 
-## Merge-to-Main Candidate Protocol (Container Deployments)
+## Merge-to-Trunk Candidate Protocol (Container Deployments)
 
-If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:
+If deployment is in scope and container images are used, every merge to the integration trunk MUST execute this protocol:
 
 1. Build and push immutable candidate image tags:
    - `sha-<shortsha>` (always)
-   - `v{base-version}-rc.{build}` (for `main` merges)
+   - `v{base-version}-rc.{build}` (for integration-trunk merges)
    - `testing` mutable pointer to the same digest
 2. Resolve and record the image digest for each service.
 3. Deploy by digest to testing environment (never deploy by mutable tag alone).

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

@@ -292,6 +292,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-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/src/stages/finalize-path.spec.ts

@@ -1,152 +0,0 @@
-/**
- * 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,12 +1,11 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, appendFileSync } 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,
@@ -145,87 +144,32 @@ function runDoctor(mosaicHome: string): DoctorResult {
 
 type PathAction = 'already' | 'added' | 'skipped';
 
-const PATH_BLOCK_BEGIN = '# >>> mosaic begin >>>';
-const PATH_BLOCK_END = '# <<< mosaic end <<<';
-const PATH_BLOCK_NOTE = '# Managed by the Mosaic installer; this block is rewritten on install.';
-
-/**
- * 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';
-  }
-
+function setupPath(mosaicHome: string, _p: WizardPrompter): PathAction {
   const binDir = join(mosaicHome, 'bin');
+  const currentPath = process.env['PATH'] ?? '';
+
+  if (currentPath.includes(binDir)) {
+    return 'already';
+  }
+
   const profilePath = getShellProfilePath();
   if (!profilePath) return 'skipped';
 
   const isWindows = platform() === 'win32';
-  const block = managedBlockFor(binDir, isWindows);
+  const exportLine = isWindows
+    ? `\n# Mosaic\n$env:Path = "${binDir};$env:Path"\n`
+    : `\n# Mosaic\nexport PATH="${binDir}:$PATH"\n`;
 
-  let content = '';
+  // Check if already in profile
   if (existsSync(profilePath)) {
-    content = readFileSync(profilePath, 'utf-8');
-  }
-
-  // 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';
+    const content = readFileSync(profilePath, 'utf-8');
+    if (content.includes(binDir)) {
+      return 'already';
+    }
   }
 
   try {
-    writeFileSync(profilePath, next, 'utf-8');
+    appendFileSync(profilePath, exportLine, 'utf-8');
     return 'added';
   } catch {
     return 'skipped';
@@ -342,7 +286,7 @@ export async function finalizeStage(
   }
 
   // 7. PATH setup
-  const pathAction = setupPath(state.mosaicHome, DEFAULT_MOSAIC_HOME);
+  const pathAction = setupPath(state.mosaicHome, p);
 
   let summaryShown = false;
   const showSummary = () => {