oh-my-opencode 4.12.1 → 4.14.0

package/packages/omo-codex/plugin/components/teammode/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/components/teammode/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/components/teammode/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;
 }
 

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

@@ -0,0 +1,113 @@
+// team-worktree.mjs - git worktree provisioning + merge integration for teammode.
+//
+// Shells out to `git` through node:child_process so the leader never hand-runs worktree or
+// merge commands and never improvises a branch name. Zero npm dependencies, like the rest of
+// the skill. team-state.mjs stays the pure state model; this file owns the git side only.
+
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+// A member id that also names a directory and a branch segment: no "/", no "..", no leading dot.
+const MEMBER_ID_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+// Compare two on-disk paths regardless of OS. realpathSync canonicalizes separators, Windows
+// 8.3 short names (RUNNER~1) and drive-letter case, and the macOS /var -> /private/var symlink -
+// none of which plain resolve() reconciles. Returns false if either side no longer exists.
+function samePath(a, b) {
+	try {
+		return realpathSync(a) === realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+
+function git(cwd, args) {
+	const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+	if (result.error) throw new Error(`git ${args.join(" ")} could not run: ${result.error.message}`);
+	return result;
+}
+
+function gitOrThrow(cwd, args) {
+	const result = git(cwd, args);
+	if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${(result.stderr || result.stdout || "").trim()}`);
+	return result.stdout ?? "";
+}
+
+export function deriveMemberBranch(team, member) {
+	if (member.worktree?.branch) return member.worktree.branch;
+	return `team/${team.sessionId ?? team.teamId}/${member.id}`;
+}
+
+// Confine a member worktree to <worktree.root>/<member id>; reject any id that would escape it.
+export function memberWorktreePath(team, member) {
+	if (!MEMBER_ID_SEGMENT.test(member.id ?? "")) throw new Error(`unsafe member id for a worktree path: "${member.id}"`);
+	const root = team.worktree?.root;
+	if (!root) throw new Error("team has no worktree root; re-init the team");
+	const path = join(root, member.id);
+	const rel = relative(root, path);
+	if (rel !== member.id || rel.startsWith("..") || isAbsolute(rel)) throw new Error(`refused: worktree path escapes ${root}`);
+	return path;
+}
+
+export function listWorktrees(cwd) {
+	const out = gitOrThrow(cwd, ["worktree", "list", "--porcelain"]);
+	const worktrees = [];
+	let current = null;
+	for (const line of out.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			current = { path: line.slice("worktree ".length) };
+			worktrees.push(current);
+		} else if (line.startsWith("branch ") && current) {
+			current.branch = line.slice("branch ".length);
+		}
+	}
+	return worktrees;
+}
+
+function branchExists(cwd, branch) {
+	return git(cwd, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).status === 0;
+}
+
+function currentBranch(cwd) {
+	return gitOrThrow(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+}
+
+export function addMemberWorktree(cwd, team, member, { baseBranch } = {}) {
+	const base = baseBranch || team.worktree?.baseBranch || "dev";
+	const branch = deriveMemberBranch(team, member);
+	const path = memberWorktreePath(team, member);
+	// Idempotent: skip if a worktree is already checked out on this member's branch (matched on the
+	// branch ref, which is OS-agnostic) or already lives at this path (matched on realpath, so a
+	// Windows 8.3 git path vs an 8.3-or-long script path still compares equal). Plain string/resolve
+	// comparison missed the 8.3-vs-canonical case and re-`git worktree add`-ed into a fatal error.
+	if (listWorktrees(cwd).some((w) => w.branch === `refs/heads/${branch}` || samePath(resolve(cwd, w.path), resolve(cwd, path)))) {
+		return { path, branch, base, created: false };
+	}
+	const add = branchExists(cwd, branch)
+		? ["worktree", "add", path, branch]
+		: ["worktree", "add", "-b", branch, path, base];
+	gitOrThrow(cwd, add);
+	return { path, branch, base, created: true };
+}
+
+export function removeMemberWorktree(cwd, team, member, { force = false } = {}) {
+	const path = memberWorktreePath(team, member);
+	gitOrThrow(cwd, ["worktree", "remove", ...(force ? ["--force"] : []), path]);
+	return { path };
+}
+
+// Land a member branch with a MERGE COMMIT (--no-ff). Never squash, never rebase (repo policy).
+// On conflict the working tree is left mid-merge so the leader can resolve and re-run.
+export function integrateMemberBranch(cwd, branch) {
+	const result = git(cwd, ["merge", "--no-ff", "--no-edit", branch]);
+	if (result.status === 0) return { branch, merged: true, into: currentBranch(cwd) };
+	const conflicts = gitOrThrow(cwd, ["diff", "--name-only", "--diff-filter=U"]).trim();
+	return {
+		branch,
+		merged: false,
+		into: currentBranch(cwd),
+		conflicts: conflicts ? conflicts.split("\n") : [],
+		message: (result.stderr || result.stdout || "").trim(),
+	};
+}