@groundnuty/macf 0.2.37 → 0.2.39

package/dist/cli/commands/restart-self.js

@@ -0,0 +1,312 @@
+/**
+ * `macf restart-self` — DR-031 piece 3, the VM "be-replaceable" verb.
+ *
+ * Safely prepares the workspace and spawns a DETACHED relauncher that OUTLIVES
+ * the agent's session death, so a watchdog (or the agent itself) can trigger a
+ * clean restart without losing uncommitted work. The naive self-kill is suicide
+ * (an agent that `tmux kill-session`s its own session dies mid-command with no
+ * respawn — DR-031 §"Be-replaceable"); the detached relauncher is what makes the
+ * restart survive the kill.
+ *
+ * Orchestration (in this exact order, ALL under a confirm gate):
+ *   1. Resolve config (workspace + the canonical `<project>@<agent>` tmux session).
+ *   2. Safety gate — DRY-RUN BY DEFAULT. Without `--confirm` (or with `--dry-run`)
+ *      it emits the full plan and exits 0 having done NOTHING (no stash/kill/spawn).
+ *   3. Prepare the working tree — a MARKED STASH (not auto-commit): only if there
+ *      are uncommitted *tracked* changes. A marked stash is local, recoverable,
+ *      non-destructive, and survives a same-host restart; auto-commit risks leaking
+ *      half-baked state into history.
+ *   4. Write a RESUME-note (reason / ts / branch / HEAD / stash-ref + a recovery line).
+ *   5. Spawn a DETACHED relauncher that waits for the old session to die, re-sources
+ *      the host-prelude (if present), then `exec ./claude.sh`.
+ *   6. Kill the current tmux session — the actual restart trigger. ONLY in
+ *      `--confirm` mode, and ONLY as the final step after 3–5 succeeded.
+ *
+ * ALL side effects flow through `RestartSelfDeps` so `runRestartSelf` is unit-
+ * testable with fakes (no real stash / kill / spawn). Production wires the real
+ * deps via `createRealDeps`.
+ */
+import { spawn, execFileSync } from 'node:child_process';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readAgentConfig } from '../config.js';
+/** The three restart drivers (DR-031 §"Be-replaceable" — fault / upgrade / manual). */
+export const RESTART_REASONS = ['fault', 'upgrade', 'manual'];
+/** Coerce an arbitrary `--reason` string to a known reason; defaults to `manual`. */
+export function coerceReason(raw) {
+    return RESTART_REASONS.includes(raw ?? '')
+        ? raw
+        : 'manual';
+}
+/** The `--json` state-record (mirrors `fleet doctor`'s versioned shape). */
+export const RESTART_SELF_JSON_SCHEMA_VERSION = 1;
+/** Derive `<project>@<agent>` (the canonical claude.sh self-wrap session), or null. */
+export function resolveSession(opts) {
+    const explicit = opts.session?.trim();
+    if (explicit)
+        return explicit;
+    const p = opts.project?.trim();
+    const a = opts.agentName?.trim();
+    return p && a ? `${p}@${a}` : null;
+}
+/** The marked-stash label: `macf-restart-self/<ISO-8601-ts>/<reason>`. */
+export function stashLabel(iso, reason) {
+    return `macf-restart-self/${iso}/${reason}`;
+}
+const RESUME_NOTE_REL = join('.claude', '.macf', 'RESUME-restart-self.md');
+const RELAUNCHER_REL = join('.claude', '.macf', 'restart-self-relauncher.sh');
+const HOST_PRELUDE_REL = join('.claude', '.macf', 'host-prelude.sh');
+const MACF_DIR_REL = join('.claude', '.macf');
+/** The RESUME-note body — what a future session needs to pick the work back up. */
+export function buildResumeNote(args) {
+    const { reason, iso, branch, head, stashRef } = args;
+    const stashLine = stashRef ?? 'none';
+    const recovery = stashRef === null
+        ? 'Nothing was stashed (working tree was clean) — just resume your task.'
+        : `Your uncommitted tracked changes were stashed. Recover with ` +
+            `\`git stash apply ${stashRef}\` (or \`git stash list\` to find it).`;
+    return [
+        '# macf restart-self — RESUME',
+        '',
+        `- Reason: ${reason}`,
+        `- Timestamp: ${iso}`,
+        `- Branch: ${branch}`,
+        `- HEAD: ${head}`,
+        `- Stash: ${stashLine}`,
+        '',
+        `Resume from here: ${recovery}`,
+        '',
+    ].join('\n');
+}
+/**
+ * The detached relauncher script. Waits for the OLD session to die (up to ~30s),
+ * then `cd`s to the workspace, sources the host-prelude IF it exists (decoupled
+ * from DR-031 piece 4 — proceed if absent), and `exec`s the launcher. Uses
+ * absolute paths so it does not depend on the dying session's env beyond what it
+ * re-establishes.
+ */
+export function buildRelauncherScript(args) {
+    const { workspaceDir, session, iso } = args;
+    const prelude = join(workspaceDir, HOST_PRELUDE_REL);
+    return [
+        '#!/usr/bin/env bash',
+        `# macf restart-self relauncher (DR-031 piece 3) — generated ${iso}`,
+        '# Detached from the dying agent session; waits for it to exit, then relaunches.',
+        'set -uo pipefail',
+        `WORKSPACE=${shq(workspaceDir)}`,
+        `SESSION=${shq(session)}`,
+        `PRELUDE=${shq(prelude)}`,
+        '',
+        '# Wait for the dying session to actually exit (up to ~30s) so the relaunch',
+        "# self-wrap re-creates it cleanly instead of attaching to the corpse.",
+        'for _ in $(seq 1 60); do',
+        '  tmux has-session -t "$SESSION" 2>/dev/null || break',
+        '  sleep 0.5',
+        'done',
+        '',
+        'cd "$WORKSPACE" || exit 1',
+        '# host-prelude re-establishes the toolchain (brew/devbox PATH) for a minimal',
+        '# (cron/detached) env. Decoupled from DR-031 piece 4 — proceed if absent.',
+        'if [ -f "$PRELUDE" ]; then',
+        '  # shellcheck disable=SC1090',
+        '  . "$PRELUDE"',
+        'fi',
+        'exec ./claude.sh',
+        '',
+    ].join('\n');
+}
+/** Single-quote a value for safe shell embedding (closes + escapes any `'`). */
+function shq(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Human-readable dry-run / confirm plan for the table (non-JSON) output. */
+function renderPlanText(plan, dirty, workspaceDir) {
+    const lines = [
+        `macf restart-self — ${plan.dry_run ? 'DRY-RUN (default; pass --confirm to act)' : 'EXECUTING (--confirm)'}`,
+        '',
+        `  reason:        ${plan.reason}`,
+        `  workspace:     ${workspaceDir}`,
+        `  session:       ${plan.session}`,
+        `  would stash:   ${dirty ? 'yes (uncommitted tracked changes)' : 'no (working tree clean)'}`,
+        `  resume note:   ${plan.resume_note_path}`,
+        `  relauncher:    ${plan.relauncher_path}`,
+        `  kill session:  ${plan.dry_run ? 'NO (dry-run)' : `yes — tmux kill-session -t ${plan.session}`}`,
+    ];
+    if (plan.dry_run) {
+        lines.push('', 'No stash, no kill, no spawn performed. Re-run with --confirm to execute.');
+    }
+    else {
+        lines.push('', `Stashed: ${plan.stash_ref ?? 'none'}. Detached relauncher spawned; killing session now.`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Pure orchestrator. Returns the shell exit code. DRY-RUN BY DEFAULT — only a
+ * `--confirm` (and not `--dry-run`) run stashes / writes / spawns / kills.
+ * Refuses (exit 1) when the session name cannot be resolved.
+ */
+export async function runRestartSelf(opts, deps) {
+    const session = resolveSession(opts);
+    if (!session) {
+        console.error('macf restart-self: cannot resolve the tmux session name.\n' +
+            'Need MACF_PROJECT + MACF_AGENT_NAME (or project/agent_name in ' +
+            '.macf/macf-agent.json), or pass an explicit session. Refusing to act.');
+        return 1;
+    }
+    const { workspaceDir, reason } = opts;
+    const resumeNotePath = join(workspaceDir, RESUME_NOTE_REL);
+    const relauncherPath = join(workspaceDir, RELAUNCHER_REL);
+    const dryRun = opts.dryRun || !opts.confirm;
+    const dirty = deps.hasUncommittedTrackedChanges();
+    const iso = deps.now().toISOString();
+    if (dryRun) {
+        const plan = makePlan({ dryRun: true, reason, session, stashRef: null, resumeNotePath, relauncherPath, killed: false });
+        if (opts.json)
+            console.log(JSON.stringify(plan, null, 2));
+        else
+            console.log(renderPlanText(plan, dirty, workspaceDir));
+        return 0;
+    }
+    // --- CONFIRM mode: prepare → note → spawn → kill (each exactly once) ---
+    deps.mkdirp(join(workspaceDir, MACF_DIR_REL));
+    // 3. Prepare working tree — marked stash, ONLY when there are tracked changes.
+    let stashRef = null;
+    if (dirty) {
+        const result = deps.stash(stashLabel(iso, reason));
+        stashRef = result.stashed ? (result.ref ?? 'stash@{0}') : null;
+    }
+    // 4. RESUME-note.
+    const note = buildResumeNote({
+        reason,
+        iso,
+        branch: deps.currentBranch(),
+        head: deps.headSha(),
+        stashRef,
+    });
+    deps.writeFile(resumeNotePath, note);
+    // 5. Detached relauncher (script + spawn).
+    const script = buildRelauncherScript({ workspaceDir, session, iso });
+    deps.writeFile(relauncherPath, script, 0o755);
+    deps.spawnDetached(relauncherPath, []);
+    // Emit the result BEFORE the kill — the kill terminates this very process in
+    // production (it kills our own session), so anything after it never prints.
+    const plan = makePlan({ dryRun: false, reason, session, stashRef, resumeNotePath, relauncherPath, killed: true });
+    if (opts.json)
+        console.log(JSON.stringify(plan, null, 2));
+    else
+        console.log(renderPlanText(plan, dirty, workspaceDir));
+    // 6. Kill the current session — the actual restart trigger.
+    deps.killSession(session);
+    return 0;
+}
+function makePlan(args) {
+    return {
+        schema_version: RESTART_SELF_JSON_SCHEMA_VERSION,
+        dry_run: args.dryRun,
+        reason: args.reason,
+        session: args.session,
+        stash_ref: args.stashRef,
+        resume_note_path: args.resumeNotePath,
+        relauncher_path: args.relauncherPath,
+        killed: args.killed,
+    };
+}
+// --- Real-deps factory (production wiring) ---
+/** Run a git command in `cwd`, returning trimmed stdout (throws on non-zero). */
+function git(cwd, args) {
+    return execFileSync('git', args, { cwd, encoding: 'utf-8' }).trim();
+}
+/**
+ * Real side-effect implementations bound to a workspace dir. Git reads/stash run
+ * in `workspaceDir`; the spawn is FULLY DETACHED (`detached: true` opens a new
+ * session — the Node equivalent of `setsid` — plus `stdio: 'ignore'` + `unref()`
+ * so the relauncher outlives this process when its session is killed).
+ */
+export function createRealDeps(workspaceDir) {
+    return {
+        now: () => new Date(),
+        hasUncommittedTrackedChanges: () => {
+            // Tracked, uncommitted (staged OR unstaged); untracked files excluded.
+            const out = git(workspaceDir, ['status', '--porcelain', '--untracked-files=no']);
+            return out.length > 0;
+        },
+        currentBranch: () => {
+            try {
+                return git(workspaceDir, ['rev-parse', '--abbrev-ref', 'HEAD']);
+            }
+            catch {
+                return '(unknown)';
+            }
+        },
+        headSha: () => {
+            try {
+                return git(workspaceDir, ['rev-parse', 'HEAD']);
+            }
+            catch {
+                return '(unknown)';
+            }
+        },
+        stash: (label) => {
+            const out = git(workspaceDir, ['stash', 'push', '-m', label]);
+            if (/no local changes/i.test(out))
+                return { stashed: false };
+            let ref = 'stash@{0}';
+            try {
+                ref = git(workspaceDir, ['rev-parse', 'stash@{0}']);
+            }
+            catch {
+                /* keep the symbolic ref */
+            }
+            return { stashed: true, ref };
+        },
+        writeFile: (path, content, mode) => {
+            writeFileSync(path, content, mode !== undefined ? { mode } : undefined);
+        },
+        mkdirp: (path) => {
+            mkdirSync(path, { recursive: true });
+        },
+        spawnDetached: (scriptPath, args) => {
+            const child = spawn('/usr/bin/env', ['bash', scriptPath, ...args], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.unref();
+        },
+        killSession: (session) => {
+            try {
+                execFileSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+            }
+            catch {
+                // The goal — the session's death — is satisfied whether or not the
+                // command "succeeds" (e.g. already gone). Never throw on the final step.
+            }
+        },
+    };
+}
+/**
+ * Resolve identity (workspace / project / agent) from env first (the running
+ * agent's `claude.sh`-exported values), falling back to `.macf/macf-agent.json`.
+ * The canonical session claude.sh self-wraps into is `${MACF_PROJECT}@${MACF_AGENT_NAME}`.
+ */
+export function resolveIdentity(projectDir, env = process.env) {
+    const config = readAgentConfig(projectDir);
+    const workspaceDir = env['MACF_WORKSPACE_DIR']?.trim() || projectDir;
+    const project = env['MACF_PROJECT']?.trim() || config?.project;
+    const agentName = env['MACF_AGENT_NAME']?.trim() || config?.agent_name;
+    return { workspaceDir, project, agentName };
+}
+/** `macf restart-self` entry point — resolves config, wires real deps, runs. */
+export async function runRestartSelfCommand(projectDir, cliOpts) {
+    const { workspaceDir, project, agentName } = resolveIdentity(projectDir);
+    const deps = createRealDeps(workspaceDir);
+    return runRestartSelf({
+        workspaceDir,
+        project,
+        agentName,
+        reason: coerceReason(cliOpts.reason),
+        confirm: cliOpts.confirm === true,
+        dryRun: cliOpts.dryRun === true,
+        json: cliOpts.json === true,
+    }, deps);
+}
+//# sourceMappingURL=restart-self.js.map

package/dist/cli/commands/restart-self.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-self.js","sourceRoot":"","sources":["../../../src/cli/commands/restart-self.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/routing-doctor-gh.d.ts

@@ -0,0 +1,29 @@
+import type { CallerPinResult, RoutingConfig } from './routing-doctor.js';
+/**
+ * List the App installation's repo-set (DR-030 Q3). Uses the installation token
+ * we already mint for the registry reads — `/installation/repositories` returns
+ * exactly the repos that token can act on, which IS the routing fleet (an agent
+ * unreachable through GitHub can't be in the fleet). Returns `owner/repo` full
+ * names. NEVER throws — an access/auth failure resolves to `[]` so the command
+ * degrades to "0 fleet repos discovered" rather than crashing.
+ */
+export declare function createInstallRepoLister(token: string): () => Promise<readonly string[]>;
+/**
+ * Read one repo's caller-pin from `.github/workflows/agent-router.yml`. Returns a
+ * tri-status result:
+ *   - `pinned`      — the file exists AND references `groundnuty/macf-actions@<pin>`.
+ *   - `no-workflow` — the file is absent OR has no macf-actions `uses:` (the repo
+ *                     is App-installed but NOT a routing caller — e.g. the registry
+ *                     owner-repo, or macf-actions itself). Excluded from the
+ *                     consistency verdict (not a divergence).
+ *   - `error`       — the read failed for another reason.
+ * NEVER throws.
+ */
+export declare function createCallerPinReader(token: string): (repo: string) => Promise<CallerPinResult>;
+/**
+ * Read one repo's `.github/agent-config.json` (the router's per-label config) via
+ * the GitHub contents API. Returns the parsed config or `null` (absent / unreadable
+ * / malformed). NEVER throws.
+ */
+export declare function createRoutingConfigGhReader(token: string): (repo: string) => Promise<RoutingConfig | null>;
+//# sourceMappingURL=routing-doctor-gh.d.ts.map

package/dist/cli/commands/routing-doctor-gh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-doctor-gh.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/routing-doctor-gh.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAa1E;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAiBvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAqB/F;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GACZ,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAgBjD"}

package/dist/cli/commands/routing-doctor-gh.js

@@ -0,0 +1,103 @@
+/**
+ * GitHub-plane I/O leaf for `macf routing doctor` (DR-030 phase-2, macf#568).
+ *
+ * Isolates the `gh` shell-outs the routing-infra checks need so the orchestration
+ * in `routing-doctor.ts` stays PURE + offline-testable (production wires these;
+ * tests inject fakes). Every call here is a READ:
+ *
+ *   - `listInstallRepos`     — the App INSTALL-SET (DR-030 Q3 repo-set source):
+ *                              `gh api /installation/repositories`. NOT a new
+ *                              `fleet.repos` config file (no parallel, drift-prone
+ *                              surface) — derived from an existing GitHub surface.
+ *   - `readCallerPin`        — a repo's `.github/workflows/agent-router.yml`
+ *                              `uses: groundnuty/macf-actions/...@<pin>` line.
+ *   - `readRoutingConfigGh`  — a repo's `.github/agent-config.json` (the router's
+ *                              per-label config), via the GitHub contents API.
+ *
+ * The token is forwarded as `GH_TOKEN` in the subprocess env (the house auth
+ * posture); none of these has a write path.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** The macf-actions caller `uses:` reference we look for in agent-router.yml. */
+const ACTIONS_USES_RE = /uses:\s*groundnuty\/macf-actions\/\.github\/workflows\/agent-router\.yml@(\S+)/;
+/** Decode a GitHub contents-API `.content` base64 blob (newline-wrapped). */
+function decodeGhContent(b64) {
+    return Buffer.from(b64.replace(/\s+/g, ''), 'base64').toString('utf-8');
+}
+/**
+ * List the App installation's repo-set (DR-030 Q3). Uses the installation token
+ * we already mint for the registry reads — `/installation/repositories` returns
+ * exactly the repos that token can act on, which IS the routing fleet (an agent
+ * unreachable through GitHub can't be in the fleet). Returns `owner/repo` full
+ * names. NEVER throws — an access/auth failure resolves to `[]` so the command
+ * degrades to "0 fleet repos discovered" rather than crashing.
+ */
+export function createInstallRepoLister(token) {
+    const env = { ...process.env, GH_TOKEN: token };
+    return async () => {
+        try {
+            const { stdout } = await execFileAsync('gh', ['api', '--paginate', '/installation/repositories', '--jq', '.repositories[].full_name'], { encoding: 'utf-8', env, maxBuffer: 32 * 1024 * 1024 });
+            return stdout
+                .split('\n')
+                .map((l) => l.trim())
+                .filter((l) => l.length > 0);
+        }
+        catch {
+            return [];
+        }
+    };
+}
+/**
+ * Read one repo's caller-pin from `.github/workflows/agent-router.yml`. Returns a
+ * tri-status result:
+ *   - `pinned`      — the file exists AND references `groundnuty/macf-actions@<pin>`.
+ *   - `no-workflow` — the file is absent OR has no macf-actions `uses:` (the repo
+ *                     is App-installed but NOT a routing caller — e.g. the registry
+ *                     owner-repo, or macf-actions itself). Excluded from the
+ *                     consistency verdict (not a divergence).
+ *   - `error`       — the read failed for another reason.
+ * NEVER throws.
+ */
+export function createCallerPinReader(token) {
+    const env = { ...process.env, GH_TOKEN: token };
+    return async (repo) => {
+        let content;
+        try {
+            const { stdout } = await execFileAsync('gh', ['api', `repos/${repo}/contents/.github/workflows/agent-router.yml`, '--jq', '.content'], { encoding: 'utf-8', env, maxBuffer: 8 * 1024 * 1024 });
+            content = decodeGhContent(stdout);
+        }
+        catch {
+            // 404 (no workflow) is the overwhelmingly common case; treat any read
+            // failure as "not a routing caller" rather than a hard error so a single
+            // non-caller repo in the install-set doesn't poison the sweep.
+            return { repo, pin: null, status: 'no-workflow' };
+        }
+        const m = ACTIONS_USES_RE.exec(content);
+        if (!m)
+            return { repo, pin: null, status: 'no-workflow' };
+        return { repo, pin: m[1], status: 'pinned' };
+    };
+}
+/**
+ * Read one repo's `.github/agent-config.json` (the router's per-label config) via
+ * the GitHub contents API. Returns the parsed config or `null` (absent / unreadable
+ * / malformed). NEVER throws.
+ */
+export function createRoutingConfigGhReader(token) {
+    const env = { ...process.env, GH_TOKEN: token };
+    return async (repo) => {
+        try {
+            const { stdout } = await execFileAsync('gh', ['api', `repos/${repo}/contents/.github/agent-config.json`, '--jq', '.content'], { encoding: 'utf-8', env, maxBuffer: 8 * 1024 * 1024 });
+            const parsed = JSON.parse(decodeGhContent(stdout));
+            if (!parsed || typeof parsed !== 'object' || typeof parsed.agents !== 'object')
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+//# sourceMappingURL=routing-doctor-gh.js.map

package/dist/cli/commands/routing-doctor-gh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-doctor-gh.js","sourceRoot":"","sources":["../../../src/cli/commands/routing-doctor-gh.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/routing-doctor.d.ts

@@ -0,0 +1,183 @@
+import type { AgentInfo, HealthResponse } from '@groundnuty/macf-core';
+export type CallerPinStatus = 'pinned' | 'no-workflow' | 'error';
+/** One repo's caller-pin read. `pinned` ones participate in the consistency verdict. */
+export interface CallerPinResult {
+    readonly repo: string;
+    readonly pin: string | null;
+    readonly status: CallerPinStatus;
+    readonly error?: string;
+}
+/** One agent's entry in a repo's `.github/agent-config.json`. */
+export interface RoutingConfigEntry {
+    readonly app_name?: string;
+    readonly tmux_session?: string;
+}
+/** A repo's `.github/agent-config.json` (the router's per-label config). */
+export interface RoutingConfig {
+    readonly agents: Readonly<Record<string, RoutingConfigEntry>>;
+}
+/** Probe a single endpoint's `/health`; null on any failure. Injectable for tests. */
+export type RoutingProbeFn = (host: string, port: number) => Promise<HealthResponse | null>;
+/** Normalize a GitHub login for comparison: lowercase, strip `app/` + `[bot]`. */
+export declare function normalizeLogin(s: string): string;
+/**
+ * The expected fleet caller-pin: an explicit override, else the MODAL (most
+ * common) pin among the repos that ARE routing callers. `null` when no repo pins
+ * macf-actions (nothing to be consistent about).
+ */
+export declare function computeExpectedPin(pinned: readonly string[], override?: string): string | null;
+/**
+ * Self-skip correctness (#538 check b / #566). `app_name` must be the bot-LOGIN.
+ * When an authoritative `expectedBotLogin` is known (the running agent's own
+ * `github_app.bot_login`, macf#535), compare exactly (normalized). Otherwise fall
+ * back to the structural heuristic: the #566 bug is literally `app_name === <bare
+ * routing label>`, so flag that — anything else passes (we can't prove the exact
+ * bot-login without an authoritative actor source; stated in the legend).
+ */
+export declare function evaluateSelfSkip(label: string, appName: string | undefined, expectedBotLogin?: string): {
+    readonly ok: boolean;
+    readonly reason?: string;
+};
+/**
+ * Session-name drift (#? Stage-2 fallback). The CONVENTION check: `tmux_session`
+ * must equal `<project>@<label>`. This is a STATIC convention check — it proves the
+ * config follows the canonical naming, NOT that it matches the LIVE tmux session
+ * (a runtime fact this command can't see). Stated in the legend.
+ */
+export declare function evaluateSession(label: string, tmuxSession: string | undefined, project: string): {
+    readonly ok: boolean;
+    readonly expected: string;
+    readonly reason?: string;
+};
+/** Strict base64: only the base64 alphabet, padded to a multiple of 4. */
+export declare function isStrictBase64(s: string): boolean;
+/**
+ * CA material check (#563). `MACF_CA_CERT` is a readable VARIABLE; validate it is
+ * present AND parses — either as a PEM cert block whose body is strict base64, or
+ * as a base64-of-PEM blob that decodes to a cert. A present-but-malformed value
+ * (truncated / garbled base64) is the #563 class: present ≠ valid.
+ */
+export declare function evaluateCaCert(raw: string | null | undefined): {
+    readonly present: boolean;
+    readonly valid: boolean;
+    readonly reason?: string;
+};
+export type FreshnessState = 'fresh' | 'stale' | 'unreachable' | 'unknown' | 'unregistered';
+/**
+ * Classify a registry entry's freshness against the LIVE `/health`:
+ *  - `/health` answers + instance_id MATCHES   → `fresh`.
+ *  - `/health` answers + instance_id MISMATCH  → `stale` (registry points at an
+ *                                                older instance; a newer one answered).
+ *  - `/health` answers but reports no instance_id (older cs) → `unknown`.
+ *  - `/health` unreachable + heartbeat aged past TTL (DR-031) → `stale` (definitively
+ *                                                dead — ungraceful death).
+ *  - `/health` unreachable, heartbeat fresh/absent → `unreachable` (can't confirm;
+ *                                                NOT a verdict failure — liveness is
+ *                                                `fleet doctor`'s job, not the plane's).
+ */
+export declare function classifyFreshness(info: AgentInfo, health: HealthResponse | null, now: number, ttlMs: number): FreshnessState;
+export interface RepoPinRow {
+    readonly repo: string;
+    readonly pin: string | null;
+    readonly status: CallerPinStatus;
+    /** `true`/`false` for routing callers; `null` for non-callers (excluded from verdict). */
+    readonly consistent: boolean | null;
+}
+export interface AgentRow {
+    readonly label: string;
+    readonly appName: string | null;
+    readonly tmuxSession: string | null;
+    readonly routable: boolean;
+    readonly selfSkipOk: boolean;
+    readonly selfSkipReason?: string;
+    readonly sessionOk: boolean;
+    readonly sessionExpected: string;
+    readonly sessionReason?: string;
+    readonly freshness: FreshnessState;
+    readonly registryInstanceId?: string | null;
+    readonly healthInstanceId?: string | null;
+}
+export interface CaCheckResult {
+    readonly present: boolean;
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+export interface RoutingDoctorReport {
+    readonly project: string;
+    readonly repoPins: readonly RepoPinRow[];
+    readonly expectedPin: string | null;
+    readonly hasRoutingConfig: boolean;
+    readonly agents: readonly AgentRow[];
+    readonly ca: CaCheckResult;
+}
+/** Injectable seam so tests drive the command fully offline. */
+export interface RoutingDoctorDeps {
+    readonly project: string;
+    /** The App install-set (DR-030 Q3 repo-set source). */
+    readonly listRepos: () => Promise<readonly string[]>;
+    /** Read a repo's macf-actions caller-pin from agent-router.yml. */
+    readonly readCallerPin: (repo: string) => Promise<CallerPinResult>;
+    /** The CURRENT project's routing config (`.github/agent-config.json`). */
+    readonly readRoutingConfig: () => Promise<RoutingConfig | null>;
+    /** Registry agents (for routability + freshness). */
+    readonly listRegistry: () => Promise<readonly {
+        readonly name: string;
+        readonly info: AgentInfo;
+    }[]>;
+    /** mTLS `/health` probe (freshness). */
+    readonly probe: RoutingProbeFn;
+    /** The `MACF_CA_CERT` variable's raw value. */
+    readonly readCaCert: () => Promise<string | null>;
+    /** Authoritative expected bot-logins by routing label (partial; heuristic fallback). */
+    readonly botLogins?: Readonly<Record<string, string>>;
+    /** Explicit expected caller-pin (else the modal pin). */
+    readonly expectedPin?: string;
+    /** Clock for the heartbeat-TTL staleness math (defaults to `Date.now()`). */
+    readonly now?: number;
+}
+/**
+ * Run all five checks. PURE w.r.t. the injected deps — tests pass fakes so nothing
+ * hits gh / the registry / the network.
+ */
+export declare function gatherRoutingDoctor(deps: RoutingDoctorDeps): Promise<RoutingDoctorReport>;
+export type RoutingVerdict = 'HEALTHY' | 'DEGRADED' | 'EMPTY';
+export declare function routingVerdict(report: RoutingDoctorReport): RoutingVerdict;
+/** `4 fleet repos (pins consistent); 3 agents (2 routing-OK); CA ✓; routing plane: HEALTHY`. */
+export declare function summaryLine(report: RoutingDoctorReport): string;
+/** ✓ consistent / ✗ divergent / `— n/a` (non-caller). */
+export declare function pinGlyph(consistent: boolean | null): string;
+/** Freshness → short glyph: fresh ✓, stale ✗, unreachable/unknown ?, unregistered —. */
+export declare function freshnessGlyph(s: FreshnessState): string;
+export declare function buildRepoRows(rows: readonly RepoPinRow[]): readonly (readonly string[])[];
+export declare function buildAgentRows(rows: readonly AgentRow[]): readonly (readonly string[])[];
+export declare function formatRepoTable(rows: readonly RepoPinRow[]): string;
+export declare function formatAgentTable(rows: readonly AgentRow[]): string;
+/**
+ * The honesty legend — these are STATIC GitHub-plane checks: they prove the
+ * routing PLUMBING is wired right, NOT that a message was delivered (that is
+ * `--e2e`, a later increment). Carried verbatim in the `--json` `disclaimer`.
+ */
+export declare const HONESTY_LEGEND: string;
+/**
+ * `schema_version` is the HARD version contract (DR-006 watchdog, devops #118):
+ * a consumer asserts `schema_version === <known>` and refuses an unknown value,
+ * so ANY breaking change (rename / removal / a same-name SEMANTIC shift) fails
+ * LOUD rather than silently misreading. BUMP on any breaking change; additive-
+ * optional fields do NOT bump it. Independent from fleet doctor's schema_version
+ * (a separate command, a separate contract).
+ */
+export declare const ROUTING_DOCTOR_JSON_SCHEMA_VERSION = 1;
+export declare function routingDoctorToJson(report: RoutingDoctorReport): unknown;
+export interface RunRoutingDoctorOptions {
+    readonly json?: boolean;
+    /** Explicit expected caller-pin (else the modal pin across the fleet). */
+    readonly expectedPin?: string;
+}
+/**
+ * `macf routing doctor` entry point. Returns the shell exit code — 1 when the
+ * routing plane is DEGRADED, 0 when HEALTHY or EMPTY (matching `fleet doctor` /
+ * `macf doctor` "non-zero on problem"). The `--json` body prints regardless; the
+ * watchdog reads `summary.verdict`. `deps` is injected by tests.
+ */
+export declare function runRoutingDoctor(projectDir: string, opts?: RunRoutingDoctorOptions, deps?: RoutingDoctorDeps): Promise<number>;
+//# sourceMappingURL=routing-doctor.d.ts.map