spawnfile 0.1.14 → 0.1.17

package/README.md

@@ -1,11 +1,11 @@
 # Spawnfile
 
-> A spec and compiler for autonomous agent runtimes. Write your agent once, compile for any runtime.
+> Write your agent team once. Compile it for different runtimes.
 
 <p align="center">
   <a href="https://www.npmjs.com/package/spawnfile"><img src="https://img.shields.io/npm/v/spawnfile?style=flat-square&color=d4604a&label=npm" alt="npm"></a>
   <a href="https://www.npmjs.com/package/spawnfile"><img src="https://img.shields.io/npm/dm/spawnfile?style=flat-square&color=d4604a" alt="downloads"></a>
-  <a href="#from-source"><img src="https://img.shields.io/node/v/spawnfile?style=flat-square&color=d4604a" alt="node"></a>
+  <a href="#try-it"><img src="https://img.shields.io/node/v/spawnfile?style=flat-square&color=d4604a" alt="node"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/spawnfile?style=flat-square&color=d4604a" alt="MIT"></a>
   <a href="https://spawnfile.com"><img src="https://img.shields.io/website?url=https%3A%2F%2Fspawnfile.com&style=flat-square&label=spawnfile.com&color=d4604a" alt="website"></a>
 </p>
@@ -14,195 +14,96 @@
   <img src="website/public/new-claw-images.png" alt="Spawnfile compiles one agent source into multiple runtimes" width="420" />
 </p>
 
-Spawnfile is a **portable source format** for autonomous agents and teams. You write one canonical project — identity docs, skills, MCP connections, model and sandbox intent, team structure, and declared communication surfaces — and `spawnfile compile` lowers it into the runtime-specific config and workspace each adapter needs.
+Describe your agents, give them identities and tools, and keep the whole team in one source project. Spawnfile compiles that project into the configuration and workspaces their runtimes need, then builds and deploys it with Docker.
 
-It's not a runtime-to-runtime translator. The compiler starts from the canonical source, emits each declared adapter's output, and reports per-capability support as `supported`, `degraded`, or `unsupported`.
-
-Pairs with [**Moltnet**](https://moltnet.dev) as the first provider for `team.networks[]`, letting compiled agents share declared rooms, DMs, and history across runtimes without Spawnfile injecting its own message router.
-
-For a Simfile linked to a Spawnfile, the product entrypoint is owned by
-Simfile:
-
-```bash
-simfile run ./Simfile --view
-```
-
-That command delegates only organization lifecycle operations to Spawnfile's
-public CLI and versioned receipts. Spawnfile prepares target resources,
-deploys the organization, records the pinned Pi-bridge Moltnet identity,
-exports evidence, and cleans up; it does not carry simulation behavior or
-trigger cognition. The world reaches paused/pristine readiness first, the
-organization starts second, and one attested activation releases independent
-world ticks and organization-owned schedules. A separately manifested
-`simfile.world-decision-claim.v1` capability may extend the base world-sidecar
-ABI without changing it. See
-[`specs/ECOSYSTEM_RUNTIME_BOUNDARIES.md`](specs/ECOSYSTEM_RUNTIME_BOUNDARIES.md)
-for ownership and [`specs/TARGETS.md`](specs/TARGETS.md) for target, auth,
-Moltnet pinning, recovery, and cleanup contracts.
-
-## Install
-
-```bash
-npm install -g spawnfile
-spawnfile --version
-spawnfile --help
+```text
+Spawnfile + workspace ─→ compile ─→ runtime files
 ```
 
-Node.js 22+ required. See [source install](#from-source) for local development.
+## Try it
 
-## The happy path
+Start with one agent. Requires **Node.js 22.19+**; compilation needs no Docker or model credentials.
 
 ```bash
-spawnfile init                                   # scaffold an agent (defaults to openclaw)
-spawnfile validate                               # check the graph
-spawnfile view .                                 # read-only graph view; writes no files
-spawnfile compile                                # lower to runtime-native output
-spawnfile status .                               # read declared/compiled status
-spawnfile auth sync --profile dev --env-file .env
-spawnfile build  --tag my-agent                  # compile + docker build
-spawnfile up . --context gpu-4090 --detach       # build and run on a Docker context
-spawnfile dev up . --auth-profile dev            # detached dev loop in .spawn-dev
-spawnfile dev apply . --agent researcher         # hot-add/reload one Pi agent
-spawnfile dev activity . --agent researcher      # inspect buffered Pi activity events
-spawnfile run    --tag my-agent --auth-profile dev --detach
-spawnfile status . --live                        # inspect the detached deployment
-spawnfile publish . --tag you/my-agent:1.0.0     # compile + build + verify + push
+npm install -g spawnfile
+spawnfile init my-agent
+cd my-agent
+spawnfile validate
+spawnfile compile
 ```
 
-Compiled output lands under `.spawn/` by default, including a `Dockerfile`, `entrypoint.sh`, `.env.example`, and a prebuilt `container/rootfs/` tree. `spawnfile build` uses the pinned runtime artifacts from `runtimes.yaml`; it does not rebuild runtimes from source. Daimon, OpenClaw, and PicoClaw use published copyable artifact images by default, so normal prompt/config edits reuse their dependency layers. To test a local runtime artifact instead, set `SPAWNFILE_DAIMON_RUNTIME_IMAGE`, `SPAWNFILE_OPENCLAW_RUNTIME_IMAGE`, or `SPAWNFILE_PICOCLAW_RUNTIME_IMAGE` to a local image tag. For `build`/`up` on a docker `--context`, Moltnet release assets are staged for that context's architecture (`amd64` or `arm64`); for local-only manual compile targeting a fixed architecture, set `SPAWNFILE_MOLTNET_TARGET_ARCH=amd64|arm64`.
-
-`spawnfile status` is read-only. By default it shows authored and compiled state without Docker, runtime, or Moltnet calls. With `--live`, it reads the selected detached deployment record, inspects the recorded Docker target, runs adapter-owned runtime probes, and checks Moltnet metadata without reading message bodies. Add `--logs` for a redacted Docker log tail, or `--watch` to refresh status continuously. For a remote Docker context where the local record is missing, pass `--context <name>` with `--live` to recover the deployment from Spawnfile container labels.
-
-`spawnfile dev` is the source-backed interactive loop. It uses `.spawn-dev/` by default, starts a detached dev deployment with `spawnfile dev up`, and can hot-apply one Daimon runtime agent with `spawnfile dev apply --agent <id>` without restarting the rest of the org. Hot apply recompiles source, copies the selected agent workspace, Daimon config, matching Moltnet node configs, and managed Moltnet server configs into the running container, loads it through the Daimon control endpoint, and starts only that agent's Moltnet bridges when it is new. `spawnfile dev activity` reads the generated Daimon app's bounded activity buffer as JSON lines so operators can see queued wakes, turn starts/completions, runtime event types, output completions, and errors without mixing those diagnostics into Moltnet chat. Running managed Moltnet servers keep their current in-memory room membership until an operator-token `moltnet apply` or server restart reconciles the copied server config.
+`init` creates an OpenClaw project with `IDENTITY.md`, `SOUL.md`, and `AGENTS.md`. `compile` writes runtime configuration, the generated workspace, and container files into `.spawn/`. Read `spawnfile-report.json` there to see how your source was compiled. **The agent is configured, but has not started.**
 
-Compiled images are self-describing: `spawnfile publish` pushes one to any OCI registry, and anyone can run it with no source — `spawnfile up you/my-agent:1.0.0 --deployment prod --detach --auth-profile me` — or inspect what it needs first with `spawnfile status you/my-agent:1.0.0`. See [`specs/DISTRIBUTION.md`](specs/DISTRIBUTION.md).
+Edit the Markdown files to define who the agent is and what it should do, then compile again. Keep the source in Git; `.spawn/` is generated and ignored.
 
-### Target adapter CLI
+## From one agent to a team
 
-`spawnfile target` is the explicit, non-interactive target-adapter boundary for
-an external orchestrator. It takes one absolute request JSON file and one
-strict private configuration object on standard input — never a configuration
-path or inline configuration:
+A team has its own `Spawnfile`, which references the member agent projects. Create its directory with `spawnfile init my-team --team`. Once you have two projects with distinct agent names under `my-team/agents/`, put their references in `my-team/Spawnfile`:
 
-```bash
-target-config-producer | spawnfile target --config - create_data_network /absolute/path/request.json
+```yaml
+spawnfile_version: "0.1"
+kind: team
+name: research-team
+mode: swarm
+members:
+  - id: researcher
+    ref: ./agents/researcher
+  - id: writer
+    ref: ./agents/writer
 ```
 
-On success it writes exactly one canonical JSON receipt followed by a newline.
-
-For a crash-safe machine caller handoff, project-mode `up --json`, `artifacts export
---json`, and `down --json` accept `--lifecycle-invocation lci_<stable-id>`. Spawnfile
-binds that id to the exact operation, correlation, and request policy, atomically stores
-the exact JSON bytes after the owner returns and before stdout, and rejects reuse with
-drift. `spawnfile lifecycle lookup <id>` is read-only and returns one versioned state:
-`not_applied`, `pending`, `completed`, or `ambiguous`, without Docker/provider
-inspection. Recovery only resumes an operation when that command verifies exact durable
-evidence that resumption is safe; otherwise it seals `ambiguous` and fails closed.
-It writes no secret values to output or diagnostics. The full verb list,
-request/receipt contract, and exit behavior are in [`specs/TARGETS.md`](specs/TARGETS.md).
-`target lookup_operation` accepts the original mutation request with a minimal
-read-only context config and reports `completed`, `pending`, or `not_applied`
-without calling the target provider or changing its journal.
-
-Declare external credentials in `secrets:` and provide values through an ignored env file or the shell environment. `spawnfile auth sync --env-file .env` stores declared model auth and project secrets in a local auth profile; `spawnfile run --env-file .env` can inject the same values directly for a single run. This is the intended pattern for credentials like `GH_TOKEN`, MCP tokens, and provider API keys.
-
-## Project structure
+Each member has its own Spawnfile, identity, and runtime. Teams can share instructions and resources, contain nested teams, and declare [Moltnet](https://moltnet.dev) rooms. The [team guide](https://spawnfile.com/guides/teams/) covers the full setup; [examples](examples/) show complete projects.
 
-A Spawnfile project is either an `agent` or a `team`.
+## What travels with your team
 
-**Agent**
+- **Agents:** Identity documents, instructions, skills, workspace resources, and each agent’s wake schedule.
+- **Tools and models:** MCP connections, model selection, and declared secret requirements.
+- **Team structure:** Members, nested teams, and shared resources.
+- **Communication:** Declared [Moltnet](https://moltnet.dev) networks and rooms for agents to exchange messages across runtimes.
+- **Deployment:** Runtime configuration, container files, and a capability report built from the same source.
 
-```text
-my-agent/
-├── Spawnfile
-├── IDENTITY.md         # who the agent is
-├── SOUL.md             # tone and personality
-├── AGENTS.md           # system prompt
-├── MEMORY.md           # long-lived memory
-├── HEARTBEAT.md        # periodic prompt for scheduled wakes
-├── skills/
-│   └── web_search/SKILL.md
-└── subagents/
-    └── researcher/Spawnfile
-```
+A team declaration alone does not create a conversation or a useful division of work. Give the agents a task, configure their communication, and choose how they wake. Start with the [team guide](https://spawnfile.com/guides/teams/) and [example projects](examples/).
 
-**Team**
+## Run and share it
 
-```text
-my-team/
-├── Spawnfile
-├── TEAM.md
-├── shared/skills/...
-└── agents/
-    ├── orchestrator/Spawnfile
-    ├── researcher/Spawnfile
-    └── writer/Spawnfile
-```
+Once the prompts and configuration are ready:
 
-Team members may target different runtimes; the compiler resolves each member independently. Subagents are internal helpers owned by a parent agent — not the same thing as team members. Team coordination is through shared declared agent surfaces and declared team networks, not a Spawnfile-owned router.
+1. **Provide credentials.** Import an existing subscription login or configure provider credentials with [auth profiles](https://spawnfile.com/guides/docker/). Keep secret values out of Git.
+2. **Build and start.** With Docker available, `spawnfile up . --detach --auth-profile <profile>` compiles, builds, and starts the project. A Docker context can target another machine.
+3. **Check the deployment.** `spawnfile status . --live` probes the running deployment; `spawnfile status .` reads only local declared and compiled state.
+4. **Share an image.** `spawnfile publish` packages the project for an OCI registry so another operator can run it without the source, using their own credentials.
 
-Not every file is required. Spawnfile names the portable roles; adapters decide how to lower them into runtime-native surfaces. See [`specs/SPEC.md`](specs/SPEC.md) for the full shape.
+See [container deployment](specs/CONTAINERS.md), [status](specs/STATUS.md), and [image distribution](specs/DISTRIBUTION.md) for complete commands and requirements.
 
 ## Runtime support
 
-v0.1 targets autonomous agent runtimes that share a markdown workspace identity model.
-
-| Runtime   | Status        | Default | Surfaces                                      |
-|-----------|---------------|---------|-----------------------------------------------|
-| OpenClaw  | active        | ✅      | Discord, Telegram, WhatsApp, Slack            |
-| PicoClaw  | active        |         | Discord, Telegram, Slack (WhatsApp blocked)   |
-| Pi        | active        |         | Embedded org app, Moltnet client config       |
-| OpenFang  | exploratory   |         | No active adapter yet                         |
-| Hermes Agent | exploratory |        | No active adapter yet                         |
-| OpenCode  | exploratory   |         | No active adapter yet                         |
-
-Each adapter maps the portable schema into its native forms. The compiler reports a machine-readable `spawnfile-report.json` with the resolved graph, chosen runtimes, and capability outcomes (`supported`, `degraded`, `unsupported`). See [`specs/RUNTIMES.md`](specs/RUNTIMES.md) for the live matrix and pinned versions, or [`runtimes.yaml`](runtimes.yaml) for the registry source of truth.
-
-## Why
-
-Autonomous agent runtimes already share a meaningful core: markdown workspace identity, skill folders, MCP, model selection, sandboxing. Today that core is re-authored by hand for each runtime. Spawnfile makes it canonical so one source project can ship to any compatible runtime.
-
-## Docs
+| Runtime | Use it for |
+|---|---|
+| **Daimon** | Agents using subscription CLI engines such as Codex and Claude Code, with Moltnet and memory integration. |
+| **OpenClaw** | OpenClaw agents and their native messaging surfaces. The default agent scaffold. |
+| **PicoClaw** | PicoClaw agents and their native messaging surfaces. |
 
-Hosted docs with rendered specs, runtime guides, and a capability matrix: **[spawnfile.com](https://spawnfile.com)** — start at [Introduction](https://spawnfile.com/introduction/), [Quickstart](https://spawnfile.com/quickstart/), or the [Runtimes overview](https://spawnfile.com/runtimes/overview/).
+Daimon requires a pinned runtime image matching the compiler contract. The older `pi` adapter remains available for existing projects.
 
-The source-of-truth specs live in this repo:
+Portability is capability-specific: the compiler reports each feature as **supported**, **degraded**, or **unsupported**. Read that report before switching runtimes. Exact versions live in [runtimes.yaml](runtimes.yaml); the [runtime specification](specs/RUNTIMES.md) describes the adapter model.
 
-- [`specs/INDEX.md`](specs/INDEX.md) — map of all specs
-- [`specs/SPEC.md`](specs/SPEC.md) — canonical source format
-- [`specs/COMPILER.md`](specs/COMPILER.md) — compiler architecture and adapter contract
-- [`specs/CONTAINERS.md`](specs/CONTAINERS.md) — container compilation
-- [`specs/RUNTIMES.md`](specs/RUNTIMES.md) — runtime registry and version pinning
-- [`specs/SURFACES.md`](specs/SURFACES.md) — messaging surface model
-- [`specs/STATUS.md`](specs/STATUS.md) — static and live operational status
-- [`specs/DISTRIBUTION.md`](specs/DISTRIBUTION.md) — image distribution, publish, and sourceless run
-- [`test/fixtures/`](test/fixtures/) — canonical example projects
-
-## From source
-
-```bash
-git clone https://github.com/noopolis/spawnfile.git
-cd spawnfile
-nvm use
-npm install
-npm run build
-npm link
-```
-
-For local development without linking globally:
-
-```bash
-npm run dev -- validate test/fixtures/single-agent
-```
+## Go further
 
-## Contributing
+| I want to… | Read |
+|---|---|
+| Understand the source format | [Spawnfile specification](specs/SPEC.md) |
+| Explore complete projects | [Examples](examples/) |
+| Add an adapter or contribute | [Contributing](CONTRIBUTING.md) |
+| Integrate with deployment tooling | [Target and lifecycle contracts](specs/TARGETS.md) |
+| Plan isolated agent training | [Paideia training handoff](specs/TRAINING.md) |
+| Find a detailed contract | [Specification index](specs/INDEX.md) |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, tests, and the runtime adapter contract.
+Spawnfile is part of [Noopolis](https://github.com/noopolis). [Moltnet](https://moltnet.dev) supplies messaging; [Daimon](https://github.com/noopolis/daimon) runs individual agents; [Simfile](https://simfile.org) builds simulation worlds around organizations. You can use Spawnfile on its own.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+[MIT](LICENSE)
 
 ---
 
-**[spawnfile.com](https://spawnfile.com)** · **[github.com/noopolis/spawnfile](https://github.com/noopolis/spawnfile)**
+**[spawnfile.com](https://spawnfile.com)** · **[Examples](examples/)** · **[Contributing](CONTRIBUTING.md)**

package/dist/audit/checksShared.d.ts

@@ -1,7 +1,7 @@
 /**
  * Evidence input types and small pure helpers shared by every check function
  * in checks.ts. Split out purely to keep checks.ts under the repo's 400-line
- * cap (see /Users/apresmoi/Documents/spawnfile/CLAUDE.md) — nothing here is
+ * cap (see the repo CLAUDE.md) — nothing here is
  * a different layer or a different contract, it is checks.ts's own
  * plumbing. No I/O, same as checks.ts itself.
  */

package/dist/auth/importers.d.ts

@@ -4,5 +4,15 @@ interface ClaudeCodeImportOptions {
 export declare const parseEnvFile: (content: string) => Record<string, string>;
 export declare const importEnvFile: (profileName: string, envFilePath: string) => Promise<import("./types.js").ResolvedAuthProfile>;
 export declare const importCodexAuth: (profileName: string, sourceDirectory?: string) => Promise<import("./types.js").ResolvedAuthProfile>;
+/**
+ * Imports a **dedicated** Grok login into a profile.
+ *
+ * Unlike Codex, the source is always explicit: training rotates the credential
+ * it is given, so defaulting to `~/.grok` would let a routine training run
+ * invalidate the developer's own desktop session, and the refreshed token
+ * would land on container tmpfs rather than back in `~/.grok` (D2). The
+ * desktop home is refused outright, by resolved path and through `GROK_HOME`.
+ */
+export declare const importGrokAuth: (profileName: string, sourceDirectory: string | undefined) => Promise<import("./types.js").ResolvedAuthProfile>;
 export declare const importClaudeCodeAuth: (profileName: string, sourceDirectory?: string, options?: ClaudeCodeImportOptions) => Promise<import("./types.js").ResolvedAuthProfile>;
 export {};

package/dist/auth/importers.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import os from "node:os";
-import { ensureDirectory, fileExists, readUtf8File, writeUtf8File } from "../filesystem/index.js";
+import { fileExists, readUtf8File, writePrivateUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { registerImportedAuth, setAuthProfileEnv } from "./profileStore.js";
 const ENV_LINE_PATTERN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/;
@@ -67,7 +67,33 @@ export const importCodexAuth = async (profileName, sourceDirectory) => {
         throw new SpawnfileError("validation_error", `Codex auth file does not exist: ${authFilePath}`);
     }
     const { directory, profile } = await registerImportedAuth(profileName, "codex");
-    await writeUtf8File(path.join(directory, "auth.json"), await readUtf8File(authFilePath));
+    await writePrivateUtf8File(path.join(directory, "auth.json"), await readUtf8File(authFilePath));
+    return profile;
+};
+/**
+ * Imports a **dedicated** Grok login into a profile.
+ *
+ * Unlike Codex, the source is always explicit: training rotates the credential
+ * it is given, so defaulting to `~/.grok` would let a routine training run
+ * invalidate the developer's own desktop session, and the refreshed token
+ * would land on container tmpfs rather than back in `~/.grok` (D2). The
+ * desktop home is refused outright, by resolved path and through `GROK_HOME`.
+ */
+export const importGrokAuth = async (profileName, sourceDirectory) => {
+    if (!sourceDirectory) {
+        throw new SpawnfileError("validation_error", "Grok import requires --from <directory> holding a dedicated training login; training never uses the desktop ~/.grok");
+    }
+    const resolvedSource = path.resolve(sourceDirectory);
+    const desktop = path.resolve(process.env.GROK_HOME ?? path.join(os.homedir(), ".grok"));
+    if (resolvedSource === desktop || resolvedSource === path.join(os.homedir(), ".grok")) {
+        throw new SpawnfileError("validation_error", `Refusing the desktop Grok home ${resolvedSource}; a training run rotates the credential it imports`);
+    }
+    const authFilePath = path.join(resolvedSource, "auth.json");
+    if (!(await fileExists(authFilePath))) {
+        throw new SpawnfileError("validation_error", `Grok auth file does not exist: ${authFilePath}`);
+    }
+    const { directory, profile } = await registerImportedAuth(profileName, "grok");
+    await writePrivateUtf8File(path.join(directory, "auth.json"), await readUtf8File(authFilePath));
     return profile;
 };
 export const importClaudeCodeAuth = async (profileName, sourceDirectory, options = {}) => {
@@ -87,7 +113,6 @@ export const importClaudeCodeAuth = async (profileName, sourceDirectory, options
         throw new SpawnfileError("validation_error", `Claude Code credentials file does not exist: ${credentialsPath} and macOS Keychain service ${CLAUDE_CODE_KEYCHAIN_SERVICE} was unavailable`);
     }
     const { directory, profile } = await registerImportedAuth(profileName, "claude-code");
-    await ensureDirectory(directory);
-    await writeUtf8File(path.join(directory, ".credentials.json"), credentialsContent);
+    await writePrivateUtf8File(path.join(directory, ".credentials.json"), credentialsContent);
     return profile;
 };

package/dist/auth/index.d.ts

@@ -10,3 +10,5 @@ export * from "./credentialProvisioningRequest.js";
 export * from "./credentialWorldBindings.js";
 export * from "./targetSecretSourceLifecycle.js";
 export * from "./targetSecretSourceResolver.js";
+export { stageTrainingAuth } from "./trainingAuth.js";
+export type { TrainingAuthStageOptions, TrainingAuthProvider } from "./trainingAuth.js";

package/dist/auth/index.js

@@ -10,3 +10,4 @@ export * from "./credentialProvisioningRequest.js";
 export * from "./credentialWorldBindings.js";
 export * from "./targetSecretSourceLifecycle.js";
 export * from "./targetSecretSourceResolver.js";
+export { stageTrainingAuth } from "./trainingAuth.js";

package/dist/auth/paths.d.ts

@@ -3,7 +3,7 @@ export declare const resolveAuthHome: () => string;
 export declare const resolveProfilesRoot: () => string;
 export declare const resolveProfileDirectory: (profileName: string) => string;
 export declare const resolveProfilePath: (profileName: string) => string;
-export declare const resolveImportedAuthDirectory: (profileName: string, kind: "claude-code" | "codex") => string;
+export declare const resolveImportedAuthDirectory: (profileName: string, kind: "claude-code" | "codex" | "grok") => string;
 export declare const resolveTargetSecretsRoot: () => string;
 export declare const resolveTargetSecretVersionsDirectory: () => string;
 export declare const resolveTargetSecretVersionPath: (versionKey: string) => string;

package/dist/auth/profileStore.js

@@ -1,8 +1,8 @@
 import path from "node:path";
 import { z } from "zod";
-import { ensureDirectory, fileExists, readUtf8File, removeDirectory, writeUtf8File } from "../filesystem/index.js";
+import { ensurePrivateDirectory, fileExists, readUtf8File, removeDirectory, writePrivateUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
-import { resolveAuthHome, resolveImportedAuthDirectory, resolveProfileDirectory, resolveProfilePath } from "./paths.js";
+import { resolveAuthHome, resolveImportedAuthDirectory, resolveProfileDirectory, resolveProfilePath, resolveProfilesRoot } from "./paths.js";
 const importedAuthEntrySchema = z.object({
     kind: z.enum(["claude-code", "codex"]),
     relativePath: z.string().min(1)
@@ -68,15 +68,14 @@ export const ensureAuthProfile = async (profileName) => {
     if (existing) {
         return existing;
     }
-    const profileDirectory = resolveProfileDirectory(profileName);
-    await ensureDirectory(profileDirectory);
-    await writeUtf8File(resolveProfilePath(profileName), `${JSON.stringify(createEmptyProfile(), null, 2)}\n`);
-    return createResolvedAuthProfile(profileName, createEmptyProfile());
+    return writeProfile(profileName, createEmptyProfile());
 };
 const writeProfile = async (profileName, profile) => {
     const profileDirectory = resolveProfileDirectory(profileName);
-    await ensureDirectory(profileDirectory);
-    await writeUtf8File(resolveProfilePath(profileName), `${JSON.stringify(profile, null, 2)}\n`);
+    await ensurePrivateDirectory(resolveAuthHome());
+    await ensurePrivateDirectory(resolveProfilesRoot());
+    await ensurePrivateDirectory(profileDirectory);
+    await writePrivateUtf8File(resolveProfilePath(profileName), `${JSON.stringify(profile, null, 2)}\n`);
     return createResolvedAuthProfile(profileName, profile);
 };
 export const setAuthProfileEnv = async (profileName, env) => {
@@ -99,8 +98,9 @@ export const setAuthProfileEnv = async (profileName, env) => {
 export const registerImportedAuth = async (profileName, kind) => {
     const current = (await loadAuthProfile(profileName)) ?? (await ensureAuthProfile(profileName));
     const importDirectory = resolveImportedAuthDirectory(profileName, kind);
+    await ensurePrivateDirectory(path.dirname(importDirectory));
     await removeDirectory(importDirectory);
-    await ensureDirectory(importDirectory);
+    await ensurePrivateDirectory(importDirectory);
     const nextProfile = {
         env: { ...current.env },
         imports: {

package/dist/auth/targetSecretSourceFsIdentity.d.ts

@@ -0,0 +1,40 @@
+import { type BigIntStats } from "node:fs";
+export type DirectoryIdentity = Readonly<{
+    birthtimeNs: bigint;
+    dev: bigint;
+    ino: bigint;
+    mode: bigint;
+    uid: bigint;
+}>;
+export type FileIdentity = Readonly<{
+    birthtimeNs: bigint;
+    ctimeNs: bigint;
+    dev: bigint;
+    ino: bigint;
+    mode: bigint;
+    nlink: bigint;
+    size: number;
+    uid: bigint;
+}>;
+/** Validates one mode-`0700` owner-held directory and reduces it to its identity. */
+export declare const directoryIdentityOf: (info: BigIntStats, owner: number) => DirectoryIdentity;
+/** Validates one mode-`0600` owner-held regular file and reduces it to its identity. */
+export declare const fileIdentityOf: (info: BigIntStats, owner: number, links: readonly number[], maxBytes: number, zero?: boolean) => FileIdentity;
+/**
+ * Same directory node. Never compares ctime: the publisher mutates the leaf
+ * directory's ctime itself every time it links or unlinks an election name.
+ */
+export declare const sameDirectory: (left: DirectoryIdentity, right: DirectoryIdentity) => boolean;
+/** Same file, unchanged in every observable field including ctime and size. */
+export declare const sameFileExact: (left: FileIdentity, right: FileIdentity) => boolean;
+/**
+ * Same file node, allowing the size and ctime to move. This is the growing
+ * final: an identical writer may legitimately append the rest of the record
+ * between two observations, which changes both.
+ */
+export declare const sameFileNode: (left: FileIdentity, right: FileIdentity) => boolean;
+/**
+ * Same inode, allowing the link count and ctime to move. This is the zero-byte
+ * token or claim while an identical publisher links or unlinks the other name.
+ */
+export declare const sameFileInode: (left: FileIdentity, right: FileIdentity) => boolean;

package/dist/auth/targetSecretSourceFsIdentity.js

@@ -0,0 +1,42 @@
+import { TARGET_SECRET_SOURCE_ERROR } from "./targetSecretSourceRecordCommon.js";
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+/** Validates one mode-`0700` owner-held directory and reduces it to its identity. */
+export const directoryIdentityOf = (info, owner) => {
+    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== BigInt(owner) || (info.mode & 4095n) !== 448n)
+        fail();
+    return { birthtimeNs: info.birthtimeNs, dev: info.dev, ino: info.ino, mode: info.mode, uid: info.uid };
+};
+/** Validates one mode-`0600` owner-held regular file and reduces it to its identity. */
+export const fileIdentityOf = (info, owner, links, maxBytes, zero = false) => {
+    if (!info.isFile() || info.isSymbolicLink() || info.uid !== BigInt(owner)
+        || !links.some((link) => info.nlink === BigInt(link)) || (info.mode & 4095n) !== 384n
+        || info.size < 0n || info.size > BigInt(maxBytes) || (zero && info.size !== 0n))
+        fail();
+    return {
+        birthtimeNs: info.birthtimeNs, ctimeNs: info.ctimeNs, dev: info.dev, ino: info.ino,
+        mode: info.mode, nlink: info.nlink, size: Number(info.size), uid: info.uid
+    };
+};
+/**
+ * Same directory node. Never compares ctime: the publisher mutates the leaf
+ * directory's ctime itself every time it links or unlinks an election name.
+ */
+export const sameDirectory = (left, right) => left.birthtimeNs === right.birthtimeNs && left.dev === right.dev && left.ino === right.ino
+    && left.mode === right.mode && left.uid === right.uid;
+/** Same file, unchanged in every observable field including ctime and size. */
+export const sameFileExact = (left, right) => left.birthtimeNs === right.birthtimeNs && left.ctimeNs === right.ctimeNs && left.dev === right.dev
+    && left.ino === right.ino && left.mode === right.mode && left.nlink === right.nlink
+    && left.size === right.size && left.uid === right.uid;
+/**
+ * Same file node, allowing the size and ctime to move. This is the growing
+ * final: an identical writer may legitimately append the rest of the record
+ * between two observations, which changes both.
+ */
+export const sameFileNode = (left, right) => left.birthtimeNs === right.birthtimeNs && left.dev === right.dev && left.ino === right.ino
+    && left.mode === right.mode && left.nlink === right.nlink && left.uid === right.uid;
+/**
+ * Same inode, allowing the link count and ctime to move. This is the zero-byte
+ * token or claim while an identical publisher links or unlinks the other name.
+ */
+export const sameFileInode = (left, right) => left.birthtimeNs === right.birthtimeNs && left.dev === right.dev && left.ino === right.ino
+    && left.mode === right.mode && left.size === right.size && left.uid === right.uid;

package/dist/auth/targetSecretSourceFsPublish.d.ts

@@ -6,6 +6,8 @@ export interface TargetSecretSourceFsPublishInput {
     readonly private_metadata: Pick<TargetSecretSourcePrivateVersionMetadata, "publication_handle" | "source_version_handle">;
 }
 export interface TargetSecretSourceFsPublishOptions {
+    readonly contentionForTest?: (reason: string, attempt: number) => void;
+    readonly errorForTest?: (error: unknown) => void;
     readonly hookForTest?: (phase: TargetSecretSourceFsPublishPhase, path: string) => Promise<void> | void;
     readonly maxWriteBytesForTest?: number;
 }

package/dist/auth/targetSecretSourceFsPublish.js

@@ -13,6 +13,7 @@ export const initializeTargetSecretSourceFsPublish = async (options = {}) => {
             resolveTargetSecretsRoot(),
             resolveTargetSecretVersionsDirectory()
         ],
+        contentionForTest: options.contentionForTest,
         hookForTest: options.hookForTest,
         maxWriteBytesForTest: options.maxWriteBytesForTest
     });
@@ -41,7 +42,8 @@ export const initializeTargetSecretSourceFsPublish = async (options = {}) => {
                 }
             });
         }
-        catch {
+        catch (error) {
+            options.errorForTest?.(error);
             fail();
         }
     };

package/dist/auth/targetSecretSourceFsPublishImmutable.d.ts

@@ -1,4 +1,4 @@
-export type TargetSecretSourceFsPublishImmutablePhase = "after_token_create" | "after_claim_link" | "after_claim_snapshot" | "after_mismatch_snapshot" | "after_exact_token_snapshot" | "after_final_create" | "after_partial_write" | "after_file_sync" | "before_directory_sync" | "after_directory_sync" | "after_token_cleanup" | "after_claim_cleanup";
+export type TargetSecretSourceFsPublishImmutablePhase = "after_token_create" | "after_claim_link" | "after_claim_snapshot" | "after_mismatch_snapshot" | "after_exact_token_snapshot" | "after_final_create" | "after_partial_write" | "after_file_sync" | "before_directory_sync" | "after_directory_sync" | "after_token_cleanup" | "after_claim_cleanup" | "after_zero_lstat" | "after_final_lstat" | "after_token_open" | "after_token_sync" | "after_final_open" | "before_unlink_exact" | "before_contention_retry";
 export interface TargetSecretSourceFsPublishImmutableInput {
     readonly bytes: Uint8Array;
     readonly final_path: string;
@@ -7,6 +7,7 @@ export interface TargetSecretSourceFsPublishImmutableInput {
 }
 export interface TargetSecretSourceFsPublishImmutableOptions {
     readonly directory_chain: readonly string[];
+    readonly contentionForTest?: (reason: string, attempt: number) => void;
     readonly hookForTest?: (phase: TargetSecretSourceFsPublishImmutablePhase, path: string) => Promise<void> | void;
     readonly maxWriteBytesForTest?: number;
 }