@phnx-labs/agents-cli 1.22.117 → 1.22.119

package/dist/lib/fleet-shared-state.js

@@ -1,11 +1,17 @@
 /**
- * Non-secret daemon state exchanged through the already fleet-synced user repo.
+ * Non-secret daemon state exchanged over SSH between fleet devices (PHNX-4116).
  *
- * Each device owns exactly one file under `~/.agents/devices/<device>/`, so
- * normal `agents repo push/pull user` merges the fleet without devices dialing
- * one another on every daemon tick. OAuth/setup-token values never belong here:
- * auth publishes only a readiness verdict; the existing encrypted SSH transport
- * remains the one path that may carry secret material.
+ * Each device owns exactly one file under `~/.agents/devices/<device>/`
+ * (`daemon-state.json`, UNTRACKED in the user repo). A device writes its OWN
+ * file locally; a PEER's file on this box is written only by the usage-sync
+ * exchange — a headed daemon dials each peer with `agents __usage-ingest
+ * --reply`, sending its own envelope on stdin and writing the peer's reply
+ * envelope here stamped with `receivedAt`. The envelope used to ride the user
+ * repo as a tracked file, which turned the shared store into 18k `chore(devices)`
+ * commits and wedged every clone behind a `git fetch` that timed out; git now
+ * carries only human-authored resources. OAuth/setup-token values never belong
+ * here: auth publishes only a readiness verdict; the existing encrypted SSH
+ * bundle push remains the one path that may carry secret material.
  */
 import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
@@ -23,11 +29,19 @@ export function fleetSharedStatePath(device, userAgentsDir = getUserAgentsDir())
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
-function parseFleetSharedDeviceState(raw, owner) {
-    const parsed = JSON.parse(raw);
-    if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || parsed.device !== owner) {
+/**
+ * Validate an already-parsed envelope. `owner` pins the `device` field when the
+ * caller knows whose envelope this must be (a file under `devices/<owner>/`);
+ * an envelope arriving over the exchange names its own owner, so the caller
+ * passes none and checks `device` against the dialed peer afterwards.
+ */
+export function parseFleetSharedDeviceStateEnvelope(parsed, owner) {
+    if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || typeof parsed.device !== 'string' || !parsed.device) {
         throw new Error('unrecognized shared-state envelope');
     }
+    if (owner !== undefined && parsed.device !== owner)
+        throw new Error('unrecognized shared-state envelope');
+    assertValidDeviceName(parsed.device);
     const usage = parsed.usage;
     if (usage !== undefined && (!isRecord(usage) || !isRecord(usage.rows))) {
         throw new Error('unrecognized usage snapshot');
@@ -41,8 +55,18 @@ function parseFleetSharedDeviceState(raw, owner) {
     if (sessions !== undefined && (!isRecord(sessions) || !Array.isArray(sessions.rows))) {
         throw new Error('unrecognized session mirror');
     }
+    const accounts = parsed.accounts;
+    if (accounts !== undefined && (!isRecord(accounts) || !Array.isArray(accounts.rows))) {
+        throw new Error('unrecognized account verdict rows');
+    }
+    if (parsed.receivedAt !== undefined && (typeof parsed.receivedAt !== 'number' || !Number.isFinite(parsed.receivedAt))) {
+        throw new Error('unrecognized receivedAt');
+    }
     return parsed;
 }
+function parseFleetSharedDeviceState(raw, owner) {
+    return parseFleetSharedDeviceStateEnvelope(JSON.parse(raw), owner);
+}
 /**
  * Merge one daemon-owned field into this device's shared file under a real
  * inter-process lock. Stable serialization avoids dirtying the user repo when
@@ -63,6 +87,8 @@ function mergeFleetState(currentRaw, device, patch) {
         ...(patch.usage !== undefined ? { usage: patch.usage } : {}),
         ...(patch.auth !== undefined ? { auth: patch.auth } : {}),
         ...(patch.sessions !== undefined ? { sessions: patch.sessions } : {}),
+        ...(patch.accounts !== undefined ? { accounts: patch.accounts } : {}),
+        ...(patch.receivedAt !== undefined ? { receivedAt: patch.receivedAt } : {}),
         version: FLEET_SHARED_STATE_VERSION,
         device,
     };
@@ -138,3 +164,46 @@ export function readFleetSharedDeviceStates(userAgentsDir = getUserAgentsDir())
     }
     return { states, errors };
 }
+/**
+ * This device's own envelope as it stands on disk — what the usage-sync exchange
+ * sends to peers and what `__usage-ingest --reply` prints back. A device that has
+ * never published anything yields the bare `{version, device}` envelope, so a
+ * peer still learns the device exists and answered.
+ */
+export function readOwnFleetSharedDeviceState(device, userAgentsDir = getUserAgentsDir()) {
+    const file = fleetSharedStatePath(device, userAgentsDir);
+    let raw = '';
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch { /* never published → bare envelope */ }
+    if (!raw.trim())
+        return { version: FLEET_SHARED_STATE_VERSION, device };
+    const state = parseFleetSharedDeviceState(raw, device);
+    // `receivedAt` is a receiver-side stamp; the owner never advertises one.
+    const { receivedAt: _receivedAt, ...own } = state;
+    return own;
+}
+/**
+ * Store a PEER's envelope, received over the SSH exchange, in that peer's file on
+ * this box, stamped with `receivedAt`. Merges field-by-field onto whatever the
+ * file already holds, so a partial envelope (a placement probe sends usage only)
+ * refreshes that field without erasing the peer's last auth verdict, session
+ * digests, or account rows. The five readers of `devices/<peer>/daemon-state.json`
+ * (usage merge, poller claims, auth verdicts, session mirror, account catalog)
+ * are unchanged by the transport swap. Async because it runs on the daemon's
+ * usage-sync tick once per peer reply: the sync lock would `sleepSync` the event
+ * loop for up to 30 s under contention (see {@link updateFleetSharedDeviceStateAsync}).
+ */
+export async function storePeerFleetSharedDeviceState(state, userAgentsDir = getUserAgentsDir(), receivedAt = Date.now()) {
+    const patch = { receivedAt };
+    if (state.usage !== undefined)
+        patch.usage = state.usage;
+    if (state.auth !== undefined)
+        patch.auth = state.auth;
+    if (state.sessions !== undefined)
+        patch.sessions = state.sessions;
+    if (state.accounts !== undefined)
+        patch.accounts = state.accounts;
+    return updateFleetSharedDeviceStateAsync(state.device, patch, userAgentsDir);
+}

package/dist/lib/fs-atomic.js

@@ -106,6 +106,21 @@ export function withFileLock(filePath, fn, opts = {}) {
         }
         catch (err) {
             lastError = err;
+            // proper-lockfile breaks stale locks with rmdir, which fails with ENOTDIR
+            // when a prior crash left a regular file instead of the expected directory.
+            // Remove the stale file so the next attempt can succeed. Match
+            // proper-lockfile's own path resolution: realpath when the option is on
+            // (the default), raw path when it is off.
+            if (err instanceof Error && err.code === 'ENOTDIR') {
+                try {
+                    const base = (opts.realpath ?? true) ? fs.realpathSync(filePath) : filePath;
+                    const lockPath = `${base}.lock`;
+                    const st = fs.statSync(lockPath);
+                    if (st.isFile())
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* best effort */ }
+            }
             if (Date.now() >= deadline)
                 break;
             const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);
@@ -175,6 +190,16 @@ export async function withFileLockAsync(filePath, fn, opts = {}) {
         }
         catch (err) {
             lastError = err;
+            if (err instanceof Error && err.code === 'ENOTDIR') {
+                try {
+                    const base = (opts.realpath ?? true) ? fs.realpathSync(filePath) : filePath;
+                    const lockPath = `${base}.lock`;
+                    const st = fs.statSync(lockPath);
+                    if (st.isFile())
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* best effort */ }
+            }
             if (Date.now() >= deadline)
                 break;
             const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);

package/dist/lib/github/pr-mergeable.d.ts

@@ -7,7 +7,7 @@
  *
  * This helper:
  *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
- *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *   2. Canonicalizes each slug (REST `repos/{slug}` — `phnx-labs/agents-cli` lists
  *      nothing; the live name is `phnx-labs/agi-cli`).
  *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
  *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
@@ -27,7 +27,9 @@ export declare function projectRepoSlugs(defs: readonly ProjectDef[]): string[];
 /**
  * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
  * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
- * name; `gh repo view` returns the live one. On error, keep the input slug.
+ * name; the REST repo read follows the rename redirect and returns the live one.
+ * REST + a 24h gh cache: a rename is rare, and every `projects prs` refresh asks.
+ * On error, keep the input slug.
  */
 export declare function canonicalizeRepo(slug: string, gh: GhExec): Promise<string>;
 interface ListedPr {

package/dist/lib/github/pr-mergeable.js

@@ -7,7 +7,7 @@
  *
  * This helper:
  *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
- *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *   2. Canonicalizes each slug (REST `repos/{slug}` — `phnx-labs/agents-cli` lists
  *      nothing; the live name is `phnx-labs/agi-cli`).
  *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
  *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
@@ -65,12 +65,14 @@ export function projectRepoSlugs(defs) {
 /**
  * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
  * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
- * name; `gh repo view` returns the live one. On error, keep the input slug.
+ * name; the REST repo read follows the rename redirect and returns the live one.
+ * REST + a 24h gh cache: a rename is rare, and every `projects prs` refresh asks.
+ * On error, keep the input slug.
  */
 export async function canonicalizeRepo(slug, gh) {
     try {
         const out = (await gh([
-            'repo', 'view', slug, '--json', 'nameWithOwner', '--jq', '.nameWithOwner',
+            'api', `repos/${slug}`, '--cache', '24h', '--jq', '.full_name',
         ])).trim();
         return out || slug;
     }

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'.
@@ -17,7 +17,6 @@ export const HARNESS_AUTH = {
     kimi: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'KIMI_CODE_HOME' },
     antigravity: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     droid: { login: null, status: null, identity: 'opaque', worker: 'api-key:FACTORY_API_KEY', slotEnv: null },
-    gemini: { login: null, status: null, identity: 'email', worker: 'none', slotEnv: null },
     copilot: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'COPILOT_HOME' },
     openclaw: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     amp: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },