spawnfile 0.1.14 → 0.1.17

package/dist/cli/usageCommand.d.ts

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import type { CliStreams } from "./runCli.js";
+import { type UsageCommandLiveHandlers } from "./usageCommandLive.js";
+/**
+ * `spawnfile usage` — what did this organization consume.
+ *
+ * A separate command from `status` on purpose. `status` answers "is it
+ * healthy"; usage answers "what did it consume". Different question, different
+ * cadence, and `status` must not read a growing ledger on every invocation.
+ *
+ * Every number this command prints is a LOWER BOUND. Neither metered engine's
+ * stream carries an incompleteness marker — grok's `streaming-messages-json`
+ * and AGY's `stream-json` both zero-fill a bucket they cannot account for — so
+ * a turn whose usage was partially zero-filled sums to a plausible total and is
+ * indistinguishable from a real one. Counts are therefore reported as `>=`, and
+ * coverage is always stated explicitly. AGY additionally reports no cost at
+ * all, so its notional column is always `—`.
+ */
+export interface UsageCommandOptions {
+    agent?: string;
+    exported?: string;
+    by?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    json?: boolean;
+    out?: string;
+    since?: string;
+    timeout?: string;
+    top?: string;
+}
+export interface UsageCommandResult {
+    error?: string;
+    /** The shared CLI convention (specs/SPEC.md §9.1, `errorExitCode`): 0 on
+     * success, 2 for a usage/input error, 1 for a runtime failure that surfaced
+     * after validation. */
+    exitCode: 0 | 1 | 2;
+    output?: string;
+}
+export declare const executeUsageCommand: (inputPath: string, options: UsageCommandOptions, handlers?: UsageCommandLiveHandlers) => Promise<UsageCommandResult>;
+export declare const registerUsageCommand: (program: Command, streams: CliStreams, setExitCode: (exitCode: 0 | 1 | 2) => void, handlers?: UsageCommandLiveHandlers) => void;

package/dist/cli/usageCommand.js

@@ -0,0 +1,284 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { listDeploymentRecords, parseExportIndex } from "../deployment/index.js";
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../runtime/daimon/contractManifest.js";
+import { readUsageLedgerViaExec } from "../runtime/usageLedgerRead.js";
+import { DEFAULT_OUTPUT_DIRECTORY, errorExitCode } from "../shared/index.js";
+import { computeUsageCoverage, dedupeUsageRecordsByTurn, DEFAULT_USAGE_SINCE, findConflictingUsageTurns, filterUsageRecordsSince, groupUsageByAgent, groupUsageByEngine, parseUsageSinceDuration } from "../runtime/usageLedger.js";
+import { resolveUsageDeploymentSource } from "./usageDeploymentSource.js";
+import { collectOrganizationUsage, rosterForRecord, selectUsageDeployment } from "./usageCommandLive.js";
+const inputFailure = (message) => ({ error: message, exitCode: 2 });
+const formatTokens = (value) => {
+    if (value === 0)
+        return "—";
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(1)}M`;
+    if (value >= 1_000)
+        return `${(value / 1_000).toFixed(1)}k`;
+    return String(value);
+};
+/**
+ * `—` means unknown, never free.
+ *
+ * A zero notional amount is never a claim worth printing: AGY's terminal frame
+ * carries no `total_cost_usd` at all, and Grok's decoder falls back to `0` for
+ * a cost it could not read. Rendering either as `$0.00` would advertise a free
+ * turn on a subscription that is being spent, which is precisely the silent
+ * loss this command exists to prevent.
+ */
+const formatUsd = (value, turns) => turns === 0 || value === 0 ? "—" : `$${value.toFixed(2)}`;
+const formatShare = (value, total) => total === 0 ? "—" : `${Math.round((value / total) * 100)}%`;
+/** An unreadable unit is UNKNOWN usage, never zero usage, so it always gets
+ * its own line and always forces the window's coverage to PARTIAL. */
+const renderUnreadableUnit = (unit) => unit.reason === "ledger_read_failed"
+    ? `UNREADABLE ${unit.unitId} (${unit.containerRef}): ledger read failed (${unit.detail ?? "no detail"}); its usage is unknown, not zero.`
+    : `UNREADABLE ${unit.unitId} (${unit.containerRef}): container ${unit.reason}; its ledger is not included.`;
+const pad = (value, width) => value.padEnd(width);
+const padStart = (value, width) => value.padStart(width);
+const renderTable = (usage, windowed, options) => {
+    const groupBy = options.by ?? "agent";
+    const coverage = computeUsageCoverage(windowed, usage.roster.length, usage.unreadableUnits.length);
+    const totalTokens = dedupeUsageRecordsByTurn(windowed).reduce((sum, record) => sum + record.total, 0);
+    const lines = [];
+    const coverageLabel = coverage.partial
+        ? `coverage PARTIAL (${coverage.agentsReporting} of ${coverage.agentsTotal} agents)`
+        : `coverage ${coverage.agentsReporting} of ${coverage.agentsTotal} agents`;
+    const sourceLabel = options.exported === undefined ? "" : ` · source exported ${options.exported}`;
+    lines.push(`ORG ${usage.deploymentName} · last ${options.since ?? DEFAULT_USAGE_SINCE}${sourceLabel} · ${coverageLabel}`);
+    lines.push("");
+    if (groupBy === "agent") {
+        let rows = groupUsageByAgent(windowed, usage.roster)
+            .sort((left, right) => right.tokens - left.tokens || left.agent.localeCompare(right.agent));
+        if (options.agent)
+            rows = rows.filter((row) => row.agent === options.agent);
+        if (options.top)
+            rows = rows.slice(0, Number(options.top));
+        const width = Math.max(8, ...rows.map((row) => row.agent.length));
+        lines.push(`${pad("agent", width)}  ${pad("engine", 8)}${padStart("turns", 7)}${padStart("tokens", 9)}${padStart("notional", 11)}${padStart("share", 7)}`);
+        for (const row of rows) {
+            lines.push(`${pad(row.agent, width)}  ${pad(row.engine ?? "—", 8)}${padStart(row.turns === 0 ? "—" : String(row.turns), 7)}${padStart(`${row.estimatedTurns > 0 ? "~" : ""}${formatTokens(row.tokens)}`, 9)}${padStart(formatUsd(row.notionalUsd, row.turns), 11)}${padStart(formatShare(row.tokens, totalTokens), 7)}`);
+        }
+        lines.push("─".repeat(width + 44));
+    }
+    const engineRows = groupUsageByEngine(windowed)
+        .sort((left, right) => right.tokens - left.tokens || left.engine.localeCompare(right.engine));
+    const engineWidth = Math.max(8, ...engineRows.map((row) => row.engine.length));
+    for (const row of engineRows) {
+        lines.push(`${pad(row.engine, engineWidth)}  ${pad("", 8)}${padStart(String(row.turns), 7)}${padStart(`${row.estimatedTurns > 0 ? "~" : ""}${formatTokens(row.tokens)}`, 9)}${padStart(formatUsd(row.notionalUsd, row.turns), 11)}`);
+    }
+    if (engineRows.length === 0)
+        lines.push("no metered turns in this window");
+    lines.push("");
+    lines.push("Counts are a lower bound: the engine stream carries no completeness marker.");
+    const conflicts = findConflictingUsageTurns(windowed);
+    if (conflicts.length > 0) {
+        lines.push(`WARNING ${conflicts.length} turn(s) carry differing ledger rows under one turn key; the first row is counted and coverage is PARTIAL: ${conflicts.map((turn) => turn.slice(0, 12)).join(", ")}`);
+    }
+    if (coverage.estimatedTurnCount > 0) {
+        const estimatedRequests = engineRows.reduce((sum, row) => sum + row.estimatedRequests, 0);
+        lines.push(`~ ${coverage.estimatedTurnCount} turn(s) include ESTIMATED usage: ${estimatedRequests} request(s) returned no provider-reported usage and were charged a conservative estimate, not a measurement.`);
+    }
+    if (coverage.incompleteRecordCount > 0) {
+        lines.push(`${coverage.incompleteRecordCount} turn(s) reported all-zero usage and are counted as unknown, not free.`);
+    }
+    for (const unit of usage.unreadableUnits) {
+        lines.push(renderUnreadableUnit(unit));
+    }
+    return lines.join("\n");
+};
+/** Where `artifactsExportPlan.ts` lands the ledger inside an exported run
+ * directory. Both halves are derived from the same pinned contract constant the
+ * export plan derives them from, so the two cannot drift apart. */
+const EXPORTED_USAGE_DIRECTORY = "raw/daimon";
+const exportedLedgerPaths = (exportedDirectory) => {
+    const resolve = (absoluteContainerPath) => path.join(exportedDirectory, EXPORTED_USAGE_DIRECTORY, path.posix.basename(absoluteContainerPath));
+    return {
+        filePath: resolve(DAIMON_GROK_TURN_USAGE_LEDGER.filePath),
+        rotatedFilePath: resolve(DAIMON_GROK_TURN_USAGE_LEDGER.rotatedFilePath)
+    };
+};
+/**
+ * Reads exported ledger bytes through the SAME reader the live path uses.
+ *
+ * `readUsageLedgerViaExec` is duck-typed on `exec(["cat", file])`, so feeding it
+ * a file-backed exec reuses the rotation ordering, the parse, and the
+ * absent-vs-unreadable classification verbatim rather than growing a second
+ * copy that could drift. A missing file is re-shaped into the failure a real
+ * `cat` produces — numeric exit code plus "No such file or directory" — because
+ * that is the exact shape the shared reader recognises as a legitimately absent
+ * generation. Every other filesystem error keeps its own `code`, which that
+ * reader treats as UNKNOWN rather than empty.
+ */
+const exportedLedgerExec = async (command) => {
+    const filePath = command[command.length - 1];
+    try {
+        return { stderr: "", stdout: await readFile(filePath, "utf8") };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            const message = `cat: ${filePath}: No such file or directory`;
+            throw Object.assign(new Error(message), { code: 1, stderr: message });
+        }
+        throw error;
+    }
+};
+/** `stat`, not a read: a rotated generation is at least 64 MiB, so probing for
+ * presence must not pull the bytes in only to throw them away. */
+const fileExists = async (filePath) => {
+    try {
+        return (await stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Reads one sealed, exported run instead of a live container.
+ *
+ * The roster still comes from the deployment record, exactly as the live path
+ * resolves it, so the coverage denominator means the same thing in both modes —
+ * that equivalence is the point, and it is what lets a single aggregation layer
+ * serve both.
+ *
+ * The one semantic that CANNOT be shared is what an absent ledger means. On a
+ * running container an absent file is genuinely "no turns yet", so the shared
+ * reader stays silent about it. In an export it means the bytes were never
+ * captured — a codex-only organization is never provisioned the volume, and an
+ * export taken before the first metered turn carries nothing — and neither of
+ * those is evidence that the organization cost nothing. So when the export
+ * carries no generation at all this reports an explicit unreadable unit, which
+ * forces coverage PARTIAL and keeps every notional column at `—`, rather than
+ * rendering a confident `$0.00` over a ledger nobody ever read.
+ */
+const collectExportedUsage = async (exportedDirectory, options, outputDirectory, handlers) => {
+    const indexPath = path.join(exportedDirectory, "spawnfile", "export-index.json");
+    let index;
+    try {
+        index = parseExportIndex(JSON.parse(await readFile(indexPath, "utf8")));
+    }
+    catch (error) {
+        return {
+            error: `Not a Spawnfile export directory: ${exportedDirectory} (${indexPath}: ${error instanceof Error ? error.message : String(error)}). Produce one with \`spawnfile artifacts export --out <dir>\`.`
+        };
+    }
+    const list = handlers.listDeploymentRecords ?? listDeploymentRecords;
+    const selected = selectUsageDeployment(await list(outputDirectory), options.deployment ?? index.deployment);
+    if ("error" in selected)
+        return selected;
+    const paths = exportedLedgerPaths(exportedDirectory);
+    const present = await Promise.all([fileExists(paths.filePath), fileExists(paths.rotatedFilePath)]);
+    if (!present.some(Boolean)) {
+        return {
+            deploymentName: selected.name,
+            records: [],
+            roster: rosterForRecord(selected),
+            runId: index.run_id,
+            unreadableUnits: [{
+                    containerRef: exportedDirectory,
+                    detail: `${EXPORTED_USAGE_DIRECTORY}/${path.posix.basename(DAIMON_GROK_TURN_USAGE_LEDGER.filePath)} is not in this export`,
+                    reason: "ledger_read_failed",
+                    unitId: `export:${index.run_id}`
+                }]
+        };
+    }
+    const read = await readUsageLedgerViaExec(exportedLedgerExec, paths);
+    return {
+        deploymentName: selected.name,
+        records: read.records,
+        roster: rosterForRecord(selected),
+        runId: index.run_id,
+        unreadableUnits: read.unreadable.map((failure) => ({
+            containerRef: exportedDirectory,
+            detail: `${failure.filePath}: ${failure.reason}`,
+            reason: "ledger_read_failed",
+            unitId: `export:${index.run_id}`
+        }))
+    };
+};
+export const executeUsageCommand = async (inputPath, options, handlers = {}) => {
+    const since = options.since ?? DEFAULT_USAGE_SINCE;
+    const sinceMs = parseUsageSinceDuration(since);
+    if (sinceMs === null) {
+        return inputFailure(`Invalid --since "${since}". Use a duration like 30m, 24h, or 7d.`);
+    }
+    if (options.by !== undefined && options.by !== "agent" && options.by !== "engine") {
+        return inputFailure(`Invalid --by "${options.by}". Use "agent" or "engine".`);
+    }
+    if (options.top !== undefined && !/^[1-9]\d*$/u.test(options.top)) {
+        return inputFailure(`Invalid --top "${options.top}". Use a positive integer.`);
+    }
+    const timeoutMs = options.timeout === undefined ? undefined : Number(options.timeout);
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        return inputFailure(`Invalid --timeout "${options.timeout}". Use a positive number of milliseconds.`);
+    }
+    const outputDirectory = resolveProjectOutputDirectory(inputPath, options.out, DEFAULT_OUTPUT_DIRECTORY);
+    let usage;
+    try {
+        const source = await resolveUsageDeploymentSource(inputPath, options, handlers, outputDirectory);
+        const sourceHandlers = { ...handlers, listDeploymentRecords: source.loader };
+        // Source selection is explicit, never inferred from what happens to be
+        // reachable: --exported reads that sealed run and never contacts Docker,
+        // and without it the live container is read exactly as before. Passing
+        // --exported alongside a running organization still reads the export --
+        // that is the point of naming it -- and the rendered header says which
+        // source produced the numbers so a reader is never left guessing.
+        usage = options.exported === undefined
+            ? await collectOrganizationUsage({
+                deployment: options.deployment,
+                dockerCommand: options.dockerCommand,
+                outputDirectory: source.outputDirectory,
+                timeoutMs
+            }, sourceHandlers)
+            : await collectExportedUsage(options.exported, options, source.outputDirectory, sourceHandlers);
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error), exitCode: errorExitCode(error) };
+    }
+    if ("error" in usage)
+        return inputFailure(usage.error);
+    const windowed = filterUsageRecordsSince(usage.records, sinceMs)
+        .filter((record) => options.agent === undefined || record.agent === options.agent);
+    if (options.json) {
+        const coverage = computeUsageCoverage(windowed, usage.roster.length, usage.unreadableUnits.length);
+        return {
+            exitCode: 0,
+            output: `${JSON.stringify({
+                version: "spawnfile.usage.v1",
+                deployment: usage.deploymentName,
+                source: options.exported === undefined ? "live" : "exported",
+                since,
+                lowerBound: true,
+                coverage,
+                byAgent: groupUsageByAgent(windowed, usage.roster),
+                byEngine: groupUsageByEngine(windowed),
+                unreadableUnits: usage.unreadableUnits
+            }, null, 2)}`
+        };
+    }
+    return { exitCode: 0, output: renderTable(usage, windowed, { ...options, since }) };
+};
+export const registerUsageCommand = (program, streams, setExitCode, handlers = {}) => {
+    program
+        .command("usage")
+        .description("Show what a deployed Spawnfile organization consumed, by agent and by engine")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--out <dir>", "Compile output directory")
+        .option("--exported <directory>", "Read a sealed run exported by `spawnfile artifacts export --out <dir>` instead of a live container")
+        .option("--deployment <name>", "Deployment record name")
+        .option("--since <duration>", `Window to report, e.g. 30m, 24h, 7d (default ${DEFAULT_USAGE_SINCE})`)
+        .option("--by <dimension>", "Group by \"agent\" (default) or \"engine\"")
+        .option("--agent <id>", "Report one agent")
+        .option("--top <n>", "Show only the n heaviest agents")
+        .option("--json", "Render machine-readable JSON")
+        .option("--docker-command <command>", "Docker command")
+        .option("--timeout <ms>", "Bound Docker reads in milliseconds")
+        .action(async (inputPath, options) => {
+        const result = await executeUsageCommand(inputPath, options, handlers);
+        setExitCode(result.exitCode);
+        if (result.error)
+            streams.stderr(`error: ${result.error}`);
+        if (result.output)
+            streams.stdout(result.output);
+    });
+};

package/dist/cli/usageCommandLive.d.ts

@@ -0,0 +1,84 @@
+import { createDockerProbeGateway, inspectDockerDeployment, listDeploymentRecords, listHomeDeploymentRecords, type DeploymentRecord } from "../deployment/index.js";
+import type { UsageRecord, UsageRosterEntry } from "../runtime/usageLedger.js";
+/**
+ * Transport for `spawnfile usage`.
+ *
+ * The ledger lives inside the container, and the host may be macOS Docker
+ * Desktop or a remote Docker context, so a host-side `readFile` is impossible.
+ * Reads therefore go through the sanctioned channel — the docker probe gateway,
+ * which already supports `--context` / `--host` remote targets and is already
+ * used to `cat` container files. `docker exec` runs as the image user (root for
+ * a Daimon image), so a 0640 uid-2100 ledger is readable.
+ *
+ * Deferred: the stopped-container post-mortem path. `spawnfile down`
+ * deliberately preserves volumes, so a stopped unit's ledger is still on disk,
+ * but `docker exec` cannot reach it; the repo's `docker create` + `docker cp`
+ * volume-egress pattern (`artifactsExportDocker.ts`) is the intended fallback.
+ * Until it lands, a stopped unit is reported as UNREADABLE — never silently as
+ * zero usage, which would misreport a dead subscription as a cheap one.
+ */
+/**
+ * Why a unit's usage is missing.
+ *
+ * `stopped`/`unreachable` are decided before any read is attempted, from the
+ * container inspection. `ledger_read_failed` is decided by the read itself
+ * (`readUsageLedgerViaExec`) and carries the generation and bounded reason in
+ * `detail`: the container was running and reachable, but one of its two ledger
+ * generations could not be `cat`ed — a `maxBuffer` overrun on a rotated
+ * generation, a timeout, or a daemon failure. All three mean the same thing
+ * for reporting: UNKNOWN usage, never zero.
+ */
+export interface UsageUnitReadFailure {
+    containerRef: string;
+    detail?: string;
+    reason: "ledger_read_failed" | "stopped" | "unreachable";
+    unitId: string;
+}
+export interface OrganizationUsage {
+    deploymentName: string;
+    records: UsageRecord[];
+    roster: UsageRosterEntry[];
+    unreadableUnits: UsageUnitReadFailure[];
+}
+export interface UsageCommandLiveHandlers {
+    createDockerProbeGateway?: typeof createDockerProbeGateway;
+    inspectDockerDeployment?: typeof inspectDockerDeployment;
+    listDeploymentRecords?: typeof listDeploymentRecords;
+    listHomeDeploymentRecords?: typeof listHomeDeploymentRecords;
+}
+export interface CollectOrganizationUsageOptions {
+    deployment?: string;
+    dockerCommand?: string;
+    outputDirectory: string;
+    timeoutMs?: number;
+}
+/**
+ * The org roster, from the deployment record itself.
+ *
+ * Engine assignment is not recorded per agent in a deployment record, so an
+ * agent's engine is learned from its own ledger records. An agent that never
+ * reports — every Codex agent, which is uninstrumented — keeps a `null` engine
+ * and renders as a dashed row. It still counts toward the coverage denominator,
+ * which is the whole point: a total computed over a partial roster must never be
+ * presented as the organization's cost.
+ */
+export declare const rosterForRecord: (record: DeploymentRecord) => UsageRosterEntry[];
+export declare const selectUsageDeployment: (records: Array<{
+    record: DeploymentRecord;
+}>, deployment?: string) => DeploymentRecord | {
+    error: string;
+};
+/**
+ * Read every unit's ledger and merge the results.
+ *
+ * A unit that is not running is recorded as unreadable rather than read as
+ * empty. A running unit whose ledger does not exist yet — the case before the
+ * first turn ever completes — reads as empty, never as an error, because
+ * `readUsageLedgerViaExec` treats an absent file (and only an absent file) as
+ * no content. Any other read failure comes back in that reader's `unreadable`
+ * list and is recorded here as a `ledger_read_failed` unit, so an unknown
+ * quantity of turns is never merged into the report as zero.
+ */
+export declare const collectOrganizationUsage: (options: CollectOrganizationUsageOptions, handlers?: UsageCommandLiveHandlers) => Promise<OrganizationUsage | {
+    error: string;
+}>;

package/dist/cli/usageCommandLive.js

@@ -0,0 +1,95 @@
+import { createDockerProbeGateway, inspectDockerDeployment, listDeploymentRecords } from "../deployment/index.js";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../runtime/daimon/contractManifest.js";
+import { readUsageLedgerViaExec } from "../runtime/usageLedgerRead.js";
+/**
+ * The org roster, from the deployment record itself.
+ *
+ * Engine assignment is not recorded per agent in a deployment record, so an
+ * agent's engine is learned from its own ledger records. An agent that never
+ * reports — every Codex agent, which is uninstrumented — keeps a `null` engine
+ * and renders as a dashed row. It still counts toward the coverage denominator,
+ * which is the whole point: a total computed over a partial roster must never be
+ * presented as the organization's cost.
+ */
+export const rosterForRecord = (record) => {
+    const agents = new Set();
+    for (const unit of record.units) {
+        for (const entry of unit.contains) {
+            if (entry.kind === "agent")
+                agents.add(entry.id);
+        }
+    }
+    return [...agents].sort().map((agent) => ({ agent, engine: null }));
+};
+const containerRefForUnit = (unit) => unit.container_id ?? unit.container_name ?? unit.id;
+export const selectUsageDeployment = (records, deployment) => {
+    if (records.length === 0) {
+        return { error: "No deployment records found. Run `spawnfile up` first." };
+    }
+    if (deployment) {
+        const match = records.find((entry) => entry.record.name === deployment);
+        return match
+            ? match.record
+            : { error: `Unknown deployment "${deployment}". Valid deployments: ${records.map((entry) => entry.record.name).sort().join(", ")}` };
+    }
+    if (records.length > 1) {
+        return { error: `spawnfile usage requires --deployment when multiple records exist: ${records.map((entry) => entry.record.name).sort().join(", ")}` };
+    }
+    return records[0].record;
+};
+/**
+ * Read every unit's ledger and merge the results.
+ *
+ * A unit that is not running is recorded as unreadable rather than read as
+ * empty. A running unit whose ledger does not exist yet — the case before the
+ * first turn ever completes — reads as empty, never as an error, because
+ * `readUsageLedgerViaExec` treats an absent file (and only an absent file) as
+ * no content. Any other read failure comes back in that reader's `unreadable`
+ * list and is recorded here as a `ledger_read_failed` unit, so an unknown
+ * quantity of turns is never merged into the report as zero.
+ */
+export const collectOrganizationUsage = async (options, handlers = {}) => {
+    const list = handlers.listDeploymentRecords ?? listDeploymentRecords;
+    const inspect = handlers.inspectDockerDeployment ?? inspectDockerDeployment;
+    const gatewayFor = handlers.createDockerProbeGateway ?? createDockerProbeGateway;
+    const selected = selectUsageDeployment(await list(options.outputDirectory), options.deployment);
+    if ("error" in selected)
+        return selected;
+    let inspections;
+    try {
+        inspections = await inspect(selected, { dockerCommand: options.dockerCommand, timeoutMs: options.timeoutMs });
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+    const records = [];
+    const unreadableUnits = [];
+    for (const unit of selected.units) {
+        const inspection = inspections.get(unit.id);
+        if (inspection?.running !== true) {
+            unreadableUnits.push({
+                containerRef: containerRefForUnit(unit),
+                reason: inspection?.exists === false || inspection?.running === false ? "stopped" : "unreachable",
+                unitId: unit.id
+            });
+            continue;
+        }
+        const gateway = gatewayFor(selected, unit, {
+            dockerCommand: options.dockerCommand,
+            inspection,
+            timeoutMs: options.timeoutMs
+        });
+        const exec = (command) => gateway.exec(command);
+        const read = await readUsageLedgerViaExec(exec, DAIMON_GROK_TURN_USAGE_LEDGER);
+        records.push(...read.records);
+        for (const failure of read.unreadable) {
+            unreadableUnits.push({
+                containerRef: containerRefForUnit(unit),
+                detail: `${failure.filePath}: ${failure.reason}`,
+                reason: "ledger_read_failed",
+                unitId: unit.id
+            });
+        }
+    }
+    return { deploymentName: selected.name, records, roster: rosterForRecord(selected), unreadableUnits };
+};

package/dist/cli/usageDeploymentSource.d.ts

@@ -0,0 +1,9 @@
+import type { UsageCommandOptions } from "./usageCommand.js";
+import type { UsageCommandLiveHandlers } from "./usageCommandLive.js";
+type UsageDeploymentRecordLoader = NonNullable<UsageCommandLiveHandlers["listDeploymentRecords"]>;
+export interface UsageDeploymentSource {
+    loader: UsageDeploymentRecordLoader;
+    outputDirectory: string;
+}
+export declare const resolveUsageDeploymentSource: (inputPath: string, options: UsageCommandOptions, handlers: UsageCommandLiveHandlers, outputDirectory: string) => Promise<UsageDeploymentSource>;
+export {};

package/dist/cli/usageDeploymentSource.js

@@ -0,0 +1,22 @@
+import { listDeploymentRecords, listHomeDeploymentRecords } from "../deployment/index.js";
+import { resolveCommandInput } from "./resolveCommandInput.js";
+export const resolveUsageDeploymentSource = async (inputPath, options, handlers, outputDirectory) => {
+    const listProject = handlers.listDeploymentRecords ?? listDeploymentRecords;
+    const listHome = handlers.listHomeDeploymentRecords ?? listHomeDeploymentRecords;
+    const commandInput = resolveCommandInput(inputPath);
+    const usedDefaultPath = inputPath === process.cwd();
+    if (options.out !== undefined || (!usedDefaultPath && commandInput.kind === "project")) {
+        return { loader: listProject, outputDirectory };
+    }
+    if (commandInput.kind === "image" || (options.deployment !== undefined && usedDefaultPath)) {
+        return { loader: listHome, outputDirectory };
+    }
+    if (usedDefaultPath) {
+        const projectRecords = await listProject(outputDirectory);
+        if (projectRecords.length > 0) {
+            return { loader: async () => projectRecords, outputDirectory };
+        }
+        return { loader: listHome, outputDirectory };
+    }
+    return { loader: listProject, outputDirectory };
+};

package/dist/cli/workspaceResourceMigrationCommand.d.ts

@@ -0,0 +1,8 @@
+import { migrateWorkspaceResource } from "../deployment/workspaceResourceMigration.js";
+export declare const isWorkspaceResourceMigrationInvocation: (argv: readonly string[]) => boolean;
+export interface WorkspaceResourceMigrationCommandDependencies {
+    migrate?: typeof migrateWorkspaceResource;
+    stderr?: (message: string) => void;
+    stdout?: (message: string) => void;
+}
+export declare const runWorkspaceResourceMigrationCommand: (argv: readonly string[], dependencies?: WorkspaceResourceMigrationCommandDependencies) => Promise<number>;

package/dist/cli/workspaceResourceMigrationCommand.js

@@ -0,0 +1,36 @@
+import { migrateWorkspaceResource } from "../deployment/workspaceResourceMigration.js";
+export const isWorkspaceResourceMigrationInvocation = (argv) => argv[0] === "workspace-resource" && argv[1] === "migrate";
+const usage = "usage: spawnfile workspace-resource migrate <source> <destination> --manifest <path> --resolved-identity <sha256> --source-quiesced [--json]";
+export const runWorkspaceResourceMigrationCommand = async (argv, dependencies = {}) => {
+    const stdout = dependencies.stdout ?? ((message) => process.stdout.write(`${message}\n`));
+    const stderr = dependencies.stderr ?? ((message) => process.stderr.write(`${message}\n`));
+    if (!isWorkspaceResourceMigrationInvocation(argv))
+        return 2;
+    const sourcePath = argv[2];
+    const destinationPath = argv[3];
+    const manifestIndex = argv.indexOf("--manifest");
+    const manifestPath = manifestIndex < 0 ? undefined : argv[manifestIndex + 1];
+    const identityIndex = argv.indexOf("--resolved-identity");
+    const resolvedIdentity = identityIndex < 0 ? undefined : argv[identityIndex + 1];
+    const quiescedIndex = argv.indexOf("--source-quiesced");
+    const allowed = new Set([0, 1, 2, 3, manifestIndex, manifestIndex + 1, identityIndex, identityIndex + 1, quiescedIndex, argv.indexOf("--json")].filter((index) => index >= 0));
+    if (!sourcePath || !destinationPath || !manifestPath || !resolvedIdentity || quiescedIndex < 0 || argv.some((_value, index) => !allowed.has(index))) {
+        stderr(usage);
+        return 2;
+    }
+    try {
+        const receipt = await (dependencies.migrate ?? migrateWorkspaceResource)({ destinationPath, manifestPath, resolvedIdentity, sourcePath, sourceQuiesced: true });
+        stdout(argv.includes("--json") ? JSON.stringify(receipt) : render(receipt));
+        return receipt.status === "activated" ? 0 : 1;
+    }
+    catch (error) {
+        stderr(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+};
+const render = (receipt) => [
+    `workspace resource migration: ${receipt.status}`,
+    `active: ${receipt.active_path}`,
+    `source retained: ${receipt.source_retained ? "yes" : "no"}`,
+    `rollback: ${receipt.rollback ? "yes" : "no"}`
+].join("\n");

package/dist/compiler/buildCompilePlanTeams.d.ts

@@ -1,4 +1,4 @@
-import type { TeamManifest } from "../manifest/index.js";
+import { type TeamManifest } from "../manifest/index.js";
 import type { ResolvedTeamNetwork, ResolvedTeamNode } from "./types.js";
 export declare const resolveTeamExternalIds: (manifest: TeamManifest) => string[];
 export declare const resolveTeamNetworks: (manifest: TeamManifest) => ResolvedTeamNetwork[];

package/dist/compiler/buildCompilePlanTeams.js

@@ -1,3 +1,4 @@
+import { isDeclaredPairedRemoteRoomMember } from "../manifest/index.js";
 import { SpawnfileError } from "../shared/index.js";
 export const resolveTeamExternalIds = (manifest) => {
     const memberIds = manifest.members.map((member) => member.id);
@@ -20,6 +21,9 @@ export const resolveTeamNetworks = (manifest) => (manifest.networks ?? []).map((
         name: network.name ?? network.id,
         provider: network.provider,
         rooms: network.rooms.map((room) => ({
+            ...(room.federation
+                ? { federation: Array.isArray(room.federation) ? [...room.federation].sort() : room.federation }
+                : {}),
             id: room.id,
             members: [...room.members],
             ...(room.name ? { name: room.name } : {}),
@@ -40,7 +44,8 @@ export const validateTeamNetworkRooms = (teamNode) => {
             for (const roomMemberId of room.members) {
                 const resolvedMember = teamNode.members.find((member) => member.id === roomMemberId);
                 if (!resolvedMember
-                    && !isAttachedExternalRoomMember(teamNode, network.id, roomMemberId)) {
+                    && !isAttachedExternalRoomMember(teamNode, network.id, roomMemberId)
+                    && !isDeclaredPairedRemoteRoomMember(network, room, roomMemberId)) {
                     throw new SpawnfileError("validation_error", `Team ${teamNode.name} Moltnet room ${room.id} references unknown member ${roomMemberId}`);
                 }
             }

package/dist/compiler/compilePlanHelpers.js

@@ -55,6 +55,9 @@ const collectMoltnetSecretNames = (server, secretNames) => {
     if (server.mode === "managed") {
         for (const pairing of server.pairings ?? []) {
             secretNames.add(pairing.token_secret);
+            if (pairing.relay) {
+                secretNames.add(pairing.relay.token_secret);
+            }
         }
         if (server.store.kind === "postgres") {
             secretNames.add(server.store.dsn_secret);

package/dist/compiler/compileProject.d.ts

@@ -7,6 +7,8 @@ export type { CreateOrganizationReadinessEvidenceInput, OrganizationReadinessEvi
 export interface CompileProjectOptions {
     clean?: boolean;
     containerArchitecture?: MoltnetTargetArchitecture;
+    /** Stable deployment identity for exclusive credential-realm reattachment. */
+    deploymentLineage?: string;
     outputDirectory?: string;
     /** Compile-time-only local overrides for runtime install npm packages
      * (see src/compiler/containerPackageOverrides.ts). Only opt-in