@phnx-labs/agents-cli 1.22.51 → 1.22.52

package/dist/lib/session/local-tmux-attach.js

@@ -0,0 +1,164 @@
+/**
+ * Attach a LIVE tmux pane on THIS box, with zero SSH — the local half of the
+ * PHNX-3292 product rule: "first unique match wins, local before fleet."
+ *
+ * `agents tmux ls` prints `ag-<agent>-<8hex>` names. A selector that already
+ * names one of those panes (the full alias, or its bare 8-hex suffix when it
+ * is unique among LIVE local panes) is attached directly — no session index
+ * lookup, no fleet SSH fan-out. `sessions resume`, the deprecated `sessions
+ * attach`, and `sessions focus` all take this gate before anything else.
+ *
+ * Lives outside `commands/` (not in focus.ts) so `sessions-resume.ts` and
+ * `attach.ts` can both import it without a focus.ts <-> sessions-resume.ts
+ * import cycle (focus.ts already imports from sessions-resume.ts).
+ */
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { attachTmux, ensureSessionHookRepaired, getDefaultSocketPath, hasSession, listSessions, runTmux, teardownIfAgentExited } from '../tmux/index.js';
+import { isAgentTmuxAlias } from './types.js';
+/** Width of `SessionMeta.shortId` / the hex an `ag-<agent>-<8hex>` alias embeds. */
+const SHORT_SESSION_ID_RE = /^[0-9a-f]{8}$/i;
+/** Shape of the tmux alias the CLI mints for an agent session: `ag-<agent>-<shortid>`.
+ * Delegates to the one canonical matcher beside the name parsers in active.ts. */
+export function looksLikeTmuxAlias(selector) {
+    return isAgentTmuxAlias(selector);
+}
+/**
+ * Classify a selector against the live tmux server. Split from the attach so the
+ * decision is testable against a real tmux server without replacing the caller's
+ * shell (attaching is not something a test can undo).
+ */
+export async function resolveTmuxAliasState(selector, socket) {
+    if (!looksLikeTmuxAlias(selector))
+        return 'not-an-alias';
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return 'no-server';
+    if (!(await hasSession(selector, sock).catch(() => false)))
+        return 'absent';
+    const panes = await runTmux({
+        socket: sock,
+        args: ['list-panes', '-t', `=${selector}`, '-F', '#{pane_dead}'],
+    }).catch(() => undefined);
+    const states = (panes?.stdout ?? '').split('\n').map(s => s.trim()).filter(Boolean);
+    return states.some(d => d === '0') ? 'live' : 'dead';
+}
+/**
+ * A local `ag-<agent>-<8hex>` alias names a pane on THIS box. Attach it
+ * without any fleet SSH. `--device` keeps the sweep: the caller scoped
+ * identity to another machine.
+ */
+export function shouldAttachLocalTmuxAliasBeforeFleet(selector, hosts) {
+    return !!selector && hosts.length === 0 && isAgentTmuxAlias(selector);
+}
+/**
+ * Attach a live tmux session named exactly as the selector, without needing the
+ * session index to know anything about it.
+ *
+ * SES-41 requires a `ag-<agent>-<8hex>` tmux alias to resolve, but the alias's
+ * hex is the LAUNCH id, not the harness session id, and for a harness that
+ * writes no `state/sessions/<pid>.json` record there is no mapping back to a
+ * SessionMeta at all. The pane is the thing the user asked for, and its NAME is
+ * sufficient to attach it — so an unattributable session is still reachable
+ * instead of being a dead end that forces raw `tmux -S … attach`.
+ *
+ * Returns false when this is not an alias, the server/session is absent, or
+ * every pane is dead — the caller then continues to normal id resolution.
+ * SES-39's "re-read `pane_dead` immediately before attach" is honoured here:
+ * liveness is queried at attach time, not read from a roster.
+ */
+export async function attachLiveTmuxAlias(selector) {
+    const socket = getDefaultSocketPath();
+    if (await resolveTmuxAliasState(selector, socket) !== 'live')
+        return false;
+    if (!process.stdout.isTTY) {
+        console.error(chalk.red(`"${selector}" is a live tmux session, but attaching needs a TTY.`));
+        console.error(chalk.gray(`  Run it from a terminal, or: agents tmux attach ${selector}`));
+        process.exitCode = 1;
+        return true;
+    }
+    // Already inside a tmux client on this socket — which is the normal state for
+    // an interactive agent session here — MOVE that client instead of nesting a
+    // second one. jumpTo (go.ts) does the same; attaching from inside tmux
+    // otherwise stacks clients rather than taking you to the session.
+    if (process.env.TMUX) {
+        await runTmux({ socket, args: ['switch-client', '-t', `=${selector}`], throwOnError: false }).catch(() => { });
+        console.log(chalk.gray(`Switched this tmux client to ${selector}.`));
+        return true;
+    }
+    console.log(chalk.gray(`Attaching ${selector} — Ctrl-b d to detach.`));
+    // Repair a legacy/stale pane-died hook before handing the session to an
+    // attach client — the 5-min daemon reconcile that used to cover this was
+    // deleted; attach-time repair is what closes the gap now (RUSH-2435).
+    await ensureSessionHookRepaired(selector, socket);
+    const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${selector}`] });
+    await teardownIfAgentExited(selector, socket);
+    process.exitCode = code;
+    return true;
+}
+/**
+ * Resolve a bare 8-hex selector (`agents tmux ls`'s hex column, typed without
+ * the `ag-<agent>-` prefix) against LIVE local panes only. Dead panes matching
+ * the suffix are excluded before the uniqueness check — a retained, exited pane
+ * must never compete with (or block) a live one for the same short id.
+ *
+ * Exported for direct testing: `attachLocalLiveSelector` composes this with a
+ * real `attachTmux()` call, which a unit test cannot safely invoke (it takes
+ * over the terminal).
+ */
+export async function resolveUniqueLocalLiveAliasBySuffix(shortId, socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return { kind: 'none' };
+    let sessions;
+    try {
+        sessions = await listSessions({ socket: sock });
+    }
+    catch {
+        return { kind: 'none' };
+    }
+    const named = sessions
+        .map((session) => session.name)
+        .filter((name) => isAgentTmuxAlias(name) && name.toLowerCase().endsWith(shortId.toLowerCase()));
+    if (named.length === 0)
+        return { kind: 'none' };
+    const states = await Promise.all(named.map(async (name) => ({ name, state: await resolveTmuxAliasState(name, sock) })));
+    const live = states.filter((entry) => entry.state === 'live').map((entry) => entry.name);
+    if (live.length === 0)
+        return { kind: 'none' };
+    if (live.length > 1)
+        return { kind: 'collision', aliases: live };
+    return { kind: 'alias', alias: live[0] };
+}
+/**
+ * The full local gate (PHNX-3292 rule 1): a selector that is either a live
+ * local tmux alias, or a bare 8-hex short id that names exactly one live local
+ * pane, attaches immediately — zero SSH. `--device`/`hosts` scopes identity to
+ * another machine and disables this gate entirely (rule 4).
+ *
+ * Two LIVE local panes matching the same 8-hex suffix fail closed (rule 5): a
+ * collision is reported with both names rather than guessing, and the caller
+ * must not fall through to fleet resolution for a selector that is genuinely
+ * ambiguous ON THIS BOX.
+ *
+ * Returns `false` (never attached, never reported) when the selector does not
+ * name a live local pane at all, so the caller can continue to session-id
+ * resolution / the fleet race.
+ */
+export async function attachLocalLiveSelector(selector, hosts) {
+    if (shouldAttachLocalTmuxAliasBeforeFleet(selector, hosts)) {
+        return attachLiveTmuxAlias(selector);
+    }
+    if (!selector || hosts.length > 0 || !SHORT_SESSION_ID_RE.test(selector))
+        return false;
+    const found = await resolveUniqueLocalLiveAliasBySuffix(selector);
+    if (found.kind === 'none')
+        return false;
+    if (found.kind === 'collision') {
+        console.error(chalk.red(`"${selector}" matches ${found.aliases.length} live local panes: ${found.aliases.join(', ')}`));
+        console.error(chalk.gray('  Pass the full alias to disambiguate — see: agents tmux ls'));
+        process.exitCode = 1;
+        return true;
+    }
+    return attachLiveTmuxAlias(found.alias);
+}

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

@@ -39,4 +39,12 @@ export interface RemoteActiveResult {
  */
 export declare function gatherRemoteActive(hosts?: string[], opts?: {
     quiet?: boolean;
+    /**
+     * Opt-in first-hit abort. Omitted by default so `--active`, projects, and
+     * `focus` with no id keep all-settle. Detach/stop pass this for a unique
+     * live id so a reachable hit does not wait out sleeping peers.
+     */
+    earlyExit?: {
+        isDefinitive: (item: ActiveSession, machine: string) => boolean;
+    };
 }): Promise<RemoteActiveResult>;

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

@@ -80,6 +80,7 @@ export async function gatherRemoteActive(hosts, opts) {
         hosts,
         parse: parseRemoteActive,
         quiet: opts?.quiet,
+        earlyExit: opts?.earlyExit,
     });
     return {
         sessions: result.items,

package/dist/lib/share/publish.d.ts

@@ -85,6 +85,8 @@ export interface PublishOptions {
 export type ShareVisibility = 'public' | 'unlisted' | 'me' | 'org';
 export interface PublishResult {
     url: string;
+    /** URL-safe object name, explicit (`--slug`) or deterministically derived. */
+    slug?: string;
     expiresAt?: string;
     coverUrl?: string;
     /** Server-enforced visibility stamped on the object. */
@@ -224,22 +226,17 @@ export declare function redactEmails(text: string): string;
 export declare function scanShareContent(body: string | Buffer): SensitiveHit[];
 /** Build the refuse message when the pre-publish scan finds sensitive content. */
 export declare function formatSensitiveContentError(hits: SensitiveHit[]): string;
-/** Derive a URL-safe slug from a filename (or pass one through). */
+/** Derive a URL-safe slug from a filename, stripping its path and extension. */
 export declare function slugify(name: string): string;
 /** The project the file belongs to — git repo name, else the cwd's basename. */
 export declare function detectProject(dir?: string): string;
 /**
- * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
- * filename is dropped. The project no longer prefixes the slug — the URL
- * namespace is already the publisher's handle (`/<you>/<slug>`).
- *
- * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
- * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
- * §Security for the threat model and `--expire` for sensitive content.)
- * `--slug` still publishes that exact slug, no view-id appended.
+ * Stable default slug for an artifact: prefer its HTML `<title>` or Markdown
+ * frontmatter `title:`, then fall back to its filename. The same artifact title
+ * always yields the same slug, so republishing without `--slug` updates the same
+ * URL. `--slug` remains an exact override.
  */
-export declare function defaultSlug(filePath: string, _dir?: string): string;
+export declare function defaultSlug(filePath: string, body?: Buffer): string;
 /**
  * Best-effort OG cover: capture a screenshot, upload it as `<slug>.png`, and return
  * the page body with og:image meta injected (+ the cover URL). All IO is injected

package/dist/lib/share/publish.js

@@ -8,7 +8,6 @@
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
 import { hostname as osHostname } from 'node:os';
 import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
@@ -309,15 +308,17 @@ export function formatSensitiveContentError(hits) {
         `Shares are world-readable by URL — pass --force to publish anyway, ` +
         `or --unlisted --expire 12h to bound the blast radius.`);
 }
-/** Derive a URL-safe slug from a filename (or pass one through). */
-export function slugify(name) {
-    return (basename(name)
-        .replace(/\.[^.]+$/, '')
-        .toLowerCase()
+/** Normalize artifact title text into a URL-safe slug. */
+function normalizeSlug(name) {
+    return (name.toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '')
         .slice(0, 60) || 'page');
 }
+/** Derive a URL-safe slug from a filename, stripping its path and extension. */
+export function slugify(name) {
+    return normalizeSlug(basename(name).replace(/\.[^.]+$/, ''));
+}
 function sanitizeSlugPart(s) {
     return sanitizeShareNamespace(s);
 }
@@ -343,19 +344,13 @@ export function detectProject(dir = process.cwd()) {
     return gitRepoName(dir) ?? (sanitizeSlugPart(basename(dir)) || 'share');
 }
 /**
- * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
- * filename is dropped. The project no longer prefixes the slug — the URL
- * namespace is already the publisher's handle (`/<you>/<slug>`).
- *
- * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
- * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
- * §Security for the threat model and `--expire` for sensitive content.)
- * `--slug` still publishes that exact slug, no view-id appended.
+ * Stable default slug for an artifact: prefer its HTML `<title>` or Markdown
+ * frontmatter `title:`, then fall back to its filename. The same artifact title
+ * always yields the same slug, so republishing without `--slug` updates the same
+ * URL. `--slug` remains an exact override.
  */
-export function defaultSlug(filePath, _dir) {
-    const feature = slugify(filePath).replace(/^plan-/, '') || 'page';
-    return `${feature}-${randomBytes(8).toString('hex')}`;
+export function defaultSlug(filePath, body) {
+    return body ? normalizeSlug(deriveLabel(filePath, body)) : slugify(filePath);
 }
 function guessContentType(filePath) {
     if (/\.html?$/i.test(filePath))
@@ -459,7 +454,8 @@ export async function publishFile(filePath, opts = {}) {
 }
 export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const username = await resolveShareUsername(opts);
-    const slugPart = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
+    let body = readFileSync(filePath);
+    const slugPart = (opts.slug ?? defaultSlug(filePath, body)).replace(/^\/+/, '');
     const key = buildShareKey(username, slugPart);
     const expiresAt = resolveExpire(opts.expire);
     const visibility = resolveShareVisibility(opts);
@@ -472,7 +468,6 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
             const res = await fetch(u, { method: 'PUT', headers: h, body: new Uint8Array(b) });
             return { ok: res.ok, status: res.status, url: u };
         });
-    let body = readFileSync(filePath);
     let coverUrl;
     const isHtml = /\.html?$/i.test(filePath);
     if (isHtml) {
@@ -576,6 +571,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     return {
         url: r.url ?? pageUrl,
+        slug: key.slice(key.indexOf('/') + 1),
         expiresAt,
         coverUrl,
         label,

package/dist/lib/share/worker-template.js

@@ -253,7 +253,20 @@ export default {
         headers.set('cache-control', 'public, max-age=60');
         if (visibility === 'unlisted') headers.set('X-Robots-Tag', 'noindex');
       }
-      return new Response(request.method === 'HEAD' ? null : obj.body, { status: 200, headers });
+      if (request.method === 'HEAD') return new Response(null, { status: 200, headers });
+      // HTML pages get an attribution bar injected at serve time (who shared it,
+      // what made it, when, and — the point — a visual VISIBILITY cue). All read
+      // from the object's stamped metadata; non-HTML assets (images, JSON, the OG
+      // cover) are served byte-for-byte. The body changes, so the R2 etag no
+      // longer matches — drop it rather than serve a lying validator.
+      const isHtmlPage = (headers.get('content-type') || '').indexOf('text/html') !== -1;
+      if (isHtmlPage) {
+        const rawHtml = await obj.text();
+        const withBar = injectAttributionBar(rawHtml, obj.customMetadata || {}, firstSeg);
+        headers.delete('etag');
+        return new Response(withBar, { status: 200, headers });
+      }
+      return new Response(obj.body, { status: 200, headers });
     }
 
     if (request.method === 'DELETE') {
@@ -473,6 +486,68 @@ function escapeHtml(s) {
     .replace(/"/g, '"');
 }
 
+// The attribution bar: a slim strip prepended to every served HTML page that
+// makes the object's stamped metadata visible — who shared it, what made it,
+// when, and (the whole point) a color-coded VISIBILITY cue Google-Drive style.
+// All values come from customMetadata; nothing new is stamped at publish time,
+// so this is a pure Worker change deployable with 'agents artifacts share update'.
+var VIS_ICON = {
+  me: '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2"><rect x="4" y="11" width="16" height="9" rx="2"/><path d="M8 11V8a4 4 0 0 1 8 0v3"/></svg>',
+  org: '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 21h18M6 21V4a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v17M14 9h4a1 1 0 0 1 1 1v11"/></svg>',
+  unlisted: '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2"><path d="M10 13a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1"/><path d="M14 11a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1"/></svg>',
+  public: '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3a15 15 0 0 1 0 18M12 3a15 15 0 0 0 0 18"/></svg>',
+};
+
+function visibilityChip(visibility, orgDomain) {
+  if (visibility === 'me') return { icon: VIS_ICON.me, label: 'Only you', color: '#f59e0b' };
+  if (visibility === 'org') return { icon: VIS_ICON.org, label: 'Anyone at ' + escapeHtml(orgDomain || 'your organization'), color: '#5b9dff' };
+  if (visibility === 'unlisted') return { icon: VIS_ICON.unlisted, label: 'Unlisted', color: '#9aa0a6' };
+  return { icon: VIS_ICON.public, label: 'Public', color: '#30a46c' };
+}
+
+function renderAttributionBar(meta, handle) {
+  var cm = meta || {};
+  var chip = visibilityChip(cm.visibility || 'public', cm.org_domain);
+  var left = '';
+  // The handle is already the public URL namespace, so surfacing it leaks nothing new.
+  if (handle) left += 'Shared by <strong>' + escapeHtml(handle) + '</strong>';
+  if (cm.agent) left += (left ? '<span class="ash-dot">·</span>' : '') + 'Made with ' + escapeHtml(cm.agent);
+  var right = '<span class="ash-chip" style="color:' + chip.color + ';border-color:' + chip.color + '66">' + chip.icon + '<span>' + chip.label + '</span></span>';
+  if (cm.date) right += '<span class="ash-date">' + escapeHtml(cm.date) + '</span>';
+  // The load-bearing background + base colour ride an INLINE style so the host
+  // page's own CSS can never wash the bar out (inline beats a page stylesheet);
+  // the rest is a namespaced style block with !important on every colour so a
+  // broad page rule (span selector to black, etc.) cannot make the text vanish.
+  return '<div class="agents-share-bar" role="contentinfo" aria-label="Sharing details" ' +
+    'style="background:#0b0b0c !important;color:#e8e8e8 !important">' +
+    '<style>' +
+    '.agents-share-bar{all:initial;position:sticky;top:0;left:0;right:0;z-index:2147483647;box-sizing:border-box;display:flex !important;align-items:center;gap:12px;flex-wrap:wrap;' +
+    'padding:8px 16px !important;background:#0b0b0c !important;color:#e8e8e8 !important;border-bottom:1px solid #24242b !important;' +
+    'font:13px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,system-ui,sans-serif !important}' +
+    '.agents-share-bar *{box-sizing:border-box;font-family:inherit}' +
+    '.agents-share-bar .ash-left{display:flex;align-items:center;gap:8px;min-width:0;color:#cfd3d9 !important}' +
+    '.agents-share-bar strong{color:#fff !important;font-weight:600}' +
+    '.agents-share-bar .ash-dot{opacity:.4;margin:0 3px}' +
+    '.agents-share-bar .ash-right{margin-left:auto;display:flex;align-items:center;gap:12px}' +
+    '.agents-share-bar .ash-date{color:#9096a0 !important}' +
+    '.agents-share-bar .ash-chip{display:inline-flex;align-items:center;gap:6px;padding:3px 10px;border-radius:999px;border:1px solid;font-weight:600;font-size:12px;white-space:nowrap}' +
+    '.agents-share-bar .ash-chip svg{flex:none}' +
+    '</style>' +
+    '<span class="ash-left">' + left + '</span>' +
+    '<span class="ash-right">' + right + '</span>' +
+    '</div>';
+}
+
+function injectAttributionBar(html, meta, handle) {
+  var bar = renderAttributionBar(meta, handle);
+  var m = /<body[^>]*>/i.exec(html);
+  if (m) {
+    var at = m.index + m[0].length;
+    return html.slice(0, at) + bar + html.slice(at);
+  }
+  return bar + html;
+}
+
 function json(body, status) {
   return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
 }
@@ -507,23 +582,35 @@ function phoenixHandle(auth) {
 // First writer of a handle owns it. Later PUTs from the same userId are fine;
 // a different userId whose email local-part collides gets 409, not a silent overwrite.
 async function assertHandleOwner(bucket, handle, userId) {
-  // Pages under the handle already stamp customMetadata.owner = userId.
-  // Treat that as the source of truth so a colliding local-part cannot
-  // PUT/DELETE another account's objects even if the claim object is missing.
+  // The __handles/<handle> claim object is the authoritative first-writer record
+  // of ownership. When it exists it decides ownership OUTRIGHT: the recorded
+  // userId may write, anyone else is refused. Consult it FIRST — a stray page
+  // under the namespace stamped with a different owner (e.g. a BYO WRITE_TOKEN
+  // publish, which stamps owner = SHARE_NAMESPACE rather than a userId, or a page
+  // published under the same human's earlier userId before a re-auth) must not
+  // lock the rightful claim holder out of their own handle (PHNX-3291).
+  const key = '__handles/' + handle;
+  const existing = await bucket.get(key);
+  if (existing) {
+    const claimed = existing.customMetadata && existing.customMetadata.userId;
+    if (claimed && claimed !== userId) {
+      return { error: json({ error: 'handle taken', handle: handle }, 409) };
+    }
+    return {};
+  }
+  // No claim object yet — fall back to the page-owner scan so a colliding email
+  // local-part cannot PUT/DELETE another account's objects in the window before
+  // the claim exists. (claimHandle writes the claim on the first Phoenix PUT.)
+  // Only a DIFFERENT Phoenix userId blocks: a BYO WRITE_TOKEN publish stamps
+  // owner = the namespace (=== handle) rather than a userId, so it is not a rival
+  // identity and must not lock the handle's first Phoenix claimant out (PHNX-3291).
   const list = await bucket.list({ prefix: handle + '/', include: ['customMetadata'] });
   for (const o of list.objects || []) {
     const owner = o.customMetadata && o.customMetadata.owner;
-    if (owner && owner !== userId) {
+    if (owner && owner !== userId && owner !== handle) {
       return { error: json({ error: 'handle taken', handle: handle }, 409) };
     }
   }
-  const key = '__handles/' + handle;
-  const existing = await bucket.get(key);
-  if (!existing) return {};
-  const claimed = existing.customMetadata && existing.customMetadata.userId;
-  if (claimed && claimed !== userId) {
-    return { error: json({ error: 'handle taken', handle: handle }, 409) };
-  }
   return {};
 }
 

package/dist/lib/sync-status.d.ts

@@ -64,8 +64,18 @@ export interface SystemRepoStatus {
     /** True when the dir isn't a git repo or has no upstream — behind is unknown. */
     unknown: boolean;
 }
+export interface UserRepoStatus {
+    dir: string;
+    /**
+     * True when `~/.agents` exists but is not a git repo (or is a repo with no
+     * `origin`) — a partial install `agents repo sync user` will adopt in place
+     * (PHNX-3301). A DISTINCT drift state, not a per-agent "N missing" count.
+     */
+    notGitRepo: boolean;
+}
 export interface UnifiedSyncStatus {
     system: SystemRepoStatus;
+    user: UserRepoStatus;
     agents: AgentVersionStatus[];
     totals: {
         drifted: number;
@@ -93,6 +103,13 @@ export interface SyncStatusOptions {
  * the menu-bar surfaces; we read it once, here, so every surface agrees.
  */
 export declare function getSystemRepoStatus(): Promise<SystemRepoStatus>;
+/**
+ * Detect whether `~/.agents` (the user config layer) is git-backed. A partial
+ * install — runtime state present but no `.git` (or no `origin`) — is a distinct
+ * drift state that `agents repo sync user` heals by adopting in place (PHNX-3301),
+ * surfaced separately from per-version resource gaps. Purely local; no network.
+ */
+export declare function getUserRepoStatus(): Promise<UserRepoStatus>;
 /**
  * Compute unified sync status across the fleet. Resolves against non-project
  * layers only (`excludeProject: true`) — the GLOBAL version home is never

package/dist/lib/sync-status.js

@@ -23,8 +23,9 @@ import { ALL_AGENT_IDS } from './agents.js';
 import { diffVersionResources, } from './doctor-diff.js';
 import { listInstalledVersions, getGlobalDefault } from './installations/versions.js';
 import { loadManifest } from './staleness/index.js';
-import { getSystemAgentsDir } from './state.js';
-import { isGitRepo } from './git.js';
+import { getSystemAgentsDir, getUserAgentsDir } from './state.js';
+import * as fs from 'fs';
+import { isGitRepo, readOriginUrl } from './git.js';
 const STATUS_MAP = {
     ok: 'synced',
     diff: 'drifted',
@@ -73,6 +74,22 @@ export async function getSystemRepoStatus() {
         return base;
     }
 }
+/**
+ * Detect whether `~/.agents` (the user config layer) is git-backed. A partial
+ * install — runtime state present but no `.git` (or no `origin`) — is a distinct
+ * drift state that `agents repo sync user` heals by adopting in place (PHNX-3301),
+ * surfaced separately from per-version resource gaps. Purely local; no network.
+ */
+export async function getUserRepoStatus() {
+    const dir = getUserAgentsDir();
+    if (!fs.existsSync(dir))
+        return { dir, notGitRepo: false };
+    if (!isGitRepo(dir))
+        return { dir, notGitRepo: true };
+    // A repo with no `origin` is just as partial for adopt's purposes — reuse the
+    // single origin-URL reader rather than a second remote check.
+    return { dir, notGitRepo: readOriginUrl(dir) === null };
+}
 /**
  * Compute unified sync status across the fleet. Resolves against non-project
  * layers only (`excludeProject: true`) — the GLOBAL version home is never
@@ -107,6 +124,7 @@ export async function computeSyncStatus(options = {}) {
         }
     }
     const system = await getSystemRepoStatus();
+    const user = await getUserRepoStatus();
     const agentsNeedingSync = new Set();
     let drifted = 0, missing = 0, orphan = 0, versionsNeedingSync = 0, versionsNeverSynced = 0;
     for (const v of agents) {
@@ -122,6 +140,7 @@ export async function computeSyncStatus(options = {}) {
     }
     return {
         system,
+        user,
         agents,
         totals: {
             drifted,

package/dist/lib/tmux/index.d.ts

@@ -5,4 +5,4 @@
  */
 export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, isTmuxVersionSupported, MIN_TMUX_VERSION, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
 export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
-export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, reconcileSessionHooks, ensureSessionHookRepaired, type SessionMeta, type CreateSessionOptions, type ListedSession, type SplitOptions, type SendOptions, type CaptureOptions, } from './session.js';
+export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, teardownIfAgentExited, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, reconcileSessionHooks, ensureSessionHookRepaired, type SessionMeta, type CreateSessionOptions, type ListedSession, type SplitOptions, type SendOptions, type CaptureOptions, } from './session.js';

package/dist/lib/tmux/index.js

@@ -5,4 +5,4 @@
  */
 export { findTmuxBinary, isTmuxInstalled, getTmuxVersion, isTmuxVersionSupported, MIN_TMUX_VERSION, assertTmuxAvailable, TmuxUnavailableError, TmuxCommandError, runTmux, attachTmux, } from './binary.js';
 export { getDefaultSocketPath, getSessionMetaPath, ensureTmuxDir, } from './paths.js';
-export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, reconcileSessionHooks, ensureSessionHookRepaired, } from './session.js';
+export { assertValidSessionName, slugifyName, hasSession, createSession, killSession, teardownIfAgentExited, killAll, listSessions, splitPane, sendKeys, capturePane, readSessionMeta, TmuxSessionError, reconcileSessionHooks, ensureSessionHookRepaired, } from './session.js';

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

@@ -109,6 +109,16 @@ export declare function createSession(opts: CreateSessionOptions): Promise<Sessi
 export declare function killSession(name: string, socket?: string, opts?: {
     reapOrphans?: boolean;
 }): Promise<boolean>;
+/**
+ * After an attach client returns: destroy the session if every pane is dead
+ * (the agent exited); leave it if any pane is still alive (Ctrl-b d).
+ *
+ * `runInTmux` already does this via `resolveAfterAttach`. The attach verbs
+ * (`agents tmux attach`, `sessions focus`/`resume --attach-only`, `jumpTo`)
+ * used to `process.exit` the tmux client status and leave a `remain-on-exit`
+ * husk — the session "came back" in `tmux ls` after the user exited the agent.
+ */
+export declare function teardownIfAgentExited(name: string, socket?: string): Promise<'killed' | 'kept' | 'absent'>;
 /**
  * Kill every session on the shared server AND the server itself, then prune
  * meta files. Wipes the socket so the next `new` starts from a clean slate.

package/dist/lib/tmux/session.js

@@ -315,6 +315,35 @@ export async function killSession(name, socket, opts = {}) {
     removeSessionMeta(name);
     return true;
 }
+/**
+ * After an attach client returns: destroy the session if every pane is dead
+ * (the agent exited); leave it if any pane is still alive (Ctrl-b d).
+ *
+ * `runInTmux` already does this via `resolveAfterAttach`. The attach verbs
+ * (`agents tmux attach`, `sessions focus`/`resume --attach-only`, `jumpTo`)
+ * used to `process.exit` the tmux client status and leave a `remain-on-exit`
+ * husk — the session "came back" in `tmux ls` after the user exited the agent.
+ */
+export async function teardownIfAgentExited(name, socket) {
+    assertValidSessionName(name);
+    const sock = socket ?? getDefaultSocketPath();
+    if (!(await hasSession(name, sock)))
+        return 'absent';
+    const res = await runTmux({
+        socket: sock,
+        args: ['list-panes', '-t', `=${name}`, '-F', '#{pane_dead}'],
+        throwOnError: false,
+    }).catch(() => null);
+    if (!res || res.code !== 0) {
+        await killSession(name, sock).catch(() => { });
+        return 'killed';
+    }
+    const flags = res.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+    if (flags.some((d) => d === '0'))
+        return 'kept';
+    await killSession(name, sock).catch(() => { });
+    return 'killed';
+}
 /**
  * Kill every session on the shared server AND the server itself, then prune
  * meta files. Wipes the socket so the next `new` starts from a clean slate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.51",
+  "version": "1.22.52",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",