@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/_lib/forge_protection.ts

@@ -0,0 +1,267 @@
+/**
+ * The five `forge_protection` rows, read from the forge rather than guessed.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 3.2. ADR-268 § 3 trades
+ * the owner's confirmation for a mechanical check, and branch protection is the
+ * check it trades for — so a run that cannot say whether protection exists has
+ * not established the thing the trade depends on.
+ *
+ * **Every row carries the API call its value came from, and a row that was not
+ * read says so.** That is the whole shape: the step's word is *read, never
+ * guessed*, and the only way a reader can tell one from the other is if the
+ * provenance travels with the value. A row is `satisfied` / `unsatisfied` only
+ * when a named call produced it; otherwise it is `unread`, which is a third
+ * state and never a false.
+ *
+ * **Rulesets, not the classic branch-protection endpoint.** On this repository
+ * `repos/<owner>/<repo>/branches/main/protection` returns `404 {"message":"Branch
+ * not protected"}` while an active ruleset protects the default branch — so a
+ * checker reading the classic endpoint reports "unprotected" for a repository
+ * that is protected. The `forge-protection-settings` blocker was re-scoped for
+ * exactly this reason on 2026-09-10, and the re-scope forbids treating that 404
+ * as absence of protection. No ruleset ID is pinned: rulesets can be replaced or
+ * split, and pinning one would break on the first change.
+ *
+ * Pure. The network lives in the caller, so both polarities are testable offline.
+ */
+
+import type { BypassActor, RulesetDetail } from './platform_anchor.js';
+
+/** Whether a row was established, refuted, or never read. */
+export type RowState = 'satisfied' | 'unsatisfied' | 'unread';
+
+/** One `forge_protection` row. */
+export interface ProtectionRow {
+    /** Stable key. Rows are addressed by this, never by position. */
+    readonly id: string;
+    readonly state: RowState;
+    /**
+     * The forge API call this value came from — or would come from, when the row
+     * is `unread`. Never empty: a value whose provenance is unstated is the
+     * guess this block exists to refuse.
+     */
+    readonly source: string;
+    /** One line a human can act on when the row is not satisfied. */
+    readonly detail: string;
+}
+
+/** The five rows, in the order the blocker's own table lists them. */
+export const PROTECTION_ROW_IDS: readonly string[] = [
+    'default_branch_protected',
+    'required_checks_present',
+    'force_push_disabled',
+    'auto_merge_available',
+    'deploy_via_pipeline_only',
+] as const;
+
+/** What a caller must supply for a row to be readable. `null` = not read. */
+export interface ForgeReading {
+    /** `repos/<repo>/rulesets` + `/rulesets/<id>`, or `null` when unread. */
+    readonly rulesets: readonly RulesetDetail[] | null;
+    /** The repository's default branch, or `null` when unread. */
+    readonly defaultBranch: string | null;
+    /** `repos/<repo>` → `allow_auto_merge`, or `null` when unread. */
+    readonly allowAutoMerge: boolean | null;
+    /**
+     * `repos/<repo>/environments` → whether every environment with deployment
+     * branch policies restricts them, or `null` when unread.
+     *
+     * Deliberately a boolean the caller derives rather than a raw payload: what
+     * the row asserts is a property of the SET of environments, and handing this
+     * module the raw list would put that judgement in two places.
+     */
+    readonly deployRestricted: boolean | null;
+}
+
+const SOURCE = {
+    rulesets: 'GET repos/{owner}/{repo}/rulesets + GET .../rulesets/{id}',
+    repo: 'GET repos/{owner}/{repo} (allow_auto_merge)',
+    environments: 'GET repos/{owner}/{repo}/environments (deployment_branch_policy)',
+} as const;
+
+/** `true` when this ruleset is active and targets branches. */
+function isActiveBranchRuleset(rs: RulesetDetail): boolean {
+    return rs.enforcement === 'active' && rs.target === 'branch';
+}
+
+/** `true` when the ruleset's ref conditions reach the default branch. */
+function reachesDefaultBranch(rs: RulesetDetail, defaultBranch: string): boolean {
+    const include = rs.conditions?.ref_name?.include ?? [];
+    return include.some(
+        (p) => p === '~DEFAULT_BRANCH' || p === '~ALL' || p === `refs/heads/${defaultBranch}`,
+    );
+}
+
+function hasRule(rs: RulesetDetail, type: string): boolean {
+    return (rs.rules ?? []).some((r) => r.type === type);
+}
+
+function requiredContexts(rs: RulesetDetail): string[] {
+    for (const r of rs.rules ?? []) {
+        if (r.type !== 'required_status_checks') continue;
+        const p = r.parameters;
+        if (p === null || typeof p !== 'object') continue;
+        const list = (p as Record<string, unknown>)['required_status_checks'];
+        if (!Array.isArray(list)) continue;
+        return list
+            .map((e) =>
+                e !== null && typeof e === 'object'
+                    ? (e as Record<string, unknown>)['context']
+                    : null,
+            )
+            .filter((c): c is string => typeof c === 'string');
+    }
+    return [];
+}
+
+/**
+ * Map a forge reading onto the five rows.
+ *
+ * Never throws and never invents: an input of `null` produces `unread`, which is
+ * why the return type has three states rather than two. A gate that reports
+ * `false` for something it did not look at is the failure this separation exists
+ * to prevent — and it is the failure the `forge-protection-settings` re-scope
+ * names, one layer up.
+ */
+export function forgeProtectionRows(reading: ForgeReading): ProtectionRow[] {
+    const rows: ProtectionRow[] = [];
+    const rulesets = reading.rulesets;
+    const branch = reading.defaultBranch;
+
+    const covering =
+        rulesets === null || branch === null
+            ? null
+            : rulesets.filter((rs) => isActiveBranchRuleset(rs) && reachesDefaultBranch(rs, branch));
+
+    rows.push(
+        covering === null
+            ? {
+                  id: 'default_branch_protected',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : covering.length > 0
+              ? {
+                    id: 'default_branch_protected',
+                    state: 'satisfied',
+                    source: SOURCE.rulesets,
+                    detail: `${String(covering.length)} active branch ruleset(s) cover the default branch`,
+                }
+              : {
+                    id: 'default_branch_protected',
+                    state: 'unsatisfied',
+                    source: SOURCE.rulesets,
+                    detail:
+                        'no active branch ruleset covers the default branch. NOTE: the classic ' +
+                        'branches/<b>/protection endpoint 404s on a ruleset-protected repository, ' +
+                        'so a 404 there is not evidence for this row.',
+                },
+    );
+
+    const contexts = covering === null ? null : covering.flatMap(requiredContexts);
+    rows.push(
+        contexts === null
+            ? {
+                  id: 'required_checks_present',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : contexts.length > 0
+              ? {
+                    id: 'required_checks_present',
+                    state: 'satisfied',
+                    source: SOURCE.rulesets,
+                    detail: `${String(contexts.length)} required context(s): ${contexts.join(', ')}`,
+                }
+              : {
+                    id: 'required_checks_present',
+                    state: 'unsatisfied',
+                    source: SOURCE.rulesets,
+                    detail: 'no required status check context is configured',
+                },
+    );
+
+    const noFastForward = covering === null ? null : covering.some((rs) => hasRule(rs, 'non_fast_forward'));
+    rows.push(
+        noFastForward === null
+            ? {
+                  id: 'force_push_disabled',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : {
+                  id: 'force_push_disabled',
+                  state: noFastForward ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.rulesets,
+                  detail: noFastForward
+                      ? 'a non_fast_forward rule is active on the default branch'
+                      : 'no non_fast_forward rule covers the default branch',
+              },
+    );
+
+    rows.push(
+        reading.allowAutoMerge === null
+            ? {
+                  id: 'auto_merge_available',
+                  state: 'unread',
+                  source: SOURCE.repo,
+                  detail: 'the repository record was not queried',
+              }
+            : {
+                  id: 'auto_merge_available',
+                  state: reading.allowAutoMerge ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.repo,
+                  detail: reading.allowAutoMerge
+                      ? 'allow_auto_merge is enabled'
+                      : 'allow_auto_merge is disabled — merge delivery cannot queue behind checks',
+              },
+    );
+
+    rows.push(
+        reading.deployRestricted === null
+            ? {
+                  id: 'deploy_via_pipeline_only',
+                  state: 'unread',
+                  source: SOURCE.environments,
+                  detail: 'the environments were not queried',
+              }
+            : {
+                  id: 'deploy_via_pipeline_only',
+                  state: reading.deployRestricted ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.environments,
+                  detail: reading.deployRestricted
+                      ? 'every environment restricts its deployment branches'
+                      : 'at least one environment accepts a deployment from any branch',
+              },
+    );
+
+    return rows;
+}
+
+/**
+ * The human ACTION lines for rows that are not satisfied.
+ *
+ * **Not a halt, and the step says so explicitly**: `doctor` LISTS what is
+ * missing and the run continues. An `unread` row produces an action too — "go
+ * and read it" is a real instruction, and silently omitting it would make an
+ * unmeasured row indistinguishable from a satisfied one, which is the same
+ * conflation the three-state row type exists to prevent.
+ */
+export function protectionActions(rows: readonly ProtectionRow[]): string[] {
+    return rows
+        .filter((r) => r.state !== 'satisfied')
+        .map((r) => `${r.id}: ${r.state} — ${r.detail} (source: ${r.source})`);
+}
+
+/** Unconditional bypass actors across the covering rulesets, for reporting. */
+export function unconditionalBypasses(
+    rulesets: readonly RulesetDetail[],
+    defaultBranch: string,
+): BypassActor[] {
+    return rulesets
+        .filter((rs) => isActiveBranchRuleset(rs) && reachesDefaultBranch(rs, defaultBranch))
+        .flatMap((rs) => (rs.bypass_actors ?? []).filter((a) => a.bypass_mode === 'always'));
+}

package/src/scripts/_lib/hook_platform_keys.ts

@@ -0,0 +1,27 @@
+/**
+ * Keys under a `hook_manifest.yaml` platform block that are NOT lifecycle slots.
+ *
+ * One definition, because three consumers had grown their own literal and a
+ * fourth key would have had to be added to each of them independently: the
+ * manifest lint (which reads an unknown key as an unknown EVENT), the
+ * injection-effect report (which counts slots per host), and the install
+ * snapshot's drift guard (which asserts every manifest event is bound). Each
+ * of those is a different question about the same block, and none of them is
+ * asking about metadata.
+ *
+ *   `fallback_only`  this package binds nothing on the host; counting it made
+ *                    copilot read one slot against the zero the host table
+ *                    records.
+ *   `ask`            the shape of the host's user-facing question primitive,
+ *                    `native` or `text`. It binds no event, so counting it
+ *                    would add one phantom slot to every host at once.
+ *
+ * A key added here is a key excluded from every event-shaped reading of the
+ * manifest, so add one only when it genuinely carries no binding.
+ */
+export const PLATFORM_METADATA_KEYS: ReadonlySet<string> = new Set(['fallback_only', 'ask']);
+
+/** True when a platform-block key describes the host rather than binding an event. */
+export function isPlatformMetadataKey(key: string): boolean {
+    return PLATFORM_METADATA_KEYS.has(key);
+}

package/src/scripts/_lib/installed_lock.ts

@@ -200,7 +200,7 @@ function splitlines(text: string): string[] {
   return parts;
 }
 
-function _render(
+export function _render(
   version: string,
   tools: string[],
   installed_at: string,

package/src/scripts/_lib/json_python_parity.ts

@@ -0,0 +1,127 @@
+/**
+ * `json.dumps` byte-parity helpers — the emit half of the ADR-200 port.
+ *
+ * The retired Python installer wrote every JSON artefact through
+ * `json.dumps(..., ensure_ascii=False)`, and the port's contract is
+ * byte-identical output, not merely equivalent JSON. `JSON.stringify` does not
+ * satisfy it: it escapes nothing above `\u001f` the same way, renders `NaN` /
+ * `Infinity` as `null` rather than as Python's bare tokens, and offers no
+ * separator control for the compact NDJSON form. So the three dump shapes the
+ * installer needs are written out here, mirroring CPython's encoder:
+ *
+ * - {@link jsonDumpsIndent} — `json.dumps(data, indent=N, ensure_ascii=False)`
+ *   with `sort_keys=False` (insertion order preserved, as JS object key order
+ *   already matches Python dict order for our string keys);
+ * - {@link jsonDumpsCompact} — `json.dumps(obj, separators=(",", ":"))`;
+ * - {@link jsonStrNoAscii} — the string encoder both build on.
+ *
+ * Sibling of `src/scripts/install.ts`, which is its only caller. It lives here
+ * rather than inline because the dump shapes are pure, total functions of their
+ * input with no installer state — and because `install.ts` is far over the
+ * 1,500-line source ceiling (`check_source_size_budget`), so a self-contained
+ * unit belongs outside it.
+ *
+ * This module is in the installer's bundled import closure
+ * (`npm run build:install-bundle`), so it carries no module-level side effect
+ * and no `process.exit` — see `check_installer_import_purity`.
+ */
+
+export function jsonStrNoAscii(s: string): string {
+    // json.dumps(ensure_ascii=False): escape control chars + " + \, keep >=0x20
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        switch (ch) {
+            case '"':
+                out += '\\"';
+                break;
+            case '\\':
+                out += '\\\\';
+                break;
+            case '\n':
+                out += '\\n';
+                break;
+            case '\r':
+                out += '\\r';
+                break;
+            case '\t':
+                out += '\\t';
+                break;
+            case '\b':
+                out += '\\b';
+                break;
+            case '\f':
+                out += '\\f';
+                break;
+            default:
+                if (code < 0x20) {
+                    out += '\\u' + code.toString(16).padStart(4, '0');
+                } else {
+                    out += ch;
+                }
+        }
+    }
+    return out + '"';
+}
+
+function _jsonScalar(value: unknown): string | null {
+    if (value === null || value === undefined) return 'null';
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            if (Number.isNaN(value)) return 'NaN';
+            return value > 0 ? 'Infinity' : '-Infinity';
+        }
+        // Our payloads carry only integers; render as-is.
+        return String(value);
+    }
+    if (typeof value === 'string') return jsonStrNoAscii(value);
+    return null;
+}
+
+function _dumpIndent(value: unknown, indent: number, depth: number): string {
+    const scalar = _jsonScalar(value);
+    if (scalar !== null) return scalar;
+    const pad = ' '.repeat(indent * (depth + 1));
+    const closePad = ' '.repeat(indent * depth);
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        const items = value.map((v) => pad + _dumpIndent(v, indent, depth + 1));
+        return `[\n${items.join(',\n')}\n${closePad}]`;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value as Record<string, unknown>;
+        const keys = Object.keys(obj);
+        if (keys.length === 0) return '{}';
+        const items = keys.map(
+            (k) => `${pad}${jsonStrNoAscii(k)}: ${_dumpIndent(obj[k], indent, depth + 1)}`,
+        );
+        return `{\n${items.join(',\n')}\n${closePad}}`;
+    }
+    return jsonStrNoAscii(String(value));
+}
+
+/** `json.dumps(data, indent=N, ensure_ascii=False)` (sort_keys=False). */
+export function jsonDumpsIndent(value: unknown, indent: number): string {
+    return _dumpIndent(value, indent, 0);
+}
+
+/** `json.dumps(obj, separators=(",", ":"))` — compact, ensure_ascii=False here. */
+export function jsonDumpsCompact(value: unknown): string {
+    const scalar = _jsonScalar(value);
+    if (scalar !== null) return scalar;
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => jsonDumpsCompact(v)).join(',') + ']';
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value as Record<string, unknown>;
+        return (
+            '{' +
+            Object.keys(obj)
+                .map((k) => `${jsonStrNoAscii(k)}:${jsonDumpsCompact(obj[k])}`)
+                .join(',') +
+            '}'
+        );
+    }
+    return jsonStrNoAscii(String(value));
+}

package/src/scripts/_lib/lean_projection_mode.ts

@@ -11,11 +11,22 @@
  *
  * So each side supplies the raw string from its own reader and this module
  * decides what it means. Anything unrecognised — absent key, typo, `null`,
- * a non-string — is `eager-all`, today's shipped behaviour: a mode nobody can
- * spell must never silently thin the standing corpus.
+ * a non-string — is `eager-all`: the parser fallback, which is NOT the value
+ * the template ships (see the type below), because a mode nobody can spell
+ * must never silently thin the standing corpus.
  */
 
-/** The three projection shapes. `eager-all` is the shipped default. */
+/**
+ * The three projection shapes, and the two different defaults they answer to.
+ *
+ * The TEMPLATE default — what a consumer is given — is `delivery` with
+ * `hosts: [claude-code]`, shipped in `src/config/agent-settings.template.yml`
+ * since ADR-267, so on that one host a normal read resolves to `delivery`.
+ * The PARSER FALLBACK — what applies when no value resolves from any layer —
+ * is `eager-all` (`DEFAULT_LEAN_PROJECTION_MODE` below), deliberately not
+ * flipped with the template per ADR-267 decision 4: the template says what was
+ * chosen, the constant says what happens when nothing could be read.
+ */
 export type LeanProjectionMode = 'eager-all' | 'thin' | 'delivery';
 
 export const DEFAULT_LEAN_PROJECTION_MODE: LeanProjectionMode = 'eager-all';