@codex-modules/teams 0.1.1

package/dist/prompt.js

@@ -0,0 +1,42 @@
+import { memberAgentName, resolveMemberSandbox } from "./team.js";
+export function assembleDeveloperInstructions(team, member) {
+    const sandbox = resolveMemberSandbox(team, member);
+    const lines = [
+        `You are team member "${member.name}" of team "${team.name}". Focus: ${member.focus}. Lens: ${member.lens}. Deliverable: ${member.deliverable}.`,
+        `Return your final report with the last line exactly in this format: TEAM-RESULT: <one-line summary>.`,
+        `Do not call codex-teams task or note commands yourself; the leader owns durable state updates.`,
+    ];
+    if (sandbox === "workspace-write") {
+        lines.push(`You may also write supporting artifacts under .codex-teams/${team.name}/artifacts/${member.name}/, but the TEAM-RESULT final line remains the canonical result channel.`);
+    }
+    if (member.instructions && member.instructions.trim())
+        lines.push(member.instructions.trim());
+    return `${lines.join("\n\n")}\n`;
+}
+export function assembleLeaderPrompt(team, goal) {
+    const roster = team.members
+        .map(member => `- ${member.name}: agent_type=${memberAgentName(team, member)}; focus=${member.focus}; deliverable=${member.deliverable}`)
+        .join("\n");
+    return `You are the leader for Codex team "${team.name}".
+
+Goal:
+${goal}
+
+Roster:
+${roster}
+
+Use the stable native multi-agent tool path only:
+1. Load tools with tool_search for multi_agent_v1.spawn_agent, wait, close, resume, and send_input.
+2. Start durable state before spawning: codex-teams state init ${team.name} --goal ${shellQuote(goal)}
+3. After each spawn, record the returned agent id: codex-teams member bind ${team.name} <member> --agent-id <id> --nickname <nick>
+4. Track work with codex-teams task add, task claim, task complete, and task fail. Use codex-teams note add for shared observations.
+5. Spawn only independent tasks concurrently. Join with wait. If a member fails, close it and return its claimed task to a safe state.
+6. Treat each member's final TEAM-RESULT line as the canonical result. Artifact files are optional supporting evidence for workspace-write members.
+7. Integrate and verify the final answer yourself. Finish with: codex-teams state finish ${team.name} --status ok or --status partial.
+
+Do not use codex_app.*, spawn_agents_on_csv, multi_agent_v2, or trust/config mutation for this MVP workflow.
+`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/dist/runner.d.ts

@@ -0,0 +1,32 @@
+import type { SandboxMode } from "./types.js";
+export type RunOptions = {
+    goal: string;
+    codexHome?: string;
+    sandbox?: SandboxMode;
+    timeoutSec?: number;
+    stallSec?: number;
+    execute?: boolean;
+    allowCodex?: boolean;
+    cwd?: string;
+    stateDir?: string;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+};
+export type DryRunPlan = {
+    mode: "dry-run";
+    argv: string[];
+    prompt: string;
+    runDir: string;
+};
+export type RunResult = {
+    mode: "executed";
+    status: "ok" | "error" | "timeout" | "stall";
+    exitCode: number | null;
+    argv: string[];
+    runDir: string;
+    eventsPath: string;
+    lastMessagePath: string;
+    summaryPath: string;
+};
+export declare function buildRunPlan(teamPath: string, opts: RunOptions): DryRunPlan;
+export declare function runTeam(teamPath: string, opts: RunOptions): Promise<DryRunPlan | RunResult>;
+export declare function buildCodexArgv(prompt: string, runDir: string, opts: RunOptions): string[];

package/dist/runner.js

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { closeSync, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { findCodexBinary, resolveCodexHome } from "./agents.js";
+import { parseTeamJson } from "./team.js";
+import { assembleLeaderPrompt } from "./prompt.js";
+import { resolveStateRoot, writeJsonAtomic } from "./state.js";
+export function buildRunPlan(teamPath, opts) {
+    const team = parseTeamJson(teamPath);
+    const prompt = assembleLeaderPrompt(team, opts.goal);
+    const runDir = resolveRunDir(team, opts);
+    return {
+        mode: "dry-run",
+        argv: buildCodexArgv(prompt, runDir, opts),
+        prompt,
+        runDir,
+    };
+}
+export async function runTeam(teamPath, opts) {
+    assertSafeRunOptions(opts);
+    const plan = buildRunPlan(teamPath, opts);
+    if (!opts.execute || !opts.allowCodex)
+        return plan;
+    if ((opts.sandbox ?? "workspace-write") === "read-only") {
+        throw new Error("executed team runs require workspace-write because the leader writes .codex-teams state");
+    }
+    const bin = findCodexBinary(opts.env);
+    if (!bin)
+        throw new Error("codex binary not found");
+    mkdirSync(plan.runDir, { recursive: true });
+    const eventsPath = join(plan.runDir, "events.jsonl");
+    const stderrPath = join(plan.runDir, "stderr.log");
+    const lastMessagePath = join(plan.runDir, "last-message.md");
+    const summaryPath = join(plan.runDir, "summary.json");
+    const startedAt = Date.now();
+    let exitCode = null;
+    let status = null;
+    await new Promise(resolve => {
+        const devNullFd = openSync("/dev/null", "r");
+        const events = createWriteStream(eventsPath, { flags: "a" });
+        const stderr = createWriteStream(stderrPath, { flags: "a" });
+        const child = spawn(bin, plan.argv, {
+            cwd: opts.cwd ?? process.cwd(),
+            env: {
+                ...process.env,
+                ...(opts.env ?? {}),
+                CODEX_HOME: resolveCodexHome(opts.env, opts.codexHome),
+            },
+            stdio: [devNullFd, "pipe", "pipe"],
+        });
+        if (!child.stdout || !child.stderr) {
+            status = "error";
+            child.kill("SIGTERM");
+            closeFd(devNullFd);
+            events.end(() => stderr.end(() => resolve()));
+            return;
+        }
+        child.stdout.pipe(events);
+        child.stderr.pipe(stderr);
+        const timeoutTimer = setTimeout(() => {
+            status = "timeout";
+            child.kill("SIGTERM");
+        }, (opts.timeoutSec ?? 600) * 1000);
+        const stallTimer = setInterval(() => {
+            if (Date.now() - latestMtimeMs([eventsPath, stderrPath, lastMessagePath], startedAt) > (opts.stallSec ?? 180) * 1000) {
+                status = "stall";
+                child.kill("SIGTERM");
+            }
+        }, 1000);
+        child.once("error", () => {
+            status = "error";
+        });
+        child.once("close", code => {
+            exitCode = code;
+            clearTimeout(timeoutTimer);
+            clearInterval(stallTimer);
+            closeFd(devNullFd);
+            events.end(() => stderr.end(() => resolve()));
+        });
+    });
+    if (!status)
+        status = exitCode === 0 ? "ok" : "error";
+    writeJsonAtomic(summaryPath, summarizeEvents(eventsPath, { status, exitCode, teamPath: basename(teamPath) }));
+    return { mode: "executed", status, exitCode, argv: plan.argv, runDir: plan.runDir, eventsPath, lastMessagePath, summaryPath };
+}
+export function buildCodexArgv(prompt, runDir, opts) {
+    const sandbox = opts.sandbox ?? "workspace-write";
+    if (sandbox !== "read-only" && sandbox !== "workspace-write")
+        throw new Error("sandbox must be read-only or workspace-write");
+    return [
+        "exec",
+        "-s",
+        sandbox,
+        "--skip-git-repo-check",
+        "--json",
+        "--ephemeral",
+        "-o",
+        join(runDir, "last-message.md"),
+        prompt,
+    ];
+}
+function resolveRunDir(team, opts) {
+    const safeStamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(resolveStateRoot({ cwd: opts.cwd, stateDir: opts.stateDir, env: opts.env }), team.name, "runs", safeStamp);
+}
+function assertSafeRunOptions(opts) {
+    if (!opts.goal || !opts.goal.trim())
+        throw new Error("--goal is required");
+    if (opts.sandbox !== undefined && opts.sandbox !== "read-only" && opts.sandbox !== "workspace-write")
+        throw new Error("sandbox must be read-only or workspace-write");
+    if (opts.timeoutSec !== undefined && (!Number.isFinite(opts.timeoutSec) || opts.timeoutSec <= 0))
+        throw new Error("timeout-sec must be > 0");
+    if (opts.stallSec !== undefined && (!Number.isFinite(opts.stallSec) || opts.stallSec <= 0))
+        throw new Error("stall-sec must be > 0");
+}
+function summarizeEvents(path, base) {
+    const collabToolCalls = [];
+    if (existsSync(path)) {
+        for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            try {
+                const item = JSON.parse(line);
+                if (JSON.stringify(item).includes("collab_tool_call"))
+                    collabToolCalls.push(item);
+            }
+            catch {
+                // ignore non-JSON event lines
+            }
+        }
+    }
+    else {
+        writeFileSync(path, "");
+    }
+    return { ...base, collabToolCallCount: collabToolCalls.length, collabToolCalls };
+}
+function latestMtimeMs(paths, fallback) {
+    let latest = fallback;
+    for (const path of paths) {
+        try {
+            latest = Math.max(latest, statSync(path).mtimeMs);
+        }
+        catch {
+            // file may not exist yet
+        }
+    }
+    return latest;
+}
+function closeFd(fd) {
+    try {
+        closeSync(fd);
+    }
+    catch {
+        // best effort
+    }
+}

package/dist/skill.d.ts

@@ -0,0 +1,14 @@
+export type SkillInstallOptions = {
+    codexHome?: string;
+    force?: boolean;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+};
+export declare function renderTeamsSkill(): string;
+export declare function installSkill(opts?: SkillInstallOptions): {
+    file: string;
+    backup: string | null;
+};
+export declare function uninstallSkill(opts?: SkillInstallOptions): {
+    removed: string[];
+    restored: string[];
+};

package/dist/skill.js

@@ -0,0 +1,84 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { backupSkillFile, resolveCodexHome, readManifest, writeManifest } from "./agents.js";
+import { nowIso, writeFileAtomic } from "./state.js";
+export function renderTeamsSkill() {
+    return `---
+name: teams
+description: Use when a task should be handled by a declared Codex team with native stable multi-agent collaboration, durable task leases, and a leader-owned journal.
+---
+
+# Codex Teams
+
+Use this skill when the user asks for a team, panel, swarm, or parallel collaboration and a local team definition is available.
+
+1. Find a team definition in ./team.json first, then .codex-teams/*/team.json if present.
+2. If the team is not installed, tell the user to run codex-teams install <team.json>. Do not edit trust or config.toml automatically.
+3. Load the native multi-agent tools with tool_search. Use stable multi_agent_v1.spawn_agent, wait, close, resume, and send_input only.
+4. Start durable state with codex-teams state init <team> --goal "<goal>" before spawning members.
+5. After each spawn, record the returned id with codex-teams member bind <team> <member> --agent-id <id> --nickname <nick>.
+6. Use codex-teams task add/claim/complete/fail and codex-teams note add/list for leader-owned state. Members should report through their final TEAM-RESULT line.
+7. Use wait to collect member results, inspect any optional artifacts, and integrate the final answer yourself.
+8. Finish with codex-teams state finish <team> --status ok or --status partial.
+
+Do not use codex_app.*, spawn_agents_on_csv, multi_agent_v2, or automatic trust mutation for this MVP workflow.
+`;
+}
+export function installSkill(opts = {}) {
+    const root = join(resolveCodexHome(opts.env, opts.codexHome), "skills");
+    const dir = join(root, "teams");
+    const file = join(dir, "SKILL.md");
+    mkdirSync(dir, { recursive: true });
+    const manifest = readManifest(root);
+    const existing = manifest.entries.find(entry => entry.kind === "skill" && entry.file === file);
+    let backup = existing?.backup ?? null;
+    if (existsSync(file) && !existing) {
+        if (!opts.force)
+            throw new Error(`refusing to overwrite unmanaged skill file: ${file} (use --force to back it up first)`);
+        backup = backupSkillFile(file, join(root, ".codex-teams-backups"));
+    }
+    const content = renderTeamsSkill();
+    writeFileAtomic(file, content);
+    const entries = manifest.entries.filter(entry => !(entry.kind === "skill" && entry.file === file));
+    entries.push({
+        team: "teams",
+        scope: "skill",
+        file,
+        backup,
+        hash: sha256(content),
+        kind: "skill",
+        installed_at: nowIso(opts.env),
+    });
+    writeManifest(root, { ...manifest, entries });
+    return { file, backup };
+}
+export function uninstallSkill(opts = {}) {
+    const root = join(resolveCodexHome(opts.env, opts.codexHome), "skills");
+    const manifest = readManifest(root);
+    const removed = [];
+    const restored = [];
+    const keep = [];
+    for (const entry of manifest.entries) {
+        if (entry.kind !== "skill" || entry.team !== "teams") {
+            keep.push(entry);
+            continue;
+        }
+        if (existsSync(entry.file)) {
+            const currentHash = sha256(readFileSync(entry.file, "utf8"));
+            if (currentHash !== entry.hash)
+                throw new Error(`installed skill changed since install; refusing uninstall without manual review: ${entry.file}`);
+            rmSync(entry.file, { force: true });
+            removed.push(entry.file);
+        }
+        if (entry.backup && existsSync(entry.backup)) {
+            copyFileSync(entry.backup, entry.file);
+            restored.push(entry.file);
+        }
+    }
+    writeManifest(root, { ...manifest, entries: keep });
+    return { removed, restored };
+}
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}

package/dist/state.d.ts

@@ -0,0 +1,45 @@
+import type { FinishStatus, JournalEntry, JournalKind, StateFile, TaskRecord, TasksFile } from "./types.js";
+export type StateOptions = {
+    cwd?: string;
+    stateDir?: string;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+};
+export declare function resolveStateRoot(opts?: StateOptions): string;
+export declare function teamDir(team: string, opts?: StateOptions): string;
+export declare function initState(team: string, goal: string, opts?: StateOptions & {
+    noGitignore?: boolean;
+}): StateFile;
+export declare function showState(team: string, opts?: StateOptions): StateFile;
+export declare function finishState(team: string, status: FinishStatus, opts?: StateOptions): StateFile;
+export declare function bindMember(team: string, member: string, agentId: string, opts?: StateOptions & {
+    nickname?: string;
+}): StateFile;
+export declare function addTask(team: string, input: {
+    title: string;
+    detail?: string;
+    dependsOn?: string[];
+}, opts?: StateOptions): TaskRecord;
+export declare function claimTask(team: string, taskId: string, input: {
+    actor: string;
+    leaseSec?: number;
+    reclaim?: boolean;
+}, opts?: StateOptions): TaskRecord;
+export declare function completeTask(team: string, taskId: string, input: {
+    actor: string;
+    result?: string;
+    failed?: boolean;
+}, opts?: StateOptions): TaskRecord;
+export declare function listTasks(team: string, opts?: StateOptions & {
+    reclaim?: boolean;
+}): TasksFile;
+export declare function addNote(team: string, input: {
+    actor: string;
+    text: string;
+    kind?: JournalKind;
+}, opts?: StateOptions): JournalEntry;
+export declare function listNotes(team: string, opts?: StateOptions): JournalEntry[];
+export declare function loadTasks(team: string, opts?: StateOptions): TasksFile;
+export declare function writeJsonAtomic(path: string, value: unknown): void;
+export declare function readJson<T>(path: string): T;
+export declare function writeFileAtomic(path: string, content: string | Buffer): void;
+export declare function nowIso(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): string;

package/dist/state.js

@@ -0,0 +1,261 @@
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { TEAM_NAME_RE, MEMBER_NAME_RE } from "./team.js";
+import { withLock } from "./lock.js";
+import { assertConfinedRoot } from "./paths.js";
+export function resolveStateRoot(opts = {}) {
+    const envRoot = opts.env?.CODEX_TEAMS_STATE_DIR;
+    if (opts.stateDir)
+        return resolve(opts.stateDir);
+    if (envRoot)
+        return resolve(envRoot);
+    const projectRoot = resolve(opts.cwd ?? process.cwd());
+    return assertConfinedRoot(join(projectRoot, ".codex-teams"), projectRoot);
+}
+export function teamDir(team, opts = {}) {
+    assertTeamName(team);
+    return join(resolveStateRoot(opts), team);
+}
+export function initState(team, goal, opts = {}) {
+    assertTeamName(team);
+    const dir = teamDir(team, opts);
+    mkdirSync(join(dir, "locks"), { recursive: true });
+    mkdirSync(join(dir, "artifacts"), { recursive: true });
+    mkdirSync(join(dir, "runs"), { recursive: true });
+    if (!opts.noGitignore && isInsideGitWorktree(opts.cwd ?? process.cwd())) {
+        mkdirSync(resolveStateRoot(opts), { recursive: true });
+        const gitignore = join(resolveStateRoot(opts), ".gitignore");
+        if (!existsSync(gitignore))
+            writeFileAtomic(gitignore, "*\n");
+    }
+    return withTeamLock(team, opts, () => {
+        const now = nowIso(opts.env);
+        const state = {
+            version: 1,
+            team,
+            goal,
+            status: "active",
+            members: {},
+            created_at: now,
+        };
+        writeJsonAtomic(join(dir, "state.json"), state);
+        if (!existsSync(join(dir, "tasks.json")))
+            writeJsonAtomic(join(dir, "tasks.json"), { version: 1, tasks: [] });
+        if (!existsSync(join(dir, "journal.jsonl")))
+            writeFileAtomic(join(dir, "journal.jsonl"), "");
+        return state;
+    });
+}
+export function showState(team, opts = {}) {
+    return readJson(join(teamDir(team, opts), "state.json"));
+}
+export function finishState(team, status, opts = {}) {
+    if (status !== "ok" && status !== "partial")
+        throw new Error("status must be ok or partial");
+    return withTeamLock(team, opts, () => {
+        const path = join(teamDir(team, opts), "state.json");
+        const state = readJson(path);
+        state.status = "finished";
+        state.finish_status = status;
+        state.finished_at = nowIso(opts.env);
+        writeJsonAtomic(path, state);
+        return state;
+    });
+}
+export function bindMember(team, member, agentId, opts = {}) {
+    assertTeamName(team);
+    assertMemberName(member);
+    if (!agentId.trim())
+        throw new Error("agent-id is required");
+    return withTeamLock(team, opts, () => {
+        const path = join(teamDir(team, opts), "state.json");
+        const state = readJson(path);
+        state.members[member] = {
+            agent_id: agentId,
+            nickname: opts.nickname,
+            bound_at: nowIso(opts.env),
+        };
+        writeJsonAtomic(path, state);
+        return state;
+    });
+}
+export function addTask(team, input, opts = {}) {
+    if (!input.title.trim())
+        throw new Error("task title is required");
+    return withTaskMutation(team, opts, tasks => {
+        const now = nowIso(opts.env);
+        const task = {
+            id: nextTaskId(tasks),
+            title: input.title,
+            detail: input.detail,
+            depends_on: input.dependsOn ?? [],
+            status: "open",
+            created_at: now,
+            updated_at: now,
+        };
+        for (const dep of task.depends_on) {
+            if (!tasks.tasks.some(existing => existing.id === dep))
+                throw new Error(`unknown dependency: ${dep}`);
+        }
+        tasks.tasks.push(task);
+        return task;
+    });
+}
+export function claimTask(team, taskId, input, opts = {}) {
+    assertMemberName(input.actor);
+    const leaseSec = input.leaseSec ?? 900;
+    if (!Number.isFinite(leaseSec) || leaseSec <= 0)
+        throw new Error("lease-sec must be > 0");
+    return withTaskMutation(team, opts, tasks => {
+        reclaimExpired(tasks, nowIso(opts.env));
+        const task = mustFindTask(tasks, taskId);
+        if (task.status !== "open")
+            throw new Error(`task ${taskId} is not open`);
+        const incomplete = task.depends_on.filter(dep => mustFindTask(tasks, dep).status !== "done");
+        if (incomplete.length > 0)
+            throw new Error(`task ${taskId} has incomplete dependencies: ${incomplete.join(",")}`);
+        const nowMs = Date.parse(nowIso(opts.env));
+        task.status = "claimed";
+        task.claimed_by = input.actor;
+        task.lease_expires_at = new Date(nowMs + leaseSec * 1000).toISOString();
+        task.updated_at = new Date(nowMs).toISOString();
+        return task;
+    });
+}
+export function completeTask(team, taskId, input, opts = {}) {
+    assertMemberName(input.actor);
+    return withTaskMutation(team, opts, tasks => {
+        const task = mustFindTask(tasks, taskId);
+        if (task.status !== "claimed" || task.claimed_by !== input.actor) {
+            throw new Error(`task ${taskId} is not claimed by ${input.actor}`);
+        }
+        task.status = input.failed ? "failed" : "done";
+        task.result = input.result;
+        task.lease_expires_at = undefined;
+        task.updated_at = nowIso(opts.env);
+        return task;
+    });
+}
+export function listTasks(team, opts = {}) {
+    if (!opts.reclaim)
+        return loadTasks(team, opts);
+    return withTaskMutation(team, opts, tasks => {
+        reclaimExpired(tasks, nowIso(opts.env));
+        return tasks;
+    });
+}
+export function addNote(team, input, opts = {}) {
+    assertMemberName(input.actor);
+    if (!input.text.trim())
+        throw new Error("note text is required");
+    const kind = input.kind ?? "note";
+    if (kind !== "note" && kind !== "handoff" && kind !== "decision")
+        throw new Error("kind must be note, handoff, or decision");
+    return withTeamLock(team, opts, () => {
+        const entry = { ts: nowIso(opts.env), actor: input.actor, kind, text: input.text };
+        appendFileSync(join(teamDir(team, opts), "journal.jsonl"), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+        return entry;
+    });
+}
+export function listNotes(team, opts = {}) {
+    const path = join(teamDir(team, opts), "journal.jsonl");
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map(line => JSON.parse(line));
+}
+export function loadTasks(team, opts = {}) {
+    const path = join(teamDir(team, opts), "tasks.json");
+    if (!existsSync(path))
+        return { version: 1, tasks: [] };
+    return readJson(path);
+}
+export function writeJsonAtomic(path, value) {
+    writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+export function writeFileAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, content, { mode: 0o600 });
+    const fd = openSync(tmp, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+}
+export function nowIso(env = process.env) {
+    const override = env.CODEX_TEAMS_NOW;
+    if (override) {
+        const ms = Date.parse(override);
+        if (Number.isNaN(ms))
+            throw new Error(`CODEX_TEAMS_NOW is not a valid ISO timestamp: ${override}`);
+        return new Date(ms).toISOString();
+    }
+    return new Date().toISOString();
+}
+function withTaskMutation(team, opts, fn) {
+    return withTeamLock(team, opts, () => {
+        const tasks = loadTasks(team, opts);
+        const result = fn(tasks);
+        writeJsonAtomic(join(teamDir(team, opts), "tasks.json"), tasks);
+        return result;
+    });
+}
+function withTeamLock(team, opts, fn) {
+    const dir = teamDir(team, opts);
+    mkdirSync(join(dir, "locks"), { recursive: true });
+    return withLock(join(dir, "locks", "state.lock"), { ttlMs: 30_000, waitMs: 10_000, purpose: `teams:${team}` }, fn);
+}
+function reclaimExpired(tasks, now) {
+    const nowMs = Date.parse(now);
+    for (const task of tasks.tasks) {
+        if (task.status === "claimed" && task.lease_expires_at && Date.parse(task.lease_expires_at) <= nowMs) {
+            task.status = "open";
+            task.claimed_by = undefined;
+            task.lease_expires_at = undefined;
+            task.updated_at = now;
+        }
+    }
+}
+function mustFindTask(tasks, taskId) {
+    const task = tasks.tasks.find(item => item.id === taskId);
+    if (!task)
+        throw new Error(`unknown task: ${taskId}`);
+    return task;
+}
+function nextTaskId(tasks) {
+    let n = tasks.tasks.length + 1;
+    for (;;) {
+        const id = `task-${String(n).padStart(3, "0")}`;
+        if (!tasks.tasks.some(task => task.id === id))
+            return id;
+        n++;
+    }
+}
+function assertTeamName(team) {
+    if (!TEAM_NAME_RE.test(team))
+        throw new Error(`invalid team name: ${team}`);
+}
+function assertMemberName(member) {
+    if (!MEMBER_NAME_RE.test(member))
+        throw new Error(`invalid member name: ${member}`);
+}
+function isInsideGitWorktree(cwd) {
+    let current = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(current, ".git")))
+            return true;
+        const next = dirname(current);
+        if (next === current)
+            return false;
+        current = next;
+    }
+}

package/dist/team.d.ts

@@ -0,0 +1,11 @@
+import type { MemberDef, SandboxMode, TeamDef } from "./types.js";
+export declare const TEAM_NAME_RE: RegExp;
+export declare const MEMBER_NAME_RE: RegExp;
+export declare function parseTeamJson(path: string): TeamDef;
+export declare function validateTeamDef(value: unknown, label?: string): TeamDef;
+export declare function collectTeamErrors(value: unknown): string[];
+export declare function scaffoldTeam(preset?: "review-panel" | "swarm" | "pipeline"): TeamDef;
+export declare function writePreset(path: string, preset: "review-panel" | "swarm" | "pipeline"): void;
+export declare function memberAgentName(team: TeamDef | string, member: MemberDef | string): string;
+export declare function resolveMemberModel(team: TeamDef, member: MemberDef): string;
+export declare function resolveMemberSandbox(team: TeamDef, member: MemberDef): SandboxMode;