@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/ssh-tunnel.js

@@ -23,6 +23,7 @@ import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
 import { sshExec, SSH_OPTS } from './ssh-exec.js';
+import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
 import { sshTargetFor } from './devices/connect.js';
@@ -56,7 +57,7 @@ export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
         const args = buildTunnelArgs(user, host, localPort, remotePort);
         const tunnel = spawn('ssh', args, {
             stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],
-            detached: Boolean(opts.detached),
+            ...(opts.detached ? backgroundSpawnOptions() : { detached: false, windowsHide: true }),
         });
         let stderr = '';
         tunnel.stderr?.on('data', (data) => {

package/dist/lib/startup/command-registry.d.ts

@@ -49,6 +49,7 @@ export declare const loadPrune: ModuleLoader;
 export declare const loadTrash: ModuleLoader;
 export declare const loadRestore: ModuleLoader;
 export declare const loadDoctor: ModuleLoader;
+export declare const loadCheck: ModuleLoader;
 export declare const loadStatus: ModuleLoader;
 export declare const loadProfiles: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;
@@ -57,6 +58,7 @@ export declare const loadHelper: ModuleLoader;
 export declare const loadMenubar: ModuleLoader;
 export declare const loadBeta: ModuleLoader;
 export declare const loadSync: ModuleLoader;
+export declare const loadLock: ModuleLoader;
 export declare const loadRefreshRules: ModuleLoader;
 export declare const loadDrive: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
@@ -66,6 +68,7 @@ export declare const loadBudget: ModuleLoader;
 export declare const loadAlias: ModuleLoader;
 export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
+export declare const loadWatchdog: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
 export declare const loadHosts: ModuleLoader;
@@ -79,6 +82,9 @@ export declare const loadSetup: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
+export declare const loadMessage: ModuleLoader;
+export declare const loadServe: ModuleLoader;
+export declare const loadAudit: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

package/dist/lib/startup/command-registry.js

@@ -27,6 +27,7 @@ export const loadPrune = async () => (await import('../../commands/prune.js')).r
 export const loadTrash = async () => (await import('../../commands/trash.js')).registerTrashCommands;
 export const loadRestore = async () => (await import('../../commands/trash.js')).registerRestoreCommand;
 export const loadDoctor = async () => (await import('../../commands/doctor.js')).registerDoctorCommand;
+export const loadCheck = async () => (await import('../../commands/check.js')).registerCheckCommand;
 export const loadStatus = async () => (await import('../../commands/status.js')).registerStatusCommand;
 export const loadProfiles = async () => (await import('../../commands/profiles.js')).registerProfilesCommands;
 export const loadSecrets = async () => (await import('../../commands/secrets.js')).registerSecretsCommands;
@@ -35,6 +36,7 @@ export const loadHelper = async () => (await import('../../commands/helper.js'))
 export const loadMenubar = async () => (await import('../../commands/menubar.js')).registerMenubarCommands;
 export const loadBeta = async () => (await import('../../commands/beta.js')).registerBetaCommands;
 export const loadSync = async () => (await import('../../commands/sync.js')).registerSyncCommand;
+export const loadLock = async () => (await import('../../commands/lock.js')).registerLockCommand;
 export const loadRefreshRules = async () => (await import('../../commands/refresh-rules.js')).registerRefreshRulesCommand;
 export const loadDrive = async () => (await import('../../commands/drive.js')).registerDriveCommands;
 export const loadFactory = async () => (await import('../../commands/factory.js')).registerFactoryCommands;
@@ -44,6 +46,7 @@ export const loadBudget = async () => (await import('../../commands/budget.js'))
 export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
 export const loadPty = async () => (await import('../../commands/pty.js')).registerPtyCommands;
 export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
+export const loadWatchdog = async () => (await import('../../commands/watchdog.js')).registerWatchdogCommand;
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
 export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
@@ -57,6 +60,9 @@ export const loadSetup = async () => (await import('../../commands/setup.js')).r
 export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
 export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
+export const loadMessage = async () => (await import('../../commands/message.js')).registerMessageCommand;
+export const loadServe = async () => (await import('../../commands/serve.js')).registerServeCommand;
+export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -64,7 +70,7 @@ export const loadCloud = async () => (await import('../../commands/cloud.js')).r
  * inherit the root's custom help formatter rather than getting the per-command
  * recursive pass. Keeping that ordering preserves their `--help` output exactly.
  */
-export const LAZY_COMMAND_NAMES = new Set(['sessions', 'teams', 'cloud']);
+export const LAZY_COMMAND_NAMES = new Set(['sessions', 'teams', 'cloud', 'message', 'serve']);
 /**
  * User-typed top-level command name -> ordered list of module loaders to run.
  *
@@ -113,6 +119,7 @@ export const COMMAND_LOADERS = {
     trash: [loadTrash],
     restore: [loadRestore],
     doctor: [loadDoctor],
+    check: [loadCheck],
     status: [loadStatus],
     profiles: [loadProfiles],
     secrets: [loadSecrets],
@@ -121,6 +128,7 @@ export const COMMAND_LOADERS = {
     menubar: [loadMenubar],
     beta: [loadBeta],
     sync: [loadSync],
+    lock: [loadLock],
     'refresh-rules': [loadRefreshRules],
     drive: [loadDrive],
     factory: [loadFactory],
@@ -130,6 +138,7 @@ export const COMMAND_LOADERS = {
     alias: [loadAlias],
     pty: [loadPty],
     tmux: [loadTmux],
+    watchdog: [loadWatchdog],
     browser: [loadBrowser],
     computer: [loadComputer],
     hosts: [loadHosts],
@@ -144,4 +153,7 @@ export const COMMAND_LOADERS = {
     sessions: [loadSessions],
     teams: [loadTeams],
     cloud: [loadCloud],
+    message: [loadMessage],
+    serve: [loadServe],
+    audit: [loadAudit],
 };

package/dist/lib/state.d.ts

@@ -120,6 +120,8 @@ export declare function getRoutinesDir(): string;
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export declare function getRunsDir(): string;
+/** Root for per-agent mailboxes (~/.agents/.history/mailbox/). */
+export declare function getMailboxRootDir(): string;
 /** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
 export declare function getVersionsDir(): string;
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
@@ -226,6 +228,17 @@ export declare function getEnabledExtraRepos(): Array<{
 export declare function ensureAgentsDir(): void;
 /** Return an empty Meta object used when no agents.yaml exists yet. */
 export declare function createDefaultMeta(): Meta;
+/**
+ * Per-device machine-local version pins — `~/.agents/devices/<machine>/agents.yaml`.
+ * Committed and synced, but each machine only ever writes its OWN folder, so
+ * pulls never conflict. `<machine>` = machineId() (Tailscale-aligned short name).
+ */
+export declare function getDeviceMetaPath(): string;
+/**
+ * Machine-local per-version resource tracking — `~/.agents/.history/version-resources.json`.
+ * Gitignored (under .history/) and regenerable; never synced.
+ */
+export declare function getVersionResourcesPath(): string;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *

package/dist/lib/state.js

@@ -28,6 +28,7 @@ import * as os from 'os';
 import * as yaml from 'yaml';
 import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { SEEDED_REGISTRIES } from './types.js';
+import { machineId } from './machine-id.js';
 const HOME = process.env.HOME ?? os.homedir();
 /**
  * Compare two filesystem paths for identity, resolving symlinks and (on
@@ -87,6 +88,7 @@ const RUNS_DIR = path.join(HISTORY_DIR, 'runs');
 const TEAMS_AGENTS_DIR = path.join(HISTORY_DIR, 'teams', 'agents');
 const BACKUPS_DIR = path.join(HISTORY_DIR, 'backups');
 const TRASH_DIR = path.join(HISTORY_DIR, 'trash');
+const MAILBOX_DIR = path.join(HISTORY_DIR, 'mailbox');
 // Cache bucket (regenerable).
 const SHIMS_DIR = path.join(CACHE_DIR, 'shims');
 const HOOK_SHIMS_DIR = path.join(SHIMS_DIR, 'hooks');
@@ -309,6 +311,8 @@ export function getProjectRoutinesDir(cwd = process.cwd()) {
 }
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
+/** Root for per-agent mailboxes (~/.agents/.history/mailbox/). */
+export function getMailboxRootDir() { return MAILBOX_DIR; }
 /** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
 export function getVersionsDir() { return VERSIONS_DIR; }
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
@@ -495,13 +499,37 @@ function safeMtimeMs(filePath) {
         return 0;
     }
 }
-/** Compute the combined cache stamp for the user + system agents.yaml files. */
+/**
+ * Per-device machine-local version pins — `~/.agents/devices/<machine>/agents.yaml`.
+ * Committed and synced, but each machine only ever writes its OWN folder, so
+ * pulls never conflict. `<machine>` = machineId() (Tailscale-aligned short name).
+ */
+export function getDeviceMetaPath() {
+    return path.join(USER_AGENTS_DIR, 'devices', machineId(), 'agents.yaml');
+}
+/**
+ * Machine-local per-version resource tracking — `~/.agents/.history/version-resources.json`.
+ * Gitignored (under .history/) and regenerable; never synced.
+ */
+export function getVersionResourcesPath() {
+    return path.join(HISTORY_DIR, 'version-resources.json');
+}
+/**
+ * Combined cache stamp across all four Meta sources: central + system
+ * agents.yaml, this machine's device pins, and the version-resources tracking.
+ * A delimited string, NOT a numeric sum — summing down-scaled epoch-ms values
+ * loses precision (float64 rounds sub-unit terms away at ~1.75e12), so a change
+ * in any one file must contribute at full resolution.
+ */
 function currentMetaStamp() {
-    return safeMtimeMs(META_FILE) + safeMtimeMs(SYSTEM_META_FILE) * 1e-3;
+    return safeMtimeMs(META_FILE)
+        + '|' + safeMtimeMs(SYSTEM_META_FILE)
+        + '|' + safeMtimeMs(getDeviceMetaPath())
+        + '|' + safeMtimeMs(getVersionResourcesPath());
 }
 /** Memoize a parsed Meta against the current file mtimes. */
 function rememberMeta(meta) {
-    metaCache = { mtime: currentMetaStamp(), meta };
+    metaCache = { stamp: currentMetaStamp(), meta };
     return meta;
 }
 function withMetaLock(fn) {
@@ -526,11 +554,78 @@ function withMetaLock(fn) {
         }
     });
 }
+/** Atomic write only when the on-disk content differs — avoids needless mtime
+ * bumps (which would thrash the meta cache) on no-op field routing. */
+function writeIfChanged(filePath, content) {
+    let current = null;
+    try {
+        current = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch { /* absent */ }
+    if (current === content)
+        return;
+    atomicWriteFileSync(filePath, content);
+}
+/**
+ * Partition the in-memory Meta across three files by sync-domain:
+ *   - central  `~/.agents/agents.yaml`             — portable, everything else
+ *   - device   `~/.agents/devices/<machine>/agents.yaml` — `agents:` pins (per-device)
+ *   - history  `~/.agents/.history/version-resources.json` — `versions:` (machine-local)
+ * All callers funnel through writeMeta → here, so nothing else changes. Empty
+ * `agents:` / `versions:` are not written (no empty committed files).
+ */
 function writeMetaUnlocked(meta) {
-    const content = META_HEADER + yaml.stringify(meta);
-    atomicWriteFileSync(META_FILE, content);
+    const { agents, versions, ...central } = meta;
+    // Write the machine-local files FIRST, then strip central — so a crash mid-write
+    // never removes pins/versions from central before they're persisted elsewhere.
+    const devicePath = getDeviceMetaPath();
+    if (agents && Object.keys(agents).length > 0) {
+        fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+        writeIfChanged(devicePath, META_HEADER + yaml.stringify({ agents }));
+    }
+    else if (fs.existsSync(devicePath)) {
+        // Every pin was cleared. Persist the emptied map instead of skipping the
+        // write — otherwise the stale device file survives and overlayMachineLocal
+        // re-applies the removed pin on the next read, leaving a dangling default
+        // (e.g. a launcher pointing at a version that was just uninstalled).
+        writeIfChanged(devicePath, META_HEADER + yaml.stringify({ agents: {} }));
+    }
+    if (versions && Object.keys(versions).length > 0) {
+        const vrPath = getVersionResourcesPath();
+        fs.mkdirSync(path.dirname(vrPath), { recursive: true });
+        writeIfChanged(vrPath, JSON.stringify(versions, null, 2) + '\n');
+    }
+    writeIfChanged(META_FILE, META_HEADER + yaml.stringify(central));
     metaCache = null;
 }
+/**
+ * Overlay this machine's local state onto a central-portable Meta:
+ *   - `agents:` from the device file (device wins; the union both preserves the
+ *     one-level merge and self-heals a pre-migration central that still has pins)
+ *   - `versions:` from the history JSON (wholesale replace; falls back to
+ *     whatever central carried when the history file doesn't exist yet)
+ */
+function overlayMachineLocal(meta) {
+    const devicePath = getDeviceMetaPath();
+    if (fs.existsSync(devicePath)) {
+        try {
+            const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+            if (dm?.agents)
+                meta.agents = { ...meta.agents, ...dm.agents };
+        }
+        catch { /* ignore malformed device file */ }
+    }
+    const vrPath = getVersionResourcesPath();
+    if (fs.existsSync(vrPath)) {
+        try {
+            const vr = JSON.parse(fs.readFileSync(vrPath, 'utf-8'));
+            if (vr)
+                meta.versions = vr;
+        }
+        catch { /* ignore malformed history file */ }
+    }
+    return meta;
+}
 function applyRegistrySeeds(meta) {
     const seeded = new Set(meta.seededPresets || []);
     let changed = false;
@@ -590,10 +685,7 @@ export function readMeta() {
     // what we last parsed. Reduces N readMeta calls per CLI invocation to ~2 stat
     // syscalls plus an in-memory object spread.
     if (metaCache) {
-        const userMtime = safeMtimeMs(META_FILE);
-        const systemMtime = safeMtimeMs(SYSTEM_META_FILE);
-        const stamp = userMtime + systemMtime * 1e-3;
-        if (stamp === metaCache.mtime) {
+        if (currentMetaStamp() === metaCache.stamp) {
             return metaCache.meta;
         }
     }
@@ -666,6 +758,7 @@ export function readMeta() {
                 ...userMeta?.registries,
             };
         }
+        overlayMachineLocal(meta);
         if (applyRegistrySeeds(meta)) {
             writeMeta(meta);
             return rememberMeta(meta);
@@ -673,6 +766,7 @@ export function readMeta() {
         return rememberMeta(meta);
     }
     const meta = createDefaultMeta();
+    overlayMachineLocal(meta);
     if (applyRegistrySeeds(meta)) {
         writeMeta(meta);
     }

package/dist/lib/sync-umbrella.d.ts

@@ -1,11 +1,12 @@
 /**
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
- * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
- * then reconciles it into every installed agent's version home. Each stage is
- * an existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run (`planUmbrellaStages`). The
- * planner is pure so the flag matrix is unit-tested without any I/O.
+ * Bare `agents sync` fetches the config repos then reconciles them into every
+ * installed agent's version home. Secrets and sessions are opt-in stages
+ * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
+ * default. Each stage is an existing exported library function; this module only
+ * sequences them and decides — from the flags — which stages run. The planner is
+ * pure so the flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
@@ -32,11 +33,17 @@ export interface UmbrellaPlan {
 }
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch all three, then reconcile
+ *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
- *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --cloud                fetch repos (or the selected subset), skip reconcile
  *   --repos/--secrets/...  fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
+ *
+ * Secrets and sessions are NOT part of the bare default — they are opt-in via
+ * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
+ * bare `agents sync` is more blast radius than the verb should carry by
+ * default, and session transcripts are queryable on demand (`agents sessions
+ * --host <machine>`) so they don't need eager mirroring.
  */
 export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
 export interface UmbrellaResult {

package/dist/lib/sync-umbrella.js

@@ -1,11 +1,12 @@
 /**
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
- * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
- * then reconciles it into every installed agent's version home. Each stage is
- * an existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run (`planUmbrellaStages`). The
- * planner is pure so the flag matrix is unit-tested without any I/O.
+ * Bare `agents sync` fetches the config repos then reconciles them into every
+ * installed agent's version home. Secrets and sessions are opt-in stages
+ * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
+ * default. Each stage is an existing exported library function; this module only
+ * sequences them and decides — from the flags — which stages run. The planner is
+ * pure so the flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
@@ -20,11 +21,17 @@ import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets/sync.js';
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch all three, then reconcile
+ *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
- *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --cloud                fetch repos (or the selected subset), skip reconcile
  *   --repos/--secrets/...  fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
+ *
+ * Secrets and sessions are NOT part of the bare default — they are opt-in via
+ * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
+ * bare `agents sync` is more blast radius than the verb should carry by
+ * default, and session transcripts are queryable on demand (`agents sessions
+ * --host <machine>`) so they don't need eager mirroring.
  */
 export function planUmbrellaStages(f) {
     if (f.local) {
@@ -39,8 +46,9 @@ export function planUmbrellaStages(f) {
             reconcile: !f.cloud,
         };
     }
-    // No per-type selector: bare = all + reconcile; --cloud = all, no reconcile.
-    return { fetchRepos: true, fetchSecrets: true, fetchSessions: true, reconcile: !f.cloud };
+    // No per-type selector: bare = repos + reconcile; --cloud = repos, no
+    // reconcile. Secrets/sessions stay off unless explicitly selected above.
+    return { fetchRepos: true, fetchSecrets: false, fetchSessions: false, reconcile: !f.cloud };
 }
 /**
  * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.

package/dist/lib/teams/forEach.d.ts

@@ -0,0 +1,110 @@
+import type { AgentManager, AgentProcess, EffortLevel } from './agents.js';
+import { type ForEachSpec, type ForEachTeammate } from '../workflows.js';
+/**
+ * Parse a producer's stdout into the item list `expandForEach` fans out over.
+ *
+ * Two shapes are accepted (issue #343), tried in order:
+ *   1. A JSON array — `["a","b","c"]` (each element coerced to a trimmed string).
+ *   2. Newline-delimited — one item per line.
+ *
+ * Empty lines / entries are dropped so a trailing newline or a `[]` never
+ * fabricates a phantom teammate. Pure and deterministic — no I/O.
+ */
+export declare function parseProducedItems(stdout: string): string[];
+export interface ProduceItemsOptions {
+    /** Working directory for the producer command. */
+    cwd?: string | null;
+    /** Environment for the producer command (defaults to the current process env). */
+    env?: NodeJS.ProcessEnv;
+    /** Kill the producer after this many ms (default 120_000). */
+    timeoutMs?: number;
+    /**
+     * Resolve an `itemsRef` (`${step}`-style reference) to a prior step's produced
+     * list. When a spec carries `itemsRef` and this resolver returns a list, the
+     * producer command is skipped entirely.
+     */
+    resolveItemsRef?: (ref: string) => string[] | undefined;
+}
+/**
+ * Resolve a `for_each` spec's item list at runtime (issue #343): either by
+ * running its `produce:` shell command and parsing stdout, or by resolving an
+ * `itemsRef` to a prior step's list. The resulting items feed `expandForEach` /
+ * `runForEach`.
+ *
+ * `itemsRef` wins when a resolver is supplied and returns a list; otherwise the
+ * `produce` command runs. A spec with neither a resolvable ref nor a produce
+ * command is a hard error — there is nothing to fan out over.
+ */
+export declare function produceItems(spec: ForEachSpec, opts?: ProduceItemsOptions): Promise<string[]>;
+/**
+ * Evaluate a verify panel's `keep_if` gate against its boolean votes (issue
+ * #343). A `true` vote is a skeptic confirming the finding should be kept.
+ *
+ *   - `all`      — every skeptic must vote keep.
+ *   - `any`      — at least one skeptic votes keep.
+ *   - `majority` — strictly more than half vote keep (a tie does NOT pass).
+ *
+ * An empty panel returns false: with no votes there is nothing affirming the
+ * item, so the conservative gate drops it.
+ */
+export declare function evaluateKeepIf(votes: boolean[], keepIf: 'majority' | 'all' | 'any'): boolean;
+/** Per-item verdict after tallying its verify panel. */
+export interface ForEachItemVerdict {
+    /** The produced item this verdict is for. */
+    item: string;
+    /** Zero-based index in the (capped) produced list. */
+    itemIndex: number;
+    /** The stage teammate that handled this item. */
+    stageName: string;
+    /** Whether the item survives its `keep_if` gate (true when it has no panel). */
+    kept: boolean;
+    /** The votes that were tallied (empty when the item has no verify panel). */
+    votes: boolean[];
+    /** The gate applied (undefined when the item has no verify panel). */
+    keepIf?: 'majority' | 'all' | 'any';
+}
+/**
+ * Tally the verify panels of an expanded `for_each` and gate each item (issue
+ * #343). Groups verify teammates by the stage teammate they depend on, reads a
+ * boolean vote per verify teammate via `readVote`, and applies `keep_if`.
+ *
+ * An item with no verify panel is kept unconditionally (there is no gate).
+ * Pure and deterministic: `readVote` is the only place runtime state enters, so
+ * this is unit-testable with a synthetic vote reader.
+ */
+export declare function tallyForEach(teammates: ForEachTeammate[], readVote: (verify: ForEachTeammate) => boolean): ForEachItemVerdict[];
+export interface RunForEachOptions {
+    /** Working directory for the spawned teammates. */
+    cwd?: string | null;
+    /**
+     * Name of the producer teammate the stage teammates should depend on. When
+     * set, each stage runs `--after` the producer so it can't start before the
+     * list is available.
+     */
+    producerName?: string;
+    /** Default effort for spawned teammates (per-item overrides live in the spec). */
+    effort?: EffortLevel;
+    /** Concurrency cap for the wave; falls back to the spec's `concurrency`. */
+    concurrency?: number;
+}
+export interface RunForEachResult {
+    /** The expanded descriptors (stage + verify), in spawn order. */
+    teammates: ForEachTeammate[];
+    /** The AgentProcess handles returned by `spawn`, aligned to `teammates`. */
+    spawned: AgentProcess[];
+    /** Items the producer emitted (pre-cap). */
+    producedCount: number;
+    /** Items actually fanned out (post-cap). */
+    usedCount: number;
+    /** How many items the runaway guard dropped. */
+    truncated: number;
+}
+/**
+ * Expand a `for_each` spec against a producer's output and stage every
+ * resulting teammate into the given team via the dynamic-add path.
+ *
+ * Returns the descriptors and the spawned handles so a caller can drive the
+ * supervisor and later gather results (e.g. to evaluate a `verify` panel's
+ * `keep_if` gate — that vote-counting lives downstream, not here).
+ */
+export declare function runForEach(mgr: AgentManager, teamName: string, spec: ForEachSpec, items: string[], opts?: RunForEachOptions): Promise<RunForEachResult>;