@phnx-labs/agents-cli 1.22.110 → 1.22.112

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.22.112
+
+- **Runs expand portable home paths on the executing device (PHNX-3940).** A remote resume terminal could open successfully while its child failed to start because `--cwd '$HOME'` was treated as a literal directory. The shared run path now expands `$HOME` and `~` locally, while preserving those anchors until remote dispatch reaches its target. This fixes direct runs and resumed conversations alike.
+
+## 1.22.111
+
+- **Remote session resume accepts the resolver’s launch metadata (PHNX-3940).** A reachable peer’s valid session row could be rejected because it included a mode or custom harness, leaving the session undiscoverable. The reader now accepts both fields while keeping private transcript paths out of the resolver contract. Malformed responses are reported as invalid data instead of an unreachable device.
+
 ## 1.22.110
 
 - **Session rows are named by what YOU asked for, not by the agent's latest

package/dist/commands/exec.d.ts

@@ -6,8 +6,97 @@
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
 import { type Command } from 'commander';
-import type { ExecEffort } from '../lib/exec.js';
+import type { ExecMode, ExecEffort } from '../lib/exec.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
+interface ExecCommandActionOptions {
+    mode: ExecMode;
+    effort: ExecEffort;
+    model?: string;
+    cwd?: string;
+    /** --project <slug>[@worktree]: resolve cwd from the projects root shorthand. */
+    project?: string;
+    addDir: string[];
+    env: string[];
+    secrets: string[];
+    /** Commander maps `--no-auto-secrets` to `autoSecrets` (default true, false when passed). */
+    autoSecrets?: boolean;
+    json?: boolean;
+    quiet?: boolean;
+    headless?: boolean;
+    interactive?: boolean;
+    /** --no-auth-check: Commander maps it to `authCheck` (default true, false when passed). Silences the logged-out preflight warning on an interactive launch. */
+    authCheck?: boolean;
+    /** --resume [id]: string id/prefix, or `true` for the bare flag (interactive picker). */
+    resume?: string | boolean;
+    sessionId?: string;
+    /** --name <slug>: durable launch handle, resolvable via `agents sessions <name>`. */
+    name?: string;
+    /** --notify: post a desktop notification when a headless run finishes. */
+    notify?: boolean;
+    /** `--no-trace-sync` → commander maps it to `traceSync` (default true, false when passed). Skips the run-exit trace auto-sync for this run (PHNX-3628). */
+    traceSync?: boolean;
+    /** --terminal [backend]: open this run in a terminal tab; `true` = auto-detect. */
+    terminal?: string | boolean;
+    verbose?: boolean;
+    raw?: boolean;
+    /** `--no-tmux` → commander sets this false (default true) to bypass the tmux wrapper. */
+    tmux?: boolean;
+    /** `--disable-tmux` → explicit alias of --no-tmux. */
+    disableTmux?: boolean;
+    timeout?: string;
+    fallback?: string;
+    balanced?: boolean;
+    strategy?: string;
+    /** Restrict selection to a named provider account discovered from live version homes. */
+    account?: string;
+    /**
+     * @deprecated Hidden alias for `--device auto`. Resolved before host dispatch.
+     * Remove after one release.
+     */
+    smart?: boolean;
+    acp?: boolean;
+    yes?: boolean;
+    loop?: boolean;
+    resumeCheckpoint?: string;
+    maxIterations?: string;
+    budget?: string;
+    until?: string;
+    interval?: string;
+    where?: string;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    remoteCwd?: string;
+    follow?: boolean;
+    any?: boolean;
+    copyCreds?: boolean;
+    lease?: string | boolean;
+    box?: string;
+    keepBox?: boolean;
+    fresh?: boolean;
+    reuse?: boolean;
+    bare?: boolean;
+    tailscale?: boolean;
+    cloud?: boolean;
+    provider?: string;
+    repo?: string[];
+    branch?: string;
+    cloudEnv?: string;
+    secretsKeys?: string;
+    allowExpired?: boolean;
+    emitSessionId?: boolean;
+    /** --broadcast: matrix-run the same prompt/task across agents × models. */
+    broadcast?: boolean;
+    /** --task <id>: house broadcast task (with --broadcast). */
+    task?: string;
+    /** --list-tasks: list broadcast tasks. */
+    listTasks?: boolean;
+    /** --results [run-id]: show saved broadcast runs. */
+    results?: string | true;
+    /** --concurrency <n>: broadcast cell parallelism. */
+    concurrency?: string;
+}
 /** Validate a caller-supplied session id before it reaches tmux, paths, indexes, or remote dispatch. */
 export declare function parseExplicitSessionId(value: string): string;
 export interface RunPickerMarkers {
@@ -210,5 +299,21 @@ export declare function runWorkflowForEach(spec: import('../lib/workflows.js').F
     cwd: string;
     effort?: ExecEffort;
 }): Promise<number>;
+/**
+ * The run's working directory from `--cwd` / `--project`. `--project <slug>` owns
+ * the directory and is mutually exclusive with `--cwd`/`--remote-cwd`; both the
+ * main dispatch and the `--terminal` handoff need the same answer, so the rule
+ * and its error live here once instead of in two places that can drift.
+ *
+ * A project that binds several directories also contributes the ones it is not
+ * landing in as `--add-dir` grants, so an agent on a multi-repo project can
+ * actually reach the sibling checkouts. Claude / Cursor / Kimi take the native
+ * flag; Codex folds them into workspace_roots; Grok widens its sandbox profile
+ * (and always injects a rules note). Other harnesses have no multi-root surface
+ * and ignore the grants (cwd only).
+ */
+export declare function resolveRunCwd(options: Pick<ExecCommandActionOptions, 'cwd' | 'project' | 'remoteCwd' | 'addDir'>, opts: {
+    forRemote: boolean;
+}): Promise<string | undefined>;
 /** Register the `agents run <agent> [prompt]` command. */
 export declare function registerRunCommand(program: Command): void;

package/dist/commands/exec.js

@@ -467,9 +467,13 @@ export async function runWorkflowForEach(spec, opts) {
  * (and always injects a rules note). Other harnesses have no multi-root surface
  * and ignore the grants (cwd only).
  */
-async function resolveRunCwd(options, opts) {
-    if (!options.project)
-        return options.cwd;
+export async function resolveRunCwd(options, opts) {
+    if (!options.project) {
+        if (!options.cwd || opts.forRemote)
+            return options.cwd;
+        const { expandLocalHome } = await import('../lib/project-root.js');
+        return expandLocalHome(options.cwd);
+    }
     if (options.cwd || options.remoteCwd) {
         console.error(chalk.red('Pass --project alone — not with --cwd or --remote-cwd.'));
         process.exit(1);
@@ -1614,13 +1618,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { armRunFinishTraceSync } = await import('../lib/run-trace-sync.js');
             armRunFinishTraceSync({ disabled: options.traceSync === false });
         }
-        // --project <slug>[@worktree]: resolve the projects-root shorthand into a
-        // cwd. On a host run it resolves home-relative (`~/…`, so the host expands
-        // it); locally it becomes an absolute path. It owns the working directory,
-        // so it is mutually exclusive with both --cwd and --remote-cwd.
-        if (options.project) {
-            options.cwd = await resolveRunCwd(options, { forRemote: hostGiven.length > 0 });
-        }
+        // Home anchors belong to the executing host; preserve them until a remote
+        // invocation reaches its local execution path.
+        options.cwd = await resolveRunCwd(options, { forRemote: hostGiven.length > 0 });
         if (hostGiven.length > 0) {
             if (new Set(hostGiven).size > 1) {
                 console.error(chalk.red('Conflicting --device values values — pass just one.'));

package/dist/lib/remote-agents-json.js

@@ -170,7 +170,7 @@ export async function gatherRemoteAgentsJson(options, deps = {}) {
             if (!cancelled) {
                 parseFailed.push(target.name);
                 if (!options.quiet) {
-                    process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+                    process.stderr.write(chalk.gray(`  ${target.name}: invalid response data — skipped\n`));
                 }
             }
             return [];

package/dist/lib/session/remote/remote-list.js

@@ -95,7 +95,7 @@ export function parseRemoteList(stdout, machine) {
  * malformed/non-array JSON is an incomplete source, not an empty machine. */
 const SAFE_RESOLVER_KEYS = new Set([
     'id', 'shortId', 'agent', 'origin', 'timestamp', 'lastActivity', 'project',
-    'version', 'label', 'topic', 'machine',
+    'version', 'harness', 'mode', 'label', 'topic', 'machine',
 ]);
 function isSafeResolverRow(value) {
     if (typeof value.id !== 'string' || typeof value.shortId !== 'string'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.110",
+  "version": "1.22.112",
   "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",