@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/lib/git.js

@@ -829,6 +829,238 @@ export async function adoptRepo(source, targetDir) {
         return { success: false, commit: '', backedUp: [], error: err.message };
     }
 }
+/**
+ * Device-local record of the user config repo's remote URL, kept OUTSIDE the git
+ * tree so it survives a lost `.git` (`.history/` is gitignored runtime state).
+ * This is what lets `agents repo sync user` adopt-in-place a box that was healthy
+ * once and later lost its checkout, without the operator re-typing the URL.
+ */
+function userRepoRemoteRecordPath(dir) {
+    return path.join(dir, '.history', 'user-repo-remote.json');
+}
+/** Read an origin remote URL from a git dir, or null when there is none. */
+export function readOriginUrl(dir) {
+    if (!isGitRepo(dir))
+        return null;
+    try {
+        const url = execFileSync('git', ['-C', dir, 'config', '--get', 'remote.origin.url'], {
+            encoding: 'utf-8',
+        }).trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the user repo's remote URL to device-local runtime state so a future
+ * adopt-in-place can recover it after a `.git` loss. Best-effort — a write
+ * failure never blocks a sync.
+ */
+export function recordUserRepoRemote(dir, url) {
+    try {
+        const file = userRepoRemoteRecordPath(dir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ url }, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* runtime cache write is best-effort */
+    }
+}
+/**
+ * Resolve the user config repo's remote URL WITHOUT hardcoding it, for the
+ * adopt-in-place self-heal. In priority order:
+ *   1. an existing `origin` remote on the dir (a partial repo that kept its
+ *      `.git` but drifted) — the same source `agents repo sync` already reads;
+ *   2. the `AGENTS_USER_REPO_URL` env override (a fresh/never-cloned box);
+ *   3. the device-local record written by a prior healthy sync (a box that lost
+ *      its `.git` but kept `.history/` runtime state).
+ * Returns null when none is known — the caller then guides the operator to
+ * `agents repo pull user <git-url>` instead of crashing.
+ */
+export function resolveUserRepoRemoteUrl(dir) {
+    const fromOrigin = readOriginUrl(dir);
+    if (fromOrigin)
+        return fromOrigin;
+    const fromEnv = process.env.AGENTS_USER_REPO_URL?.trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const raw = fs.readFileSync(userRepoRemoteRecordPath(dir), 'utf-8');
+        const url = JSON.parse(raw).url?.trim();
+        if (url)
+            return url;
+    }
+    catch {
+        /* no record yet */
+    }
+    return null;
+}
+/**
+ * Decide whether a local top-level `agents.yaml` is a stale install stub that
+ * should be restored from the committed copy, vs. a legitimately customized file
+ * that must be preserved.
+ *
+ * The stub a partial install leaves behind (createDefaultMeta + a few config
+ * writes) is strictly SHORTER than the committed config AND missing whole
+ * top-level blocks the committed one carries (`config:` / `hooks:` — the fleet
+ * browser hub and hook registrations). Device-specific settings live in
+ * `devices/<host>/agents.yaml`, never here, so restoring the top-level file is
+ * safe. A file that already carries those blocks (or is longer) is treated as a
+ * real local edit and left alone — it surfaces as a modified path instead.
+ */
+export function isStaleAgentsYamlStub(local, committed) {
+    if (local.trim() === committed.trim())
+        return false;
+    const shorter = local.split('\n').length < committed.split('\n').length;
+    const missingBlock = (/^config:/m.test(committed) && !/^config:/m.test(local)) ||
+        (/^hooks:/m.test(committed) && !/^hooks:/m.test(local));
+    return shorter && missingBlock;
+}
+/**
+ * Adopt an EXISTING, non-git (or origin-less) `~/.agents` directory in place —
+ * git-back it against its remote WITHOUT re-cloning and WITHOUT destroying the
+ * runtime state it carries (`.cache` / `.history` / `scratch` / `.system`, all
+ * gitignored). The self-heal for a partial install (PHNX-3301): the current code
+ * hard-fails with "Not a git repo", and the only manual fix is a destructive
+ * re-clone that wipes that runtime state.
+ *
+ * Plumbing-only, so it never trips the fleet git-guard (no `reset` / `checkout
+ * <branch>` / `stash` / `git config`):
+ *   1. `git init` + point HEAD at `main`.
+ *   2. `git remote add origin <url>`.
+ *   3. `git fetch origin main`.
+ *   4. `git update-ref refs/heads/main origin/main`; set upstream to origin/main.
+ *   5. `git read-tree origin/main` — index = origin/main, working tree untouched.
+ *   6. Materialize only the tracked files MISSING from the working tree
+ *      (`checkout-index` on that set) — existing local files are never overwritten.
+ *   7. Reconcile the top-level `agents.yaml`: restore it from origin/main only
+ *      when the local copy is a stale stub ({@link isStaleAgentsYamlStub}).
+ *
+ * Idempotent: a second run finds the remote/refs already present and simply
+ * re-materializes nothing. Any tracked path with real local edits is returned in
+ * `localEdits` (surfaced, never clobbered).
+ */
+export async function adoptRepoInPlace(dir, remoteUrl) {
+    const empty = {
+        success: false,
+        commit: '',
+        materialized: 0,
+        reconciledAgentsYaml: false,
+        localEdits: [],
+    };
+    const trimmed = remoteUrl.trim();
+    try {
+        // The URL is always a resolved git remote (origin / env / record), never a
+        // `gh:` shorthand — so skip parseSource (which THROWS on ssh:// and rewrites
+        // git@github -> https, breaking SSH-key-only auth). assertSafeGitTransport
+        // still blocks the dangerous transports (ext::, file://, option injection)
+        // while permitting https / ssh / scp-style / a local bare repo.
+        assertSafeGitTransport(trimmed);
+        if (!fs.existsSync(dir)) {
+            return { ...empty, error: `Target directory does not exist: ${dir}` };
+        }
+        // Non-interactive git — fail fast on a missing credential instead of hanging
+        // on a prompt (same rationale as adoptRepo).
+        process.env.GIT_TERMINAL_PROMPT = '0';
+        const git = simpleGit(dir);
+        // 1. init + HEAD -> main (idempotent: init on an existing repo is a no-op).
+        //    Set HEAD via symbolic-ref rather than `init -b main` so it works on git
+        //    < 2.28, and lands on `main` even if the repo already initialized as
+        //    `master`.
+        if (!isGitRepo(dir))
+            await git.init();
+        await git.raw(['symbolic-ref', 'HEAD', 'refs/heads/main']);
+        // 2. origin — add only when absent, so a re-run keeps the existing remote.
+        const remotes = await git.getRemotes(true);
+        if (!remotes.some((r) => r.name === 'origin')) {
+            await git.raw(['remote', 'add', 'origin', trimmed]);
+        }
+        // 3-4. fetch, plant the local main on origin/main, set upstream.
+        await git.raw(['fetch', 'origin', 'main']);
+        await git.raw(['update-ref', 'refs/heads/main', 'origin/main']);
+        await git.raw(['branch', '--set-upstream-to=origin/main', 'main']);
+        // 5. index = origin/main, working tree untouched.
+        await git.raw(['read-tree', 'origin/main']);
+        // 6. Materialize only the tracked files MISSING on disk. Passing the explicit
+        //    missing set (never `checkout-index -a`) guarantees no existing local
+        //    file — a stub agents.yaml, a modified rule — is overwritten. Chunked to
+        //    stay under the argv limit on a cold box where most files are missing.
+        const tracked = (await git.raw(['ls-files', '-z'])).split('\0').filter(Boolean);
+        const missing = tracked.filter((rel) => !fs.existsSync(path.join(dir, rel)));
+        for (let i = 0; i < missing.length; i += 500) {
+            await git.raw(['checkout-index', '-f', '--', ...missing.slice(i, i + 500)]);
+        }
+        // 7. Reconcile a stale-stub top-level agents.yaml from origin/main. `restore`
+        //    is plumbing the git-guard allows; it rewrites only this one path.
+        let reconciledAgentsYaml = false;
+        let agentsYamlBackup;
+        if (tracked.includes('agents.yaml')) {
+            const abs = path.join(dir, 'agents.yaml');
+            const local = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf-8') : '';
+            const committed = await git.raw(['show', 'origin/main:agents.yaml']);
+            if (isStaleAgentsYamlStub(local, committed)) {
+                // The stub heuristic can't perfectly distinguish a partial-install stub
+                // from a user who deliberately removed a whole block, so save the local
+                // copy to gitignored runtime state BEFORE restoring — a false positive is
+                // then recoverable and surfaced, never silent data loss.
+                if (local) {
+                    agentsYamlBackup = path.join(dir, '.history', 'agents.yaml.pre-adopt.bak');
+                    fs.mkdirSync(path.dirname(agentsYamlBackup), { recursive: true });
+                    fs.writeFileSync(agentsYamlBackup, local);
+                }
+                await git.raw(['restore', '--source=origin/main', '--', 'agents.yaml']);
+                reconciledAgentsYaml = true;
+            }
+        }
+        // Surface — never silently keep — any tracked path whose local copy still
+        // differs from origin/main after the reconcile (real un-gitignored edits).
+        const dirty = (await git.raw(['status', '--porcelain', '--untracked-files=no']))
+            .split('\n')
+            .map((l) => l.slice(3).trim())
+            .filter(Boolean);
+        installGithooksSymlinks(dir);
+        recordUserRepoRemote(dir, trimmed);
+        const commit = (await git.raw(['rev-parse', '--short', 'HEAD'])).trim();
+        return {
+            success: true,
+            commit,
+            materialized: missing.length,
+            reconciledAgentsYaml,
+            ...(agentsYamlBackup ? { agentsYamlBackup } : {}),
+            localEdits: dirty,
+        };
+    }
+    catch (err) {
+        return { ...empty, error: err.message };
+    }
+}
+/**
+ * Self-heal entry point for the USER config repo: when `dir` is not a git repo
+ * (or is a repo with no `origin`), resolve its remote URL and adopt it in place;
+ * otherwise return null (nothing to adopt — the normal sync path runs). Returns a
+ * failed result carrying `needsUrl` when the URL cannot be resolved, so the
+ * caller can print the `agents repo pull user <git-url>` remediation instead of
+ * the old "Not a git repo" crash.
+ */
+export async function adoptUserRepoIfNeeded(dir, opts = {}) {
+    const hasOrigin = isGitRepo(dir) && readOriginUrl(dir) !== null;
+    if (hasOrigin)
+        return null;
+    const url = opts.explicitUrl?.trim() || resolveUserRepoRemoteUrl(dir);
+    if (!url) {
+        return {
+            success: false,
+            commit: '',
+            materialized: 0,
+            reconciledAgentsYaml: false,
+            localEdits: [],
+            needsUrl: true,
+            error: `${displayHomePath(dir)} is not a git repo and no remote URL is known.`,
+        };
+    }
+    return adoptRepoInPlace(dir, url);
+}
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/helper-download.d.ts

@@ -16,8 +16,18 @@
  * lands for both helpers at once.
  */
 import { type HelperName } from './helper-versions.js';
-/** GitHub repo whose `v<version>` releases carry the helper assets. */
-export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/**
+ * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
+ *
+ * This is the SLUG, which is not the npm package name: the package is still
+ * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
+ * slug kept working only because GitHub redirects a renamed repo, which is a
+ * poor thing to hang signed-binary delivery on — a redirect is one re-created
+ * repo away from resolving somewhere else. What actually protects the download
+ * is the sha256 + codesign + designated-requirement + Team ID verification
+ * below; this just stops relying on the redirect.
+ */
+export declare const HELPER_RELEASE_REPO = "phnx-labs/agi-cli";
 /** Apple Developer ID Team every helper must be signed by ("Developer ID
  *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
 export declare const EXPECTED_TEAM_ID = "2HTP252L87";

package/dist/lib/helper-download.js

@@ -23,8 +23,18 @@ import { pipeline } from 'node:stream/promises';
 import { getCacheDir } from './state.js';
 import { parseSha256Asset, sha256File } from './sha256-asset.js';
 import { helperTag } from './helper-versions.js';
-/** GitHub repo whose `v<version>` releases carry the helper assets. */
-export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/**
+ * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
+ *
+ * This is the SLUG, which is not the npm package name: the package is still
+ * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
+ * slug kept working only because GitHub redirects a renamed repo, which is a
+ * poor thing to hang signed-binary delivery on — a redirect is one re-created
+ * repo away from resolving somewhere else. What actually protects the download
+ * is the sha256 + codesign + designated-requirement + Team ID verification
+ * below; this just stops relying on the redirect.
+ */
+export const HELPER_RELEASE_REPO = 'phnx-labs/agi-cli';
 /** Apple Developer ID Team every helper must be signed by ("Developer ID
  *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
 export const EXPECTED_TEAM_ID = '2HTP252L87';

package/dist/lib/installations/migrate.js

@@ -298,7 +298,7 @@ function foldUserHooksYamlIntoAgentsYaml() {
     meta.hooks = merged;
     const header = `# agents-cli metadata
 # Auto-generated - do not edit manually
-# https://github.com/phnx-labs/agents-cli
+# https://github.com/phnx-labs/agi-cli
 
 `;
     try {
@@ -414,7 +414,7 @@ function foldBrowserProfilesIntoAgentsYaml() {
     meta.browser = merged;
     const header = `# agents-cli metadata
 # Auto-generated - do not edit manually
-# https://github.com/phnx-labs/agents-cli
+# https://github.com/phnx-labs/agi-cli
 
 `;
     try {
@@ -1641,7 +1641,7 @@ function migrateVersionResourcesToPatterns() {
         }
     }
     if (changed) {
-        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n';
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agi-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agi-cli/main/cli/schema/agents-yaml.schema.json\n\n';
         fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }
@@ -1668,7 +1668,7 @@ function migrateSplitDeviceLocalMeta() {
     const agents = meta.agents;
     const versions = meta.versions;
     const hasLocal = (!!agents && Object.keys(agents).length > 0) || (!!versions && Object.keys(versions).length > 0);
-    const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+    const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agi-cli\n\n';
     // Only rewrite central when it actually carries machine-local fields — a
     // machine whose agents.yaml is already portable-only is left untouched.
     if (hasLocal) {

package/dist/lib/menubar/install-menubar.d.ts

@@ -35,6 +35,26 @@ export declare const MENUBAR_HELPER_EXECUTABLE_NAME = "AGI Menu";
  * hermetic test fork's own teardown boots out the operator's live helper.
  */
 export declare function serviceLabel(): string;
+/**
+ * What the installed helper IS — deliberately not the CLI's version.
+ *
+ * `source` matters because the two install paths have different notions of
+ * "changed": a release bundle is identified by its helper version, while a local
+ * dev build has none (menubar/scripts/build.sh hardcodes CFBundleShortVersionString),
+ * so it is identified by the source path + mtime it was copied from.
+ */
+/** Version label for a bundle that has none of its own (a local dev build). */
+export declare const LOCAL_BUILD_LABEL = "local";
+export type MenubarStamp = {
+    source: 'release';
+    helperVersion: string;
+} | {
+    source: 'local';
+    sourceStamp: string;
+} | {
+    source: 'legacy';
+    raw: string;
+};
 /**
  * Absolute path to the installed menu-bar helper executable if it exists on
  * disk, else null. The desktop notifier (notify-desktop.ts) routes daemon
@@ -136,16 +156,50 @@ export declare function enableMenubarService(opts?: {
     clearOptOut?: boolean;
 }): Promise<boolean>;
 /**
- * Pure staleness decision (no I/O) so the truth table is unit-testable. The
- * installed service is stale when the helper binary is gone, or when it was
- * installed by a different CLI version than the one now running — a version
- * change is the signal that the plist's baked interpreter/entry/bundle paths
- * and the helper binary itself may have drifted. A null installedVersion
- * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ * Render a stamp as a comparable/displayable version string.
+ *
+ * A local build has no version of its own, so it reports `local`; the ownership
+ * contest treats that as "not comparable" and falls through to its owner arm,
+ * which is the correct outcome — a dev build must never win a version contest
+ * against a release.
+ */
+export declare function stampVersionLabel(stamp: MenubarStamp | null): string | null;
+/**
+ * Identify the bundle about to be installed, for the stamp.
+ *
+ * A bundle is a RELEASE iff it sits under the helper's own download cache —
+ * asked of `menubarHelperCacheDir`, not pattern-matched out of the path. A regex
+ * for `/v<x.y.z>/` gets this wrong in both directions: a checkout living under
+ * any directory that happens to contain a version-shaped segment reads as a
+ * release, and a release cache laid out differently reads as local. Either
+ * misclassification flips `source` between invocations, and a kind change is
+ * unconditionally stale — which is a reinstall loop.
+ */
+export declare function stampFor(resolvedSourceAppPath: string): MenubarStamp;
+/**
+ * The helper version a path denotes, iff it is inside that version's cache dir.
+ * Returns null for anything else — including a version-shaped path that is not
+ * actually the cache.
+ */
+export declare function releaseVersionOfCachedBundle(appPath: string, cacheDirFor?: (v: string) => string): string | null;
+/**
+ * Pure staleness decision (no I/O) so the truth table is unit-testable.
+ *
+ * This compares the HELPER axis, not the CLI's. It used to compare the installed
+ * stamp against `getCliVersion()`, which was wrong in both directions once the
+ * helpers gained their own version line: every CLI release made an unchanged
+ * helper look stale and reinstalled it (the #2109 restart storm), while a
+ * genuinely newer helper at the same CLI version never looked stale at all.
+ *
+ * Stale when: the executable is gone; nothing is stamped; the stamp predates the
+ * JSON format (`legacy` — re-stamped once); the install KIND changed
+ * (local <-> release), since a dev build and a release bundle are not
+ * interchangeable; a release install whose available helper version is newer;
+ * or a local install whose source path or mtime moved.
  */
 export declare function isMenubarStale(opts: {
-    installedVersion: string | null;
-    currentVersion: string;
+    installed: MenubarStamp | null;
+    available: MenubarStamp;
     execExists: boolean;
 }): boolean;
 /**
@@ -354,8 +408,12 @@ export interface MenubarStatus {
     platform: string;
     source: string | null;
     installedApp: string | null;
+    /** The installed HELPER's version — not the CLI's. `local` for a dev build. */
     installedVersion: string | null;
+    /** The helper version this install would put on disk right now. */
     currentVersion: string;
+    /** The CLI's own version, reported separately so the two are never conflated. */
+    cliVersion: string;
     stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
@@ -370,8 +428,13 @@ export declare function getMenubarStatus(): MenubarStatus;
 export interface MenubarDoctorReport {
     platform: string;
     installPath: string | null;
+    /** The installed HELPER's version — not the CLI's. `local` for a dev build. */
     installedVersion: string | null;
+    /** The helper version this install would put on disk right now. */
     currentVersion: string;
+    /** The CLI's own version, reported separately so the two are never conflated. */
+    cliVersion: string;
+    /** installed helper vs available helper. Never compares the CLI's version. */
     versionMatches: boolean;
     /** `unknown` on non-darwin or when nothing is installed to inspect. */
     signingIdentity: 'developer-id' | 'ad-hoc' | 'unknown';