@phnx-labs/agents-cli 1.22.35 → 1.22.38

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

@@ -10,9 +10,25 @@ export interface PublishEndpoint {
 }
 export interface PublishOptions {
     slug?: string;
-    /** e.g. `30d`, `12h`, or an absolute date like `2026-08-01`. */
+    /**
+     * Auto-expire window. Relative (`30d`, `12h`), absolute (`2026-08-01`), or
+     * `never` / `none` / `permanent` for no expiry. When omitted, publishes default
+     * to {@link DEFAULT_SHARE_EXPIRE} so an accidental share decays instead of
+     * living forever (RUSH-2443).
+     */
     expire?: string;
     contentType?: string;
+    /**
+     * Hide this page from the public `/<user>` gallery and `agents artifacts share list`
+     * (metadata `visibility=unlisted`). The direct URL is still world-readable —
+     * unlisted, not secret (RUSH-2443). Alias of `--private` on the CLI.
+     */
+    unlisted?: boolean;
+    /**
+     * Bypass the pre-publish sensitive-content scan (emails / credential-shaped
+     * strings). Required when the page intentionally carries those patterns.
+     */
+    force?: boolean;
     /** Generate + attach an OG cover for HTML pages (default true). */
     cover?: boolean;
     /** Inject the Cloudflare Web Analytics beacon (default true for HTML). */
@@ -34,9 +50,32 @@ export interface PublishResult {
     url: string;
     expiresAt?: string;
     coverUrl?: string;
+    /** True when the page was published with `visibility=unlisted`. */
+    unlisted?: boolean;
 }
+/** Default auto-expire for unflagged publishes — accidental links decay (RUSH-2443). */
+export declare const DEFAULT_SHARE_EXPIRE = "30d";
 /** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
 export declare function parseExpire(spec: string | undefined): string | undefined;
+/**
+ * Resolve the publish expiry. Omitted → {@link DEFAULT_SHARE_EXPIRE}. Explicit
+ * `never` / `none` / `permanent` → no expiry. Anything else → {@link parseExpire}.
+ */
+export declare function resolveExpire(spec: string | undefined): string | undefined;
+export type SensitiveHitKind = 'email' | 'credential';
+export interface SensitiveHit {
+    kind: SensitiveHitKind;
+    /** Short redacted sample so the error names *what* was found without dumping it. */
+    sample: string;
+}
+/**
+ * Scan a text body for email addresses and credential-shaped strings. Returns
+ * the first few hits (deduped by kind+sample). Binary / non-text bodies yield
+ * nothing — the gate is for HTML/text reports, not screenshots.
+ */
+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). */
 export declare function slugify(name: string): string;
 /** The project the file belongs to — git repo name, else the cwd's basename. */

package/dist/lib/share/publish.js

@@ -1,4 +1,4 @@
-// The publish path for `agents share <file>` — an authed PUT to the Worker.
+// The publish path for `agents artifacts share <file>` — an authed PUT to the Worker.
 // Pure logic (slug, expiry) is exported for tests; the network call is behind a DI seam.
 //
 // For HTML publishes it also captures a 1200×630 cover (the page's own hero) and
@@ -14,6 +14,8 @@ 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';
+/** 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 };
 /** `30d` / `12h` / `2026-08-01` → an absolute ISO timestamp (or undefined). */
 export function parseExpire(spec) {
@@ -26,7 +28,99 @@ export function parseExpire(spec) {
     const d = new Date(spec);
     if (!Number.isNaN(d.getTime()))
         return d.toISOString();
-    throw new Error(`Bad --expire '${spec}'. Use e.g. 30d, 12h, or an absolute date like 2026-08-01.`);
+    throw new Error(`Bad --expire '${spec}'. Use e.g. 30d, 12h, an absolute date like 2026-08-01, or 'never' for no expiry.`);
+}
+/**
+ * Resolve the publish expiry. Omitted → {@link DEFAULT_SHARE_EXPIRE}. Explicit
+ * `never` / `none` / `permanent` → no expiry. Anything else → {@link parseExpire}.
+ */
+export function resolveExpire(spec) {
+    if (spec === undefined)
+        return parseExpire(DEFAULT_SHARE_EXPIRE);
+    const trimmed = spec.trim().toLowerCase();
+    if (trimmed === 'never' || trimmed === 'none' || trimmed === 'permanent')
+        return undefined;
+    return parseExpire(spec);
+}
+/** Email addresses — the RUSH-2428 incident page carried seven of these. */
+const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+/**
+ * Credential-shaped strings that an agent routinely dumps into reports: GitHub
+ * PATs, OpenAI/Anthropic/etc. API keys, AWS access keys, Slack tokens, and a
+ * generic long `sk-…` / `Bearer …` form. Keep the set tight — false positives
+ * force `--force` and train agents to bypass the gate.
+ */
+const CREDENTIAL_PATTERNS = [
+    { re: /\bghp_[A-Za-z0-9_]{20,}\b/g, label: 'ghp_…' },
+    { re: /\bgho_[A-Za-z0-9_]{20,}\b/g, label: 'gho_…' },
+    { re: /\bghu_[A-Za-z0-9_]{20,}\b/g, label: 'ghu_…' },
+    { re: /\bghs_[A-Za-z0-9_]{20,}\b/g, label: 'ghs_…' },
+    { re: /\bghr_[A-Za-z0-9_]{20,}\b/g, label: 'ghr_…' },
+    { re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, label: 'github_pat_…' },
+    { re: /\bsk-(?:ant|proj|live|test)?[_-]?[A-Za-z0-9]{16,}\b/g, label: 'sk-…' },
+    { re: /\bAKIA[0-9A-Z]{16}\b/g, label: 'AKIA…' },
+    { re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, label: 'xox…' },
+    { re: /\bBearer\s+[A-Za-z0-9._\-+/=]{20,}\b/gi, label: 'Bearer …' },
+];
+function redactSample(raw, max = 12) {
+    if (raw.length <= max)
+        return raw.slice(0, 4) + '…';
+    return raw.slice(0, Math.min(6, max)) + '…';
+}
+/**
+ * Scan a text body for email addresses and credential-shaped strings. Returns
+ * the first few hits (deduped by kind+sample). Binary / non-text bodies yield
+ * nothing — the gate is for HTML/text reports, not screenshots.
+ */
+export function scanShareContent(body) {
+    // Skip clearly-binary content (null bytes in the first 1KB) so a PNG/MP4
+    // publish never false-positives on binary noise.
+    if (Buffer.isBuffer(body)) {
+        const head = body.subarray(0, Math.min(body.length, 1024));
+        if (head.includes(0))
+            return [];
+    }
+    const text = typeof body === 'string' ? body : body.toString('utf8');
+    const hits = [];
+    const seen = new Set();
+    for (const m of text.matchAll(EMAIL_RE)) {
+        const sample = redactSample(m[0]);
+        const key = `email:${sample}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        hits.push({ kind: 'email', sample });
+        if (hits.length >= 5)
+            return hits;
+    }
+    for (const { re, label } of CREDENTIAL_PATTERNS) {
+        re.lastIndex = 0;
+        const m = re.exec(text);
+        if (!m)
+            continue;
+        const sample = label;
+        const key = `credential:${sample}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        hits.push({ kind: 'credential', sample });
+        if (hits.length >= 5)
+            return hits;
+    }
+    return hits;
+}
+/** Build the refuse message when the pre-publish scan finds sensitive content. */
+export function formatSensitiveContentError(hits) {
+    const kinds = Array.from(new Set(hits.map((h) => h.kind)));
+    const samples = hits.map((h) => h.sample).join(', ');
+    const what = kinds.length === 2
+        ? 'email addresses and credential-shaped strings'
+        : kinds[0] === 'email'
+            ? 'email addresses'
+            : 'credential-shaped strings';
+    return (`Refusing to publish: the file contains ${what} (${samples}). ` +
+        `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) {
@@ -161,7 +255,7 @@ export function buildShareKey(username, slugPart) {
 export async function publishFile(filePath, opts = {}) {
     const cfg = opts.config ?? readShareConfig();
     if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents share setup' (provision your own endpoint) or 'agents share join' (use an existing one).");
+        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
     }
     const token = opts.writeToken ?? readWriteToken();
     const username = await resolveShareUsername(opts);
@@ -176,7 +270,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const username = await resolveShareUsername(opts);
     const slugPart = (opts.slug ?? defaultSlug(filePath)).replace(/^\/+/, '');
     const key = buildShareKey(username, slugPart);
-    const expiresAt = parseExpire(opts.expire);
+    const expiresAt = resolveExpire(opts.expire);
+    const unlisted = opts.unlisted === true;
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const put = opts.uploader ??
         (async (u, b, h) => {
@@ -187,16 +282,29 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         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.
+    if (opts.force !== true) {
+        const hits = scanShareContent(body);
+        if (hits.length > 0) {
+            throw new Error(formatSensitiveContentError(hits));
+        }
+    }
     // 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');
     }
     // Cover: screenshot the page's hero → upload <slug>.png → inject og:image meta.
+    // Unlisted pages still get a cover (the direct URL is the capability), but the
+    // cover inherits visibility=unlisted so it is also omitted from the gallery.
     if (isHtml && opts.cover !== false) {
         const res = await attachOgCover(filePath, body, {
             pngUrl: `${pageUrl}.png`,
@@ -210,7 +318,12 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
     if (!r.ok) {
-        throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents share setup' completed.`);
+        throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
-    return { url: r.url ?? pageUrl, expiresAt, coverUrl };
+    return {
+        url: r.url ?? pageUrl,
+        expiresAt,
+        coverUrl,
+        ...(unlisted ? { unlisted: true } : {}),
+    };
 }

package/dist/lib/share/worker-template.d.ts

@@ -1,2 +1,13 @@
-/** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
+/**
+ * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
+ *
+ * The literal below still spells the CLI `agents share` in its provenance comment,
+ * its root response, and its gallery title, even though the command is now
+ * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
+ * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
+ * recorded `templateHash` against, so editing ANY byte here marks every already-
+ * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
+ * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
+ * worth that; change this text only alongside a real Worker behavior change.
+ */
 export declare function renderWorkerScript(): string;

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

@@ -7,14 +7,30 @@
 //   - 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>         — public gallery of that user's shares.
+//   - 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
+//     gallery and gated on the SAME "does <username>/ hold any object" check, so it
+//     only intercepts a genuine namespace — a legacy flat slug with ?format=json
+//     still serves its real content, never a fake empty listing.
 //   - GET  /<slug>             — backward-compat flat slug (legacy shares before
 //     per-user namespaces).
 //
 // Emitted as a string (mirrors src/lib/serve/page.ts `renderPage()`), so it compiles
 // into `dist/**` and ships with no package.json#files change. `provision.ts` uploads
 // this verbatim as an ES-module Worker with a BUCKET (R2) binding + a WRITE_TOKEN secret.
-/** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
+/**
+ * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
+ *
+ * The literal below still spells the CLI `agents share` in its provenance comment,
+ * its root response, and its gallery title, even though the command is now
+ * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
+ * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
+ * recorded `templateHash` against, so editing ANY byte here marks every already-
+ * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
+ * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
+ * worth that; change this text only alongside a real Worker behavior change.
+ */
 export function renderWorkerScript() {
     return `// GENERATED by agents-cli agents share setup — do not edit here; edit
 // src/lib/share/worker-template.ts and re-run setup.
@@ -35,22 +51,41 @@ export default {
         return json({ error: 'unauthorized' }, 401);
       }
       const expiresAt = request.headers.get('x-share-expires-at') || '';
+      // 'unlisted' hides the page from the public gallery + JSON listing while
+      // 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 = {};
+      if (expiresAt) customMetadata['expires-at'] = expiresAt;
+      if (visibility === 'unlisted') customMetadata['visibility'] = 'unlisted';
       await env.BUCKET.put(path, request.body, {
         httpMetadata: { contentType },
-        customMetadata: expiresAt ? { 'expires-at': expiresAt } : {},
+        customMetadata,
       });
-      return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null }, 200);
+      return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null, unlisted: visibility === 'unlisted' }, 200);
     }
 
     if (request.method === 'GET' || request.method === 'HEAD') {
-      // Single-segment path may be a user gallery OR a legacy flat slug.
+      // Single-segment path may be a user gallery/listing OR a legacy flat slug.
+      // The disambiguator is whether the <seg>/ prefix holds any object: only a
+      // genuine per-user namespace does. BOTH the HTML gallery and the
+      // machine-readable listing gate on it, so ?format=json on a legacy flat
+      // slug (an object stored at the bare key, before per-user namespaces) does
+      // NOT hijack it into a fake empty listing — it falls through to the object
+      // GET below and serves its real content, exactly as before.
       const segments = path.split('/').filter(Boolean);
       if (segments.length === 1) {
         const list = await env.BUCKET.list({ prefix: segments[0] + '/', limit: 1 });
-        if (list.objects && list.objects.length > 0) {
-          return renderGallery(env.BUCKET, url.origin, segments[0], request.method);
+        const isNamespace = list.objects && list.objects.length > 0;
+        if (isNamespace) {
+          return url.searchParams.get('format') === 'json'
+            ? renderListing(env.BUCKET, url.origin, segments[0], request.method)
+            : renderGallery(env.BUCKET, url.origin, segments[0], request.method);
         }
+        // Not a namespace: fall through. A legacy flat-slug object resolves to its
+        // real content; anything else 404s (an empty/nonexistent namespace, which
+        // agents share list reads as "nothing published" via the template-hash
+        // signal rather than a missing route).
       }
 
       const obj = await env.BUCKET.get(path);
@@ -90,6 +125,8 @@ async function renderGallery(bucket, origin, user, method) {
 
   const activeObjects = objects.filter(o => {
     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;
     const expiresAt = o.customMetadata && o.customMetadata['expires-at'];
     return !(expiresAt && Date.now() > Date.parse(expiresAt));
   });
@@ -124,6 +161,45 @@ async function renderGallery(bucket, origin, user, method) {
   return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'public, max-age=60' } });
 }
 
+async function renderListing(bucket, origin, user, method) {
+  const objects = [];
+  let cursor;
+  do {
+    const list = await bucket.list({ prefix: user + '/', limit: 1000, cursor, include: ['httpMetadata', 'customMetadata'] });
+    objects.push(...(list.objects || []));
+    cursor = list.truncated ? list.cursor : undefined;
+  } while (cursor);
+
+  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.
+      if (o.key.endsWith('.png')) return false;
+      if (o.customMetadata && o.customMetadata.visibility === 'unlisted') return false;
+      const expiresAt = o.customMetadata && o.customMetadata['expires-at'];
+      return !(expiresAt && now > Date.parse(expiresAt));
+    })
+    .map(o => ({
+      slug: o.key.slice(o.key.indexOf('/') + 1),
+      url: origin + '/' + o.key,
+      size: typeof o.size === 'number' ? o.size : 0,
+      contentType: (o.httpMetadata && o.httpMetadata.contentType) || null,
+      publishedAt: new Date(o.uploaded).toISOString(),
+      expiresAt: (o.customMetadata && o.customMetadata['expires-at']) || null,
+    }));
+  // 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));
+
+  if (method === 'HEAD') {
+    return new Response(null, { status: 200, headers: { 'content-type': 'application/json; charset=utf-8' } });
+  }
+  return new Response(JSON.stringify({ user, count: items.length, objects: items }), {
+    status: 200,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'public, max-age=30' },
+  });
+}
+
 function escapeHtml(s) {
   return String(s)
     .replace(/&/g, '&amp;')

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 29;
+export declare const SHIM_SCHEMA_VERSION = 30;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -159,8 +159,22 @@ export declare function removeShim(agent: AgentId): boolean;
  *        alias failed with "not installed" whenever the binary was staged into
  *        the versioned home (installer run with GROK_HOME set, or grok
  *        self-update under the shim).
- */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 15;
+ *  v16 — RUSH-2459: two compounding grok binary-resolution bugs fixed. (1) The
+ *        "exact version match" grep ran against `ls`'s FULL PATH output, and
+ *        the versioned home's own path always contains the version string
+ *        (.../versions/grok/<version>/...), so it matched every candidate
+ *        unconditionally and silently degraded to "whatever ls sorts first" —
+ *        now matched against each candidate's basename instead. (2) When no
+ *        filename genuinely carries the version, the fallback no longer
+ *        trusts whatever sorts first: it rejects any grok-* candidate under
+ *        1MB (real grok binaries are ~100MB+; a stray wrapper/alias script is
+ *        a few hundred bytes) and prefers the most recently modified
+ *        survivor. On yosemite-s0 both bugs fired together: a stale, unrelated
+ *        grok-0.2.118-* file — a 99-byte wrapper that exec'd cursor-agent —
+ *        sorted alphabetically before the real self-updated grok binary and
+ *        was silently launched instead.
+ */
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 16;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).

package/dist/lib/shims.js

@@ -223,12 +223,79 @@ async function promptConflictStrategy(conflictInfos) {
 //        The old dispatcher checked only the global dir, so a pinned grok that
 //        installed into the versioned home fell through to the "not installed"
 //        error.
-export const SHIM_SCHEMA_VERSION = 29;
+// v30 — RUSH-2459: two compounding grok binary-resolution bugs fixed. (1) The
+//        "exact version match" grep ran against `ls`'s FULL PATH output, and
+//        the versioned home's own path always contains the version string
+//        (.../versions/grok/<version>/...), so it matched every candidate
+//        unconditionally and silently degraded to "whatever ls sorts first" —
+//        now matched against each candidate's basename instead. (2) When no
+//        filename genuinely carries the version, the fallback no longer
+//        trusts whatever sorts first: it rejects any grok-* candidate under
+//        1MB (real grok binaries are ~100MB+; a stray wrapper/alias script is
+//        a few hundred bytes) and prefers the most recently modified
+//        survivor. On yosemite-s0 both bugs fired together: a stale, unrelated
+//        grok-0.2.118-* file — a 99-byte wrapper that exec'd cursor-agent —
+//        sorted alphabetically before the real self-updated grok binary and
+//        was silently launched instead.
+export const SHIM_SCHEMA_VERSION = 30;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+/**
+ * Bash function embedded in every generated grok binary-resolution block
+ * (the dispatcher shim's `generateShimScript` and the direct alias's
+ * `generateVersionedAliasScript`). Prints the path to use, or nothing.
+ *
+ * Prefers a `grok-*` FILENAME that carries the pinned version string —
+ * checked against `basename`, never the full path: `dir` is always
+ * `.../versions/grok/<version>/home/.grok/downloads`, so the version string
+ * is already a substring of every path in that directory regardless of the
+ * actual filename. The original `ls "$dir"/grok-* | grep -i "$version"`
+ * matched on the full line and so matched every candidate unconditionally,
+ * silently degrading to "whatever sorts first" — the versioned-home half of
+ * RUSH-2459, distinct from (and compounding) the missing-match fallback bug
+ * below.
+ *
+ * Grok self-updates its binary in place while running under the shim, so a
+ * version-home's downloads dir can accumulate several `grok-*` files whose
+ * names have drifted away from the version-home's pinned version — when no
+ * filename carries it, never trust whatever the directory listing returns
+ * first (RUSH-2459: a stale, unrelated 99-byte wrapper script matching the
+ * `grok-*` naming pattern sorted before the real ~127MB self-updated binary
+ * and was silently exec'd). Instead, reject anything under
+ * MIN_GROK_BINARY_BYTES — comfortably above any wrapper/alias artifact,
+ * comfortably below a real compiled binary — and among the survivors, pick
+ * the most recently modified: the file grok's self-updater actually wrote
+ * last. Mirrors the TS implementation, `resolveGrokFallbackBinary` in
+ * versions.ts (which reads bare filenames via `fs.readdirSync` and so never
+ * had the full-path-match bug).
+ */
+const GROK_RESOLVE_BINARY_FN = `_resolve_grok_binary() {
+  local dir="$1" version_hint="$2"
+  local candidate base size mtime
+  for candidate in "$dir"/grok-*; do
+    [ -f "$candidate" ] || continue
+    base=$(basename "$candidate")
+    case "$base" in
+      *"$version_hint"*) printf '%s\\n' "$candidate"; return ;;
+    esac
+  done
+  local min_bytes=1000000
+  local best="" best_mtime=-1
+  for candidate in "$dir"/grok-*; do
+    [ -f "$candidate" ] || continue
+    size=$(wc -c < "$candidate" 2>/dev/null || echo 0)
+    [ "$size" -ge "$min_bytes" ] || continue
+    mtime=$(stat -c %Y "$candidate" 2>/dev/null || stat -f %m "$candidate" 2>/dev/null || echo -1)
+    if [ "$mtime" -gt "$best_mtime" ]; then
+      best_mtime="$mtime"
+      best="$candidate"
+    fi
+  done
+  printf '%s\\n' "$best"
+}`;
 function codexShimLaunchArgs() {
     return [
         '-c',
@@ -538,27 +605,20 @@ VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
 # for pre-fix installs, the global ~/.grok/downloads), not node_modules. We
 # still use the agents-cli version dir purely for GROK_HOME isolation.
 if [ "$AGENT" = "grok" ]; then
+${GROK_RESOLVE_BINARY_FN}
   # Check the versioned home first — this is where the binary lands when the
   # installer runs with GROK_HOME set (i.e. via the shim or a correct
   # \`agents add grok\`), or when grok self-updates from within the shim.
   GROK_DOWNLOADS="$VERSION_DIR/home/.grok/downloads"
   if [ -d "$GROK_DOWNLOADS" ]; then
-    # Prefer a binary whose filename contains the exact version
-    BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
-    if [ -z "$BINARY" ]; then
-      # Fallback to the "current" grok binary (symlink or latest)
-      BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
-    fi
+    BINARY=$(_resolve_grok_binary "$GROK_DOWNLOADS" "$VERSION")
   fi
   # Fall back to the global grok home (binary installed without GROK_HOME set,
   # e.g. an earlier \`agents add grok@latest\` before this resolution fix).
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
     GROK_DOWNLOADS="$HOME/.grok/downloads"
     if [ -d "$GROK_DOWNLOADS" ]; then
-      BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
-      if [ -z "$BINARY" ]; then
-        BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
-      fi
+      BINARY=$(_resolve_grok_binary "$GROK_DOWNLOADS" "$VERSION")
     fi
   fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
@@ -622,13 +682,12 @@ elif [ "$AGENT" = "muse" ]; then
     fi
   fi
 elif [ "$AGENT" = "warp" ]; then
-  # Warp Agent CLI installs a global, self-updating oz binary (brew cask on
-  # macOS, the oz-stable apt|yum|pacman package on Linux) -- a platform/package
-  # specific location, not ~/.local/bin -- so resolve it from PATH with the same
-  # shims-dir re-exec guard as droid/muse.
+  # Warp Agent CLI installs a global, self-updating warp binary at
+  # ~/.local/bin/warp (curl installer) -- like droid/muse -- so resolve it from
+  # PATH with the same shims-dir re-exec guard as droid/muse.
   BINARY=$(adopted_original_bin || echo "")
   if [ -z "$BINARY" ]; then
-    BINARY=$(command -v oz 2>/dev/null || echo "")
+    BINARY=$(command -v warp 2>/dev/null || echo "")
     case "$(readlink -f "$BINARY" 2>/dev/null)" in
       "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
     esac
@@ -942,8 +1001,22 @@ export function removeShim(agent) {
  *        alias failed with "not installed" whenever the binary was staged into
  *        the versioned home (installer run with GROK_HOME set, or grok
  *        self-update under the shim).
- */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 15;
+ *  v16 — RUSH-2459: two compounding grok binary-resolution bugs fixed. (1) The
+ *        "exact version match" grep ran against `ls`'s FULL PATH output, and
+ *        the versioned home's own path always contains the version string
+ *        (.../versions/grok/<version>/...), so it matched every candidate
+ *        unconditionally and silently degraded to "whatever ls sorts first" —
+ *        now matched against each candidate's basename instead. (2) When no
+ *        filename genuinely carries the version, the fallback no longer
+ *        trusts whatever sorts first: it rejects any grok-* candidate under
+ *        1MB (real grok binaries are ~100MB+; a stray wrapper/alias script is
+ *        a few hundred bytes) and prefers the most recently modified
+ *        survivor. On yosemite-s0 both bugs fired together: a stale, unrelated
+ *        grok-0.2.118-* file — a 99-byte wrapper that exec'd cursor-agent —
+ *        sorted alphabetically before the real self-updated grok binary and
+ *        was silently launched instead.
+ */
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 16;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -1062,18 +1135,17 @@ export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home
     const binaryResolution = agent === 'grok'
         ? `# Grok ships its native binary in the versioned home's .grok/downloads (or,
 # for pre-fix installs, the global ~/.grok/downloads), not node_modules.
+${GROK_RESOLVE_BINARY_FN}
 GROK_DOWNLOADS="${versionDir}/home/.grok/downloads"
 BINARY=""
 if [ -d "$GROK_DOWNLOADS" ]; then
-  BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
-  [ -n "$BINARY" ] || BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+  BINARY=$(_resolve_grok_binary "$GROK_DOWNLOADS" "${version}")
 fi
 # Fall back to the global grok home (binary installed without GROK_HOME set).
 if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   GROK_GLOBAL_DOWNLOADS="$HOME/.grok/downloads"
   if [ -d "$GROK_GLOBAL_DOWNLOADS" ]; then
-    BINARY=$(ls "$GROK_GLOBAL_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
-    [ -n "$BINARY" ] || BINARY=$(ls "$GROK_GLOBAL_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+    BINARY=$(_resolve_grok_binary "$GROK_GLOBAL_DOWNLOADS" "${version}")
   fi
 fi
 # Refuse a PATH match under our own shims dir — it resolves to this alias's
@@ -1110,10 +1182,10 @@ else
   esac
 fi`
                 : agent === 'warp'
-                    ? `# Warp Agent CLI installs a global self-updating \`oz\` binary (brew cask on
-# macOS, oz-stable apt|yum|pacman on Linux) — a platform-specific location, not
-# ~/.local/bin — so resolve it from PATH, refusing anything under our shims dir.
-BINARY=$(command -v oz 2>/dev/null || echo "")
+                    ? `# Warp Agent CLI installs a global self-updating \`warp\` binary at
+# ~/.local/bin/warp (curl installer) — like droid/muse — so resolve it from
+# PATH, refusing anything under our shims dir.
+BINARY=$(command -v warp 2>/dev/null || echo "")
 case "$BINARY" in
   "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
 esac`

package/dist/lib/signin-badge.js

@@ -24,11 +24,12 @@ export function loginHint(agentId) {
             return `${cli}, then /login`;
         case 'codex':
         case 'grok':
-        // Warp Agent CLI: `oz login` opens a browser sign-in (or set WARP_API_KEY).
-        case 'warp':
             return `${cli} login`;
         case 'opencode':
             return `${cli} auth login`;
+        // Warp Agent CLI has no `login` subcommand: running `warp` opens a browser
+        // sign-in on launch (or set WARP_API_KEY / pass --api-key), so the default
+        // bare-`warp` hint is correct.
         default:
             return cli;
     }

package/dist/lib/skills.js

@@ -10,6 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { normalizeAliases } from './resource-aliases.js';
 import { AGENTS, ensureSkillsDir, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
 import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, getTrashSkillsDir } from './state.js';
@@ -98,6 +99,7 @@ export function tryParseSkillMetadata(skillDir) {
                         version: parsed.version,
                         license: parsed.license,
                         keywords: parsed.keywords,
+                        aliases: normalizeAliases(parsed.aliases),
                     },
                 };
             }