oh-my-opencode 4.12.1 → 4.14.0

package/packages/omo-codex/plugin/skills/lcx-doctor/SKILL.md

@@ -39,7 +39,7 @@ sync_latest_source openai/codex /tmp/openai-codex-source
    - `$CODEX_HOME/config.toml` exists and parses; LazyCodex-managed entries match what the latest installer would write.
    - Plugin payload present and non-empty: `hooks/hooks.json`, `skills/`, `.mcp.json`, components under the installed plugin root.
    - Stale project-local leftovers the installer now removes (e.g. `.codex/hooks.json`, `.codex/skills` in the project) are flagged, not deleted.
-4. Probe the real surface. Run the built-in diagnostics first: `lazycodex doctor --json` (add `--verbose` when a check needs deeper traces) and fold its results into the report. A missing or crashing `lazycodex doctor` is itself a FAIL finding, not a reason to skip probing — fall back to `codex --version` plus a trivial non-interactive invocation that loads the plugin. Capture stderr verbatim; a clean exit with warnings is WARN, not PASS.
+4. Probe the real surface. Do not invoke `lazycodex doctor`; this skill is already running inside that doctor workflow, so calling it would recurse. Instead run non-recursive probes directly: `codex --version`, `command -v codex`, the bin-link checks above, config/plugin payload inspections, and a trivial non-interactive Codex invocation that loads the plugin. Capture stderr verbatim; a clean exit with warnings is WARN, not PASS.
 5. Compare for drift. Where installed bundled files differ from the same files at the installed version, or the latest source renamed or removed something the local config still references, record it with both paths.
 6. Check whether each FAIL is already known: `gh issue list --repo code-yeongyu/lazycodex --search "<short symptom>" --state open` (and `openai/codex` when the failure points upstream). Link matches in the report instead of re-diagnosing from scratch.
 7. If a probe fails and the cause is not explained by config or source comparison, invoke `$omo:debugging` for the investigation. If Codex exposes only unqualified skill names in the current session, invoke `$debugging` and state that it is the OMO debugging skill.

package/packages/omo-codex/plugin/skills/refactor/SKILL.md

@@ -19,6 +19,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command

package/packages/omo-codex/plugin/skills/remove-ai-slops/SKILL.md

@@ -19,6 +19,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # Remove AI Slops Skill

package/packages/omo-codex/plugin/skills/review-work/SKILL.md

@@ -18,6 +18,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## Codex Subagent Reliability
@@ -58,7 +62,11 @@ gate, it is blocking. A timeout, missing deliverable, ack-only response,
 explicit `BLOCKED:`, or inconclusive lane is not a pass. Treat that lane as
 failed, investigate the underlying uncertainty with the `debugging` skill when
 runtime behavior may be wrong, fix with evidence, and rerun the affected lane
-before claiming completion or handing off a PR.
+before claiming completion, creating or handing off a PR, or merging.
+
+When reviewing a PR or branch, collect diff, file contents, and verification
+results from a dedicated review worktree attached to that branch. Never
+checkout, test, or edit the review branch in the main worktree.
 
 Review evidence must be safe to share. Redact or mask secrets and sensitive
 user data before including evidence in logs, PR bodies, or handoffs. Never
@@ -95,7 +103,7 @@ Before launching agents, collect these inputs. Extract from conversation history
 </required_inputs>
 
 
-**NEVER CHECKOUT A PR BRANCH IN THE MAIN WORKTREE. ALWAYS CREATE A NEW GIT WORKTREE (`git worktree add`) AND WORK THERE. THIS PREVENTS CONTAMINATING THE USER'S WORKING DIRECTORY WITH UNRELATED BRANCH STATE.**
+Review PRs and branches from a dedicated review worktree only: create or attach one with `git worktree add <path> <branch>` before collecting changed files, diff, file contents, or running checks. The main worktree is read-only context; never checkout, test, or edit the review branch there.
 
 **Auto-collection sequence:**
 
@@ -213,7 +221,7 @@ The QA agent follows a structured process: brainstorm scenarios exhaustively fir
 task(
   category="unspecified-high",
   run_in_background=true,
-  load_skills=["playwright", "dev-browser"],
+  load_skills=["browser:control-in-app-browser", "playwright", "dev-browser"],
   description="QA by actually running and using the application",
   prompt="""
 <review_type>QA - HANDS-ON APP EXECUTION</review_type>
@@ -281,7 +289,7 @@ Work through the task list in priority order (P0 first). For each test:
 6. Mark the task complete
 
 **Execution guidance by app type:**
-- **Web app**: Use playwright/dev-browser to navigate, click, fill forms, verify visual output.
+- **Web app**: In Codex, use `browser:control-in-app-browser` first for browser work that does not need an authenticated user session. Fall back to playwright/dev-browser when the Browser plugin is unavailable, lacks the needed action, or the test specifically needs a persistent/authenticated browser profile. Navigate, click, fill forms, and verify visual output through the chosen browser surface.
 - **CLI tool**: Run commands with various arguments, pipe inputs, check exit codes and output.
 - **Library/SDK**: Write and execute a test script that imports and exercises the public API.
 - **Backend API**: Use curl/httpie to hit endpoints with various payloads, verify response codes and bodies.

package/packages/omo-codex/plugin/skills/start-work/SKILL.md

@@ -19,6 +19,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## ABSOLUTE RULE: YOU ARE AN ORCHESTRATOR — NEVER THE IMPLEMENTER
@@ -42,7 +46,7 @@ $start-work [plan-name] [--worktree <absolute-path>]
 ```
 
 - `plan-name` (optional): a full or partial file stem under `.omo/plans/`.
-- `--worktree` (optional): only when the user explicitly asks for a separate git worktree.
+- `--worktree` (required for PR/branch work; otherwise optional): the task-owned git worktree path.
 
 ## Phase 1: Select the plan
 
@@ -85,7 +89,7 @@ Write `.omo/boulder.json` before implementation starts. Prefix session ids with
 }
 ```
 
-If `--worktree` is set, verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
+For PR/branch work, `--worktree` is mandatory before implementation starts. Verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
 
 ## Phase 3: Execute the next checkbox
 
@@ -102,11 +106,12 @@ Each sub-task message must include:
 2. When the task touches existing behavior: a baseline characterization test, written first, that pins current observable behavior and passes on the unchanged code (exact inputs, exact observable, exact assertion). Then the failing-first proof for the new behavior before production changes — a unit test where a seam exists, otherwise the sub-task's Manual-QA scenario captured failing. A test that mirrors its implementation (mock-call assertions, pinned constants) is not evidence.
 3. Implementation constraints from the plan and project rules.
 4. Automated verification commands to run.
-5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
+5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
    - HTTP call: `curl -i` against the live endpoint.
    - tmux: a `tmux` session driven with `send-keys`, dumped via `capture-pane`.
-   - Browser use: drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
+   - Browser use: in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
    - Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
+   - TUI visual evidence: when a tmux/TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --from-file <capture.txt> --evidence-dir <dir>` and attach `terminal.png` plus `metadata.json`.
 6. The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
 7. Required artifact path and cleanup receipt.
 
@@ -168,13 +173,13 @@ Only after verification passes:
 When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are complete:
 
 1. Run the plan's final verification commands.
-2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR creation, PR handoff, branch handoff, or merge:
    - Invoke the `review-work` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, `BLOCKED:`, or inconclusive lane is a gate failure, not approval.
    - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to `.omo/start-work/ledger.jsonl`.
    - If any review lane or debugging hypothesis fails, invoke the `debugging` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
    - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing `.omo/start-work/ledger.jsonl`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
-   - If the work includes creating, updating, or handing off a PR, refresh `git status` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
-3. If worktree mode was used, sync `.omo/` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+   - If the work includes creating, updating, or handing off a PR, refresh `git status` and the PR/branch state from the task-owned worktree after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. Finish the PR/branch lifecycle from its task-owned worktree: sync `.omo/` state back to the main repo, create or update the PR when requested, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 4. Remove or mark the Boulder work as completed.
 5. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.
 
@@ -185,6 +190,7 @@ When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are
 - No tests-only completion claim. A Manual-QA artifact is required.
 - **NO DIRECT IMPLEMENTATION BY THE ORCHESTRATOR.** Root NEVER edits product files, writes tests, or runs QA itself — a spawned worker does.
 - No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.
-- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.
+- No `ORCHESTRATION COMPLETE`, final response, PR creation, PR handoff, or merge before the Global Review and Debugging Gate passes with recorded evidence.
+- No PR/branch implementation or review in the main worktree; create or use a task-owned git worktree first.
 - No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.
 - No stale-memory execution. The plan and ledger are the durable source of truth.

package/packages/omo-codex/plugin/skills/teammode/SKILL.md

@@ -26,11 +26,15 @@ Use plain subagents (`$ulw` / `multi_agent_v1.spawn_agent`) - NOT a team - when
 A team buys cross-member coordination at a real overhead cost; only spend it when coordination
 is the thing you actually need.
 
-## You are the leader
+## You are the leader - orchestrate, do not implement
 
-The main session is ALWAYS the team leader. Do NOT create a separate leader thread - you
-orchestrate directly. Members are the threads you create; they report to you, and you own the
-final synthesis and any integration.
+The main session is ALWAYS the team leader; you orchestrate directly and never spin up a separate
+leader thread. Your job is orchestration, NOT writing product code: split the work and assign each
+slice, hold live situational awareness of every member, verify and QA what they deliver, relay
+findings between members, instruct and unblock, and synthesize the result. DELEGATE every code edit
+to a member - if you catch yourself editing product files while the team runs, that work was a
+member's slice you should have handed off. You own direction, verification, and integration (the
+merge), not the keystrokes.
 
 ## Compose by part, ownership, or perspective - not by job title
 
@@ -45,6 +49,9 @@ member by a concrete slice: a specific part of the codebase, an ownership area,
 perspective/lens. Assigning a vague role ("backend dev", "release analyst", "the tester") is an
 anti-pattern - it gives the member no real boundary and invites overlap. Each member's `focus`
 names what they own concretely; the `lens` is one of `area`, `ownership`, or `perspective`.
+Give each member a short, distinct `--name` too - its role or what it watches (e.g.
+`app-server-lifecycle`, `mailbox-delivery`) - because that name titles its thread; never reuse
+one name for two members.
 
 ## Run the script - never hand-write team state
 
@@ -54,10 +61,13 @@ Replace `<skill-root>` with this skill's own directory.
 
 ```
 node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<session>" [--session <leader_session_id>] [--worktree] [--base-branch dev]
-node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
+node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
 node "<skill-root>/scripts/team.mjs" bind-thread  --team <session_id> --id A --thread <thread_id> [--cwd <path>]
 node "<skill-root>/scripts/team.mjs" member-prompt --team <session_id> --id A
 node "<skill-root>/scripts/team.mjs" set-status   --team <session_id> --id A --status reported|blocked|active|archived [--note "<...>"]
+node "<skill-root>/scripts/team.mjs" worktree-add    --team <session_id> --id A [--base-branch <branch>]
+node "<skill-root>/scripts/team.mjs" worktree-remove --team <session_id> --id A [--force]
+node "<skill-root>/scripts/team.mjs" integrate       --team <session_id> [--id A]
 node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A]
 node "<skill-root>/scripts/team.mjs" delete       --team <session_id> [--force]
 node "<skill-root>/scripts/team.mjs" status       --team <session_id>
@@ -74,20 +84,28 @@ subcommand rewrites `guide.md`, so the manual always matches the current team.
 
 1. `init` the team, then `add-member` once per member.
 2. Create a durable thread per member with `codex_app.create_thread` - ALWAYS this tool for every
-   member, never a spawned agent - titled EXACTLY
-   `[team name] {session name}` (keep this convention strictly). If `codex_app.create_thread`
-   accepts a working directory / cwd argument, set it to that member's worktree; otherwise the
-   member's manual tells it to `cd` there first. Use `codex_app.set_thread_title` if the title
-   did not land at creation.
+   member, never a spawned agent - titled `[team name] <member name>`, using THAT member's own
+   name (its role / what it watches), so no two threads share a title. `add-member` prints the
+   exact title to use. If `codex_app.create_thread` accepts a working directory / cwd argument,
+   set it to that member's worktree; otherwise the member's manual tells it to `cd` there first.
+   Use `codex_app.set_thread_title` if the title did not land at creation.
+   If Codex returns only `pendingWorktreeId`, the worktree-backed thread is not ready yet: do not
+   `bind-thread` and do not send the member bootstrap. Wait until Codex surfaces a real `threadId`
+   or the thread appears in the thread list, then set the title, bind that real id with the cwd,
+   and only then send the bootstrap.
 3. `bind-thread` to record each thread id (and `--cwd`), then send that member's bootstrap
    trigger (printed by `add-member` / `member-prompt`) as the thread's first message. The trigger
    is short on purpose: it tells the new thread to READ its `guide.md` and `team.json` rather than
    carrying the whole protocol inline.
+4. Whenever you report, audit, reopen, or hand off a member thread, include the app deep link
+   `codex://threads/<thread_id>` next to the raw id. For example:
+   `codex://threads/019ef350-ee78-72a3-bd5e-e40cebc3d814`. Worktree-backed threads are easy to
+   lose in the sidebar without this link.
 
 Every team member is a real Codex thread created with `codex_app.create_thread` - this is strict,
 not a preference. NEVER substitute `multi_agent_v1.spawn_agent`, or any other in-process subagent,
 for a team member: a spawned agent is an ephemeral helper that does not show up as a team thread,
-cannot carry the `[team name] {session name}` title, and cannot be inspected, titled, archived, or
+cannot carry the `[team name] <member name>` title, and cannot be inspected, titled, archived, or
 re-opened with the `codex_app.*` thread tools - which defeats the entire point of a durable team.
 A member only counts once you have `bind-thread`-ed it to a real `codex_app.create_thread` thread
 id. If the thread-creation tool is unavailable, STOP and say so (see Stop rules); do not quietly
@@ -95,24 +113,71 @@ fall back to a spawned agent.
 
 ## Communication
 
-Coordinate with `codex_app.send_message_to_thread` (leader-to-member and peer digests) and inspect
-status with `codex_app.read_thread`. The generated manual already binds members to the hard rules,
-so you mostly enforce them: all member-to-member and member-to-leader communication is in English;
-when the END user addresses a member, that member replies in the user's own language. Members
-over-communicate relentlessly - constant, small, lean updates that report every finding, hand-off,
-and even the smallest or most trivial step as it happens rather than one final dump - and send
-`WORKING:`/`BLOCKED:` markers so the leader always knows their state; stale, stuck, or
-silently-blocked members are not acceptable, and a finished
-member reports to the leader immediately. Members hand off files and
-memos through the team `artifacts/` directory and reference them by path instead of pasting large
-content. Wait for every required member's final report before you declare the team done.
-
-## Worktrees (optional isolation)
-
-When parallel members would edit overlapping files, enable isolation with `init --worktree`. Create
-one git worktree per member off the base branch, `bind-thread --cwd <worktree>` so each member's
-worktree is recorded in `team.json`, and rely on the manual to direct each member into its own
-worktree. Each member commits inside its worktree so you can integrate.
+Members push to you and to one another with `codex_app.send_message_to_thread`; you inspect their
+state with `codex_app.read_thread`. So members can actually reach you, run `init` with
+`--session <your own thread id>` - that makes `leader.sessionId` in team.json a real, messageable
+thread; without it members cannot report to you and you are stuck polling. The generated manual binds
+members to the hard rules, so you mainly keep the channel open: expect frequent small inbound updates
+from each member - findings, `WORKING:`/`BLOCKED:` markers, peer digests - rather than one final
+dump, and act on them as they arrive. All member-to-member and member-to-leader traffic is in English;
+when the END user addresses a member, that member replies in the user's own language. Members hand off
+files and memos through the team `artifacts/` directory and reference them by path.
+
+## Let members work - do not rush them
+
+Members heartbeat every few tool calls and message you on every finding, blocker, and finished
+slice (their manual binds them to this). So a member that is quiet between heartbeats is **working,
+not stalled** - a stretch of silence is the normal sound of focused work, not a problem to chase.
+Re-reading `codex_app.read_thread` to check on a calm member, or sending "any update?" / "are you
+done?" / "hurry up" pings, interrupts that member and slows the whole team. Trust the heartbeat and
+let them cook.
+
+Message a member only when one of these is true:
+- you have new information, context, or a correction it needs to do its slice right;
+- you are reassigning, narrowing, or unblocking its scope;
+- a peer's result changes what it should do; or
+- it has gone fully silent well past its heartbeat cadence AND that stall is blocking the team -
+  then send one specific question, not a barrage.
+
+Otherwise stay calm and keep the channel open: read inbound updates as they arrive and act on them.
+A long-running member is alive; a heartbeat you have not received yet is not a failure. Wait for
+every required member's final report before you declare the team done - rushing toward "done" while
+members are still mid-slice just produces half-built work you will have to redo.
+
+## Worktrees - isolate members who would touch the same files
+
+The moment two members' slices would edit the same files, give each its own git worktree so they
+cannot clobber each other. Decide this whenever you see the collision - at team creation OR mid-run,
+not only up front. For each colliding member run `worktree-add --team <id> --id <member>`: it creates
+the worktree off the base branch on a derived branch, flips the team into worktree mode, records it in
+`team.json`, and prints the `cd` path to hand that member. The member works and commits only inside
+its own worktree. To land the work, `integrate --team <id>` merges every member branch into your
+current branch with a merge commit (never a squash or rebase); resolve any conflict it reports, then
+`worktree-remove` each worktree at cleanup.
+
+After `worktree-add`, immediately send the member a follow-up that includes both its assigned
+worktree path and its `codex://threads/<thread_id>` link. Use `bind-thread --cwd <worktree>` or
+`--worktree-path <worktree>` after the thread exists so `team.json`, `guide.md`, `status`, and
+`member-prompt` all point at the same worktree-backed thread.
+
+When the member starts inside a worktree, it must verify the assigned cwd exists and contains the
+repository checkout before editing. If the directory is missing, empty, or does not look like a git
+worktree/repository yet, the member reports `BLOCKED: worktree not ready` to the leader and waits
+instead of editing a parent checkout or an empty directory.
+
+## Run a ulw-plan in parallel
+
+When a decision-complete plan already exists at `.omo/plans/<slug>.md` (from ulw-plan), execute its
+parallel waves as a team instead of one todo at a time. Map it directly:
+- one wave's independent todos -> one member each; the todo's scope/files become that member's `focus`,
+  and its acceptance criteria + QA become the member's `deliverable`.
+- the plan's dependency matrix sets the shape: todos with no unmet dependency inside a wave run as
+  concurrent members; a todo that depends on another waits, so launch the next wave only after the
+  blocking members report.
+- todos in the same wave that touch overlapping files -> give those members worktrees (see above).
+
+Keep the plan file as the shared spec: point each member at its todo by path, and verify the member's
+result against that todo's acceptance criteria before you integrate.
 
 ## Archive, delete, and cleanup
 
@@ -126,9 +191,9 @@ then delete the team state. A finished team that is never disbanded is a leak.
   and tell the user - never pretend a member was archived.
 - `delete` removes `.omo/teams/{session_id}` and refuses while the team is unarchived or any member
   is still active unless `--force`.
-- When the work wraps up, integrate each member's worktree the way the user asked - merge directly,
-  or open a fresh PR and merge it - then archive and delete. Cleanup is real work; respect the
-  user's instruction on how to land it.
+- When the work wraps up, land it the way the user asked: `integrate --team <id>` for a direct merge
+  commit, or push each member branch and open a PR. Then `worktree-remove` each worktree, archive, and
+  delete. Cleanup is real work; respect the user's instruction on how to land it.
 
 ## Stop rules
 

package/packages/omo-codex/plugin/skills/teammode/scripts/team-guide.mjs

@@ -5,10 +5,16 @@
 // writes it once at team creation, and every member thread is told to READ it instead of
 // receiving the rules inline each turn.
 
+export function codexThreadLink(threadId) {
+	return `codex://threads/${threadId}`;
+}
+
 function memberLine(member) {
-	const thread = member.threadId ? ` | thread ${member.threadId}` : " | thread not created yet";
+	const thread = member.threadId ? ` | thread ${member.threadId} (${codexThreadLink(member.threadId)})` : " | thread not created yet";
 	const wt = member.worktree?.path ? ` | worktree ${member.worktree.path}` : "";
-	return `- **${member.id}** (${member.lens}) - ${member.focus}${member.deliverable ? ` -> ${member.deliverable}` : ""}${thread}${wt} [${member.status}]`;
+	const name = member.name ? ` "${member.name}"` : "";
+	const title = member.threadTitle ? ` | thread title \`${member.threadTitle}\`` : "";
+	return `- **${member.id}**${name} (${member.lens}) - ${member.focus}${member.deliverable ? ` -> ${member.deliverable}` : ""}${title}${thread}${wt} [${member.status}]`;
 }
 
 function worktreeSection(team) {
@@ -21,13 +27,23 @@ that is a coordination signal: mark yourself \`blocked\` and tell the leader at
 	}
 	const lines = team.members
 		.filter((m) => m.worktree?.path || m.worktree?.branch)
-		.map((m) => `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\``);
+		.map((m) => {
+			const thread = m.threadId ? `; thread ${codexThreadLink(m.threadId)}` : "";
+			return `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\`${thread}`;
+		});
 	return `## Worktrees (ISOLATION IS ON - this is not optional for you)
 
 This team runs each member in its own git worktree branched off \`${team.worktree.baseBranch}\`.
 **You MUST work only inside your own worktree.** The very first thing you do is \`cd\` into it;
 every edit, command, and commit happens there. Never touch another member's worktree, and
 never edit files outside your assigned scope. Commit your work so the leader can integrate it.
+Before editing, verify that your assigned worktree exists and contains repo files. If the path is
+missing, empty, or does not look like a git worktree/repository yet, send \`BLOCKED: worktree not ready\`
+to the leader and wait instead of editing any parent checkout or empty directory.
+
+If Codex returns only \`pendingWorktreeId\` while the leader is creating a worktree-backed member
+thread, the thread is not ready yet. The leader must wait until Codex surfaces a real thread id,
+then bind that real id and send the bootstrap.
 
 ${lines.length ? lines.join("\n") : "- (worktree paths are assigned as threads are bound; read team.json for yours)"}`;
 }
@@ -43,7 +59,7 @@ export function buildGuide(team) {
 
 - Team: **${team.teamName}** (id \`${team.teamId}\`)
 - Team state: \`${teamJson}\`
-- Thread/session title convention (use it EXACTLY): \`${team.threadTitleConvention}\`
+- Thread title convention: \`${team.threadTitleConvention}\` - each member's thread takes its OWN title from its name (your row below shows yours); two members never share a title
 
 ## Who you are (your identity is fixed)
 
@@ -66,18 +82,21 @@ coordinate with each other, but the leader owns the final decision and integrati
   is mandatory regardless of the language the task was given in.
 - **Exception: when the END USER addresses you directly, reply in the user's own language.**
   Team-internal traffic stays English; user-facing replies match the user.
-- **Report to the leader the moment your work is complete.** A finished task that was never
-  reported does not count as done.
-- **Over-communicate relentlessly - report even the trivial.** Message constantly and
-  proactively: every finding, decision, hand-off, and even the smallest or most trivial step, the
-  moment it happens, in short lean notes. Never save it up for one final report. When in doubt,
-  send the message - far more and far smaller updates always beats going quiet. The instant
-  anything changes a peer's assumption, push it to them. Too many messages is correct here; the
-  only failure is going quiet.
-- **Stale, stuck, and silently-blocked states are NOT acceptable.** During long work send
-  \`WORKING: <your focus> - <phase>\` so the leader can see you are alive. If you truly cannot
-  proceed, send \`BLOCKED: <reason>\` immediately and propose the smallest unblock - never sit
-  idle and never disappear. Being quiet is a failure, not a pause.
+- **Reach the leader and your peers with \`codex_app.send_message_to_thread\` - not by narrating in
+  your own thread, where no one reads it.** The address book is in team.json: the leader thread id
+  is \`leader.sessionId\`, and each peer thread id is its \`members[].threadId\`.
+- **When you mention a Codex thread, include its app link too:** \`codex://threads/<threadId>\`.
+  These links are the fastest way for the leader to reopen worktree-backed member threads.
+- **Push a short message at each of these moments - never batch them into one report at the end:**
+  - to the **leader**: every finding or decision, every file or sub-task you finish, a
+    \`WORKING: <focus> - <phase>\` heartbeat every few tool calls so you never look stale, a
+    \`BLOCKED: <reason>\` the instant you cannot proceed, and your result the moment your slice is done.
+  - to a **peer**: the instant you learn anything that touches their slice - a shared finding, a
+    changed assumption, an interface they depend on. When unsure who owns it, send it to the leader.
+- **Going quiet is the only failure.** Many small lean messages beat one end-of-work dump; keep
+  every message short. Your heartbeats are what let the leader relax and leave you to work: a leader
+  who can see your progress has no reason to interrupt you, while silence forces it to break in and
+  ask where things stand. Frequent lean updates buy you uninterrupted focus.
 
 ## Artifacts (how you hand work off)
 
@@ -102,10 +121,19 @@ export function buildMemberPrompt(team, id) {
 	if (!member) throw new Error(`no member with id "${id}"`);
 	const guide = team.paths?.guide ?? ".omo/teams/<session_id>/guide.md";
 	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
-	const where = member.cwd ? `Work inside \`${member.cwd}\`.` : "Work from the repository root unless your manual assigns a worktree.";
-	return `You are member ${member.id} of team ${team.teamName} - owner of: ${member.focus}.
+	const where = member.cwd
+		? `Work inside \`${member.cwd}\`.`
+		: team.worktree?.enabled
+			? "Wait for the leader to bind your worktree cwd before editing."
+			: "Work from the repository root unless your manual assigns a worktree.";
+	const threadLink = member.threadId ? `\nYour Codex thread link is ${codexThreadLink(member.threadId)}. Include it when reporting handoffs or worktree status.` : "";
+	const readiness =
+		team.worktree?.enabled
+			? "\nBefore editing, verify that your assigned worktree exists and contains repo files. If this prompt arrived before your Codex worktree checkout is ready, or the path is missing, empty, or not a git worktree/repository yet, report `BLOCKED: worktree not ready` to the leader and wait."
+			: "";
+	return `You are member ${member.id}${member.name ? ` (${member.name})` : ""} of team ${team.teamName} - owner of: ${member.focus}. Your thread title is \`${member.threadTitle}\`.
 FIRST read your field manual at \`${guide}\`, then the team state at \`${teamJson}\`; they define your scope, deliverable, the leader, the artifacts directory, and the communication rules.
-${where}
+${where}${threadLink}${readiness}
 Communicate with the team and leader in English; reply to the end user in the user's own language.
-Start now, send WORKING/BLOCKED updates so you never look stale, and report to the leader the moment you are done.`;
+Start now. Push updates to the leader and relevant peers with \`codex_app.send_message_to_thread\` as you work - findings, \`WORKING:\` heartbeats, and \`BLOCKED:\` the instant you stall - never just one report at the end.`;
 }

package/packages/omo-codex/plugin/skills/teammode/scripts/team-state.mjs

@@ -39,7 +39,7 @@ export function buildTeam({ teamName, sessionName, sessionId = null, dir = null,
 		teamName: teamName.trim(),
 		sessionName: sessionName.trim(),
 		sessionId,
-		threadTitleConvention: `[${teamName.trim()}] ${sessionName.trim()}`,
+		threadTitleConvention: `[${teamName.trim()}] <member name>`,
 		status: "active",
 		createdAt: ts,
 		updatedAt: ts,
@@ -72,6 +72,14 @@ function normalizedFocus(focus) {
 	return focus.trim().replace(/\s+/g, " ").toLowerCase();
 }
 
+function normalizedMemberName(name) {
+	return name.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function normalizedThreadTitle(title) {
+	return title.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
 function assertUniqueMemberFocus(team) {
 	const seen = new Map();
 	for (const member of team.members) {
@@ -84,6 +92,35 @@ function assertUniqueMemberFocus(team) {
 	}
 }
 
+function assertUniqueMemberName(team) {
+	const seen = new Map();
+	for (const member of team.members) {
+		const memberName = member.name ?? member.focus ?? "";
+		const key = normalizedMemberName(memberName);
+		const previous = seen.get(key);
+		if (previous) {
+			throw new Error(`member name "${memberName}" duplicates "${previous.name ?? previous.focus}" (no two members may produce the same thread title)`);
+		}
+		seen.set(key, member);
+	}
+}
+
+function assertUniqueMemberThreadTitle(team) {
+	const seen = new Map();
+	for (const member of team.members) {
+		const threadTitle = member.threadTitle;
+		if (typeof threadTitle !== "string" || !threadTitle.trim()) {
+			throw new Error(`member "${member.id ?? member.name ?? member.focus ?? "(unknown)"}" has invalid threadTitle (non-empty string required)`);
+		}
+		const key = normalizedThreadTitle(threadTitle);
+		const previous = seen.get(key);
+		if (previous) {
+			throw new Error(`member threadTitle "${threadTitle}" duplicates "${previous.threadTitle}" (no two members may produce the same thread title)`);
+		}
+		seen.set(key, member);
+	}
+}
+
 function assertTeamReadyForThreadBinding(team) {
 	if (isUnderstaffed(team)) {
 		throw new Error(
@@ -91,24 +128,34 @@ function assertTeamReadyForThreadBinding(team) {
 		);
 	}
 	assertUniqueMemberFocus(team);
+	assertUniqueMemberName(team);
+	assertUniqueMemberThreadTitle(team);
 }
 
-export function addMember(team, { id, focus, lens, deliverable = "", branch = null }) {
+export function addMember(team, { id, focus, lens, deliverable = "", branch = null, name = null }) {
 	if (!id?.trim()) throw new Error("member id is required");
 	if (!focus?.trim()) throw new Error("member focus is required - a concrete part, ownership area, or perspective");
 	if (!LENSES.includes(lens)) throw new Error(`invalid lens "${lens}" - use one of: ${LENSES.join(", ")}`);
 	const memberId = id.trim();
 	const memberFocus = focus.trim();
+	// The member name is the short role label that titles this member's thread. Fall back to the
+	// focus so the title is ALWAYS per-member and never the shared team-wide session name.
+	const memberName = name?.trim() || memberFocus;
 	if (team.members.some((m) => m.id === memberId)) throw new Error(`member id "${memberId}" already exists (duplicate)`);
 	const duplicate = team.members.find((m) => normalizedFocus(m.focus) === normalizedFocus(memberFocus));
 	if (duplicate) throw new Error(`member focus "${memberFocus}" duplicates "${duplicate.focus}" (no two members may own the same thing)`);
+	const duplicateName = team.members.find((m) => normalizedMemberName(m.name ?? m.focus ?? "") === normalizedMemberName(memberName));
+	if (duplicateName) {
+		throw new Error(`member name "${memberName}" duplicates "${duplicateName.name ?? duplicateName.focus}" (no two members may produce the same thread title)`);
+	}
 	team.members.push({
 		id: memberId,
+		name: memberName,
 		focus: memberFocus,
 		lens,
 		deliverable: deliverable.trim(),
 		threadId: null,
-		threadTitle: team.threadTitleConvention,
+		threadTitle: `[${team.teamName}] ${memberName}`,
 		cwd: null,
 		worktree: { path: null, branch: branch ?? null },
 		status: "pending",
@@ -133,6 +180,24 @@ export function setMemberStatus(team, { id, status, note = "" }) {
 	return touch(team, "set-status", `member ${id} -> ${status}${note ? `: ${note}` : ""}`);
 }
 
+// Record a provisioned worktree. Isolation is conflict-triggered: the first worktree-add flips
+// the whole team into worktree mode, so the leader can decide it mid-run, not only at init.
+export function setMemberWorktree(team, { id, path, branch }) {
+	const m = memberById(team, id);
+	team.worktree.enabled = true;
+	m.worktree.path = path;
+	m.worktree.branch = branch;
+	m.cwd = path;
+	return touch(team, "worktree-add", `member ${id} -> ${path} (${branch})`);
+}
+
+export function clearMemberWorktree(team, { id }) {
+	const m = memberById(team, id);
+	if (m.cwd === m.worktree?.path) m.cwd = null;
+	m.worktree.path = null;
+	return touch(team, "worktree-remove", `member ${id}`);
+}
+
 export function archive(team, { id = null, note = "" } = {}) {
 	if (id) {
 		memberById(team, id).status = "archived";
@@ -150,6 +215,8 @@ export function validateTeam(team) {
 	if (team.leader?.kind !== "main-session") throw new Error("invalid team: leader.kind must be main-session");
 	if (!Array.isArray(team.members)) throw new Error("invalid team: members must be an array");
 	assertUniqueMemberFocus(team);
+	assertUniqueMemberName(team);
+	assertUniqueMemberThreadTitle(team);
 	return team;
 }