fix: enforce lifecycle and desktop launch boundaries

AGENTS.md

@@ -10,21 +10,23 @@ checkout.
 Artifacts, lifecycle states, Gates, verification evidence, release handoff, Incidents, and Evals.
 Use [`docs/sdlc/development-workflow.md`](docs/sdlc/development-workflow.md) and
 [`./script/devflow`](script/devflow) for daily change creation, approval recording, and validation.
-Install the external [`sdlc-skill`](https://github.com/IchenDEV/sdlc-skill) `ai-native-sdlc` skill
-when Bootstrap, audit, or incident-to-improvement guidance is needed; the repository checker remains
-the enforcement source.
+Use the external [`sdlc-skill`](https://github.com/IchenDEV/sdlc-skill) `ai-native-sdlc` skill only
+when guidance is needed to bootstrap or audit the development lifecycle, or improve it after an
+incident. Reuse an installed copy first; the repository checker remains the enforcement source.
 
 - A direct user implementation request may approve Intent. Record its source, constraints, named
-  approver, and observable acceptance in one change Artifact, then move it to `executing` before
-  repository implementation begins. An Artifact-only Intent proposal may remain `draft` or
-  `in-review`.
+  approver, and observable acceptance in one change bundle. Implementation requires accepted
+  Intent, Spec, and Plan; use verification `in-progress` while executing. Artifact-only proposals
+  may remain `draft` or `in-review`.
 - Reuse accepted ADRs, design documents, issues, and PRs as evidence; link them from the change
   Artifact instead of copying their state into another tracker.
-- Run `bun test script/verify/checks.test.ts` when either repository Gate changes. Before handoff,
-  always run `bun script/verify/docs.ts`, `bun script/verify/sdlc.ts`, and
-  `bun script/verify/sdlc.ts --worktree`. A PR that
-  changes repository files must change or add a schema-2 canonical
-  `docs/sdlc/changes/<date>-<slug>/` with schema-3 stage files (`intent.md`, `spec.md`,
+- Before handing off repository file changes, run `bun script/verify/docs.ts` and
+  `bun script/verify/sdlc.ts --worktree`; the latter includes the full lifecycle check. Run
+  `bun test script/verify/checks.test.ts` for Gate or lifecycle-contract changes, and
+  `bun test script/devflow.test.ts` for devflow changes. Also run applicable active Evals.
+  Read-only audits do not require these runs.
+- A PR that changes repository files must change or add a canonical
+  `docs/sdlc/changes/<date>-<slug>/` bundle with schema-3 stage files (`intent.md`, `spec.md`,
   `plan.md`, `verification.md`); implementation differences require that bundle's
   `intent.md`, `spec.md`, and `plan.md` to be `accepted` and every changed path to fall under its
   explicit `plan.md` scope.
@@ -57,9 +59,9 @@ automation state.
   cross-process ownership lock.
 - Session Git worktrees isolate code changes; they do not make shared application state safe.
 
-Until the profile contract below is implemented and verified, assume `bun run dev` supports only
-one live dev instance. A distinct `CODETWO_DATA_DIR` is a partial diagnostic workaround, not proof
-of safe multi-instance development.
+Until the [profile contract](docs/reference/desktop-development-profiles.md) is implemented and
+verified, assume `bun run dev` supports only one live dev instance. A distinct `CODETWO_DATA_DIR`
+is a partial diagnostic workaround, not proof of safe multi-instance development.
 
 ### Launch rules
 
@@ -78,71 +80,7 @@ Before starting the desktop:
 If multiple windows need to show the same sessions, use one Core with multiple renderer windows.
 Do not solve that requirement by sharing SQLite between multiple Core processes.
 
-### Required profile contract
-
-When implementing or using true multi-instance development, introduce an explicit
-`CODETWO_DEV_PROFILE` and make one profile the complete isolation boundary. Preserve the existing
-single-instance behavior when no profile is supplied.
-
-For every non-default profile, derive or require all of the following:
-
-- a unique absolute `CODETWO_DATA_DIR`, preferably under the current worktree's ignored
-  `.codex/run/instances/<profile>/data` directory;
-- an explicit unique `CODETWO_DEV_PORT` used by Vite with `strictPort: true`;
-- a profile-specific PID/ownership-lock path, Unix socket path, logs, and temporary runtime files;
-- isolated build output when two instances could build concurrently;
-- on macOS, a profile-specific development application name and bundle identifier when two app
-  bundles will run at once, so Dock identity, TCC attribution, app capture, and UI automation do
-  not select the wrong instance.
-
-Validate profile names before using them in paths or identifiers. Accept a small slug alphabet,
-reject traversal and empty values, and show the resolved profile, port, and data directory in the
-startup output.
-
-The intended interface after implementation is:
-
-```bash
-CODETWO_DEV_PROFILE=feature-a CODETWO_DEV_PORT=1421 bun run dev
-CODETWO_DEV_PROFILE=plugin-dev CODETWO_DEV_PORT=1422 bun run dev
-```
-
-Do not present those commands as supported until the launcher, Vite configuration, bundle
-metadata, and ownership checks have actually been implemented and exercised.
-
-### Same-profile ownership
-
-Before opening SQLite, running migrations, normalizing interrupted work, purging transient state,
-or removing/rebinding the scene socket, the native Core must acquire an operating-system-backed
-exclusive lock under the resolved data directory.
-
-- If the lock is held, fail fast with a clear "profile already running" error. Include safe owner
-  diagnostics such as profile, PID, and data directory when available.
-- A PID file alone is not sufficient; PID reuse and stale files must not grant ownership.
-- Normal process exit and crashes must release the OS lock automatically.
-- Startup recovery may mark in-flight work interrupted only after ownership is acquired.
-- Never unlink a live instance's socket before ownership is established.
-
-If shared state across independently hosted Core processes ever becomes a product requirement,
-design that separately as a single Core daemon with multiple clients or as a durable lease and
-fencing protocol. Do not weaken the development-profile lock ad hoc.
-
-### Acceptance criteria
-
-Do not call multi-instance development complete until an automated or agent-runnable harness proves
-all of these behaviors:
-
-1. Profiles A and B start concurrently on different ports and use different databases, sockets,
-   provider child-process groups, and build/runtime directories.
-2. A prompt or permission request in A cannot appear in, cancel, interrupt, or mutate B.
-3. Starting a second process with profile A fails before database mutation, startup recovery, or
-   socket replacement, while the first A process and its active turn continue normally.
-4. After the first A process exits or crashes, A can restart and only its own genuinely abandoned
-   in-flight work is reconciled as interrupted.
-5. Stopping or rebuilding B does not stop, relaunch, or overwrite A.
-6. The default no-profile launch remains backward compatible and does not move or rewrite existing
-   user data unexpectedly.
-7. Port collisions and invalid profiles fail with actionable messages; no launcher silently falls
-   back to another port or shared directory.
-
-For validation, capture the resolved instance identities and assert the exact user-visible symptom,
-not merely that two processes stayed alive.
+Before implementing or changing development-instance isolation, read the
+[development profile contract](docs/reference/desktop-development-profiles.md). It preserves the
+required profile boundaries, OS-backed ownership lock, and complete acceptance criteria. Do not
+claim profile-based launches are supported until that contract is implemented and exercised.

README.md

@@ -95,6 +95,11 @@ cd codeTwo
 ./script/dev/run.sh
 ```
 
+If this launcher's tracked instance is already running, normal launch refuses to replace it.
+Use `./script/dev/run.sh --logs` or `--telemetry` to inspect it, or `--restart` to explicitly stop
+and rebuild it. These modes do not provide multi-instance isolation; follow the
+[desktop launch rules](AGENTS.md#desktop-development-instances).
+
 C2 detects provider CLIs on your `PATH`. Provider-specific setup and the exact adapter commands
 are documented in [Providers](website/guide/providers.md).
 

crates/core/src/engine.rs

@@ -1383,7 +1383,7 @@ fn attach_host_mcp_servers(
 }
 
 const CODETWO_BROWSER_ROUTING_INSTRUCTIONS: &str = "[C2 desktop browser routing]\nFor any browser or website task, use the codetwo_browser MCP tools by default. Do not use node_repl, the host in-app browser, or Chrome unless the user explicitly asks for Chrome, an existing browser tab, or an existing login state. This routing rule applies even when another available skill describes a different in-app browser. Website access and sensitive actions still require the approvals requested by codetwo_browser.";
-const CODEX_SITES_INSTRUCTIONS: &str = "[C2 Sites routing and safety]\nWhen the user asks to build, save, publish, deploy, manage, or inspect a hosted site, or when .openai/hosting.json exists, use the official OpenAI Sites plugin and its Sites skills. Reuse the exact project_id from .openai/hosting.json; never invent or transform Sites identifiers, and never expose or persist connector credentials. Treat saving a version and deploying it as separate stages, and remember that every Sites deployment URL is production. Immediately before any deployment, access-policy change, environment/secret change, custom-domain change, bypass-token generation, or deletion, require an explicit ACP or MCP approval even in Full Access; if the connector does not request one, stop and ask the user. A request for a local build or saved version alone never authorizes production deployment.";
+const CODEX_SITES_INSTRUCTIONS: &str = "[C2 Sites routing and safety]\nWhen the user explicitly requests OpenAI Sites, or the current task operates on the Sites project identified by .openai/hosting.json, use the official OpenAI Sites plugin and its Sites skills. Reuse the exact project_id from .openai/hosting.json; never invent or transform Sites identifiers, and never expose or persist connector credentials. Treat saving a version and deploying it as separate stages, and remember that every Sites deployment URL is production. Immediately before any deployment, access-policy change, environment/secret change, custom-domain change, bypass-token generation, or deletion, require an explicit ACP or MCP approval even in Full Access; if the connector does not request one, stop and ask the user. A request for a local build or saved version alone never authorizes production deployment.";
 
 fn with_codetwo_browser_routing(prompt: String, enabled: bool) -> String {
     if enabled {

docs/catalog.json

@@ -11,6 +11,7 @@
       "authority": "current",
       "paths": [
         "docs/reference/architecture.md",
+        "docs/reference/desktop-development-profiles.md",
         "docs/design/system.md",
         "docs/reference/memory.md",
         "docs/reference/plugin-protocol.md",

docs/reference/desktop-development-profiles.md

@@ -0,0 +1,72 @@
+# Desktop Development Profile Contract
+
+Follow the [desktop launch rules](../../AGENTS.md#desktop-development-instances) before starting an instance.
+
+## Required profile contract
+
+When implementing or using true multi-instance development, introduce an explicit
+`CODETWO_DEV_PROFILE` and make one profile the complete isolation boundary. Preserve the existing
+single-instance behavior when no profile is supplied.
+
+For every non-default profile, derive or require all of the following:
+
+- a unique absolute `CODETWO_DATA_DIR`, preferably under the current worktree's ignored
+  `.codex/run/instances/<profile>/data` directory;
+- an explicit unique `CODETWO_DEV_PORT` used by Vite with `strictPort: true`;
+- a profile-specific PID/ownership-lock path, Unix socket path, logs, and temporary runtime files;
+- isolated build output when two instances could build concurrently;
+- on macOS, a profile-specific development application name and bundle identifier when two app
+  bundles will run at once, so Dock identity, TCC attribution, app capture, and UI automation do
+  not select the wrong instance.
+
+Validate profile names before using them in paths or identifiers. Accept a small slug alphabet,
+reject traversal and empty values, and show the resolved profile, port, and data directory in the
+startup output.
+
+The intended interface after implementation is:
+
+```bash
+CODETWO_DEV_PROFILE=feature-a CODETWO_DEV_PORT=1421 bun run dev
+CODETWO_DEV_PROFILE=plugin-dev CODETWO_DEV_PORT=1422 bun run dev
+```
+
+Do not present those commands as supported until the launcher, Vite configuration, bundle
+metadata, and ownership checks have actually been implemented and exercised.
+
+## Same-profile ownership
+
+Before opening SQLite, running migrations, normalizing interrupted work, purging transient state,
+or removing/rebinding the scene socket, the native Core must acquire an operating-system-backed
+exclusive lock under the resolved data directory.
+
+- If the lock is held, fail fast with a clear "profile already running" error. Include safe owner
+  diagnostics such as profile, PID, and data directory when available.
+- A PID file alone is not sufficient; PID reuse and stale files must not grant ownership.
+- Normal process exit and crashes must release the OS lock automatically.
+- Startup recovery may mark in-flight work interrupted only after ownership is acquired.
+- Never unlink a live instance's socket before ownership is established.
+
+If shared state across independently hosted Core processes ever becomes a product requirement,
+design that separately as a single Core daemon with multiple clients or as a durable lease and
+fencing protocol. Do not weaken the development-profile lock ad hoc.
+
+## Acceptance criteria
+
+Do not call multi-instance development complete until an automated or agent-runnable harness proves
+all of these behaviors:
+
+1. Profiles A and B start concurrently on different ports and use different databases, sockets,
+   provider child-process groups, and build/runtime directories.
+2. A prompt or permission request in A cannot appear in, cancel, interrupt, or mutate B.
+3. Starting a second process with profile A fails before database mutation, startup recovery, or
+   socket replacement, while the first A process and its active turn continue normally.
+4. After the first A process exits or crashes, A can restart and only its own genuinely abandoned
+   in-flight work is reconciled as interrupted.
+5. Stopping or rebuilding B does not stop, relaunch, or overwrite A.
+6. The default no-profile launch remains backward compatible and does not move or rewrite existing
+   user data unexpectedly.
+7. Port collisions and invalid profiles fail with actionable messages; no launcher silently falls
+   back to another port or shared directory.
+
+For validation, capture the resolved instance identities and assert the exact user-visible symptom,
+not merely that two processes stayed alive.

docs/sdlc/changes/2026-09-02-four-stage-sdlc/verification.md

@@ -18,17 +18,14 @@ release_identity: ""
 
 ## Automated checks
 
-- AC-1: PASS — `bun test script/verify/checks.test.ts` includes schema-3 approval rejection cases.
-- AC-2: PASS — `bun test script/devflow.test.ts` covers approve/design/plan flow.
-- AC-3: PASS — `bun script/verify/docs.ts` passes after `change-stage` catalog classification fix.
-- AC-4: PASS — `docs/sdlc/workflow.md`, `development-workflow.md`, and `artifact-contracts.md` updated.
+- AC-1: PASS — `bun test script/verify/checks.test.ts` includes schema-3 approval rejection cases. `bun test script/verify/checks.test.ts` fixture rejects unaccepted intent upstream.
+- AC-2: PASS — `bun test script/devflow.test.ts` covers approve/design/plan flow. `./script/devflow approve` writes `approved_by` and `approved_at` on approved stages.
+- AC-3: PASS — `bun script/verify/docs.ts` passes after `change-stage` catalog classification fix. `bun script/verify/docs.ts` accepts migrated stage files as `change-stage`.
+- AC-4: PASS — `docs/sdlc/workflow.md`, `development-workflow.md`, and `artifact-contracts.md` updated. [`development-workflow.md`](../../development-workflow.md) documents mandatory approval.
 
 ## Behavioral evidence
 
-- AC-1: PASS — `bun test script/verify/checks.test.ts` fixture rejects unaccepted intent upstream.
-- AC-2: PASS — `./script/devflow approve` writes `approved_by` and `approved_at` on approved stages.
-- AC-3: PASS — `bun script/verify/docs.ts` accepts migrated stage files as `change-stage`.
-- AC-4: PASS — [`development-workflow.md`](../../development-workflow.md) documents mandatory approval.
+The acceptance mappings above retain both the automated and behavioral evidence.
 
 ## Visual evidence
 

docs/sdlc/changes/2026-09-07-astra-scaffold-cleanup/intent.md

@@ -0,0 +1,46 @@
+---
+id: "2026-09-07-astra-scaffold-cleanup"
+stage: intent
+schema: 3
+status: accepted
+owner: codex
+created: "2026-09-07"
+source: "user"
+risk: "low"
+approved_by: "Chen Li"
+approved_at: 2026-09-07
+---
+
+# Intent: Astra Scaffold Cleanup
+
+## Problem
+
+Always-on instructions contain an overbroad Sites trigger, a long development-profile specification, duplicated verification commands, and an ambiguous lifecycle-skill trigger.
+
+## Proposed outcome
+
+Narrow Sites and lifecycle-skill triggers, move the profile contract into a reference document, and remove duplicate handoff checks.
+
+## Affected users and systems
+
+CodeTwo contributors and provider sessions that receive the host Sites instructions.
+
+## Constraints
+
+Preserve Ponytail unchanged, stage approvals, production and sensitive-action approvals, live Core ownership, and all multi-instance acceptance requirements.
+
+## Out of scope
+
+No profile implementation, permission changes, deployment, plugin installation, model-specific prompt forks, or unrelated cleanup.
+
+## Success signals
+
+The four approved edits are present; profile detail and safety clauses are preserved; routing regression and repository Gates pass.
+
+## Open questions
+
+None within the approved audit scope.
+
+## Decision
+
+Chen Li approved the concrete edits from the preceding audit with “除`ponytail` 立即处理” on 2026-09-07. This approval covers the stated outcome, constraints, and surgical implementation plan for findings 2–5.

docs/sdlc/changes/2026-09-07-astra-scaffold-cleanup/plan.md

@@ -0,0 +1,47 @@
+---
+id: "2026-09-07-astra-scaffold-cleanup"
+stage: plan
+schema: 3
+status: accepted
+owner: codex
+created: "2026-09-07"
+based_on: spec.md
+risk: "low"
+scope: AGENTS.md, docs/catalog.json, docs/reference/desktop-development-profiles.md, docs/sdlc/workflow.md, docs/sdlc/development-workflow.md, crates/core/src/engine.rs, docs/sdlc/changes/2026-09-07-astra-scaffold-cleanup
+approved_by: "Chen Li"
+approved_at: 2026-09-07
+---
+
+# Plan: Astra Scaffold Cleanup
+
+## Files and ownership
+
+Codex owns the exact paths in scope: routing sentence, instruction documentation, catalog registration, and this canonical bundle.
+
+## Order of work
+
+Preserve the existing profile-contract text; move it and add the contextual link. Narrow Sites and lifecycle-skill triggers. Align handoff commands and run the targeted routing regression plus lifecycle checks.
+
+## Test-first proof
+
+Use the existing codex_sites_routing_preserves_the_production_boundary regression. Check moved text and retained safety clauses against HEAD; no new tests that merely mirror wording.
+
+## Visual or integration proof
+
+No rendered UI changes. Inspect the emitted prompt policy through the existing routing test; do not claim a live model-selection evaluation.
+
+## Risks and mitigations
+
+Keep safety text verbatim and preserve every isolation criterion. Run the active lifecycle Eval because project instructions change.
+
+## Rollback
+
+Revert only the scoped patch and remove its new reference document and bundle; no application data or external state changes.
+
+## Deviations
+
+None. Ponytail is excluded by the user’s explicit instruction.
+
+## Decision
+
+Chen Li approved this bounded implementation through “除`ponytail` 立即处理” on 2026-09-07 following the file-scoped audit proposals. The follow-up “clean up code/docs” authorizes wording, formatting, and schema terminology cleanup within the same paths. Merge and release are not authorized.