@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/onepassword.js

@@ -79,6 +79,7 @@ const IMPORTABLE_FIELD_TYPES = new Set([
     'URL', 'url',
 ]);
 const SKIP_FIELD_LABELS = new Set(['username', 'notesPlain', 'notes']);
+const NOTES_FIELD_LABELS = new Set(['notesplain', 'notes']);
 function pickBestField(fields) {
     const dominated = fields.filter((f) => IMPORTABLE_FIELD_TYPES.has(f.type) &&
         f.value &&
@@ -97,6 +98,52 @@ function pickBestField(fields) {
     // Fall back to first importable field
     return dominated[0];
 }
+/**
+ * The item's notes, if any — a NOTES-purpose field (1Password's `notesPlain`)
+ * or a field labelled notes/notesPlain, whichever carries a non-empty value.
+ * Returns undefined when the item has no notes. This is descriptive metadata
+ * only; it is deliberately independent of value selection and is never picked
+ * as the secret value (see SKIP_FIELD_LABELS / pickBestField).
+ */
+function pickNotes(fields) {
+    const notes = fields.find((f) => f.value != null &&
+        f.value.trim() !== '' &&
+        (f.purpose?.toUpperCase() === 'NOTES' ||
+            NOTES_FIELD_LABELS.has(f.label?.toLowerCase() || '')));
+    const value = notes?.value?.trim();
+    return value ? value : undefined;
+}
+/**
+ * Pure transform from a fetched 1Password item to an importable secret (or the
+ * reason it was skipped). Split out of extractSecrets so the field-selection
+ * and notes-extraction logic is exercised directly by tests without shelling
+ * out to `op`.
+ */
+export function itemToSecret(item) {
+    const field = pickBestField(item.fields || []);
+    if (!field) {
+        return { skipped: { itemTitle: item.title, fieldLabel: '*', reason: 'no importable fields' } };
+    }
+    if (field.value.includes('\n')) {
+        return {
+            skipped: {
+                itemTitle: item.title,
+                fieldLabel: field.label,
+                reason: 'contains newlines (keychain limitation)',
+            },
+        };
+    }
+    const secret = {
+        envKey: toEnvKey(item.title),
+        itemTitle: item.title,
+        fieldLabel: field.label,
+        value: field.value,
+    };
+    const description = pickNotes(item.fields || []);
+    if (description)
+        secret.description = description;
+    return { secret };
+}
 export function extractSecrets(items, vaultName) {
     const secrets = [];
     const skipped = [];
@@ -113,30 +160,13 @@ export function extractSecrets(items, vaultName) {
             });
             continue;
         }
-        const field = pickBestField(item.fields || []);
-        if (!field) {
-            skipped.push({
-                itemTitle: item.title,
-                fieldLabel: '*',
-                reason: 'no importable fields',
-            });
-            continue;
+        const result = itemToSecret(item);
+        if ('skipped' in result) {
+            skipped.push(result.skipped);
         }
-        if (field.value.includes('\n')) {
-            skipped.push({
-                itemTitle: item.title,
-                fieldLabel: field.label,
-                reason: 'contains newlines (keychain limitation)',
-            });
-            continue;
+        else {
+            secrets.push(result.secret);
         }
-        const envKey = toEnvKey(item.title);
-        secrets.push({
-            envKey,
-            itemTitle: item.title,
-            fieldLabel: field.label,
-            value: field.value,
-        });
     }
     return { secrets, skipped };
 }

package/dist/lib/open-url.js

@@ -1,6 +1,6 @@
 /**
  * Open a URL in the user's default browser, cross-platform. Best-effort and
- * detached — never throws and never blocks the caller. Shared by `agents lease`
+ * detached — never throws and never blocks the caller. Shared by `agents devices lease`
  * (Hetzner console) and `agents fleet login` (the local login dashboard).
  */
 import { spawn } from 'child_process';

package/dist/lib/picker.d.ts

@@ -5,13 +5,25 @@
  * for selecting items in the terminal. Used by session picker, command
  * picker, and other interactive selection flows.
  */
+/**
+ * Custom inquirer prompt for searchable, scrollable selection lists.
+ *
+ * Extends @inquirer/core to support type-ahead filtering, column-aligned
+ * display, and keyboard navigation. Used by sessions, teams, and other
+ * interactive pickers throughout the CLI.
+ */
+import { Separator } from '@inquirer/core';
 /** Configuration for the interactive picker prompt. */
 export interface PickerConfig<T> {
     message: string;
     /** Optional dim hint line rendered directly under the header (above the rows). */
     subtitle?: string;
-    items: T[];
-    filter: (query: string) => T[];
+    /**
+     * The row pool. A {@link Separator} entry renders as a non-selectable divider
+     * (used for group headers) — navigation skips it and it is never returned.
+     */
+    items: Array<T | Separator>;
+    filter: (query: string) => Array<T | Separator>;
     labelFor: (item: T, query: string) => string;
     buildPreview?: (item: T) => string;
     shortIdFor?: (item: T) => string;

package/dist/lib/picker.js

@@ -139,17 +139,39 @@ export function itemPicker(config) {
         const prefix = usePrefix({ status, theme });
         const results = useMemo(() => {
             const filtered = cfg.filter(searchTerm).slice(0, 50);
-            return filtered.map((item) => ({
-                value: item,
-                label: cfg.labelFor(item, searchTerm),
-            }));
+            return filtered.map((item) => Separator.isSeparator(item)
+                ? item
+                : { value: item, label: cfg.labelFor(item, searchTerm) });
         }, [searchTerm]);
+        // A row is selectable unless it is a divider (Separator). Navigation and the
+        // initial cursor skip dividers, and enter never resolves one.
+        const isSelectable = (i) => i >= 0 && i < results.length && !Separator.isSeparator(results[i]);
+        const firstSelectable = () => {
+            for (let i = 0; i < results.length; i++)
+                if (isSelectable(i))
+                    return i;
+            return -1;
+        };
+        const nextSelectable = (from, dir) => {
+            if (results.length === 0)
+                return -1;
+            let i = from;
+            for (let n = 0; n < results.length; n++) {
+                i = (i + dir + results.length) % results.length;
+                if (isSelectable(i))
+                    return i;
+            }
+            return -1;
+        };
         const [active, setActive] = useState(0);
+        // Keep the cursor on a selectable row: after a filter change the old index can
+        // land past the end or on a divider, so snap to the first selectable row.
         useEffect(() => {
-            if (active >= results.length)
-                setActive(0);
+            if (!isSelectable(active))
+                setActive(firstSelectable());
         }, [results]);
-        const selected = results[active];
+        const activeRow = results[active];
+        const selected = activeRow && !Separator.isSeparator(activeRow) ? activeRow : undefined;
         useKeypress((key, rl) => {
             if (isEnterKey(key)) {
                 if (selected) {
@@ -165,16 +187,16 @@ export function itemPicker(config) {
             }
             if (isUpKey(key)) {
                 rl.clearLine(0);
-                if (results.length > 0) {
-                    setActive((active - 1 + results.length) % results.length);
-                }
+                const target = nextSelectable(active, -1);
+                if (target >= 0)
+                    setActive(target);
                 return;
             }
             if (isDownKey(key)) {
                 rl.clearLine(0);
-                if (results.length > 0) {
-                    setActive((active + 1) % results.length);
-                }
+                const target = nextSelectable(active, 1);
+                if (target >= 0)
+                    setActive(target);
                 return;
             }
             setSearchTerm(rl.line);

package/dist/lib/placement.d.ts

@@ -81,6 +81,6 @@ export declare function placementFromHostStrategy(strategy: 'local' | 'host' | '
 /** One-line human form for logs / help. */
 export declare function formatPlacement(p: Placement): string;
 /**
- * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ * Short matrix for help footers and docs. Keep in sync with concepts.md.
  */
 export declare const PLACEMENT_MATRIX: string;

package/dist/lib/placement.js

@@ -176,7 +176,7 @@ export function formatPlacement(p) {
     return p.kind;
 }
 /**
- * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ * Short matrix for help footers and docs. Keep in sync with concepts.md.
  */
 export const PLACEMENT_MATRIX = `
   Intent                         Flag / path

package/dist/lib/pr-land-detach.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Snapshot of the current branch's open PR (if any), for the headless-exit
+ * fail-loud path. Returns null when there is no open PR or `gh` cannot answer.
+ */
+export interface BranchOpenPr {
+    number: number;
+    url: string;
+    state: string;
+}
+/**
+ * Pure classifier: should the exit path warn about this open PR?
+ * Warn when the PR exists and is still OPEN.
+ */
+export declare function shouldWarnOrphanedOpenPr(pr: BranchOpenPr | null): boolean;
+/** Human-readable warning for an open PR the exiting run left unattended. */
+export declare function formatOrphanedOpenPrWarning(pr: BranchOpenPr): string;
+/**
+ * Probe `cwd` for an open PR on the current branch via `gh pr view`.
+ * Fail-open: any error / missing gh → null (never block the run's exit).
+ */
+export declare function getBranchOpenPr(cwd: string, execFileAsync: (file: string, args: string[], opts: {
+    cwd: string;
+    timeout: number;
+    maxBuffer: number;
+}) => Promise<{
+    stdout: string;
+}>): Promise<BranchOpenPr | null>;
+/**
+ * Headless-exit fail-loud: if the cwd's branch has an OPEN PR, print a loud
+ * stderr warning. Never throws.
+ */
+export declare function warnOrphanedOpenPr(cwd?: string): Promise<void>;

package/dist/lib/pr-land-detach.js

@@ -0,0 +1,79 @@
+/**
+ * Headless-exit warning for an open PR left behind by a run (RUSH-2394).
+ *
+ * A headless agent that backgrounds `gh pr checks --watch` and exits strands its
+ * own PR: that watcher is a child of the agent's process tree, so it dies with
+ * the agent and nothing merges on green. This module is the fail-loud half of
+ * that story — it probes the run's branch for an OPEN PR on exit and says so.
+ *
+ * The `agents pr land --detach` lander this warning used to point at was removed
+ * with the `agents pr` command group (RUSH-2472): merge-on-green is a monitor
+ * (`agents monitors`), not a bespoke command with its own scheduler. The
+ * reusable CI/review polling it will run on lives in lib/teams/pr-watch.ts, so
+ * this module keeps only the exit-path warning and names no specific command.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsyncDefault = promisify(execFile);
+/**
+ * Pure classifier: should the exit path warn about this open PR?
+ * Warn when the PR exists and is still OPEN.
+ */
+export function shouldWarnOrphanedOpenPr(pr) {
+    if (!pr)
+        return false;
+    return pr.state.toUpperCase() === 'OPEN';
+}
+/** Human-readable warning for an open PR the exiting run left unattended. */
+export function formatOrphanedOpenPrWarning(pr) {
+    const lines = [
+        '',
+        chalkRed('WARNING: open PR left unattended (RUSH-2394)'),
+        `  ${pr.url}`,
+        `  PR #${pr.number} is still OPEN and nothing is watching it. A background`,
+        '  `gh pr checks --watch` child dies when a headless agent exits, so the PR',
+        '  will sit green and unmerged.',
+        '  Merge it once CI is green and a non-author review has cleared it, or set up',
+        '  a merge-on-green monitor (`agents monitors`) that outlives this process.',
+        '',
+    ];
+    return lines.join('\n');
+}
+/** Tiny chalk-free red for environments where chalk is not wanted on the exit path. */
+function chalkRed(s) {
+    // Match warn-unpushed: bold red when stderr is a TTY; plain otherwise.
+    if (process.stderr.isTTY)
+        return `\u001b[1m\u001b[31m${s}\u001b[0m`;
+    return s;
+}
+/**
+ * Probe `cwd` for an open PR on the current branch via `gh pr view`.
+ * Fail-open: any error / missing gh → null (never block the run's exit).
+ */
+export async function getBranchOpenPr(cwd, execFileAsync) {
+    try {
+        const { stdout } = await execFileAsync('gh', ['pr', 'view', '--json', 'number,url,state'], { cwd, timeout: 5000, maxBuffer: 512 * 1024 });
+        const raw = JSON.parse(stdout);
+        if (!raw?.number || !raw?.url || !raw?.state)
+            return null;
+        return { number: Number(raw.number), url: String(raw.url), state: String(raw.state) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Headless-exit fail-loud: if the cwd's branch has an OPEN PR, print a loud
+ * stderr warning. Never throws.
+ */
+export async function warnOrphanedOpenPr(cwd = process.cwd()) {
+    try {
+        const pr = await getBranchOpenPr(cwd, (file, args, opts) => execFileAsyncDefault(file, args, opts).then((r) => ({ stdout: String(r.stdout ?? '') })));
+        if (!shouldWarnOrphanedOpenPr(pr))
+            return;
+        process.stderr.write(formatOrphanedOpenPrWarning(pr));
+    }
+    catch {
+        // Advisory only — never break the run's exit.
+    }
+}

package/dist/lib/profiles-presets.js

@@ -190,6 +190,19 @@ export const PRESETS = [
             ANTHROPIC_SMALL_FAST_MODEL: 'claude-3-5-haiku-latest',
         },
     },
+    {
+        name: 'deepinfra',
+        description: 'DeepInfra direct API through its OpenAI-compatible endpoint, hosted by Codex.',
+        provider: 'deepinfra',
+        host: 'codex',
+        authEnvVar: 'OPENAI_API_KEY',
+        signupUrl: 'https://deepinfra.com/dash/api_keys',
+        docPath: 'deepinfra',
+        env: {
+            OPENAI_BASE_URL: 'https://api.deepinfra.com/v1/openai',
+            OPENAI_MODEL: 'deepseek-ai/DeepSeek-V3',
+        },
+    },
     // ----- Gateway / enterprise / self-hosted -----
     {
         name: 'proxy',

package/dist/lib/profiles.d.ts

@@ -16,6 +16,8 @@ export interface Profile {
         version?: string;
     };
     env: Record<string, string>;
+    /** Default durable credential account. A per-run --account overrides it. */
+    account?: string;
     auth?: {
         envVar: string;
         keychainItem: string;

package/dist/lib/profiles.js

@@ -7,11 +7,15 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
 import { getUserAgentsDir } from './state.js';
-import { getKeychainToken, hasKeychainToken, keychainItemName } from './secrets/profiles.js';
+import { deleteKeychainToken, getKeychainToken, hasKeychainToken, keychainItemName } from './secrets/profiles.js';
 import { getPreset } from './profiles-presets.js';
 import { MODEL_TIERS, isTierToken } from './model-tiers.js';
+import { addAccount, findAccount, resolveCredentialAccount } from './account-registry.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { listAccountProviders } from './account-provider-registry.js';
 const PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
 /** Get the directory where profile YAML files are stored. */
 export function getProfilesDir() {
@@ -55,8 +59,43 @@ export function readProfile(name) {
     if (!parsed.env || typeof parsed.env !== 'object') {
         parsed.env = {};
     }
+    migrateLegacyProfileAuth(parsed, file);
     return parsed;
 }
+function migrateLegacyProfileAuth(profile, file) {
+    if (!profile.auth || profile.account)
+        return;
+    if (!profile.provider) {
+        throw new Error(`Profile '${profile.name}' owns a legacy credential without a provider. Add a durable account with 'agents accounts add', then set account: <name> in ${file}.`);
+    }
+    const provider = listAccountProviders().includes(profile.provider) ? profile.provider : 'proxy';
+    const suffix = crypto.createHash('sha256').update(profile.auth.keychainItem).digest('hex').slice(0, 8);
+    const accountName = `legacy-${profile.provider}-${suffix}`;
+    if (!findAccount(accountName)) {
+        const kind = profile.auth.envVar.includes('BEARER_TOKEN') ? 'bearer-token' : 'api-key';
+        addAccount(accountName, provider, kind, getKeychainToken(profile.auth.keychainItem));
+    }
+    const migratedAccount = findAccount(accountName);
+    const oldItem = profile.auth.keychainItem;
+    profile.account = migratedAccount.id;
+    profile.provider = provider;
+    delete profile.auth;
+    delete profile.authOptional;
+    atomicWriteFileSync(file, yaml.stringify(profile));
+    const stillReferenced = fs.readdirSync(path.dirname(file))
+        .filter(entry => /\.ya?ml$/.test(entry) && path.join(path.dirname(file), entry) !== file)
+        .some(entry => {
+        try {
+            const other = yaml.parse(fs.readFileSync(path.join(path.dirname(file), entry), 'utf8'));
+            return other?.auth?.keychainItem === oldItem;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!stillReferenced)
+        deleteKeychainToken(oldItem);
+}
 /** Write a profile to disk atomically (write-to-tmp then rename). */
 export function writeProfile(profile) {
     validateProfileName(profile.name);
@@ -437,6 +476,10 @@ export function renameProfile(oldName, newName) {
  */
 export function resolveProfileEnv(profile) {
     const env = { ...profile.env };
+    if (profile.account) {
+        const account = resolveCredentialAccount(profile.account, profile.host.agent, profile.provider);
+        Object.assign(env, account.env);
+    }
     if (profile.auth) {
         // Optional auth (host manages its own login) with no stored token: inject
         // nothing and let the host use its own credentials. Only required auth

package/dist/lib/project-focus.d.ts

@@ -46,6 +46,6 @@ export declare function formatFocusCount(n: number): string;
  * One scannable focus line: path + count, with a single unit trailer so the
  * bare integer is never mistaken for commits or minutes.
  *
- *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/factory/src 245  file-touches (7d)
+ *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/ext/src 245  file-touches (7d)
  */
 export declare function formatFocusAreas(areas: FocusArea[], windowDays: number): string;

package/dist/lib/project-focus.js

@@ -92,7 +92,7 @@ export function formatFocusCount(n) {
  * One scannable focus line: path + count, with a single unit trailer so the
  * bare integer is never mistaken for commits or minutes.
  *
- *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/factory/src 245  file-touches (7d)
+ *   apps/cli/src 2.3k  ·  apps/cli/docs 302  ·  apps/ext/src 245  file-touches (7d)
  */
 export function formatFocusAreas(areas, windowDays) {
     if (areas.length === 0)

package/dist/lib/project-probe.d.ts

@@ -11,7 +11,7 @@
  * and offline-safe. The fleet half (`--fleet`) just runs this probe on every
  * peer via the canonical `remote-agents-json` SSH fan-out.
  */
-import type { ProjectDef } from './projects.js';
+import { type ProjectDef } from './projects.js';
 /** The on-disk state of one workspace repo on one machine. */
 export interface RepoWorkspaceStatus {
     /** The probed path, echoed home-relative (re-roots per machine). */
@@ -52,6 +52,9 @@ export declare function probeProjectWorkspaces(paths: string[]): RepoWorkspaceSt
  * probe echoes, so a hand-edited def (absolute path under home, trailing
  * slash) matches its probe rows exactly — `writeProjectDef` normalizes on
  * write, but defs are hand-editable YAML and never silently drop a row.
+ *
+ * The walk itself lives in `projects.ts` so the probe and the spawn grants read
+ * one definition of "the project's directories" instead of two that drift.
  */
 export declare function workspaceTargetsForDef(def: ProjectDef): string[];
 /**

package/dist/lib/project-probe.js

@@ -16,6 +16,7 @@ import * as path from 'path';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { expandLocalHome, toHomeRelative } from './project-root.js';
+import { projectProbeTargets } from './projects.js';
 /** Per-call git budget. A read-only git call taking >3s is wedged by any
  * definition (NFS stall, index lock) — and the fleet fan-out SIGKILLs the SSH
  * hop at 12s, so a probe must fit inside that budget to avoid a slow peer
@@ -87,12 +88,12 @@ export function probeProjectWorkspaces(paths) {
  * probe echoes, so a hand-edited def (absolute path under home, trailing
  * slash) matches its probe rows exactly — `writeProjectDef` normalizes on
  * write, but defs are hand-editable YAML and never silently drop a row.
+ *
+ * The walk itself lives in `projects.ts` so the probe and the spawn grants read
+ * one definition of "the project's directories" instead of two that drift.
  */
 export function workspaceTargetsForDef(def) {
-    const targets = [def.root, ...(def.repos ?? []).map((r) => r.path)]
-        .filter((p) => typeof p === 'string' && p.length > 0)
-        .map((p) => toHomeRelative(expandLocalHome(p)));
-    return [...new Set(targets)];
+    return projectProbeTargets(def);
 }
 /**
  * Parse a peer's `projects probe --json` stdout, tagging each row with the

package/dist/lib/project-resources.js

@@ -30,7 +30,7 @@ export function syncProjectResourcesToAgent(agent, version, projectAgentsDir) {
     }
     syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, next);
     syncProjectSkills(agent, version, projectAgentsDir, agentRoot, result, next);
-    syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, agentRoot, manifest, result, next);
+    syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, agentRoot, result, next);
     syncProjectWorkflows(agent, version, projectAgentsDir, projectRoot, agentRoot, result, next);
     if (next.size > 0 || manifest) {
         writeProjectManifest(agentRoot, Array.from(next).sort());
@@ -258,7 +258,7 @@ function readProjectSubagents(projectAgentsDir) {
     }
     return map;
 }
-function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, agentRoot, manifest, result, manifestPaths) {
+function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, agentRoot, result, manifestPaths) {
     if (!supports(agent, 'subagents', version).ok)
         return;
     const target = subagentTarget(agent);
@@ -266,8 +266,6 @@ function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, age
         return;
     const all = readProjectSubagents(projectAgentsDir);
     const dir = target.dir(projectRoot);
-    const targetDirRel = toPosixRel(path.relative(agentRoot, dir));
-    const hadManagedTarget = manifest?.paths.some((rel) => rel === targetDirRel || rel.startsWith(targetDirRel + '/')) ?? false;
     for (const sub of all.values()) {
         const occupied = target.occupied(dir, sub.name);
         const existing = occupied.find((entry) => pathExists(entry.path));
@@ -283,20 +281,6 @@ function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, age
             // Malformed source or unsupported transform; skip this item.
         }
     }
-    const syncedNames = result.synced
-        .filter((name) => name.startsWith('subagents/'))
-        .map((name) => name.slice('subagents/'.length))
-        .filter((name) => all.has(name))
-        .map((name) => all.get(name));
-    if (target.finalize && (syncedNames.length > 0 || hadManagedTarget)) {
-        target.finalize(dir, syncedNames);
-        for (const entry of target.finalizeOccupied?.(dir) ?? []) {
-            // Same normalization as record(): this is the one manifest write that
-            // doesn't funnel through it (the parent subagent index, e.g. Kimi's
-            // agents/_agents-cli.yaml).
-            manifestPaths.add(toPosixRel(path.relative(agentRoot, entry.path)));
-        }
-    }
 }
 function workflowManagedRelPaths(agent, projectRoot, name, workflowDir) {
     if (agent === 'kimi')

package/dist/lib/project-root.d.ts

@@ -110,3 +110,19 @@ export declare function resolveProjectRef(ref: string, opts: {
     forRemote: boolean;
     cwd?: string;
 }): Promise<string>;
+/**
+ * Resolve a `--project` ref to the cwd an agent lands in PLUS the other
+ * directories that project binds, so a spawn can grant them.
+ *
+ * `cwd` is exactly what `resolveProjectRef` returns — this never changes where
+ * an agent starts. `extraDirs` is every other `repos[].path`, and is empty for
+ * a convention-resolved project (no definition means no bound repos) and for a
+ * definition that binds only its primary checkout.
+ */
+export declare function resolveProjectDirs(ref: string, opts: {
+    forRemote: boolean;
+    cwd?: string;
+}): Promise<{
+    cwd: string;
+    extraDirs: string[];
+}>;

package/dist/lib/project-root.js

@@ -17,7 +17,7 @@ import * as fs from 'fs';
 import { readMeta, updateMeta } from './state.js';
 import { getMainRepoRoot } from './git.js';
 import { toPosix } from './platform/index.js';
-import { loadProjectDef, resolveDefinedProjectPath } from './projects.js';
+import { loadProjectDef, projectDirsAbs, resolveDefinedProjectPath } from './projects.js';
 import { shellQuote } from './ssh-exec.js';
 const HOME = process.env.HOME ?? os.homedir();
 /** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
@@ -157,7 +157,7 @@ export async function ensureProjectRoot(cwd) {
     if (!inferred) {
         throw new Error('Could not determine your projects root. Run once from inside a project ' +
             '(a git repo under your projects dir) so it can be inferred, or set it:\n' +
-            '  agents defaults project-root ~/src/github.com/<you>');
+            '  agents config set project.root ~/src/github.com/<you>');
     }
     updateMeta({ projectRoot: inferred });
     process.stderr.write(`[project] cached projects root: ${inferred}\n`);
@@ -216,3 +216,21 @@ export async function resolveProjectRef(ref, opts) {
     }
     return resolved;
 }
+/**
+ * Resolve a `--project` ref to the cwd an agent lands in PLUS the other
+ * directories that project binds, so a spawn can grant them.
+ *
+ * `cwd` is exactly what `resolveProjectRef` returns — this never changes where
+ * an agent starts. `extraDirs` is every other `repos[].path`, and is empty for
+ * a convention-resolved project (no definition means no bound repos) and for a
+ * definition that binds only its primary checkout.
+ */
+export async function resolveProjectDirs(ref, opts) {
+    const resolved = await resolveProjectRef(ref, opts);
+    const { slug } = parseProjectRef(ref);
+    const def = slug ? loadProjectDef(slug) : undefined;
+    if (!def)
+        return { cwd: resolved, extraDirs: [] };
+    const all = projectDirsAbs(def, { forRemote: opts.forRemote, primary: resolved });
+    return { cwd: resolved, extraDirs: all.filter((d) => d !== resolved) };
+}

package/dist/lib/projects.d.ts

@@ -151,6 +151,25 @@ export declare function removeProjectDef(name: string): boolean;
  * expanded against the local home. Returns undefined when neither is set.
  */
 export declare function projectBasePath(def: ProjectDef, forRemote: boolean): string | undefined;
+/**
+ * The directories `projects status` probes across the fleet: the repo root plus
+ * every bound checkout, home-relative so each host re-roots them, and including
+ * directories absent here so a peer can still answer `✗ missing` for them.
+ */
+export declare function projectProbeTargets(def: ProjectDef): string[];
+/**
+ * The directories an agent spawned on this project should reach: the cwd first
+ * (`resolveDefinedProjectPath`, so cwd behavior is unchanged), then every other
+ * bound repo. `forRemote` keeps them `~/…` so the remote shell re-roots them at
+ * its own `$HOME`; locally they are absolute and filtered to what exists.
+ *
+ * Callers pass the resolved primary so a `--project slug@worktree` run grants
+ * the sibling repos alongside the worktree it actually landed in.
+ */
+export declare function projectDirsAbs(def: ProjectDef, opts: {
+    forRemote: boolean;
+    primary?: string;
+}): string[];
 /**
  * Which defined project a session belongs to, derived from its working
  * directory. A session whose `cwd` sits inside a project's repo root (or a
@@ -162,7 +181,7 @@ export declare function projectBasePath(def: ProjectDef, forRemote: boolean): st
  * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
  * this machine's home layout. A session recorded on a different-home machine
  * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
- * home-relative variant lands (see the deferred item in docs/11-projects.md).
+ * home-relative variant lands (see the deferred item in docs/projects.md).
  */
 export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
 /**