@phnx-labs/agents-cli 1.22.60 → 1.22.61

package/dist/lib/github/gh-overload.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The delegate behind the `gh` PATH shim (`agents __gh --real-gh <path> -- <argv>`).
+ *
+ * Agents are statically trained to type `gh pr checks …`; the shim intercepts that
+ * habit and routes it here so the rate-limit-prone read runs over REST instead of
+ * GraphQL — no new command for an agent to remember. This is the Tier-1 scope:
+ * only `gh pr checks` is handled; every other invocation execs the real gh
+ * byte-for-byte (the shim already passes non-`pr checks` verbs straight to real gh,
+ * and this file passes through defensively for anything it cannot cleanly serve).
+ *
+ * Two switch modes (see the PHNX-3501 plan):
+ *   - `--watch` → EAGER REST: own the poll loop, re-anchored to the live head SHA
+ *     each tick, so a superseded run's red can never be reported (PHNX-3042).
+ *   - one-shot → LAZY: run real gh first; only translate to REST when it fails with
+ *     the exact GraphQL rate-limit signal. An over-budget GraphQL call is rejected
+ *     at 0 points, so this is nearly free and never reproduces gh's happy path.
+ *
+ * Fail-open is the rule: anything not cleanly resolvable (no PR number/URL, an
+ * unmappable request) execs real gh rather than returning wrong data.
+ */
+import { type RollupItem } from './rest.js';
+interface Parsed {
+    realGh: string;
+    ghArgs: string[];
+}
+/** Split `--real-gh <path> -- <gh argv>`; defaults realGh to bare `gh`. */
+export declare function parseDelegateArgs(argv: string[]): Parsed;
+export interface Target {
+    repo: string;
+    number: number;
+}
+/** owner/repo from a git remote URL, or null. */
+export declare function repoFromRemote(remoteUrl: string): string | null;
+/**
+ * Resolve `{repo, number}` from the `gh pr checks` argv + cwd, over git/REST only.
+ * Returns null (→ caller passes through to real gh) when it can't be resolved
+ * cleanly, e.g. no number and no open PR for the current branch.
+ */
+export declare function resolveTarget(ghArgs: string[], cwd: string, realGh: string): Promise<Target | null>;
+/** Render one rollup as `gh pr checks`-ish lines (or JSON when asked). */
+export declare function renderRollup(input: RollupItem[], json: boolean): string;
+/**
+ * True once CI has settled for this SHA.
+ *
+ * Check-suites only disambiguate an EMPTY rollup: no checks + no pending suites is
+ * "genuinely none" (settled); no checks + a pending suite is "not registered yet"
+ * (wait). Once real checks exist we decide on THEM alone and ignore suites — some
+ * App integrations (claude/cursor reviewers) register a suite that stays `queued`
+ * forever and never posts a run, exactly what `gh pr checks` also ignores.
+ */
+export declare function isSettled(rollup: RollupItem[], pendingSuites: number): boolean;
+/** Eager REST watch: poll to a terminal state, re-anchored to the live head SHA. */
+export declare function watchChecks(target: Target, json: boolean, realGh: string): Promise<number>;
+/** Lazy one-shot: real gh first; translate to REST only on the exact rate-limit signal. */
+export declare function checksOnce(target: Target | null, json: boolean, realGh: string, ghArgs: string[]): Promise<number>;
+/** Entry point for the `__gh` early branch in index.ts. */
+export declare function runGhOverload(argv: string[], cwd?: string): Promise<number>;
+export {};

package/dist/lib/github/gh-overload.js

@@ -0,0 +1,246 @@
+/**
+ * The delegate behind the `gh` PATH shim (`agents __gh --real-gh <path> -- <argv>`).
+ *
+ * Agents are statically trained to type `gh pr checks …`; the shim intercepts that
+ * habit and routes it here so the rate-limit-prone read runs over REST instead of
+ * GraphQL — no new command for an agent to remember. This is the Tier-1 scope:
+ * only `gh pr checks` is handled; every other invocation execs the real gh
+ * byte-for-byte (the shim already passes non-`pr checks` verbs straight to real gh,
+ * and this file passes through defensively for anything it cannot cleanly serve).
+ *
+ * Two switch modes (see the PHNX-3501 plan):
+ *   - `--watch` → EAGER REST: own the poll loop, re-anchored to the live head SHA
+ *     each tick, so a superseded run's red can never be reported (PHNX-3042).
+ *   - one-shot → LAZY: run real gh first; only translate to REST when it fails with
+ *     the exact GraphQL rate-limit signal. An over-budget GraphQL call is rejected
+ *     at 0 points, so this is nearly free and never reproduces gh's happy path.
+ *
+ * Fail-open is the rule: anything not cleanly resolvable (no PR number/URL, an
+ * unmappable request) execs real gh rather than returning wrong data.
+ */
+import { execFile, spawn } from 'child_process';
+import { promisify } from 'util';
+import { isCiGreen } from './pr-verdict.js';
+import { isRateLimitError, pendingCheckSuites, prHead, rollupForSha } from './rest.js';
+const execFileAsync = promisify(execFile);
+/** Split `--real-gh <path> -- <gh argv>`; defaults realGh to bare `gh`. */
+export function parseDelegateArgs(argv) {
+    let realGh = 'gh';
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--real-gh') {
+            realGh = argv[++i] ?? 'gh';
+        }
+        else if (argv[i] === '--') {
+            rest.push(...argv.slice(i + 1));
+            break;
+        }
+        else {
+            rest.push(argv[i]);
+        }
+    }
+    return { realGh, ghArgs: rest };
+}
+const PR_URL = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/;
+/** owner/repo from a git remote URL, or null. */
+export function repoFromRemote(remoteUrl) {
+    const m = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/);
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+/**
+ * Resolve `{repo, number}` from the `gh pr checks` argv + cwd, over git/REST only.
+ * Returns null (→ caller passes through to real gh) when it can't be resolved
+ * cleanly, e.g. no number and no open PR for the current branch.
+ */
+export async function resolveTarget(ghArgs, cwd, realGh) {
+    // `pr checks <n|url>` — the arg after "checks", if any.
+    const idx = ghArgs.indexOf('checks');
+    const arg = idx >= 0 ? ghArgs.slice(idx + 1).find((a) => !a.startsWith('-')) : undefined;
+    if (arg) {
+        const url = arg.match(PR_URL);
+        if (url)
+            return { repo: `${url[1]}/${url[2]}`, number: Number(url[3]) };
+        if (/^\d+$/.test(arg)) {
+            const repo = await repoFromCwd(cwd, ghArgs);
+            if (repo)
+                return { repo, number: Number(arg) };
+        }
+        return null;
+    }
+    // No number: resolve the open PR for the current branch over REST.
+    const repo = await repoFromCwd(cwd, ghArgs);
+    if (!repo)
+        return null;
+    try {
+        const branch = (await execFileAsync('git', ['-C', cwd, 'symbolic-ref', '--short', 'HEAD']))
+            .stdout.trim();
+        if (!branch)
+            return null;
+        const owner = repo.split('/')[0];
+        const out = await execFileAsync(realGh, [
+            'api', `repos/${repo}/pulls`, '--method', 'GET',
+            '-f', `head=${owner}:${branch}`, '-f', 'state=open',
+            '--jq', '.[0].number // empty',
+        ], { env: ghChildEnv() });
+        const n = out.stdout.trim();
+        return n ? { repo, number: Number(n) } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `--repo owner/name` on the argv wins; else derive from cwd's origin remote. */
+async function repoFromCwd(cwd, ghArgs) {
+    const ri = ghArgs.indexOf('--repo');
+    if (ri >= 0 && ghArgs[ri + 1])
+        return ghArgs[ri + 1];
+    try {
+        const out = await execFileAsync('git', ['-C', cwd, 'remote', 'get-url', 'origin']);
+        return repoFromRemote(out.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** Env for any real-gh child: mark the shim sentinel + strip color (FORCE_COLOR breaks JSON). */
+function ghChildEnv() {
+    const env = { ...process.env };
+    env.AGENTS_GH_SHIM = '1';
+    env.GH_NO_COLOR = '1';
+    env.GH_PAGER = 'cat';
+    env.NO_COLOR = '1';
+    delete env.FORCE_COLOR;
+    delete env.CLICOLOR_FORCE;
+    return env;
+}
+/** A REST GhExec bound to the real gh + sentinel env, so it never re-enters the shim. */
+function restExec(realGh) {
+    return async (args) => {
+        const { stdout } = await execFileAsync(realGh, args, {
+            env: ghChildEnv(),
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return String(stdout ?? '');
+    };
+}
+/** Passthrough: exec real gh inheriting stdio, resolve its exit code. */
+function passthrough(realGh, ghArgs) {
+    return new Promise((resolve) => {
+        const child = spawn(realGh, ghArgs, { stdio: 'inherit', env: ghChildEnv() });
+        child.on('close', (code) => resolve(code ?? 0));
+        child.on('error', () => resolve(127));
+    });
+}
+/** Render one rollup as `gh pr checks`-ish lines (or JSON when asked). */
+export function renderRollup(input, json) {
+    // Sort by name so identical states render identically across polls — otherwise
+    // non-deterministic REST/Map order defeats the watch's change-detection dedup.
+    const rollup = [...input].sort((a, b) => a.name.localeCompare(b.name));
+    if (json) {
+        return JSON.stringify(rollup.map((c) => ({
+            name: c.name,
+            state: (c.conclusion || c.state || c.status || '').toLowerCase() || 'pending',
+            link: c.link ?? '',
+        })));
+    }
+    return rollup
+        .map((c) => {
+        const s = (c.conclusion || c.state || c.status || 'PENDING').toUpperCase();
+        const mark = s === 'SUCCESS' ? '✓' : s === 'SKIPPED' || s === 'NEUTRAL' ? '-' : s === 'FAILURE' || s === 'CANCELLED' || s === 'TIMED_OUT' || s === 'ACTION_REQUIRED' ? '✗' : '*';
+        return `${mark} ${c.name}\t${s}${c.link ? `\t${c.link}` : ''}`;
+    })
+        .join('\n');
+}
+const NON_TERMINAL = new Set(['IN_PROGRESS', 'QUEUED', 'PENDING', 'WAITING', 'REQUESTED']);
+/**
+ * True once CI has settled for this SHA.
+ *
+ * Check-suites only disambiguate an EMPTY rollup: no checks + no pending suites is
+ * "genuinely none" (settled); no checks + a pending suite is "not registered yet"
+ * (wait). Once real checks exist we decide on THEM alone and ignore suites — some
+ * App integrations (claude/cursor reviewers) register a suite that stays `queued`
+ * forever and never posts a run, exactly what `gh pr checks` also ignores.
+ */
+export function isSettled(rollup, pendingSuites) {
+    if (rollup.length === 0)
+        return pendingSuites === 0;
+    return rollup.every((c) => !NON_TERMINAL.has((c.conclusion || c.state || c.status || '').toUpperCase()));
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Eager REST watch: poll to a terminal state, re-anchored to the live head SHA. */
+export async function watchChecks(target, json, realGh) {
+    const gh = restExec(realGh);
+    const deadline = Date.now() + 30 * 60_000; // 30-min guard against a hung matrix
+    let last = '';
+    for (;;) {
+        const head = await prHead(target.repo, target.number, gh); // re-anchor each tick
+        const [rollup, pending] = await Promise.all([
+            rollupForSha(target.repo, head.sha, gh),
+            pendingCheckSuites(target.repo, head.sha, gh),
+        ]);
+        const view = renderRollup(rollup, json);
+        if (view && view !== last && !json) {
+            process.stdout.write(view + '\n');
+            last = view;
+        }
+        if (isSettled(rollup, pending)) {
+            if (json)
+                process.stdout.write(view + '\n');
+            const green = isCiGreen(rollup);
+            if (rollup.length === 0) {
+                process.stderr.write('no checks reported on the head commit\n');
+                return 0;
+            }
+            return green ? 0 : 1;
+        }
+        if (Date.now() > deadline) {
+            process.stderr.write('gh(REST): watch timed out after 30m\n');
+            return 1;
+        }
+        await sleep(10_000);
+    }
+}
+/** Lazy one-shot: real gh first; translate to REST only on the exact rate-limit signal. */
+export async function checksOnce(target, json, realGh, ghArgs) {
+    // Try real gh, capturing output so we can detect the rate-limit signal.
+    try {
+        const { stdout } = await execFileAsync(realGh, ghArgs, { env: ghChildEnv(), maxBuffer: 16 * 1024 * 1024 });
+        process.stdout.write(stdout);
+        return 0;
+    }
+    catch (err) {
+        const e = err;
+        if (!isRateLimitError(String(e.stderr ?? ''))) {
+            // A real failure (checks failing, bad flag). Pass gh's own output/exit through.
+            if (e.stdout)
+                process.stdout.write(e.stdout);
+            if (e.stderr)
+                process.stderr.write(e.stderr);
+            return typeof e.code === 'number' ? e.code : 1;
+        }
+    }
+    // Rate-limited: serve from REST if we can resolve the PR, else re-raise real gh.
+    if (!target)
+        return passthrough(realGh, ghArgs);
+    const gh = restExec(realGh);
+    const head = await prHead(target.repo, target.number, gh);
+    const rollup = await rollupForSha(target.repo, head.sha, gh);
+    process.stdout.write(renderRollup(rollup, json) + '\n');
+    return isCiGreen(rollup) ? 0 : 1;
+}
+/** Entry point for the `__gh` early branch in index.ts. */
+export async function runGhOverload(argv, cwd = process.cwd()) {
+    const { realGh, ghArgs } = parseDelegateArgs(argv);
+    // Only `pr checks` is Tier-1. Anything else → real gh, untouched.
+    if (ghArgs[0] !== 'pr' || ghArgs[1] !== 'checks')
+        return passthrough(realGh, ghArgs);
+    const json = ghArgs.includes('--json');
+    const watch = ghArgs.includes('--watch');
+    const target = await resolveTarget(ghArgs, cwd, realGh);
+    if (watch) {
+        if (!target)
+            return passthrough(realGh, ghArgs); // can't resolve → let real gh try
+        return watchChecks(target, json, realGh);
+    }
+    return checksOnce(target, json, realGh, ghArgs);
+}

package/dist/lib/github/rest.d.ts

@@ -0,0 +1,64 @@
+/**
+ * REST-backed reads for PR CI state — the engine behind the `gh` overload shim.
+ *
+ * The problem this exists for: the whole fleet shares one GitHub token, and the
+ * merge loop's `gh pr checks/view/list` are all **GraphQL**-backed. GraphQL is
+ * metered on a 5000-POINT/hr budget separate from REST core (5000 req/hr), so the
+ * fleet drains GraphQL while REST core sits idle, and every agent's CI watch dies
+ * with `GraphQL: API rate limit already exceeded`. These functions answer the same
+ * questions over REST, which is the budget nobody is using.
+ *
+ * They also fix PHNX-3042 (a superseded run's red reported as the current verdict):
+ * `commits/{sha}/check-runs` returns ONLY runs for that exact SHA, so anchoring on
+ * the PR's live head SHA can never surface a stale run from a superseded commit —
+ * the head-exact property `gh pr checks`'s denormalized GraphQL rollup lacks.
+ *
+ * `gh api …` here draws REST core, and reuses {@link ghExec}'s hardened env
+ * (`ghEnv` strips FORCE_COLOR / pins GH_NO_COLOR — this fleet exports FORCE_COLOR
+ * and gh otherwise paints the JSON payload and JSON.parse dies).
+ */
+import { type GhExec } from './pr-mergeable.js';
+import type { StatusCheck } from './pr-verdict.js';
+/** A rollup item shaped like `gh pr checks --json`, built from REST. */
+export interface RollupItem extends StatusCheck {
+    /** Check name / status context. */
+    name: string;
+    /** html_url (check-run) or target_url (legacy status); may be empty. */
+    link?: string;
+}
+/** PR head identity — the SHA every check query must anchor to. */
+export interface PrHead {
+    number: number;
+    sha: string;
+}
+/**
+ * Resolve a PR's current head SHA over REST (`GET repos/{repo}/pulls/{n}`).
+ *
+ * This is the anchor for every check query: pinning to the live head SHA is what
+ * makes the watch immune to a superseded run's verdict (PHNX-3042). Throws if the
+ * PR has no head SHA (deleted / not found) rather than returning a wrong empty.
+ */
+export declare function prHead(repo: string, number: number, gh?: GhExec): Promise<PrHead>;
+/**
+ * The status-check rollup for ONE commit SHA, over REST — the union of the two
+ * GitHub subsystems `gh pr checks`'s GraphQL rollup merges for you:
+ *
+ *   - `GET commits/{sha}/check-runs` — GitHub Actions + check-run apps (paginated).
+ *   - `GET commits/{sha}/status`     — legacy commit statuses (external CI).
+ *
+ * Deduped by name; a check-run wins over a legacy status of the same context.
+ * Fields are ASCII-upper-cased to match {@link StatusCheck}, which
+ * {@link isCiGreen} reads as `conclusion || state || status`.
+ */
+export declare function rollupForSha(repo: string, sha: string, gh?: GhExec): Promise<RollupItem[]>;
+/**
+ * How many check-suites are still queued/in_progress for a SHA.
+ *
+ * Disambiguates the empty rollup: a suite that is `queued`/`in_progress` with no
+ * runs yet means "checks are coming, not registered" (keep polling), NOT "this PR
+ * has no checks" (terminal). Without this, a `--watch` on a freshly-pushed SHA
+ * would read an empty rollup as green before CI registers.
+ */
+export declare function pendingCheckSuites(repo: string, sha: string, gh?: GhExec): Promise<number>;
+/** True when gh stderr is the rate-limit outcome the shim should switch to REST on. */
+export declare function isRateLimitError(stderr: string): boolean;

package/dist/lib/github/rest.js

@@ -0,0 +1,111 @@
+/**
+ * REST-backed reads for PR CI state — the engine behind the `gh` overload shim.
+ *
+ * The problem this exists for: the whole fleet shares one GitHub token, and the
+ * merge loop's `gh pr checks/view/list` are all **GraphQL**-backed. GraphQL is
+ * metered on a 5000-POINT/hr budget separate from REST core (5000 req/hr), so the
+ * fleet drains GraphQL while REST core sits idle, and every agent's CI watch dies
+ * with `GraphQL: API rate limit already exceeded`. These functions answer the same
+ * questions over REST, which is the budget nobody is using.
+ *
+ * They also fix PHNX-3042 (a superseded run's red reported as the current verdict):
+ * `commits/{sha}/check-runs` returns ONLY runs for that exact SHA, so anchoring on
+ * the PR's live head SHA can never surface a stale run from a superseded commit —
+ * the head-exact property `gh pr checks`'s denormalized GraphQL rollup lacks.
+ *
+ * `gh api …` here draws REST core, and reuses {@link ghExec}'s hardened env
+ * (`ghEnv` strips FORCE_COLOR / pins GH_NO_COLOR — this fleet exports FORCE_COLOR
+ * and gh otherwise paints the JSON payload and JSON.parse dies).
+ */
+import { ghExec } from './pr-mergeable.js';
+/** Parse newline-delimited JSON (gh `--jq` streams one object per line/page). */
+function parseNdjson(out) {
+    const rows = [];
+    for (const line of out.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        rows.push(JSON.parse(t));
+    }
+    return rows;
+}
+/**
+ * Resolve a PR's current head SHA over REST (`GET repos/{repo}/pulls/{n}`).
+ *
+ * This is the anchor for every check query: pinning to the live head SHA is what
+ * makes the watch immune to a superseded run's verdict (PHNX-3042). Throws if the
+ * PR has no head SHA (deleted / not found) rather than returning a wrong empty.
+ */
+export async function prHead(repo, number, gh = ghExec) {
+    const sha = (await gh(['api', `repos/${repo}/pulls/${number}`, '--jq', '.head.sha'])).trim();
+    if (!sha)
+        throw new Error(`no head SHA for ${repo}#${number}`);
+    return { number, sha };
+}
+/**
+ * The status-check rollup for ONE commit SHA, over REST — the union of the two
+ * GitHub subsystems `gh pr checks`'s GraphQL rollup merges for you:
+ *
+ *   - `GET commits/{sha}/check-runs` — GitHub Actions + check-run apps (paginated).
+ *   - `GET commits/{sha}/status`     — legacy commit statuses (external CI).
+ *
+ * Deduped by name; a check-run wins over a legacy status of the same context.
+ * Fields are ASCII-upper-cased to match {@link StatusCheck}, which
+ * {@link isCiGreen} reads as `conclusion || state || status`.
+ */
+export async function rollupForSha(repo, sha, gh = ghExec) {
+    const [runsRaw, statusRaw] = await Promise.all([
+        gh([
+            'api', `repos/${repo}/commits/${sha}/check-runs`, '--paginate',
+            '--jq',
+            '.check_runs[] | {name: .name, status: (.status // "" | ascii_upcase), ' +
+                'conclusion: (.conclusion // "" | ascii_upcase), link: (.html_url // "")}',
+        ]),
+        gh([
+            'api', `repos/${repo}/commits/${sha}/status`,
+            '--jq',
+            '.statuses[] | {name: .context, state: (.state // "" | ascii_upcase), ' +
+                'link: (.target_url // "")}',
+        ]),
+    ]);
+    const byName = new Map();
+    // Legacy statuses first; check-runs override on a name collision.
+    for (const s of parseNdjson(statusRaw)) {
+        byName.set(String(s.name), { name: String(s.name), state: str(s.state), link: str(s.link) });
+    }
+    for (const r of parseNdjson(runsRaw)) {
+        byName.set(String(r.name), {
+            name: String(r.name),
+            status: str(r.status),
+            conclusion: str(r.conclusion),
+            link: str(r.link),
+        });
+    }
+    return [...byName.values()];
+}
+/**
+ * How many check-suites are still queued/in_progress for a SHA.
+ *
+ * Disambiguates the empty rollup: a suite that is `queued`/`in_progress` with no
+ * runs yet means "checks are coming, not registered" (keep polling), NOT "this PR
+ * has no checks" (terminal). Without this, a `--watch` on a freshly-pushed SHA
+ * would read an empty rollup as green before CI registers.
+ */
+export async function pendingCheckSuites(repo, sha, gh = ghExec) {
+    const out = await gh([
+        'api', `repos/${repo}/commits/${sha}/check-suites`,
+        '--jq',
+        '[.check_suites[] | select(.status == "queued" or .status == "in_progress")] | length',
+    ]);
+    const n = Number.parseInt(out.trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/** The exact GitHub GraphQL primary rate-limit signal (never the bare noun). */
+const RATE_LIMIT_SIGNAL = /GraphQL: API rate limit (?:already )?exceeded|You have exceeded a secondary rate limit/i;
+/** True when gh stderr is the rate-limit outcome the shim should switch to REST on. */
+export function isRateLimitError(stderr) {
+    return RATE_LIMIT_SIGNAL.test(stderr);
+}
+function str(v) {
+    return v === undefined || v === null || v === '' ? undefined : String(v);
+}

package/dist/lib/harness-connection-test.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pre-save connection test for a custom harness (PHNX-2221).
+ *
+ * A harness binds a (host CLI + model + endpoint + auth) — but none of that is
+ * exercised until the first real run, so a typo in the base URL, a wrong account,
+ * or a model id the endpoint doesn't serve only surfaces later. This module runs
+ * a genuine minimal request through the SAME resolution path a real run takes —
+ * `agents run <name> "say alive in one word" --headless --timeout 60s`, which
+ * flows `resolveProfileForRun` → `resolveProfileEnv` (keychain/account read) →
+ * `buildExecEnv` → spawn — and classifies the result so the user learns it works
+ * (or exactly why it doesn't) before committing the harness.
+ *
+ * There is no mock or dry-run: the profile must already be on disk (the caller
+ * writes it first) because the test drives the real `agents run` argv. The
+ * classifier is a pure function over the child's exit code + combined output, so
+ * it is unit-tested against real stderr samples with no spawn.
+ */
+/** Why a connection test failed, when it did. `undefined` reason ⇒ it passed. */
+export type ConnectionTestReason = 'auth' | 'endpoint' | 'model' | 'unknown';
+/** Outcome of a harness connection test. */
+export interface ConnectionTestResult {
+    ok: boolean;
+    /** Machine-readable failure class; absent on success. */
+    reason?: ConnectionTestReason;
+    /** One-line human summary (the classified cause, or a success note). */
+    message?: string;
+}
+/** The prompt the smoke test sends — cheap, deterministic, one token of output. */
+export declare const CONNECTION_TEST_PROMPT = "say alive in one word";
+/**
+ * Classify a finished `agents run` smoke test from its exit code and combined
+ * stdout+stderr. Pure — no spawn — so the mapping (pass / auth / endpoint /
+ * model / unknown) is unit-tested against real provider error strings.
+ *
+ * Exit 0 is a pass. Otherwise the output is matched against provider-error
+ * shapes in priority order: an auth rejection (401 / invalid key) is the most
+ * specific, then a model-not-served error, then a transport/DNS failure; a
+ * failure that matches none is `unknown` (the run failed but not in a way we can
+ * name — surfaced verbatim, never swallowed).
+ */
+export declare function classifyConnectionOutput(exitCode: number | null, output: string): ConnectionTestResult;
+/** Options for {@link runHarnessConnectionTest}. */
+export interface ConnectionTestOptions {
+    /** Agent-side timeout passed to `agents run --timeout`. Default `60s`. */
+    timeout?: string;
+    /** Hard wall-clock cap (ms) on the child, above the agent timeout. Default 90s. */
+    killAfterMs?: number;
+}
+/**
+ * Run the real connection test against an already-saved harness. Spawns the CLI
+ * itself (`getCliLaunch`, the one self-invocation primitive) with the same argv a
+ * user would type, and classifies the result. Never throws on a failed run — a
+ * failure is returned as a classified {@link ConnectionTestResult}; only a spawn
+ * that never produced an exit (killed by the wall-clock cap) reads as `endpoint`
+ * (the request hung).
+ */
+export declare function runHarnessConnectionTest(name: string, opts?: ConnectionTestOptions): Promise<ConnectionTestResult>;

package/dist/lib/harness-connection-test.js

@@ -0,0 +1,80 @@
+/**
+ * Pre-save connection test for a custom harness (PHNX-2221).
+ *
+ * A harness binds a (host CLI + model + endpoint + auth) — but none of that is
+ * exercised until the first real run, so a typo in the base URL, a wrong account,
+ * or a model id the endpoint doesn't serve only surfaces later. This module runs
+ * a genuine minimal request through the SAME resolution path a real run takes —
+ * `agents run <name> "say alive in one word" --headless --timeout 60s`, which
+ * flows `resolveProfileForRun` → `resolveProfileEnv` (keychain/account read) →
+ * `buildExecEnv` → spawn — and classifies the result so the user learns it works
+ * (or exactly why it doesn't) before committing the harness.
+ *
+ * There is no mock or dry-run: the profile must already be on disk (the caller
+ * writes it first) because the test drives the real `agents run` argv. The
+ * classifier is a pure function over the child's exit code + combined output, so
+ * it is unit-tested against real stderr samples with no spawn.
+ */
+import { spawnSync } from 'node:child_process';
+import { getCliLaunch } from './cli-entry.js';
+/** The prompt the smoke test sends — cheap, deterministic, one token of output. */
+export const CONNECTION_TEST_PROMPT = 'say alive in one word';
+/**
+ * Classify a finished `agents run` smoke test from its exit code and combined
+ * stdout+stderr. Pure — no spawn — so the mapping (pass / auth / endpoint /
+ * model / unknown) is unit-tested against real provider error strings.
+ *
+ * Exit 0 is a pass. Otherwise the output is matched against provider-error
+ * shapes in priority order: an auth rejection (401 / invalid key) is the most
+ * specific, then a model-not-served error, then a transport/DNS failure; a
+ * failure that matches none is `unknown` (the run failed but not in a way we can
+ * name — surfaced verbatim, never swallowed).
+ */
+export function classifyConnectionOutput(exitCode, output) {
+    if (exitCode === 0)
+        return { ok: true, message: 'Connection test passed.' };
+    const text = output || '';
+    const firstLine = text.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    const detail = firstLine ? ` (${firstLine})` : '';
+    if (/\b401\b|unauthor|invalid[\s_-]?(x-)?api[\s_-]?key|authentication|invalid x-api-key|missing[\s_-]?api[\s_-]?key/i.test(text)) {
+        return { ok: false, reason: 'auth', message: `Authentication rejected — check the harness's account/key.${detail}` };
+    }
+    if (/model[^\n]{0,48}(not\s+found|not\s+exist|does\s+not\s+exist|unknown|invalid|unsupported|unavailable)|no\s+such\s+model|unknown\s+model|invalid\s+model|unrecognized\s+model/i.test(text)) {
+        return { ok: false, reason: 'model', message: `The endpoint did not accept that model id.${detail}` };
+    }
+    if (/ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH|getaddrinfo|connection\s+refused|could\s+not\s+connect|unreachable|fetch\s+failed|socket\s+hang\s+up|network\s+error|dns|certificate|self[\s-]?signed/i.test(text)) {
+        return { ok: false, reason: 'endpoint', message: `The endpoint was unreachable — check the base URL.${detail}` };
+    }
+    return { ok: false, reason: 'unknown', message: `Run failed (exit ${exitCode ?? 'null'}).${detail}` };
+}
+/**
+ * Run the real connection test against an already-saved harness. Spawns the CLI
+ * itself (`getCliLaunch`, the one self-invocation primitive) with the same argv a
+ * user would type, and classifies the result. Never throws on a failed run — a
+ * failure is returned as a classified {@link ConnectionTestResult}; only a spawn
+ * that never produced an exit (killed by the wall-clock cap) reads as `endpoint`
+ * (the request hung).
+ */
+export async function runHarnessConnectionTest(name, opts = {}) {
+    const { command, args } = getCliLaunch([
+        'run',
+        name,
+        CONNECTION_TEST_PROMPT,
+        '--headless',
+        '--timeout',
+        opts.timeout ?? '60s',
+    ]);
+    const result = spawnSync(command, args, {
+        encoding: 'utf-8',
+        timeout: opts.killAfterMs ?? 90_000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.error && result.error.code === 'ETIMEDOUT') {
+        return { ok: false, reason: 'endpoint', message: 'The request hung past the timeout — the endpoint may be unreachable or wrong.' };
+    }
+    if (result.error) {
+        return { ok: false, reason: 'unknown', message: `Could not launch the test: ${result.error.message}` };
+    }
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+    return classifyConnectionOutput(result.status, output);
+}

package/dist/lib/heal.js

@@ -43,6 +43,7 @@ const KIND_TO_SELECTION = {
     permissions: 'permissions',
     subagents: 'subagents',
     plugins: 'plugins',
+    workflows: 'workflows',
 };
 function totalHealed(r) {
     return r.versions.reduce((n, v) => n + v.healed.length, 0);
@@ -173,9 +174,13 @@ function healVersion(agent, version, opts) {
                 result.skipped.push({ kind: row.kind, name: row.name, reason: 'drift' });
                 continue;
             }
-            if (row.kind === 'promptcuts')
-                continue; // not version-synced
-            if (row.kind === 'rules') {
+            // Rules (the composed instruction file) and knowledge memory (~/.agents/
+            // memory/ facts) are both repaired by a sync of this version: rules via the
+            // preset re-composition `selection.memory` drives, knowledge facts via the
+            // unconditional `syncMemoryToVersionHome` fan-out every sync runs. Setting
+            // the rules selection guarantees a sync executes, so a memory-fact drift is
+            // reconciled the same pass (PHNX-3504).
+            if (row.kind === 'rules' || row.kind === 'memory') {
                 selection.memory = 'all';
                 attempted.push({ kind: row.kind, name: row.name, was: row.status });
                 continue;