@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/lib/session/tool-store.d.ts

@@ -0,0 +1,15 @@
+import type Database from '../sqlite.js';
+import { type IndexedToolCall } from './tool-calls.js';
+import type { SessionMeta } from './types.js';
+export declare function canonicalToolLedgerPath(filePath: string): string;
+/** Resolve the transcript that actually carries tool events for split-file harnesses. */
+export declare function toolEvidenceSourcePath(filePath: string, agent: string): string;
+/** Remove cached tool evidence when its source transcript no longer exists. */
+export declare function purgeToolCalls(db: Database.Database, sessionId: string): void;
+/** Purge deleted direct children when a transcript directory's stamp changes. */
+export declare function purgeMissingToolCallsInDirectory(db: Database.Database, dirPath: string, currentFilePaths: string[]): number;
+/** Persist one parser batch and its file stamp atomically. */
+export declare function persistToolCalls(db: Database.Database, session: SessionMeta, calls: IndexedToolCall[], sourceStamp: {
+    fileMtimeMs: number;
+    fileSize: number;
+}, mode?: 'replace' | 'append', maxSessionBytes?: number): void;

package/dist/lib/session/tool-store.js

@@ -0,0 +1,198 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, TOOL_SESSION_EVIDENCE_MAX_BYTES, toolCallEvidenceBytes, toolCallKey, } from './tool-calls.js';
+export function canonicalToolLedgerPath(filePath) {
+    let probe = path.resolve(filePath);
+    const suffix = [];
+    while (true) {
+        try {
+            return path.join(fs.realpathSync(probe), ...suffix.reverse());
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                return path.resolve(filePath);
+            suffix.push(path.basename(probe));
+            probe = parent;
+        }
+    }
+}
+/** Resolve the transcript that actually carries tool events for split-file harnesses. */
+export function toolEvidenceSourcePath(filePath, agent) {
+    if (agent === 'kimi' && path.basename(filePath) === 'state.json') {
+        return path.join(path.dirname(filePath), 'agents', 'main', 'wire.jsonl');
+    }
+    if (agent === 'grok' && path.basename(filePath) === 'summary.json') {
+        return path.join(path.dirname(filePath), 'chat_history.jsonl');
+    }
+    return filePath;
+}
+function deleteSessionCalls(db, sessionId) {
+    const keys = db.prepare(`SELECT call_key FROM tool_calls WHERE session_id = ?`).all(sessionId);
+    for (const { call_key } of keys) {
+        db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`).run(call_key);
+        db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`).run(call_key);
+        db.prepare(`DELETE FROM tool_call_text WHERE call_key = ?`).run(call_key);
+    }
+    db.prepare(`DELETE FROM tool_calls WHERE session_id = ?`).run(sessionId);
+}
+/** Remove cached tool evidence when its source transcript no longer exists. */
+export function purgeToolCalls(db, sessionId) {
+    deleteSessionCalls(db, sessionId);
+    db.prepare(`DELETE FROM tool_scan_ledger WHERE session_id = ?`).run(sessionId);
+}
+/** Purge deleted direct children when a transcript directory's stamp changes. */
+export function purgeMissingToolCallsInDirectory(db, dirPath, currentFilePaths) {
+    const normalizedDir = path.normalize(dirPath);
+    const prefix = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep;
+    const present = new Set(currentFilePaths.map((filePath) => path.normalize(filePath)));
+    const rows = db.prepare(`
+    SELECT s.id, s.file_path, s.agent
+    FROM sessions s
+    WHERE substr(s.file_path, 1, ?) = ?
+  `).all(prefix.length, prefix);
+    let purged = 0;
+    for (const row of rows) {
+        const filePath = path.normalize(row.file_path);
+        if (path.dirname(filePath) !== normalizedDir || present.has(filePath))
+            continue;
+        purgeToolCalls(db, row.id);
+        purged++;
+    }
+    return purged;
+}
+/** Persist one parser batch and its file stamp atomically. */
+export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replace', maxSessionBytes = TOOL_SESSION_EVIDENCE_MAX_BYTES) {
+    const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
+    const insertCall = db.prepare(`
+    INSERT INTO tool_calls (
+      call_key, session_id, ordinal, source_call_id, timestamp, tool, input,
+      outcome, exit_code, status_code, error_code, output, error, parse_error
+      , evidence_bytes
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id, ordinal) DO UPDATE SET
+      source_call_id = excluded.source_call_id,
+      timestamp = excluded.timestamp,
+      tool = excluded.tool,
+      input = excluded.input,
+      outcome = excluded.outcome,
+      exit_code = excluded.exit_code,
+      status_code = excluded.status_code,
+      error_code = excluded.error_code,
+      output = excluded.output,
+      error = excluded.error,
+      parse_error = excluded.parse_error,
+      evidence_bytes = excluded.evidence_bytes
+  `);
+    const insertProgram = db.prepare(`INSERT OR IGNORE INTO tool_call_programs (call_key, program) VALUES (?, ?)`);
+    const insertOccurrence = db.prepare(`
+    INSERT INTO tool_program_occurrences (call_key, occurrence_ordinal, program, role)
+    VALUES (?, ?, ?, ?)
+  `);
+    const insertText = db.prepare(`INSERT INTO tool_call_text (call_key, tool, input, output, error) VALUES (?, ?, ?, ?, ?)`);
+    const deletePrograms = db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`);
+    const deleteOccurrences = db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`);
+    const deleteText = db.prepare(`DELETE FROM tool_call_text WHERE call_key = ?`);
+    const deleteCall = db.prepare(`DELETE FROM tool_calls WHERE call_key = ?`);
+    const writeLedger = db.prepare(`
+    INSERT INTO tool_scan_ledger (
+      session_id, file_path, file_mtime_ms, file_size, extractor_version, indexed_at, call_count,
+      evidence_bytes
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_path = excluded.file_path,
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      indexed_at = excluded.indexed_at,
+      call_count = excluded.call_count,
+      evidence_bytes = excluded.evidence_bytes
+  `);
+    const txn = db.transaction(() => {
+        if (mode === 'replace')
+            deleteSessionCalls(db, session.id);
+        const ledgerPath = canonicalToolLedgerPath(sourcePath);
+        const priorLedger = mode === 'append'
+            ? db.prepare(`SELECT call_count, evidence_bytes FROM tool_scan_ledger WHERE session_id = ?`).get(session.id)
+            : undefined;
+        if (mode === 'append' && !priorLedger) {
+            throw new Error('Append tool evidence requires an existing tool ledger row.');
+        }
+        if (mode === 'append' && calls.length === 0) {
+            writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), priorLedger.call_count, priorLedger.evidence_bytes);
+            return;
+        }
+        const limitKey = toolCallKey(session.id, TOOL_INDEX_LIMIT_ORDINAL);
+        const existingSize = db.prepare(`
+      SELECT evidence_bytes FROM tool_calls WHERE session_id = ? AND ordinal = ?
+    `);
+        const priorLimit = mode === 'append'
+            ? existingSize.get(session.id, TOOL_INDEX_LIMIT_ORDINAL)
+            : undefined;
+        deletePrograms.run(limitKey);
+        deleteOccurrences.run(limitKey);
+        deleteText.run(limitKey);
+        deleteCall.run(limitKey);
+        const existingRows = mode === 'append'
+            ? calls.map((call) => ({
+                ordinal: call.ordinal,
+                bytes: existingSize.get(session.id, call.ordinal)?.evidence_bytes ?? 0,
+            }))
+            : [];
+        const existingByOrdinal = new Map(existingRows.map((row) => [row.ordinal, row.bytes]));
+        let storedBytes = priorLedger?.evidence_bytes ?? 0;
+        let count = priorLedger?.call_count ?? 0;
+        if (priorLimit) {
+            storedBytes -= priorLimit.evidence_bytes;
+            count--;
+        }
+        const limitCall = {
+            ordinal: TOOL_INDEX_LIMIT_ORDINAL,
+            timestamp: session.timestamp,
+            tool: 'index_limit',
+            programs: [],
+            programOccurrences: [],
+            input: `Tool evidence stopped at the ${Math.floor(maxSessionBytes / 1024 / 1024)} MiB per-session payload limit.`,
+            outcome: 'unknown',
+            parseError: 'Additional tool calls were not indexed for this session.',
+        };
+        const limitBytes = toolCallEvidenceBytes(limitCall);
+        const ordinaryLimit = Math.max(0, maxSessionBytes - limitBytes);
+        const accepted = [];
+        let truncated = false;
+        for (const call of [...calls].sort((a, b) => a.ordinal - b.ordinal)) {
+            const replacingBytes = existingByOrdinal.get(call.ordinal) ?? 0;
+            const nextBytes = storedBytes - replacingBytes + toolCallEvidenceBytes(call);
+            if (nextBytes > ordinaryLimit) {
+                truncated = true;
+                break;
+            }
+            storedBytes = nextBytes;
+            accepted.push(call);
+            if (!existingByOrdinal.has(call.ordinal) || replacingBytes === 0)
+                count++;
+        }
+        if (truncated) {
+            if (storedBytes + limitBytes <= maxSessionBytes) {
+                accepted.push(limitCall);
+                storedBytes += limitBytes;
+                count++;
+            }
+        }
+        for (const call of accepted) {
+            const key = toolCallKey(session.id, call.ordinal);
+            insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.tool, call.input, call.outcome, call.exitCode ?? null, call.statusCode ?? null, call.errorCode ?? null, call.output ?? null, call.error ?? null, call.parseError ?? null, toolCallEvidenceBytes(call));
+            deletePrograms.run(key);
+            deleteOccurrences.run(key);
+            deleteText.run(key);
+            for (const program of call.programs)
+                insertProgram.run(key, program);
+            call.programOccurrences.forEach((occurrence, occurrenceOrdinal) => {
+                insertOccurrence.run(key, occurrenceOrdinal, occurrence.program, occurrence.role);
+            });
+            insertText.run(key, call.tool, call.input, call.output ?? '', call.error ?? '');
+        }
+        writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), count, storedBytes);
+    });
+    txn();
+}

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

@@ -24,10 +24,17 @@ export interface SessionEvent {
     role?: 'user' | 'assistant';
     content?: string;
     tool?: string;
+    /** Harness-native call identity, used to correlate concurrent results. */
+    callId?: string;
     args?: Record<string, any>;
     path?: string;
     command?: string;
     success?: boolean;
+    /** Structured harness outcome; never inferred from free-text output. */
+    outcome?: 'ok' | 'error' | 'unknown';
+    exitCode?: number;
+    statusCode?: number;
+    errorCode?: string;
     output?: string;
     /** Internal: marks tool_use events from local commands */
     _local?: boolean;
@@ -52,6 +59,15 @@ export interface SessionEvent {
     hookName?: string;
     /** Lifecycle event the hook fired on (SessionStart, PreToolUse, …). */
     hookEvent?: string;
+    /**
+     * Slash-command invocation name (e.g. `/recap`, `/code:commit`), captured
+     * two ways in a Claude transcript: a `role=user` message whose content is
+     * the `<command-name>` wrapper Claude injects for a typed slash command
+     * (`parseClaudeContent`, see `prompt.ts`'s `extractSlashCommandName`), or a
+     * `tool_use` event for the `SlashCommand` tool (a command the MODEL invoked
+     * programmatically, not the user). Undefined for every other event.
+     */
+    slashCommand?: string;
 }
 /** A displayable file attachment discovered in a session transcript. */
 export interface SessionAttachment {
@@ -186,6 +202,39 @@ export interface SessionMeta {
     todos?: TodoProgress;
     /** Most-recent unique directories changed or used as a shell working directory. */
     recentDirectoriesTouched?: string[];
+    /**
+     * Skills invoked during the session (structurally identical to
+     * session/highlights.ts's SkillUse — declared inline here rather than
+     * imported, to avoid a circular import: highlights.ts imports SessionEvent
+     * from this file). Populated by discover.ts's incremental Claude
+     * accumulator (ClaudeParseState.skillEvents, run through extractSkills at
+     * finalize) so session/db.ts's upsertSessionsBatch can write
+     * session_resource_usage rows WITHOUT re-parsing the whole transcript —
+     * the same reason meta.todos/recentDirectoriesTouched are pre-computed by
+     * the caller for claude/codex instead of left to db.ts's re-parse path.
+     */
+    skillsUsed?: Array<{
+        name: string;
+        count: number;
+    }>;
+    /** Sibling of {@link skillsUsed} for slash-command invocations (SessionEvent.slashCommand). */
+    slashCommandsUsed?: Array<{
+        name: string;
+        count: number;
+    }>;
+    /**
+     * Whether this session emitted at least one `browser.navigate` /
+     * `browser.screenshot` event, computed at scan time from a sessionId-scoped
+     * read of the events log (events.ts `query({ sessionId })`) rather than a
+     * transcript re-scan — see `detectToolUsage` in session/db.ts. `undefined`
+     * means a legacy row this scanner hasn't computed the field for yet (never
+     * collapsed to `false`, so a consumer — e.g. sessions-picker.ts's
+     * `classifySessionTool` — knows to fall back to a transcript-derived guess
+     * instead of trusting a false negative).
+     */
+    usedBrowser?: boolean;
+    /** Sibling of {@link usedBrowser} for `computer.action` events. */
+    usedComputer?: boolean;
     /** Linear project containing ticketId, resolved lazily and cached in SQLite. */
     linearProject?: string;
     /** Browser URL for linearProject. */

package/dist/lib/state.d.ts

@@ -272,7 +272,16 @@ export declare function getCompanionDir(): string;
 export declare function getBrowserRuntimeDir(): string;
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export declare function getHelpersDir(): string;
-/** Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/). */
+/**
+ * Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/) — holds
+ * the daemon pid file, heartbeat, start lock, and log. AGENTS_DAEMON_DIR
+ * redirects it to a fork-private temp so daemon tests (which write pid/heartbeat
+ * files and acquire the real start lock) can never clobber a live daemon's state
+ * on a dev machine — the surgical mirror of AGENTS_DEVICES_DIR /
+ * AGENTS_HOOK_SHIMS_DIR, leaving HOME untouched. Read at CALL time (daemon.ts
+ * resolves every path helper through this), so tests/setup.ts can set it before
+ * the daemon module is exercised. Never set in production code.
+ */
 export declare function getDaemonDir(): string;
 /** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
 export declare function getPtyDir(): string;

package/dist/lib/state.js

@@ -579,8 +579,17 @@ export function getCompanionDir() { return COMPANION_CACHE_DIR; }
 export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export function getHelpersDir() { return HELPERS_DIR; }
-/** Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/). */
-export function getDaemonDir() { return DAEMON_DIR; }
+/**
+ * Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/) — holds
+ * the daemon pid file, heartbeat, start lock, and log. AGENTS_DAEMON_DIR
+ * redirects it to a fork-private temp so daemon tests (which write pid/heartbeat
+ * files and acquire the real start lock) can never clobber a live daemon's state
+ * on a dev machine — the surgical mirror of AGENTS_DEVICES_DIR /
+ * AGENTS_HOOK_SHIMS_DIR, leaving HOME untouched. Read at CALL time (daemon.ts
+ * resolves every path helper through this), so tests/setup.ts can set it before
+ * the daemon module is exercised. Never set in production code.
+ */
+export function getDaemonDir() { return process.env.AGENTS_DAEMON_DIR ?? DAEMON_DIR; }
 /** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
 export function getPtyDir() { return PTY_DIR; }
 /** Path to tmux scratch (~/.agents/.cache/helpers/tmux/) — shared server socket + per-session meta JSONs. */

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

@@ -26,10 +26,9 @@ export declare function remoteDefaultBranch(target: string, repoPath: string): s
  * Create a worktree on the host for a teammate, branched off the freshly-fetched
  * default branch. Returns the absolute worktree path on the host.
  *
- * Mirrors local `createWorktree`, with two deliberate differences: it fetches
- * origin first (the orchestrator can't reach into the host's tree to do it), and
- * it bases the branch on `origin/<default>` rather than local `HEAD` so a stale
- * checkout on the host can't fork the teammate off old code.
+ * Same base policy as local `createWorktree`: fetch origin, then
+ * `worktree add -b … origin/<default>` so a stale checkout can't fork the
+ * teammate off old code.
  */
 export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string): string;
 /**

package/dist/lib/teams/remoteWorktree.js

@@ -87,10 +87,9 @@ export function remoteDefaultBranch(target, repoPath) {
  * Create a worktree on the host for a teammate, branched off the freshly-fetched
  * default branch. Returns the absolute worktree path on the host.
  *
- * Mirrors local `createWorktree`, with two deliberate differences: it fetches
- * origin first (the orchestrator can't reach into the host's tree to do it), and
- * it bases the branch on `origin/<default>` rather than local `HEAD` so a stale
- * checkout on the host can't fork the teammate off old code.
+ * Same base policy as local `createWorktree`: fetch origin, then
+ * `worktree add -b … origin/<default>` so a stale checkout can't fork the
+ * teammate off old code.
  */
 export function createRemoteWorktree(target, repoPath, worktreeName) {
     assertValidSshTarget(target);

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

@@ -22,7 +22,17 @@ export declare const DEFAULT_DIFF_MAX_BYTES = 200000;
  */
 export declare function gitDiff(worktreePath: string, maxBytes?: number): Promise<string>;
 /**
- * Create a new git worktree for a teammate.
+ * Resolve the repo's default branch name (origin/HEAD → `main`/`master`/…).
+ * Refreshes origin/HEAD first so a repo cloned before the default was set resolves.
+ * Falls back to `main` when origin/HEAD isn't set.
+ */
+export declare function localDefaultBranch(gitRoot: string): Promise<string>;
+/**
+ * Create a new git worktree for a teammate, branched off the freshly-fetched
+ * default branch. Fetches `origin` first and bases the branch on
+ * `origin/<default>` so a stale local checkout cannot fork teammates off old
+ * code. Matches `createRemoteWorktree` — local and remote isolation share one
+ * base policy.
  *
  * @param repoDir - Directory inside the git repository
  * @param worktreeName - Name for the worktree (used in path and branch)

package/dist/lib/teams/worktree.js

@@ -77,7 +77,34 @@ export async function gitDiff(worktreePath, maxBytes = DEFAULT_DIFF_MAX_BYTES) {
     }
 }
 /**
- * Create a new git worktree for a teammate.
+ * Resolve the repo's default branch name (origin/HEAD → `main`/`master`/…).
+ * Refreshes origin/HEAD first so a repo cloned before the default was set resolves.
+ * Falls back to `main` when origin/HEAD isn't set.
+ */
+export async function localDefaultBranch(gitRoot) {
+    try {
+        await execFileAsync('git', ['remote', 'set-head', 'origin', '--auto'], { cwd: gitRoot });
+    }
+    catch {
+        // Offline / no origin — fall through to symbolic-ref or main.
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd: gitRoot });
+        const base = stdout.trim().replace(/^origin\//, '');
+        if (base)
+            return base;
+    }
+    catch {
+        // no origin/HEAD
+    }
+    return 'main';
+}
+/**
+ * Create a new git worktree for a teammate, branched off the freshly-fetched
+ * default branch. Fetches `origin` first and bases the branch on
+ * `origin/<default>` so a stale local checkout cannot fork teammates off old
+ * code. Matches `createRemoteWorktree` — local and remote isolation share one
+ * base policy.
  *
  * @param repoDir - Directory inside the git repository
  * @param worktreeName - Name for the worktree (used in path and branch)
@@ -90,10 +117,21 @@ export async function createWorktree(repoDir, worktreeName) {
     const gitRoot = await getGitRoot(repoDir);
     const worktreePath = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     const branchName = `agents/${worktreeName}`;
+    const base = await localDefaultBranch(gitRoot);
     await fs.mkdir(path.dirname(worktreePath), { recursive: true });
-    await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, 'HEAD'], {
-        cwd: gitRoot,
-    });
+    // Fetch first so origin/<default> is current. Fail loud on network errors —
+    // silent fallback to HEAD is how swarms write on a days-stale base and only
+    // discover it at merge time.
+    try {
+        await execFileAsync('git', ['fetch', 'origin'], { cwd: gitRoot });
+    }
+    catch (err) {
+        const detail = (err?.stderr || err?.message || String(err)).toString().trim();
+        throw new Error(`createWorktree: git fetch origin failed in ${gitRoot}` +
+            (detail ? `: ${detail}` : '') +
+            `. Cannot base a teammate worktree on a stale remote-tracking ref.`);
+    }
+    await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, `origin/${base}`], { cwd: gitRoot });
     return worktreePath;
 }
 /**

package/dist/lib/types.d.ts

@@ -11,6 +11,23 @@ import type { FeedBroadcastConfig } from './feed-broadcast.js';
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
+/**
+ * Reserved `<agent>` keyword for `agents run auto` — full-auto dispatch:
+ * host (14d launch affinity) → harness (best-account headroom, weighted) →
+ * account (balanced). Lives in lib (not commands/) because both the run
+ * command (exec.ts) and the host dispatch layer (hosts/dispatch.ts, which
+ * arms the chain-hop guard for remote `run auto`) must agree on it.
+ */
+export declare const RUN_AUTO_KEYWORD = "auto";
+/**
+ * Env var a host dispatcher exports into the remote SHELL when it dispatches
+ * `agents run auto`: tells the remote CLI its host layer is already resolved,
+ * so it must not re-run affinity and chain-hop to a third host. It rides the
+ * shell-export prelude (hosts/dispatch.ts `remoteRunShellPrelude`) because
+ * `--env` flags only reach the spawned AGENT's env — the remote CLI's own
+ * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
+ */
+export declare const RUN_AUTO_HOST_RESOLVED_ENV = "AGENTS_RUN_AUTO_HOST_RESOLVED";
 /** Per-agent run strategy config. */
 export interface AgentRunConfig {
     strategy?: RunStrategy;
@@ -605,6 +622,20 @@ export interface DiscoveredPlugin {
      * (e.g. workflow-scoped) — those default to the user marketplace on sync.
      */
     marketplace?: string;
+    /**
+     * Absolute path to the DotAgents repo root containing this plugin — the
+     * grandparent of `root` (`<repo>/plugins/<name>` → `<repo>`), true for every
+     * marketplace kind (user/system/extra/project). DotAgents repos are
+     * git-tracked (plugins.ts), so this pairs with {@link snapshotSha}.
+     */
+    repoRoot: string;
+    /**
+     * Short HEAD sha of `repoRoot`'s git checkout, lazily resolved (a getter,
+     * not computed at discovery time) and memoized per repoRoot
+     * (`git.ts` `resolveSnapshotSha`) — see `ResolvedResource.snapshotSha` for
+     * the identical rationale. `undefined` when `repoRoot` isn't a git repo.
+     */
+    readonly snapshotSha: string | undefined;
 }
 /**
  * Identifies one DotAgents repo that contributes a plugin marketplace. Each

package/dist/lib/types.js

@@ -5,6 +5,23 @@
  * configuration schemas, resource tracking, registry types, and permission
  * formats for each supported agent.
  */
+/**
+ * Reserved `<agent>` keyword for `agents run auto` — full-auto dispatch:
+ * host (14d launch affinity) → harness (best-account headroom, weighted) →
+ * account (balanced). Lives in lib (not commands/) because both the run
+ * command (exec.ts) and the host dispatch layer (hosts/dispatch.ts, which
+ * arms the chain-hop guard for remote `run auto`) must agree on it.
+ */
+export const RUN_AUTO_KEYWORD = 'auto';
+/**
+ * Env var a host dispatcher exports into the remote SHELL when it dispatches
+ * `agents run auto`: tells the remote CLI its host layer is already resolved,
+ * so it must not re-run affinity and chain-hop to a third host. It rides the
+ * shell-export prelude (hosts/dispatch.ts `remoteRunShellPrelude`) because
+ * `--env` flags only reach the spawned AGENT's env — the remote CLI's own
+ * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
+ */
+export const RUN_AUTO_HOST_RESOLVED_ENV = 'AGENTS_RUN_AUTO_HOST_RESOLVED';
 /** Every canonical mode in declaration order. Useful for iteration / validation. */
 export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
 /** Canonical system repo cloned into ~/.agents/.system/. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.21.2",
+  "version": "1.22.0",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -89,6 +89,7 @@
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
+    "acorn": "8.18.0",
     "age-encryption": "0.3.0",
     "chalk": "5.6.2",
     "commander": "15.0.0",
@@ -101,6 +102,7 @@
     "shlex": "3.0.0",
     "simple-git": "3.36.0",
     "smol-toml": "1.7.0",
+    "unbash": "4.0.5",
     "ws": "^8.21.0",
     "yaml": "2.9.0"
   },