@phnx-labs/agents-cli 1.22.118 → 1.22.120

package/dist/lib/github/project-prs.d.ts

@@ -23,13 +23,22 @@
  */
 import { type GhExec } from './pr-mergeable.js';
 import { type RollupItem } from './rest.js';
-import type { ProjectDef } from '../projects.js';
+import { type ProjectDef } from '../projects.js';
 /** The author of a PR, as the menu renders it (login + avatar). */
 export interface ProjectPrAuthor {
     login: string;
     avatarUrl: string;
 }
-/** One open PR row. `checks`/`reviewDecision` are null unless the PR was enriched. */
+/**
+ * Where a PR sits for a project whose repository is SHARED with another project
+ * (a monorepo): `project` touches the paths this project claims, `repo-wide`
+ * touches no sharing project's paths (root config, CI, docs). A PR that touches
+ * only another project's paths is not listed at all. Null when the repository is
+ * not shared, or this project claims all of it. Claims are {@link repoPathClaims},
+ * the same ownership that attributes a session's cwd.
+ */
+export type ProjectPrScope = 'project' | 'repo-wide';
+/** One open PR row. `checks`/`reviewDecision`/merge state are null unless the PR was enriched. */
 export interface ProjectPr {
     number: number;
     title: string;
@@ -37,12 +46,18 @@ export interface ProjectPr {
     isDraft: boolean;
     /** Upper-cased GitHub state — always `OPEN` here (only open PRs are listed). */
     state: string;
+    createdAt: string;
     updatedAt: string;
     author: ProjectPrAuthor;
     headRefName: string;
     baseRefName: string;
     headSha: string;
     body: string;
+    scope: ProjectPrScope | null;
+    /** Populated only for the `--number` PR: GitHub's mergeability (null while it computes). */
+    mergeable: boolean | null;
+    /** Populated only for the `--number` PR: `clean` | `unstable` | `blocked` | `behind` | `dirty` | `draft` | `unknown` … */
+    mergeableState: string | null;
     /** Populated only for the `--number` PR: the head-SHA status-check rollup. */
     checks: RollupItem[] | null;
     /** Populated only for the `--number` PR: GitHub's computed review decision. */
@@ -51,6 +66,8 @@ export interface ProjectPr {
 /** One repository's open PRs, or the error that stopped its fetch. */
 export interface ProjectRepoPrs {
     slug: string;
+    /** Other project definitions attached to this same repository. */
+    sharedWith: string[];
     pullRequests: ProjectPr[];
     /** Non-null when the fetch failed — the list is then NOT authoritative. */
     error: string | null;
@@ -61,6 +78,8 @@ export interface ProjectPrsEnvelope {
         name: string;
         linearProjectId: string | null;
     };
+    /** The authenticated GitHub login — what a "mine" filter compares `author.login` to. */
+    viewer: string | null;
     repositories: ProjectRepoPrs[];
     /** True when at least one repository fetch failed (its list is incomplete). */
     partial: boolean;
@@ -110,9 +129,45 @@ export declare function enrichPr(repo: string, pr: ProjectPr, gh?: GhExec): Prom
  * is not one of the project's attached repos (raw or canonical) is refused.
  */
 export declare function resolveTargetSlugs(def: ProjectDef, repo: string | undefined, gh: GhExec): Promise<string[]>;
+/**
+ * Classify one PR of a shared repository by the files it changes. `own` are
+ * this project's prefixes, `others` every other sharing project's. Returns
+ * null when the PR belongs only to another project.
+ */
+export declare function scopeForFiles(files: readonly string[], own: readonly string[], others: readonly string[]): ProjectPrScope | null;
+/** The authenticated login, from a REST read gh caches for a day. */
+export declare function fetchViewer(gh?: GhExec): Promise<string | null>;
 /**
  * Build the full envelope. `number` (which the command requires alongside
  * `repo`) fetches and enriches exactly that one PR; otherwise every target
  * repo's open PRs are listed with checks/reviewDecision left null.
+ *
+ * `peers` are every project definition. A repository attached to more than one
+ * project is scoped: when this project claims part of it ({@link repoPathClaims}),
+ * its list keeps only PRs that touch those paths (`scope: project`) or touch no
+ * sharing project's paths (`scope: repo-wide`).
+ */
+export declare function buildProjectPrs(def: ProjectDef, opts?: ProjectPrsOptions, gh?: GhExec, peers?: readonly ProjectDef[]): Promise<ProjectPrsEnvelope>;
+/** How a PR is merged; the default is the first of these the repository allows. */
+export declare const MERGE_METHODS: readonly ["rebase", "squash", "merge"];
+export type MergeMethod = (typeof MERGE_METHODS)[number];
+/** The result of one `projects prs merge`. */
+export interface ProjectPrMergeResult {
+    repo: string;
+    number: number;
+    method: MergeMethod;
+    merged: boolean;
+    /** The merge commit SHA GitHub reports. */
+    sha: string | null;
+    message: string;
+}
+/** The first of {@link MERGE_METHODS} the repository allows. */
+export declare function defaultMergeMethod(repo: string, gh?: GhExec): Promise<MergeMethod>;
+/**
+ * Merge one PR over REST (`PUT repos/{repo}/pulls/{n}/merge`), pinned to `sha`:
+ * GitHub refuses with 409 when the head moved since the caller looked, so a push
+ * that landed after the menu rendered is never merged unseen. Branch protection,
+ * required checks and reviews are GitHub's to enforce; their refusal comes back
+ * as `merged: false` with GitHub's own message.
  */
-export declare function buildProjectPrs(def: ProjectDef, opts?: ProjectPrsOptions, gh?: GhExec): Promise<ProjectPrsEnvelope>;
+export declare function mergeProjectPr(repo: string, number: number, sha: string, method: MergeMethod | undefined, gh?: GhExec): Promise<ProjectPrMergeResult>;

package/dist/lib/github/project-prs.js

@@ -21,14 +21,20 @@
  *   - A per-repo fetch failure is reported as `repositories[].error` and flips
  *     `partial` — it is NEVER relabeled as "zero open PRs".
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { ghExec, canonicalizeRepo, projectRepoSlugs } from './pr-mergeable.js';
 import { rollupForSha } from './rest.js';
+import { repoPathClaims } from '../projects.js';
+import { getCacheDir } from '../state.js';
+import { atomicWriteFileSync } from '../fs-atomic.js';
 /** The jq projection that flattens a REST PR object into {@link ProjectPr}'s scalars. */
 const PR_JQ = '{number, title, url: .html_url, isDraft: (.draft // false), ' +
-    'state: (.state // "" | ascii_upcase), updatedAt: (.updated_at // ""), ' +
+    'state: (.state // "" | ascii_upcase), createdAt: (.created_at // ""), updatedAt: (.updated_at // ""), ' +
     'login: (.user.login // ""), avatarUrl: (.user.avatar_url // ""), ' +
     'headRefName: (.head.ref // ""), baseRefName: (.base.ref // ""), ' +
-    'headSha: (.head.sha // ""), body: (.body // "")}';
+    'headSha: (.head.sha // ""), body: (.body // ""), ' +
+    'mergeable: .mergeable, mergeableState: .mergeable_state}';
 /** Parse newline-delimited JSON (gh `--jq` streams one object per line/page). */
 function parseNdjson(out) {
     const rows = [];
@@ -48,12 +54,16 @@ export function rowToProjectPr(row) {
         url: String(row.url ?? ''),
         isDraft: Boolean(row.isDraft),
         state: String(row.state ?? ''),
+        createdAt: String(row.createdAt ?? ''),
         updatedAt: String(row.updatedAt ?? ''),
         author: { login: String(row.login ?? ''), avatarUrl: String(row.avatarUrl ?? '') },
         headRefName: String(row.headRefName ?? ''),
         baseRefName: String(row.baseRefName ?? ''),
         headSha: String(row.headSha ?? ''),
         body: String(row.body ?? ''),
+        scope: null,
+        mergeable: typeof row.mergeable === 'boolean' ? row.mergeable : null,
+        mergeableState: typeof row.mergeableState === 'string' ? row.mergeableState : null,
         checks: null,
         reviewDecision: null,
     };
@@ -121,7 +131,7 @@ export async function enrichPr(repo, pr, gh = ghExec) {
  */
 export async function resolveTargetSlugs(def, repo, gh) {
     const raw = projectRepoSlugs([def]);
-    // Canonicalize CONCURRENTLY — each `gh repo view` can take up to gh's 30s
+    // Canonicalize CONCURRENTLY — each repo read can take up to gh's 30s
     // timeout, so a sequential walk of N repos would stack N×30s and blow past a
     // native caller's bounded deadline. Repo count per project is small.
     const canonPairs = await Promise.all(raw.map(async (slug) => [slug, await canonicalizeRepo(slug, gh)]));
@@ -139,19 +149,145 @@ export async function resolveTargetSlugs(def, repo, gh) {
     }
     return [requested];
 }
+/**
+ * Classify one PR of a shared repository by the files it changes. `own` are
+ * this project's prefixes, `others` every other sharing project's. Returns
+ * null when the PR belongs only to another project.
+ */
+export function scopeForFiles(files, own, others) {
+    const under = (prefixes) => files.some((f) => prefixes.some((p) => f.startsWith(p)));
+    if (under(own))
+        return 'project';
+    if (under(others))
+        return null;
+    return 'repo-wide';
+}
+/**
+ * The files a PR changes, keyed by its head SHA. The list for a given head is
+ * immutable, so a cached entry never goes stale; a push mints a new key. Entries
+ * for heads that are no longer open in that repo are pruned on write.
+ */
+class PrFilesCache {
+    file = path.join(getCacheDir(), 'project-pr-files.json');
+    entries = {};
+    dirty = false;
+    constructor() {
+        // A missing or unreadable cache only costs re-reads; it never fails a list.
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.file, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                this.entries = parsed;
+        }
+        catch {
+            this.entries = {};
+        }
+    }
+    async files(slug, pr, gh) {
+        const key = `${slug}@${pr.headSha}`;
+        const hit = this.entries[key];
+        if (hit)
+            return hit;
+        // A rename counts on both sides: moving a file out of a project's path touches that project.
+        const out = await gh(['api', `repos/${slug}/pulls/${pr.number}/files?per_page=100`, '--paginate', '--jq', '.[] | .filename, (.previous_filename // empty)']);
+        const files = out.split('\n').map((l) => l.trim()).filter(Boolean);
+        this.entries[key] = files;
+        this.dirty = true;
+        return files;
+    }
+    prune(slug, openHeads) {
+        for (const key of Object.keys(this.entries)) {
+            const at = key.lastIndexOf('@');
+            if (key.slice(0, at) === slug && !openHeads.has(key.slice(at + 1))) {
+                delete this.entries[key];
+                this.dirty = true;
+            }
+        }
+    }
+    save() {
+        if (!this.dirty)
+            return;
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        atomicWriteFileSync(this.file, JSON.stringify(this.entries));
+    }
+}
+/** Run `fn` over `items` with at most `limit` in flight, preserving order. */
+async function mapBounded(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+/** The authenticated login, from a REST read gh caches for a day. */
+export async function fetchViewer(gh = ghExec) {
+    try {
+        return (await gh(['api', 'user', '--cache', '24h', '--jq', '.login'])).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The repository paths `def` claims, keyed by canonical slug. Canonicalization
+ * is cached, so this costs no network after the first run of the day.
+ */
+async function canonicalClaims(def, gh) {
+    const out = new Map();
+    for (const { slug, prefix } of repoPathClaims(def)) {
+        const canonical = await canonicalizeRepo(slug, gh);
+        out.set(canonical, [...(out.get(canonical) ?? []), prefix]);
+    }
+    return out;
+}
+/** For each canonical slug, the other projects attached to it and the paths they claim. */
+async function repoPeers(def, peers, gh) {
+    const bySlug = new Map();
+    await Promise.all(peers.filter((p) => p.name !== def.name).map(async (peer) => {
+        const [slugs, claims] = await Promise.all([
+            Promise.all(projectRepoSlugs([peer]).map((s) => canonicalizeRepo(s, gh))),
+            canonicalClaims(peer, gh),
+        ]);
+        for (const slug of new Set(slugs)) {
+            const entry = bySlug.get(slug) ?? { names: [], prefixes: [] };
+            entry.names.push(peer.name);
+            entry.prefixes.push(...(claims.get(slug) ?? []));
+            bySlug.set(slug, entry);
+        }
+    }));
+    for (const entry of bySlug.values())
+        entry.names.sort();
+    return bySlug;
+}
 /**
  * Build the full envelope. `number` (which the command requires alongside
  * `repo`) fetches and enriches exactly that one PR; otherwise every target
  * repo's open PRs are listed with checks/reviewDecision left null.
+ *
+ * `peers` are every project definition. A repository attached to more than one
+ * project is scoped: when this project claims part of it ({@link repoPathClaims}),
+ * its list keeps only PRs that touch those paths (`scope: project`) or touch no
+ * sharing project's paths (`scope: repo-wide`).
  */
-export async function buildProjectPrs(def, opts = {}, gh = ghExec) {
+export async function buildProjectPrs(def, opts = {}, gh = ghExec, peers = []) {
     const project = { name: def.name, linearProjectId: def.linear?.projectId ?? null };
     const slugs = await resolveTargetSlugs(def, opts.repo, gh);
+    if (slugs.length === 0)
+        return { project, viewer: null, repositories: [], partial: false };
+    const viewerRead = fetchViewer(gh);
+    const [shared, ownClaims] = await Promise.all([repoPeers(def, peers, gh), canonicalClaims(def, gh)]);
+    const filesCache = new PrFilesCache();
     // Fetch repos in PARALLEL so a native caller's overall deadline scales with the
     // slowest repo, not the sum — a serial multi-repo walk of 30s gh calls can blow
     // past a bounded caller timeout and lose the whole result. Repo count is small
     // (a project's attached repos), so this is a bounded fan-out, not unbounded.
     const repositories = await Promise.all(slugs.map(async (slug) => {
+        const peer = shared.get(slug);
+        const sharedWith = peer?.names ?? [];
         try {
             let pullRequests;
             if (opts.number !== undefined) {
@@ -160,14 +296,76 @@ export async function buildProjectPrs(def, opts = {}, gh = ghExec) {
             }
             else {
                 pullRequests = await listOpenPrs(slug, gh);
+                const own = ownClaims.get(slug);
+                if (peer && own) {
+                    filesCache.prune(slug, new Set(pullRequests.map((pr) => pr.headSha)));
+                    const scopes = await mapBounded(pullRequests, 8, async (pr) => scopeForFiles(await filesCache.files(slug, pr, gh), own, peer.prefixes));
+                    pullRequests = pullRequests
+                        .map((pr, i) => ({ ...pr, scope: scopes[i] }))
+                        .filter((pr) => pr.scope !== null);
+                }
             }
-            return { slug, pullRequests, error: null };
+            return { slug, sharedWith, pullRequests, error: null };
         }
         catch (err) {
             // A fetch failure is reported, never relabeled as zero open PRs.
-            return { slug, pullRequests: [], error: err instanceof Error ? err.message : String(err) };
+            return { slug, sharedWith, pullRequests: [], error: err instanceof Error ? err.message : String(err) };
         }
     }));
+    filesCache.save();
     const partial = repositories.some((r) => r.error !== null);
-    return { project, repositories, partial };
+    return { project, viewer: await viewerRead, repositories, partial };
+}
+/** How a PR is merged; the default is the first of these the repository allows. */
+export const MERGE_METHODS = ['rebase', 'squash', 'merge'];
+/** The first of {@link MERGE_METHODS} the repository allows. */
+export async function defaultMergeMethod(repo, gh = ghExec) {
+    const allowed = JSON.parse((await gh([
+        'api', `repos/${repo}`, '--cache', '1h',
+        '--jq', '{rebase: .allow_rebase_merge, squash: .allow_squash_merge, merge: .allow_merge_commit}',
+    ])).trim());
+    const method = MERGE_METHODS.find((m) => allowed[m]);
+    if (!method)
+        throw new Error(`${repo} allows no merge method this token can see.`);
+    return method;
+}
+/**
+ * gh prints GitHub's refusal on stderr (`gh: Required status check … (HTTP 405)`),
+ * sometimes followed by a hint line (a 401 adds `try authenticating with: gh auth
+ * login`). Keep the line carrying the HTTP status, else the first line.
+ */
+function ghFailure(err) {
+    const stderr = err?.stderr;
+    const text = typeof stderr === 'string' && stderr.trim() ? stderr : err instanceof Error ? err.message : String(err);
+    const lines = text.trim().split('\n').map((l) => l.trim()).filter(Boolean);
+    const line = lines.find((l) => /\(HTTP \d{3}\)/.test(l)) ?? lines[0] ?? text;
+    return line.replace(/^gh:\s*/, '');
+}
+/**
+ * Merge one PR over REST (`PUT repos/{repo}/pulls/{n}/merge`), pinned to `sha`:
+ * GitHub refuses with 409 when the head moved since the caller looked, so a push
+ * that landed after the menu rendered is never merged unseen. Branch protection,
+ * required checks and reviews are GitHub's to enforce; their refusal comes back
+ * as `merged: false` with GitHub's own message.
+ */
+export async function mergeProjectPr(repo, number, sha, method, gh = ghExec) {
+    let chosen;
+    try {
+        chosen = method ?? await defaultMergeMethod(repo, gh);
+    }
+    catch (err) {
+        return { repo, number, method: method ?? MERGE_METHODS[0], merged: false, sha: null, message: ghFailure(err) };
+    }
+    let out;
+    try {
+        out = await gh([
+            'api', '-X', 'PUT', `repos/${repo}/pulls/${number}/merge`,
+            '-f', `sha=${sha}`, '-f', `merge_method=${chosen}`, '--jq', '.sha',
+        ]);
+    }
+    catch (err) {
+        return { repo, number, method: chosen, merged: false, sha: null, message: ghFailure(err) };
+    }
+    // GitHub answers this endpoint 200 only once the PR is merged; anything else made gh exit non-zero.
+    return { repo, number, method: chosen, merged: true, sha: out.trim() || null, message: 'Merged' };
 }

package/dist/lib/harness/adapters/cursor.js

@@ -15,13 +15,23 @@ export const cursorAdapter = {
         stripForeignConfigDir(result);
     },
     execPreModeArgs(ctx) {
-        // A configured headless run is the workspace trust decision. Keep this
-        // narrower than --yolo/-f, which also bypasses permission checks.
-        return ctx.resolvedMode === 'edit' && !ctx.interactive ? ['--trust'] : undefined;
+        // A configured headless run is the workspace trust decision, in plan mode
+        // too: an untrusted cwd otherwise stops on Cursor's trust prompt with no one
+        // to answer it. Keep this narrower than --yolo/-f, which skip already passes
+        // and which also bypasses permission checks.
+        return ctx.resolvedMode !== 'skip' && !ctx.interactive ? ['--trust'] : undefined;
+    },
+    // Headless read-only runs use ask mode, not --plan. In plan mode Cursor
+    // delivers its answer through the createPlan tool, which `-p` text output
+    // never prints, so the run exits 0 with an empty stdout. Ask mode is equally
+    // read-only (it refuses file writes) and prints its answer. Interactive plan
+    // keeps --plan, where the TUI renders the plan.
+    execModeArgs(ctx) {
+        return ctx.resolvedMode === 'plan' && !ctx.interactive ? ['--mode', 'ask'] : undefined;
     },
     routineModeArgs(cmd, ctx) {
         if (ctx.mode === 'plan') {
-            cmd.push('--plan');
+            cmd.push('--mode', 'ask', '--trust');
         }
         else if (ctx.mode === 'skip') {
             cmd.push('-f');

package/dist/lib/harness-auth-capabilities.d.ts

@@ -16,9 +16,10 @@ import type { AgentId } from './types.js';
 type HarnessIdentityKind = 'strong' | 'email' | 'opaque';
 /**
  * Durable worker credential, or `none` when the harness must log in per box.
- * Codex is both: an API key (portable, bills the API) OR a per-device
- * ChatGPT-plan device-auth login (the plan seat; never stored in the reserved
- * store because it is a rotating session).
+ * Codex and Grok are both: an API key (portable, bills the API) OR a
+ * per-device device-auth login (the subscription seat — ChatGPT plan,
+ * SuperGrok, X Premium+; never stored in the reserved store because it is a
+ * rotating session, so each box signs in for itself).
  */
 type HarnessWorkerKind = 'setup-token' | 'none' | `api-key:${string}` | `per-device${'' | `:${string}`}`;
 type HarnessWorker = HarnessWorkerKind | HarnessWorkerKind[];

package/dist/lib/harness-auth-capabilities.js

@@ -6,7 +6,7 @@ export const HARNESS_AUTH = {
     // the OS defaults to. The device-code screen prints the URL + code instead,
     // so the human finishes it in the browser profile they choose — which is
     // what makes it usable over an SSH shell on a worker.
-    grok: { login: ['login', '--device-auth'], status: null, identity: 'strong', worker: 'api-key:XAI_API_KEY', slotEnv: 'GROK_HOME' },
+    grok: { login: ['login', '--device-auth'], status: null, identity: 'strong', worker: ['api-key:XAI_API_KEY', 'per-device:device-auth'], slotEnv: 'GROK_HOME' },
     // auth.json has no email claim; identity is the sorted provider-id join
     // (`resolveOpenCodeAccountId`). NATIVE_ACCOUNT_CAPABILITIES.opencode.inspection
     // is already 'opaque'.

package/dist/lib/helper-versions.js

@@ -41,7 +41,7 @@
  * it would claim a distribution responsibility agents-cli no longer has.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.6.1' },
+    menubar: { tagPrefix: 'menubar', floor: '1.6.2' },
 };
 /** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
 export function helperTag(helper, version) {

package/dist/lib/installations/shims.d.ts

@@ -64,7 +64,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 = 32;
+export declare const SHIM_SCHEMA_VERSION = 33;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/installations/shims.js

@@ -271,7 +271,7 @@ async function promptConflictStrategy(conflictInfos) {
 // v32 — every config-dir pin (claude, grok, opencode, kimi, muse, copilot) yields to
 //        an account-slot launch (AGENTS_EXEC_HOME from `agents run`), so a slot run
 //        reads and writes its own slot home instead of the shared version home.
-export const SHIM_SCHEMA_VERSION = 32;
+export const SHIM_SCHEMA_VERSION = 33;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -306,7 +306,14 @@ function shellQuote(value) {
  * 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() {
+const GROK_RESOLVE_BINARY_FN = `_resolve_grok_current() {
+  local target
+  target=$(readlink -f "$1/bin/grok" 2>/dev/null) || return 0
+  [ -f "$target" ] && [ -x "$target" ] || return 0
+  [ "$(wc -c < "$target" 2>/dev/null || echo 0)" -ge 1000000 ] || return 0
+  printf '%s\\n' "$target"
+}
+_resolve_grok_binary() {
   local dir="$1" version_hint="$2"
   local candidate base size mtime
   for candidate in "$dir"/grok-*; do
@@ -569,12 +576,20 @@ ${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.
+  # \`bin/grok\` is grok's own current-release pointer, kept by its updater in
+  # both layouts (\`bin/grok -> ../downloads/grok-<v>-<arch>\` and the newer
+  # \`bin/grok -> grok-<v>\`); \`grok update\` never touches downloads/ in the
+  # newer one, so scanning downloads/ alone keeps exec'ing a dead release.
+  BINARY=$(_resolve_grok_current "$VERSION_DIR/home/.grok")
   GROK_DOWNLOADS="$VERSION_DIR/home/.grok/downloads"
-  if [ -d "$GROK_DOWNLOADS" ]; then
+  if [ -z "$BINARY" ] && [ -d "$GROK_DOWNLOADS" ]; then
     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
+    BINARY=$(_resolve_grok_current "$HOME/.grok")
+  fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
     GROK_DOWNLOADS="$HOME/.grok/downloads"
     if [ -d "$GROK_DOWNLOADS" ]; then
@@ -1300,12 +1315,15 @@ export AGENT_CLI_CREDENTIAL_STORE="file"
         ? `# 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}
+BINARY=$(_resolve_grok_current "${versionDir}/home/.grok")
 GROK_DOWNLOADS="${versionDir}/home/.grok/downloads"
-BINARY=""
-if [ -d "$GROK_DOWNLOADS" ]; then
+if [ -z "$BINARY" ] && [ -d "$GROK_DOWNLOADS" ]; then
   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
+  BINARY=$(_resolve_grok_current "$AGENTS_REAL_HOME/.grok")
+fi
 if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   GROK_GLOBAL_DOWNLOADS="$AGENTS_REAL_HOME/.grok/downloads"
   if [ -d "$GROK_GLOBAL_DOWNLOADS" ]; then

package/dist/lib/installations/store.d.ts

@@ -118,6 +118,15 @@ export declare function getVersionDir(agent: AgentId, version: string): string;
  * Returns null (fail loud, never guess) when nothing survives the size filter.
  */
 export declare function resolveGrokFallbackBinary(downloadsDir: string): string | null;
+/**
+ * Grok's own current-release pointer, `<grokHome>/bin/grok`, resolved to the
+ * real binary, or null when absent or not a real binary. Grok's updater keeps
+ * it current in both of its layouts (`bin/grok -> ../downloads/grok-<v>-<arch>`
+ * and the newer `bin/grok -> grok-<v>`, which never touches downloads/), so it
+ * is the only location that tracks `grok update`. Mirrors the shim's
+ * `_resolve_grok_current`.
+ */
+export declare function resolveGrokCurrentBinary(grokHome: string): string | null;
 /**
  * Get the binary path for a specific agent version.
  */

package/dist/lib/installations/store.js

@@ -339,12 +339,36 @@ export function resolveGrokFallbackBinary(downloadsDir) {
     }
     return best ? path.join(downloadsDir, best.name) : null;
 }
+/**
+ * Grok's own current-release pointer, `<grokHome>/bin/grok`, resolved to the
+ * real binary, or null when absent or not a real binary. Grok's updater keeps
+ * it current in both of its layouts (`bin/grok -> ../downloads/grok-<v>-<arch>`
+ * and the newer `bin/grok -> grok-<v>`, which never touches downloads/), so it
+ * is the only location that tracks `grok update`. Mirrors the shim's
+ * `_resolve_grok_current`.
+ */
+export function resolveGrokCurrentBinary(grokHome) {
+    try {
+        const target = fs.realpathSync(path.join(grokHome, 'bin', 'grok'));
+        const stat = fs.statSync(target);
+        if (!stat.isFile() || stat.size < MIN_GROK_BINARY_BYTES)
+            return null;
+        fs.accessSync(target, fs.constants.X_OK);
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Get the binary path for a specific agent version.
  */
 export function getBinaryPath(agent, version) {
     const agentConfig = AGENTS[agent];
     if (agent === 'grok') {
+        const current = resolveGrokCurrentBinary(path.join(getVersionHomePath(agent, version), '.grok'));
+        if (current)
+            return current;
         const grokDownloads = path.join(getVersionHomePath(agent, version), '.grok', 'downloads');
         // The directory token is the stable installation/account label. A
         // self-updating slot may carry a newer vendor release, whose binary keeps

package/dist/lib/installations/versions.js

@@ -2550,7 +2550,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         // Orphan-sweep stale skill directories from previous syncs under a
         // different cwd. Only runs in "full sync" mode (no explicit selection) —
         // see the matching guard on the commands sweep above for why. Skip
-        // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact.
+        // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact,
+        // and the harness's own directories (ownedSkillDirs), which it writes itself.
         const skillsTargetSweep = path.join(agentDir, 'skills');
         if (!userPassedSelection && fs.existsSync(skillsTargetSweep) && !fs.lstatSync(skillsTargetSweep).isSymbolicLink()) {
             // Trust real skills AND command-skills: when commandsInstallAsSkills, the
@@ -2558,7 +2559,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             // skills/. Those names are not in skillsToSync, so without this they'd be
             // swept as orphans — silently deleting every converted command (e.g.
             // /recap on Kimi or newer Codex releases).
-            const trustedSkills = new Set(skillsToSync);
+            const trustedSkills = new Set([...skillsToSync, ...(agentConfig.ownedSkillDirs ?? [])]);
             if (commandsInstallAsSkills)
                 for (const cmd of commandsToSync)
                     trustedSkills.add(cmd);

package/dist/lib/projects.d.ts

@@ -193,6 +193,22 @@ export declare function projectDirsAbs(def: ProjectDef, opts: {
     forRemote: boolean;
     primary?: string;
 }): string[];
+/**
+ * The repository paths a project claims, as `{ slug, prefix }` with `prefix`
+ * repo-relative and `dir/` shaped — the same ownership {@link projectRootsAbs}
+ * applies to a session's cwd, expressed against the repository instead of a
+ * checkout: a `defaultPath` narrowed under `root` claims that subtree of the
+ * primary `repo`, and a `repos[]` entry with a `subpath` claims that subpath. A
+ * project with no narrowed claim on a repository claims all of it and yields no
+ * row for it. Two cases of {@link projectRootsAbs} have no repository form and
+ * yield nothing here: a `defaultPath` outside `root` (no repo-relative path),
+ * and the weak root of a narrowed project (it only takes what nobody claims,
+ * which for a PR is the `repo-wide` scope).
+ */
+export declare function repoPathClaims(def: ProjectDef): Array<{
+    slug: string;
+    prefix: string;
+}>;
 /**
  * Which defined project a session belongs to, derived from its working
  * directory. A session whose `cwd` sits inside a project's repo root (or a