@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/self_repair_cli.ts

@@ -12,9 +12,14 @@
  * instruction lifts that floor. Running this command IS the user's word.
  *
  * Route selection follows the spec exactly: a pull request when the fix can be
- * authored and pushed, an issue when it cannot, and a local record when nothing
- * can leave the machine. `--dry-run` prints the resolved route and the rendered
- * body and touches no network — that is the path the tests drive.
+ * authored and pushed — directly when the pre-flight probe shows upstream push
+ * rights, via fork → cross-repo PR when it does not — an issue when it cannot,
+ * and a local record when nothing can leave the machine. Once publishing was
+ * authorized, failures degrade down the ladder WITHIN the same call (push/PR
+ * failure or 30 s timeout → issue; issue failure → the record stays open with
+ * the errors attached) — degrading never widens what leaves the machine, only
+ * the vehicle. `--dry-run` prints the resolved route and the rendered body and
+ * touches no network — that is the path the tests drive.
  *
  * Fail-closed on privacy: the record's own text goes through the audited
  * privacy floor before anything leaves the machine, and a refusal downgrades
@@ -26,17 +31,34 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
-    chooseEgressRoute,
+    chooseEgress,
     type DefectRecord,
     type EgressCapability,
+    type EgressChoice,
     type EgressRoute,
     egressBlockedReason,
+    patchDeniedReason,
+    type PushVia,
     renderReport,
+    sanitizeEvidence,
 } from './_lib/self_repair.js';
-import { listRecords, markReleased, openRecords, readRecord } from './_lib/self_repair_store.js';
+import { buildSettingsClassIndex, parseSettingsClassRows } from '../shared/settingsClasses.js';
+import {
+    attachReleaseErrors,
+    listRecords,
+    markReleased,
+    openRecords,
+    readRecord,
+} from './_lib/self_repair_store.js';
 
 export const UPSTREAM_REPO = 'event4u-app/agent-config';
 
+/**
+ * Per-step ceiling for every network-touching egress step. A hung `git push`
+ * or `gh` call degrades down the ladder instead of hanging the release.
+ */
+export const EGRESS_STEP_TIMEOUT_MS = 30_000;
+
 const EXIT_OK = 0;
 const EXIT_FAIL = 1;
 
@@ -44,12 +66,30 @@ const EXIT_FAIL = 1;
 export interface Probe {
     agentConfigCheckout: string | null;
     ghAuthenticated: boolean;
-    canPush: boolean;
+    canPushUpstream: boolean;
+    canFork: boolean;
 }
 
-function run(cmd: string, args: string[], cwd?: string): { ok: boolean; out: string } {
-    const r = spawnSync(cmd, args, { cwd, encoding: 'utf-8' });
-    return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+export interface RunResult {
+    ok: boolean;
+    out: string;
+    timedOut: boolean;
+}
+
+/** Injectable command runner — tests script it, production shells out. */
+export type Runner = (cmd: string, args: string[], cwd?: string) => RunResult;
+
+function run(cmd: string, args: string[], cwd?: string): RunResult {
+    const r = spawnSync(cmd, args, { cwd, encoding: 'utf-8', timeout: EGRESS_STEP_TIMEOUT_MS });
+    // Only spawnSync's own ETIMEDOUT counts: a child killed externally by
+    // SIGTERM is a failure, not a timeout, and recording it as "timed out"
+    // points the next debugging session at the wrong cause (R2 finding #3).
+    const timedOut = (r.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT';
+    return {
+        ok: r.status === 0 && !timedOut,
+        out: `${r.stdout ?? ''}${r.stderr ?? ''}`,
+        timedOut,
+    };
 }
 
 /**
@@ -71,18 +111,63 @@ export function findAgentConfigCheckout(env: NodeJS.ProcessEnv, cwd: string): st
     return null;
 }
 
-export function probeMachine(env: NodeJS.ProcessEnv, cwd: string): Probe {
+/**
+ * Pre-flight probe of ACTUAL push rights, not remote existence. `git remote`
+ * returning a name proves only that the repo was cloned — every consumer of
+ * the public repo has that and no write access. `gh api repos/<repo>` returns
+ * the authenticated viewer's `permissions.push` and the repo's `allow_forking`,
+ * which are the two facts the route actually depends on. An unreachable or
+ * unauthenticated API answers `false` for both — the ladder then degrades to
+ * an issue rather than failing at push time.
+ */
+export function probeUpstreamRights(
+    runner: Runner,
+    repo: string,
+): { canPushUpstream: boolean; canFork: boolean } {
+    const r = runner('gh', ['api', `repos/${repo}`]);
+    if (!r.ok) {
+        return { canPushUpstream: false, canFork: false };
+    }
+    try {
+        const parsed: unknown = JSON.parse(r.out);
+        const meta = parsed as {
+            permissions?: { push?: boolean };
+            allow_forking?: boolean;
+        };
+        return {
+            canPushUpstream: meta.permissions?.push === true,
+            canFork: meta.allow_forking !== false,
+        };
+    } catch {
+        return { canPushUpstream: false, canFork: false };
+    }
+}
+
+export function probeMachine(
+    env: NodeJS.ProcessEnv,
+    cwd: string,
+    runner: Runner = run,
+    repo: string = UPSTREAM_REPO,
+): Probe {
     const checkout = findAgentConfigCheckout(env, cwd);
-    const gh = run('gh', ['auth', 'status']);
-    const canPush = checkout !== null && run('git', ['remote'], checkout).out.trim().length > 0;
-    return { agentConfigCheckout: checkout, ghAuthenticated: gh.ok, canPush };
+    const gh = runner('gh', ['auth', 'status']);
+    const rights = gh.ok
+        ? probeUpstreamRights(runner, repo)
+        : { canPushUpstream: false, canFork: false };
+    return {
+        agentConfigCheckout: checkout,
+        ghAuthenticated: gh.ok,
+        canPushUpstream: rights.canPushUpstream,
+        canFork: gh.ok && rights.canFork,
+    };
 }
 
 export function capabilityOf(probe: Probe): EgressCapability {
     return {
         hasAgentConfigCheckout: probe.agentConfigCheckout !== null,
         ghAuthenticated: probe.ghAuthenticated,
-        canPush: probe.canPush,
+        canPushUpstream: probe.canPushUpstream,
+        canFork: probe.canFork,
     };
 }
 
@@ -93,17 +178,226 @@ export function titleFor(record: DefectRecord): string {
 
 export interface ReleasePlan {
     route: EgressRoute;
+    pushVia: PushVia | null;
     blocked: string | null;
+    /**
+     * Non-null when the record targets a may-not-modify surface (kernel rules,
+     * safety floors, settings class C, CI enforcement, self-repair's own
+     * policy/code): the patch/PR path is refused with this reason and the
+     * route degrades to report-only. Detection and the issue path stay open.
+     */
+    patch_denied: string | null;
     title: string;
     body: string;
 }
 
+/**
+ * Class-C settings keys from the contract in the agent-config checkout, for
+ * the deny-list's dynamic key match. `null` when there is no checkout or the
+ * contract is unreadable — the deny-list's static path matches still apply.
+ */
+export function readClassCKeys(checkout: string | null): ReadonlySet<string> | null {
+    if (checkout === null) {
+        return null;
+    }
+    try {
+        const md = fs.readFileSync(
+            path.join(checkout, 'docs', 'contracts', 'settings-classes.md'),
+            'utf-8',
+        );
+        const index = buildSettingsClassIndex(parseSettingsClassRows(md));
+        return new Set([...index].filter(([, cls]) => cls === 'C').map(([key]) => key));
+    } catch {
+        return null;
+    }
+}
+
 /** Pure: everything `release` decides before it touches the network. */
-export function planRelease(record: DefectRecord, probe: Probe, repoRoot: string): ReleasePlan {
+export function planRelease(
+    record: DefectRecord,
+    probe: Probe,
+    repoRoot: string,
+    opts?: { classCKeys?: ReadonlySet<string> | null },
+): ReleasePlan {
     const blocked = egressBlockedReason(record, repoRoot);
-    const route: EgressRoute =
-        blocked !== null ? 'local-only' : chooseEgressRoute(capabilityOf(probe));
-    return { route, blocked, title: titleFor(record), body: renderReport(record, route) };
+    const patch_denied = blocked === null ? patchDeniedReason(record, opts) : null;
+    let choice: EgressChoice =
+        blocked !== null
+            ? { route: 'local-only' as const, pushVia: null }
+            : chooseEgress(capabilityOf(probe));
+    if (patch_denied !== null && choice.route === 'pull-request') {
+        // chooseEgress only returns pull-request when gh is authenticated, so
+        // report-only degrades to an issue, never to a dropped record.
+        choice = { route: 'issue', pushVia: null };
+    }
+    return {
+        route: choice.route,
+        pushVia: choice.pushVia,
+        blocked,
+        patch_denied,
+        title: titleFor(record),
+        body: renderReport(record, choice.route),
+    };
+}
+
+// ── egress ladder execution ────────────────────────────────────────
+
+/** One egress step's outcome — kept for the record when the ladder exhausts. */
+export interface EgressAttempt {
+    step: string;
+    ok: boolean;
+    detail: string;
+}
+
+export interface ReleaseOutcome {
+    /** What actually got published, or null when the whole ladder failed. */
+    published: 'pull-request' | 'issue' | null;
+    attempts: EgressAttempt[];
+}
+
+export interface ReleaseDeps {
+    runner: Runner;
+    now: () => string;
+}
+
+const FORK_REMOTE = 'self-repair-fork';
+
+function failDetail(step: string, r: RunResult): string {
+    return r.timedOut
+        ? `${step}: timed out after ${EGRESS_STEP_TIMEOUT_MS / 1000}s`
+        : `${step}: ${r.out.trim() || 'failed'}`;
+}
+
+/**
+ * Push the fix branch — directly, or via fork → cross-repo PR — then open the
+ * PR. Returns null on success; on any step failure or timeout returns the
+ * failed attempt so the caller degrades down the ladder.
+ */
+function tryPullRequest(
+    plan: ReleasePlan,
+    probe: Probe,
+    repo: string,
+    branch: string,
+    via: PushVia,
+    deps: ReleaseDeps,
+): EgressAttempt | null {
+    const checkout = probe.agentConfigCheckout!;
+    let prHead: string | null = null;
+
+    if (via === 'upstream') {
+        const pushed = deps.runner('git', ['push', '-u', 'origin', branch], checkout);
+        if (!pushed.ok) {
+            return { step: 'push-upstream', ok: false, detail: failDetail('push-upstream', pushed) };
+        }
+    } else {
+        const forked = deps.runner('gh', ['repo', 'fork', repo, '--clone=false']);
+        if (!forked.ok) {
+            return { step: 'fork-ensure', ok: false, detail: failDetail('fork-ensure', forked) };
+        }
+        const who = deps.runner('gh', ['api', 'user', '--jq', '.login']);
+        if (!who.ok || who.out.trim().length === 0) {
+            return { step: 'whoami', ok: false, detail: failDetail('whoami', who) };
+        }
+        const login = who.out.trim();
+        const repoName = repo.split('/')[1] ?? repo;
+        const hasRemote = deps.runner('git', ['remote', 'get-url', FORK_REMOTE], checkout);
+        if (!hasRemote.ok) {
+            const added = deps.runner(
+                'git',
+                ['remote', 'add', FORK_REMOTE, `https://github.com/${login}/${repoName}.git`],
+                checkout,
+            );
+            if (!added.ok) {
+                return { step: 'fork-remote', ok: false, detail: failDetail('fork-remote', added) };
+            }
+        }
+        const pushed = deps.runner('git', ['push', '-u', FORK_REMOTE, branch], checkout);
+        if (!pushed.ok) {
+            return { step: 'push-fork', ok: false, detail: failDetail('push-fork', pushed) };
+        }
+        prHead = `${login}:${branch}`;
+    }
+
+    const prArgs = ['pr', 'create', '--repo', repo, '--title', plan.title, '--body', plan.body];
+    if (prHead !== null) {
+        prArgs.push('--head', prHead);
+    }
+    const pr = deps.runner('gh', prArgs, checkout);
+    if (!pr.ok) {
+        return { step: 'pr-create', ok: false, detail: failDetail('pr-create', pr) };
+    }
+    process.stdout.write(`${pr.out}`);
+    return null;
+}
+
+/**
+ * The egress ladder, executed within ONE `release` call: direct push → fork
+ * push → issue → open-with-errors. Every rung is separately timed out; a rung
+ * that fails degrades to the next instead of aborting the release. When the
+ * whole ladder fails, the record stays `open` with every failed attempt
+ * attached (sanitized — command output can carry local paths).
+ */
+export function executeRelease(
+    record: DefectRecord,
+    plan: ReleasePlan,
+    probe: Probe,
+    repo: string,
+    deps: ReleaseDeps,
+): ReleaseOutcome {
+    const attempts: EgressAttempt[] = [];
+
+    if (plan.route === 'pull-request') {
+        const checkout = probe.agentConfigCheckout!;
+        const branch = deps.runner('git', ['branch', '--show-current'], checkout).out.trim();
+        if (!branch || branch === 'main') {
+            // Precondition, not an egress failure: the authored fix exists and
+            // must ride its own branch — an issue instead would drop the fix.
+            attempts.push({
+                step: 'branch-check',
+                ok: false,
+                detail:
+                    'the fix must sit on its own branch in the agent-config checkout ' +
+                    `(currently: ${branch || 'detached'})`,
+            });
+            return { published: null, attempts };
+        }
+        const ladder: PushVia[] =
+            plan.pushVia === 'upstream' && probe.canFork
+                ? ['upstream', 'fork']
+                : [plan.pushVia ?? 'upstream'];
+        for (const via of ladder) {
+            const failed = tryPullRequest(plan, probe, repo, branch, via, deps);
+            if (failed === null) {
+                return { published: 'pull-request', attempts };
+            }
+            attempts.push(failed);
+        }
+    }
+
+    if (plan.route === 'pull-request' || plan.route === 'issue') {
+        // Re-render for the rung actually taken: a plan that degraded from
+        // pull-request must not file an issue whose body claims
+        // `Route: pull-request` (R2 finding #4).
+        const issueBody =
+            plan.route === 'issue' ? plan.body : renderReport(record, 'issue');
+        const issue = deps.runner('gh', [
+            'issue',
+            'create',
+            '--repo',
+            repo,
+            '--title',
+            plan.title,
+            '--body',
+            issueBody,
+        ]);
+        if (issue.ok) {
+            process.stdout.write(`${issue.out}`);
+            return { published: 'issue', attempts };
+        }
+        attempts.push({ step: 'issue-create', ok: false, detail: failDetail('issue-create', issue) });
+    }
+
+    return { published: null, attempts };
 }
 
 function statusCmd(root: string): number {
@@ -140,12 +434,18 @@ function releaseCmd(root: string, argv: string[]): number {
     const repoArg = argv.indexOf('--repo');
     const repo = repoArg >= 0 ? (argv[repoArg + 1] ?? UPSTREAM_REPO) : UPSTREAM_REPO;
     const probe = probeMachine(process.env, process.cwd());
-    const plan = planRelease(record, probe, root);
+    const plan = planRelease(record, probe, root, {
+        classCKeys: readClassCKeys(probe.agentConfigCheckout),
+    });
 
-    process.stdout.write(`self-repair:release ${fp} -> route=${plan.route}\n`);
+    const via = plan.pushVia !== null ? ` via=${plan.pushVia}` : '';
+    process.stdout.write(`self-repair:release ${fp} -> route=${plan.route}${via}\n`);
     if (plan.blocked !== null) {
         process.stdout.write(`  WARN  ${plan.blocked}\n`);
     }
+    if (plan.patch_denied !== null) {
+        process.stdout.write(`  DENY  ${plan.patch_denied}\n`);
+    }
     if (dryRun) {
         process.stdout.write(`\n--- ${plan.title} ---\n${plan.body}\n`);
         return EXIT_OK;
@@ -156,47 +456,25 @@ function releaseCmd(root: string, argv: string[]): number {
         );
         return EXIT_OK;
     }
-    if (plan.route === 'issue') {
-        const r = run('gh', [
-            'issue',
-            'create',
-            '--repo',
-            repo,
-            '--title',
-            plan.title,
-            '--body',
-            plan.body,
-        ]);
-        process.stdout.write(`${r.out}\n`);
-        if (!r.ok) {
-            return EXIT_FAIL;
-        }
-    } else {
-        const checkout = probe.agentConfigCheckout!;
-        const branch = run('git', ['branch', '--show-current'], checkout).out.trim();
-        if (!branch || branch === 'main') {
-            process.stderr.write(
-                '  The fix must sit on its own branch in the agent-config checkout ' +
-                    `(currently: ${branch || 'detached'}).\n`,
-            );
-            return EXIT_FAIL;
-        }
-        const pushed = run('git', ['push', '-u', 'origin', branch], checkout);
-        if (!pushed.ok) {
-            process.stderr.write(`${pushed.out}\n`);
-            return EXIT_FAIL;
-        }
-        const pr = run(
-            'gh',
-            ['pr', 'create', '--repo', repo, '--title', plan.title, '--body', plan.body],
-            checkout,
+
+    const deps: ReleaseDeps = { runner: run, now: () => new Date().toISOString() };
+    const outcome = executeRelease(record, plan, probe, repo, deps);
+
+    for (const a of outcome.attempts) {
+        process.stderr.write(`  FAIL  ${a.detail}\n`);
+    }
+    if (outcome.published === null) {
+        const errors = outcome.attempts.map((a) => sanitizeEvidence(a.detail));
+        attachReleaseErrors(root, fp, errors, deps.now());
+        process.stderr.write(
+            '  The egress ladder is exhausted; the record stays open with the errors attached.\n',
         );
-        process.stdout.write(`${pr.out}\n`);
-        if (!pr.ok) {
-            return EXIT_FAIL;
-        }
+        return EXIT_FAIL;
+    }
+    if (outcome.published !== plan.route) {
+        process.stdout.write(`  Degraded to ${outcome.published} after failed attempt(s).\n`);
     }
-    markReleased(root, fp, new Date().toISOString());
+    markReleased(root, fp, deps.now());
     return EXIT_OK;
 }