Plan and chunk 1 start [PAP-17]

.github/workflows/ci-non-mcp-gates.yml

@@ -0,0 +1,64 @@
+name: CI Non-MCP Gates
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-non-mcp-gates-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  non_mcp_gates:
+    name: Build, Test, Lint, Preflight
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    env:
+      CI: "true"
+      CODEX_AUTO_LINK: "false"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          npm ci
+
+      - name: Build
+        run: |
+          set -euo pipefail
+          npm run build
+
+      - name: Test
+        env:
+          HOME: ${{ runner.temp }}/codex-synaptic-ci-home
+        run: |
+          set -euo pipefail
+          mkdir -p "${HOME}"
+          npm test
+
+      - name: Lint
+        run: |
+          set -euo pipefail
+          npm run lint
+
+      - name: Release preflight (canonical repo)
+        if: github.repository == 'clduab11/codex-synaptic'
+        run: |
+          set -euo pipefail
+          npm run release:preflight
+
+      - name: Release preflight skipped (non-canonical repo)
+        if: github.repository != 'clduab11/codex-synaptic'
+        run: |
+          echo "Skipping release preflight: repository is ${{ github.repository }} (expects clduab11/codex-synaptic)."

AGENTS.md

@@ -10,6 +10,13 @@ The Codex-Synaptic system enhances OpenAI's Codex with advanced multi-agent capa
 - **Autoscaler behaviour:** With the background daemon disabled, idle worker retirement requests cannot execute. Expect scale-down warnings in logs and manually right-size replicas after experiments. See `docs/runbooks/autoscaler-daemon-coordination.md` for operational guidance.
 - **Repository hygiene:** Active development is running from the local `codex-synaptic-clone` directory, but upstream pushes must target `github.com/clduab11/codex-synaptic`. Align the folder/remote names before release packaging so automation recipes resolve assets correctly. See `docs/runbooks/workspace-rename-guide.md` for the step-by-step procedure.
 
+## Startup Gate (Codex For macOS)
+
+- Run `codex-synaptic launch --json` before repository work whenever the user asks to launch or verify readiness first.
+- Treat launch as a hard gate: if `ok` is `false` (or the command exits non-zero), stop and only return remediation commands.
+- Proceed with repository changes only when launch returns `ok=true` and `nextAction="continue"`.
+- Default launch gate profiles are `mcp-filesystem`, `mcp-playwright`, and `mcp-desktop-commander`.
+
 ## Core Agent Types
 
 ### 1. Worker Agents

README.md

@@ -59,8 +59,10 @@ npm install
 npm run build
 
 # readiness
+node dist/cli/index.js launch --json
+node dist/cli/index.js launch --strict --json
 node dist/cli/index.js doctor
-node dist/cli/index.js doctor --strict
+node dist/cli/index.js doctor --strict --json
 
 # daemon lifecycle
 node dist/cli/index.js background start
@@ -76,6 +78,7 @@ node dist/cli/index.js tui --local --interval 1000
 
 # MCP profiles and registration
 node dist/cli/index.js env plan mcp-filesystem mcp-playwright mcp-desktop-commander
+node dist/cli/index.js env docker-login mcp-filesystem mcp-playwright mcp-desktop-commander
 node dist/cli/index.js env up mcp-filesystem mcp-playwright mcp-desktop-commander
 node dist/cli/index.js env status mcp-filesystem mcp-playwright mcp-desktop-commander
 node dist/cli/index.js env codex-register mcp-filesystem mcp-playwright mcp-desktop-commander --replace
@@ -89,6 +92,9 @@ Non-interactive CLI commands run in one-shot mode by default (the process exits
 # Local mode
 codex -C /absolute/path/to/codex-synaptic
 
+# first-launch gate in this repo
+codex-synaptic launch --json
+
 # Worktree mode
 git worktree add ../codex-synaptic-worktree -b codex/macos-ops
 codex -C ../codex-synaptic-worktree

docker/mcp/docker-compose.playwright.yml

@@ -1,10 +1,10 @@
 version: '3.8'
 services:
   mcp-playwright:
-    image: ghcr.io/context-labs/playwright-mcp:latest
+    image: mcp/playwright:latest
     container_name: codex-mcp-playwright
     restart: unless-stopped
     ports:
       - "7030:7030"
     shm_size: '1gb'
-    command: ["--port", "7030"]
+    command: ["--port", "7030", "--host", "0.0.0.0"]

docs/guides/codex-macos-workflows.md

@@ -1,6 +1,6 @@
 # Codex macOS Workflows (Local, Worktree, Cloud + MCP)
 
-Last reviewed: 2026-02-13  
+Last reviewed: 2026-02-14  
 Audience: contributors using Codex app/CLI on macOS (Apple Silicon) with Codex-Synaptic.
 
 ## Source Of Truth
@@ -17,7 +17,7 @@ This guide is aligned with:
   - `https://developers.openai.com/codex/cli/features/`
   - `https://developers.openai.com/codex/security/`
 
-## Bootstrap And Doctor (Run First)
+## Bootstrap And Launch Gate (Run First)
 
 ```bash
 cd /absolute/path/to/codex-synaptic
@@ -29,11 +29,40 @@ codex --help
 codex mcp --help
 codex mcp add --help
 
-# one-shot readiness checks (auth + mcp + repo cli)
-node dist/cli/index.js doctor
+# one-command bootstrap + strict readiness gate
+node dist/cli/index.js launch --json
 
-# enforce failure in CI/automation
-node dist/cli/index.js doctor --strict --json
+# explicit strict form for CI/automation
+node dist/cli/index.js launch --strict --json
+```
+
+Launch defaults:
+
+- Detached runtime authority (`background start`) that remains running after success.
+- Required MCP gate set: `mcp-filesystem`, `mcp-playwright`, `mcp-desktop-commander`.
+- Hard-stop behavior in strict mode: first failing gate exits non-zero with remediation commands.
+
+Typical first Codex app prompt in this repo:
+
+```text
+Launch codex-synaptic and determine health/status prior to beginning repository work.
+```
+
+### Launch Failure Remediation Examples
+
+```bash
+# Codex auth missing
+codex login
+
+# Docker registry auth for MCP images
+node dist/cli/index.js env docker-login mcp-filesystem mcp-playwright mcp-desktop-commander
+
+# MCP runtime or registration drift
+node dist/cli/index.js env up mcp-filesystem mcp-playwright mcp-desktop-commander
+node dist/cli/index.js env codex-register mcp-filesystem mcp-playwright mcp-desktop-commander --replace
+
+# Re-run hard gate
+node dist/cli/index.js launch --strict --json
 ```
 
 ## Runtime Model (Deterministic)
@@ -130,6 +159,9 @@ codex cloud apply <task-id>
 # inspect profiles and codex registration targets
 node dist/cli/index.js env plan mcp-filesystem mcp-playwright mcp-desktop-commander
 
+# authenticate required Docker registries (for private GHCR images)
+node dist/cli/index.js env docker-login mcp-filesystem mcp-playwright mcp-desktop-commander
+
 # safest default: filesystem read-only
 node dist/cli/index.js env up mcp-filesystem mcp-playwright mcp-desktop-commander
 
@@ -147,6 +179,7 @@ codex mcp list --json
 Expected indicators:
 
 - `env status` returns `running: yes` and `healthy: yes` for active profiles.
+- `launch --json` returns `ok: true` and `nextAction: "continue"`.
 - `doctor` reports MCP profile checks passing and registration present.
 
 ## Sandbox And Approval Recommendations
@@ -169,7 +202,7 @@ codex --sandbox read-only --ask-for-approval on-request
 ```bash
 # 1) refresh build + readiness
 npm run build
-node dist/cli/index.js doctor --strict
+node dist/cli/index.js launch --strict --json
 
 # 2) run focused work
 codex exec "Implement one bounded fix with tests"

docs/guides/quick-start.md

@@ -1,6 +1,6 @@
 # Quick Start (Codex-Synaptic + Codex macOS)
 
-Last reviewed: 2026-02-10
+Last reviewed: 2026-02-14
 
 ## 1. Install and build
 
@@ -9,43 +9,49 @@ npm install
 npm run build
 ```
 
-## 2. Verify CLI health
+## 2. Run launch gate
 
 ```bash
-npm run cli -- system status
+npm run cli -- launch --strict --json
 ```
 
-Expected output in a cold shell:
+Expected success indicators:
 
-```text
-System not started. Run `codex-synaptic system start` first.
+```json
+{
+  "ok": true,
+  "nextAction": "continue"
+}
 ```
 
-Expected output after startup:
+If launch fails, stop repository work and run the remediation commands returned in the report.
+For Docker registry-denied errors, run:
 
 ```bash
-npm run cli -- system start
+npm run cli -- env docker-login mcp-filesystem mcp-playwright mcp-desktop-commander
 ```
 
-This command prints a telemetry snapshot and then exits cleanly in one-shot mode.
+## 3. Optional direct runtime inspection
 
-If you need to keep the foreground process alive for debugging, run with `CODEX_CLI_AUTO_SHUTDOWN=0`.
+```bash
+npm run cli -- system status
+```
 
-## 3. Run a minimal local workflow
+## 4. Run a minimal local workflow
 
 ```bash
 npm run cli -- reasoning plan "Stabilize codex-synaptic release readiness" --require-consensus --json
 npm run cli -- openai usage --json
 npm run cli -- hive-mind spawn "Verify macOS readiness smoke flow" --codex --dry-run
 ```
 
-## 4. Use Codex passthrough
+## 5. Use Codex passthrough
 
 ```bash
 codex-synaptic --codex --dry-run "Inspect current readiness blockers and propose bounded fixes"
 ```
 
-## 5. Run verification gates
+## 6. Run verification gates
 
 ```bash
 npm run lint