@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/share/publish.js

@@ -9,11 +9,108 @@ 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, readWriteToken } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
 import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
 import { injectAnalyticsBeacon } from './analytics.js';
+/**
+ * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
+ * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
+ * may not target any of these (see {@link parseMetaEntries}).
+ */
+export const RESERVED_META_KEYS = ['agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
+const META_KEY_RE = /^[a-z0-9-]{1,64}$/;
+/**
+ * Auto-capture publish provenance from the exec env, git, and the local clock.
+ * Every field is present only when the environment genuinely carries it — a
+ * human running the command by hand outside a git repo yields `session`/`agent`/
+ * `repo` all undefined, never an invented value. `host` is always present
+ * (`os.hostname()` never fails to return something real about where the publish
+ * ran, so it isn't "invented" in the same sense).
+ */
+export function resolveShareProvenance(opts = {}) {
+    const env = opts.env ?? process.env;
+    return {
+        session: env.AGENTS_SESSION_ID || env.AGENT_SESSION_ID || undefined,
+        agent: env.AGENTS_AGENT_NAME || undefined,
+        host: opts.hostname ?? osHostname(),
+        repo: gitRepoName(opts.dir ?? process.cwd()),
+        date: (opts.now ?? new Date()).toISOString().slice(0, 10),
+    };
+}
+/**
+ * Parse repeated `--meta key=value` CLI args into a validated metadata record.
+ * Keys are lowercase `[a-z0-9-]`, up to 64 characters, and may not collide with
+ * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
+ * label/label-source) — throws naming the offending pair on any violation.
+ */
+export function parseMetaEntries(pairs) {
+    const meta = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0) {
+            throw new Error(`Bad --meta '${pair}'. Expected key=value.`);
+        }
+        const key = pair.slice(0, eq).trim();
+        const value = pair.slice(eq + 1);
+        if (!META_KEY_RE.test(key)) {
+            throw new Error(`Bad --meta key '${key}'. Keys are lowercase letters, digits, and hyphens, up to 64 characters.`);
+        }
+        if (RESERVED_META_KEYS.includes(key)) {
+            throw new Error(`--meta ${key}=… is reserved (set automatically from your session/git) — pass a different key.`);
+        }
+        meta[key] = value;
+    }
+    return meta;
+}
+/** S3's `x-amz-meta` convention caps user metadata around 2KB; R2 publishes no
+ * hard limit of its own, so stay under that ceiling to keep a share portable to
+ * an S3-compatible mirror. Checked over the FULL customMetadata payload
+ * (provenance + label + --meta combined), since that's what actually gets
+ * written to the object. */
+const MAX_METADATA_BYTES = 2048;
+/** Throws when the combined `customMetadata` payload would exceed {@link MAX_METADATA_BYTES}. */
+export function assertMetadataSize(customMetadata) {
+    const bytes = Buffer.byteLength(JSON.stringify(customMetadata), 'utf8');
+    if (bytes > MAX_METADATA_BYTES) {
+        throw new Error(`Share metadata is ${bytes} bytes, over the ${MAX_METADATA_BYTES}-byte cap ` +
+            `(provenance + --label + --meta combined). Trim your --meta values.`);
+    }
+}
+/**
+ * Collapse a label to a single line before it goes into the `x-share-label`
+ * header or public customMetadata. `<title>[^<]{1,200}</title>` matches
+ * newlines (`[^<]` excludes only `<`), and `.trim()` only strips leading/
+ * trailing whitespace, not embedded newlines — a multi-line `<title>` (or an
+ * explicit `--label`/`--title` the caller typed with a literal newline) was
+ * previously passed straight into `Headers.set()` unsanitized, which throws
+ * an unhandled `TypeError: Invalid value` and crashes the publish outright.
+ */
+export function sanitizeLabel(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
+ * Markdown frontmatter `title:`, else the filename. Always returns something —
+ * a headless publish must never hang waiting on a prompt for one.
+ */
+export function deriveLabel(filePath, body) {
+    const text = body.toString('utf8');
+    const htmlTitle = /<title[^>]*>([^<]{1,200})<\/title>/i.exec(text);
+    if (htmlTitle?.[1]?.trim())
+        return sanitizeLabel(htmlTitle[1]);
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (frontmatter) {
+        const titleLine = /^title:\s*(.+)$/m.exec(frontmatter[1]);
+        const cleaned = titleLine?.[1]?.trim().replace(/^["']|["']$/g, '').trim();
+        if (cleaned)
+            return sanitizeLabel(cleaned);
+    }
+    const base = basename(filePath).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').trim();
+    return sanitizeLabel(base || basename(filePath));
+}
 /** Default auto-expire for unflagged publishes — accidental links decay (RUSH-2443). */
 export const DEFAULT_SHARE_EXPIRE = '30d';
 const UNIT_MS = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
@@ -118,7 +215,7 @@ export function formatSensitiveContentError(hits) {
         : kinds[0] === 'email'
             ? 'email addresses'
             : 'credential-shaped strings';
-    return (`Refusing to publish: the file contains ${what} (${samples}). ` +
+    return (`Refusing to publish: found ${what} (${samples}) in the file, label, or metadata. ` +
         `Shares are world-readable by URL — pass --force to publish anyway, ` +
         `or --unlisted --expire 12h to bound the blast radius.`);
 }
@@ -134,8 +231,9 @@ export function slugify(name) {
 function sanitizeSlugPart(s) {
     return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
 }
-/** The project the file belongs to — git repo name, else the cwd's basename. */
-export function detectProject(dir = process.cwd()) {
+/** The current repo's name, or undefined outside a git checkout — never a
+ * fallback guess, since callers that want one (detectProject) supply it themselves. */
+function gitRepoName(dir) {
     try {
         const top = execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
             stdio: ['ignore', 'pipe', 'ignore'],
@@ -143,12 +241,16 @@ export function detectProject(dir = process.cwd()) {
             .toString()
             .trim();
         if (top)
-            return sanitizeSlugPart(basename(top)) || 'share';
+            return sanitizeSlugPart(basename(top)) || undefined;
     }
     catch {
-        // not a git repo — fall through to cwd basename
+        // not a git repo
     }
-    return sanitizeSlugPart(basename(dir)) || 'share';
+    return undefined;
+}
+/** The project the file belongs to — git repo name, else the cwd's basename. */
+export function detectProject(dir = process.cwd()) {
+    return gitRepoName(dir) ?? (sanitizeSlugPart(basename(dir)) || 'share');
 }
 /**
  * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
@@ -273,31 +375,79 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const expiresAt = resolveExpire(opts.expire);
     const unlisted = opts.unlisted === true;
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
+    const provenance = opts.provenance ?? resolveShareProvenance();
+    const meta = opts.meta ?? {};
     const put = opts.uploader ??
         (async (u, b, h) => {
             const res = await fetch(u, { method: 'PUT', headers: h, body: new Uint8Array(b) });
             return { ok: res.ok, status: res.status, url: u };
         });
-    const authHeaders = (contentType) => {
-        const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
-        if (expiresAt)
-            h['x-share-expires-at'] = expiresAt;
-        if (unlisted)
-            h['x-share-visibility'] = 'unlisted';
-        return h;
-    };
     let body = readFileSync(filePath);
     let coverUrl;
     const isHtml = /\.html?$/i.test(filePath);
-    // Pre-publish scan (RUSH-2443): refuse emails / credential-shaped strings
-    // unless --force. Runs on the raw file before analytics/cover mutation so a
-    // beacon injection never triggers a false positive. Binary media is a no-op.
+    const explicitLabel = opts.label?.trim();
+    // sanitizeLabel here (not just inside deriveLabel) covers an explicit
+    // --label/--title the caller typed with an embedded newline — deriveLabel
+    // is only reached when --label is omitted.
+    const label = explicitLabel ? sanitizeLabel(explicitLabel) : deriveLabel(filePath, body);
+    const labelSource = explicitLabel ? 'explicit' : 'derived';
+    // Pre-publish scan (RUSH-2443/RUSH-2683): refuse emails / credential-shaped
+    // strings unless --force. Runs on the raw file body AND on every piece of
+    // free-text metadata that lands in public customMetadata — --label (explicit
+    // or derived) and every --meta value. Metadata is visible in the gallery,
+    // `share list --json`, and `share revisions` just like the page itself, so a
+    // credential smuggled in there is exactly as exposed as one in the body; it
+    // must not have a free pass around this gate. Runs before analytics/cover
+    // mutation so a beacon injection never triggers a false positive on the body
+    // scan. Binary media bodies are a no-op for the body scan.
     if (opts.force !== true) {
-        const hits = scanShareContent(body);
+        const hits = [
+            ...scanShareContent(body),
+            ...scanShareContent(label),
+            ...Object.values(meta).flatMap((v) => scanShareContent(v)),
+        ];
         if (hits.length > 0) {
             throw new Error(formatSensitiveContentError(hits));
         }
     }
+    // Validate the FULL customMetadata payload before any network call — fail
+    // fast, not mid-upload.
+    const metadataPreview = { ...meta, label, 'label-source': labelSource };
+    if (provenance.agent)
+        metadataPreview.agent = provenance.agent;
+    if (provenance.session)
+        metadataPreview.session = provenance.session;
+    if (provenance.host)
+        metadataPreview.host = provenance.host;
+    if (provenance.repo)
+        metadataPreview.repo = provenance.repo;
+    if (provenance.date)
+        metadataPreview.date = provenance.date;
+    assertMetadataSize(metadataPreview);
+    const authHeaders = (contentType) => {
+        const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
+        if (expiresAt)
+            h['x-share-expires-at'] = expiresAt;
+        if (unlisted)
+            h['x-share-visibility'] = 'unlisted';
+        if (provenance.agent)
+            h['x-share-agent'] = provenance.agent;
+        if (provenance.session)
+            h['x-share-session'] = provenance.session;
+        if (provenance.host)
+            h['x-share-host'] = provenance.host;
+        if (provenance.repo)
+            h['x-share-repo'] = provenance.repo;
+        if (provenance.date)
+            h['x-share-date'] = provenance.date;
+        h['x-share-label'] = label;
+        h['x-share-label-source'] = labelSource;
+        if (Object.keys(meta).length > 0)
+            h['x-share-meta'] = JSON.stringify(meta);
+        if (opts.noRevision)
+            h['x-share-no-revision'] = '1';
+        return h;
+    };
     // Analytics: cookieless CF Web Analytics beacon, injected for HTML by default.
     if (isHtml && opts.analytics !== false && opts.analyticsToken) {
         body = Buffer.from(injectAnalyticsBeacon(body.toString('utf8'), opts.analyticsToken), 'utf8');
@@ -324,6 +474,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         url: r.url ?? pageUrl,
         expiresAt,
         coverUrl,
+        label,
+        labelSource,
         ...(unlisted ? { unlisted: true } : {}),
     };
 }

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

@@ -2,11 +2,16 @@
 //
 // One tiny Worker does both sides:
 //   - PUT  /<username>/<slug>  — bearer-gated (WRITE_TOKEN secret); writes the body
-//     to R2 via the BUCKET binding, storing an optional expires-at value in
-//     object metadata.
+//     to R2 via the BUCKET binding, storing an optional expires-at value plus
+//     provenance (agent/session/host/repo/date), a label, and any `--meta`
+//     entries in object metadata. Overwriting an existing slug first copies the
+//     current object to <slug>/rev-<ts>-<rand> (revision history) unless
+//     x-share-no-revision is set.
 //   - GET  /<username>/<slug>  — public; streams the object from R2, 410s (and lazily
 //     deletes) once its expiry has passed. A bucket lifecycle rule is the durable
 //     sweeper; this is the immediate gate.
+//   - GET  /<username>/<slug>?revisions=json — machine-readable history of the
+//     retained prior versions under that slug, newest first.
 //   - GET  /<username>         — public gallery of that user's shares (HTML).
 //   - GET  /<username>?format=json — public machine-readable listing of that user's
 //     ACTIVE shares (`agents artifacts share list`). Same single-segment path as the HTML
@@ -55,9 +60,71 @@ export default {
       // keeping the direct URL world-readable (capability URL, not secret).
       const visibility = (request.headers.get('x-share-visibility') || '').toLowerCase();
       const contentType = request.headers.get('content-type') || 'text/html; charset=utf-8';
-      const customMetadata = {};
+      // Provenance (RUSH-2683): captured client-side from the exec env/git/clock,
+      // never invented here — a header is simply absent when the CLI had nothing
+      // to say. --meta entries ride one JSON header; reserved keys are stripped
+      // from that JSON UNCONDITIONALLY (not just overwritten when a provenance
+      // header happens to be present) so a same-named x-share-meta entry can
+      // never smuggle through on a publish that carries no agent/session/host/
+      // repo/date at all — e.g. a human publishing outside an agent session, or
+      // outside a git checkout.
+      const agent = request.headers.get('x-share-agent') || '';
+      const session = request.headers.get('x-share-session') || '';
+      const host = request.headers.get('x-share-host') || '';
+      const repo = request.headers.get('x-share-repo') || '';
+      const date = request.headers.get('x-share-date') || '';
+      const label = request.headers.get('x-share-label') || '';
+      const labelSource = request.headers.get('x-share-label-source') || '';
+      let extraMeta = {};
+      const metaHeader = request.headers.get('x-share-meta');
+      if (metaHeader) {
+        try {
+          const parsed = JSON.parse(metaHeader);
+          if (parsed && typeof parsed === 'object') extraMeta = parsed;
+        } catch {
+          // malformed --meta header — ignore rather than fail the whole publish
+        }
+      }
+      const customMetadata = { ...extraMeta };
+      // Strip every reserved key UNCONDITIONALLY before re-applying the real
+      // provenance below — an if(value)-guarded overwrite alone leaves a
+      // same-named --meta entry in place whenever the real header is absent.
+      for (const reservedKey of RESERVED_METADATA_KEYS) {
+        delete customMetadata[reservedKey];
+      }
       if (expiresAt) customMetadata['expires-at'] = expiresAt;
       if (visibility === 'unlisted') customMetadata['visibility'] = 'unlisted';
+      if (agent) customMetadata['agent'] = agent;
+      if (session) customMetadata['session'] = session;
+      if (host) customMetadata['host'] = host;
+      if (repo) customMetadata['repo'] = repo;
+      if (date) customMetadata['date'] = date;
+      if (label) customMetadata['label'] = label;
+      if (labelSource) customMetadata['label-source'] = labelSource;
+
+      // Revision retention (RUSH-2683): R2 has no native object versioning, so a
+      // republish over an EXISTING key first copies the current object to
+      // <key>/rev-<ts>-<rand> before the canonical key is overwritten. Default
+      // keep-all; --no-revision (x-share-no-revision) skips it. The random
+      // suffix guards against two rapid overwrites of the same slug colliding on
+      // the millisecond, and against a slug whose canonical key already sits 3+
+      // segments deep (an unsupported shape outside the CLI) landing on the same
+      // literal revision key.
+      const noRevision = !!request.headers.get('x-share-no-revision');
+      if (!noRevision) {
+        const existing = await env.BUCKET.get(path);
+        if (existing) {
+          const existingHeaders = new Headers();
+          if (typeof existing.writeHttpMetadata === 'function') existing.writeHttpMetadata(existingHeaders);
+          const existingContentType = existingHeaders.get('content-type');
+          const revKey = path + '/rev-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);
+          await env.BUCKET.put(revKey, existing.body, {
+            httpMetadata: existingContentType ? { contentType: existingContentType } : undefined,
+            customMetadata: existing.customMetadata || {},
+          });
+        }
+      }
+
       await env.BUCKET.put(path, request.body, {
         httpMetadata: { contentType },
         customMetadata,
@@ -88,6 +155,13 @@ export default {
         // signal rather than a missing route).
       }
 
+      // Revision history for one canonical <user>/<slug> key (RUSH-2683). Checked
+      // before the plain object GET below so the query param routes even though
+      // the canonical key itself resolves to a real object.
+      if (segments.length === 2 && url.searchParams.get('revisions') === 'json') {
+        return renderRevisions(env.BUCKET, url.origin, path, request.method);
+      }
+
       const obj = await env.BUCKET.get(path);
       if (!obj) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
       const expiresAt = obj.customMetadata && obj.customMetadata['expires-at'];
@@ -114,6 +188,16 @@ export default {
   },
 };
 
+// A canonical share object's key is exactly 2 segments (<user>/<slug>, or the
+// sibling <user>/<slug>.png OG cover). A retained revision lives a 3rd segment
+// deeper (<user>/<slug>/rev-<ts>-<rand>) — history, not a page in its own
+// right, so every gallery/listing view hides it. A raw external PUT to an
+// already-3-segment-deep path is treated the same way for the same reason:
+// there is no ambiguity to resolve, and the CLI never produces such a key.
+function isRevisionKey(key) {
+  return key.split('/').length > 2;
+}
+
 async function renderGallery(bucket, origin, user, method) {
   const objects = [];
   let cursor;
@@ -124,6 +208,7 @@ async function renderGallery(bucket, origin, user, method) {
   } while (cursor);
 
   const activeObjects = objects.filter(o => {
+    if (isRevisionKey(o.key)) return false;
     if (o.key.endsWith('.png')) return false;
     // Unlisted pages are reachable by direct URL only — never on the gallery.
     if (o.customMetadata && o.customMetadata.visibility === 'unlisted') return false;
@@ -133,7 +218,9 @@ async function renderGallery(bucket, origin, user, method) {
   const items = activeObjects.map(o => {
     const slug = o.key.slice(o.key.indexOf('/') + 1);
     const url = origin + '/' + o.key;
-    return { slug, url, updated: o.uploaded };
+    const label = (o.customMetadata && o.customMetadata['label']) || '';
+    const agent = (o.customMetadata && o.customMetadata['agent']) || '';
+    return { slug, url, updated: o.uploaded, label, agent };
   });
 
   if (method === 'HEAD') {
@@ -148,14 +235,17 @@ async function renderGallery(bucket, origin, user, method) {
     'body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;max-width:720px;margin:48px auto;padding:0 24px;color:#111;background:#fafafa}' +
     'h1{font-size:28px;margin-bottom:8px}a{color:#0a0a0a;text-decoration:none;border-bottom:1px solid #999}' +
     'a:hover{border-color:#111}ul{list-style:none;padding:0}li{margin:16px 0}' +
-    '.slug{font-weight:600}.meta{color:#666;font-size:14px}' +
+    '.slug{font-weight:600}.title{font-weight:600}.meta{color:#666;font-size:14px}' +
     '</style></head><body>' +
     '<h1>@' + escapeHtml(user) + '</h1>' +
     '<p class="meta">' + items.length + ' shared ' + (items.length === 1 ? 'page' : 'pages') + '</p>' +
     '<ul>' +
     items.map(i =>
-      '<li><a class="slug" href="' + escapeHtml(i.url) + '">' + escapeHtml(i.slug) + '</a>' +
-      '<br><span class="meta">' + new Date(i.updated).toISOString().slice(0, 10) + '</span></li>'
+      '<li>' +
+      (i.label ? '<span class="title">' + escapeHtml(i.label) + '</span><br>' : '') +
+      '<a class="slug" href="' + escapeHtml(i.url) + '">' + escapeHtml(i.slug) + '</a>' +
+      '<br><span class="meta">' + new Date(i.updated).toISOString().slice(0, 10) +
+      (i.agent ? ' · ' + escapeHtml(i.agent) : '') + '</span></li>'
     ).join('') +
     '</ul></body></html>';
   return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'public, max-age=60' } });
@@ -170,11 +260,21 @@ async function renderListing(bucket, origin, user, method) {
     cursor = list.truncated ? list.cursor : undefined;
   } while (cursor);
 
+  // Revisions never appear as their own listing row, but they count toward
+  // their canonical object's revisionCount.
+  const revisionCounts = {};
+  for (const o of objects) {
+    if (!isRevisionKey(o.key)) continue;
+    const canonicalKey = o.key.split('/').slice(0, 2).join('/');
+    revisionCounts[canonicalKey] = (revisionCounts[canonicalKey] || 0) + 1;
+  }
+
   const now = Date.now();
   const items = objects
     .filter(o => {
-      // Mirror the gallery: hide sibling .png OG covers, expired pages, and
-      // unlisted pages — the listing is the machine-readable public surface.
+      // Mirror the gallery: hide revisions, sibling .png OG covers, expired
+      // pages, and unlisted pages — the listing is the machine-readable public surface.
+      if (isRevisionKey(o.key)) return false;
       if (o.key.endsWith('.png')) return false;
       if (o.customMetadata && o.customMetadata.visibility === 'unlisted') return false;
       const expiresAt = o.customMetadata && o.customMetadata['expires-at'];
@@ -187,6 +287,13 @@ async function renderListing(bucket, origin, user, method) {
       contentType: (o.httpMetadata && o.httpMetadata.contentType) || null,
       publishedAt: new Date(o.uploaded).toISOString(),
       expiresAt: (o.customMetadata && o.customMetadata['expires-at']) || null,
+      label: (o.customMetadata && o.customMetadata['label']) || null,
+      agent: (o.customMetadata && o.customMetadata['agent']) || null,
+      session: (o.customMetadata && o.customMetadata['session']) || null,
+      host: (o.customMetadata && o.customMetadata['host']) || null,
+      repo: (o.customMetadata && o.customMetadata['repo']) || null,
+      revisionCount: revisionCounts[o.key] || 0,
+      meta: extraMetaOf(o.customMetadata),
     }));
   // Newest first, so the human table and any script reads the freshest share top.
   items.sort((a, b) => (a.publishedAt < b.publishedAt ? 1 : a.publishedAt > b.publishedAt ? -1 : 0));
@@ -200,6 +307,62 @@ async function renderListing(bucket, origin, user, method) {
   });
 }
 
+async function renderRevisions(bucket, origin, key, method) {
+  const objects = [];
+  let cursor;
+  do {
+    const list = await bucket.list({ prefix: key + '/rev-', limit: 1000, cursor, include: ['httpMetadata', 'customMetadata'] });
+    objects.push(...(list.objects || []));
+    cursor = list.truncated ? list.cursor : undefined;
+  } while (cursor);
+
+  const items = objects.map(o => ({
+    key: o.key,
+    url: origin + '/' + o.key,
+    size: typeof o.size === 'number' ? o.size : 0,
+    contentType: (o.httpMetadata && o.httpMetadata.contentType) || null,
+    uploadedAt: new Date(o.uploaded).toISOString(),
+    expiresAt: (o.customMetadata && o.customMetadata['expires-at']) || null,
+    label: (o.customMetadata && o.customMetadata['label']) || null,
+    agent: (o.customMetadata && o.customMetadata['agent']) || null,
+    session: (o.customMetadata && o.customMetadata['session']) || null,
+    host: (o.customMetadata && o.customMetadata['host']) || null,
+    repo: (o.customMetadata && o.customMetadata['repo']) || null,
+    meta: extraMetaOf(o.customMetadata),
+  }));
+  // Newest first — the most recently replaced version leads.
+  items.sort((a, b) => (a.uploadedAt < b.uploadedAt ? 1 : a.uploadedAt > b.uploadedAt ? -1 : 0));
+
+  if (method === 'HEAD') {
+    return new Response(null, { status: 200, headers: { 'content-type': 'application/json; charset=utf-8' } });
+  }
+  return new Response(JSON.stringify({ key, count: items.length, revisions: items }), {
+    status: 200,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'public, max-age=30' },
+  });
+}
+
+// The customMetadata keys the CLI sets automatically (provenance + label) —
+// never a real \`--meta key=value\` entry (the CLI rejects a colliding key
+// before it ever reaches this Worker; see RESERVED_META_KEYS in publish.ts).
+// One list, reused both to strip a same-named --meta collision on write and
+// to split arbitrary --meta entries back out on read.
+var RESERVED_METADATA_KEYS = ['expires-at', 'visibility', 'agent', 'session', 'host', 'repo', 'date', 'label', 'label-source'];
+
+// Everything in customMetadata that ISN'T one of the reserved provenance/label
+// keys above — i.e. the caller's own \`--meta key=value\` entries. Surfaced on
+// every read route (listing, revisions) so a value stored with \`--meta
+// kind=plan --meta ticket=RUSH-2683\` is actually visible again, not just
+// write-only (RUSH-2683 review fix).
+function extraMetaOf(customMetadata) {
+  var out = {};
+  if (!customMetadata) return out;
+  for (var k in customMetadata) {
+    if (RESERVED_METADATA_KEYS.indexOf(k) === -1) out[k] = customMetadata[k];
+  }
+  return out;
+}
+
 function escapeHtml(s) {
   return String(s)
     .replace(/&/g, '&amp;')

package/dist/lib/shims.js

@@ -504,6 +504,32 @@ parse_agents_default() {
   ' "$meta"
 }
 
+# Parse the pins JSON (~/.agents/.history/devices/pins-<machine>.json) for this
+# AGENT's pinned version. The file is JSON.stringify(…, 2) output, so the
+# "agents" map sits at 2-space indent and its entries at 4 — a stable shape the
+# awk below scrapes without a JSON parser (shims must stay dependency-free).
+parse_pins_default() {
+  local pins="$1"
+  [ -f "$pins" ] || return 0
+  # Scope carefully: enter ONLY on a line that opens the agents block
+  # (  "agents": {) — an inline-empty map ("agents": {}) must NOT enter,
+  # or the needle would leak into a following "isolatedAgents" block and an
+  # isolated pin would masquerade as the global default. Exit at the block's
+  # closing brace (a trailing comma is fine). Entries sit at exactly 4 spaces.
+  awk -v agent="$AGENT" '
+    /^  "agents": [{]$/ { in_agents=1; next }
+    in_agents && /^  }/ { exit }
+    in_agents && /^    "/ {
+      needle = "\\"" agent "\\":"
+      if (index($0, needle) > 0) {
+        line = substr($0, index($0, needle) + length(needle))
+        gsub(/[[:space:],"]/, "", line)
+        print line; exit
+      }
+    }
+  ' "$pins"
+}
+
 # This machine's device id — mirrors machineId()/normalizeHost() in
 # src/lib/machine-id.ts: first hostname label, lowercased, non-[a-z0-9_-] -> '-'.
 # MUST stay in sync or the shim reads the wrong device folder.
@@ -514,15 +540,17 @@ machine_id() {
   [ -n "$raw" ] && printf '%s' "$raw" || printf 'unknown'
 }
 
-# Resolve the default version. The agents: version pins are stored PER-DEVICE at
-# devices/<machine>/agents.yaml (moved there so multi-machine syncs never
-# conflict); read that first, then fall back to the central agents.yaml for
-# pre-split installs. Must match readMeta()'s central+device merge in state.ts --
-# reading only the central file (the old behavior) missed every device pin and
-# made the shim re-prompt "no default set" on every launch.
+# Resolve the default version. The agents: version pins are MACHINE-LOCAL runtime
+# state at .history/devices/pins-<machine>.json (untracked — auto-written pins in
+# the tracked device doc caused commit churn); read that first, then fall back to
+# the tracked device doc (installs not yet migrated) and finally the central
+# agents.yaml (pre-split installs). Must match readMeta()'s central+pins merge in
+# state.ts -- reading only the central file (the old behavior) missed every device
+# pin and made the shim re-prompt "no default set" on every launch.
 resolve_default_version() {
   local v
-  v=$(parse_agents_default "$AGENTS_USER_DIR/devices/$(machine_id)/agents.yaml")
+  v=$(parse_pins_default "$AGENTS_USER_DIR/.history/devices/pins-$(machine_id).json")
+  [ -n "$v" ] || v=$(parse_agents_default "$AGENTS_USER_DIR/devices/$(machine_id)/agents.yaml")
   [ -n "$v" ] || v=$(parse_agents_default "$AGENTS_USER_DIR/agents.yaml")
   printf '%s' "$v"
 }

package/dist/lib/smart-launch.d.ts

@@ -1,5 +1,5 @@
 /**
- * Device placement for `--device auto` / `--host auto`.
+ * Device placement for `--device auto`.
  *
  * Explicit auto placement probes live fleet health and harness readiness.
  * Historical affinity remains for generic host resolution callers.
@@ -60,7 +60,7 @@ export interface DeviceAffinityOptions {
     project?: string;
 }
 export interface DeviceAffinityPlan {
-    /** null means run locally (do not pass --host). */
+    /** null means run locally (do not pass --device). */
     host: string | null;
     deviceCandidates: WeightedCandidate[];
     pickedDeviceKey: string | null;
@@ -100,7 +100,7 @@ export declare function resolveDeviceAuto(agent?: string, opts?: {
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
  *
  * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
- * `agents ssh auto`, the generic `--host auto` passthrough, and `matchHost`'s
+ * `agents ssh auto`, the generic `--device auto` passthrough, and `matchHost`'s
  * `auto` sentinel honour device roles too. Throws when roles leave the pool
  * empty — a `null` host here means "run locally", which for a box marked
  * `personal` is the outcome the mark exists to prevent.
@@ -131,7 +131,7 @@ export type DeviceAutoApplyResult = {
     };
 };
 /**
- * Apply `--device auto` / `--host auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` (and deprecated `--smart`) onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */

package/dist/lib/smart-launch.js

@@ -1,5 +1,5 @@
 /**
- * Device placement for `--device auto` / `--host auto`.
+ * Device placement for `--device auto`.
  *
  * Explicit auto placement probes live fleet health and harness readiness.
  * Historical affinity remains for generic host resolution callers.
@@ -111,7 +111,9 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
     const target = agent ? `can run ${agent}` : "for 'run auto'";
     // Name the role narrowing when there is one: a fleet where every box but two
     // is filtered out by a worker mark reads as "the fleet is down" without it.
-    const marked = describeAutoPool();
+    // Roster on `pool` so a fleet-wide role default reaches a doc-less device
+    // in this error's own candidate set, not just the ones with a doc.
+    const marked = describeAutoPool({ roster: pool });
     const poolNote = marked ? ` [pool: ${marked}]` : '';
     return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}; earliest window resets unknown`;
 }
@@ -177,7 +179,7 @@ export async function resolveDeviceAuto(agent, opts = {}) {
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
  *
  * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
- * `agents ssh auto`, the generic `--host auto` passthrough, and `matchHost`'s
+ * `agents ssh auto`, the generic `--device auto` passthrough, and `matchHost`'s
  * `auto` sentinel honour device roles too. Throws when roles leave the pool
  * empty — a `null` host here means "run locally", which for a box marked
  * `personal` is the outcome the mark exists to prevent.
@@ -242,7 +244,7 @@ export function isDeviceAuto(value) {
 }
 const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
 /**
- * Apply `--device auto` / `--host auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` (and deprecated `--smart`) onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */