@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/fleet/auth-sync.js

@@ -0,0 +1,142 @@
+/**
+ * Login/token propagation — the "one login instead of ~48 OAuth flows" core of
+ * `agents apply`.
+ *
+ * A source machine that is already signed in to a set of harnesses has portable
+ * credential files on disk (verified per-agent locations below). `snapshotAuth`
+ * captures those; `materializeAuth` writes them into the corresponding paths on
+ * a target device. Transport is the caller's job — `apply` streams the bundle
+ * over the existing (encrypted, authenticated) SSH channel via `sshExec`'s
+ * stdin `input`, so no app-layer crypto is layered on top of SSH here.
+ *
+ * Honest boundary: on macOS, claude and antigravity keep their tokens in the
+ * login keychain, ACL-bound to the harness process — unreadable by us. Those are
+ * classified `bound` and surfaced for a one-time manual login, never faked.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Verified portable auth-file locations per agent (home-relative). Sourced from
+ * live inspection of a Linux fleet box + the agent registry. Agents absent here
+ * have no portable credential file we can propagate.
+ */
+export const FLEET_AUTH_FILES = {
+    claude: [{ rel: '.claude/.credentials.json', mode: 0o600 }],
+    codex: [{ rel: '.codex/auth.json', mode: 0o600 }],
+    gemini: [{ rel: '.gemini/oauth_creds.json', mode: 0o600 }],
+    grok: [{ rel: '.grok/auth.json', mode: 0o600 }],
+    kimi: [{ rel: '.kimi-code/credentials/kimi-code.json', mode: 0o600 }],
+    opencode: [{ rel: '.local/share/opencode/auth.json', mode: 0o600 }],
+    droid: [
+        { rel: '.factory/auth.v2.file', mode: 0o600 },
+        { rel: '.factory/auth.v2.key', mode: 0o600 },
+    ],
+    antigravity: [{ rel: '.gemini/antigravity-cli/antigravity-oauth-token', mode: 0o600 }],
+};
+/** Agents whose macOS credentials live in the ACL-bound login keychain. */
+export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
+/** Which agents `apply` can propagate auth for at all. */
+export function isPropagatableAgent(agent) {
+    return agent in FLEET_AUTH_FILES;
+}
+/**
+ * Capture portable credential files for the given agents from a source home.
+ * Returns the readable file payloads plus the list of agents whose auth is
+ * device-bound (macOS keychain) and therefore cannot be captured. Agents that
+ * are simply not signed in (no file on disk) are silently omitted — nothing to
+ * propagate, not an error.
+ */
+export function snapshotAuth(agents, opts) {
+    const files = [];
+    const bound = [];
+    for (const agent of agents) {
+        const specs = FLEET_AUTH_FILES[agent];
+        if (!specs)
+            continue; // not propagatable — caller surfaces separately if desired
+        if (opts.platform === 'darwin' && KEYCHAIN_BOUND_ON_MAC.has(agent)) {
+            bound.push(agent);
+            continue;
+        }
+        for (const spec of specs) {
+            const abs = path.join(opts.home, spec.rel);
+            let stat;
+            try {
+                stat = fs.statSync(abs);
+            }
+            catch {
+                continue; // not signed in for this agent — nothing to carry
+            }
+            if (!stat.isFile())
+                continue;
+            const content = fs.readFileSync(abs); // follows symlinks into version homes
+            files.push({
+                agent,
+                rel: spec.rel,
+                contentB64: content.toString('base64'),
+                mode: (stat.mode & 0o777) || spec.mode,
+            });
+        }
+    }
+    return { files, bound };
+}
+/** Assemble the plaintext bundle shipped to a target. */
+export function buildAuthBundle(source, files) {
+    return { v: 1, source, files };
+}
+/**
+ * Write a captured auth bundle into a target home. Parent dirs are created; the
+ * captured POSIX mode is restored (0600 for credentials). Writing through an
+ * existing symlink lands in the agent's active version home, which is exactly
+ * what per-version credential carry-forward expects.
+ */
+export function materializeAuth(bundle, opts) {
+    const written = new Set();
+    const errors = [];
+    for (const f of bundle.files) {
+        const abs = path.join(opts.home, f.rel);
+        try {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, Buffer.from(f.contentB64, 'base64'));
+            fs.chmodSync(abs, f.mode || 0o600);
+            written.add(f.agent);
+        }
+        catch (e) {
+            errors.push(`${f.rel}: ${e.message}`);
+        }
+    }
+    return { written: [...written], errors };
+}
+/** Parse + validate a bundle received on stdin (the remote `--_recv-auth` path). */
+export function parseAuthBundle(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`auth bundle is not valid JSON: ${e.message}`);
+    }
+    if (typeof doc !== 'object' || doc === null)
+        throw new Error('auth bundle must be an object.');
+    const o = doc;
+    if (o.v !== 1)
+        throw new Error(`unsupported auth bundle version ${JSON.stringify(o.v)}.`);
+    if (typeof o.source !== 'string')
+        throw new Error('auth bundle missing source.');
+    if (!Array.isArray(o.files))
+        throw new Error('auth bundle missing files[].');
+    for (const f of o.files) {
+        if (typeof f !== 'object' || f === null ||
+            typeof f.agent !== 'string' ||
+            typeof f.rel !== 'string' ||
+            typeof f.contentB64 !== 'string' ||
+            typeof f.mode !== 'number') {
+            throw new Error('auth bundle has a malformed file entry.');
+        }
+        // Reject path traversal — rel must stay under $HOME.
+        const rel = f.rel;
+        if (rel.startsWith('/') || rel.split('/').includes('..')) {
+            throw new Error(`auth bundle rejected unsafe path: ${rel}`);
+        }
+    }
+    return doc;
+}

package/dist/lib/fleet/manifest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Parse + validate the `fleet:` block of a profile manifest and resolve it into
+ * per-device desired state.
+ *
+ * `fleet:` is additive to the `Meta` schema (`types.ts`). Any `-f <file>` that
+ * carries a `fleet:` block is a valid manifest, so `ag apply -f agents.yaml`
+ * works against the project file. The functions here are pure (no SSH, no
+ * registry I/O) so they're fully unit-testable; device enumeration is injected.
+ */
+import type { FleetManifest, DeviceDesired } from './types.js';
+/** Validate a raw `fleet:` object (already YAML-parsed) into a typed manifest. */
+export declare function parseFleetManifest(raw: unknown): FleetManifest;
+/** Read a YAML file and extract + validate its `fleet:` block. */
+export declare function readFleetFile(filePath: string): FleetManifest;
+export interface ResolveContext {
+    /** Device names currently online (used to expand `devices: all`). */
+    onlineDevices: string[];
+    /** All registered device names (used to validate explicit entries). */
+    registeredDevices: string[];
+    /** The source machine, always excluded from the target set. */
+    source: string;
+}
+/**
+ * Expand a manifest into concrete per-device desired states. `devices: all`
+ * expands to every online registered device minus the source; an explicit map
+ * validates each name against the registry. Devices with no desired agents,
+ * sync scopes, and `login: skip` are still returned (probe/report only).
+ */
+export declare function resolveDesired(manifest: FleetManifest, ctx: ResolveContext): DeviceDesired[];

package/dist/lib/fleet/manifest.js

@@ -0,0 +1,127 @@
+/**
+ * Parse + validate the `fleet:` block of a profile manifest and resolve it into
+ * per-device desired state.
+ *
+ * `fleet:` is additive to the `Meta` schema (`types.ts`). Any `-f <file>` that
+ * carries a `fleet:` block is a valid manifest, so `ag apply -f agents.yaml`
+ * works against the project file. The functions here are pure (no SSH, no
+ * registry I/O) so they're fully unit-testable; device enumeration is injected.
+ */
+import * as fs from 'fs';
+import * as yaml from 'yaml';
+const LOGIN_MODES = ['sync', 'skip'];
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+function validateLogin(v, where) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string' || !LOGIN_MODES.includes(v)) {
+        throw new Error(`fleet: ${where}.login must be one of ${LOGIN_MODES.join(' | ')} (got ${JSON.stringify(v)}).`);
+    }
+    return v;
+}
+function validateDefaults(v, where) {
+    if (v === undefined)
+        return {};
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+        throw new Error(`fleet: ${where} must be a mapping.`);
+    }
+    const o = v;
+    if (o.agents !== undefined && !isStringArray(o.agents)) {
+        throw new Error(`fleet: ${where}.agents must be a list of agent specs (e.g. [claude@latest]).`);
+    }
+    if (o.sync !== undefined && !isStringArray(o.sync)) {
+        throw new Error(`fleet: ${where}.sync must be a list of scope names (e.g. [user]).`);
+    }
+    return {
+        agents: o.agents,
+        sync: o.sync,
+        login: validateLogin(o.login, where),
+    };
+}
+/** Validate a raw `fleet:` object (already YAML-parsed) into a typed manifest. */
+export function parseFleetManifest(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('fleet: block must be a mapping with a `devices:` key.');
+    }
+    const o = raw;
+    const defaults = validateDefaults(o.defaults, 'defaults');
+    if (o.devices === undefined) {
+        throw new Error('fleet: a `devices:` key is required (use `devices: all` or an explicit map).');
+    }
+    let devices;
+    if (o.devices === 'all') {
+        devices = 'all';
+    }
+    else if (typeof o.devices === 'object' && o.devices !== null && !Array.isArray(o.devices)) {
+        const map = {};
+        for (const [name, ov] of Object.entries(o.devices)) {
+            // An empty entry (`device: {}`) inherits defaults — represent as {}.
+            const merged = ov == null ? {} : validateDefaults(ov, `devices.${name}`);
+            map[name] = merged;
+        }
+        devices = map;
+    }
+    else {
+        throw new Error(`fleet: devices must be the string 'all' or a mapping of device -> overrides (got ${JSON.stringify(o.devices)}).`);
+    }
+    return { defaults, devices };
+}
+/** Read a YAML file and extract + validate its `fleet:` block. */
+export function readFleetFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Manifest not found: ${filePath}`);
+    }
+    let doc;
+    try {
+        doc = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Failed to parse YAML in ${filePath}: ${e.message}`);
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        throw new Error(`${filePath} is not a mapping — no fleet: block to apply.`);
+    }
+    const fleet = doc.fleet;
+    if (fleet === undefined) {
+        throw new Error(`${filePath} has no fleet: block. Add one to declare the profile (see \`agents apply --help\`).`);
+    }
+    return parseFleetManifest(fleet);
+}
+/** Merge a per-device override over defaults into a concrete desired state. */
+function mergeDesired(device, defaults, override) {
+    return {
+        device,
+        agents: override.agents ?? defaults.agents ?? [],
+        sync: override.sync ?? defaults.sync ?? [],
+        login: override.login ?? defaults.login ?? 'sync',
+    };
+}
+/**
+ * Expand a manifest into concrete per-device desired states. `devices: all`
+ * expands to every online registered device minus the source; an explicit map
+ * validates each name against the registry. Devices with no desired agents,
+ * sync scopes, and `login: skip` are still returned (probe/report only).
+ */
+export function resolveDesired(manifest, ctx) {
+    const defaults = manifest.defaults ?? {};
+    const out = [];
+    if (manifest.devices === 'all') {
+        for (const name of ctx.onlineDevices) {
+            if (name === ctx.source)
+                continue;
+            out.push(mergeDesired(name, defaults, {}));
+        }
+        return out;
+    }
+    for (const [name, override] of Object.entries(manifest.devices)) {
+        if (name === ctx.source)
+            continue;
+        if (!ctx.registeredDevices.includes(name)) {
+            throw new Error(`fleet: device '${name}' is not a registered device. Run \`agents devices add ${name}\` or fix the manifest.`);
+        }
+        out.push(mergeDesired(name, defaults, override));
+    }
+    return out;
+}

package/dist/lib/fleet/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Shared types for the fleet profile-sync feature (`agents apply` / `ag apply`).
+ *
+ * `agents.yaml` gains an additive `fleet:` block that declares a *profile*: which
+ * agents every device should have installed, which config scopes to reconcile,
+ * and whether logins/tokens propagate. `apply` reconciles the live fleet to it.
+ *
+ * These types are the contract shared by the manifest parser (`manifest.ts`),
+ * the reconcile engine (`apply.ts`), the auth propagation (`auth-sync.ts`), and
+ * the command (`commands/apply.ts`). Runtime probe/diff shapes live here too so
+ * the pure diff can be unit-tested without SSH.
+ */
+/**
+ * How login/token state propagates to a device.
+ * - `sync` (default): push portable credentials where possible, surface the rest
+ *   as a manual login.
+ * - `skip`: probe/report only; take no login action.
+ * (A per-agent interactive `prompt` mode is intentionally not offered yet — it
+ * was removed rather than accepted as a silent no-op that behaves like `skip`.)
+ */
+export type FleetLoginMode = 'sync' | 'skip';
+/** Defaults applied to every targeted device unless a per-device entry overrides. */
+export interface FleetDefaults {
+    /** Agent specs to ensure installed, e.g. `['claude@latest', 'codex@latest']`. */
+    agents?: string[];
+    /** Config sync scopes to reconcile on each device, e.g. `['user']`. */
+    sync?: string[];
+    /** Login propagation strategy. Default `'sync'`. */
+    login?: FleetLoginMode;
+}
+/** Per-device override; any omitted field inherits from `defaults`. */
+export interface FleetDeviceOverride {
+    agents?: string[];
+    sync?: string[];
+    login?: FleetLoginMode;
+}
+/**
+ * The `fleet:` block as it appears in `agents.yaml` (or any `-f` file). `devices`
+ * is either the literal string `'all'` (every online registered device minus the
+ * source machine) or an explicit map of device-name -> override.
+ */
+export interface FleetManifest {
+    defaults?: FleetDefaults;
+    devices: 'all' | Record<string, FleetDeviceOverride>;
+}
+/**
+ * A device's desired state after merging defaults with its override and
+ * expanding `devices: all`. This is what the reconcile engine drives toward.
+ */
+export interface DeviceDesired {
+    /** Registered device name (from `agents devices`). */
+    device: string;
+    /** Resolved agent specs to ensure installed. */
+    agents: string[];
+    /** Config sync scopes. */
+    sync: string[];
+    /** Login propagation strategy for this device. */
+    login: FleetLoginMode;
+}
+/**
+ * What a probe found on one device. Populated from `readyProbe` plus an
+ * installed-agents listing; `reachable: false` short-circuits everything else.
+ */
+export interface DeviceProbe {
+    device: string;
+    reachable: boolean;
+    /** Platform of the device (`linux` | `macos` | `windows`), for login classification. */
+    platform?: string;
+    /** agents-cli version present on the device (undefined if not installed). */
+    cliVersion?: string;
+    /** Agent ids currently installed on the device. */
+    installedAgents: string[];
+    /** Reason string when `reachable` is false or the probe partially failed. */
+    note?: string;
+}
+/** One planned action against a device, in a single reconcile dimension. */
+export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login';
+export interface FleetAction {
+    device: string;
+    kind: FleetActionKind;
+    /** Agent id for agent/login actions; undefined for cli/config actions. */
+    agent?: string;
+    /** Human, one-line description of the action. */
+    detail: string;
+}
+/**
+ * The full reconcile plan: per-device desired vs probed, plus the flat list of
+ * actions. Pure output of `diffFleet(desired, probes)` — drives both `--plan`
+ * rendering and the confirm prompt.
+ */
+export interface FleetPlan {
+    devices: DeviceDiff[];
+    actions: FleetAction[];
+}
+/** Per-device diff row rendered in the plan matrix. */
+export interface DeviceDiff {
+    device: string;
+    desired: DeviceDesired;
+    probe: DeviceProbe;
+    actions: FleetAction[];
+    /** Agents that must be logged in on the device but can't be propagated
+     * (source token is device-bound, e.g. macOS keychain). Surfaced, not faked. */
+    loginBlocked: string[];
+}
+/** A portable auth file captured from a source agent home, ready to propagate. */
+export interface AuthFilePayload {
+    /** Agent id this file belongs to. */
+    agent: string;
+    /** Path relative to the agent's config dir (or $HOME), reconstructed on target. */
+    rel: string;
+    /** File contents, base64. */
+    contentB64: string;
+    /** POSIX mode to restore (e.g. 0o600 for credentials). */
+    mode: number;
+}
+/** The plaintext we encrypt before shipping auth over the wire. */
+export interface AuthBundle {
+    /** Schema version for forward-compat. */
+    v: 1;
+    /** Source machine name the snapshot was taken on. */
+    source: string;
+    files: AuthFilePayload[];
+}
+/** Result of classifying one source agent's auth for propagation. */
+export interface AuthSnapshotResult {
+    files: AuthFilePayload[];
+    /** Agent ids whose auth is device-bound (keychain) and cannot be captured. */
+    bound: string[];
+}

package/dist/lib/fleet/types.js

@@ -0,0 +1,13 @@
+/**
+ * Shared types for the fleet profile-sync feature (`agents apply` / `ag apply`).
+ *
+ * `agents.yaml` gains an additive `fleet:` block that declares a *profile*: which
+ * agents every device should have installed, which config scopes to reconcile,
+ * and whether logins/tokens propagate. `apply` reconciles the live fleet to it.
+ *
+ * These types are the contract shared by the manifest parser (`manifest.ts`),
+ * the reconcile engine (`apply.ts`), the auth propagation (`auth-sync.ts`), and
+ * the command (`commands/apply.ts`). Runtime probe/diff shapes live here too so
+ * the pure diff can be unit-tested without SSH.
+ */
+export {};

package/dist/lib/git.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Git operations for the agents-cli system repo and package repositories.
+ *
+ * Handles cloning, pulling, syncing, and inspecting git repos used by
+ * the agents version management and plugin/package system. Includes
+ * source parsing for GitHub shorthand, SSH, HTTPS, and local paths.
+ */
+import { SimpleGit } from 'simple-git';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
  * handed to `git`.
@@ -16,6 +24,25 @@
  * @throws Error if the source uses a disallowed transport.
  */
 export declare function assertSafeGitTransport(source: string): void;
+/**
+ * Validate a branch name before it is passed to `git push` / `git pull`.
+ *
+ * A name beginning with `-` is parsed by git as a command-line option
+ * (e.g. `--mirror`, `--receive-pack=…`), not a ref. Pure string check —
+ * identical on every OS, no spawn.
+ *
+ * @throws Error if the name is empty or would be interpreted as a git option.
+ */
+export declare function assertValidBranchName(branch: string): void;
+/**
+ * `git push origin <branch>` with option-injection hardening:
+ *   1. {@link assertValidBranchName} rejects leading `-`
+ *   2. `--` ends option parsing so a hostile ref cannot be read as a flag
+ *
+ * Prefer this over `git.push(remote, branch)` whenever the branch comes from
+ * repo state rather than a hard-coded literal.
+ */
+export declare function pushOrigin(git: SimpleGit, branch: string): Promise<void>;
 /** Parsed representation of a git source string (GitHub, generic URL, or local path). */
 export interface GitSource {
     type: 'github' | 'url' | 'local';

package/dist/lib/git.js

@@ -51,6 +51,36 @@ export function assertSafeGitTransport(source) {
     }
     // No scheme -> SCP-style SSH ("git@host:path") or a local path; both safe.
 }
+/**
+ * Validate a branch name before it is passed to `git push` / `git pull`.
+ *
+ * A name beginning with `-` is parsed by git as a command-line option
+ * (e.g. `--mirror`, `--receive-pack=…`), not a ref. Pure string check —
+ * identical on every OS, no spawn.
+ *
+ * @throws Error if the name is empty or would be interpreted as a git option.
+ */
+export function assertValidBranchName(branch) {
+    const b = branch.trim();
+    if (!b) {
+        throw new Error(`Invalid branch name ${JSON.stringify(branch)}: branch name is empty.`);
+    }
+    if (b.startsWith('-')) {
+        throw new Error(`Invalid branch name ${JSON.stringify(branch)}: a name starting with "-" is interpreted as a git option.`);
+    }
+}
+/**
+ * `git push origin <branch>` with option-injection hardening:
+ *   1. {@link assertValidBranchName} rejects leading `-`
+ *   2. `--` ends option parsing so a hostile ref cannot be read as a flag
+ *
+ * Prefer this over `git.push(remote, branch)` whenever the branch comes from
+ * repo state rather than a hard-coded literal.
+ */
+export async function pushOrigin(git, branch) {
+    assertValidBranchName(branch);
+    await git.raw(['push', '--', 'origin', branch]);
+}
 /**
  * Whether installing a cloned/pulled repo's `.githooks/` is enabled.
  *
@@ -377,6 +407,7 @@ export async function commitAndPush(repoPath, message) {
         const git = simpleGit(repoPath);
         let status = await git.status();
         const branch = status.current || 'main';
+        assertValidBranchName(branch);
         let committed = false;
         if (status.files.length > 0) {
             await git.add('-A');
@@ -402,7 +433,7 @@ export async function commitAndPush(repoPath, message) {
         catch {
             /* origin/<branch> may not exist yet (first push) */
         }
-        await git.push('origin', branch);
+        await pushOrigin(git, branch);
         let after = '';
         try {
             after = (await git.raw(['rev-parse', '--short=8', 'HEAD'])).trim();
@@ -735,12 +766,13 @@ export async function syncRepoGit(dir, opts) {
             };
         }
         const branch = status.current || 'main';
+        assertValidBranchName(branch);
         await git.fetch('origin');
         await git.pull('origin', branch, { '--rebase': 'true' });
         installGithooksSymlinks(dir);
         let pushed = false;
         if (opts.push) {
-            await git.push('origin', branch);
+            await pushOrigin(git, branch);
             pushed = true;
         }
         const log = await git.log({ maxCount: 1 });

package/dist/lib/hosts/dispatch.d.ts

@@ -62,24 +62,37 @@ export interface DispatchOptions {
     prompt: string;
     /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
-    /** Explicit run strategy (e.g. "balanced") to forward as `--strategy <strategy>`. */
+    /** Run strategy (e.g. "balanced") — the remote picks among ITS signed-in accounts. */
     strategy?: string;
+    balanced?: boolean;
+    fallback?: string;
     mode?: string;
     model?: string;
-    /** Reasoning effort to forward as `--effort <effort>`. */
+    /** Reasoning effort — forwarded unless 'auto' (the remote default). */
     effort?: string;
-    /** Additional directories to grant, already made remote-portable. */
+    /** `--env k=v` pairs, forwarded verbatim (the remote CLI parses them). */
+    env?: string[];
+    /** `--add-dir` grants, already made remote-portable. */
     addDir?: string[];
-    /** Stream events as JSON lines. */
+    /** Agent wall-clock cap, forwarded as `--timeout <duration>` for the REMOTE to enforce. */
+    timeout?: string;
+    /** Loop family — the loop driver runs on the host. */
+    loop?: boolean;
+    maxIterations?: string;
+    budget?: string;
+    until?: string;
+    interval?: string;
+    /** Remote emits ndjson into its log; the local follow streams it verbatim. */
     json?: boolean;
-    /** Show detailed execution logs. */
     verbose?: boolean;
-    /** Kill the agent after this duration, forwarded as `--timeout <duration>`. */
-    timeout?: string;
-    /** Skip the interactive budget-confirm prompt. */
+    /** Skip the budget-confirm prompt — a detached remote run can't answer one. */
     yes?: boolean;
     /** Route through the Agent Client Protocol. */
     acp?: boolean;
+    /** False forwards --no-auto-secrets (workflow secrets resolve on the REMOTE keychain). */
+    autoSecrets?: boolean;
+    /** Native-CLI passthrough (everything after `--`), appended last. */
+    passthroughArgs?: string[];
     remoteCwd?: string;
     /**
      * Force the remote run's NEW session to use this exact id (Claude only, via
@@ -105,6 +118,10 @@ export interface DispatchOptions {
  * session-id / resume flag wiring is unit-testable without an SSH round-trip.
  * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
  * resume wins when — defensively — both are set.
+ *
+ * Every field here is classified 'forward' in RUN_OPTION_FORWARDING
+ * (remote-cmd.ts) — keep the two in lockstep; run-forwarding.test.ts asserts
+ * the table side.
  */
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
 export interface InteractiveDispatchOptions {
@@ -139,6 +156,10 @@ export interface InteractiveDispatchOptions {
     raw?: boolean;
     /** Forward `--interactive` to the remote so a prompt-bearing run still starts the TUI. */
     forceInteractive?: boolean;
+    /** `--env k=v` pairs, forwarded verbatim (the remote CLI parses them). */
+    env?: string[];
+    balanced?: boolean;
+    fallback?: string;
     /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }