oh-my-opencode 4.11.1 → 4.12.1

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

@@ -0,0 +1,139 @@
+---
+name: teammode
+description: "Codex-only team orchestration: run a named team of cooperating Codex threads with durable, script-managed state. MUST USE when the user asks Codex to create, run, coordinate, inspect, archive, or delete a team of threads/sessions, or to work on something as a team in parallel. The main session is always the leader; members are defined by a concrete part, ownership area, or perspective - never a vague job role; a bundled cross-platform script writes the .omo/teams state plus an auto-generated member field manual. Use a team when the work is not perfectly isolated but parallelizing helps, or when a task still needs exploration under a clear goal; use plain subagents when scope is perfectly isolated or the goal is ambiguous. Triggers: team mode, teammode, make a team, run as a team, team of agents, coordinate threads, parallel Codex threads, archive the team, delete the team."
+---
+
+# Teammode
+
+Run a named team of cooperating Codex threads under one leader, with durable state on disk.
+This is a Codex-only workflow. It is inspired by the lifecycle concerns in the
+Yeachan-Heo/oh-my-codex team skill, but it does not copy that runtime model and never depends
+on an external terminal runner - it coordinates through Codex's own thread tools plus a bundled
+state script.
+
+## When to use a team (and when to use plain subagents instead)
+
+Use a TEAM when EITHER holds:
+- the work does NOT split into perfectly isolated pieces, but doing it in parallel is clearly
+  more convenient - members will need to see and react to each other's findings; or
+- one task still needs exploration, yet its GOAL is already clear - parallel investigation under
+  a fixed objective.
+
+Use plain subagents (`$ulw` / `multi_agent_v1.spawn_agent`) - NOT a team - when EITHER holds:
+- the work IS perfectly isolated, so there is no coordination cost worth paying; or
+- the GOAL is still ambiguous, where one mind should resolve direction before any fan-out.
+
+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
+
+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.
+
+## Compose by part, ownership, or perspective - not by job title
+
+A team is ALWAYS two or more members - never a single-member team. One worker on an isolated
+job is a subagent (`multi_agent_v1.spawn_agent`), not a team; if you end up with a single member,
+either split off a second distinct slice or drop the team and use a subagent.
+
+Compose the team from what you actually KNOW about the work. Ground the split in real knowledge
+of the problem, then divide it into clear, non-overlapping responsibilities - one per aspect of
+the work - and give each member exactly one. No two members may own the same thing. Define each
+member by a concrete slice: a specific part of the codebase, an ownership area, or a distinct
+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`.
+
+## Run the script - never hand-write team state
+
+A bundled, dependency-free Node script owns all team state so you never author `team.json` or
+the member manual by hand. Run it with `node` (or `bun`); it works on macOS, Linux, and Windows.
+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" 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" 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>
+```
+
+`init` creates `.omo/teams/{session_id}/` containing `team.json` (the single durable state file:
+team id, the main-session leader, the member roster, status, worktree config, and a lifecycle
+log), `guide.md` (the auto-generated member field manual), and `artifacts/` (a shared exchange
+space). `{session_id}` is the leader's Codex session id when you can pass it via `--session`;
+otherwise the script generates a stable handle. Re-running `init` is a safe no-op. Every mutating
+subcommand rewrites `guide.md`, so the manual always matches the current team.
+
+## Create the team and its threads
+
+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.
+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.
+
+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
+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
+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.
+
+## Archive, delete, and cleanup
+
+DISBAND the team the moment it is no longer needed. A team exists only to do its work; once that
+work is done, or the user no longer wants it, do not leave it lying around - archive every member,
+then delete the team state. A finished team that is never disbanded is a leak.
+
+- `archive` closes the team: notify each active member, copy anything useful into `artifacts/`,
+  archive each member thread with `codex_app.set_thread_archived`, then `archive` flips the team
+  and all members to archived. If a thread-archive tool is unavailable, record that in the team log
+  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.
+
+## Stop rules
+
+- Stop and ask before deleting an unarchived team while any member is still active.
+- Member communication stays English unless the user explicitly requests otherwise; user-facing
+  replies follow the user's language.
+- Stop if the requested operation needs Codex thread tools (create/read/send/title/archive) and
+  they are unavailable; say so instead of faking it.

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

@@ -0,0 +1,111 @@
+// team-guide.mjs - render the member-facing field manual (guide.md) and the short
+// bootstrap trigger a new thread reads on startup. Pure string builders, no I/O.
+//
+// The manual is the durable, two-channel replacement for per-prompt guidance: the leader
+// writes it once at team creation, and every member thread is told to READ it instead of
+// receiving the rules inline each turn.
+
+function memberLine(member) {
+	const thread = member.threadId ? ` | thread ${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}]`;
+}
+
+function worktreeSection(team) {
+	if (!team.worktree?.enabled) {
+		return `## Worktrees
+
+This team does not use isolated git worktrees. Work in the shared repository checkout
+the leader is running from. If your changes would collide with another member's files,
+that is a coordination signal: mark yourself \`blocked\` and tell the leader at once.`;
+	}
+	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}\``);
+	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.
+
+${lines.length ? lines.join("\n") : "- (worktree paths are assigned as threads are bound; read team.json for yours)"}`;
+}
+
+export function buildGuide(team) {
+	const artifacts = team.paths?.artifacts ?? ".omo/teams/<session_id>/artifacts";
+	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
+	const roster = team.members.length ? team.members.map(memberLine).join("\n") : "- (no members yet)";
+	return `# Team ${team.teamName} - Member Field Manual
+
+> Auto-generated by the teammode script. This file is the single source of truth for how
+> this team works. Re-read it whenever you are unsure - do not improvise the protocol.
+
+- Team: **${team.teamName}** (id \`${team.teamId}\`)
+- Team state: \`${teamJson}\`
+- Thread/session title convention (use it EXACTLY): \`${team.threadTitleConvention}\`
+
+## Who you are (your identity is fixed)
+
+**You are a member of team ${team.teamName}, not a generic assistant.** You own exactly one
+slice of this team's work - the focus and deliverable assigned to your id below - and you are
+accountable for it end to end. Read your row, internalize it, and act as that owner for the
+whole session. Do not drift into other members' scope.
+
+${roster}
+
+## Leader
+
+**The main session is the leader. There is no other leader, and you are not it.** You report
+to the leader, take direction from the leader, and send your results to the leader. Peers
+coordinate with each other, but the leader owns the final decision and integration.
+
+## Communication rules (hard rules)
+
+- **All communication between team members, and from you to the leader, is in English.** This
+  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.
+
+## Artifacts (how you hand work off)
+
+Exchange files and memos through the team artifacts directory:
+
+\`${artifacts}\`
+
+Drop deliverables, notes, diffs, and findings there as files, and reference them by path in
+your messages instead of pasting large content into a thread. Treat it as the team's shared
+desk: if a peer or the leader needs something from you, leave it in artifacts and point them to it.
+
+${worktreeSection(team)}
+
+## Done means reported and verified
+
+Your slice is done only when (1) the deliverable exists, (2) you have evidence it works, and
+(3) you have reported it to the leader. Until all three are true, keep going.`;
+}
+
+export function buildMemberPrompt(team, id) {
+	const member = team.members.find((m) => m.id === 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}.
+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}
+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.`;
+}

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

@@ -0,0 +1,250 @@
+// team-state.mjs - the teammode state model + atomic, symlink-guarded persistence.
+//
+// Zero external dependencies (node builtins only) so it runs byte-identically under
+// `node` and `bun` on macOS, Linux, and Windows with no install step, no POSIX shell,
+// and no python3 precondition. This is the SINGLE source of the team-state shape: the
+// model never hand-writes team.json - it calls these helpers through scripts/team.mjs.
+//
+// Rendering (the member field manual + bootstrap trigger) lives in team-guide.mjs so
+// this file stays the state concern only.
+
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export const LENSES = ["area", "ownership", "perspective"];
+export const MEMBER_STATUSES = ["pending", "active", "reported", "blocked", "archived"];
+// A team is never a single member: two or more distinct slices is the minimum. One isolated
+// job is a subagent, not a team.
+export const MIN_MEMBERS = 2;
+
+export function isUnderstaffed(team) {
+	return team.members.length < MIN_MEMBERS;
+}
+// A team dir is a single child of .omo/teams. This pattern alone blocks "/", "\", and a
+// leading "." so ".." and "a/b" can never name a team dir (the escape guard).
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function isoNow(now) {
+	return now ?? new Date().toISOString();
+}
+
+export function buildTeam({ teamName, sessionName, sessionId = null, dir = null, worktreeEnabled = false, baseBranch = "dev", now }) {
+	if (!teamName?.trim()) throw new Error("team name is required");
+	if (!sessionName?.trim()) throw new Error("session name is required");
+	const ts = isoNow(now);
+	return {
+		schemaVersion: 2,
+		teamId: randomUUID(),
+		teamName: teamName.trim(),
+		sessionName: sessionName.trim(),
+		sessionId,
+		threadTitleConvention: `[${teamName.trim()}] ${sessionName.trim()}`,
+		status: "active",
+		createdAt: ts,
+		updatedAt: ts,
+		archivedAt: null,
+		leader: { kind: "main-session", sessionId },
+		communication: { memberLanguage: "english", replyToUserInUserLanguage: true },
+		worktree: { enabled: Boolean(worktreeEnabled), baseBranch, root: dir ? join(dir, "worktrees") : null },
+		paths: dir
+			? { dir, team: join(dir, "team.json"), guide: join(dir, "guide.md"), artifacts: join(dir, "artifacts") }
+			: null,
+		members: [],
+		log: [{ ts, event: "created", detail: `team ${teamName.trim()}` }],
+	};
+}
+
+function touch(team, event, detail) {
+	const ts = isoNow();
+	team.updatedAt = ts;
+	team.log.push({ ts, event, detail });
+	return team;
+}
+
+function memberById(team, id) {
+	const found = team.members.find((m) => m.id === id);
+	if (!found) throw new Error(`no member with id "${id}"`);
+	return found;
+}
+
+function normalizedFocus(focus) {
+	return focus.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function assertUniqueMemberFocus(team) {
+	const seen = new Map();
+	for (const member of team.members) {
+		const key = normalizedFocus(member.focus ?? "");
+		const previous = seen.get(key);
+		if (previous) {
+			throw new Error(`member focus "${member.focus}" duplicates "${previous.focus}" (no two members may own the same thing)`);
+		}
+		seen.set(key, member);
+	}
+}
+
+function assertTeamReadyForThreadBinding(team) {
+	if (isUnderstaffed(team)) {
+		throw new Error(
+			`cannot bind member threads until the team has at least ${MIN_MEMBERS} distinct members; current count is ${team.members.length}`,
+		);
+	}
+	assertUniqueMemberFocus(team);
+}
+
+export function addMember(team, { id, focus, lens, deliverable = "", branch = 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();
+	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)`);
+	team.members.push({
+		id: memberId,
+		focus: memberFocus,
+		lens,
+		deliverable: deliverable.trim(),
+		threadId: null,
+		threadTitle: team.threadTitleConvention,
+		cwd: null,
+		worktree: { path: null, branch: branch ?? null },
+		status: "pending",
+	});
+	return touch(team, "add-member", `member ${memberId} (${lens}): ${memberFocus}`);
+}
+
+export function bindThread(team, { id, threadId, cwd = null, worktreePath = null }) {
+	if (!threadId?.trim()) throw new Error("thread id is required");
+	assertTeamReadyForThreadBinding(team);
+	const m = memberById(team, id);
+	m.threadId = threadId.trim();
+	m.status = "active";
+	if (cwd) m.cwd = cwd;
+	if (team.worktree.enabled) m.worktree.path = worktreePath ?? cwd ?? m.worktree.path;
+	return touch(team, "bind-thread", `member ${id} -> thread ${threadId.trim()}`);
+}
+
+export function setMemberStatus(team, { id, status, note = "" }) {
+	if (!MEMBER_STATUSES.includes(status)) throw new Error(`invalid status "${status}" - use one of: ${MEMBER_STATUSES.join(", ")}`);
+	memberById(team, id).status = status;
+	return touch(team, "set-status", `member ${id} -> ${status}${note ? `: ${note}` : ""}`);
+}
+
+export function archive(team, { id = null, note = "" } = {}) {
+	if (id) {
+		memberById(team, id).status = "archived";
+		return touch(team, "archive-member", `member ${id}${note ? `: ${note}` : ""}`);
+	}
+	for (const m of team.members) m.status = "archived";
+	team.status = "archived";
+	team.archivedAt = isoNow();
+	return touch(team, "archive", note || "team archived; all members closed");
+}
+
+export function validateTeam(team) {
+	if (team?.schemaVersion !== 2) throw new Error("invalid team: schemaVersion must be 2");
+	if (!team.teamId || !team.teamName) throw new Error("invalid team: teamId and teamName are required");
+	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);
+	return team;
+}
+
+// Resolve (and confine) a team dir to a single child of <cwd>/.omo/teams.
+export function resolveTeamDir(cwd, sessionId) {
+	if (!SESSION_ID_PATTERN.test(sessionId ?? "")) throw new Error(`invalid or unsafe session id "${sessionId}"`);
+	return resolve(cwd, ".omo", "teams", sessionId);
+}
+
+async function lstatOrNull(p) {
+	return lstat(p).catch((error) => {
+		if (error && error.code === "ENOENT") return null;
+		throw error;
+	});
+}
+
+// Create a directory chain refusing any symlinked component, so team state can never be
+// written through a symlink that escapes the workspace.
+async function mkdirNoSymlink(dir, stopAt) {
+	if (dir === stopAt) return;
+	const rel = relative(stopAt, dir);
+	if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`refused: path escapes ${stopAt}: ${dir}`);
+	await mkdirNoSymlink(dirname(dir), stopAt);
+	const st = await lstatOrNull(dir);
+	if (st) {
+		if (st.isSymbolicLink()) throw new Error(`refused: path component is a symlink: ${dir}`);
+		if (!st.isDirectory()) throw new Error(`refused: path component is not a directory: ${dir}`);
+		return;
+	}
+	await mkdir(dir);
+}
+
+async function assertNoSymlinkComponents(dir, stopAt) {
+	if (dir === stopAt) return;
+	const rel = relative(stopAt, dir);
+	if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`refused: path escapes ${stopAt}: ${dir}`);
+	await assertNoSymlinkComponents(dirname(dir), stopAt);
+	const st = await lstatOrNull(dir);
+	if (st?.isSymbolicLink()) throw new Error(`refused: path component is a symlink: ${dir}`);
+}
+
+export async function ensureTeamDir(cwd, sessionId) {
+	const workspaceRoot = resolve(cwd);
+	const teamsRoot = resolve(cwd, ".omo", "teams");
+	const dir = resolveTeamDir(cwd, sessionId);
+	await mkdirNoSymlink(teamsRoot, workspaceRoot);
+	await mkdirNoSymlink(dir, teamsRoot);
+	await mkdirNoSymlink(join(dir, "artifacts"), dir);
+	return dir;
+}
+
+export async function assertSafeTeamDir(cwd, sessionId) {
+	const workspaceRoot = resolve(cwd);
+	const teamsRoot = resolve(cwd, ".omo", "teams");
+	const dir = resolveTeamDir(cwd, sessionId);
+	await assertNoSymlinkComponents(teamsRoot, workspaceRoot);
+	await assertNoSymlinkComponents(dir, teamsRoot);
+	return dir;
+}
+
+export async function readTeam(dir) {
+	return validateTeam(JSON.parse(await readFile(join(dir, "team.json"), "utf8")));
+}
+
+export async function teamExists(dir) {
+	return (await lstatOrNull(join(dir, "team.json"))) !== null;
+}
+
+async function persistedFileTarget(team, pathKey, fileName, expectedDir) {
+	validateTeam(team);
+	if (!team.paths?.dir || !team.paths?.[pathKey]) throw new Error(`invalid team: paths.${pathKey} is required`);
+	const dir = resolve(expectedDir);
+	if (resolve(team.paths.dir) !== dir) throw new Error(`refused: persisted team dir does not match trusted team dir: ${team.paths.dir}`);
+	const target = resolve(team.paths[pathKey]);
+	if (target !== resolve(dir, fileName)) throw new Error(`refused: ${fileName} persist target escapes team dir: ${team.paths[pathKey]}`);
+	const dirStat = await lstatOrNull(dir);
+	if (dirStat?.isSymbolicLink()) throw new Error(`refused: team dir is a symlink: ${dir}`);
+	const st = await lstatOrNull(target);
+	if (st?.isSymbolicLink()) throw new Error(`refused: ${fileName} is a symlink: ${target}`);
+	if (st && !st.isFile()) throw new Error(`refused: ${fileName} is not a file: ${target}`);
+	return target;
+}
+
+async function writePersistedFileAtomic(team, pathKey, fileName, content, expectedDir) {
+	const target = await persistedFileTarget(team, pathKey, fileName, expectedDir);
+	const tmp = `${target}.tmp-${process.pid}-${randomUUID()}`;
+	await writeFile(tmp, content, { encoding: "utf8", flag: "wx" });
+	await rename(tmp, target);
+	return team;
+}
+
+export async function writeTeamAtomic(team, expectedDir) {
+	return writePersistedFileAtomic(team, "team", "team.json", `${JSON.stringify(team, null, 2)}\n`, expectedDir);
+}
+
+export async function writeGuideAtomic(team, content, expectedDir) {
+	return writePersistedFileAtomic(team, "guide", "guide.md", content, expectedDir);
+}