@phnx-labs/agents-cli 1.20.44 → 1.20.46

package/dist/lib/self-heal/checks/shadowing.js

@@ -0,0 +1,48 @@
+// shadowing check — when a harness's own launcher shadows our shim on PATH, adopt
+// it (symlink-only, reversible) so version management wins regardless of PATH order.
+// A REAL native binary is never moved — it's surfaced as needsAttention so the
+// interactive layer can inform the user once. POSIX-only (the launcher convention
+// and PATH-order problem are POSIX; Windows resolves via the registry PATH).
+import { resultOf } from '../types.js';
+import { AGENTS } from '../../agents.js';
+import { getPathShadowingExecutable, adoptShadowingLauncher, listAgentsWithInstalledVersions, } from '../../shims.js';
+import { getGlobalDefault } from '../../versions.js';
+export const shadowingCheck = {
+    id: 'shadowing',
+    title: 'Launcher shadowing the version-managed shim',
+    platforms: ['darwin', 'linux'],
+    cadence: 'frequent',
+    async run(ctx) {
+        const fixed = [];
+        const needsAttention = [];
+        for (const agent of listAgentsWithInstalledVersions()) {
+            if (!getGlobalDefault(agent))
+                continue; // only default agents, like the interactive flow
+            const cmd = AGENTS[agent].cliCommand;
+            const shadowedBy = getPathShadowingExecutable(agent);
+            if (!shadowedBy)
+                continue;
+            if (ctx.dryRun) {
+                // Classify without mutating: adoption only ever touches a symlink.
+                let isSymlink = false;
+                try {
+                    const fs = await import('node:fs');
+                    isSymlink = fs.lstatSync(shadowedBy).isSymbolicLink();
+                }
+                catch { /* treat as real binary */ }
+                if (isSymlink)
+                    fixed.push(`${cmd} launcher (${shadowedBy})`);
+                else
+                    needsAttention.push(`${cmd}: real binary shadows the shim (${shadowedBy})`);
+                continue;
+            }
+            const res = adoptShadowingLauncher(agent);
+            if (res.adopted)
+                fixed.push(`adopted ${cmd} launcher (${res.launcher})`);
+            else if (res.reason === 'not-a-symlink') {
+                needsAttention.push(`${cmd}: real binary shadows the shim (${shadowedBy})`);
+            }
+        }
+        return resultOf(fixed, needsAttention);
+    },
+};

package/dist/lib/self-heal/checks/shims.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const shimsCheck: HealCheck;

package/dist/lib/self-heal/checks/shims.js

@@ -0,0 +1,35 @@
+// shims check — keeps the dispatch shims and versioned aliases current, and clears
+// pre-split legacy shim files. Formerly done in the interactive index.ts startup
+// (which PRINTED "Updated <cli> shim" on every run); here it runs silently in the
+// background so the shim schema settles without user-facing churn.
+import { resultOf } from '../types.js';
+import { AGENTS } from '../../agents.js';
+import { ensureShimCurrent, ensureVersionedAliasCurrent, isShimCurrent, isVersionedAliasCurrent, removeLegacyUserShim, listAgentsWithInstalledVersions, } from '../../shims.js';
+import { listInstalledVersions } from '../../versions.js';
+export const shimsCheck = {
+    id: 'shims',
+    title: 'Dispatch shims + versioned aliases',
+    cadence: 'frequent',
+    async run(ctx) {
+        const fixed = [];
+        for (const agent of listAgentsWithInstalledVersions()) {
+            const cmd = AGENTS[agent].cliCommand;
+            if (!isShimCurrent(agent)) {
+                if (!ctx.dryRun)
+                    ensureShimCurrent(agent);
+                fixed.push(`${cmd} shim`);
+            }
+            for (const version of listInstalledVersions(agent)) {
+                if (!isVersionedAliasCurrent(agent, version)) {
+                    if (!ctx.dryRun)
+                        ensureVersionedAliasCurrent(agent, version);
+                    fixed.push(`${cmd}@${version} alias`);
+                }
+            }
+            // Pre-split ~/.agents/shims/<cli> files cause false-positive shadow hits.
+            if (!ctx.dryRun && removeLegacyUserShim(agent))
+                fixed.push(`removed legacy ${cmd} shim`);
+        }
+        return resultOf(fixed, []);
+    },
+};

package/dist/lib/self-heal/registry.d.ts

@@ -0,0 +1,22 @@
+import type { HealCheck, HealCheckId, HealCadence, SelfHealReport } from './types.js';
+export declare const HEAL_CHECKS: HealCheck[];
+export interface SelfHealOptions {
+    /** Restrict to these check ids; omit to run every registered check. */
+    checks?: HealCheckId[];
+    /** Only run checks whose cadence is in this set (daemon scheduling). */
+    cadences?: HealCadence[];
+    /** 'safe' (daemon default) or 'full' (doctor --fix). Default 'safe'. */
+    mode?: 'safe' | 'full';
+    /** Detect only — never write. Default false. */
+    dryRun?: boolean;
+    /** Override the platform gate (tests). Default process.platform. */
+    platform?: NodeJS.Platform;
+}
+/** Run the selected checks, isolating per-check failures. */
+export declare function runSelfHeal(opts?: SelfHealOptions): Promise<SelfHealReport>;
+/** True if any check repaired something (for daemon logging / notification). */
+export declare function selfHealChangedAnything(report: SelfHealReport): boolean;
+/** True if any check surfaced something a human should look at. */
+export declare function selfHealNeedsAttention(report: SelfHealReport): boolean;
+/** One-line human summary, e.g. "shims: 2 fixed; path: 1 fixed". */
+export declare function summarizeSelfHeal(report: SelfHealReport): string;

package/dist/lib/self-heal/registry.js

@@ -0,0 +1,66 @@
+// The self-heal registry + runner.
+//
+// One ordered list of HealChecks; one runner that executes the requested subset,
+// isolating failures (one check throwing never aborts the rest) and aggregating a
+// SelfHealReport. Both front doors — the daemon (by cadence) and `agents doctor`
+// (all, or by id) — call runSelfHeal.
+import { resourcesCheck } from './checks/resources.js';
+import { shimsCheck } from './checks/shims.js';
+import { shadowingCheck } from './checks/shadowing.js';
+import { pathCheck } from './checks/path.js';
+// Order matters: cheap structural fixes (shims, shadow adoption, PATH) before the
+// heavier resource reconciliation, so a freshly-repaired shim is in place first.
+export const HEAL_CHECKS = [
+    shimsCheck,
+    shadowingCheck,
+    pathCheck,
+    resourcesCheck,
+];
+/** Run the selected checks, isolating per-check failures. */
+export async function runSelfHeal(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const ctx = { mode: opts.mode ?? 'safe', dryRun: opts.dryRun ?? false };
+    const selected = HEAL_CHECKS.filter((c) => {
+        if (opts.checks && !opts.checks.includes(c.id))
+            return false;
+        if (opts.cadences && !opts.cadences.includes(c.cadence))
+            return false;
+        if (c.platforms && !c.platforms.includes(platform))
+            return false;
+        return true;
+    });
+    const reports = [];
+    for (const check of selected) {
+        try {
+            const result = await check.run(ctx);
+            reports.push({ id: check.id, title: check.title, result });
+        }
+        catch (err) {
+            reports.push({ id: check.id, title: check.title, result: null, error: err.message });
+        }
+    }
+    return { checks: reports };
+}
+/** True if any check repaired something (for daemon logging / notification). */
+export function selfHealChangedAnything(report) {
+    return report.checks.some((c) => (c.result?.fixed.length ?? 0) > 0);
+}
+/** True if any check surfaced something a human should look at. */
+export function selfHealNeedsAttention(report) {
+    return report.checks.some((c) => (c.result?.needsAttention.length ?? 0) > 0 || Boolean(c.error));
+}
+/** One-line human summary, e.g. "shims: 2 fixed; path: 1 fixed". */
+export function summarizeSelfHeal(report) {
+    const parts = [];
+    for (const c of report.checks) {
+        if (c.error) {
+            parts.push(`${c.id}: error (${c.error})`);
+            continue;
+        }
+        const n = c.result?.fixed.length ?? 0;
+        const a = c.result?.needsAttention.length ?? 0;
+        if (n > 0 || a > 0)
+            parts.push(`${c.id}: ${n} fixed${a > 0 ? `, ${a} to review` : ''}`);
+    }
+    return parts.join('; ') || 'nothing to heal';
+}

package/dist/lib/self-heal/types.d.ts

@@ -0,0 +1,41 @@
+export type HealCheckId = 'resources' | 'shims' | 'shadowing' | 'path';
+/** When the daemon schedules a check. */
+export type HealCadence = 'startup' | 'frequent' | 'periodic';
+export interface HealCtx {
+    /** 'safe' = daemon (low-risk only); 'full' = doctor --fix (everything). */
+    mode: 'safe' | 'full';
+    /** Detect only — never write. Powers `agents doctor` (read-only) and previews. */
+    dryRun: boolean;
+}
+/** Outcome of one check. `ok` means nothing was wrong. */
+export interface CheckResult {
+    /** Things repaired (or, under dryRun, that WOULD be repaired). Human-readable. */
+    fixed: string[];
+    /** Detected but not auto-fixed: unfixable, or risky-in-safe-mode. Human-readable. */
+    needsAttention: string[];
+    /** True iff detect found nothing wrong (fixed and needsAttention both empty). */
+    ok: boolean;
+}
+export interface HealCheck {
+    id: HealCheckId;
+    title: string;
+    /** Restrict to these platforms; omit to run on all. */
+    platforms?: NodeJS.Platform[];
+    cadence: HealCadence;
+    /** Detect + (repair unless dryRun). Must be headless (no TTY/prompt) and idempotent. */
+    run(ctx: HealCtx): Promise<CheckResult>;
+}
+export interface CheckReport {
+    id: HealCheckId;
+    title: string;
+    result: CheckResult | null;
+    /** Set when the check itself threw (isolated — one check failing never aborts the run). */
+    error?: string;
+}
+export interface SelfHealReport {
+    checks: CheckReport[];
+}
+/** Convenience: an all-clear result. */
+export declare function okResult(): CheckResult;
+/** Build a CheckResult from collected fixes/attention items (ok iff both empty). */
+export declare function resultOf(fixed: string[], needsAttention: string[]): CheckResult;

package/dist/lib/self-heal/types.js

@@ -0,0 +1,21 @@
+// Unified self-heal subsystem — shared shapes.
+//
+// agents-cli had ~37 separate repair routines scattered across the daemon, every
+// CLI startup, and a handful of commands, each hand-rolling detect+fix on its own
+// trigger. This subsystem gives every repairable class of problem ONE shape — a
+// HealCheck — driven by ONE runner, hosted behind TWO front doors (the daemon,
+// on tiered schedules, and `agents doctor`, on demand).
+//
+// A check's `run()` both detects and repairs in a single pass (repair is skipped
+// when `ctx.dryRun`), mirroring the existing resource heal (heal.ts) which computes
+// and applies together. `mode` gates how aggressive a repair may be: 'safe' (the
+// daemon default) fixes only low-risk drift and merely reports risky conditions;
+// 'full' (`agents doctor --fix`) applies everything.
+/** Convenience: an all-clear result. */
+export function okResult() {
+    return { fixed: [], needsAttention: [], ok: true };
+}
+/** Build a CheckResult from collected fixes/attention items (ok iff both empty). */
+export function resultOf(fixed, needsAttention) {
+    return { fixed, needsAttention, ok: fixed.length === 0 && needsAttention.length === 0 };
+}

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

@@ -36,6 +36,10 @@ export interface ActiveSession {
     worktree?: DetectedWorktree;
     /** Tracker ticket the session is tied to. */
     ticket?: DetectedTicket;
+    /** Tracker refs the session CREATED (Linear create_issue / gh issue create). */
+    createdTickets?: string[];
+    /** Team name the session SPAWNED via `agents teams create/add`. */
+    spawnedTeam?: string;
     sessionFile?: string;
     startedAtMs?: number;
     status: ActiveStatus;

package/dist/lib/session/active.js

@@ -241,6 +241,8 @@ function applyState(base, state, fallbackFile) {
         pr: state.pr,
         worktree: state.worktree,
         ticket: state.ticket,
+        createdTickets: state.createdTickets,
+        spawnedTeam: state.spawnedTeam,
     };
 }
 /**

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

@@ -22,7 +22,6 @@ export interface SessionRow {
     git_branch: string | null;
     topic: string | null;
     label: string | null;
-    name: string | null;
     message_count: number | null;
     token_count: number | null;
     cost_usd: number | null;
@@ -130,15 +129,23 @@ export declare function upsertSessionsBatch(entries: Array<{
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
 /**
- * Sync `agents run --name` handles for a set of sessions, keyed by session id.
- * The name's source of truth lives outside the transcript (host task sidecars,
- * run-name sidecars written at launch), so — like {@link syncLabels} — it is
- * re-applied by id every scan rather than parsed per-file. Updates only
- * `sessions.name` (names resolve via a direct column tier in ftsSearch, not
- * FTS, so there's no session_text column to touch). Only writes when the value
- * differs; cheap to call every run. Returns the number of rows updated.
+ * Seed session labels from `agents run --name` handles, keyed by session id.
+ *
+ * `--name` is the universal launch-time way to set a session's label — the same
+ * field an agent later refines with a generated title (`syncLabels`) or the user
+ * with `/rename`. The seed's source of truth lives outside the transcript (host
+ * task sidecars, run-name sidecars written at launch), so it is re-applied by id
+ * every scan rather than parsed per-file. It only fills a label that is still
+ * EMPTY — an agent-generated title always wins over the seed, so a Claude run's
+ * `--name` shows until Claude titles it, and a non-Claude run keeps its `--name`
+ * as the label. Writes both `sessions.label` and the FTS5 label column so a
+ * seeded name is fuzzy-searchable. Cheap to call every run; returns rows updated.
+ *
+ * Ordering matters: this runs AFTER the per-agent scans (which apply
+ * agent-generated titles via {@link syncLabels}), so it never overwrites a real
+ * title — it only backfills the gap the seed was meant to cover.
  */
-export declare function syncNames(nameMap: Map<string, string | null>): number;
+export declare function seedLabelsFromNames(nameMap: Map<string, string | null>): number;
 /**
  * Sync topics (session titles) for a set of sessions, keyed by id. For agents
  * whose human-readable title lives in a side index that updates independently

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 9;
+const SCHEMA_VERSION = 10;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -52,7 +52,6 @@ CREATE TABLE IF NOT EXISTS sessions (
   git_branch TEXT,
   topic TEXT,
   label TEXT,
-  name TEXT,
   message_count INTEGER,
   token_count INTEGER,
   cost_usd REAL,
@@ -198,6 +197,22 @@ function migrateSchema(db, fromVersion) {
         if (!cols.some(c => c.name === 'name'))
             db.exec(`ALTER TABLE sessions ADD COLUMN name TEXT`);
     }
+    if (fromVersion < 10) {
+        // v9 → v10: `name` and `label` unify into a single `label`. `--name` now
+        // SEEDS the label at launch (refined later by an agent-generated title)
+        // instead of living in a separate immutable `name` column. Fold any existing
+        // name into label where the label is empty, mirror it into the FTS row, then
+        // drop the redundant column. Seeds re-apply from the run-name sidecars every
+        // scan (seedLabelsFromNames), so no rescan is required.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (cols.some(c => c.name === 'name')) {
+            db.exec(`UPDATE sessions SET label = name
+               WHERE (label IS NULL OR label = '') AND name IS NOT NULL AND name != ''`);
+            db.exec(`UPDATE session_text SET label = COALESCE(
+                 (SELECT label FROM sessions WHERE sessions.id = session_text.session_id), '')`);
+            db.exec(`ALTER TABLE sessions DROP COLUMN name`);
+        }
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -411,13 +426,13 @@ export function recordScans(entries) {
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, version, account, timestamp, last_activity,
-    project, cwd, git_branch, topic, label, name, message_count, token_count,
+    project, cwd, git_branch, topic, label, message_count, token_count,
     cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
     pr_url, pr_number, worktree_slug, ticket_id
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp, @last_activity,
-    @project, @cwd, @git_branch, @topic, @label, @name, @message_count, @token_count,
+    @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
     @pr_url, @pr_number, @worktree_slug, @ticket_id
@@ -481,7 +496,6 @@ export function upsertSession(meta, content, scan) {
         git_branch: meta.gitBranch ?? null,
         topic: meta.topic ?? null,
         label: meta.label ?? null,
-        name: meta.name ?? null,
         message_count: meta.messageCount ?? null,
         token_count: meta.tokenCount ?? null,
         cost_usd: meta.costUsd ?? null,
@@ -570,7 +584,6 @@ export function upsertSessionsBatch(entries) {
                     git_branch: meta.gitBranch ?? null,
                     topic: meta.topic ?? null,
                     label: meta.label ?? null,
-                    name: meta.name ?? null,
                     message_count: meta.messageCount ?? null,
                     token_count: meta.tokenCount ?? null,
                     cost_usd: meta.costUsd ?? null,
@@ -639,15 +652,23 @@ export function syncLabels(labelMap) {
     return updates.length;
 }
 /**
- * Sync `agents run --name` handles for a set of sessions, keyed by session id.
- * The name's source of truth lives outside the transcript (host task sidecars,
- * run-name sidecars written at launch), so — like {@link syncLabels} — it is
- * re-applied by id every scan rather than parsed per-file. Updates only
- * `sessions.name` (names resolve via a direct column tier in ftsSearch, not
- * FTS, so there's no session_text column to touch). Only writes when the value
- * differs; cheap to call every run. Returns the number of rows updated.
+ * Seed session labels from `agents run --name` handles, keyed by session id.
+ *
+ * `--name` is the universal launch-time way to set a session's label — the same
+ * field an agent later refines with a generated title (`syncLabels`) or the user
+ * with `/rename`. The seed's source of truth lives outside the transcript (host
+ * task sidecars, run-name sidecars written at launch), so it is re-applied by id
+ * every scan rather than parsed per-file. It only fills a label that is still
+ * EMPTY — an agent-generated title always wins over the seed, so a Claude run's
+ * `--name` shows until Claude titles it, and a non-Claude run keeps its `--name`
+ * as the label. Writes both `sessions.label` and the FTS5 label column so a
+ * seeded name is fuzzy-searchable. Cheap to call every run; returns rows updated.
+ *
+ * Ordering matters: this runs AFTER the per-agent scans (which apply
+ * agent-generated titles via {@link syncLabels}), so it never overwrites a real
+ * title — it only backfills the gap the seed was meant to cover.
  */
-export function syncNames(nameMap) {
+export function seedLabelsFromNames(nameMap) {
     if (nameMap.size === 0)
         return 0;
     const db = getDB();
@@ -658,21 +679,25 @@ export function syncNames(nameMap) {
         const chunk = ids.slice(i, i + CHUNK);
         const placeholders = chunk.map(() => '?').join(',');
         const rows = db
-            .prepare(`SELECT id, name FROM sessions WHERE id IN (${placeholders})`)
+            .prepare(`SELECT id, label FROM sessions WHERE id IN (${placeholders})`)
             .all(...chunk);
         for (const row of rows) {
-            const live = nameMap.get(row.id) ?? null;
-            if ((live ?? '') !== (row.name ?? '')) {
-                updates.push({ id: row.id, name: live });
+            const seed = nameMap.get(row.id);
+            // Only fill an empty label; a real agent title (non-empty) always wins.
+            if (seed && !(row.label ?? '').trim()) {
+                updates.push({ id: row.id, label: seed });
             }
         }
     }
     if (updates.length === 0)
         return 0;
-    const upd = db.prepare(`UPDATE sessions SET name = ? WHERE id = ?`);
+    const updSessions = db.prepare(`UPDATE sessions SET label = ? WHERE id = ?`);
+    const updFts = db.prepare(`UPDATE session_text SET label = ? WHERE session_id = ?`);
     const txn = db.transaction((items) => {
-        for (const { id, name } of items)
-            upd.run(name, id);
+        for (const { id, label } of items) {
+            updSessions.run(label, id);
+            updFts.run(label, id);
+        }
     });
     txn(updates);
     return updates.length;
@@ -739,7 +764,6 @@ function rowToMeta(row) {
         account: row.account ?? undefined,
         topic: row.topic ?? undefined,
         label: row.label ?? undefined,
-        name: row.name ?? undefined,
         isTeamOrigin: row.is_team_origin === 1,
         prUrl: row.pr_url ?? undefined,
         prNumber: row.pr_number ?? undefined,
@@ -1009,33 +1033,31 @@ export function ftsSearch(input, limit = 200) {
     const seen = new Set();
     const hits = [];
     // Tier 1-3: handle-based matches, ordered by exactness. A session's handle is
-    // its /rename `label` OR its `agents run --name` handle — both are user-chosen
-    // aliases and rank identically, so typing either the renamed title or the run
-    // name resolves the session ahead of any FTS content hit.
+    // its `label` — set by an agent title / `/rename`, or seeded at launch from
+    // `agents run --name`. Typing it resolves the session ahead of any FTS content
+    // hit.
     const labelRows = db.prepare(`
-    SELECT id, label, name FROM sessions
-    WHERE (label IS NOT NULL AND LOWER(label) LIKE ?)
-       OR (name  IS NOT NULL AND LOWER(name)  LIKE ?)
-  `).all(`%${lower}%`, `%${lower}%`);
+    SELECT id, label FROM sessions
+    WHERE label IS NOT NULL AND LOWER(label) LIKE ?
+  `).all(`%${lower}%`);
     let hasExactLabelMatch = false;
     for (const row of labelRows) {
-        // Score against whichever handle matches best (exact > prefix > contains).
+        // Score the label by match quality (exact > prefix > contains).
         let score = 0;
-        for (const handle of [row.label, row.name]) {
-            if (!handle)
-                continue;
+        const handle = row.label;
+        if (handle) {
             const h = handle.toLowerCase();
-            if (!h.includes(lower))
-                continue;
-            if (h === lower) {
-                score = Math.max(score, 1_000_000);
-                hasExactLabelMatch = true;
-            }
-            else if (h.startsWith(lower)) {
-                score = Math.max(score, 900_000);
-            }
-            else {
-                score = Math.max(score, 800_000);
+            if (h.includes(lower)) {
+                if (h === lower) {
+                    score = 1_000_000;
+                    hasExactLabelMatch = true;
+                }
+                else if (h.startsWith(lower)) {
+                    score = 900_000;
+                }
+                else {
+                    score = 800_000;
+                }
             }
         }
         if (score === 0)

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

@@ -64,6 +64,10 @@ interface ClaudeSessionScan {
     prNumber?: number;
     worktreeSlug?: string;
     ticketId?: string;
+    /** Tracker refs the session CREATED (Linear create_issue / gh issue create). */
+    createdTickets?: string[];
+    /** Team name this session SPAWNED via `agents teams create/add` (not team-of-origin). */
+    spawnedTeam?: string;
 }
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since