@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/lib/runner.js

@@ -44,17 +44,20 @@ export function buildJobCommand(config, resolvedPrompt) {
         const cmd = ['agents', 'run', config.workflow, resolvedPrompt, '--mode', config.mode];
         return cmd;
     }
+    // Past the workflow branch this is an agent (or resume) job — command jobs never
+    // reach buildJobCommand (execute*Job branches out first), and validateJob guarantees agent.
+    const agent = config.agent;
     // Resume branch: reopen an EXISTING session via `agents run <agent> --resume <id>`
     // instead of starting fresh. The real session resumes with its full prior context
     // (index-based lookup, cwd-independent) and `resolvedPrompt` becomes its next turn —
     // so a self-scheduled wake (e.g. /hibernate) is handled by the session that scheduled
     // it, not a fresh, context-less agent that would refuse an "opaque" instruction.
     if (config.resume) {
-        return ['agents', 'run', config.agent, '--resume', config.resume, resolvedPrompt, '--mode', config.mode];
+        return ['agents', 'run', agent, '--resume', config.resume, resolvedPrompt, '--mode', config.mode];
     }
-    const template = AGENT_COMMANDS[config.agent];
+    const template = AGENT_COMMANDS[agent];
     if (!template) {
-        throw new Error(`Unsupported agent for daemon jobs: ${config.agent}`);
+        throw new Error(`Unsupported agent for daemon jobs: ${agent}`);
     }
     let cmd = template.map((part) => part.replace('{prompt}', resolvedPrompt));
     // Canonicalize mode (accepts legacy `full` as alias for `skip`).
@@ -155,10 +158,12 @@ export function buildJobCommand(config, resolvedPrompt) {
  * Reasoning level (config.config.reasoning) maps to per-agent flags via models.ts.
  */
 function appendModelAndReasoning(cmd, config) {
+    // Only called from buildJobCommand's agent path — config.agent is set.
+    const agent = config.agent;
     const model = config.config?.model;
     if (model) {
         if (config.version) {
-            const resolved = resolveModel(config.agent, config.version, model);
+            const resolved = resolveModel(agent, config.version, model);
             if (resolved.warning) {
                 process.stderr.write(`[agents] ${resolved.warning}\n`);
             }
@@ -170,7 +175,7 @@ function appendModelAndReasoning(cmd, config) {
     }
     const reasoning = config.config?.reasoning;
     if (reasoning) {
-        const flags = buildReasoningFlags(config.agent, reasoning);
+        const flags = buildReasoningFlags(agent, reasoning);
         if (flags.length > 0)
             cmd.push(...flags);
     }
@@ -178,6 +183,48 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/**
+ * Build the argv for a command-mode routine: run the shell string directly
+ * through the platform shell. No agent binary, no rotation, no sandbox.
+ */
+function buildShellCommand(command) {
+    return process.platform === 'win32'
+        ? ['cmd', '/c', command]
+        : ['/bin/sh', '-c', command];
+}
+/**
+ * Real (un-sandboxed) environment for a command routine. Command routines do
+ * `npm i -g` / `git pull` and need the actual $HOME / $PATH, not the sandbox
+ * overlay. Only TZ is injected when the routine pins a timezone.
+ */
+function commandSpawnEnv(config) {
+    const env = { ...process.env };
+    if (config.timezone)
+        env.TZ = config.timezone;
+    return env;
+}
+/** POSIX single-quote a string so it is safe to embed in a `/bin/sh -c` script. */
+function shSingleQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Detached command routines write their own exit code to `<runDir>/exit-code`
+ * (see the wrapper in executeCommandJobDetached). `monitorRunningJobs` reads it
+ * to recover the true terminal status when the daemon restarted between spawn and
+ * exit and so missed the in-process `child.on('exit')`. Returns null when the
+ * file is absent/unparseable (child killed or crashed before writing it).
+ */
+function readCommandExitCode(runDir) {
+    try {
+        const raw = fs.readFileSync(path.join(runDir, 'exit-code'), 'utf-8').trim();
+        if (!/^-?\d+$/.test(raw))
+            return null;
+        return parseInt(raw, 10);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the version/account chain for a routine the same way `agents run`
  * does: honor an explicit `version:` pin; otherwise use the configured run
@@ -191,6 +238,8 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
     if (config.workflow) {
         return { chain: [], rotation: null, pinned: false };
     }
+    // resolveRoutineLaunch is only called for agent jobs (workflow returns above;
+    // command jobs branch out of execute*Job before reaching this).
     const agent = config.agent;
     if (config.version) {
         const version = config.version;
@@ -399,6 +448,12 @@ export async function executeJob(config, deps) {
     if (eligibility) {
         throw new Error(eligibility.message);
     }
+    // Command-mode: run a plain shell command directly (no agent, no rotation,
+    // no pinning, no sandbox overlay). Reuses the run-record machinery so
+    // list/runs/overdue keep working.
+    if (config.command) {
+        return executeCommandJobForeground(config);
+    }
     maybeRotate();
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
@@ -425,6 +480,7 @@ export async function executeJob(config, deps) {
         : { ...process.env };
     // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
     // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
+    // (command jobs branched out earlier, so config.agent is set on the non-workflow path.)
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
@@ -561,6 +617,100 @@ export async function executeJob(config, deps) {
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
 }
+/**
+ * Foreground execution for a command-mode routine (`config.command`). Runs a
+ * plain shell command in the REAL environment (no sandbox), captures stdout+
+ * stderr to `stdout.log`, awaits completion, and honors `config.timeout` with
+ * the same SIGTERM→SIGKILL kill mechanism the agent path uses. No agent is
+ * spawned; the run record carries `command` instead of `agent`. There is no
+ * agent report to extract, so `reportPath` is always null (the stdout log is
+ * the artifact — same location the agent path writes).
+ */
+async function executeCommandJobForeground(config) {
+    const timer = createTimer('agent.run', {
+        jobName: config.name,
+        mode: config.mode,
+        schedule: config.schedule,
+    });
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const stdoutPath = path.join(runDir, 'stdout.log');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
+    const meta = {
+        jobName: config.name,
+        runId,
+        command: config.command,
+        pid: null,
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+    };
+    writeRunMeta(meta);
+    const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
+    const cmd = buildShellCommand(config.command);
+    const env = commandSpawnEnv(config);
+    process.stderr.write(`[agents] routine ${config.name}: running command\n`);
+    const result = await new Promise((resolve) => {
+        const child = spawn(cmd[0], cmd.slice(1), {
+            stdio: ['ignore', stdoutFd, stdoutFd],
+            ...backgroundSpawnOptions({ fdStdio: true }),
+            env,
+        });
+        meta.pid = child.pid || null;
+        writeRunMeta(meta);
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                fs.closeSync(stdoutFd);
+            }
+            catch { /* fd already closed */ }
+            resolve(r);
+        };
+        const timeoutTimer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGTERM');
+            }
+            catch { /* process already exited */ }
+            setTimeout(() => {
+                try {
+                    if (child.pid)
+                        process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* process already exited */ }
+            }, 5000);
+            finish({ exitCode: null, status: 'timeout' });
+        }, timeoutMs);
+        child.on('exit', (code) => {
+            clearTimeout(timeoutTimer);
+            finish({ exitCode: code, status: code === 0 ? 'completed' : 'failed' });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeoutTimer);
+            finish({ exitCode: 1, status: 'failed', error: err.message });
+        });
+    });
+    meta.status = result.status;
+    meta.exitCode = result.exitCode ?? (result.status === 'completed' ? 0 : 1);
+    meta.completedAt = new Date().toISOString();
+    writeRunMeta(meta);
+    if (result.error) {
+        process.stderr.write(`[agents] routine ${config.name}: command spawn failed: ${result.error}\n`);
+    }
+    timer.end({
+        status: meta.status,
+        exitCode: meta.exitCode ?? undefined,
+        runId,
+        ...(result.error ? { error: result.error } : {}),
+    });
+    return { meta, reportPath: null };
+}
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
     const eligibility = checkJobDeviceEligibility(config);
@@ -568,6 +718,12 @@ export async function executeJobDetached(config) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
+    // Command-mode: fire a plain shell command detached (no agent, no rotation,
+    // no pinning, no sandbox overlay). Still writes a run record so the daemon,
+    // list/runs, and overdue tracking keep working.
+    if (config.command) {
+        return executeCommandJobDetached(config);
+    }
     // Pre-flight: pick a healthy version/account so the daemon does not launch
     // into a credit-exhausted install. Detached cannot mid-run failover (no exit
     // wait); the next schedule tick re-selects if this attempt still fails.
@@ -577,7 +733,7 @@ export async function executeJobDetached(config) {
     let cmd = buildJobCommand(config, resolvedPrompt);
     // workflow AND resume dispatch through `agents run` — never binary-pin them (pinning
     // rewrites cmd[0] to the agent binary → broken `<binary> run …`).
-    if (!dispatchesViaAgentsRun(config) && version) {
+    if (!dispatchesViaAgentsRun(config) && version && config.agent) {
         cmd = pinJobBinary(cmd, config.agent, version);
     }
     // Resume must run against the REAL home: `--resume <id>` resolves the session from
@@ -601,6 +757,7 @@ export async function executeJobDetached(config) {
                 e.TZ = config.timezone;
             return e;
         })()
+        // Non-command path only: config.agent is always set here (command/workflow branch earlier).
         : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone);
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
@@ -640,6 +797,74 @@ export async function executeJobDetached(config) {
     writeRunMeta(meta);
     return meta;
 }
+/**
+ * Detached (fire-and-forget) execution for a command-mode routine. Mirrors the
+ * agent detached flow: write an initial running record, spawn the shell command
+ * un-sandboxed, unref, then record the pid. The daemon does not wait for exit;
+ * `monitorRunningJobs` reaps the record on the next tick.
+ */
+function executeCommandJobDetached(config) {
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const stdoutPath = path.join(runDir, 'stdout.log');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
+    // Wrap the shell so the child records its own exit code to <runDir>/exit-code.
+    // The in-process `child.on('exit')` below writes the terminal record while the
+    // daemon is alive (the common case); the file lets monitorRunningJobs recover
+    // the real status if the daemon restarted between spawn and exit. (win32 relies
+    // on the exit event only.)
+    const exitCodePath = path.join(runDir, 'exit-code');
+    // Run the command in a SUBSHELL `( … )` so that if it calls `exit`, only the
+    // subshell exits — the outer shell still captures `$?` and writes the file.
+    const cmd = process.platform === 'win32'
+        ? buildShellCommand(config.command)
+        : ['/bin/sh', '-c',
+            `(\n${config.command}\n)\n__ac_rc=$?; printf '%s' "$__ac_rc" > ${shSingleQuote(exitCodePath)} 2>/dev/null; exit $__ac_rc`];
+    const env = commandSpawnEnv(config);
+    const meta = {
+        jobName: config.name,
+        runId,
+        command: config.command,
+        pid: null,
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+    };
+    const child = spawn(cmd[0], cmd.slice(1), {
+        stdio: ['ignore', stdoutFd, stdoutFd],
+        ...backgroundSpawnOptions({ fdStdio: true }),
+        env,
+    });
+    // Record the real terminal status ourselves — the daemon stays alive after this
+    // fire-and-forget call, so the exit event fires here. (monitorRunningJobs no
+    // longer force-fails command jobs; it reads exit-code only on the restart edge.)
+    let settled = false;
+    const settle = (status, exitCode) => {
+        if (settled)
+            return;
+        settled = true;
+        meta.status = status;
+        meta.exitCode = exitCode;
+        meta.completedAt = new Date().toISOString();
+        writeRunMeta(meta);
+    };
+    child.on('exit', (code) => settle(code === 0 ? 'completed' : 'failed', code ?? 1));
+    child.on('error', (err) => {
+        settle('failed', 1);
+        process.stderr.write(`[agents] daemon: command spawn failed for job "${config.name}": ${err.message}\n`);
+    });
+    child.unref();
+    try {
+        fs.closeSync(stdoutFd);
+    }
+    catch { /* fd already closed */ }
+    meta.pid = child.pid || null;
+    writeRunMeta(meta);
+    return meta;
+}
 function extractAndSaveReport(stdoutPath, agentType, runDir) {
     try {
         const report = extractReport(stdoutPath, agentType);
@@ -792,26 +1017,43 @@ export function monitorRunningJobs() {
                     continue;
                 const runDirPath = path.join(jobRunsPath, runDirEntry.name);
                 const stdoutPath = path.join(runDirPath, 'stdout.log');
+                // Command-mode records carry no agent; there is no stream-json report to
+                // parse or extract. Reap them on pid liveness alone.
+                const isCommandRun = Boolean(meta.command) || !meta.agent;
                 const wallClockMs = Date.now() - Date.parse(meta.startedAt);
                 if (Number.isFinite(wallClockMs) && wallClockMs > MAX_WALL_CLOCK_MS) {
                     meta.status = 'timeout';
                     meta.completedAt = new Date().toISOString();
                     writeRunMeta(meta);
-                    extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+                    if (!isCommandRun)
+                        extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
                     continue;
                 }
                 if (!isPidOurs(meta.pid, meta.spawnedAt)) {
-                    const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
-                    if (inferred) {
-                        meta.status = inferred.status;
-                        meta.exitCode = inferred.exitCode;
+                    if (isCommandRun) {
+                        // Command routines normally record their own terminal status via
+                        // child.on('exit') (so this record would already be non-'running' and
+                        // skipped above). Reaching here means the daemon restarted mid-run and
+                        // missed the exit event — recover the true code from the exit-code file
+                        // the child wrote; its absence means the child was killed/crashed.
+                        const ec = readCommandExitCode(runDirPath);
+                        meta.status = ec === 0 ? 'completed' : 'failed';
+                        meta.exitCode = ec;
                     }
                     else {
-                        meta.status = 'failed';
+                        const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
+                        if (inferred) {
+                            meta.status = inferred.status;
+                            meta.exitCode = inferred.exitCode;
+                        }
+                        else {
+                            meta.status = 'failed';
+                        }
                     }
                     meta.completedAt = new Date().toISOString();
                     writeRunMeta(meta);
-                    extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+                    if (!isCommandRun)
+                        extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
                 }
             }
             catch { /* corrupt or unreadable meta.json */ }

package/dist/lib/sandbox.d.ts

@@ -9,7 +9,15 @@
 import type { JobConfig } from './routines.js';
 /** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<string, string>): Record<string, string>;
-/** Get the overlay HOME directory path for a named job. */
+/**
+ * Get the overlay HOME directory path for a named job.
+ *
+ * The job name originates from routine YAML (`name:` field or file basename),
+ * which can arrive from a synced user/system config repo. `safeJoin` contains
+ * it to a single segment beneath the routines dir so a crafted name such as
+ * `../../../..` cannot steer `prepareJobHome`/`cleanJobHome` (which does a
+ * recursive `rmSync`) at a path outside `~/.agents/routines`.
+ */
 export declare function getJobHomePath(name: string): string;
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig): string;

package/dist/lib/sandbox.js

@@ -11,6 +11,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 import { createLink } from './platform/index.js';
 function resolveRealHome() {
     const home = os.homedir();
@@ -79,9 +80,17 @@ export function buildSpawnEnv(overlayHome, extraEnv) {
     }
     return env;
 }
-/** Get the overlay HOME directory path for a named job. */
+/**
+ * Get the overlay HOME directory path for a named job.
+ *
+ * The job name originates from routine YAML (`name:` field or file basename),
+ * which can arrive from a synced user/system config repo. `safeJoin` contains
+ * it to a single segment beneath the routines dir so a crafted name such as
+ * `../../../..` cannot steer `prepareJobHome`/`cleanJobHome` (which does a
+ * recursive `rmSync`) at a path outside `~/.agents/routines`.
+ */
 export function getJobHomePath(name) {
-    return path.join(getRoutinesDir(), name, 'home');
+    return path.join(safeJoin(getRoutinesDir(), name), 'home');
 }
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export function prepareJobHome(config) {

package/dist/lib/session/bundle.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Portable session bundle — the on-the-wire format behind `agents sessions
+ * export` / `import` (RUSH-1710 / RUSH-1711).
+ *
+ * A bundle is a self-describing NDJSON stream: the FIRST line is a
+ * {@link BundleHeader}, every subsequent line is one {@link BundleRecord} (one
+ * constituent file of a session). NDJSON — not tar — because the bundle has to
+ * pipe cleanly over `agents ssh … export --stdout | … import -` (RUSH-1712)
+ * without any external archiver on either box, stays inspectable with `head`,
+ * and lets each file body carry its own encryption envelope.
+ *
+ * This module owns the FORMAT and the import PLACEMENT only; selecting which
+ * sessions to export (which needs the session DB) lives in the export command.
+ * Placement reuses the sync mirror model verbatim: a foreign machine's session
+ * lands at {@link mirrorPath}(spec, originMachine, relKey), exactly where the
+ * cross-machine sync writes it — so the existing scanner indexes it as a
+ * machine-tagged row and "local always wins" falls out of the scanner's
+ * live-home-first dedup with no extra logic here.
+ */
+import { type SyncAgentSpec } from './sync/agents.js';
+export declare const BUNDLE_KIND = "agents-session-bundle";
+export declare const BUNDLE_VERSION = 1;
+/** First line of a bundle: what it is and how the bodies are encoded. */
+export interface BundleHeader {
+    kind: typeof BUNDLE_KIND;
+    version: number;
+    /** ISO timestamp the bundle was produced. */
+    exportedAt: string;
+    /** Machine that produced the bundle (informational; per-record `machine` is authoritative for placement). */
+    origin: string;
+    /** True when record bodies are AES-256-GCM envelopes (see transcript-crypto). */
+    encrypted: boolean;
+    /** True when bodies were secret-scrubbed before hashing/sealing. */
+    redacted: boolean;
+    /** Number of file records that follow. */
+    count: number;
+    /** Distinct session count across those records. */
+    sessions: number;
+}
+/** One constituent file of one session. Dir-shaped sessions emit several, sharing `sessionId`. */
+export interface BundleRecord {
+    /** SYNC_AGENTS id (claude, codex, kimi, …). */
+    agent: string;
+    /** ORIGIN machine of this session — where placement mirrors it to. */
+    machine: string;
+    sessionId: string;
+    /** Storage-relative key within the agent's subdir (preserved on import). */
+    relKey: string;
+    /** Byte length of the plaintext body. */
+    size: number;
+    /** SHA-256 of the plaintext body — identity + byte-exact dedup. */
+    hash: string;
+    /** Human label carried from SessionMeta, if any. */
+    label?: string;
+    /** True when `body` is an encryption envelope rather than plaintext. */
+    encrypted: boolean;
+    /** File content: plaintext, or a transcript-crypto envelope when `encrypted`. */
+    body: string;
+}
+export interface ParsedBundle {
+    header: BundleHeader;
+    records: BundleRecord[];
+}
+/** A single file selected for export, resolved to an absolute on-disk path. */
+export interface FileToExport {
+    agent: string;
+    /** Origin machine of the session (self for live-home, the peer for a mirror). */
+    machine: string;
+    sessionId: string;
+    relKey: string;
+    absPath: string;
+    label?: string;
+}
+export interface BuildRecordOpts {
+    /** Scrub secrets from the body before hashing/sealing (default-on at the command layer). */
+    redact: boolean;
+    /** Non-null → seal each body with this key; null → plaintext bodies. */
+    encryptKey: Buffer | null;
+}
+/** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
+export declare function specForAgent(agentId: string): SyncAgentSpec | undefined;
+/** True when an agent's sessions can be represented in a bundle (has a sync spec). */
+export declare function isExportableAgent(agentId: string): boolean;
+/**
+ * Read one file and turn it into a bundle record. The hash and size are always
+ * computed over the PLAINTEXT (post-redaction) body, so they equal what lands on
+ * disk after import — keeping dedup byte-exact whether or not the bundle is
+ * encrypted.
+ */
+export declare function buildRecord(file: FileToExport, opts: BuildRecordOpts): BundleRecord;
+/** Build the header for a set of records. */
+export declare function makeHeader(args: {
+    origin: string;
+    exportedAt: string;
+    encrypted: boolean;
+    redacted: boolean;
+    records: BundleRecord[];
+}): BundleHeader;
+/**
+ * Merge record sets from several bundles (e.g. a fan-out pull across hosts),
+ * deduping by agent + origin machine + session + file so the same session seen
+ * from two peers lands once. First occurrence wins.
+ */
+export declare function mergeRecords(sets: BundleRecord[][]): BundleRecord[];
+/** Serialize a bundle to its NDJSON wire form (header line + one line per record). */
+export declare function serializeBundle(header: BundleHeader, records: BundleRecord[]): string;
+/** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
+export declare function parseBundle(text: string): ParsedBundle;
+/** Placement outcome for one record, computed against what is already on disk. */
+export type ImportStatus = 'new' | 'dup' | 'conflict' | 'unknown';
+export interface ImportPlanItem {
+    record: BundleRecord;
+    /** Absolute path the file lands at (empty for `unknown` agents). */
+    targetPath: string;
+    status: ImportStatus;
+}
+export interface PlanImportOpts {
+    /** Key to open encrypted record bodies (null → only plaintext bodies readable). */
+    decryptKey: Buffer | null;
+}
+/**
+ * Compute where each record lands and whether it duplicates / conflicts with an
+ * existing file. Pure w.r.t. the filesystem it reads (no writes). Dedup is
+ * byte-exact: a target that already holds an identical body is `dup`; a target
+ * that holds a DIFFERENT body is `conflict` (only overwritten with --overwrite).
+ * An agent with no sync spec is `unknown` and never placed.
+ */
+export declare function planImport(bundle: ParsedBundle, opts: PlanImportOpts): ImportPlanItem[];
+export interface WriteResult {
+    /** New files written. */
+    placed: number;
+    /** Byte-exact dups skipped. */
+    skipped: number;
+    /** Conflicts replaced (only with overwrite). */
+    overwritten: number;
+    /** Conflicts left in place (overwrite off). */
+    conflicts: number;
+    /** Records for agents with no sync spec. */
+    unknown: number;
+}
+export interface WriteImportOpts {
+    overwrite: boolean;
+    decryptKey: Buffer | null;
+}
+/**
+ * Materialize a plan to disk. `dup` records are always skipped (local wins);
+ * `conflict` records are replaced only when `overwrite` is set; `unknown` records
+ * are counted and skipped.
+ */
+export declare function writeImport(plan: ImportPlanItem[], opts: WriteImportOpts): WriteResult;