@phnx-labs/agents-cli 1.22.72 → 1.22.74

package/dist/commands/sessions.js

@@ -18,6 +18,7 @@ import { sanitizeForTerminal, redactSecrets } from '../lib/redact.js';
 import { resolveProjectKey } from '../lib/project-key.js';
 import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
 import ora from 'ora';
+import { interruptibleSpinner } from '../lib/spinner.js';
 import { SESSION_AGENTS, isAgentTmuxAlias, sessionDisplayAgent } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
 import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, composeWin32CommandLine } from '../lib/platform/index.js';
@@ -28,14 +29,14 @@ import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
 import { resolveViewingIn, viewingInLabel } from '../lib/session/viewing-in.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
-import { loadFleetActiveSessions, loadLocalActiveSessions, } from '../lib/session/session-cache.js';
+import { loadFleetActiveSessions, loadLocalActiveSessions, readActiveSessionsCache, } from '../lib/session/session-cache.js';
 import { gatherRemoteList, gatherRemoteToolProgramCounts, gatherRemoteToolSearch, runOnPeer } from '../lib/session/remote-list.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
-import { liveSessionMetas } from '../lib/session/live-metadata.js';
+import { liveSessionMetas, fleetExecutionMachineById, reconcileLiveMetaMachine } from '../lib/session/live-metadata.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
@@ -2801,7 +2802,7 @@ limitSource) {
                 const forwarded = ensureWholeIndex(buildForwardedArgs(process.argv, new Set(options.host ?? [])));
                 if (!forwarded.includes('--json'))
                     forwarded.push('--json');
-                const fanSpinner = isInteractiveTerminal() ? ora('Reaching other machines...').start() : null;
+                const fanSpinner = isInteractiveTerminal() ? interruptibleSpinner('Reaching other machines...').start() : null;
                 try {
                     const { sessions: remoteSessions } = await gatherRemoteList(forwarded, undefined);
                     if (remoteSessions.length > 0) {
@@ -2841,7 +2842,7 @@ limitSource) {
             const forwarded = buildForwardedArgs(process.argv, new Set(options.host ?? []));
             if (!forwarded.includes('--json'))
                 forwarded.push('--json');
-            const fanSpinner = isInteractiveTerminal() ? ora('Reaching other machines...').start() : null;
+            const fanSpinner = isInteractiveTerminal() ? interruptibleSpinner('Reaching other machines...').start() : null;
             try {
                 const { sessions: remoteSessions } = await gatherRemoteList(forwarded, options.host);
                 if (remoteSessions.length > 0) {
@@ -4105,7 +4106,7 @@ async function runCloudSessions(query, options) {
         process.exit(1);
     }
     const mode = resolveViewMode(options, filterOpts);
-    const spinner = options.json ? null : ora('Loading cloud sessions...').start();
+    const spinner = options.json ? null : interruptibleSpinner('Loading cloud sessions...').start();
     let sessions;
     try {
         sessions = await discoverCloudSessions({ limit: parseInt(options.limit || '50', 10) });
@@ -4141,7 +4142,7 @@ async function runCloudSessions(query, options) {
         process.exit(1);
     }
     const meta = matches[0];
-    const cachedSpinner = options.json ? null : ora('Fetching session...').start();
+    const cachedSpinner = options.json ? null : interruptibleSpinner('Fetching session...').start();
     let cachedPath;
     try {
         cachedPath = await ensureCloudSessionCached(meta.id);
@@ -4843,6 +4844,59 @@ export function metadataResolveOutcome(localMatches, remote, selector) {
         return { kind: 'ambiguous', candidates };
     return { kind: 'resolved', session: candidates[0].hits[0].session };
 }
+/**
+ * Whether a local candidate answers a full-UUID selector **definitively** — i.e.
+ * whether finding it on this box is the whole answer, so the fleet fan-out can be
+ * skipped (PHNX-3890).
+ *
+ * Two shapes qualify, and both are claims this box can actually back:
+ *
+ * - **A real transcript on this disk** (`filePath`). It renders locally, whoever
+ *   owns it — a local session or a fleet-synced mirror — so no SSH hop is needed.
+ * - **A genuine peer attribution** (`machine` names another box). The row already
+ *   routes the read to its owner through `transcriptOnPeerOf`, so the peer that
+ *   would answer the fan-out is the peer the render already dials.
+ *
+ * What does NOT qualify is the launcher-shim shape: a transcript-less live row
+ * whose `machine` is this box only because it DEFAULTED there
+ * (`activeSessionToSessionMeta`'s `active.machine ?? self`,
+ * `computeLocalMetadataMatches`'s `machine || localMachine`). A dispatcher holds
+ * exactly that row for a session whose agent and transcript live on a peer: the
+ * launch process is here, the conversation is not. Treating it as definitive is
+ * what dead-ended `agents sessions preview <full-uuid>` on the local
+ * "Live session — full transcript not indexed here." stub while a passive peer —
+ * which has no local row at all, so it fans out — rendered the real digest.
+ * Process locality is not transcript locality.
+ */
+export function isLocallyDefinitiveMatch(session, self) {
+    if (session.filePath)
+        return true;
+    return !!session.machine && session.machine !== self;
+}
+/**
+ * Drop the launcher-shim local rows that a peer has since answered for
+ * (PHNX-3890). `fleetCandidatesByQuery` groups a logical session's copies per
+ * machine and every consumer reads `hits[0]`, with local rows passed first — so
+ * simply fanning out is not enough: the self-defaulted shim would still win the
+ * attribution and route the read back to a box with no transcript. When the peer
+ * that actually owns the session has answered the sweep, its row is the strictly
+ * better one, and the shim carries no information the candidate loses (same
+ * logical id, so the candidate — and any ambiguity it is part of — survives
+ * through the remote hit).
+ *
+ * A row that is {@link isLocallyDefinitiveMatch} is never dropped, so a locally
+ * readable transcript or a synced mirror still renders here with no SSH hop. When
+ * no peer answered for that id, the shim is kept: with no fleet evidence, a
+ * transcript-less self-attributed row is indistinguishable from a session THIS box
+ * just started, and dropping it would re-break the cold-index lookup RUSH-2682
+ * fixed.
+ */
+export function preferOwnerAttribution(localMatches, remoteSessions, self) {
+    if (remoteSessions.length === 0)
+        return localMatches;
+    const answeredByPeer = new Set(remoteSessions.map(session => session.id.toLowerCase()));
+    return localMatches.filter(session => isLocallyDefinitiveMatch(session, self) || !answeredByPeer.has(session.id.toLowerCase()));
+}
 /**
  * Local metadata candidates for a selector: the indexed SQLite rows, plus — when
  * an id-shaped selector misses the index entirely — the live-session registry
@@ -4880,7 +4934,20 @@ export async function computeLocalMetadataMatches(selector, scope, deps = {}) {
  */
 export async function liveMetadataMatches(selector, scope, self, deps = {}) {
     const load = deps.loadActive ?? loadLocalActiveSessions;
-    const match = (metas) => resolveIndexedMetadataRows(applyScopeFilters(metas, scope), selector, scope);
+    const loadFleet = deps.loadFleetActive ?? (() => readActiveSessionsCache('fleet')?.sessions ?? []);
+    // A launcher-shim row whose `machine` self-defaulted to this box gets its true
+    // EXECUTION host from the fleet snapshot, so a session dispatched to a peer is
+    // read on that peer instead of dead-ending on the local stub (PHNX-3890). The
+    // read is best-effort: an absent/cold snapshot leaves the row untouched and the
+    // fleet fan-out in resolveSessionMetadataValue supplies the owner instead.
+    let fleetExecMachine;
+    try {
+        fleetExecMachine = fleetExecutionMachineById(loadFleet());
+    }
+    catch {
+        fleetExecMachine = new Map();
+    }
+    const match = (metas) => resolveIndexedMetadataRows(applyScopeFilters(reconcileLiveMetaMachine(metas, fleetExecMachine, self), scope), selector, scope);
     try {
         const cached = liveSessionMetas((await load()).sessions, self, Date.now());
         const hit = match(cached);
@@ -4897,16 +4964,24 @@ export async function liveMetadataMatches(selector, scope, self, deps = {}) {
  * Full UUIDs hit the local SQLite index without any SSH fan-out. */
 export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
     const localMatches = await computeLocalMetadataMatches(selector, scope, deps);
+    const localMachine = machineId();
     // A full-UUID local hit resolves with ZERO SSH: a UUID is globally unique, so
     // finding it locally is the whole answer and no peer is dialed. (A label is
     // NOT resolved local-only here — it can collide with a same-label session on a
     // peer, so it must consult the fleet; see isDefinitiveMatch, RUSH-2203.) The
     // local index lookup is synchronous and completes before any fan-out spawns,
     // so this local hit never waits on a peer.
+    //
+    // "Found it locally" must mean this box can actually ANSWER for it, though —
+    // see isLocallyDefinitiveMatch. A transcript-less launcher shim for a session
+    // executing on a peer is a local row that is not a local answer, and
+    // short-circuiting on it skipped the one fan-out that could have named the
+    // owner (PHNX-3890).
     if (FULL_SESSION_ID_RE.test(selector)) {
         const localOutcome = metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
-        if (localOutcome.kind === 'resolved')
+        if (localOutcome.kind === 'resolved' && isLocallyDefinitiveMatch(localOutcome.session, localMachine)) {
             return localOutcome;
+        }
     }
     if (scope.local === true)
         return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
@@ -4919,7 +4994,7 @@ export async function resolveSessionMetadataValue(selector, scope = {}, deps = {
         const remote = await deps.gatherRemoteList(forwarded, scope.hosts, selectorAllowsEarlyExit(selector)
             ? { isDefinitive: (session) => isDefinitiveMatch(session, selector) }
             : undefined);
-        return metadataResolveOutcome(localMatches, remote, selector);
+        return metadataResolveOutcome(preferOwnerAttribution(localMatches, remote.sessions, localMachine), remote, selector);
     }
     catch (error) {
         return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [error?.message ?? 'fleet fan-out'] }, selector);
@@ -4972,7 +5047,7 @@ export async function resolveSessionMetadata(selector, scope, deps = { gatherRem
     process.stdout.write(serializeResolvedSessionsJson([outcome.session]));
 }
 export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gatherRemoteList, runOnPeer }) {
-    const spinner = isInteractiveTerminal() ? ora('Searching the fleet...').start() : null;
+    const spinner = isInteractiveTerminal() ? interruptibleSpinner('Searching the fleet...').start() : null;
     let candidates = [];
     let deviceCount = 0;
     let unreachable = [];

package/dist/lib/actor.d.ts

@@ -13,6 +13,13 @@ export interface ResolvedActor {
     email?: string;
     /** GitHub handle, when the actors map records one. */
     github?: string;
+    /**
+     * Phoenix (work) identity id for this human, when the actors map records one.
+     * Bridges a personal tailnet login (e.g. a personal gmail) to the stable
+     * internal work identity, so attribution survives whichever email a person
+     * happens to be signed into tailscale with.
+     */
+    phoenixId?: string;
 }
 /** Result of `tailscale whois --json <ip>` we care about. */
 export interface WhoisIdentity {
@@ -28,16 +35,41 @@ export interface WhoisIdentity {
  */
 export declare function actorFromIdentity(who: WhoisIdentity | undefined, host: string, actors: Record<string, ActorConfig>): ResolvedActor;
 /**
- * Compute the actor for a given environment. Pure with respect to `env` (the
- * only impurity is the `tailscale whois` / config read on the fresh-SSH path),
- * so tests can drive every branch by passing an env explicitly.
+ * Injectable tailscale resolvers, so tests can drive the SSH-whois and
+ * local-self branches deterministically without a real tailscale on the box
+ * (a dev machine that *is* on the tailnet would otherwise make the local path
+ * non-deterministic). Production callers use the defaults.
  */
-export declare function computeActor(env?: NodeJS.ProcessEnv): ResolvedActor;
+export interface ActorResolvers {
+    whois: (ip: string) => WhoisIdentity | undefined;
+    self: () => WhoisIdentity | undefined;
+}
+/**
+ * Compute the actor for a given environment. The only impurity is the tailscale
+ * shell-out (injectable via `resolvers`), so tests drive every branch explicitly.
+ *
+ * Resolution order: an inherited env actor wins; otherwise an SSH run whois-es
+ * its client IP; a local run (no SSH) credits the device's own tailnet owner;
+ * and anything unresolvable degrades to `UNRESOLVED@<host>`. Note the self
+ * fallback fires ONLY for a truly local run — an SSH run whose whois fails must
+ * NOT be credited to the box owner (that would misattribute a remote human to
+ * whoever owns the machine).
+ */
+export declare function computeActor(env?: NodeJS.ProcessEnv, resolvers?: ActorResolvers): ResolvedActor;
 /**
  * Resolve the actor for the current process, cached for the process lifetime
  * (the SSH `whois` shell-out runs at most once).
  */
 export declare function resolveActor(): ResolvedActor;
+/**
+ * Test-only: pin the tailscale resolvers `resolveActor()` uses, so a test that
+ * exercises the cached production entrypoint (e.g. `withActorEnv()`) is isolated
+ * from whether the box running it is on the tailnet. `computeActor` already takes
+ * injected resolvers for its unit tests; this extends the same seam to the cached
+ * path. Pass `undefined` to restore the real tailscale resolvers. Resets the
+ * cache so the next `resolveActor()` recomputes under the new resolvers.
+ */
+export declare function setActorResolvers(resolvers: ActorResolvers | undefined): void;
 /** Clear the per-process cache. For tests, and for env changes within a run. */
 export declare function resetActorCache(): void;
 /**

package/dist/lib/actor.js

@@ -7,8 +7,10 @@
  *
  *   - Over SSH (the shared-fleet case): `tailscale whois` the SSH client IP to
  *     the connecting tailnet identity -- a real name + login email.
- *   - Locally (non-SSH): we can't honestly say who is at the box, so the id is
- *     `UNRESOLVED@<host>` and no personal git identity is claimed.
+ *   - Locally (non-SSH): the run belongs to whoever owns this device on the
+ *     tailnet, so we read that owner from `tailscale status` (`.Self.UserID` ->
+ *     `.User[]`). Only if tailscale can't name the device owner either do we fall
+ *     back to the honest `UNRESOLVED@<host>` with no personal git identity claimed.
  *   - Inherited: a child spawn trusts the `AGENTS_ACTOR*` env its parent
  *     stamped rather than re-resolving, so the whole spawn tree shares one actor.
  *
@@ -54,6 +56,38 @@ function tailscaleWhois(ip) {
         return undefined;
     }
 }
+/**
+ * Resolve this device's own tailnet owner via `tailscale status --json`:
+ * `.Self.UserID` indexes into the `.User` map for the owner's login + display
+ * name. Used for a LOCAL run, where there is no SSH client to whois — the run
+ * belongs to whoever owns the box on the tailnet. Same graceful-undefined +
+ * timeout discipline as `tailscaleWhois`: tailscale absent, a wedged daemon, a
+ * tagged (owner-less) device, or a parse failure all yield undefined, never an
+ * error and never a hang on the spawn hot path.
+ */
+function tailscaleSelf() {
+    try {
+        const res = spawnSync('tailscale', ['status', '--json'], {
+            encoding: 'utf-8',
+            windowsHide: true,
+            timeout: WHOIS_TIMEOUT_MS,
+        });
+        if (res.status !== 0 || !res.stdout)
+            return undefined;
+        const data = JSON.parse(res.stdout);
+        const uid = data.Self?.UserID;
+        if (uid == null)
+            return undefined;
+        // The User map is keyed by the UserID rendered as a string.
+        const u = data.User?.[String(uid)];
+        if (!u?.LoginName)
+            return undefined;
+        return { login: u.LoginName, displayName: u.DisplayName };
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Read the actors map from config, tolerant of a missing/unreadable config. */
 function readActors() {
     try {
@@ -96,6 +130,7 @@ export function actorFromIdentity(who, host, actors) {
         name: cfg?.name ?? who?.displayName,
         email: cfg?.email ?? emailFromLogin,
         github: cfg?.github,
+        phoenixId: cfg?.phoenixId,
     };
 }
 /** Reconstruct an actor an ancestor process already resolved into the env. */
@@ -109,31 +144,58 @@ function inheritedActor(env) {
         name: env.AGENTS_ACTOR_NAME || undefined,
         email: env.AGENTS_ACTOR_EMAIL || undefined,
         github: env.AGENTS_ACTOR_GITHUB || undefined,
+        phoenixId: env.AGENTS_ACTOR_PHOENIX_ID || undefined,
     };
 }
+const defaultResolvers = { whois: tailscaleWhois, self: tailscaleSelf };
 /**
- * Compute the actor for a given environment. Pure with respect to `env` (the
- * only impurity is the `tailscale whois` / config read on the fresh-SSH path),
- * so tests can drive every branch by passing an env explicitly.
+ * Compute the actor for a given environment. The only impurity is the tailscale
+ * shell-out (injectable via `resolvers`), so tests drive every branch explicitly.
+ *
+ * Resolution order: an inherited env actor wins; otherwise an SSH run whois-es
+ * its client IP; a local run (no SSH) credits the device's own tailnet owner;
+ * and anything unresolvable degrades to `UNRESOLVED@<host>`. Note the self
+ * fallback fires ONLY for a truly local run — an SSH run whose whois fails must
+ * NOT be credited to the box owner (that would misattribute a remote human to
+ * whoever owns the machine).
  */
-export function computeActor(env = process.env) {
+export function computeActor(env = process.env, resolvers = defaultResolvers) {
     const inherited = inheritedActor(env);
     if (inherited)
         return inherited;
-    const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
-    const who = ssh?.clientIp ? tailscaleWhois(ssh.clientIp) : undefined;
+    const sshRaw = env.SSH_CONNECTION;
+    const ssh = sshRaw ? parseSshConnection(sshRaw) : undefined;
+    let who = ssh?.clientIp ? resolvers.whois(ssh.clientIp) : undefined;
+    // Self-credit only for a genuinely LOCAL run (no SSH_CONNECTION at all). An
+    // SSH session whose connection is unparseable or unresolvable stays
+    // UNRESOLVED rather than being misattributed to the box's owner.
+    if (!who && !sshRaw)
+        who = resolvers.self();
     return actorFromIdentity(who, machineId(), readActors());
 }
 let cached;
+let resolverOverride;
 /**
  * Resolve the actor for the current process, cached for the process lifetime
  * (the SSH `whois` shell-out runs at most once).
  */
 export function resolveActor() {
     if (!cached)
-        cached = computeActor(process.env);
+        cached = computeActor(process.env, resolverOverride ?? defaultResolvers);
     return cached;
 }
+/**
+ * Test-only: pin the tailscale resolvers `resolveActor()` uses, so a test that
+ * exercises the cached production entrypoint (e.g. `withActorEnv()`) is isolated
+ * from whether the box running it is on the tailnet. `computeActor` already takes
+ * injected resolvers for its unit tests; this extends the same seam to the cached
+ * path. Pass `undefined` to restore the real tailscale resolvers. Resets the
+ * cache so the next `resolveActor()` recomputes under the new resolvers.
+ */
+export function setActorResolvers(resolvers) {
+    resolverOverride = resolvers;
+    cached = undefined;
+}
 /** Clear the per-process cache. For tests, and for env changes within a run. */
 export function resetActorCache() {
     cached = undefined;
@@ -156,6 +218,8 @@ export function actorEnv(actor) {
         env.AGENTS_ACTOR_EMAIL = actor.email;
     if (actor.github)
         env.AGENTS_ACTOR_GITHUB = actor.github;
+    if (actor.phoenixId)
+        env.AGENTS_ACTOR_PHOENIX_ID = actor.phoenixId;
     if (actor.kind === 'human' && actor.name && actor.email) {
         env.GIT_AUTHOR_NAME = actor.name;
         env.GIT_AUTHOR_EMAIL = actor.email;

package/dist/lib/agent-spec/index.d.ts

@@ -2,6 +2,10 @@ import type { AgentId } from '../types.js';
 import type { AgentTarget, ResolveOptions, VersionFilter } from './types.js';
 export * from './types.js';
 export * from './primitives.js';
+export * from './package-types.js';
+export { parseAgentPackageManifest, loadAgentPackageManifest } from './package-schema.js';
+export { resolveAgentPackage, effectiveResources } from './package-resolve.js';
+export { materializeAgentPackage, sha256OfReceiptFile } from './materialize.js';
 /** Shared `--help` epilog so every agent-spec command documents the same grammar. */
 export declare const AGENT_SPEC_HELP: string;
 /** Resolve a spec (single or comma-list) into concrete installed targets. */

package/dist/lib/agent-spec/index.js

@@ -10,6 +10,11 @@ import { defaultVersionProvider } from './provider.js';
 import * as core from './resolve.js';
 export * from './types.js';
 export * from './primitives.js';
+// Portable agent-package resolver + native-home materializer (PHNX-3838).
+export * from './package-types.js';
+export { parseAgentPackageManifest, loadAgentPackageManifest } from './package-schema.js';
+export { resolveAgentPackage, effectiveResources } from './package-resolve.js';
+export { materializeAgentPackage, sha256OfReceiptFile } from './materialize.js';
 /** Shared `--help` epilog so every agent-spec command documents the same grammar. */
 export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
     '@latest (highest installed), @oldest (lowest installed), ' +

package/dist/lib/agent-spec/materialize.d.ts

@@ -0,0 +1,13 @@
+import type { MaterializationReceipt, MaterializeOptions, ResolvedAgentPackage } from './package-types.js';
+/**
+ * Materialize `resolved` into a fresh native home for `options.harness`. Fails
+ * closed (throws `AgentPackageError`, writes nothing new) when the harness is
+ * not declared supported by the package, or when any effective resource needs
+ * a capability the harness+version does not have. Idempotent and
+ * deterministic: re-running against the same `outputHome` with the same
+ * inputs produces a byte-identical receipt and prunes any managed path this
+ * materializer previously wrote that the current resource set no longer needs.
+ */
+export declare function materializeAgentPackage(resolved: ResolvedAgentPackage, options: MaterializeOptions): MaterializationReceipt;
+/** Lowercase hex sha256 of arbitrary bytes — exposed for callers that want to verify the receipt file's own digest (Factory's observed-digest record). */
+export declare function sha256OfReceiptFile(receiptPath: string): string;