@diffci.com/diffci 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,98 @@
+# DiffCI
+
+DiffCI is a deterministic, change-aware CI planner: given a commit or PR, it builds a real TypeScript
+dependency graph, computes what's actually reachable from the changed files, and proposes which CI
+tasks/tests could safely be skipped - without ever modifying production CI behavior itself. Every mode
+this repository currently implements is observe-and-compare only; nothing here can cancel, skip, or block
+a real CI run.
+
+**This repository moved out of the [DentalPresence.in](https://github.com/adityankale190895/DentalPresence.in)
+monorepo** (previously `diffci/` there) into its own repo on 2026-08-21, once the project outgrew being a
+subfolder. DentalPresence.in remains DiffCI's original dogfooding target - some code (the `planner`
+DentalPresence-specific PATH baseline/task registry, a few fixture tests) still reflects that origin - but
+the research and shadow-validation pipelines are generic and have been exercised against dozens of
+real third-party repositories.
+
+## Current state
+
+Three completed research stages plus an in-progress prospective-validation stage, in order:
+
+- **Stage 0** - a 2,000-delta historical benchmark across 20 real repositories, run through a real
+  Cloudflare orchestrator. Verdict: **GO WITH CONDITIONS**.
+- **Stage 1A** - forensic root-cause investigation of every repository/delta where Stage 0's confidence
+  model degraded to UNSAFE, and of every historical "unsafe miss" candidate. Identified the top 3
+  highest-leverage fixes.
+- **Stage 1B** - implemented those 3 fixes (reachability-aware confidence narrowing, an improved
+  historical safety-measurement methodology, a tsconfig-scope + package.json-diffing fix), validated them
+  live against real repositories (coverage improved, zero contradicted safety cases), and ran a real
+  wall-clock FULL/PATH/DiffCI runtime pilot.
+- **Stage 2** (current) - prospective shadow validation on real, currently-arriving CI events, not more
+  historical benchmarking. A live pipeline (Cloudflare Sandbox Containers + Worker, D1 + R2) observes real
+  repositories, predicts *before* their outcome is known, and later reconciles against the real CI result.
+  Current verdict: **EXTEND SHADOW VALIDATION** - the pipeline is real and defect-free, and since
+  2026-08-21 it runs **autonomously**: a Cron Trigger polls enrolled repositories every 10 minutes
+  (`src/research/cloudflare/shadow-cron.ts`), and the registered **DiffCI Shadow GitHub App**
+  (read-only; see [`docs/github-app-registration.md`](docs/github-app-registration.md)) delivers
+  push/workflow events to `/v1/shadow/webhook` for instant predictions and exactly-on-time
+  reconciliation - this repository shadow-observes itself through that App. See
+  [`docs/research/2026-08-21-stage2-final-report.md`](docs/research/2026-08-21-stage2-final-report.md)
+  for the full picture; what's honestly still missing is real observation volume, working GitHub
+  Actions on our own repositories (account billing), and real design-partner repositories.
+
+Every dated report behind these stages lives in [`docs/research/`](docs/research/) - start with
+`2026-08-21-stage2-architecture.md` for the fullest current picture of what's built vs not, or the
+Stage 0/1A/1B reports for the historical-validation story.
+
+## Architecture
+
+- `src/git/` - Git delta analysis (`analyzeGitDelta`): parses a commit range into a structured,
+  serializable `GitDelta`. Project invariant: **failure to analyze must never be interpreted as
+  permission to skip CI** - a failed analysis returns `{ success: false, error }` explicitly, never a
+  silently-empty affected set.
+- `src/repo/` - the dependency graph engine (`buildDependencyGraph`, TypeScript-compiler-backed) and the
+  impact analyzer (`ImpactAnalyzer`) that turns a graph + delta into a confidence-scored, fallback-aware
+  impact result.
+- `src/planner/` - turns an impact result into an `ExecutionPlan` (`DefaultCIPlanner`): which tasks/tests
+  run, which are skip-candidates, and why.
+- `src/research/` - the Stage 0/1 historical benchmark pipeline: repository sampling, the generic
+  (non-DentalPresence-specific) PATH baseline, the opportunity classifier, historical GitHub CI evidence
+  collection with flakiness detection, and the Cloudflare orchestrator (`src/research/cloudflare/`) that
+  runs all of it at scale.
+- `src/shadow/` - the Stage 2 prospective pipeline: event identity (`event-identity.ts`), failure
+  classification, ground-truth reconciliation (`reconcile.ts`) against real CI outcomes, and (written,
+  not yet registered) GitHub App JWT/webhook code (`github-app.ts`).
+
+## Commands
+
+```bash
+# Type-check and run the full test suite
+npm run check
+
+# Generate an example delta / impact / plan for the current repo's latest commit
+npm run diffci
+npm run impact
+
+# Run a real Stage 0-style historical benchmark locally
+npm run research:stage0
+
+# Deploy the Cloudflare research/shadow Worker (D1 + R2 + Sandbox Containers)
+npm run research:sandbox:deploy
+```
+
+## Install Surfaces
+
+DiffCI is intended to be installable as infrastructure, not only as a hosted shadow experiment:
+
+```yaml
+- uses: DiffCI/DiffCI.com@v1
+```
+
+```bash
+npx @diffci.com/diffci observe
+npx @diffci.com/diffci verify-workflow
+```
+
+The GitHub App remains the easiest shadow-mode entry point. The GitHub Action and npm CLI establish
+the OSS/package distribution path: DiffCI can become an explicit CI dependency while preserving the
+same observe-only contract. See [`docs/distribution.md`](docs/distribution.md) for the package and
+Action positioning.

package/action.yml

@@ -0,0 +1,155 @@
+# DiffCI observer - the GitHub Action a third-party repository installs (Phase 02, 2026-08-26).
+#
+# WHAT THIS DOES: analyses one commit range against the checkout the job already has, writes a JSON
+# report to the runner's temp directory, prints a summary to the job log and the job summary, optionally
+# uploads the report as an artifact, and - only when `api-url` and `api-token` are both set - sends that
+# same report to DiffCI. With no token configured nothing leaves the runner at all.
+#
+# WHAT THIS DOES NOT DO, and cannot: run tests, skip tests, cancel a job, re-order steps, write to the
+# repository, comment on a pull request, or set a check status. There is no input below that turns any
+# of that on, because the claim being tested for seven days is that installing DiffCI leaves CI
+# byte-identical, and a flag that could change what CI runs would eventually be set by accident.
+#
+# INSTALL IT AS ITS OWN JOB. A job of its own is what makes the claim structural rather than careful:
+#
+#   jobs:
+#     diffci:
+#       runs-on: ubuntu-latest
+#       continue-on-error: true         # a DiffCI failure must not become the workflow's conclusion
+#       permissions:
+#         contents: read
+#       steps:
+#         - uses: actions/checkout@v4
+#           with:
+#             fetch-depth: 0            # the base commit must exist locally, or DiffCI refuses
+#         - uses: DiffCI/DiffCI.com@<40-character commit sha>
+#
+# `diffci verify-workflow` checks those properties against your own workflow files and exits non-zero
+# if any of them does not hold. Run it before the observation window starts.
+name: DiffCI observer
+description: Observation-only change-aware CI analysis. Runs nothing, changes nothing, skips nothing.
+branding:
+  icon: eye
+  color: gray-dark
+
+inputs:
+  repository-path:
+    description: The checkout to observe. Defaults to the workspace.
+    required: false
+    default: ${{ github.workspace }}
+  base-sha:
+    description: Base commit. Leave empty to derive it from the event (pull request base, push before).
+    required: false
+    default: ""
+  head-sha:
+    description: Head commit. Must be given together with base-sha.
+    required: false
+    default: ""
+  node-version:
+    description: Node version used to run the observer. Only affects this job.
+    required: false
+    default: "22"
+  report-path:
+    description: Where to write the report. Must be outside the checkout. Defaults to RUNNER_TEMP.
+    required: false
+    default: ""
+  redact-paths:
+    description: Replace every file path in the report with a stable 12-character digest.
+    required: false
+    default: "false"
+  upload-artifact:
+    description: Upload the report as a workflow artifact.
+    required: false
+    default: "true"
+  artifact-name:
+    description: Name of the uploaded artifact.
+    required: false
+    default: diffci-observation
+  artifact-retention-days:
+    description: Retention for the uploaded artifact.
+    required: false
+    default: "7"
+  api-url:
+    description: >-
+      DiffCI ingest endpoint. Leave empty and nothing is sent anywhere - the report stays on the runner
+      as an artifact. Must be https.
+    required: false
+    default: ""
+  api-token:
+    description: >-
+      Ingest token for THIS repository, from a repository secret. Pass it as the workflow expression
+      for secrets.DIFFCI_TOKEN, never as a literal. Nothing is sent without it. (This text deliberately
+      does not spell out the expression: GitHub evaluates expressions inside action metadata, and
+      "secrets" is not a context an action file may use - a literal expression here made the whole
+      action fail to load on every run until 2026-09-06.)
+    required: false
+    default: ""
+  fail-on-error:
+    description: >-
+      Fail this step when the observation refuses or errors. Default false, so a DiffCI problem never
+      shows up as a red step in your CI. Turn it on only while debugging an installation.
+    required: false
+    default: "false"
+
+outputs:
+  report-path:
+    description: Absolute path of the written report.
+    value: ${{ steps.observe.outputs.report-path }}
+  status:
+    description: OBSERVED, REFUSED, or ERROR.
+    value: ${{ steps.observe.outputs.status }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Node for the observer
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    # Installed into the action's own directory, never into the observed repository: nothing here
+    # touches the workspace, its node_modules, or its lockfile. --omit=dev keeps this to TypeScript and
+    # a YAML parser; --ignore-scripts means no dependency of DiffCI's runs code on your runner.
+    - name: Install observer dependencies
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm ci --omit=dev --no-audit --fund=false --ignore-scripts
+
+    - name: Build observer
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: node_modules/.bin/tsc -p tsconfig.client.json
+
+    - name: Observe
+      id: observe
+      shell: bash
+      env:
+        DIFFCI_REPO: ${{ inputs.repository-path }}
+        DIFFCI_BASE: ${{ inputs.base-sha }}
+        DIFFCI_HEAD: ${{ inputs.head-sha }}
+        DIFFCI_OUT: ${{ inputs.report-path }}
+        DIFFCI_REDACT: ${{ inputs.redact-paths }}
+        DIFFCI_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}
+        # Passed through the environment, never on the command line: an argv is visible to every other
+        # process on the runner and shows up in traces. The observer reads these directly and never
+        # prints them.
+        DIFFCI_API_URL: ${{ inputs.api-url }}
+        DIFFCI_TOKEN: ${{ inputs.api-token }}
+      run: |
+        set -euo pipefail
+        args=(observe --repo "$DIFFCI_REPO")
+        if [ -n "$DIFFCI_BASE" ]; then args+=(--base "$DIFFCI_BASE"); fi
+        if [ -n "$DIFFCI_HEAD" ]; then args+=(--head "$DIFFCI_HEAD"); fi
+        if [ -n "$DIFFCI_OUT" ]; then args+=(--out "$DIFFCI_OUT"); fi
+        if [ "$DIFFCI_REDACT" = "true" ]; then args+=(--redact-paths); fi
+        if [ "$DIFFCI_FAIL_ON_ERROR" = "true" ]; then args+=(--fail-on-error); fi
+        node "$GITHUB_ACTION_PATH/dist-client/src/client/cli.js" "${args[@]}"
+
+    - name: Upload observation report
+      if: ${{ inputs.upload-artifact == 'true' && steps.observe.outputs.report-path != '' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ steps.observe.outputs.report-path }}
+        retention-days: ${{ inputs.artifact-retention-days }}
+        if-no-files-found: warn

package/dist-client/src/client/cli.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * `diffci` - the client-side command (Phase 02, 2026-08-26).
+ *
+ * This is the binary a third-party repository runs in its own CI. Everything it does is observation:
+ * it reads a checkout, writes one JSON report to a path outside that checkout, prints a summary,
+ * optionally sends that report to DiffCI, and exits 0. There is no mode in this file that runs, skips,
+ * cancels or re-orders anything, and the absence is deliberate - the seven-day Phase 02 criterion is
+ * "CI byte-identical", and a flag that could change what CI runs is a flag that will eventually be set
+ * by accident.
+ *
+ * Sending is opt-in and off unless both an API URL and a token are supplied (Phase 03). Without them
+ * the observer is exactly what Phase 02 shipped: a local analysis whose output never leaves the runner.
+ *
+ * Commands:
+ *   observe            analyse the checkout and write an observation report
+ *   verify-workflow    check that a DiffCI job in this repository's workflows cannot affect other jobs
+ *   version            print the observer version
+ *
+ * Exit codes: `observe` exits 0 even when it refuses or errors, because a broken observer must not
+ * fail somebody's build; the status is in the report and in the printed summary. `--fail-on-error`
+ * opts out of that, for operators running it deliberately. The one exception is exit 2, for a
+ * misconfigured invocation that would itself break the byte-identical guarantee (a report path inside
+ * the observed checkout) - nothing was observed, and the caller has to change the call. `verify-workflow`
+ * exits 1 on a BLOCKING finding - it is a pre-install check run by a human, not a step inside a build.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { observe, isInsideRepository } from "./observe.js";
+import { submitObservation } from "./submit.js";
+import { auditWorkflows, isNonInterfering } from "./workflow-guard.js";
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const flags = {};
+    let command;
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (!token.startsWith("--")) {
+            command ??= token;
+            continue;
+        }
+        const key = token.slice(2);
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[key] = next;
+            i++;
+        }
+        else {
+            flags[key] = true;
+        }
+    }
+    return { command, flags };
+}
+/**
+ * The observer's own version and commit. Found by walking up from this file rather than by a fixed
+ * relative path, because this module runs both from source (tsx, depth src/client) and from compiled
+ * output (node, depth dist-client/src/client) and a hardcoded `../..` is right in exactly one of them.
+ */
+function observerIdentity() {
+    let current = dirname(import.meta.filename);
+    for (let depth = 0; depth < 8; depth++) {
+        const candidate = join(current, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+                if (parsed.name === "diffci") {
+                    let sha;
+                    try {
+                        sha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: current, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+                    }
+                    catch {
+                        // Installed from a tarball rather than a checkout: there is no commit to report, and
+                        // inventing one would be worse than the field being absent.
+                    }
+                    return { version: parsed.version ?? "0.0.0", root: current, sha };
+                }
+            }
+            catch {
+                // Keep walking - an unreadable package.json above us says nothing about ours.
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return { version: "0.0.0" };
+}
+function defaultReportPath(env) {
+    // RUNNER_TEMP is outside GITHUB_WORKSPACE on every GitHub-hosted runner, which is the property that
+    // matters: the report cannot become an untracked file in the repository being observed.
+    const base = env.RUNNER_TEMP && existsSync(env.RUNNER_TEMP) ? env.RUNNER_TEMP : tmpdir();
+    const stamp = env.GITHUB_RUN_ID ? `${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT ?? "1"}` : String(Date.now());
+    return join(base, `diffci-observation-${stamp}.json`);
+}
+function formatFinding(finding) {
+    const where = finding.job ? `${finding.workflow}#${finding.job}` : finding.workflow;
+    return `  [${finding.severity}] ${finding.code} (${where})\n      ${finding.message}`;
+}
+function summarise(report) {
+    const lines = [];
+    lines.push(`DiffCI observation: ${report.status} (${report.stage})`);
+    if (report.reason)
+        lines.push(`  reason: ${report.reason}`);
+    if (report.commitRange) {
+        lines.push(`  range: ${report.commitRange.baseSha.slice(0, 12)}..${report.commitRange.headSha.slice(0, 12)} (${report.commitRange.source})`);
+    }
+    const result = report.result;
+    if (result) {
+        lines.push(`  verdict: ${result.mode}`);
+        lines.push(`  selection: ${result.selectedTests.length}/${result.totalTestCount} test files, from ${result.changedFileCount} changed file(s)`);
+        lines.push(`  comparator: a simple path-rule CI would have run ${result.pathBaseline.mode === "FULL" ? "everything" : `${result.pathBaseline.selectedTestCount} test file(s)`}`);
+        lines.push(`  graph: ${result.graph.nodes} nodes, confidence ${result.graph.effectiveConfidence ?? result.graph.confidence}`);
+        if (result.fallbackReasons.length > 0) {
+            lines.push(`  fallback: ${result.fallbackReasons.join("; ")}`);
+        }
+        for (const command of result.proposedCommands)
+            lines.push(`  would have run: ${command}`);
+        if (result.commandRefusalReason)
+            lines.push(`  no command: ${result.commandRefusalReason}`);
+        if (result.blindSpot) {
+            lines.push("  blind spot: this repository declares a test framework and DiffCI discovered none of its tests");
+        }
+    }
+    lines.push(`  non-interference: worktree ${report.nonInterference.worktreeUnchanged ? "unchanged" : "CHANGED - report this"}, report written ${report.nonInterference.reportWrittenOutsideRepository ? "outside" : "INSIDE"} the checkout`);
+    const blocking = report.nonInterference.workflowFindings.filter((f) => f.severity === "BLOCKING");
+    if (blocking.length > 0) {
+        lines.push(`  workflow: ${blocking.length} blocking finding(s) - this installation CAN affect other jobs:`);
+        for (const finding of blocking)
+            lines.push(formatFinding(finding));
+    }
+    lines.push("  DiffCI changed nothing: no test was run, skipped, cancelled or re-ordered by this step.");
+    return lines.join("\n");
+}
+async function runObserve(flags, env) {
+    const repoPath = resolve(typeof flags.repo === "string" ? flags.repo : env.GITHUB_WORKSPACE ?? process.cwd());
+    const reportPath = resolve(typeof flags.out === "string" ? flags.out : defaultReportPath(env));
+    if (isInsideRepository(repoPath, reportPath) && flags["allow-in-tree-report"] !== true) {
+        // Refused rather than relocated: a caller who asked for a path inside the checkout may have a
+        // reason, and silently writing somewhere else would make the artifact they collect disappear.
+        console.error(`Refusing to write the report to ${reportPath}: it is inside the repository being observed, where an untracked file changes \`git status\` and can fail a clean-tree check. Pass --out with a path outside the checkout (RUNNER_TEMP is the default), or --allow-in-tree-report to accept that risk.`);
+        return 2;
+    }
+    const identity = observerIdentity();
+    const report = await observe({
+        repoPath,
+        env: env,
+        version: identity.version,
+        engineSha: identity.sha,
+        baseOverride: typeof flags.base === "string" ? flags.base : undefined,
+        headOverride: typeof flags.head === "string" ? flags.head : undefined,
+        redactPaths: flags["redact-paths"] === true,
+        reportPath,
+    });
+    mkdirSync(dirname(reportPath), { recursive: true });
+    writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    const summary = summarise(report);
+    if (flags.json === true) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else if (flags.quiet !== true) {
+        console.log(summary);
+        console.log(`  report: ${reportPath}`);
+    }
+    // Sending happens before the job summary is written, so the summary can say whether it worked.
+    // It is allowed to fail: by this point the report is on disk and (in the action) about to become an
+    // artifact, so a delivery problem costs the observation nothing - it is DiffCI's problem to fix, not
+    // the host repository's build to fail. By this point the report is on
+    // disk and (in the action) about to become an artifact, so a delivery problem costs the observation
+    // nothing - it is DiffCI's problem to fix, not the host repository's build to fail.
+    const apiUrl = typeof flags["api-url"] === "string" ? flags["api-url"] : env.DIFFCI_API_URL;
+    const apiToken = typeof flags["api-token"] === "string" ? flags["api-token"] : env.DIFFCI_TOKEN;
+    let delivery;
+    if (apiUrl && apiToken && flags["no-send"] !== true) {
+        const outcome = await submitObservation({ apiUrl, token: apiToken, report });
+        delivery = outcome.ok
+            ? `sent${outcome.duplicate ? " (already recorded - a re-run or retry of the same observation)" : ""}`
+            : `not sent (${outcome.kind}): ${outcome.message}`;
+        if (flags.quiet !== true)
+            console.log(`  delivery: ${delivery}`);
+    }
+    else if (apiUrl && !apiToken && flags["no-send"] !== true) {
+        delivery = "not sent: an api-url was given with no api-token";
+        if (flags.quiet !== true)
+            console.log(`  delivery: ${delivery}`);
+    }
+    // GitHub renders this under the job. It is the only place most people will ever read a report, so it
+    // says the same thing the report says, including when the answer is "refused" or "not sent".
+    if (env.GITHUB_STEP_SUMMARY) {
+        try {
+            writeFileSync(env.GITHUB_STEP_SUMMARY, `### DiffCI (observation only)\n\n\`\`\`\n${summary}${delivery ? `\n  delivery: ${delivery}` : ""}\n\`\`\`\n`, { flag: "a" });
+        }
+        catch {
+            // Losing the summary is cosmetic; the report on disk is the record.
+        }
+    }
+    if (env.GITHUB_OUTPUT) {
+        try {
+            writeFileSync(env.GITHUB_OUTPUT, `report-path=${reportPath}\nstatus=${report.status}\n`, { flag: "a" });
+        }
+        catch {
+            // Same: the outputs are a convenience for the workflow, not the record.
+        }
+    }
+    if (flags["fail-on-error"] === true && report.status !== "OBSERVED")
+        return 1;
+    return 0;
+}
+function runVerifyWorkflow(flags, env) {
+    const repoPath = resolve(typeof flags.repo === "string" ? flags.repo : env.GITHUB_WORKSPACE ?? process.cwd());
+    const result = auditWorkflows(repoPath);
+    if (result.workflowsScanned.length === 0) {
+        console.log(`No workflow files found under ${join(repoPath, ".github", "workflows")}. Nothing was checked.`);
+        return 1;
+    }
+    console.log(`Scanned ${result.workflowsScanned.length} workflow file(s).`);
+    if (result.observerJobs.length === 0) {
+        console.log("No job runs the DiffCI action. Add one before starting the observation window.");
+        return 1;
+    }
+    console.log(`DiffCI runs in: ${result.observerJobs.join(", ")}`);
+    if (result.findings.length === 0) {
+        console.log("No findings: nothing in these workflows lets the observation change what the rest of CI does.");
+        return 0;
+    }
+    for (const finding of result.findings)
+        console.log(formatFinding(finding));
+    if (isNonInterfering(result)) {
+        console.log("\nNo blocking findings. The observation cannot change what the rest of CI does.");
+        return 0;
+    }
+    console.log("\nBlocking findings above: as written, this installation CAN change what the rest of CI does.");
+    return 1;
+}
+const USAGE = `diffci - observation-only change-aware CI analysis
+
+Usage:
+  diffci observe [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
+                 [--redact-paths] [--json] [--quiet] [--fail-on-error]
+                 [--api-url <url> --api-token <token>] [--no-send]
+  diffci verify-workflow [--repo <path>]
+  diffci version
+
+observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
+verify-workflow checks that the job running DiffCI cannot affect any other job, and exits 1 if it can.
+
+The report is sent only when both --api-url and --api-token are given (or DIFFCI_API_URL and
+DIFFCI_TOKEN are set). A failed send is reported and never fails the step - the report is on disk
+either way. Plain http is refused; the token is never printed.
+`;
+async function main() {
+    const { command, flags } = parseArgs(process.argv);
+    const env = process.env;
+    if (flags.help === true || command === "help" || command === undefined) {
+        console.log(USAGE);
+        process.exitCode = command === undefined ? 1 : 0;
+        return;
+    }
+    switch (command) {
+        case "observe":
+            process.exitCode = await runObserve(flags, env);
+            return;
+        case "verify-workflow":
+            process.exitCode = runVerifyWorkflow(flags, env);
+            return;
+        case "version":
+            console.log(observerIdentity().version);
+            return;
+        default:
+            console.error(`Unknown command "${command}".\n\n${USAGE}`);
+            process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    // Reaching here means a defect outside observe()'s own guard. It still must not take a build down:
+    // the failure is printed, and the exit code stays 0 unless the caller asked otherwise.
+    console.error(`DiffCI observer failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = process.argv.includes("--fail-on-error") ? 1 : 0;
+});