@celilo/cli 1.2.0 → 1.4.0

package/src/services/aspect-runner.ts

@@ -47,7 +47,7 @@ import {
   EVENT_TYPES,
   busInterviewGuarded,
 } from './bus-interview';
-import { executeAnsible } from './deploy-ansible';
+import { type AnsibleHostRecap, executeAnsible, parseAnsibleRecap } from './deploy-ansible';
 import { getContainerSystemsInZones } from './deployed-systems';
 import { getSystemsByZone } from './machine-pool';
 import { executeProxmoxReconcile, planProxmoxReconcile } from './proxmox-reconcile';
@@ -89,6 +89,12 @@ export interface AspectRunResult {
   error?: string;
   /** The plan that was executed, for caller logging / event emission. */
   plan: AspectFanOutPlan;
+  /**
+   * Per-host `PLAY RECAP` counters. Empty when Ansible produced no recap — a
+   * state callers must NOT read as success. `verifyAspectCoverage` classifies
+   * from this.
+   */
+  recap: AnsibleHostRecap[];
 }
 
 export interface AspectRunOptions {
@@ -101,6 +107,21 @@ export interface AspectRunOptions {
    * they want it, the framework doesn't force a skip).
    */
   excludeHostnames?: string[];
+  /**
+   * Restrict the fan-out to exactly these hostnames, intersected with the
+   * zone-derived target set. Used by the inbound reconcile
+   * (`reconcileAspectsForSystems`), which applies an aspect to the systems a
+   * deploy just created rather than to the whole fleet. Narrows only — a
+   * hostname the aspect's zones do not cover is still not a target.
+   */
+  onlyHostnames?: string[];
+  /**
+   * Run Ansible in CHECK mode: evaluate the role against each target without
+   * changing anything. Used by `verifyAspectCoverage` to ask the HOST whether
+   * an aspect is applied, rather than consulting a stored claim that it once
+   * ran (celilo#902 design D6).
+   */
+  check?: boolean;
   /**
    * Override for noInteractive mode passed to executeAnsible.
    * Defaults to `true` because aspect fan-outs run as part of
@@ -117,8 +138,12 @@ export interface AspectRunOptions {
  */
 export async function planAspectFanOut(
   aspect: BaseModuleAspect,
-  options: Pick<AspectRunOptions, 'excludeHostnames'> = {},
+  options: Pick<AspectRunOptions, 'excludeHostnames' | 'onlyHostnames'> = {},
 ): Promise<AspectFanOutPlan> {
+  // `onlyHostnames` narrows, never widens: it is intersected with the
+  // zone-derived set below rather than replacing it, so an inbound reconcile
+  // cannot apply an aspect to a system outside its `applicable_zones`.
+  const only = options.onlyHostnames ? new Set(options.onlyHostnames) : undefined;
   // Machine-pool systems in the zones (api_only recorded as skips for
   // observability). excludeHostnames is applied by getSystemsByZone.
   const allInZones = await getSystemsByZone(aspect.applicable_zones, {
@@ -134,6 +159,7 @@ export async function planAspectFanOut(
       skipped.push({ machine: m, reason: 'api_only' });
       continue;
     }
+    if (only && !only.has(m.hostname)) continue;
     targetSystems.push({
       hostname: m.hostname,
       ipAddress: m.ipAddress,
@@ -151,6 +177,7 @@ export async function planAspectFanOut(
   const exclude = new Set(options.excludeHostnames ?? []);
   for (const sys of getContainerSystemsInZones(aspect.applicable_zones, getDb())) {
     if (exclude.has(sys.hostname) || seen.has(sys.hostname)) continue;
+    if (only && !only.has(sys.hostname)) continue;
     targetSystems.push({
       hostname: sys.hostname,
       ipAddress: sys.ipv4_address,
@@ -326,13 +353,14 @@ export async function runAspectFanOut(args: {
 
   const plan = await planAspectFanOut(aspect, {
     excludeHostnames: options.excludeHostnames,
+    onlyHostnames: options.onlyHostnames,
   });
 
   if (plan.targetSystems.length === 0) {
     log.info(
       `Aspect fan-out for '${moduleId}' (${options.trigger}): no eligible systems in zones [${aspect.applicable_zones.join(', ')}]`,
     );
-    return { success: true, output: '', plan };
+    return { success: true, output: '', plan, recap: [] };
   }
 
   log.info(
@@ -351,6 +379,7 @@ export async function runAspectFanOut(args: {
 
     const result = await executeAnsible(workDir, {
       noInteractive: options.noInteractive ?? true,
+      check: options.check,
     });
 
     // Proxmox reconciliation (D5): if the aspect declares
@@ -386,6 +415,7 @@ export async function runAspectFanOut(args: {
       output: result.output,
       error: result.error,
       plan,
+      recap: parseAnsibleRecap(result.output),
     };
   } finally {
     if (workDir) {
@@ -458,6 +488,61 @@ export interface AspectGlueResult {
   runResult?: AspectRunResult;
 }
 
+/**
+ * The consent gate, shared by both fan-out directions.
+ *
+ * Already-approved → run. Already-DENIED → skip silently: the operator made a
+ * durable decision and re-prompting every deploy would be nagging (ISS-0027).
+ * Only the undecided ('no_approval') and stale ('scope_changed') states warrant
+ * an interview, and the decision is persisted either way so a denial isn't
+ * re-asked next deploy.
+ *
+ * Extracted so `reconcileAspectsForSystems` cannot drift from
+ * `maybeRunAspectForTrigger`: an inbound reconcile that skipped this would
+ * apply an aspect the operator never approved, or one they refused.
+ */
+async function ensureAspectConsent(args: {
+  moduleId: string;
+  version: string;
+  aspect: BaseModuleAspect;
+  trigger: BaseModuleAspectTrigger;
+  db: DbClient;
+  requestConsent?: AspectConsentRequest;
+}): Promise<{ consented: true } | { consented: false; reason: AspectSkipReason }> {
+  const { moduleId, version, aspect, trigger, db } = args;
+  const approvalStatus = checkAspectApproval(moduleId, version, aspect, db);
+
+  if (approvalStatus === 'denied') {
+    return { consented: false, reason: 'denied' };
+  }
+  if (approvalStatus === 'no_approval' || approvalStatus === 'scope_changed') {
+    // ISS-0027: don't silently skip a declared aspect. Interview the operator
+    // for consent on the bus and WAIT. A responder (terminal, `events reply`,
+    // the celilo-deploy skill) approves or denies.
+    const requestConsent = args.requestConsent ?? requestAspectConsentViaBus;
+    const consented = await requestConsent({
+      moduleId,
+      version,
+      aspect,
+      trigger,
+      reason: approvalStatus,
+    });
+    recordAspectConsent({
+      moduleId,
+      version,
+      scopeHash: computeAspectScopeHash(aspect),
+      approver: process.env.USER ?? null,
+      consented,
+      db,
+    });
+    if (!consented) {
+      log.warn(`Aspect for '${moduleId}' consent refused; aspect skipped (will not re-prompt).`);
+      return { consented: false, reason: 'denied' };
+    }
+  }
+  return { consented: true };
+}
+
 /**
  * Deploy-flow glue (SC4): consulted by `module-deploy.ts` after a
  * primary deploy successfully completes. Decides whether to fan an
@@ -517,40 +602,16 @@ export async function maybeRunAspectForTrigger(args: {
     return { ran: false, reason: 'no_approval' };
   }
 
-  const approvalStatus = checkAspectApproval(moduleId, moduleRow.version, aspect, db);
-
-  // Already-approved → run. Already-DENIED → skip silently: the operator
-  // made a durable decision; re-prompting every deploy would be nagging
-  // (ISS-0027). Only the undecided ('no_approval') and stale ('scope_changed')
-  // states warrant an interview.
-  if (approvalStatus === 'denied') {
-    return { ran: false, reason: 'denied' };
-  }
-  if (approvalStatus === 'no_approval' || approvalStatus === 'scope_changed') {
-    // ISS-0027: don't silently skip a declared aspect. Interview the operator
-    // for consent on the bus and WAIT. A responder (terminal, `events reply`,
-    // the celilo-deploy skill) approves or denies. We persist the decision —
-    // either way — so a denial isn't re-asked next deploy.
-    const requestConsent = args.requestConsent ?? requestAspectConsentViaBus;
-    const consented = await requestConsent({
-      moduleId,
-      version: moduleRow.version,
-      aspect,
-      trigger,
-      reason: approvalStatus,
-    });
-    recordAspectConsent({
-      moduleId,
-      version: moduleRow.version,
-      scopeHash: computeAspectScopeHash(aspect),
-      approver: process.env.USER ?? null,
-      consented,
-      db,
-    });
-    if (!consented) {
-      log.warn(`Aspect for '${moduleId}' consent refused; aspect skipped (will not re-prompt).`);
-      return { ran: false, reason: 'denied' };
-    }
+  const consent = await ensureAspectConsent({
+    moduleId,
+    version: moduleRow.version,
+    aspect,
+    trigger,
+    db,
+    requestConsent: args.requestConsent,
+  });
+  if (!consent.consented) {
+    return { ran: false, reason: consent.reason };
   }
 
   const runner = args.runner ?? runAspectFanOut;
@@ -566,3 +627,313 @@ export async function maybeRunAspectForTrigger(args: {
   });
   return { ran: true, success: runResult.success, runResult };
 }
+
+/**
+ * A system the inbound reconcile may apply aspects to. Deliberately just a
+ * hostname and a zone: the reconcile decides eligibility from the zone and
+ * hands the hostname to `planAspectFanOut`, which already knows how to reach
+ * both a pool machine and a container_service LXC.
+ */
+export interface AspectReconcileSystem {
+  hostname: string;
+  /**
+   * `string`, not `NetworkZone`, to match what everything on this path already
+   * uses: `aspect.applicable_zones` is `string[]` from the manifest schema,
+   * `getSystemsByZone` takes `string[]`, and `DeployedSystem.zone` — the
+   * capability contract this is fed from — is `string`. Narrowing here would
+   * only add a cast at every call site.
+   */
+  zone: string;
+}
+
+/** One provider's aspect, applied (or not) to the systems it covered. */
+export interface AspectReconcileOutcome {
+  /** The module whose aspect this is — NOT the module being deployed. */
+  providerModuleId: string;
+  role: string;
+  /** The subset of the offered systems this aspect's zones actually cover. */
+  hostnames: string[];
+  ran: boolean;
+  success: boolean;
+  error?: string;
+  /** Set when `ran === false`. */
+  reason?: AspectSkipReason | 'paused' | 'not_deployed' | 'no_covered_systems';
+}
+
+export interface AspectReconcileResult {
+  outcomes: AspectReconcileOutcome[];
+  /** The subset that ran and failed — what a caller decides fatality on. */
+  failures: AspectReconcileOutcome[];
+}
+
+/**
+ * The INBOUND direction: given systems that have just come into existence,
+ * apply every approved aspect the fleet already provides that covers their
+ * zones.
+ *
+ * This is the fix for celilo#902. `maybeRunAspectForTrigger` is provider-scoped
+ * — one module's aspect across the whole fleet, enumerated at that instant —
+ * and nothing re-runs it, so a system provisioned later never receives an
+ * aspect and nothing reports the gap.
+ *
+ * TWO THINGS ARE DELIBERATELY NOT CONSULTED HERE, and both are load-bearing:
+ *
+ *  1. `aspect.triggers` (design D2). Eligibility is `applicable_zones` plus
+ *     operator approval, full stop. `triggers` declares which PROVIDER-side
+ *     events cause a fleet-wide fan-out; a system joining a zone is a framework
+ *     event, not a provider event, and the spec's scenario does not condition
+ *     on it either ("every approved aspect whose `applicable_zones` includes
+ *     that zone SHALL run on the new system"). Requiring modules to declare
+ *     `on_new_system_in_zone` would change every aspect's scope hash — raising
+ *     a re-approval interview on the live fleet as a side effect of a bug fix —
+ *     and would make correct convergence opt-in, so the next module that forgot
+ *     the declaration would reintroduce this bug quietly.
+ *  2. The deploying module's own aspect. `on_install` already fans that one out
+ *     across the whole fleet, so the caller passes it in `excludeModuleIds`.
+ *
+ * PAUSED PROVIDERS ARE SKIPPED (design D4a), and that is the documented escape
+ * hatch: an inbound aspect failure is fatal to the deploy that created the
+ * system, so an operator whose non-essential aspect is wedging every deploy
+ * pauses its provider, deploys, and unpauses.
+ *
+ * Consent is checked exactly as the outbound direction checks it, through the
+ * shared `ensureAspectConsent`.
+ */
+export async function reconcileAspectsForSystems(args: {
+  systems: AspectReconcileSystem[];
+  db: DbClient;
+  /** Providers to skip — the deploying module, whose own aspect already ran. */
+  excludeModuleIds?: string[];
+  runner?: typeof runAspectFanOut;
+  requestConsent?: AspectConsentRequest;
+}): Promise<AspectReconcileResult> {
+  const { systems, db } = args;
+  const outcomes: AspectReconcileOutcome[] = [];
+  if (systems.length === 0) return { outcomes, failures: [] };
+
+  const exclude = new Set(args.excludeModuleIds ?? []);
+  const runner = args.runner ?? runAspectFanOut;
+
+  for (const moduleRow of db.select().from(modules).all()) {
+    if (exclude.has(moduleRow.id)) continue;
+
+    const manifest = moduleRow.manifestData as ModuleManifest | null;
+    const aspect = manifest?.base_module_aspect;
+    if (!aspect) continue;
+
+    const base = { providerModuleId: moduleRow.id, role: aspect.ansible_role };
+
+    // A module that never deployed has nothing to fan out FROM — its
+    // ansible_vars resolve against infrastructure that does not exist.
+    if (moduleRow.state !== 'INSTALLED' && moduleRow.state !== 'VERIFIED') {
+      if (moduleRow.state === 'PAUSED') {
+        // Reported rather than silent: pausing to get past a wedged aspect is
+        // legitimate, but it must not quietly become permanent.
+        log.warn(
+          `Aspect '${aspect.ansible_role}' from paused module '${moduleRow.id}' NOT applied to ${systems.map((s) => s.hostname).join(', ')}. Unpause and redeploy it to converge them.`,
+        );
+        outcomes.push({ ...base, hostnames: [], ran: false, success: true, reason: 'paused' });
+        continue;
+      }
+      outcomes.push({ ...base, hostnames: [], ran: false, success: true, reason: 'not_deployed' });
+      continue;
+    }
+
+    const zones = new Set<string>(aspect.applicable_zones);
+    const covered = systems.filter((s) => zones.has(s.zone));
+    if (covered.length === 0) {
+      outcomes.push({
+        ...base,
+        hostnames: [],
+        ran: false,
+        success: true,
+        reason: 'no_covered_systems',
+      });
+      continue;
+    }
+
+    const consent = await ensureAspectConsent({
+      moduleId: moduleRow.id,
+      version: moduleRow.version,
+      aspect,
+      trigger: 'on_new_system_in_zone',
+      db,
+      requestConsent: args.requestConsent,
+    });
+    if (!consent.consented) {
+      outcomes.push({
+        ...base,
+        hostnames: covered.map((s) => s.hostname),
+        ran: false,
+        success: true,
+        reason: consent.reason,
+      });
+      continue;
+    }
+
+    const hostnames = covered.map((s) => s.hostname);
+    log.info(
+      `Applying aspect '${aspect.ansible_role}' from '${moduleRow.id}' to newly created system(s): ${hostnames.join(', ')}`,
+    );
+    const runResult = await runner({
+      moduleId: moduleRow.id,
+      aspect,
+      moduleSourcePath: moduleRow.sourcePath,
+      options: { trigger: 'on_new_system_in_zone', onlyHostnames: hostnames },
+      db,
+    });
+    outcomes.push({
+      ...base,
+      hostnames,
+      ran: true,
+      success: runResult.success,
+      error: runResult.error,
+    });
+  }
+
+  return { outcomes, failures: outcomes.filter((o) => o.ran && !o.success) };
+}
+
+/**
+ * How an aspect stands on one system, as MEASURED against that system.
+ *
+ * `unknown` is not a hedge and must not be collapsed into `applied`. Ansible's
+ * check mode does not evaluate a task that cannot support it — it SKIPS it —
+ * so a role built from `command:` / `shell:` tasks can finish a check run with
+ * `changed=0` having never been applied to the host at all. A two-state answer
+ * would report that as applied: a confidently clean verdict about an
+ * unconverged system, which is the same failure this whole approach exists to
+ * avoid (celilo#902 design D6). Absence of a change is not evidence of
+ * convergence when nothing was assessed.
+ */
+export type AspectCoverageState = 'applied' | 'missing' | 'unknown' | 'unreachable';
+
+export interface AspectCoverageFinding {
+  providerModuleId: string;
+  role: string;
+  hostname: string;
+  state: AspectCoverageState;
+  /** Why, in operator-facing words. Always set for anything but 'applied'. */
+  detail?: string;
+}
+
+/**
+ * Ask every system the fleet's approved aspects entitle it to whether it
+ * actually has them (celilo#902 design D6/D7).
+ *
+ * NOTHING IS STORED AND NOTHING IS READ FROM A RECORD. Both halves of the
+ * question are answered from live state:
+ *
+ *  - "should have" is `planAspectFanOut(aspect)` — literally the code that
+ *    performs the fan-out, so the entitlement set cannot disagree with it. No
+ *    separate query to drift.
+ *  - "does have" is the aspect evaluated against the host in check mode. A row
+ *    saying "applied" would be a claim about a remote host, and celilo has been
+ *    burned by trusting exactly that (celilo#626: `dns_registrations` rows held
+ *    a pinned `ip` and the refresher republished a dead address over correct
+ *    public DNS, with every in-fleet check green).
+ *
+ * This SSHes to every entitled system, so it is not cheap and must not run in a
+ * default `system doctor` pass — it is gated behind `--deep`.
+ *
+ * Consent is checked but never REQUESTED: a read-only diagnostic must not raise
+ * an interview. An aspect that is unapproved, denied, or whose scope changed is
+ * simply not verified.
+ */
+export async function verifyAspectCoverage(args: {
+  db: DbClient;
+  /** Restrict to one provider — `doctor --deep <module>`. */
+  onlyModuleId?: string;
+  /** Injected in tests, exactly as the other entry points here do it. */
+  runner?: typeof runAspectFanOut;
+}): Promise<AspectCoverageFinding[]> {
+  const { db } = args;
+  const runner = args.runner ?? runAspectFanOut;
+  const findings: AspectCoverageFinding[] = [];
+
+  for (const moduleRow of db.select().from(modules).all()) {
+    if (args.onlyModuleId && moduleRow.id !== args.onlyModuleId) continue;
+
+    const manifest = moduleRow.manifestData as ModuleManifest | null;
+    const aspect = manifest?.base_module_aspect;
+    if (!aspect) continue;
+    if (moduleRow.state !== 'INSTALLED' && moduleRow.state !== 'VERIFIED') {
+      // A paused provider's entitled systems are still reported (D4a) — pausing
+      // to get past a wedged aspect is legitimate, but it must not quietly
+      // become permanent. Reported without a probe: the provider is not running
+      // and re-running its role against every host would be a change, not a read.
+      if (moduleRow.state === 'PAUSED') {
+        const plan = await planAspectFanOut(aspect);
+        for (const target of plan.targetSystems) {
+          findings.push({
+            providerModuleId: moduleRow.id,
+            role: aspect.ansible_role,
+            hostname: target.hostname,
+            state: 'unknown',
+            detail: `'${moduleRow.id}' is PAUSED, so its aspect is not being applied to new systems. Unpause and redeploy it to converge.`,
+          });
+        }
+      }
+      continue;
+    }
+    if (checkAspectApproval(moduleRow.id, moduleRow.version, aspect, db) !== 'approved') continue;
+
+    const plan = await planAspectFanOut(aspect);
+    if (plan.targetSystems.length === 0) continue;
+
+    const result = await runner({
+      moduleId: moduleRow.id,
+      aspect,
+      moduleSourcePath: moduleRow.sourcePath,
+      options: { trigger: 'on_new_system_in_zone', check: true, noInteractive: true },
+      db,
+    });
+
+    const byHost = new Map(result.recap.map((r) => [r.host, r]));
+    for (const target of plan.targetSystems) {
+      const base = {
+        providerModuleId: moduleRow.id,
+        role: aspect.ansible_role,
+        hostname: target.hostname,
+      };
+      const recap = byHost.get(target.hostname);
+      if (!recap) {
+        findings.push({
+          ...base,
+          state: 'unknown',
+          detail:
+            'Ansible produced no recap line for this host, so nothing was measured. Absence of a recap is not evidence the aspect is applied.',
+        });
+        continue;
+      }
+      if (recap.unreachable > 0 || recap.failed > 0) {
+        findings.push({
+          ...base,
+          state: 'unreachable',
+          detail: 'The host could not be evaluated — it did not answer, or the role errored on it.',
+        });
+        continue;
+      }
+      if (recap.skipped > 0) {
+        // THE CASE THAT MUST NOT READ AS APPLIED. See AspectCoverageState.
+        findings.push({
+          ...base,
+          state: 'unknown',
+          detail: `The role has ${recap.skipped} task(s) check mode cannot evaluate, so convergence was not measured. Prefer check-capable Ansible modules (copy, template, lineinfile, file, package, service) in aspect roles, or give a command/shell task an honest changed_when:.`,
+        });
+        continue;
+      }
+      if (recap.changed > 0) {
+        findings.push({
+          ...base,
+          state: 'missing',
+          detail: `The aspect would change ${recap.changed} thing(s) on this host, so it is not applied. Run \`celilo module deploy ${moduleRow.id}\` to converge it.`,
+        });
+        continue;
+      }
+      findings.push({ ...base, state: 'applied' });
+    }
+  }
+
+  return findings;
+}

package/src/services/deploy-ansible-recap.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Parsing Ansible's PLAY RECAP, and the one classification that must not be got
+ * wrong.
+ *
+ * `--check` is how `verifyAspectCoverage` asks a HOST whether an aspect is
+ * applied, instead of consulting a stored claim that it once ran (celilo#902
+ * design D6). The trap is that check mode does not evaluate a task it cannot
+ * support — it SKIPS it — so a role built from `command:` / `shell:` tasks can
+ * finish a check run reporting `changed=0` having never been applied at all.
+ *
+ * Read as a boolean ("no changes, therefore applied") that is a confidently
+ * clean answer about an unconverged host: the same failure shape as the stored
+ * verdict this approach exists to avoid, arriving by a different route. Hence
+ * three outcomes, and hence this file.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { parseAnsibleRecap } from './deploy-ansible';
+
+const RECAP = `
+PLAY RECAP *********************************************************************
+caddy-int                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+vpn                        : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+legacy-box                 : ok=1    changed=0    unreachable=0    failed=0    skipped=2    rescued=0    ignored=0
+dead-host                  : ok=0    changed=0    unreachable=1    failed=0    skipped=0    rescued=0    ignored=0
+`;
+
+describe('parseAnsibleRecap', () => {
+  it('reads every host line with its counters', () => {
+    const recaps = parseAnsibleRecap(RECAP);
+    expect(recaps.map((r) => r.host)).toEqual(['caddy-int', 'vpn', 'legacy-box', 'dead-host']);
+    expect(recaps[0]).toEqual({
+      host: 'caddy-int',
+      ok: 3,
+      changed: 0,
+      unreachable: 0,
+      failed: 0,
+      skipped: 0,
+    });
+  });
+
+  it('SKIPPED IS NOT UNCHANGED — the case that must never read as applied', () => {
+    // THE assertion this file exists for. `legacy-box` reports zero changes,
+    // which a two-state reading calls "applied". It is not: two of its tasks
+    // were never evaluated, so nothing about its convergence was measured.
+    // If this ever passes while a caller treats it as applied, celilo is once
+    // again confidently reporting a host it has not looked at.
+    const legacy = parseAnsibleRecap(RECAP).find((r) => r.host === 'legacy-box');
+    expect(legacy).toBeDefined();
+    expect(legacy?.changed).toBe(0);
+    expect(legacy?.skipped).toBeGreaterThan(0);
+  });
+
+  it('separates a host that could not be reached from one that was measured clean', () => {
+    const recaps = parseAnsibleRecap(RECAP);
+    expect(recaps.find((r) => r.host === 'dead-host')?.unreachable).toBe(1);
+    expect(recaps.find((r) => r.host === 'caddy-int')?.unreachable).toBe(0);
+  });
+
+  it('survives ANSI colour, which the progress filter leaves in', () => {
+    const coloured =
+      '\x1b[0;32mweb-01\x1b[0m                 : ok=5    changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0';
+    const [recap] = parseAnsibleRecap(coloured);
+    expect(recap.host).toBe('web-01');
+    expect(recap.changed).toBe(2);
+    expect(recap.skipped).toBe(1);
+  });
+
+  it('returns nothing for output with no recap, rather than inventing a clean one', () => {
+    // A run that produced no recap measured nothing. Callers must not read an
+    // empty array as "every host is fine" — verifyAspectCoverage classifies a
+    // host with no recap line as unknown for exactly this reason.
+    expect(parseAnsibleRecap('fatal: could not connect\n')).toEqual([]);
+    expect(parseAnsibleRecap('')).toEqual([]);
+  });
+});

package/src/services/deploy-ansible.ts

@@ -138,7 +138,7 @@ function parseAnsibleLine(line: string): string | null {
  */
 export async function executeAnsible(
   generatedPath: string,
-  options?: { noInteractive?: boolean },
+  options?: { noInteractive?: boolean; check?: boolean },
 ): Promise<AnsibleResult> {
   const ansibleDir = join(generatedPath, 'ansible');
   const inventoryPath = join(ansibleDir, 'inventory', 'hosts.ini');
@@ -161,6 +161,11 @@ export async function executeAnsible(
         shellEscape(inventoryPath),
         '--vault-password-file',
         shellEscape(passwordPath),
+        // `--check` evaluates the play without changing anything, so a caller
+        // can ask "is this already applied?" of the HOST rather than of a
+        // stored record of the host (celilo#902 design D6). One argument, not a
+        // second execution path — everything else about the run is identical.
+        ...(options?.check ? ['--check'] : []),
         shellEscape(playbookPath),
       ],
       cwd: ansibleDir,
@@ -200,3 +205,53 @@ export async function executeAnsible(
     await rm(tempDir, { recursive: true, force: true });
   }
 }
+
+/**
+ * One host's line from Ansible's `PLAY RECAP`.
+ *
+ *   web-01   : ok=5    changed=2    unreachable=0    failed=0    skipped=1  …
+ *
+ * `skipped` is the field that matters and the one it is easy not to look at. A
+ * task that does NOT support check mode is not evaluated — it is skipped, and
+ * reported as skipped rather than changed. So a role built from `command:` /
+ * `shell:` tasks finishes a `--check` run with `changed=0` having never been
+ * applied to the host at all. Read as a boolean that says "applied", which is a
+ * confidently clean answer about an unconverged system. Callers must treat
+ * `skipped > 0` as NOT MEASURED rather than as applied.
+ */
+export interface AnsibleHostRecap {
+  host: string;
+  ok: number;
+  changed: number;
+  unreachable: number;
+  failed: number;
+  skipped: number;
+}
+
+const RECAP_LINE =
+  /^(\S+)\s*:\s*ok=(\d+)\s+changed=(\d+)\s+unreachable=(\d+)\s+failed=(\d+)\s+skipped=(\d+)/;
+
+/**
+ * Parse every host line out of an Ansible run's `PLAY RECAP`.
+ *
+ * Tolerant of ANSI colour and of the recap appearing anywhere in the stream,
+ * because the output here has been through a progress filter. Lines that are
+ * not recap lines are ignored rather than throwing — a run that produced no
+ * recap at all returns an empty array, which callers must not read as success.
+ */
+export function parseAnsibleRecap(output: string): AnsibleHostRecap[] {
+  const recaps: AnsibleHostRecap[] = [];
+  for (const raw of output.split('\n')) {
+    const match = RECAP_LINE.exec(raw.replace(ANSI_ESCAPE, '').trim());
+    if (!match) continue;
+    recaps.push({
+      host: match[1],
+      ok: Number(match[2]),
+      changed: Number(match[3]),
+      unreachable: Number(match[4]),
+      failed: Number(match[5]),
+      skipped: Number(match[6]),
+    });
+  }
+  return recaps;
+}