@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/activity.d.ts

@@ -1,6 +1,8 @@
 import type { EventRecord } from './events.js';
 /** Recognizable milestone events, ordered first in any activity lane. */
-export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created';
+export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created'
+/** Deliberate agent-authored progress post (`agents feed post`). */
+ | 'status.posted';
 /** Routine activity events, collapsed to counts by readers. */
 export type ActivityKind = 'file.edited';
 export type ActivityEventKind = MilestoneEvent | ActivityKind;
@@ -29,12 +31,20 @@ export interface ActivityEvent {
     cwd?: string;
     /** Agent that produced the event (claude, codex, ...). */
     agent?: string;
-    /** Tool that triggered the event (Bash, Task, ExitPlanMode, ...). */
+    /** Tool that triggered the event (Bash, Task, ExitPlanMode, feed.post, ...). */
     tool?: string;
-    /** One-line human summary (plan title, PR command, sub-agent role). */
+    /** One-line human summary (plan title, PR command, sub-agent role, status text). */
     detail?: string;
     /** Extracted URL when the event has one (e.g. the opened PR). */
     url?: string;
+    /** Auto-stamped process identity for deliberate posts (from pid registry / env). */
+    pid?: number;
+    /** Spawn-time join key (`AGENT_LAUNCH_ID`) when known. */
+    launchId?: string;
+    /** Factory terminal id when the launch inherited one. */
+    terminalId?: string;
+    /** `$TMUX_PANE` at launch when recorded. */
+    tmuxPane?: string;
 }
 /**
  * Append one event to a session's activity log. Primarily the Python hook
@@ -110,7 +120,7 @@ export declare function formatActivityLine(ev: ActivityEvent, opts?: {
  * Edit|MultiEdit) so read-only tools never pay the hook cost. Fail-open: any
  * error is swallowed so a logging hiccup never blocks a tool call.
  */
-export declare const ACTIVITY_LOG_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Append agent-activity events for `agents feed` / `agents activity`.\n\nBound to PreToolUse (ExitPlanMode, Task) and PostToolUse (Bash, Write, Edit,\nMultiEdit). One append-only file per session; read-only tools never trigger it\nbecause the manifest matcher excludes them.\n\nSub-agent gate: when the payload carries `agent_type`, this is a Task/Agent\nsub-agent -- skip so only the top-level agent logs its own activity.\n\nFail-open: ANY error is swallowed so a logging hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport re\nimport sys\nimport json\nimport shlex\nimport socket\nfrom datetime import datetime, timezone\n\nMAX_LOG_BYTES = 5 * 1024 * 1024  # cap a pathological session's log\nMILESTONE_EVENTS = {\n    \"plan.created\", \"pr.opened\", \"pr.merged\", \"worktree.created\",\n    \"worktree.removed\", \"commit.created\", \"pushed\", \"subagent.spawned\",\n    \"artifact.created\",\n}\n\n# Deliverable file types + locations -- a Write here is a recognizable artifact\n# (an HTML plan, a PDF report, a rendered image), not a routine code edit.\nARTIFACT_EXTS = {\n    \".html\", \".htm\", \".pdf\", \".png\", \".jpg\", \".jpeg\", \".gif\", \".svg\",\n    \".webp\", \".mp4\", \".mov\", \".webm\", \".csv\", \".xlsx\", \".pptx\", \".docx\",\n}\nARTIFACT_DIR_HINTS = (\"/tmp/\", \"/downloads/\", \"/.agents/artifacts/\")\n\n\ndef is_artifact(file_path):\n    low = (file_path or \"\").lower()\n    if os.path.splitext(low)[1] in ARTIFACT_EXTS:\n        return True\n    return any(hint in low for hint in ARTIFACT_DIR_HINTS)\n\n\ndef first_line(text, limit=140):\n    for raw in (text or \"\").splitlines():\n        s = raw.strip().lstrip(\"#\").strip()\n        if s:\n            return s[:limit]\n    return \"\"\n\n\ndef _subcommand(tokens, tool):\n    \"\"\"First non-flag token after `tool`, i.e. its subcommand (skips -C <path>,\n    -c <cfg>, and other leading flags). None if `tool` isn't the invoked command.\"\"\"\n    try:\n        i = tokens.index(tool) + 1\n    except ValueError:\n        return None, []\n    while i < len(tokens):\n        t = tokens[i]\n        if t in (\"-C\", \"-c\", \"--git-dir\", \"--work-tree\"):\n            i += 2  # flag that consumes the next token\n            continue\n        if t.startswith(\"-\"):\n            i += 1\n            continue\n        return t, tokens[i + 1:]\n    return None, []\n\n\ndef classify_bash(command):\n    \"\"\"Return the milestone event for a git/gh command, else None. Tokenizes so a\n    path like `git diff -- src/commit.ts` is not mistaken for a commit.\"\"\"\n    try:\n        tokens = shlex.split(command or \"\")\n    except Exception:\n        tokens = (command or \"\").split()\n\n    verb, rest = _subcommand(tokens, \"git\")\n    if verb == \"worktree\":\n        sub = rest[0] if rest else \"\"\n        if sub == \"add\":\n            return \"worktree.created\"\n        if sub == \"remove\":\n            return \"worktree.removed\"\n    elif verb == \"commit\":\n        return \"commit.created\"\n    elif verb == \"push\":\n        return \"pushed\"\n\n    verb, rest = _subcommand(tokens, \"gh\")\n    if verb == \"pr\" and rest:\n        if rest[0] == \"create\":\n            return \"pr.opened\"\n        if rest[0] == \"merge\":\n            return \"pr.merged\"\n    return None\n\n\ndef extract_url(tool_response):\n    \"\"\"Pull the first https URL out of a Bash tool response (stdout).\"\"\"\n    text = \"\"\n    if isinstance(tool_response, dict):\n        text = str(tool_response.get(\"stdout\") or tool_response.get(\"output\") or \"\")\n    elif isinstance(tool_response, str):\n        text = tool_response\n    m = re.search(r\"https?://\\S+\", text)\n    return m.group(0).rstrip(\").,\") if m else None\n\n\ndef build_event(payload, hook_event):\n    tool_name = payload.get(\"tool_name\", \"\")\n    tool_input = payload.get(\"tool_input\", {}) or {}\n    tool_response = payload.get(\"tool_response\", {})\n\n    event = None\n    detail = None\n    url = None\n\n    if hook_event == \"PreToolUse\":\n        if tool_name == \"ExitPlanMode\":\n            event = \"plan.created\"\n            detail = first_line(tool_input.get(\"plan\", \"\")) or \"plan presented\"\n        elif tool_name == \"Task\":\n            event = \"subagent.spawned\"\n            role = tool_input.get(\"subagent_type\") or \"agent\"\n            desc = tool_input.get(\"description\") or tool_input.get(\"prompt\") or \"\"\n            detail = (role + \": \" + first_line(desc)).strip(\": \").strip()\n    elif hook_event == \"PostToolUse\":\n        if tool_name == \"Bash\":\n            event = classify_bash(tool_input.get(\"command\", \"\"))\n            if event:\n                detail = first_line(tool_input.get(\"command\", \"\"))\n                url = extract_url(tool_response)\n        elif tool_name in (\"Write\", \"Edit\", \"MultiEdit\"):\n            fp = tool_input.get(\"file_path\") or tool_input.get(\"path\") or \"\"\n            # A freshly-written deliverable is a milestone; edits and code\n            # writes stay routine and collapse to a count.\n            if tool_name == \"Write\" and is_artifact(fp):\n                event = \"artifact.created\"\n            else:\n                event = \"file.edited\"\n            detail = os.path.basename(fp) if fp else tool_name\n\n    if not event:\n        return None, tool_name\n\n    tier = \"milestone\" if event in MILESTONE_EVENTS else \"activity\"\n    record = {\n        \"v\": 1,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"event\": event,\n        \"tier\": tier,\n    }\n    if detail:\n        record[\"detail\"] = detail\n    if url:\n        record[\"url\"] = url\n    record[\"tool\"] = tool_name\n    return record, tool_name\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate -- only the top-level agent logs.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    hook_event = payload.get(\"hook_event_name\", \"\")\n    record, tool_name = build_event(payload, hook_event)\n    if not record:\n        return\n\n    safe_session = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id) or \"unknown\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    activity_dir = os.path.join(home, \".agents\", \".history\", \"activity\")\n    target = os.path.join(activity_dir, safe_session + \".jsonl\")\n\n    # Identity (mirrors 10-feed-publish.py).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", hostname.split(\".\")[0].strip().lower()) or \"unknown\"\n\n    record[\"sessionId\"] = session_id\n    record[\"mailboxId\"] = mailbox_id\n    record[\"host\"] = host\n    record[\"runtime\"] = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    if cwd:\n        record[\"cwd\"] = cwd\n    agent = os.environ.get(\"AGENTS_AGENT_NAME\") or \"claude\"\n    record[\"agent\"] = agent\n\n    try:\n        os.makedirs(activity_dir, exist_ok=True)\n        # Cap growth: once over the size limit, keep only milestones.\n        if record[\"tier\"] != \"milestone\":\n            try:\n                if os.path.getsize(target) > MAX_LOG_BYTES:\n                    return\n            except OSError:\n                pass\n        with open(target, \"a\") as f:\n            f.write(json.dumps(record) + \"\\n\")\n    except Exception:\n        pass  # fail open\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const ACTIVITY_LOG_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Append agent-activity events for `agents feed` / `agents activity`.\n\nBound to PreToolUse (ExitPlanMode, Task) and PostToolUse (Bash, Write, Edit,\nMultiEdit). One append-only file per session; read-only tools never trigger it\nbecause the manifest matcher excludes them.\n\nSub-agent gate: when the payload carries `agent_type`, this is a Task/Agent\nsub-agent -- skip so only the top-level agent logs its own activity.\n\nFail-open: ANY error is swallowed so a logging hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport re\nimport sys\nimport json\nimport shlex\nimport socket\nfrom datetime import datetime, timezone\n\nMAX_LOG_BYTES = 5 * 1024 * 1024  # cap a pathological session's log\nMILESTONE_EVENTS = {\n    \"plan.created\", \"pr.opened\", \"pr.merged\", \"worktree.created\",\n    \"worktree.removed\", \"commit.created\", \"pushed\", \"subagent.spawned\",\n    \"artifact.created\", \"status.posted\",\n}\n\n# Deliverable file types + locations -- a Write here is a recognizable artifact\n# (an HTML plan, a PDF report, a rendered image), not a routine code edit.\nARTIFACT_EXTS = {\n    \".html\", \".htm\", \".pdf\", \".png\", \".jpg\", \".jpeg\", \".gif\", \".svg\",\n    \".webp\", \".mp4\", \".mov\", \".webm\", \".csv\", \".xlsx\", \".pptx\", \".docx\",\n}\nARTIFACT_DIR_HINTS = (\"/tmp/\", \"/downloads/\", \"/.agents/artifacts/\")\n\n\ndef is_artifact(file_path):\n    low = (file_path or \"\").lower()\n    if os.path.splitext(low)[1] in ARTIFACT_EXTS:\n        return True\n    return any(hint in low for hint in ARTIFACT_DIR_HINTS)\n\n\ndef first_line(text, limit=140):\n    for raw in (text or \"\").splitlines():\n        s = raw.strip().lstrip(\"#\").strip()\n        if s:\n            return s[:limit]\n    return \"\"\n\n\ndef _subcommand(tokens, tool):\n    \"\"\"First non-flag token after `tool`, i.e. its subcommand (skips -C <path>,\n    -c <cfg>, and other leading flags). None if `tool` isn't the invoked command.\"\"\"\n    try:\n        i = tokens.index(tool) + 1\n    except ValueError:\n        return None, []\n    while i < len(tokens):\n        t = tokens[i]\n        if t in (\"-C\", \"-c\", \"--git-dir\", \"--work-tree\"):\n            i += 2  # flag that consumes the next token\n            continue\n        if t.startswith(\"-\"):\n            i += 1\n            continue\n        return t, tokens[i + 1:]\n    return None, []\n\n\ndef classify_bash(command):\n    \"\"\"Return the milestone event for a git/gh command, else None. Tokenizes so a\n    path like `git diff -- src/commit.ts` is not mistaken for a commit.\"\"\"\n    try:\n        tokens = shlex.split(command or \"\")\n    except Exception:\n        tokens = (command or \"\").split()\n\n    verb, rest = _subcommand(tokens, \"git\")\n    if verb == \"worktree\":\n        sub = rest[0] if rest else \"\"\n        if sub == \"add\":\n            return \"worktree.created\"\n        if sub == \"remove\":\n            return \"worktree.removed\"\n    elif verb == \"commit\":\n        return \"commit.created\"\n    elif verb == \"push\":\n        return \"pushed\"\n\n    verb, rest = _subcommand(tokens, \"gh\")\n    if verb == \"pr\" and rest:\n        if rest[0] == \"create\":\n            return \"pr.opened\"\n        if rest[0] == \"merge\":\n            return \"pr.merged\"\n    return None\n\n\ndef extract_url(tool_response):\n    \"\"\"Pull the first https URL out of a Bash tool response (stdout).\"\"\"\n    text = \"\"\n    if isinstance(tool_response, dict):\n        text = str(tool_response.get(\"stdout\") or tool_response.get(\"output\") or \"\")\n    elif isinstance(tool_response, str):\n        text = tool_response\n    m = re.search(r\"https?://\\S+\", text)\n    return m.group(0).rstrip(\").,\") if m else None\n\n\ndef build_event(payload, hook_event):\n    tool_name = payload.get(\"tool_name\", \"\")\n    tool_input = payload.get(\"tool_input\", {}) or {}\n    tool_response = payload.get(\"tool_response\", {})\n\n    event = None\n    detail = None\n    url = None\n\n    if hook_event == \"PreToolUse\":\n        if tool_name == \"ExitPlanMode\":\n            event = \"plan.created\"\n            detail = first_line(tool_input.get(\"plan\", \"\")) or \"plan presented\"\n        elif tool_name == \"Task\":\n            event = \"subagent.spawned\"\n            role = tool_input.get(\"subagent_type\") or \"agent\"\n            desc = tool_input.get(\"description\") or tool_input.get(\"prompt\") or \"\"\n            detail = (role + \": \" + first_line(desc)).strip(\": \").strip()\n    elif hook_event == \"PostToolUse\":\n        if tool_name == \"Bash\":\n            event = classify_bash(tool_input.get(\"command\", \"\"))\n            if event:\n                detail = first_line(tool_input.get(\"command\", \"\"))\n                url = extract_url(tool_response)\n        elif tool_name in (\"Write\", \"Edit\", \"MultiEdit\"):\n            fp = tool_input.get(\"file_path\") or tool_input.get(\"path\") or \"\"\n            # A freshly-written deliverable is a milestone; edits and code\n            # writes stay routine and collapse to a count.\n            if tool_name == \"Write\" and is_artifact(fp):\n                event = \"artifact.created\"\n            else:\n                event = \"file.edited\"\n            detail = os.path.basename(fp) if fp else tool_name\n\n    if not event:\n        return None, tool_name\n\n    tier = \"milestone\" if event in MILESTONE_EVENTS else \"activity\"\n    record = {\n        \"v\": 1,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"event\": event,\n        \"tier\": tier,\n    }\n    if detail:\n        record[\"detail\"] = detail\n    if url:\n        record[\"url\"] = url\n    record[\"tool\"] = tool_name\n    return record, tool_name\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate -- only the top-level agent logs.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    hook_event = payload.get(\"hook_event_name\", \"\")\n    record, tool_name = build_event(payload, hook_event)\n    if not record:\n        return\n\n    safe_session = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id) or \"unknown\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    activity_dir = os.path.join(home, \".agents\", \".history\", \"activity\")\n    target = os.path.join(activity_dir, safe_session + \".jsonl\")\n\n    # Identity (mirrors 10-feed-publish.py).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", hostname.split(\".\")[0].strip().lower()) or \"unknown\"\n\n    record[\"sessionId\"] = session_id\n    record[\"mailboxId\"] = mailbox_id\n    record[\"host\"] = host\n    record[\"runtime\"] = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    if cwd:\n        record[\"cwd\"] = cwd\n    agent = os.environ.get(\"AGENTS_AGENT_NAME\") or \"claude\"\n    record[\"agent\"] = agent\n\n    try:\n        os.makedirs(activity_dir, exist_ok=True)\n        # Cap growth: once over the size limit, keep only milestones.\n        if record[\"tier\"] != \"milestone\":\n            try:\n                if os.path.getsize(target) > MAX_LOG_BYTES:\n                    return\n            except OSError:\n                pass\n        with open(target, \"a\") as f:\n            f.write(json.dumps(record) + \"\\n\")\n    except Exception:\n        pass  # fail open\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Hook manifest entries (agents.yaml shape) for the activity-log hook. */
 export declare const ACTIVITY_HOOK_DEFINITIONS: Record<string, Record<string, unknown>>;
 /**

package/dist/lib/activity.js

@@ -34,6 +34,7 @@ export const MILESTONE_EVENTS = [
     'pushed',
     'subagent.spawned',
     'artifact.created',
+    'status.posted',
 ];
 const MILESTONE_SET = new Set(MILESTONE_EVENTS);
 export function tierForEvent(event) {
@@ -82,6 +83,10 @@ function parseLine(line) {
             tool: parsed.tool,
             detail: parsed.detail,
             url: parsed.url,
+            pid: typeof parsed.pid === 'number' ? parsed.pid : undefined,
+            launchId: parsed.launchId,
+            terminalId: parsed.terminalId,
+            tmuxPane: parsed.tmuxPane,
         };
     }
     catch {
@@ -193,11 +198,11 @@ export function activityEventToRecord(ev) {
         hostname: ev.host,
         platform: process.platform,
         arch: process.arch,
-        pid: 0,
+        pid: ev.pid ?? 0,
         ppid: 0,
         event: ev.event,
         level: 'info',
-        caller: 'hook',
+        caller: ev.tool === 'feed.post' ? 'agent' : 'hook',
         session: ev.sessionId,
         osUser: ev.agent ?? 'agent',
         transport: 'local',
@@ -210,6 +215,9 @@ export function activityEventToRecord(ev) {
         detail: ev.detail,
         url: ev.url,
         tier: ev.tier,
+        ...(ev.launchId ? { launchId: ev.launchId } : {}),
+        ...(ev.terminalId ? { terminalId: ev.terminalId } : {}),
+        ...(ev.tmuxPane ? { tmuxPane: ev.tmuxPane } : {}),
     };
 }
 /** Read recent activity across sessions as unified {@link EventRecord}s. */
@@ -230,6 +238,7 @@ export const EVENT_STYLE = {
     'pushed': { glyph: '↥', color: chalk.yellow, label: 'pushed' },
     'subagent.spawned': { glyph: '⑂', color: chalk.magenta, label: 'sub-agent spawned' },
     'artifact.created': { glyph: '▤', color: chalk.cyan, label: 'artifact' },
+    'status.posted': { glyph: '▸', color: chalk.white, label: 'status' },
     'file.edited': { glyph: '·', color: chalk.gray, label: 'file edited' },
 };
 export function styleForEvent(event) {
@@ -240,10 +249,13 @@ export function formatActivityLine(ev, opts = {}) {
     const s = styleForEvent(ev.event);
     const host = opts.showHost && ev.host && ev.host !== 'unknown' ? chalk.gray(`[${ev.host}] `) : '';
     const label = s.color(`${s.glyph} ${s.label}`);
-    const detail = ev.detail ? ` ${truncate(ev.detail, 60)}` : '';
+    // Status posts are the message; allow a longer snippet than tool-derived detail.
+    const detailLimit = ev.event === 'status.posted' ? 100 : 60;
+    const detail = ev.detail ? ` ${truncate(ev.detail, detailLimit)}` : '';
     const url = ev.url ? chalk.gray(` ${ev.url}`) : '';
+    const agent = ev.event === 'status.posted' && ev.agent ? chalk.gray(` · ${ev.agent}`) : '';
     const when = chalk.gray(relTime(ev.ts).padStart(7));
-    return `  ${when}  ${host}${label}${detail}${url}`;
+    return `  ${when}  ${host}${label}${detail}${agent}${url}`;
 }
 // ---------------------------------------------------------------------------
 // Hook installation
@@ -281,7 +293,7 @@ MAX_LOG_BYTES = 5 * 1024 * 1024  # cap a pathological session's log
 MILESTONE_EVENTS = {
     "plan.created", "pr.opened", "pr.merged", "worktree.created",
     "worktree.removed", "commit.created", "pushed", "subagent.spawned",
-    "artifact.created",
+    "artifact.created", "status.posted",
 }
 
 # Deliverable file types + locations -- a Write here is a recognizable artifact

package/dist/lib/actor.d.ts

@@ -0,0 +1,50 @@
+import type { ActorConfig } from './types.js';
+export type ActorKind = 'human' | 'agent';
+export interface ResolvedActor {
+    /**
+     * Stable id for the responsible entity: the tailnet login (usually an email)
+     * for a resolved human, or `UNRESOLVED@<host>` when it can't be determined.
+     */
+    id: string;
+    kind: ActorKind;
+    /** Human-readable name, for git author + display. */
+    name?: string;
+    /** Email, for git author + as a durable key. */
+    email?: string;
+    /** GitHub handle, when the actors map records one. */
+    github?: string;
+}
+/** Result of `tailscale whois --json <ip>` we care about. */
+export interface WhoisIdentity {
+    login?: string;
+    displayName?: string;
+}
+/**
+ * Map a resolved tailnet identity (+ the actors map) to a ResolvedActor. Pure --
+ * the impure whois/config reads happen in computeActor -- so the enrich/override
+ * path is fully testable. No login (local, or an unnameable peer) yields the
+ * honest `UNRESOLVED@<host>`; a login without a config entry still credits git
+ * from the tailnet DisplayName + login email.
+ */
+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.
+ */
+export declare function computeActor(env?: NodeJS.ProcessEnv): 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;
+/** Clear the per-process cache. For tests, and for env changes within a run. */
+export declare function resetActorCache(): void;
+/**
+ * The env an actor propagates to child processes. Always carries the actor id +
+ * kind (so children inherit and don't re-resolve). For a resolved human with a
+ * real name and email, it also carries `GIT_AUTHOR_*` / `GIT_COMMITTER_*` so the
+ * agent's own commits are credited to the person, not the shared account. An
+ * unresolved actor sets no git identity -- git keeps its ambient config.
+ */
+export declare function actorEnv(actor: ResolvedActor): Record<string, string>;

package/dist/lib/actor.js

@@ -0,0 +1,166 @@
+/**
+ * Actor provenance -- who initiated a run.
+ *
+ * One shared account means every session, commit, and event otherwise shows up
+ * as the same person. `resolveActor()` answers "which human is behind this run"
+ * by looking at how the process was reached:
+ *
+ *   - 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.
+ *   - Inherited: a child spawn trusts the `AGENTS_ACTOR*` env its parent
+ *     stamped rather than re-resolving, so the whole spawn tree shares one actor.
+ *
+ * The resolved actor rides the child-process env (`actorEnv()`, merged into
+ * `buildExecEnv`). When the actor is a resolved human, that env also carries
+ * `GIT_AUTHOR_*` / `GIT_COMMITTER_*`, so the agent's own `git commit` is credited
+ * to the person instead of the shared account.
+ *
+ * The optional `actors:` map in agents.yaml enriches or overrides a resolved
+ * identity (pin a work email, add a github handle, mark an entry as an agent).
+ */
+import { spawnSync } from 'child_process';
+import { machineId } from './machine-id.js';
+import { parseSshConnection } from './session/provenance.js';
+import { readMeta } from './state.js';
+/** Hard cap on the whois shell-out — it runs on the spawn hot path. */
+const WHOIS_TIMEOUT_MS = 2000;
+/**
+ * Resolve the tailnet identity behind an IP via `tailscale whois`. Returns
+ * undefined when tailscale is absent, the peer is unknown, the call fails, or it
+ * exceeds WHOIS_TIMEOUT_MS -- every one of those falls back to an unresolved
+ * actor, never an error and never a hang (a wedged tailscaled is timed out, not
+ * waited on, since this sits in buildExecEnv on every agent spawn).
+ */
+function tailscaleWhois(ip) {
+    try {
+        const res = spawnSync('tailscale', ['whois', '--json', ip], {
+            encoding: 'utf-8',
+            windowsHide: true,
+            timeout: WHOIS_TIMEOUT_MS,
+        });
+        // A timeout leaves status null (child killed by SIGTERM) -- the status guard
+        // below treats it as an unresolved actor, same as any other failure.
+        if (res.status !== 0 || !res.stdout)
+            return undefined;
+        const data = JSON.parse(res.stdout);
+        const up = data.UserProfile;
+        if (!up)
+            return undefined;
+        return { login: up.LoginName, displayName: up.DisplayName };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the actors map from config, tolerant of a missing/unreadable config. */
+function readActors() {
+    try {
+        return readMeta().actors ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Find the actors-map entry for a resolved tailnet login. Matches on an entry's
+ * explicit `login`, its map key, or its `email` (all case-insensitive).
+ */
+function findActorConfig(login, actors) {
+    const needle = login.toLowerCase();
+    for (const [key, cfg] of Object.entries(actors)) {
+        const candidates = [cfg.login, key, cfg.email].filter((v) => !!v);
+        if (candidates.some((c) => c.toLowerCase() === needle))
+            return cfg;
+    }
+    return undefined;
+}
+/**
+ * Map a resolved tailnet identity (+ the actors map) to a ResolvedActor. Pure --
+ * the impure whois/config reads happen in computeActor -- so the enrich/override
+ * path is fully testable. No login (local, or an unnameable peer) yields the
+ * honest `UNRESOLVED@<host>`; a login without a config entry still credits git
+ * from the tailnet DisplayName + login email.
+ */
+export function actorFromIdentity(who, host, actors) {
+    const login = who?.login;
+    if (!login) {
+        return { id: `UNRESOLVED@${host}`, kind: 'human' };
+    }
+    const cfg = findActorConfig(login, actors);
+    const emailFromLogin = login.includes('@') ? login : undefined;
+    return {
+        id: login,
+        kind: cfg?.kind ?? 'human',
+        name: cfg?.name ?? who?.displayName,
+        email: cfg?.email ?? emailFromLogin,
+        github: cfg?.github,
+    };
+}
+/** Reconstruct an actor an ancestor process already resolved into the env. */
+function inheritedActor(env) {
+    const id = env.AGENTS_ACTOR;
+    if (!id)
+        return undefined;
+    return {
+        id,
+        kind: env.AGENTS_ACTOR_KIND === 'agent' ? 'agent' : 'human',
+        name: env.AGENTS_ACTOR_NAME || undefined,
+        email: env.AGENTS_ACTOR_EMAIL || undefined,
+        github: env.AGENTS_ACTOR_GITHUB || undefined,
+    };
+}
+/**
+ * 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.
+ */
+export function computeActor(env = process.env) {
+    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;
+    return actorFromIdentity(who, machineId(), readActors());
+}
+let cached;
+/**
+ * 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);
+    return cached;
+}
+/** Clear the per-process cache. For tests, and for env changes within a run. */
+export function resetActorCache() {
+    cached = undefined;
+}
+/**
+ * The env an actor propagates to child processes. Always carries the actor id +
+ * kind (so children inherit and don't re-resolve). For a resolved human with a
+ * real name and email, it also carries `GIT_AUTHOR_*` / `GIT_COMMITTER_*` so the
+ * agent's own commits are credited to the person, not the shared account. An
+ * unresolved actor sets no git identity -- git keeps its ambient config.
+ */
+export function actorEnv(actor) {
+    const env = {
+        AGENTS_ACTOR: actor.id,
+        AGENTS_ACTOR_KIND: actor.kind,
+    };
+    if (actor.name)
+        env.AGENTS_ACTOR_NAME = actor.name;
+    if (actor.email)
+        env.AGENTS_ACTOR_EMAIL = actor.email;
+    if (actor.github)
+        env.AGENTS_ACTOR_GITHUB = actor.github;
+    if (actor.kind === 'human' && actor.name && actor.email) {
+        env.GIT_AUTHOR_NAME = actor.name;
+        env.GIT_AUTHOR_EMAIL = actor.email;
+        env.GIT_COMMITTER_NAME = actor.name;
+        env.GIT_COMMITTER_EMAIL = actor.email;
+    }
+    return env;
+}

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

@@ -1,9 +1,10 @@
 // The production VersionProvider: the only fs/meta-coupled file in the engine.
 // Everything else in this module is pure and testable without it.
-import { listInstalledVersions, getGlobalDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
+import { listInstalledVersions, getGlobalDefault, getIsolatedDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
 export const defaultVersionProvider = {
     listInstalled: (agent) => listInstalledVersions(agent),
     getProjectVersion: (agent, cwd) => getProjectVersion(agent, cwd),
     getGlobalDefault: (agent) => getGlobalDefault(agent),
+    getIsolatedDefault: (agent) => getIsolatedDefault(agent),
     isInstalled: (agent, version) => isVersionInstalled(agent, version),
 };

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

@@ -66,6 +66,15 @@ export function resolveAgentTargets(spec, provider, opts = {}) {
                 push(agent, glob, 'global-default');
                 continue;
             }
+            // An isolated-only agent never has a global default — that is the point — so
+            // without this step `--agents codex` threw "No default version set" at a user
+            // who had explicitly run `agents use codex@<v>`. resolveVersion already had
+            // this fallback; the two resolvers had drifted apart.
+            const iso = provider.getIsolatedDefault(agent);
+            if (iso) {
+                push(agent, iso, 'isolated-default');
+                continue;
+            }
             const installed = provider.listInstalled(agent);
             if (installed.length === 0) {
                 push(agent, null, 'none');
@@ -81,13 +90,17 @@ export function resolveAgentTargets(spec, provider, opts = {}) {
             }
             throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`, 'no-default', agent, installed);
         }
-        // ----- @pinned / @default: the configured global default -----
+        // ----- @pinned / @default: the configured default (global, else isolated) -----
         if (qualifier === 'pinned' || qualifier === 'default') {
-            const def = provider.getGlobalDefault(agent);
+            const glob = provider.getGlobalDefault(agent);
+            // Report which kind it was: an isolated default owns none of the launcher /
+            // shim / config-symlink machinery a global default does, and callers that log
+            // the source shouldn't claim otherwise.
+            const def = glob ?? provider.getIsolatedDefault(agent);
             if (!def) {
                 throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`, 'no-default', agent, provider.listInstalled(agent));
             }
-            push(agent, def, 'global-default(@pinned)');
+            push(agent, def, glob ? 'global-default(@pinned)' : 'isolated-default');
             continue;
         }
         // ----- @all: every installed version -----
@@ -168,7 +181,8 @@ export function resolveListFilter(agent, qualifier, provider, opts = {}) {
     const q = qualifier?.trim();
     if (!q || q === 'any')
         return undefined;
-    if (q === 'default' || q === 'pinned')
-        return provider.getGlobalDefault(agent) ?? undefined;
+    if (q === 'default' || q === 'pinned') {
+        return provider.getGlobalDefault(agent) ?? provider.getIsolatedDefault(agent) ?? undefined;
+    }
     return resolveSingleAgentTarget(`${agent}@${q}`, provider, { ...opts, availableAgents: [agent] }).version;
 }

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

@@ -1,6 +1,6 @@
 import type { AgentId } from '../types.js';
 /** How a resolved version was arrived at — for provenance, display, and error rendering. */
-export type VersionSource = 'explicit' | 'project-pin' | 'global-default' | 'global-default(@pinned)' | 'sole-installed' | 'newest-installed' | 'alias-latest' | 'alias-oldest' | 'none';
+export type VersionSource = 'explicit' | 'project-pin' | 'global-default' | 'isolated-default' | 'global-default(@pinned)' | 'sole-installed' | 'newest-installed' | 'alias-latest' | 'alias-oldest' | 'none';
 export interface AgentTarget {
     agent: AgentId;
     /** Resolved exact version, or null when the agent has no installed versions yet. */
@@ -32,6 +32,14 @@ export interface VersionProvider {
     getProjectVersion(agent: AgentId, cwd: string): string | null;
     /** The configured global default version, or null. */
     getGlobalDefault(agent: AgentId): string | null;
+    /**
+     * The preferred isolated copy. Kept separate from getGlobalDefault on purpose: a
+     * global default owns the launcher, the bare shim and the real ~/.<agent> config
+     * symlink, and an isolated version must never acquire any of those. Folding the
+     * two together here would hand an isolated version back to every caller that
+     * reasonably assumes a global default means "the one that owns the launcher".
+     */
+    getIsolatedDefault(agent: AgentId): string | null;
     /** Whether an exact version is installed. */
     isInstalled(agent: AgentId, version: string): boolean;
 }

package/dist/lib/agents.d.ts

@@ -71,6 +71,17 @@ export declare function getCliPath(agentId: AgentId): Promise<string | null>;
  * back to a plain PATH lookup.
  */
 export declare function getCliState(agentId: AgentId): Promise<CliState>;
+/**
+ * Resolve the agent's OWN install — the one agents-cli does not manage — by plain
+ * PATH lookup, ignoring the version dirs entirely.
+ *
+ * Callers that specifically mean "the user's own globally-installed CLI" must use
+ * this rather than `getCliState`, whose managed fast path reports an installed
+ * version (any version dir, in readdir order) and would therefore hand back an
+ * isolated copy — a copy that is deliberately unreachable from PATH — labelled as
+ * the global install.
+ */
+export declare function getUnmanagedCliState(agentId: AgentId): Promise<CliState>;
 /** Resolve CLI state for all registered agents in parallel. */
 export declare function getAllCliStates(): Promise<Partial<Record<AgentId, CliState>>>;
 /** Info about an existing unmanaged agent installation. */
@@ -230,6 +241,51 @@ export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
 } | null;
 /** @internal test hook — clear the per-process keyring probe cache. */
 export declare function __resetAntigravityKeychainCacheForTest(): void;
+/**
+ * Whether a Claude version home's credential file is present but carries no
+ * token — the "must have a real credential" floor (see
+ * `isValidOpenCodeCredential`) applied to claude.
+ *
+ * A FAILED OAuth refresh leaves exactly this state behind: Claude Code rewrites
+ * `.claude/.credentials.json` with `accessToken: ""`, `refreshToken: ""` and
+ * `expiresAt: 0`, keeping only the descriptive fields (`subscriptionType`,
+ * `rateLimitTier`, `refreshTokenExpiresAt`). Everything we derive from
+ * `.claude.json` — email, plan — still looks healthy, so the install reported
+ * `signedIn: true`, `agents view` drew usage bars for it, and balanced rotation
+ * (whose `authValid` is just "email present") kept picking it — every pick dying
+ * at spawn on "OAuth session expired and could not be refreshed".
+ *
+ * Only decidable off macOS: there the login Keychain is the canonical store and
+ * this file is not authoritative, and probing the Keychain would raise an
+ * authorization sheet per installed version on every `agents run` — the reason
+ * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
+ * only store, so a token-less file is proof of signed-out. `platform` is a
+ * parameter so both branches are testable on any host.
+ *
+ * Sync, no Keychain, no network — safe on the `agents run` hot path.
+ */
+export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether a Claude version home holds its OWN on-disk credential — a non-blank
+ * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
+ * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
+ *
+ * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
+ * (RUSH-1759) so a token-less default account still authenticates. But Claude —
+ * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
+ * env var over a pinned account's config dir, so when balanced rotation pins a
+ * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
+ * is inert and every fire 401s on the one stale token. A routine spawn drops the
+ * ambient token when the pinned account has its own credential (this returns
+ * true) so the account authenticates itself; when it does not (the RUSH-1759
+ * default), the injected token is kept.
+ *
+ * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
+ * login Keychain is the canonical store and probing it raises an auth sheet, and
+ * there the daemon injects no token to shadow (broker-only, usually absent), so
+ * returning false changes nothing. Sync, no Keychain, no network.
+ */
+export declare function claudeHomeHasOwnCredential(base: string, platform?: NodeJS.Platform): boolean;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,