@phnx-labs/agents-cli 1.20.44 → 1.20.46

package/dist/lib/session/discover.js

@@ -21,11 +21,11 @@ import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
 import { parseAntigravity } from './parse.js';
-import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand } from './state.js';
+import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket } from './state.js';
 import { costOfUsage } from '../pricing/index.js';
 import { machineId } from './sync/config.js';
 import { mapBounded } from '../concurrency.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, syncNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, seedLabelsFromNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
 import { buildRunNameMap } from './run-names.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
@@ -64,9 +64,11 @@ export async function discoverSessions(options) {
             // reads to behavioral EDR (CrowdStrike Falcon) as a ransomware-style bulk
             // file-enumeration sweep. Same dirs, same results — just not all at once.
             await scanAgentsBounded(agents, agent => dispatchAgentScan(agent, onProgress));
-            // Apply `agents run --name` handles onto the freshly-scanned rows by id —
-            // the same idempotent, re-applied-every-scan pattern as /rename labels.
-            syncNames(buildRunNameMap());
+            // Seed labels from `agents run --name` handles onto the freshly-scanned
+            // rows by id. Runs AFTER the per-agent scans (which applied agent-generated
+            // titles via syncLabels), so a real title always wins and the seed only
+            // backfills sessions that would otherwise be unnamed.
+            seedLabelsFromNames(buildRunNameMap());
         }
         finally {
             releaseScan(process.pid);
@@ -481,6 +483,8 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             prNumber: scan.prNumber,
             worktreeSlug: scan.worktreeSlug,
             ticketId: scan.ticketId,
+            createdTickets: scan.createdTickets,
+            spawnedTeam: scan.spawnedTeam,
         };
     }
     else {
@@ -504,6 +508,8 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             prNumber: scan.prNumber,
             worktreeSlug: scan.worktreeSlug,
             ticketId: scan.ticketId,
+            createdTickets: scan.createdTickets,
+            spawnedTeam: scan.spawnedTeam,
         };
     }
     return { meta, content: scan.contentText || '' };
@@ -715,6 +721,8 @@ export async function readCodexMeta(filePath, resolveAccount, currentVersion) {
         prNumber: scan.prNumber,
         worktreeSlug: scan.worktreeSlug,
         ticketId: scan.ticketId,
+        createdTickets: scan.createdTickets,
+        spawnedTeam: scan.spawnedTeam,
     };
     return { meta, content: scan.contentText || '' };
 }
@@ -1756,6 +1764,12 @@ export async function scanClaudeSession(filePath) {
     let sawPrCreate = false;
     let prUrl;
     let prNumber;
+    // Artifacts the session PRODUCED: tracker refs it created and any team it spawned.
+    // Ticket creation spans two events — a create_issue tool_use, then the tool_result
+    // carrying the new id — so we hold the pending tool_use ids until their result lands.
+    const createdTickets = new Set();
+    const pendingTicketTools = new Set();
+    let spawnedTeam;
     try {
         for await (const line of rl) {
             if (!line.trim())
@@ -1772,6 +1786,39 @@ export async function scanClaudeSession(filePath) {
             if (!entrypoint && typeof parsed.entrypoint === 'string') {
                 entrypoint = parsed.entrypoint;
             }
+            // Produced-artifact signals, structurally (independent of the PR gate below):
+            //   - a Bash `agents teams create/add` command → the team it spawned
+            //   - a Linear create_issue / `gh issue create` tool_use → its result carries
+            //     the new ticket ref, read from the matching tool_result.
+            if (parsed.type === 'assistant' && Array.isArray(parsed.message?.content)) {
+                for (const b of parsed.message.content) {
+                    if (b?.type !== 'tool_use')
+                        continue;
+                    if (!spawnedTeam && typeof b?.input?.command === 'string') {
+                        const team = detectSpawnedTeam(b.input.command);
+                        if (team)
+                            spawnedTeam = team;
+                    }
+                    if (typeof b?.id === 'string' && isTicketCreateTool(b?.name, b?.input?.command)) {
+                        pendingTicketTools.add(b.id);
+                    }
+                }
+            }
+            if (pendingTicketTools.size > 0 && parsed.type === 'user' && Array.isArray(parsed.message?.content)) {
+                for (const b of parsed.message.content) {
+                    if (b?.type !== 'tool_result' || typeof b?.tool_use_id !== 'string')
+                        continue;
+                    if (!pendingTicketTools.has(b.tool_use_id))
+                        continue;
+                    pendingTicketTools.delete(b.tool_use_id);
+                    const text = typeof b.content === 'string'
+                        ? b.content
+                        : Array.isArray(b.content) ? b.content.map((c) => c?.text || '').join('\n') : '';
+                    const t = extractCreatedTicket(text);
+                    if (t)
+                        createdTickets.add(t);
+                }
+            }
             // PR signal, structurally: a Bash tool_use whose command is `gh pr create`
             // marks intent; the pull URL is then read from a tool_result's output.
             if (!prUrl) {
@@ -1900,6 +1947,8 @@ export async function scanClaudeSession(filePath) {
         prNumber,
         worktreeSlug: worktree?.slug,
         ticketId: ticket?.id,
+        createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
+        spawnedTeam,
     };
 }
 /** Stream a Codex JSONL file and extract scan-level metadata (session ID, cwd, topic, tokens). */
@@ -1922,6 +1971,10 @@ async function scanCodexSession(filePath) {
     let sawPrCreate = false;
     let prUrl;
     let prNumber;
+    // Produced artifacts (mirror of the Claude scan): created tracker refs + spawned team.
+    const createdTickets = new Set();
+    const pendingTicketTools = new Set();
+    let spawnedTeam;
     try {
         for await (const line of rl) {
             if (!line.trim())
@@ -1935,23 +1988,39 @@ async function scanCodexSession(filePath) {
             }
             // PR signal, structurally: a Codex `function_call` whose command is
             // `gh pr create`, then the pull URL from a `function_call_output`.
-            if (!prUrl && parsed.type === 'response_item') {
+            if (parsed.type === 'response_item') {
                 const p = parsed.payload || {};
-                if (!sawPrCreate && p.type === 'function_call') {
+                if (p.type === 'function_call') {
                     let cmd = '';
                     try {
                         const args = typeof p.arguments === 'string' ? JSON.parse(p.arguments) : (p.arguments || {});
                         cmd = String(args.command || args.cmd || '');
                     }
                     catch { /* non-JSON args */ }
-                    if (isPrCreateCommand(cmd))
+                    if (!prUrl && !sawPrCreate && isPrCreateCommand(cmd))
                         sawPrCreate = true;
+                    if (!spawnedTeam) {
+                        const team = detectSpawnedTeam(cmd);
+                        if (team)
+                            spawnedTeam = team;
+                    }
+                    if (typeof p.call_id === 'string' && isTicketCreateTool(p.name, cmd)) {
+                        pendingTicketTools.add(p.call_id);
+                    }
                 }
-                if (sawPrCreate && p.type === 'function_call_output') {
-                    const pr = extractPrUrl(String(p.output || ''));
-                    if (pr) {
-                        prUrl = pr.url;
-                        prNumber = pr.number;
+                if (p.type === 'function_call_output') {
+                    if (!prUrl && sawPrCreate) {
+                        const pr = extractPrUrl(String(p.output || ''));
+                        if (pr) {
+                            prUrl = pr.url;
+                            prNumber = pr.number;
+                        }
+                    }
+                    if (typeof p.call_id === 'string' && pendingTicketTools.has(p.call_id)) {
+                        pendingTicketTools.delete(p.call_id);
+                        const t = extractCreatedTicket(String(p.output || ''));
+                        if (t)
+                            createdTickets.add(t);
                     }
                 }
             }
@@ -2044,6 +2113,8 @@ async function scanCodexSession(filePath) {
         prNumber,
         worktreeSlug: worktree?.slug,
         ticketId: ticket?.id,
+        createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
+        spawnedTeam,
     };
 }
 /** Resolve the working directory for an OpenClaw agent from its workspace config. */

package/dist/lib/session/run-names.d.ts

@@ -3,11 +3,12 @@
  * session id of the run it named.
  *
  * `agents run` records `<sessionId>.json` here at launch whenever both a name
- * and a session id are known up front (Claude pre-mints its id — see
- * spawnAgent). The session-discovery pass reads these sidecars and applies the
- * names onto the SQLite index by id (via syncNames), the same idempotent,
- * re-applied-every-scan pattern as Claude `/rename` labels. Names therefore
- * survive transcript rescans without being parsed out of the transcript itself.
+ * and a session id are known up front (Claude pre-mints its id — see spawnAgent;
+ * a teams teammate's Claude session id is its agent id). The session-discovery
+ * pass reads these sidecars and SEEDS the session label by id (via
+ * seedLabelsFromNames) — the launch handle becomes the label, refined later by an
+ * agent-generated title. Idempotent and re-applied every scan, so seeds survive
+ * transcript rescans without being parsed out of the transcript itself.
  *
  * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
  * one small JSON per run under `~/.agents/.cache/run-names/`.
@@ -26,7 +27,8 @@ export declare function runNamesDir(): string;
  */
 export declare function recordRunName(rec: Omit<RunNameRecord, 'ts'>): void;
 /**
- * Build the sessionId → name map from every run-name sidecar, for syncNames to
- * apply onto the index. Returns an empty map when the dir doesn't exist yet.
+ * Build the sessionId → name map from every run-name sidecar, for
+ * seedLabelsFromNames to apply onto the index as label seeds. Returns an empty
+ * map when the dir doesn't exist yet.
  */
 export declare function buildRunNameMap(): Map<string, string | null>;

package/dist/lib/session/run-names.js

@@ -3,11 +3,12 @@
  * session id of the run it named.
  *
  * `agents run` records `<sessionId>.json` here at launch whenever both a name
- * and a session id are known up front (Claude pre-mints its id — see
- * spawnAgent). The session-discovery pass reads these sidecars and applies the
- * names onto the SQLite index by id (via syncNames), the same idempotent,
- * re-applied-every-scan pattern as Claude `/rename` labels. Names therefore
- * survive transcript rescans without being parsed out of the transcript itself.
+ * and a session id are known up front (Claude pre-mints its id — see spawnAgent;
+ * a teams teammate's Claude session id is its agent id). The session-discovery
+ * pass reads these sidecars and SEEDS the session label by id (via
+ * seedLabelsFromNames) — the launch handle becomes the label, refined later by an
+ * agent-generated title. Idempotent and re-applied every scan, so seeds survive
+ * transcript rescans without being parsed out of the transcript itself.
  *
  * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
  * one small JSON per run under `~/.agents/.cache/run-names/`.
@@ -37,8 +38,9 @@ export function recordRunName(rec) {
     }
 }
 /**
- * Build the sessionId → name map from every run-name sidecar, for syncNames to
- * apply onto the index. Returns an empty map when the dir doesn't exist yet.
+ * Build the sessionId → name map from every run-name sidecar, for
+ * seedLabelsFromNames to apply onto the index as label seeds. Returns an empty
+ * map when the dir doesn't exist yet.
  */
 export function buildRunNameMap() {
     const map = new Map();

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

@@ -44,6 +44,10 @@ export interface SessionState {
     pr?: DetectedPr;
     worktree?: DetectedWorktree;
     ticket?: DetectedTicket;
+    /** Tracker refs this session CREATED (Linear create_issue / gh issue create). */
+    createdTickets?: string[];
+    /** Team name this session SPAWNED via `agents teams create/add`. */
+    spawnedTeam?: string;
 }
 export interface StateContext {
     /** Session file mtime; drives running-vs-stale. */
@@ -63,6 +67,24 @@ export declare function detectTicket(text?: string, branch?: string): DetectedTi
 export declare function extractPrUrl(output?: string): DetectedPr | undefined;
 /** True when a Bash/exec command string is a `gh pr create`. */
 export declare function isPrCreateCommand(command?: string): boolean;
+/**
+ * The team a session SPAWNED, from an `agents teams create/add <name>` command.
+ * Returns the team name, or undefined if the command isn't a team spawn. Note this
+ * is the opposite of `isTeamOrigin` (which marks sessions spawned BY a team).
+ */
+export declare function detectSpawnedTeam(command?: string): string | undefined;
+/**
+ * True when a tool_use call CREATES a tracker ticket — a Linear MCP `create_issue`
+ * tool, or a Bash `gh issue create`. The created id is then read from the matching
+ * tool_result via {@link extractCreatedTicket}.
+ */
+export declare function isTicketCreateTool(name?: string, command?: string): boolean;
+/**
+ * Pull a created ticket ref out of a create-issue tool_result. Linear returns a
+ * key like `RUSH-1234`; `gh issue create` returns the issue URL, from which we
+ * take `#<number>`. Returns undefined when neither shape is present.
+ */
+export declare function extractCreatedTicket(text?: string): string | undefined;
 /**
  * Infer live activity + a preview from a chronological event slice. `pr` /
  * `ticket` / `worktree` are attached by `inferSessionState`; this focuses on the
@@ -70,13 +92,17 @@ export declare function isPrCreateCommand(command?: string): boolean;
  */
 export declare function inferActivity(events: SessionEvent[], ctx?: StateContext): SessionState;
 /**
- * Scan an event slice for the durable signals (PR opened, ticket) that aren't
- * about the cwd. Correlates each `gh pr create` with the nearest following
- * tool_result URL; keeps the last PR found.
+ * Scan an event slice for the durable signals that aren't about the cwd: the PR
+ * opened, the injected ticket, plus the artifacts the session PRODUCED — tracker
+ * refs it created and any team it spawned. Each `gh pr create` / create-issue tool
+ * call is correlated with the nearest following tool_result; the team name comes
+ * straight off the `agents teams create/add` command.
  */
 export declare function detectDurableSignals(events: SessionEvent[]): {
     pr?: DetectedPr;
     ticket?: DetectedTicket;
+    createdTickets?: string[];
+    spawnedTeam?: string;
 };
 /** Full inference: activity + preview + durable signals + worktree/ticket from ctx. */
 export declare function inferSessionState(events: SessionEvent[], ctx?: StateContext): SessionState;

package/dist/lib/session/state.js

@@ -37,6 +37,16 @@ const PR_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/pull\/(\d+)/;
 const WORKTREE_RE = /\/\.agents\/worktrees\/([^/]+)/;
 /** gh invocations that create/open a PR. */
 const GH_PR_CREATE_RE = /\bgh\s+pr\s+(?:create|new)\b/;
+/** gh invocation that opens an issue — the created number is read from its result. */
+const GH_ISSUE_CREATE_RE = /\bgh\s+issue\s+create\b/;
+/** A created GitHub issue URL (…/issues/123) in tool-result output. */
+const GH_ISSUE_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/issues\/(\d+)/;
+/**
+ * `agents teams create <name>` / `agents teams add <team> …` (also the `ag` alias).
+ * The team NAME is the first bareword after the sub-verb, skipping any flags. This
+ * is the structural signal that a session SPAWNED a team (vs. was spawned by one).
+ */
+const TEAMS_SPAWN_RE = /\bag(?:ents)?\s+teams?\s+(?:create|add)\s+(?:--?[a-z][\w-]*(?:[= ]\S+)?\s+)*([A-Za-z0-9][\w-]*)/;
 /** Collapse to a single trimmed line for a one-row preview cell. */
 function oneLine(s) {
     return s.replace(/\s+/g, ' ').trim();
@@ -80,6 +90,46 @@ export function extractPrUrl(output) {
 export function isPrCreateCommand(command) {
     return !!command && GH_PR_CREATE_RE.test(command);
 }
+/**
+ * The team a session SPAWNED, from an `agents teams create/add <name>` command.
+ * Returns the team name, or undefined if the command isn't a team spawn. Note this
+ * is the opposite of `isTeamOrigin` (which marks sessions spawned BY a team).
+ */
+export function detectSpawnedTeam(command) {
+    if (!command)
+        return undefined;
+    const m = command.match(TEAMS_SPAWN_RE);
+    return m ? m[1] : undefined;
+}
+/**
+ * True when a tool_use call CREATES a tracker ticket — a Linear MCP `create_issue`
+ * tool, or a Bash `gh issue create`. The created id is then read from the matching
+ * tool_result via {@link extractCreatedTicket}.
+ */
+export function isTicketCreateTool(name, command) {
+    if (typeof name === 'string' && /linear/i.test(name) && /create[_-]?issue/i.test(name))
+        return true;
+    // Any shell tool (Bash / shell / local_shell) running `gh issue create`.
+    if (!!command && GH_ISSUE_CREATE_RE.test(command))
+        return true;
+    return false;
+}
+/**
+ * Pull a created ticket ref out of a create-issue tool_result. Linear returns a
+ * key like `RUSH-1234`; `gh issue create` returns the issue URL, from which we
+ * take `#<number>`. Returns undefined when neither shape is present.
+ */
+export function extractCreatedTicket(text) {
+    if (!text)
+        return undefined;
+    const lin = text.match(TICKET_RE);
+    if (lin && !TICKET_DENYLIST.has(lin[1].split('-')[0]))
+        return lin[1];
+    const gh = text.match(GH_ISSUE_URL_RE);
+    if (gh)
+        return `#${gh[1]}`;
+    return undefined;
+}
 /** Does an assistant message read as a question directed at the user? */
 function looksLikeQuestion(text) {
     const t = text.trim();
@@ -181,14 +231,19 @@ export function inferActivity(events, ctx = {}) {
     return base;
 }
 /**
- * Scan an event slice for the durable signals (PR opened, ticket) that aren't
- * about the cwd. Correlates each `gh pr create` with the nearest following
- * tool_result URL; keeps the last PR found.
+ * Scan an event slice for the durable signals that aren't about the cwd: the PR
+ * opened, the injected ticket, plus the artifacts the session PRODUCED — tracker
+ * refs it created and any team it spawned. Each `gh pr create` / create-issue tool
+ * call is correlated with the nearest following tool_result; the team name comes
+ * straight off the `agents teams create/add` command.
  */
 export function detectDurableSignals(events) {
     let pr;
     let sawPrCreate = false;
     let ticket;
+    let sawTicketCreate = false;
+    let spawnedTeam;
+    const createdTickets = new Set();
     for (const e of events) {
         // Structural PR signal: a real `gh pr create` tool call, then the pull URL
         // from a following tool_result — never a bare URL mentioned in prose.
@@ -201,21 +256,45 @@ export function detectDurableSignals(events) {
                 sawPrCreate = false;
             }
         }
+        // Produced artifacts: a team spawn is read off the command; a created ticket
+        // is a create-issue tool call whose following tool_result carries the new ref.
+        if (e.type === 'tool_use') {
+            if (!spawnedTeam) {
+                const team = detectSpawnedTeam(e.command);
+                if (team)
+                    spawnedTeam = team;
+            }
+            if (isTicketCreateTool(e.tool, e.command))
+                sawTicketCreate = true;
+        }
+        if (sawTicketCreate && e.type === 'tool_result') {
+            const t = extractCreatedTicket(e.output);
+            if (t)
+                createdTickets.add(t);
+            sawTicketCreate = false;
+        }
         if (!ticket && e.type === 'message' && e.role === 'user') {
             ticket = detectTicket(e.content);
         }
     }
-    return { pr, ticket };
+    return {
+        pr,
+        ticket,
+        createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
+        spawnedTeam,
+    };
 }
 /** Full inference: activity + preview + durable signals + worktree/ticket from ctx. */
 export function inferSessionState(events, ctx = {}) {
     const state = inferActivity(events, ctx);
-    const { pr, ticket } = detectDurableSignals(events);
+    const { pr, ticket, createdTickets, spawnedTeam } = detectDurableSignals(events);
     const worktree = detectWorktree(ctx.cwd, ctx.gitBranch);
     return {
         ...state,
         pr: pr ?? state.pr,
         worktree: worktree ?? state.worktree,
         ticket: ticket ?? detectTicket(undefined, ctx.gitBranch) ?? state.ticket,
+        createdTickets,
+        spawnedTeam,
     };
 }

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

@@ -65,16 +65,16 @@ export interface SessionMeta {
     version?: string;
     account?: string;
     topic?: string;
-    /** Custom name the user gave the session (e.g. Claude Code /rename). */
-    label?: string;
     /**
-     * Durable launch handle from `agents run --name <slug>` — an alias chosen at
-     * launch (not derived from the session id), used to resolve the run in
-     * `agents sessions <name>`. Distinct from `label` (post-hoc /rename): a run's
-     * name is immutable; both are searchable. Absent for runs launched without
-     * `--name`.
+     * The session's human-readable name — one field, several sources with a plain
+     * priority: an agent-generated title / Claude `/rename` wins; else the launch
+     * handle seeded from `agents run --name <slug>` (interactive, headless, remote
+     * host, or a teams teammate); else it stays unset and the listing falls back to
+     * `topic`. Searchable via `agents sessions <label>`. (Before v10 the launch
+     * handle lived in a separate immutable `name` column; `--name` now just seeds
+     * this label.)
      */
-    name?: string;
+    label?: string;
     /** Set when this session was spawned by `agents teams`. */
     teamOrigin?: TeamOrigin;
     /** Durable state signals extracted at scan time by the session-state engine. */
@@ -86,6 +86,17 @@ export interface SessionMeta {
     worktreeSlug?: string;
     /** Tracker ticket ref (e.g. RUSH-1234) from the prompt or branch. */
     ticketId?: string;
+    /**
+     * Tracker refs the session CREATED during its run — Linear `create_issue` MCP
+     * calls or `gh issue create` shell commands — read from the tool result. Distinct
+     * from `ticketId` (the injected/worked-on ticket from the prompt or branch).
+     */
+    createdTickets?: string[];
+    /**
+     * Team name this session SPAWNED via `agents teams create/add`. The inverse of
+     * `isTeamOrigin` (which marks sessions spawned BY a team).
+     */
+    spawnedTeam?: string;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

package/dist/lib/shim-heal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Heal the shim/shadow/PATH conditions silently, then return the notice lines to
+ * print ONCE for whatever is left (a real-binary shadow we won't move; a PATH entry
+ * that was just added / needs a reload), or null when there's nothing new to say.
+ */
+export declare function healShimsInteractive(): Promise<string[] | null>;
+type PathNoticeState = 'ok' | 'added' | 'reload';
+/**
+ * A stable signature of the conditions worth surfacing: the sorted set of
+ * real-binary shadows plus the PATH notice state. Empty string = nothing to say.
+ */
+export declare function computeShimNoticeSignature(input: {
+    shadowNotes: string[];
+    pathState: PathNoticeState;
+}): string;
+/**
+ * Whether to surface the notice for the current condition. Returns false (stay
+ * quiet) when the exact same signature was already surfaced, or when there's
+ * nothing to say. On true it records the signature so the next shell with the same
+ * state is suppressed. An empty signature clears the marker.
+ */
+export declare function shouldSurfaceShimNotice(signature: string): boolean;
+export {};

package/dist/lib/shim-heal.js

@@ -0,0 +1,109 @@
+// Interactive shim-heal for the CLI startup path + the persistent notice-state that
+// replaces the old per-PPID sentinel.
+//
+// The actual repair (regenerating shims, adopting symlink launchers, adding the
+// shims dir to PATH) lives in the unified self-heal registry — this module just
+// drives the shim-relevant checks SILENTLY on a normal `agents` invocation and then
+// decides whether to print a one-time notice about anything left. The old flow
+// re-ran its whole detect-and-nag on every new terminal (its sentinel was keyed to
+// process.ppid); the persistent signature here means an unresolved condition is
+// surfaced once, not on every shell.
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRuntimeStateDir } from './state.js';
+/**
+ * Heal the shim/shadow/PATH conditions silently, then return the notice lines to
+ * print ONCE for whatever is left (a real-binary shadow we won't move; a PATH entry
+ * that was just added / needs a reload), or null when there's nothing new to say.
+ */
+export async function healShimsInteractive() {
+    const { runSelfHeal } = await import('./self-heal/registry.js');
+    const report = await runSelfHeal({ checks: ['shims', 'shadowing', 'path'], mode: 'safe' });
+    const shadowNotes = [];
+    let pathAdded = null;
+    let pathReload = null;
+    for (const c of report.checks) {
+        if (!c.result)
+            continue;
+        if (c.id === 'shadowing')
+            shadowNotes.push(...c.result.needsAttention);
+        if (c.id === 'path') {
+            for (const f of c.result.fixed)
+                pathAdded = f; // "added shims to PATH (~/.zshrc)"
+            for (const a of c.result.needsAttention)
+                pathReload = a; // "...not loaded — open a new terminal"
+        }
+    }
+    const pathState = pathAdded ? 'added' : pathReload ? 'reload' : 'ok';
+    const signature = computeShimNoticeSignature({ shadowNotes, pathState });
+    if (!shouldSurfaceShimNotice(signature))
+        return null;
+    const lines = [];
+    if (pathAdded) {
+        lines.push(pathAdded);
+        lines.push('Open a new terminal (or source your shell rc) to pick it up.');
+    }
+    else if (pathReload) {
+        lines.push(pathReload);
+    }
+    if (shadowNotes.length > 0) {
+        lines.push('These agent commands run a native binary instead of the version-managed shim:');
+        for (const note of shadowNotes)
+            lines.push(`  ${note}`);
+        lines.push("It's a real binary (not a symlink), so agents-cli won't move it — reorder PATH or remove it to hand it over.");
+    }
+    return lines.length > 0 ? lines : null;
+}
+function noticeStatePath() {
+    return path.join(getRuntimeStateDir(), 'shim-notice.json');
+}
+/**
+ * A stable signature of the conditions worth surfacing: the sorted set of
+ * real-binary shadows plus the PATH notice state. Empty string = nothing to say.
+ */
+export function computeShimNoticeSignature(input) {
+    const shadows = [...input.shadowNotes].sort().join(',');
+    const parts = [];
+    if (shadows)
+        parts.push(`shadow:${shadows}`);
+    if (input.pathState !== 'ok')
+        parts.push(`path:${input.pathState}`);
+    return parts.join('|');
+}
+function readLastNoticeSignature() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(noticeStatePath(), 'utf-8'));
+        return typeof parsed.signature === 'string' ? parsed.signature : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLastNoticeSignature(signature) {
+    try {
+        fs.mkdirSync(getRuntimeStateDir(), { recursive: true });
+        fs.writeFileSync(noticeStatePath(), JSON.stringify({ signature }));
+    }
+    catch {
+        /* best-effort: never block a command on the marker */
+    }
+}
+/**
+ * Whether to surface the notice for the current condition. Returns false (stay
+ * quiet) when the exact same signature was already surfaced, or when there's
+ * nothing to say. On true it records the signature so the next shell with the same
+ * state is suppressed. An empty signature clears the marker.
+ */
+export function shouldSurfaceShimNotice(signature) {
+    if (!signature) {
+        try {
+            fs.rmSync(noticeStatePath(), { force: true });
+        }
+        catch { /* best-effort */ }
+        return false;
+    }
+    if (readLastNoticeSignature() === signature)
+        return false;
+    writeLastNoticeSignature(signature);
+    return true;
+}

package/dist/lib/shims.d.ts

@@ -278,6 +278,12 @@ export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
  */
 export declare function onDiskShimFile(cliCommand: string, platform: NodeJS.Platform): string;
 export declare function shimExists(agent: AgentId): boolean;
+/**
+ * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
+ * False means either the shim is missing, is pre-v2 (no marker), or is an
+ * older version that needs regeneration.
+ */
+export declare function isShimCurrent(agent: AgentId): boolean;
 /**
  * Regenerate the shim if it's missing or outdated. Returns a status describing
  * what happened — callers can surface a one-line notice to the user ("Updated

package/dist/lib/shims.js

@@ -1606,7 +1606,7 @@ function readShimSchemaVersion(agent) {
  * False means either the shim is missing, is pre-v2 (no marker), or is an
  * older version that needs regeneration.
  */
-function isShimCurrent(agent) {
+export function isShimCurrent(agent) {
     const version = readShimSchemaVersion(agent);
     return version === SHIM_SCHEMA_VERSION;
 }