@event4u/agent-config 9.28.0 → 9.29.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,31 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
-    chooseEgressRoute,
+    chooseEgress,
     type DefectRecord,
     type EgressCapability,
     type EgressRoute,
     egressBlockedReason,
+    type PushVia,
     renderReport,
+    sanitizeEvidence,
 } from './_lib/self_repair.js';
-import { listRecords, markReleased, openRecords, readRecord } from './_lib/self_repair_store.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 +63,30 @@ const EXIT_FAIL = 1;
 export interface Probe {
     agentConfigCheckout: string | null;
     ghAuthenticated: boolean;
-    canPush: boolean;
+    canPushUpstream: boolean;
+    canFork: boolean;
+}
+
+export interface RunResult {
+    ok: boolean;
+    out: string;
+    timedOut: 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 ?? ''}` };
+/** 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 +108,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,6 +175,7 @@ export function titleFor(record: DefectRecord): string {
 
 export interface ReleasePlan {
     route: EgressRoute;
+    pushVia: PushVia | null;
     blocked: string | null;
     title: string;
     body: string;
@@ -101,9 +184,177 @@ export interface ReleasePlan {
 /** Pure: everything `release` decides before it touches the network. */
 export function planRelease(record: DefectRecord, probe: Probe, repoRoot: string): 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 choice =
+        blocked !== null
+            ? { route: 'local-only' as const, pushVia: null }
+            : chooseEgress(capabilityOf(probe));
+    return {
+        route: choice.route,
+        pushVia: choice.pushVia,
+        blocked,
+        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 {
@@ -142,7 +393,8 @@ function releaseCmd(root: string, argv: string[]): number {
     const probe = probeMachine(process.env, process.cwd());
     const plan = planRelease(record, probe, root);
 
-    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`);
     }
@@ -156,47 +408,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;
 }
 

package/src/scripts/team_events_spike.ts

@@ -0,0 +1,271 @@
+#!/usr/bin/env tsx
+/**
+ * Team-event payload shape spike (Phase 5.1, road-to-always-on-orchestration).
+ *
+ * `TaskCreated` / `TaskCompleted` / `TeammateIdle` are documented Claude Code
+ * hook events (agent teams, behind `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`),
+ * but this repo has never observed a real payload for any of them — the
+ * shapes are documented, not verified. This script is manually startable
+ * ONLY: it is never wired into `hook_manifest.yaml` / `hooks.json`. A
+ * maintainer points a hook command at it (or pipes a captured payload) to
+ * record a SHAPE — field names + JS/JSON types — and never a value.
+ * Privacy by construction: the recursive walk below inspects `typeof` /
+ * `Array.isArray`, nothing else, so there is no code path that could copy a
+ * value into the written report.
+ *
+ * SCOPE OF THE PRIVACY CLAIM (stated honestly, per independent review): the
+ * claim above holds for a payload whose OWN keys are static field names —
+ * true of the three documented envelopes this script targets
+ * (`TaskCreated` / `TaskCompleted` / `TeammateIdle`), where a key is always
+ * a schema name like `task_id` or `teammate_name`. It does NOT hold for a
+ * payload with dynamically-named keys — a map keyed by a file path, a
+ * person's name, or any other runtime value — because `extractShape` walks
+ * `Object.keys()` and records each key verbatim as a "field name". A
+ * dynamic key is not a field name; it is a value wearing a field name's
+ * clothes, and this script would write it into the tracked report exactly
+ * as it would refuse to write a value. Point this script only at the three
+ * documented shapes (or another envelope you have separately confirmed has
+ * static keys) — never at an undocumented payload that might carry a
+ * dynamically-keyed map.
+ *
+ * Usage (only meaningful with the experimental flag set):
+ *
+ *     echo '<payload-json>' | \
+ *       CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 npx tsx src/scripts/team_events_spike.ts [EventName]
+ *
+ * `EventName` is optional; if omitted, the payload's own `hook_event_name` /
+ * `event` / `eventName` / `event_name` / `type` field is read and matched
+ * against the three known `TEAM_EVENT_NAMES` — an unrecognised value falls
+ * back to `unlabeled-event` rather than copying the raw (payload-supplied)
+ * string into the report, which would itself be writing a value under the
+ * cover of a "name".
+ *
+ * Without the flag: clean one-line skip, exit 0, stdin is never touched.
+ *
+ * Output: appends one dated section per capture to
+ * `agents/evidence/analysis/team-event-shapes.md`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const OUT_FILE = path.join(ROOT, 'agents', 'evidence', 'analysis', 'team-event-shapes.md');
+
+export const FLAG = 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS';
+export const TEAM_EVENT_NAMES = ['TaskCreated', 'TaskCompleted', 'TeammateIdle'] as const;
+
+export interface ShapeEntry {
+    path: string;
+    type: string;
+}
+
+/** JS/JSON type of a value. Reads only `typeof` / `Array.isArray` — never the value. */
+function _typeOf(value: unknown): string {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    return typeof value; // 'string' | 'number' | 'boolean' | 'object' | 'undefined'
+}
+
+/**
+ * Walk a parsed JSON payload and record field-name + type only.
+ *
+ * This never returns, prints, or embeds a value — recursion is driven
+ * entirely by structural type and object keys.
+ */
+export function extractShape(value: unknown, prefix = ''): ShapeEntry[] {
+    const entries: ShapeEntry[] = [];
+    const t = _typeOf(value);
+    if (prefix !== '') {
+        entries.push({ path: prefix, type: t });
+    }
+    if (t === 'array') {
+        // An event payload's arrays are homogeneous lists, not fixed tuples —
+        // merge every element's shape under one `[]` path (deduped below).
+        for (const item of value as unknown[]) {
+            entries.push(...extractShape(item, `${prefix}[]`));
+        }
+        return entries;
+    }
+    if (t === 'object') {
+        const obj = value as Record<string, unknown>;
+        for (const key of Object.keys(obj).sort()) {
+            entries.push(...extractShape(obj[key], prefix === '' ? key : `${prefix}.${key}`));
+        }
+    }
+    return entries;
+}
+
+/** De-duplicate by path+type — an array's elements repeat the same shape. */
+function _dedupe(entries: ShapeEntry[]): ShapeEntry[] {
+    const seen = new Set<string>();
+    const out: ShapeEntry[] = [];
+    for (const e of entries) {
+        const key = `${e.path}\u0000${e.type}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(e);
+    }
+    return out;
+}
+
+/**
+ * Best-effort event-name inference from the payload's own envelope.
+ *
+ * m4 fix (independent-review finding): the envelope field this reads
+ * (`hook_event_name` / `event` / `type` / …) carries a payload-SUPPLIED
+ * string — copying it verbatim into the recorded report is exactly the
+ * "copy a value into the report" this script otherwise refuses to do
+ * (see the module header's privacy claim). Matched against the known
+ * `TEAM_EVENT_NAMES` allowlist instead: a recognised name is safe to
+ * record because it is drawn from three publicly documented, stable
+ * literals, never from the untrusted payload string itself; anything
+ * else returns `null` and the caller falls back to the fixed literal
+ * `'unlabeled-event'`.
+ */
+export function inferEventName(payload: unknown): string | null {
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return null;
+    const obj = payload as Record<string, unknown>;
+    const known = new Set<string>(TEAM_EVENT_NAMES);
+    for (const key of ['hook_event_name', 'event', 'eventName', 'event_name', 'type']) {
+        const v = obj[key];
+        if (typeof v === 'string' && known.has(v)) return v;
+    }
+    return null;
+}
+
+/** Render one capture as a Markdown section — field names + types only. */
+export function renderShapeReport(eventName: string, entries: ShapeEntry[], observedAt: string): string {
+    const deduped = _dedupe(entries);
+    const rows = deduped.map((e) => `| \`${e.path}\` | ${e.type} |`).join('\n');
+    const table = rows === '' ? '_(empty payload — no fields observed)_' : `| Field | Type |\n|---|---|\n${rows}`;
+    return [`## ${eventName} — observed ${observedAt}`, '', table, ''].join('\n');
+}
+
+function _printGuide(): void {
+    process.stdout.write(
+        [
+            'team-event shape spike (manual, not hook-bound)',
+            '',
+            `${FLAG} is set — recording.`,
+            '',
+            `Observed events: ${TEAM_EVENT_NAMES.join(', ')}`,
+            '',
+            'Pipe one captured JSON payload on stdin — values are never written,',
+            'only field names + types:',
+            '',
+            `  echo '<payload-json>' | ${FLAG}=1 npx tsx src/scripts/team_events_spike.ts [EventName]`,
+            '',
+            `Shapes append to ${path.relative(ROOT, OUT_FILE)}.`,
+            '',
+        ].join('\n'),
+    );
+}
+
+async function _readStdin(): Promise<string> {
+    const chunks: Buffer[] = [];
+    // `for await` streams stdin — a synchronous `readFileSync(0)` EAGAINs
+    // past the pipe buffer on a large payload; this has no such ceiling.
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk as Buffer);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+
+export interface RunResult {
+    skipped: boolean;
+    reason?: string;
+    eventName?: string;
+    entryCount?: number;
+    outFile?: string;
+}
+
+export interface RunOptions {
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+    readStdin?: () => Promise<string>;
+    writeReport?: (section: string) => void;
+    now?: () => string;
+}
+
+/**
+ * Orchestrates the spike. Every side effect is injectable so tests never
+ * touch the real environment, stdin, or the tracked report file.
+ */
+export async function run(opts?: RunOptions): Promise<RunResult> {
+    const env = opts?.env ?? process.env;
+    const argv = opts?.argv ?? process.argv.slice(2);
+    const readStdin = opts?.readStdin ?? _readStdin;
+    const now = opts?.now ?? (() => new Date().toISOString());
+    const writeReport =
+        opts?.writeReport ??
+        ((section: string) => {
+            fs.mkdirSync(path.dirname(OUT_FILE), { recursive: true });
+            fs.appendFileSync(OUT_FILE, section, 'utf-8');
+        });
+
+    if (!env[FLAG]) {
+        const reason = `${FLAG} is not set — teams are experimental and unavailable; skipping.`;
+        process.stdout.write(`${reason}\n`);
+        return { skipped: true, reason };
+    }
+
+    _printGuide();
+    const raw = (await readStdin()).trim();
+    if (raw === '') {
+        const reason = 'no payload received on stdin — nothing recorded.';
+        process.stdout.write(`${reason}\n`);
+        return { skipped: true, reason };
+    }
+
+    let payload: unknown;
+    try {
+        payload = JSON.parse(raw);
+    } catch (e) {
+        const reason = `invalid JSON on stdin: ${(e as Error).message}`;
+        process.stderr.write(`team_events_spike: ${reason}\n`);
+        return { skipped: true, reason };
+    }
+
+    const eventName = argv[0] ?? inferEventName(payload) ?? 'unlabeled-event';
+    const entries = extractShape(payload);
+    const section = renderShapeReport(eventName, entries, now());
+    writeReport(`\n${section}`);
+    const count = _dedupe(entries).length;
+    process.stdout.write(`recorded ${count} field shape(s) for ${eventName} -> ${path.relative(ROOT, OUT_FILE)}\n`);
+    return { skipped: false, eventName, entryCount: count, outFile: OUT_FILE };
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection)
+    // makes the raw URLs differ; compare realpaths so the entry guard still
+    // fires when run through a symlink.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    run()
+        .then(() => {
+            // Observational spike, never a gate — always exit 0 on a
+            // completed run (skip or record alike).
+            process.exit(0);
+        })
+        .catch((e: unknown) => {
+            process.stderr.write(`team_events_spike: ${(e as Error).message}\n`);
+            process.exit(1);
+        });
+}