Temporary integration: three-way merge private Work Lane fork onto v0.0.35

.github/workflows/macbrains-spec.yml

@@ -0,0 +1,41 @@
+name: MacBrains specification
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - "macbrains/**"
+    paths:
+      - "AGENTS.md"
+      - "MACBRAINS.md"
+      - "docs/macbrains/**"
+      - "scripts/validate-macbrains-spec.mjs"
+      - ".github/workflows/macbrains-spec.yml"
+  pull_request:
+    paths:
+      - "AGENTS.md"
+      - "MACBRAINS.md"
+      - "docs/macbrains/**"
+      - "scripts/validate-macbrains-spec.mjs"
+      - ".github/workflows/macbrains-spec.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate campaign files
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.13.1"
+          package-manager-cache: false
+
+      - name: Validate MacBrains specification
+        run: node scripts/validate-macbrains-spec.mjs

AGENTS.md

@@ -1,3 +1,13 @@
+# MacBrains Fork Directive
+
+This branch belongs to the MacBrains fork. Before planning or editing, read `MACBRAINS.md` and every file in `docs/macbrains/` referenced by it. Those files define the fork's product contract, domain model, implementation ledger, acceptance matrix, and execution prompt.
+
+For fork work, the MacBrains contract overrides upstream product preferences where they conflict. Existing safety rules, architecture boundaries, performance discipline, multi-surface requirements, and development-state protections below remain mandatory.
+
+Do not stop after producing a plan when implementation is authorized. Use an isolated worktree, preserve source truth, keep agents visible, produce exact receipts, and do not claim completion without current tests, independent verification, and a user-visible deliverable.
+
+---
+
 # T3 Code
 
 T3 Code is a minimal GUI for coding agents. A Node WebSocket server wraps provider CLIs (Codex, Claude Code, Cursor, Grok, OpenCode) and serves web, desktop, and mobile clients.
@@ -136,4 +146,4 @@ Full glossary with file links: `docs/reference/encyclopedia.md`
 ## Additional tips
 
 - Don't verify with browsers or computer use unless the user explicitly agrees or requests it.
-- Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.
+- Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.

MACBRAINS.md

@@ -0,0 +1,162 @@
+# MacBrains T3 Code Operating Contract
+
+This fork is the user-facing control plane for Nayte's coding agents, repositories, Mac, and Linux compute node. It is not a generic chat launcher.
+
+## Authority
+
+Apply this precedence whenever instructions conflict:
+
+1. current repository state and repository-scoped instructions;
+2. canonical project records, manifests, databases, CI, and experiment ledgers;
+3. current command output and durable receipts;
+4. approved handoff documents;
+5. conversation narrative.
+
+Never use remembered state as a substitute for reading the real repository. Every state-changing run starts with a read-only source-truth preflight.
+
+## Required run lifecycle
+
+Every substantial run MUST visibly pass through these durable states:
+
+`queued -> preflight -> oriented -> planned -> executing -> testing -> reviewing -> deliverable-ready -> completed`
+
+Additional terminal states:
+
+`blocked`, `failed`, `cancelled`, `superseded`, `recovery-required`.
+
+A provider saying it is done does not complete a run. Completion is decided by the orchestration layer only after required receipts exist.
+
+## Mandatory receipts
+
+A run cannot enter `completed` without all applicable receipts:
+
+- repository identity, branch, HEAD, worktree, dirty state, and instruction files;
+- ownership and overlap assessment;
+- plan and acceptance criteria;
+- files changed and final diff summary;
+- commands executed with exit status;
+- tests, lint, typecheck, build, and UI validation results;
+- staged file list or explicit statement that nothing is staged;
+- user-visible launch or access path;
+- screenshots or recordings for UI changes;
+- unresolved risks and missing evidence;
+- final verdict using `PROVEN`, `INFERRED`, `SUSPECTED`, and `UNKNOWN`.
+
+No spinner, assistant message, or provider process state may impersonate these receipts.
+
+## Worktree isolation
+
+Substantial repository work uses one isolated Git worktree per implementation lane. The UI must show:
+
+- repository;
+- base branch and base SHA;
+- lane branch;
+- worktree path;
+- owner agent;
+- changed files;
+- ahead/behind and conflict status;
+- whether another live lane overlaps the same files.
+
+Never silently edit the primary checkout when an isolated lane is available. Never clean, reset, switch, delete, or repurpose another lane without explicit evidence that it is abandoned and safe.
+
+## Agent topology
+
+Default substantial topology:
+
+1. **Executor** performs inspection, edits, and focused validation.
+2. **Advisor** reviews the approach after orientation and before irreversible or broad edits.
+3. **Verifier** independently reviews the finished diff, evidence, and acceptance criteria.
+
+Do not fan out multiple editors into overlapping files. Parallel agents require explicit ownership boundaries and merge contracts.
+
+Preserve productive explorer context, but transfer claims to an independent canonical verifier before treating them as fact.
+
+## Model routing
+
+Use the smallest sufficient model and reasoning level.
+
+- routine bounded work: lower-cost executor;
+- normal implementation and research: medium reasoning;
+- architecture, migrations, concurrency, security, performance, and provenance: executor + stronger advisor + independent verifier;
+- escalate only after task-specific failure evidence.
+
+The UI must store the selected role, provider instance, model, reasoning level, and escalation cause for every agent lane.
+
+## Mac and Linux node
+
+The Mac is the interactive control and integration surface. The Linux node is a first-class execution environment for heavy builds, tests, benchmarks, analysis, and long-running jobs.
+
+Node rules:
+
+- no Python implementation or Python-based worker prompts;
+- prefer C, C++, Rust, Swift where supported, shell, or another native compiled implementation;
+- show the exact environment and filesystem owning every command;
+- preserve artifacts and return them through typed receipts;
+- do not imply that node output is integrated until the Mac repository has received and verified it.
+
+For ANVIL, always write `ANVIL` uppercase except in case-sensitive identifiers, commands, and paths.
+
+## Visible completion
+
+Backend implementation is not completion. Every durable feature must have:
+
+- an obvious UI surface;
+- a launch or access path;
+- persistent visibility after restart;
+- notifications when attention is required;
+- a demonstrated end-to-end acceptance check that Nayte can see and use.
+
+A hidden daemon, database row, log file, or command without a discoverable UI does not count as delivered.
+
+## Remote and mobile
+
+Web, desktop, iPhone, and iPad are first-class control surfaces. A workflow that can start on desktop must remain observable and controllable remotely unless the operation is inherently local-only.
+
+Required remote capabilities include:
+
+- add and manage projects on remote environments;
+- create and inspect worktrees;
+- start, interrupt, steer, queue, resume, and recover runs;
+- view live logs, diff, tests, receipts, blockers, and agent topology;
+- receive actionable notifications;
+- open the exact repository, branch, PR, artifact, or dashboard involved.
+
+Never expose a public backend without authenticated access. Prefer Tailscale endpoints and preserve the existing environment/access-endpoint boundary.
+
+## User interaction
+
+Do not force repeated gates or ceremonial confirmations. Ask only when missing information changes the correct action or an irreversible boundary requires explicit consent.
+
+For authorized repository work, proceed through the full lifecycle and stop only at a real blocker or completed acceptance contract. Surface blockers with exact evidence and the smallest safe next action.
+
+## Completion report
+
+Every completed or blocked run must close with these fields:
+
+- `proven`
+- `missing evidence`
+- `possibly wrong or overstated`
+- `exact next action`
+- `what does not count as completion`
+- `safe to continue here or start a fresh context`
+
+## Implementation map
+
+The complete product and engineering specification is indexed by `docs/macbrains/README.md`. The required campaign artifacts are:
+
+- `docs/macbrains/FORK_BASELINE.md`
+- `docs/macbrains/DOCUMENTATION_AUDIT.md`
+- `docs/macbrains/PRODUCT_SPEC.md`
+- `docs/macbrains/PROJECT_PROFILES.md`
+- `docs/macbrains/DOMAIN_MODEL.md`
+- `docs/macbrains/IMPLEMENTATION_LEDGER.md`
+- `docs/macbrains/CAMPAIGN_MANIFEST.json`
+- `docs/macbrains/WORKFLOW_TEMPLATES.json`
+- `docs/macbrains/ACCEPTANCE_MATRIX.md`
+- `docs/macbrains/DEFAULT_POLICIES.json`
+- `docs/macbrains/FORK_IDENTITY_AND_RELEASE.md`
+- `docs/macbrains/PULL_TO_MAC.md`
+- `docs/macbrains/IMPLEMENTATION_HANDOFF.md`
+- `docs/macbrains/AGENT_EXECUTION_PROMPT.md`
+
+Agents must read the index, contract, project profile, selected workflow template, current package definition, and applicable acceptance rows before changing behavior governed by this fork.

apps/server/src/auth/RpcAuthorization.ts

@@ -27,6 +27,8 @@ export const RPC_REQUIRED_SCOPES = {
   [ORCHESTRATION_WS_METHODS.subscribeShell]: AuthOrchestrationReadScope,
   [ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot]: AuthOrchestrationReadScope,
   [ORCHESTRATION_WS_METHODS.subscribeThread]: AuthOrchestrationReadScope,
+  [ORCHESTRATION_WS_METHODS.subscribeLane]: AuthOrchestrationReadScope,
+  [ORCHESTRATION_WS_METHODS.getLaneDetail]: AuthOrchestrationReadScope,
   [WS_METHODS.serverProbe]: AuthOrchestrationReadScope,
   [WS_METHODS.serverGetConfig]: AuthOrchestrationReadScope,
   [WS_METHODS.serverRefreshProviders]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -108,6 +108,8 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          getLaneShellById: () => Effect.succeed(Option.none()),
+          getLaneDetail: () => Effect.succeed(Option.none()),
           }),
         ),
       );
@@ -201,6 +203,8 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          getLaneShellById: () => Effect.succeed(Option.none()),
+          getLaneDetail: () => Effect.succeed(Option.none()),
           }),
         ),
       );
@@ -284,6 +288,8 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          getLaneShellById: () => Effect.succeed(Option.none()),
+          getLaneDetail: () => Effect.succeed(Option.none()),
           }),
         ),
       );
@@ -352,6 +358,8 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          getLaneShellById: () => Effect.succeed(Option.none()),
+          getLaneDetail: () => Effect.succeed(Option.none()),
           }),
         ),
       );
@@ -405,6 +413,8 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          getLaneShellById: () => Effect.succeed(Option.none()),
+          getLaneDetail: () => Effect.succeed(Option.none()),
           }),
         ),
       );

apps/server/src/environment/ServerEnvironment.ts

@@ -142,6 +142,7 @@ export const make = Effect.gen(function* () {
       connectionProbe: true,
       threadSettlement: true,
       threadSnooze: true,
+      workLanes: true,
       ...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
     },
   };

apps/server/src/laneResume.ts

@@ -0,0 +1,12 @@
+/** Default bound matching SHELL_RESUME_MAX_GAP / event-store page size. */
+export const LANE_RESUME_MAX_GAP = 1_000;
+
+/** Prefer a detail snapshot when the resume cursor is missing or too far behind. */
+export function shouldResumeLaneWithSnapshot(
+  latestSequence: number,
+  afterSequence: number,
+  maxGap: number = LANE_RESUME_MAX_GAP,
+): boolean {
+  const replayGap = latestSequence - afterSequence;
+  return replayGap < 0 || replayGap > maxGap;
+}

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -156,6 +156,7 @@ describe("OrchestrationEngine", () => {
           session: null,
         },
       ],
+      lanes: [],
     };
     const commandReadModel = {
       ...projectionSnapshot,
@@ -183,13 +184,15 @@ describe("OrchestrationEngine", () => {
               snapshotSequence: projectionSnapshot.snapshotSequence,
               projects: [],
               threads: [],
+              lanes: [],
               updatedAt: projectionSnapshot.updatedAt,
             }),
           getArchivedShellSnapshot: () =>
             Effect.succeed({
               snapshotSequence: projectionSnapshot.snapshotSequence,
               projects: [],
               threads: [],
+              lanes: [],
               updatedAt: projectionSnapshot.updatedAt,
             }),
           getSnapshotSequence: () =>
@@ -203,6 +206,8 @@ describe("OrchestrationEngine", () => {
           getThreadShellById: () => Effect.succeed(Option.none()),
           getThreadDetailById: () => Effect.succeed(Option.none()),
           getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          getLaneShellById: () => Effect.succeed(Option.none()),
+          getLaneDetail: () => Effect.succeed(Option.none()),
         }),
       ),
       Layer.provide(

apps/server/src/orchestration/Layers/OrchestrationEngine.ts

@@ -3,6 +3,7 @@ import type {
   OrchestrationReadModel,
   ProjectId,
   ThreadId,
+  WorkLaneId,
 } from "@t3tools/contracts";
 import { OrchestrationCommand } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
@@ -57,8 +58,8 @@ interface CommandEnvelope {
 }
 
 function commandToAggregateRef(command: OrchestrationCommand): {
-  readonly aggregateKind: "project" | "thread";
-  readonly aggregateId: ProjectId | ThreadId;
+  readonly aggregateKind: "project" | "thread" | "lane";
+  readonly aggregateId: ProjectId | ThreadId | WorkLaneId;
 } {
   switch (command.type) {
     case "project.create":
@@ -68,6 +69,32 @@ function commandToAggregateRef(command: OrchestrationCommand): {
         aggregateKind: "project",
         aggregateId: command.projectId,
       };
+    case "lane.create":
+    case "lane.task-contract.update":
+    case "lane.preflight.request":
+    case "lane.orientation.record":
+    case "lane.plan.propose":
+    case "lane.plan.activate":
+    case "lane.execution.start":
+    case "lane.testing.start":
+    case "lane.review.request":
+    case "lane.deliverable.register":
+    case "lane.completion.request":
+    case "lane.block":
+    case "lane.unblock":
+    case "lane.cancel":
+    case "lane.supersede":
+    case "lane.recovery.request":
+    case "lane.completion.invalidate":
+    case "lane.fail":
+    case "lane.meta.update":
+    case "source-truth.preflight.record":
+    case "source-truth.conflict.record":
+    case "source-truth.refresh.request":
+      return {
+        aggregateKind: "lane",
+        aggregateId: command.laneId,
+      };
     default:
       return {
         aggregateKind: "thread",