feat(operations): codify premote staging lanes

Author: giggabit-mac

.codex/skills/premote-staging/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: premote-staging
+description: Promote the T3 Code staging lane to main across Jordan's Linux server and Mac launcher checkout. Use when the user asks to "premote staging", "promote staging to main", update T3 Code main from staging, normalize the four durable T3 Code lanes, or run the project-specific staging promotion flow.
+---
+
+# Premote Staging
+
+## Overview
+
+This skill runs the project-specific T3 Code promotion flow. It treats `original`, `nightly`, `staging`, and `main` as the only durable Linux lanes, promotes `staging` to the live `main` lane only after verification and backups, and then updates the Mac checkout to match.
+
+## Required Reading
+
+Read `references/procedure.md` before acting. Also read `docs/operations/premote-staging.md` from the repo if the procedure has changed since this skill was last edited.
+
+## Operating Rules
+
+- Use `fleet-ssh giggabit-server -- <command>` or `ssh giggabit-server` for Linux work. Prefer the fleet wrapper when Node, pnpm, or repo tools need the development PATH.
+- Do not move `main` while `T3 Code Main` is running from `/home/jgigg/code/t3code`; stop the launcher first and restart it after promotion.
+- Do not skip `vp check` or `vp run typecheck`. Run them with Node `24.13.1`.
+- Preserve dirty state with patch files, stashes, or backup refs before removing temporary worktrees or switching the Mac checkout.
+- Do not mass-delete GitHub branches during the promotion. Update durable remote lanes and create remote backup branches first.
+- If a required verification step fails, leave `main` untouched or restore it from the backup ref before reporting.
+
+## Completion Criteria
+
+The flow is complete only when Linux `main` and the Mac checkout point at the promoted commit, T3 Code Main is running again, required checks are recorded, and temporary local worktrees have either been removed or explicitly left with a reason.

.codex/skills/premote-staging/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Premote Staging"
+  short_description: "Promote T3 Code staging to main"
+  default_prompt: "Use $premote-staging to promote the T3 Code staging lane to main on giggabit-server."

.codex/skills/premote-staging/references/procedure.md

@@ -0,0 +1,58 @@
+# Premote Staging Procedure
+
+Use this procedure to promote T3 Code `staging` to `main` for Jordan's local fleet.
+
+## Lanes
+
+- `original`: `/home/jgigg/code/t3code/.worktrees/original`, branch `original`, tracks `upstream/main`.
+- `nightly`: `/home/jgigg/code/t3code/.worktrees/nightly`, branch `nightly`, latest upstream plus replayed local topics.
+- `staging`: `/home/jgigg/code/t3code/.worktrees/staging`, branch `staging`, final verification lane.
+- `main`: `/home/jgigg/code/t3code`, branch `main`, live day-to-day lane.
+- Mac launcher checkout: `/Users/giggabit-mac/code/projects/t3code`, branch `main` after promotion.
+
+## Workflow
+
+1. Confirm the user explicitly wants staging promoted and accepts downtime for T3 Code Main.
+2. Audit:
+   - `fleet-doctor`
+   - remote `git status --short --branch` for all durable lanes
+   - `git worktree list --porcelain`
+   - running `t3code-dev-main`, `dev-runner`, Electron, and Vite+ processes
+3. Verify staging under Node `24.13.1`:
+   - `mise x node@24.13.1 -- bash -lc './node_modules/.bin/vp check'`
+   - `mise x node@24.13.1 -- bash -lc './node_modules/.bin/vp run typecheck'`
+   - `mise x node@24.13.1 -- bash -lc './node_modules/.bin/vp run lint:mobile'`
+   - `mise x node@24.13.1 -- bash -lc 'pnpm run topic-plugins:check'`
+4. Save backups:
+   - dirty Mac patch or stash
+   - dirty Linux temporary-worktree patches
+   - `refs/backup/premote-staging/<timestamp>/{main,staging,original,nightly,origin-main,origin-staging,upstream-main}` where refs exist
+5. Stop T3 Code Main before mutating `/home/jgigg/code/t3code`.
+6. Promote locally:
+   - `cd /home/jgigg/code/t3code`
+   - `git reset --hard staging`
+7. Push safely:
+   - create `origin/backup/premote-staging-<timestamp>-origin-main`
+   - create `origin/backup/premote-staging-<timestamp>-origin-staging`
+   - `git push --force-with-lease=main:<old-origin-main-sha> origin main:main`
+   - `git push --force-with-lease=staging:<old-origin-staging-sha> origin staging:staging`
+   - push `nightly` only after the durable nightly worktree exists and is clean
+8. Ensure durable Linux worktrees exist:
+   - Reset `original` to `upstream/main` after backup.
+   - Create or update `.worktrees/nightly` on branch `nightly`. If no newer replay candidate exists, it may temporarily match `staging`.
+   - Keep `.worktrees/staging` on branch `staging`.
+   - Keep `/home/jgigg/code/t3code` on branch `main`.
+9. Restart T3 Code Main with `~/.local/bin/t3code-dev-main`.
+10. Verify:
+    - `git -C /home/jgigg/code/t3code rev-parse HEAD`
+    - `curl -fsS https://giggabit-server.tailfb378a.ts.net/main/`
+    - process list shows the launcher running from `/home/jgigg/code/t3code`
+11. Update Mac:
+    - fetch origin
+    - switch to `main`
+    - reset to `origin/main`
+    - reapply only intentional saved edits
+12. Local cleanup:
+    - Remove temporary Linux worktrees after backup.
+    - Delete extra local branches only when their commits are reachable from durable branches or backup refs.
+    - Leave remote branch cleanup for a separate explicit pass.

AGENTS.md

@@ -28,7 +28,7 @@
   there.
 - `/home/jgigg/code/t3code/.worktrees/staging` is reserved for the `staging` branch and the staging promotion lane.
   Do not check out feature branches in this path.
-- `/home/jgigg/code/t3code/.worktrees/nightly-local` is the rolling upstream replay candidate worktree. It is owned
+- `/home/jgigg/code/t3code/.worktrees/nightly` is the durable upstream replay candidate worktree. It is owned
   by `pnpm run topic-stack:nightly -- --apply`; if it is dirty, nightly replay must fail closed instead of resetting
   it.
 - Do all new implementation work in a separate worktree whose directory name starts with `dev-`, for example
@@ -60,7 +60,7 @@
 - The `original` mirror should be synced from upstream and tested nightly so replayable local topics can be checked
   against the latest upstream base. Use `pnpm run topic-stack:nightly -- --dry-run` to inspect the plan and
   `pnpm run topic-stack:nightly -- --apply` to fetch `upstream`, back up and reset `original`, rebuild
-  `.worktrees/nightly-local`, and run verification. The nightly script never promotes to `staging`.
+  `.worktrees/nightly`, and run verification. The nightly script never promotes to `staging`.
 - Local replay topics are documented as repo-internal plugins under `local-plugins/<topic>/`. Keep each
   `plugin.json`, topic `README.md`, and `docs/operations/jordan-topic-stack.manifest.json` entry synchronized with
   the replay commit. These are not installable Codex plugins and must not use `.codex-plugin/plugin.json`.
@@ -122,8 +122,8 @@ Current topic order:
 
 When upstream changes, prefer the scripted nightly workflow in
 `docs/operations/nightly-upstream-replay.md`. It fetches upstream, backs up and
-resets `original`, creates or reuses `.worktrees/nightly-local`, creates
-`dev/nightly-topic-stack-YYYYMMDD`, cherry-picks the manifest topics in order,
+resets `original`, creates or reuses `.worktrees/nightly`, resets branch
+`nightly`, cherry-picks the manifest topics in order,
 and writes artifacts, including `topic-audit.md`, under `.t3code-nightly-runs/`. Resolve conflicts in the
 owning topic, run the verification commands from
 `docs/operations/jordan-topic-stack.md`, and compare the final stack against the
@@ -250,7 +250,7 @@ Source commits intentionally not replayed as new follow-up commits:
   server port `13833`, and desktop debugging port `9232`. Its app data lives in
   `~/.local/share/t3code-dev/staging`, and its config lives in `~/.config/t3code-dev/staging`.
 - `T3 Code Nightly` uses `~/.local/bin/t3code-dev-nightly` and
-  `~/.local/share/applications/t3code-dev-nightly.desktop`. It launches `.worktrees/nightly-local` on web port
+  `~/.local/share/applications/t3code-dev-nightly.desktop`. It launches `.worktrees/nightly` on web port
   `5833`, server port `13873`, and desktop debugging port `9234`, and exposes the public HTTPS route
   `https://giggabit-server.tailfb378a.ts.net/nightly/`. Its app data lives in `~/.local/share/t3code-dev/nightly`, and its
   config lives in `~/.config/t3code-dev/nightly`. The nightly worktree is rebuilt by

CONTEXT.md

@@ -11,3 +11,23 @@ _Avoid_: checkbox, checklist bullet, feature bullet
 **Topic Replay Audit**:
 A run-specific audit artifact that records what was inspected, replayed, repaired, verified, and signed off before a rebuilt local topic stack is promoted.
 _Avoid_: replay notes, checklist copy, promotion log
+
+**Durable Lane**:
+A long-lived local branch and worktree role in the T3 Code fork. The durable lanes are `original`, `nightly`, `staging`, and `main`; temporary topic, replay, and investigation branches are not durable lanes.
+_Avoid_: permanent branch, protected worktree, environment
+
+**Original Lane**:
+The resettable mirror of the upstream ping.gg T3 Code repository. It tracks `upstream/main` and does not contain Jordan-local topic commits.
+_Avoid_: upstream branch, clean copy
+
+**Nightly Lane**:
+The rebuilt candidate produced by replaying Jordan-local topic commits on top of the Original Lane. It is the place to inspect fresh upstream compatibility before promoting anything to Staging.
+_Avoid_: nightly-local, dev/nightly-topic-stack branch
+
+**Staging Lane**:
+The verified integration lane for Jordan-local updates. It receives tested topic commits from dev worktrees or the Nightly Lane and is the final proving ground before Main.
+_Avoid_: test branch, QA copy
+
+**Main Lane**:
+The day-to-day T3 Code lane used by the operator. It is updated from Staging only after explicit confirmation, backups, green checks, and a controlled restart of the running main app.
+_Avoid_: production, root checkout

apps/desktop/scripts/verify-staging-public.mjs

@@ -28,7 +28,7 @@ const DEFAULT_PAIRING_DEV_URL =
     ? "http://127.0.0.1:5833/nightly/"
     : "http://127.0.0.1:5793/staging/";
 const DEFAULT_PROJECT_ROOT = PUBLIC_VERIFY_TARGET === "nightly" ? repoRoot : "";
-const DEFAULT_PROJECT_TITLE = PUBLIC_VERIFY_TARGET === "nightly" ? "nightly-local" : "";
+const DEFAULT_PROJECT_TITLE = PUBLIC_VERIFY_TARGET === "nightly" ? "nightly" : "";
 const DEFAULT_PAIRING_TTL = "5m";
 const DEFAULT_NETWORK_PREFLIGHT_TIMEOUT_MS = 20_000;
 

apps/desktop/src/backend/DesktopServerExposure.test.ts

@@ -665,8 +665,8 @@ describe("DesktopServerExposure", () => {
 
     return withGitHarness(
       {
-        appRootRelativePath: "repo/.worktrees/nightly-local",
-        branch: "dev/nightly-topic-stack-20260626",
+        appRootRelativePath: "repo/.worktrees/nightly",
+        branch: "nightly",
         spawnerLayer: recordingSpawnerLayer(commands),
       },
       Effect.gen(function* () {
@@ -684,8 +684,8 @@ describe("DesktopServerExposure", () => {
         }
         assert.equal(error.servePath, "/staging");
         assert.include(error.message, "reserved for the staging branch/worktree");
-        assert.include(error.message, ".worktrees/nightly-local");
-        assert.include(error.message, "dev/nightly-topic-stack-20260626");
+        assert.include(error.message, ".worktrees/nightly");
+        assert.include(error.message, "nightly");
         assert.deepEqual(commands, []);
       }),
     );
@@ -718,13 +718,13 @@ describe("DesktopServerExposure", () => {
     );
   });
 
-  it.effect("allows /nightly from the rolling nightly replay worktree", () => {
+  it.effect("allows /nightly from the durable nightly worktree", () => {
     const commands: Array<{ readonly command: string; readonly args: ReadonlyArray<string> }> = [];
 
     return withGitHarness(
       {
-        appRootRelativePath: "repo/.worktrees/nightly-local",
-        branch: "dev/nightly-topic-stack-20260707",
+        appRootRelativePath: "repo/.worktrees/nightly",
+        branch: "nightly",
         spawnerLayer: recordingSpawnerLayer(commands),
       },
       Effect.gen(function* () {
@@ -768,7 +768,7 @@ describe("DesktopServerExposure", () => {
           );
         }
         assert.equal(error.servePath, "/nightly");
-        assert.include(error.message, "reserved for the nightly replay branch/worktree");
+        assert.include(error.message, "reserved for the nightly branch/worktree");
         assert.include(error.message, ".worktrees/staging");
         assert.deepEqual(commands, []);
       }),

docs/adr/0001-four-durable-t3code-lanes.md

@@ -0,0 +1,7 @@
+# Four Durable T3 Code Lanes
+
+The local T3 Code fork uses four durable lanes: `original`, `nightly`, `staging`, and `main`. This keeps the upstream mirror, nightly replay candidate, final verification lane, and day-to-day running version separate while allowing temporary topic branches and worktrees to be removed after their work is merged.
+
+## Consequences
+
+Temporary `dev-*`, replay, and investigation worktrees are disposable after backup and verification. Promotion to `main` is a controlled replacement from `staging`, not an ad hoc merge from whatever topic branch happens to exist.

docs/operations/jordan-topic-stack.md

@@ -119,10 +119,10 @@ pnpm run topic-stack:nightly -- --apply
 The detailed workflow lives in `docs/operations/nightly-upstream-replay.md`.
 It fetches `upstream`, backs up dirty or divergent `original`, resets
 `.worktrees/original` exactly to `upstream/main`, creates or reuses the rolling
-`.worktrees/nightly-local` candidate worktree, creates
-`dev/nightly-topic-stack-YYYYMMDD`, and cherry-picks manifest topics in order.
+`.worktrees/nightly` candidate worktree, resets branch `nightly`, and
+cherry-picks manifest topics in order.
 Artifacts are written under
-`.worktrees/nightly-local/.t3code-nightly-runs/YYYYMMDD-HHMMSS/`.
+`.worktrees/nightly/.t3code-nightly-runs/YYYYMMDD-HHMMSS/`.
 Each apply run also writes `topic-audit.md` with run metadata, branch-diff
 audit placeholders, replay outcomes, one topic checklist placeholder per
 manifest topic, verification placeholders, unresolved risk tracking, and a
@@ -218,7 +218,7 @@ Manual promotion from the nightly candidate:
 cd /home/jgigg/code/t3code/.worktrees/staging
 git status --short
 git update-ref refs/backup/staging-before-nightly-promote/$(date +%Y%m%d-%H%M%S) staging
-git merge --ff-only dev/nightly-topic-stack-YYYYMMDD
+git merge --ff-only nightly
 vp check
 vp run typecheck
 vp run verify:staging-public

docs/operations/nightly-upstream-replay.md

@@ -10,7 +10,7 @@ topic stack in a rolling candidate worktree. It does not promote anything to
   `upstream/main`. The nightly script creates a backup ref for dirty or
   divergent state, stashes dirty changes with untracked files, then resets the
   worktree to `upstream/main`.
-- `/home/jgigg/code/t3code/.worktrees/nightly-local` is the rebuild candidate.
+- `/home/jgigg/code/t3code/.worktrees/nightly` is the durable rebuild candidate.
   It is reused across runs. If it is dirty, the script fails closed before
   running mutating git commands.
 - `/home/jgigg/code/t3code/.worktrees/staging` is updated only by manual
@@ -81,25 +81,25 @@ pnpm run topic-stack:nightly -- --apply
 
 Apply mode:
 
-1. Verifies `nightly-local` is not dirty.
+1. Verifies `nightly` is not dirty.
 2. Fetches `upstream --prune`.
 3. Creates `refs/backup/original-before-nightly/YYYYMMDD-HHMMSS` when
    `original` is dirty or not at `upstream/main`.
 4. Stashes dirty `original` changes with untracked files.
 5. Resets `original` to `upstream/main` and removes untracked files.
-6. Creates or reuses `.worktrees/nightly-local`.
-7. Creates or resets branch `dev/nightly-topic-stack-YYYYMMDD`.
+6. Creates or reuses `.worktrees/nightly`.
+7. Creates or resets branch `nightly`.
 8. Cherry-picks manifest topics in order.
 9. Records empty cherry-picks and skips them with `git cherry-pick --skip`.
-10. Stops on conflicts and leaves `nightly-local` ready for human repair.
+10. Stops on conflicts and leaves `nightly` ready for human repair.
 11. Runs `vp check`, `vp run typecheck`, and
     `pnpm run topic-plugins:check`.
 12. Writes a `topic-audit.md` stub for the run.
 
 Run artifacts are written under:
 
 ```text
-.worktrees/nightly-local/.t3code-nightly-runs/YYYYMMDD-HHMMSS/
+.worktrees/nightly/.t3code-nightly-runs/YYYYMMDD-HHMMSS/
 ```
 
 Run artifacts include `plan.json`, `topics.json`, and `topic-audit.md`.
@@ -113,7 +113,7 @@ complete the audit before promotion.
 ## Nightly Launcher
 
 The Omarchy launcher target for this rebuilt worktree is `nightly`. It expects
-`.worktrees/nightly-local` to be on `dev/nightly-topic-stack-YYYYMMDD`, serves
+`.worktrees/nightly` to be on branch `nightly`, serves
 the app through `https://giggabit-server.tailfb378a.ts.net/nightly/`, and uses isolated
 ports and app data:
 
@@ -161,7 +161,7 @@ Promotion is manual only:
 cd /home/jgigg/code/t3code/.worktrees/staging
 git status --short
 git update-ref refs/backup/staging-before-nightly-promote/$(date +%Y%m%d-%H%M%S) staging
-git merge --ff-only dev/nightly-topic-stack-YYYYMMDD
+git merge --ff-only nightly
 vp check
 vp run typecheck
 vp run verify:staging-public