@phnx-labs/agents-cli 1.22.51 → 1.22.53

package/dist/lib/session/pid-registry.d.ts

@@ -1,6 +1,13 @@
 export interface PidSessionEntry {
     pid: number;
     agent: string;
+    /**
+     * Custom harness / profile name when this pid was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
+     * CLI (`claude`) so process matching and transcript discovery keep
+     * working. `sessions --active` displays this when set (PHNX-2935).
+     */
+    harness?: string;
     /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;

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

@@ -69,5 +69,20 @@ export interface ClassifiedPrompt {
 export declare function classifyUserPrompt(raw: string | undefined, opts?: {
     hasImageAttachment?: boolean;
 }): ClassifiedPrompt;
+/**
+ * Collapse a harness-generated session title when it is injected skill
+ * scaffolding; otherwise leave the title as the harness wrote it.
+ *
+ * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
+ * first turn, so a session opened with a skill gets named after the injected
+ * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
+ * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
+ * whitespace-only input yields `undefined` so the caller falls through to the
+ * first-prompt topic.
+ *
+ * A user-authored title (Claude `/rename` / `custom-title`) is never passed
+ * here — the caller keeps it verbatim.
+ */
+export declare function cleanGeneratedSessionLabel(title: string | undefined): string | undefined;
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export declare function extractSessionTopic(raw: string): string | undefined;

package/dist/lib/session/prompt.js

@@ -201,6 +201,27 @@ export function classifyUserPrompt(raw, opts = {}) {
     const display = (cleanedFirst || firstLine).replace(IMAGE_PATH_RE, '[image]').trim();
     return { clean: display, kind: 'text' };
 }
+/**
+ * Collapse a harness-generated session title when it is injected skill
+ * scaffolding; otherwise leave the title as the harness wrote it.
+ *
+ * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
+ * first turn, so a session opened with a skill gets named after the injected
+ * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
+ * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
+ * whitespace-only input yields `undefined` so the caller falls through to the
+ * first-prompt topic.
+ *
+ * A user-authored title (Claude `/rename` / `custom-title`) is never passed
+ * here — the caller keeps it verbatim.
+ */
+export function cleanGeneratedSessionLabel(title) {
+    const trimmed = title?.trim();
+    if (!trimmed)
+        return undefined;
+    const classified = classifyUserPrompt(trimmed);
+    return classified.kind === 'skill' ? classified.clean : trimmed;
+}
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export function extractSessionTopic(raw) {
     if (!raw.trim())

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/session/types.d.ts

@@ -31,6 +31,16 @@ export declare const AG_TMUX_NAME_RE: RegExp;
 /** Whether `name` is an `ag-<agent>-<shortid>` tmux session name. */
 export declare function isAgentTmuxAlias(name: string): boolean;
 export declare function isSessionTrackedAgent(agent: string): agent is SessionAgentId;
+/**
+ * The name `agents sessions` shows for a run. A custom harness launched via a
+ * profile (`agents run deepseek`) keeps its host agent for transcript discovery
+ * and parsing (`claude`) and stamps the profile name on `harness`. Display
+ * prefers that stamp so a deepseek run is not listed as claude (PHNX-2935).
+ */
+export declare function sessionDisplayAgent(session: {
+    agent: string;
+    harness?: string | null;
+}): string;
 /** A single normalized event within a session (message, tool call, thinking, etc.). */
 export interface SessionEvent {
     type: 'message' | 'tool_use' | 'tool_result' | 'thinking' | 'error' | 'init' | 'result' | 'usage' | 'attachment' | 'hook' | 'interrupt';
@@ -154,6 +164,13 @@ export interface SessionMeta {
     id: string;
     shortId: string;
     agent: SessionAgentId;
+    /**
+     * Custom harness / profile name when this session was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
+     * harness that produced the transcript (`claude`, …) so discovery and
+     * parsing keep working. Display surfaces this when set (PHNX-2935).
+     */
+    harness?: string;
     /** Where the indexed transcript came from. Routine rows are archived from a run directory. */
     origin?: 'cli' | 'routine';
     /** Routine name for transcripts archived from ~/.agents/.history/runs/<name>/<runId>/. */

package/dist/lib/session/types.js

@@ -31,3 +31,13 @@ export function isAgentTmuxAlias(name) {
 export function isSessionTrackedAgent(agent) {
     return SESSION_AGENTS.includes(agent);
 }
+/**
+ * The name `agents sessions` shows for a run. A custom harness launched via a
+ * profile (`agents run deepseek`) keeps its host agent for transcript discovery
+ * and parsing (`claude`) and stamps the profile name on `harness`. Display
+ * prefers that stamp so a deepseek run is not listed as claude (PHNX-2935).
+ */
+export function sessionDisplayAgent(session) {
+    const harness = session.harness?.trim();
+    return harness || session.agent;
+}

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,73 @@ 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.
+  // FIXED, full-viewport-width chrome (not sticky-inside-body — that inherited the
+  // page's max-width/margins and rendered as a floating box). html padding-top
+  // pushes the whole page down by the bar's height; flex-wrap:nowrap + ellipsis on
+  // the left keeps the bar exactly one line tall so the push height stays correct.
+  return '<div class="agents-share-bar" role="contentinfo" aria-label="Sharing details" ' +
+    'style="background:#0b0b0c !important;color:#e8e8e8 !important">' +
+    '<style>' +
+    'html{padding-top:38px !important}' +
+    '.agents-share-bar{all:initial;position:fixed !important;top:0 !important;left:0 !important;right:0 !important;width:100% !important;z-index:2147483647 !important;box-sizing:border-box;display:flex !important;align-items:center;gap:12px;flex-wrap:nowrap;' +
+    'padding:8px 16px !important;background:#0b0b0c !important;color:#e8e8e8 !important;border-bottom:1px solid #23232a !important;box-shadow:0 1px 3px rgba(0,0,0,.35) !important;' +
+    'font:13px/1.4 -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{flex:1 1 auto;min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;color:#cfd3d9 !important}' +
+    '.agents-share-bar strong{color:#fff !important;font-weight:600}' +
+    '.agents-share-bar .ash-dot{opacity:.4;margin:0 4px}' +
+    '.agents-share-bar .ash-right{flex:none;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;vertical-align:middle}' +
+    '</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 +587,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/state.d.ts

@@ -391,6 +391,14 @@ export declare function getDeviceMetaPath(): string;
  */
 export declare function getVersionResourcesPath(): string;
 export declare function withMetaLock<T>(fn: () => T): T;
+/**
+ * Write `meta` to disk (central + device docs + pins) WITHOUT taking the meta
+ * lock — the caller must already hold it via {@link withMetaLock}. Exported so a
+ * writer that needs to read fresh state, decide, and commit within a SINGLE lock
+ * acquisition (e.g. browser tombstone eviction) can do so without the
+ * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ */
+export declare function writeMetaUnlocked(meta: Meta): void;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *

package/dist/lib/state.js

@@ -876,6 +876,9 @@ const META_KEY_SCOPE = {
     deviceRoutines: 'device',
     deviceConfig: 'device',
     deviceBrowser: 'device',
+    deviceFleet: 'device',
+    deviceHosts: 'device',
+    deviceAccounts: 'device',
     // Central — synced via agents.yaml.
     accounts: 'central',
     run: 'central',
@@ -915,6 +918,35 @@ const KNOWN_META_KEYS = new Set([
     // first registry read can migrate it into this device's file and delete it.
     'browser',
 ]);
+/**
+ * Rewrite a frozen `agents.yaml` header to the current {@link META_HEADER}.
+ *
+ * `serializeCentral` parses the existing file to preserve its hand-written body
+ * comments, but that also preserves the leading metadata header verbatim, so a
+ * top-level file written before the agi-cli rename (or before the `$schema` line
+ * existed) keeps its stale header forever — every freshly-written device doc gets
+ * the current header while the shared file is left behind (PHNX-3315).
+ *
+ * The header is healed TEXTUALLY, on the already-serialized string, rather than
+ * via `doc.commentBefore`: the `yaml` library folds the whole leading comment
+ * block onto the FIRST key's `commentBefore` when that key already carries a
+ * hand-written comment, so the header is not reliably the document comment — but
+ * it is always the top block of the output. Strip a leading `agents-cli metadata`
+ * header (any pre-rename variant, with or without the `$schema` line — the URL
+ * and schema lines are matched specifically so a hand-written body comment is
+ * never mistaken for a header line) and prepend the canonical header. A file with
+ * no recognizable header simply gains one. Body comments, which sit below the
+ * blank line that terminates the header, are untouched.
+ */
+function healMetaHeader(serialized) {
+    const headerBlock = /^# agents-cli metadata\n# Auto-generated - do not edit manually\n(?:# (?:https:\/\/github\.com\/phnx-labs\/[^\n]*|yaml-language-server: \$schema=[^\n]*)\n)*\n?/;
+    const stripped = serialized.replace(headerBlock, '');
+    // No metadata header present (replace was a no-op) → leave the file exactly as
+    // it is. We heal a STALE header; we never prepend one to a file that never had
+    // it (that would rewrite a hand-authored, headerless central file on the first
+    // real central change). A current header round-trips to the identical bytes.
+    return stripped === serialized ? serialized : META_HEADER + stripped;
+}
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.
@@ -973,20 +1005,37 @@ function serializeCentral(central) {
         }
     }
     // No central field changed → keep the file byte-identical (comments intact), so
-    // writeIfChanged skips it and the churn loop never starts.
+    // writeIfChanged skips it and the churn loop never starts. A device-only write
+    // (pins/routines/etc. routed elsewhere) reaches here with changed=false and
+    // MUST NOT rewrite the shared file — header healing waits for a genuine central
+    // change below rather than dirtying agents.yaml on an unrelated write, which is
+    // the very churn that wedges `agents sync` and blocks fleet pulls.
     if (!changed)
         return existing;
-    // Everything cleared → header only (never leave a flow `{}` behind).
-    // Otherwise stringifyDoc: it still normalizes a legacy flow root (`{}`) to
-    // block, so edited nodes do not render flow (`disabledCommands: [ teams ]`
-    // instead of a `- teams` block list), but it no longer forces block on a
-    // normal document — that flattened committed flow sequences and made this
-    // writer disagree with feed.ts/activity.ts/migrate.ts on the same file
-    // (RUSH-2505). parseDocument still preserves comments + key ordering.
-    return isEmpty ? META_HEADER : stringifyDoc(doc);
+    // Everything cleared → header only (never leave a flow `{}` behind). Byte-stable
+    // when the file is already exactly the current header.
+    if (isEmpty)
+        return existing === META_HEADER ? existing : META_HEADER;
+    // A central key changed: serialize the edited doc and heal a frozen header on
+    // the result. stringifyDoc still normalizes a legacy flow root (`{}`) to block,
+    // so edited nodes do not render flow (`disabledCommands: [ teams ]` instead of a
+    // `- teams` block list), but it no longer forces block on a normal document —
+    // that flattened committed flow sequences and made this writer disagree with
+    // feed.ts/activity.ts/migrate.ts on the same file (RUSH-2505). parseDocument
+    // still preserves body comments + key ordering; healMetaHeader is a no-op unless
+    // a stale metadata header is actually present, so a headerless central file is
+    // updated in place without gaining one.
+    return healMetaHeader(stringifyDoc(doc));
 }
-function writeMetaUnlocked(meta) {
-    const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, projectRoot, ...central } = meta;
+/**
+ * Write `meta` to disk (central + device docs + pins) WITHOUT taking the meta
+ * lock — the caller must already hold it via {@link withMetaLock}. Exported so a
+ * writer that needs to read fresh state, decide, and commit within a SINGLE lock
+ * acquisition (e.g. browser tombstone eviction) can do so without the
+ * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ */
+export function writeMetaUnlocked(meta) {
+    const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, deviceFleet, deviceHosts, deviceAccounts, projectRoot, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
     const hasAgents = !!agents && Object.keys(agents).length > 0;
@@ -1049,6 +1098,43 @@ function writeMetaUnlocked(meta) {
         doc.browser = deviceBrowser;
     else
         delete doc.browser;
+    // PHNX-3315 device-scoped fleet/hosts/accounts blocks. Each is this box's OWN
+    // slice; the effective fleet view is unioned across every device doc at read
+    // time (lib/devices/device-docs.ts). Empty slices are dropped so a box that
+    // has made no decision leaves no key behind (no committed empty maps).
+    const fleetDiscovery = deviceFleet?.discovery && Object.keys(deviceFleet.discovery).length > 0
+        ? deviceFleet.discovery : undefined;
+    const fleetIgnored = deviceFleet?.ignored && deviceFleet.ignored.length > 0
+        ? deviceFleet.ignored : undefined;
+    if (fleetDiscovery || fleetIgnored) {
+        const df = {};
+        if (fleetDiscovery)
+            df.discovery = fleetDiscovery;
+        if (fleetIgnored)
+            df.ignored = fleetIgnored;
+        doc.fleet = df;
+    }
+    else
+        delete doc.fleet;
+    const hasDeviceHosts = !!deviceHosts && Object.keys(deviceHosts).length > 0;
+    if (hasDeviceHosts)
+        doc.hosts = deviceHosts;
+    else
+        delete doc.hosts;
+    const accountsNative = deviceAccounts?.native && Object.keys(deviceAccounts.native).length > 0
+        ? deviceAccounts.native : undefined;
+    const accountsBindings = deviceAccounts?.bindings && Object.keys(deviceAccounts.bindings).length > 0
+        ? deviceAccounts.bindings : undefined;
+    if (accountsNative || accountsBindings) {
+        const da = {};
+        if (accountsNative)
+            da.native = accountsNative;
+        if (accountsBindings)
+            da.bindings = accountsBindings;
+        doc.accounts = da;
+    }
+    else
+        delete doc.accounts;
     const hasProjectRoot = typeof projectRoot === 'string' && projectRoot.length > 0;
     if (hasProjectRoot)
         doc.projectRoot = projectRoot;
@@ -1121,6 +1207,52 @@ function overlayMachineLocal(meta) {
             if (dm?.config && typeof dm.config === 'object' && !Array.isArray(dm.config)) {
                 meta.deviceConfig = { ...meta.deviceConfig, ...dm.config };
             }
+            // PHNX-3315: this box's own device-scoped fleet/hosts/accounts slices.
+            // These populate the `device*` keys the writers read-modify-write; the
+            // effective UNION across all boxes is computed separately by
+            // lib/devices/device-docs.ts, not here (this overlay is this box only).
+            // A malformed block on THIS box's own doc is a HARD error, exactly like
+            // `routines` below and the cross-box union readers (device-docs.ts): a
+            // silent drop would let the next writeMetaUnlocked round-trip overwrite the
+            // whole block with just the new entry, discarding the rest on this box's
+            // tracked file (PHNX-3315).
+            const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+            const dmRaw = dm;
+            if (dmRaw.fleet !== undefined) {
+                if (!isMap(dmRaw.fleet))
+                    throw new Error(`Device config corrupted at ${devicePath}: fleet must be a map.`);
+                const df = dmRaw.fleet;
+                if (df.discovery !== undefined && !isMap(df.discovery)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: fleet.discovery must be a map.`);
+                }
+                if (df.ignored !== undefined && !Array.isArray(df.ignored)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: fleet.ignored must be a list.`);
+                }
+                const discovery = df.discovery;
+                const ignored = df.ignored;
+                if (discovery || ignored)
+                    meta.deviceFleet = { ...(discovery ? { discovery } : {}), ...(ignored ? { ignored } : {}) };
+            }
+            if (dmRaw.hosts !== undefined) {
+                if (!isMap(dmRaw.hosts))
+                    throw new Error(`Device config corrupted at ${devicePath}: hosts must be a map.`);
+                meta.deviceHosts = { ...meta.deviceHosts, ...dmRaw.hosts };
+            }
+            if (dmRaw.accounts !== undefined) {
+                if (!isMap(dmRaw.accounts))
+                    throw new Error(`Device config corrupted at ${devicePath}: accounts must be a map.`);
+                const acc = dmRaw.accounts;
+                if (acc.native !== undefined && !isMap(acc.native)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: accounts.native must be a map.`);
+                }
+                if (acc.bindings !== undefined && !isMap(acc.bindings)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: accounts.bindings must be a map.`);
+                }
+                const native = acc.native;
+                const bindings = acc.bindings;
+                if (native || bindings)
+                    meta.deviceAccounts = { ...(native ? { native } : {}), ...(bindings ? { bindings } : {}) };
+            }
             if (Object.prototype.hasOwnProperty.call(dm, 'routines')) {
                 if (!Array.isArray(dm.routines) || dm.routines.some((name) => typeof name !== 'string')) {
                     throw new Error(`Device config corrupted at ${devicePath}: routines must be a string list.`);

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