@codex-modules/teams 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArcSolver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,158 @@
+<p align="right"><a href="README.md">English</a> | 한국어</p>
+
+# @codex-modules/teams
+
+`codex-teams`는 `team.json`을 Codex agent TOML, 리더 지시문, 프로젝트 로컬 팀 상태로 바꾸는 CLI입니다.
+
+멀티 에이전트 실행 엔진은 Codex native stable `multi_agent_v1.spawn_agent`를 리더 세션 안에서 사용합니다. 이 패키지는 엔진을 다시 만들지 않고, 팀 정의, 안전한 install/uninstall, task lease, journal, dry-run 기본 headless runner를 관리합니다.
+
+## 설치
+
+```bash
+npm install -g @codex-modules/teams
+```
+
+또는 source에서:
+
+```bash
+npm install
+npm run build
+```
+
+이 패키지의 CLI를 바로 실행하려면:
+
+```bash
+node dist/cli.js doctor
+```
+
+global 설치나 npm linking 후에는:
+
+```bash
+codex-teams doctor
+```
+
+## 사용법
+
+starter team을 만듭니다:
+
+```bash
+codex-teams init --preset review-panel --out team.json
+codex-teams validate team.json
+```
+
+팀을 Codex home에 설치합니다:
+
+```bash
+codex-teams install team.json
+```
+
+기본값은 `$CODEX_HOME/agents/<team>-<member>.toml`을 쓰고 `$CODEX_HOME/agents/.codex-teams-manifest.json`에 소유권을 기록합니다. sandbox나 다른 Codex home을 쓰려면 `--codex-home <dir>`를 넘기세요.
+
+Project scope 설치는 명시적으로 선택합니다:
+
+```bash
+codex-teams install team.json --scope project
+```
+
+Project scope는 `<cwd>/.codex/agents/`에 쓰고 trust 경고를 출력합니다. `config.toml`을 편집하거나 프로젝트를 trusted로 등록하지 않습니다.
+
+리더 프롬프트를 생성합니다:
+
+```bash
+codex-teams leader-prompt team.json --goal "Review this change for security and correctness"
+```
+
+프로젝트 내구 상태를 시작합니다:
+
+```bash
+codex-teams state init review-panel --goal "Review this change"
+codex-teams task add review-panel --title "Security review"
+codex-teams task claim review-panel task-001 --actor security
+codex-teams note add review-panel --actor leader --text "Security and correctness can run in parallel"
+```
+
+`run`은 기본적으로 dry-run입니다:
+
+```bash
+codex-teams run team.json --goal "Review this change"
+```
+
+실제 `codex exec` 실행은 두 opt-in이 모두 필요합니다:
+
+```bash
+codex-teams run team.json --goal "Review this change" --execute --allow-codex
+```
+
+실행 runner는 기본적으로 `codex exec -s workspace-write --skip-git-repo-check --json --ephemeral`을 사용하고 run artifact를 `.codex-teams/<team>/runs/` 아래에 남깁니다. runner는 `read-only` 또는 `workspace-write` sandbox만 허용하고, danger-access flag를 전달하지 않으며, 조립된 prompt를 `codex exec`의 단일 positional 인자로만 넘깁니다.
+
+선택적 Codex skill을 설치합니다:
+
+```bash
+codex-teams skill install
+```
+
+## 동작 방식
+
+`team.json`은 team name, defaults, 2명에서 8명 사이의 members를 정의합니다. Member name은 `<team>-<member>` 형식의 Codex agent type이 됩니다.
+
+Install은 각 member를 다음 필드가 있는 TOML로 렌더합니다:
+
+- `name`
+- `description`
+- `model`
+- `sandbox_mode`
+- `nickname_candidates`
+- `developer_instructions`
+
+모든 TOML string은 basic string으로 렌더되어 따옴표, 백슬래시, 개행, TOML 제어문자가 escape됩니다. `nickname_candidates`는 string array로 렌더됩니다.
+
+기존 unmanaged file은 `--force` 없이는 절대 덮어쓰지 않습니다. `--force`를 사용한 overwrite는 먼저 backup을 만듭니다. Uninstall은 선택한 target root의 manifest에 기록된 파일만 건드립니다.
+
+프로젝트 상태는 다음 위치에 있습니다:
+
+```text
+.codex-teams/<team>/
+  state.json
+  tasks.json
+  journal.jsonl
+  artifacts/<member>/
+  runs/
+  locks/
+```
+
+`state.json`과 `tasks.json`은 mkdir lock 안에서 atomic write로 저장됩니다. `journal.jsonl`은 같은 lock 안에서 append-only로 추가됩니다. Task claim은 lease를 사용하며, 만료된 claim은 `task claim`과 `task list --reclaim`에서 회수됩니다. 결정론적 테스트에는 `CODEX_TEAMS_NOW`로 시간을 override할 수 있습니다.
+
+상태 CLI는 리더 또는 사람이 호출하는 표면입니다. 멤버는 마지막 `TEAM-RESULT: <one-line summary>` 줄로 보고합니다. Workspace-write 멤버는 선택적으로 artifact를 남길 수 있지만, canonical 결과 채널은 final message입니다.
+
+`doctor`는 Codex binary, version, native feature state, model catalog availability, write access, installed teams를 user/project scope로 나눠 보고합니다. 건강한 native workflow에는 `multi_agent`가 stable and enabled여야 합니다. `enable_fanout`과 `multi_agent_v2`는 under-development surface로만 보고합니다.
+
+이 package는 runtime dependency가 없습니다. package root는 team parsing, install/uninstall, doctor, prompt/run planning, durable state/task/note operation을 위한 지원 대상 high-level helper만 export합니다.
+
+## Attribution
+
+No third-party code is included; the state protocol is an original clean-room design.
+
+## 제거와 롤백
+
+설치된 team을 제거합니다:
+
+```bash
+codex-teams uninstall review-panel
+```
+
+sandbox 또는 project scope를 썼다면 install 때와 같은 target root를 지정합니다:
+
+```bash
+codex-teams uninstall review-panel --codex-home /tmp/codex-home
+codex-teams uninstall review-panel --scope project
+```
+
+Uninstall은 manifest-owned file만 삭제합니다. `--force` install이 unmanaged file을 backup했다면 uninstall 때 그 backup을 복원합니다. 설치된 파일이 install 이후 바뀌었다면, 수동 확인을 위해 uninstall이 삭제를 거부합니다.
+
+선택적 skill 제거:
+
+```bash
+codex-teams skill uninstall
+```
+
+`.codex-teams/` 아래 상태는 project-local runtime data입니다. 프로젝트가 git worktree로 보이면 기본적으로 ignore됩니다. task board, journal, runs, artifacts가 더 필요 없으면 `.codex-teams/<team>/`을 삭제하세요.

package/README.md

@@ -0,0 +1,158 @@
+<p align="right">English | <a href="README.ko.md">한국어</a></p>
+
+# @codex-modules/teams
+
+`codex-teams` turns a `team.json` file into Codex agent TOML files, leader instructions, and durable project-local team state.
+
+It uses Codex native stable `multi_agent_v1.spawn_agent` through a leader session. This package does not reimplement the multi-agent engine. It manages team definitions, safe install/uninstall, task leases, a journal, and a dry-run-first headless runner.
+
+## Install
+
+```bash
+npm install -g @codex-modules/teams
+```
+
+Or from source:
+
+```bash
+npm install
+npm run build
+```
+
+Use the CLI from this package:
+
+```bash
+node dist/cli.js doctor
+```
+
+When installed globally or through npm linking, the command is:
+
+```bash
+codex-teams doctor
+```
+
+## Usage
+
+Create a starter team:
+
+```bash
+codex-teams init --preset review-panel --out team.json
+codex-teams validate team.json
+```
+
+Install the team into a Codex home:
+
+```bash
+codex-teams install team.json
+```
+
+By default this writes `$CODEX_HOME/agents/<team>-<member>.toml` and records ownership in `$CODEX_HOME/agents/.codex-teams-manifest.json`. Use `--codex-home <dir>` for a sandbox or alternate Codex home.
+
+Project-scope install is explicit:
+
+```bash
+codex-teams install team.json --scope project
+```
+
+Project scope writes `<cwd>/.codex/agents/` and prints a trust warning. It does not edit `config.toml` or mark the project trusted.
+
+Generate the leader prompt:
+
+```bash
+codex-teams leader-prompt team.json --goal "Review this change for security and correctness"
+```
+
+Start durable state in the project:
+
+```bash
+codex-teams state init review-panel --goal "Review this change"
+codex-teams task add review-panel --title "Security review"
+codex-teams task claim review-panel task-001 --actor security
+codex-teams note add review-panel --actor leader --text "Security and correctness can run in parallel"
+```
+
+Run is dry-run by default:
+
+```bash
+codex-teams run team.json --goal "Review this change"
+```
+
+Actual `codex exec` launch requires both opt-ins:
+
+```bash
+codex-teams run team.json --goal "Review this change" --execute --allow-codex
+```
+
+The executed runner uses `codex exec -s workspace-write --skip-git-repo-check --json --ephemeral` by default and writes run artifacts under `.codex-teams/<team>/runs/`. The runner only accepts `read-only` or `workspace-write` sandbox modes, never forwards danger-access flags, and passes the assembled prompt as one positional `codex exec` argument.
+
+Install the optional Codex skill:
+
+```bash
+codex-teams skill install
+```
+
+## How It Works
+
+`team.json` defines a team name, defaults, and 2 to 8 members. Member names become Codex agent types named `<team>-<member>`.
+
+Install renders each member to TOML with:
+
+- `name`
+- `description`
+- `model`
+- `sandbox_mode`
+- `nickname_candidates`
+- `developer_instructions`
+
+All TOML strings are basic strings with quotes, backslashes, newlines, and TOML control characters escaped. `nickname_candidates` is rendered as a string array.
+
+Existing unmanaged files are never overwritten unless `--force` is passed. Forced overwrites are backed up first. Uninstall only touches files recorded in the manifest for the selected target root.
+
+Project state lives in:
+
+```text
+.codex-teams/<team>/
+  state.json
+  tasks.json
+  journal.jsonl
+  artifacts/<member>/
+  runs/
+  locks/
+```
+
+`state.json` and `tasks.json` are written atomically under a mkdir lock. `journal.jsonl` is append-only under the same lock. Task claims use leases; expired claims are reclaimed by `task claim` and `task list --reclaim`. `CODEX_TEAMS_NOW` can override time for deterministic tests.
+
+Leader state commands are for the leader or a human operator. Members report through their final `TEAM-RESULT: <one-line summary>` line. Workspace-write members may also leave optional artifacts, but the final message is the canonical result channel.
+
+`doctor` reports the Codex binary, version, native feature state, model catalog availability, write access, and installed teams split into user and project scopes. `multi_agent` must be stable and enabled for a healthy native workflow. `enable_fanout` and `multi_agent_v2` are reported as under-development surfaces only.
+
+The package has zero runtime dependencies. Its package root exports only the supported high-level helpers for team parsing, install/uninstall, doctor, prompt/run planning, and durable state/task/note operations.
+
+## Attribution
+
+No third-party code is included; the state protocol is an original clean-room design.
+
+## Uninstall Rollback
+
+Remove an installed team:
+
+```bash
+codex-teams uninstall review-panel
+```
+
+For a sandbox or project scope, use the same target root used during install:
+
+```bash
+codex-teams uninstall review-panel --codex-home /tmp/codex-home
+codex-teams uninstall review-panel --scope project
+```
+
+Uninstall deletes only manifest-owned files. If install backed up an unmanaged file with `--force`, uninstall restores that backup. If an installed file changed after install, uninstall refuses to remove it so you can inspect the file manually.
+
+Remove the optional skill:
+
+```bash
+codex-teams skill uninstall
+```
+
+State under `.codex-teams/` is project-local runtime data. It is ignored by default when the project appears to be a git worktree. Delete `.codex-teams/<team>/` when you no longer need the task board, journal, runs, or artifacts.

package/dist/agents.d.ts

@@ -0,0 +1,38 @@
+import type { InstallScope, TeamDef, TeamsManifest } from "./types.js";
+export type InstallOptions = {
+    codexHome?: string;
+    scope?: InstallScope;
+    cwd?: string;
+    force?: boolean;
+    skipModelCheck?: boolean;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+};
+export type InstallResult = {
+    team: string;
+    scope: InstallScope;
+    targetRoot: string;
+    files: string[];
+    removed: string[];
+    warnings: string[];
+};
+export type UninstallResult = {
+    team: string;
+    scope: InstallScope;
+    targetRoot: string;
+    removed: string[];
+    restored: string[];
+    warnings: string[];
+};
+export declare function installTeam(teamPath: string, opts?: InstallOptions): InstallResult;
+export declare function installTeamDef(team: TeamDef, opts?: InstallOptions): InstallResult;
+export declare function uninstallTeam(team: string, opts?: InstallOptions): UninstallResult;
+export declare function renderAgentToml(team: TeamDef, memberName: string): string;
+export declare function resolveCodexHome(env?: NodeJS.ProcessEnv | Record<string, string | undefined>, explicit?: string): string;
+export declare function resolveAgentsRoot(scope: InstallScope, opts?: InstallOptions): string;
+export declare function manifestPath(targetRoot: string): string;
+export declare function readManifest(targetRoot: string, warnings?: string[]): TeamsManifest;
+export declare function writeManifest(targetRoot: string, manifest: TeamsManifest): void;
+export declare function findCodexBinary(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): string | null;
+export declare function listInstalledTeams(targetRoot: string): string[];
+export declare function parseModelCatalog(stdout: string): string[];
+export declare function backupSkillFile(file: string, backupDir: string): string;

package/dist/agents.js

@@ -0,0 +1,285 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, chmodSync, constants as fsConstants, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { assembleDeveloperInstructions } from "./prompt.js";
+import { memberAgentName, parseTeamJson, resolveMemberModel, resolveMemberSandbox } from "./team.js";
+import { renderToml } from "./toml.js";
+import { nowIso, readJson, writeFileAtomic, writeJsonAtomic } from "./state.js";
+import { assertConfinedRoot, isConfinedPath } from "./paths.js";
+export function installTeam(teamPath, opts = {}) {
+    const team = parseTeamJson(teamPath);
+    return installTeamDef(team, opts);
+}
+export function installTeamDef(team, opts = {}) {
+    const scope = opts.scope ?? "user";
+    const targetRoot = resolveAgentsRoot(scope, opts);
+    mkdirSync(targetRoot, { recursive: true });
+    if (scope === "project")
+        assertProjectRoot(targetRoot, opts);
+    const warnings = [];
+    const removed = [];
+    if (scope === "project") {
+        warnings.push("project scope requires a trusted Codex project; config.toml is not modified automatically");
+    }
+    if (!opts.skipModelCheck)
+        warnings.push(...checkModels(team, opts));
+    const manifest = readManifest(targetRoot, warnings);
+    const installedAt = nowIso(opts.env);
+    const newMembers = new Set(team.members.map(member => member.name));
+    const oldTeamEntries = manifest.entries.filter(entry => entry.team === team.name && entry.kind === "agent");
+    const nextEntries = manifest.entries.filter(entry => !(entry.team === team.name && entry.kind === "agent"));
+    const files = [];
+    for (const entry of oldTeamEntries) {
+        if (entry.member && newMembers.has(entry.member))
+            continue;
+        const unsafeReason = validateManagedEntry(entry, targetRoot, scope);
+        if (unsafeReason) {
+            warnings.push(`skipping stale cleanup for ${entry.file}: ${unsafeReason}`);
+            nextEntries.push(entry);
+            continue;
+        }
+        if (!existsSync(entry.file))
+            continue;
+        const currentHash = sha256(readFileSync(entry.file, "utf8"));
+        if (currentHash !== entry.hash) {
+            warnings.push(`stale managed agent changed since install; leaving in place: ${entry.file}`);
+            nextEntries.push(entry);
+            continue;
+        }
+        rmSync(entry.file, { force: true });
+        removed.push(entry.file);
+        warnings.push(`removed stale managed agent file: ${entry.file}`);
+    }
+    for (const member of team.members) {
+        const file = join(targetRoot, `${memberAgentName(team, member)}.toml`);
+        const content = renderAgentToml(team, member.name);
+        const existing = manifest.entries.find(entry => entry.file === file && entry.kind === "agent" && entry.scope === scope);
+        let backup = existing?.backup ?? null;
+        if (existsSync(file) && !existing) {
+            if (!opts.force)
+                throw new Error(`refusing to overwrite unmanaged agent file: ${file} (use --force to back it up first)`);
+            backup = backupFile(file, join(targetRoot, ".codex-teams-backups"));
+        }
+        writeFileAtomic(file, content);
+        files.push(file);
+        nextEntries.push({
+            team: team.name,
+            scope,
+            file,
+            backup,
+            hash: sha256(content),
+            kind: "agent",
+            member: member.name,
+            installed_at: installedAt,
+        });
+    }
+    writeManifest(targetRoot, { ...manifest, entries: nextEntries });
+    return { team: team.name, scope, targetRoot, files, removed, warnings };
+}
+export function uninstallTeam(team, opts = {}) {
+    const scope = opts.scope ?? "user";
+    const targetRoot = resolveAgentsRoot(scope, opts);
+    const warnings = [];
+    const manifest = readManifest(targetRoot, warnings);
+    const removed = [];
+    const restored = [];
+    const keep = [];
+    for (const entry of manifest.entries) {
+        if (entry.team !== team || entry.kind !== "agent") {
+            keep.push(entry);
+            continue;
+        }
+        const unsafeReason = validateManagedEntry(entry, targetRoot, scope);
+        if (unsafeReason) {
+            warnings.push(`skipping manifest entry for ${entry.file}: ${unsafeReason}`);
+            keep.push(entry);
+            continue;
+        }
+        if (existsSync(entry.file)) {
+            const currentHash = sha256(readFileSync(entry.file, "utf8"));
+            if (currentHash !== entry.hash)
+                throw new Error(`installed file 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(targetRoot, { ...manifest, entries: keep });
+    return { team, scope, targetRoot, removed, restored, warnings };
+}
+export function renderAgentToml(team, memberName) {
+    const member = team.members.find(item => item.name === memberName);
+    if (!member)
+        throw new Error(`unknown member: ${memberName}`);
+    const agentName = memberAgentName(team, member);
+    return renderToml({
+        name: agentName,
+        description: member.focus,
+        model: resolveMemberModel(team, member),
+        sandbox_mode: resolveMemberSandbox(team, member),
+        nickname_candidates: [member.name],
+        developer_instructions: assembleDeveloperInstructions(team, member),
+    });
+}
+export function resolveCodexHome(env = process.env, explicit) {
+    return resolve(explicit ?? env.CODEX_HOME ?? join(homedir(), ".codex"));
+}
+export function resolveAgentsRoot(scope, opts = {}) {
+    if (scope === "project") {
+        const projectRoot = realProjectRoot(opts.cwd ?? process.cwd());
+        return assertConfinedRoot(join(projectRoot, ".codex", "agents"), projectRoot);
+    }
+    return join(resolveCodexHome(opts.env, opts.codexHome), "agents");
+}
+export function manifestPath(targetRoot) {
+    return join(targetRoot, ".codex-teams-manifest.json");
+}
+export function readManifest(targetRoot, warnings = []) {
+    const path = manifestPath(targetRoot);
+    if (!existsSync(path))
+        return { version: 1, owner: "@codex-modules/teams", entries: [] };
+    const manifest = readJson(path);
+    if (manifest.version !== 1 || manifest.owner !== "@codex-modules/teams" || !Array.isArray(manifest.entries)) {
+        throw new Error(`unsupported teams manifest format: ${path}`);
+    }
+    return { ...manifest, entries: manifest.entries.flatMap((entry, index) => validateManifestEntry(entry, `${path} entries[${index}]`, warnings)) };
+}
+export function writeManifest(targetRoot, manifest) {
+    mkdirSync(targetRoot, { recursive: true });
+    writeJsonAtomic(manifestPath(targetRoot), manifest);
+}
+export function findCodexBinary(env = process.env) {
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (!pathValue)
+        return null;
+    const names = process.platform === "win32" ? ["codex.exe", "codex.cmd", "codex.bat", "codex"] : ["codex"];
+    for (const dir of pathValue.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = join(dir, name);
+            try {
+                accessSync(candidate, fsConstants.X_OK);
+                return candidate;
+            }
+            catch {
+                // keep searching
+            }
+        }
+    }
+    return null;
+}
+export function listInstalledTeams(targetRoot) {
+    return [...new Set(readManifest(targetRoot).entries.filter(entry => entry.kind === "agent").map(entry => entry.team))].sort();
+}
+function checkModels(team, opts) {
+    const warnings = [];
+    const bin = findCodexBinary(opts.env);
+    if (!bin)
+        return ["codex binary not found; skipping model catalog preflight"];
+    const result = spawnSync(bin, ["debug", "models"], {
+        env: { ...process.env, ...(opts.env ?? {}), CODEX_HOME: resolveCodexHome(opts.env, opts.codexHome) },
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 10_000,
+    });
+    if (result.status !== 0 || result.error) {
+        const reason = result.error ? result.error.message : result.stderr.trim();
+        return [`codex debug models unavailable; continuing without strict model preflight${reason ? ` (${reason})` : ""}`];
+    }
+    let catalog;
+    try {
+        catalog = parseModelCatalog(result.stdout);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return [`codex debug models returned non-JSON catalog; continuing without strict model preflight (${reason})`];
+    }
+    if (catalog.length === 0)
+        return ["codex debug models returned no parseable catalog entries; continuing"];
+    const available = new Set(catalog);
+    for (const member of team.members) {
+        const model = resolveMemberModel(team, member);
+        if (!available.has(model))
+            throw new Error(`model ${model} for member ${member.name} is not in codex debug models catalog`);
+    }
+    return warnings;
+}
+export function parseModelCatalog(stdout) {
+    const parsed = JSON.parse(stdout);
+    if (!isRecord(parsed) || !Array.isArray(parsed.models))
+        return [];
+    const values = new Set();
+    for (const item of parsed.models) {
+        if (!isRecord(item))
+            continue;
+        const value = typeof item.slug === "string" ? item.slug : typeof item.id === "string" ? item.id : null;
+        if (value)
+            values.add(value);
+    }
+    return [...values].sort();
+}
+function backupFile(file, backupDir) {
+    mkdirSync(backupDir, { recursive: true });
+    const backup = join(backupDir, `${basename(file)}.${new Date().toISOString().replace(/[:.]/g, "-")}.${process.pid}.bak`);
+    copyFileSync(file, backup);
+    try {
+        chmodSync(backup, statSync(file).mode & 0o777);
+    }
+    catch {
+        // best effort
+    }
+    return backup;
+}
+export function backupSkillFile(file, backupDir) {
+    return backupFile(file, backupDir);
+}
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function assertProjectRoot(targetRoot, opts) {
+    assertConfinedRoot(targetRoot, realProjectRoot(opts.cwd ?? process.cwd()));
+}
+function realProjectRoot(cwd) {
+    return statSync(resolve(cwd)).isDirectory() ? resolve(cwd) : dirname(resolve(cwd));
+}
+function validateManagedEntry(entry, targetRoot, scope) {
+    if (entry.scope !== scope)
+        return `scope ${entry.scope} does not match ${scope}`;
+    if (!entry.member)
+        return "agent entry is missing member";
+    if (!isConfinedPath(entry.file, targetRoot))
+        return "file path is outside target root";
+    if (entry.backup && !isConfinedPath(entry.backup, targetRoot))
+        return "backup path is outside target root";
+    return null;
+}
+function validateManifestEntry(value, label, warnings) {
+    if (!isRecord(value)) {
+        warnings.push(`skipping invalid manifest entry at ${label}: expected object`);
+        return [];
+    }
+    const backup = value.backup;
+    const kind = value.kind;
+    const scope = value.scope;
+    if (typeof value.team !== "string" ||
+        (scope !== "user" && scope !== "project" && scope !== "skill") ||
+        typeof value.file !== "string" ||
+        !(backup === undefined || backup === null || typeof backup === "string") ||
+        typeof value.hash !== "string" ||
+        (kind !== "agent" && kind !== "skill") ||
+        typeof value.installed_at !== "string" ||
+        (kind === "agent" && typeof value.member !== "string")) {
+        warnings.push(`skipping invalid manifest entry at ${label}: unsupported entry schema`);
+        return [];
+    }
+    return [value];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+void main(process.argv.slice(2));

package/dist/doctor.d.ts

@@ -0,0 +1,10 @@
+import type { DoctorReport } from "./types.js";
+export type DoctorOptions = {
+    codexHome?: string;
+    stateDir?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+};
+export declare function doctor(opts?: DoctorOptions): DoctorReport;
+export declare function doctorIsHealthy(report: DoctorReport): boolean;
+export declare function formatDoctor(report: DoctorReport): string;