@celilo/cli 0.15.0 → 0.16.1

package/CELILO_SUBSYSTEMS.md

@@ -30,6 +30,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 - **Control-plane network (`secure-mgmt`)** — `apps/celilo/src/hooks/capability-loader.ts` — `loadControlPlaneSubnet` returns the subnet of the zone `celilo-mgmt` is deployed in. `secure-mgmt` is a placement zone AND the control-plane tier, deliberately NOT in `ZONE_TIER_ORDER` (it is not part of the `dmz → app → secure` data-plane chain; it reaches every tier by trust). The firewall's `trustedSubnets` derives from this rather than assuming celilo-mgr sits on `internal`. Reported as an actionable gap by `checkControlPlaneNetwork` in `apps/celilo/src/services/fleet-checks.ts` when the management address matches no configured subnet.
 - **A deployed system's zone** — `apps/celilo/src/services/deployed-systems.ts` — for machine-pool deploys the zone recorded is the ZONE OF THE MACHINE, not `requires.system.zone` (which is only the minimum used to *select* a host, as with sizing). Three writers must agree: `recordDeployedSystemForModule`, `backfillModuleSystems`, and `apps/celilo/src/variables/context.ts` — the last runs latest and will overwrite the others.
 - **Host discovery ("which host serves module X?")** — `apps/celilo/src/cli/commands/module-where.ts` (`celilo module where <id> [--json]`, MCP `celilo_module_where`) — reads deployed hosts from `module_systems` via `getModuleSystems`, reconciles the live Proxmox node via `reconcilePlacement`, and adds a role-based reachability hint per zone. CI/build infra (builder VM, Forgejo runners) is out of scope (not in `module_systems`).
+- **Daemon-journal diagnostic ("what does the module's daemon know that celilo doesn't?")** — `apps/celilo/src/services/module-journal.ts` + `apps/celilo/src/cli/commands/module-journal.ts` (`celilo module journal <id> [--unit|--lines|--since|--grep|--json]`, MCP `celilo_module_journal` on the RO principal) — resolves hosts via `getModuleSystems` and reads each one's systemd journal through the `tailLog` remote primitive. General to every module, not one. **READ-ONLY by construction**: `planJournalRead` is pure and the only remote command the op can emit is a `journalctl` read, so it cannot reconfigure a module, send anything, or consume inbound messages the collection path is waiting for (`module-journal.test.ts` asserts on the exact command reaching the SSH seam). Sibling to `celilo module logs`, which reads the LOCAL Ansible deploy log, not the remote daemon. Unit defaults to the glob `<module-id>*`. An unreachable host reports UNREADABLE, never as an empty journal. Rationale: openspec/changes/fix-signal-inbound-delivery Decision 5.
 
 ## Capability system (cross-module data & functions)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -59,7 +59,7 @@
     "@aws-sdk/client-s3": "^3.1024.0",
     "@celilo/capabilities": "^0.9.1",
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/core": "^0.2.0",
+    "@celilo/core": "^0.3.0",
     "@celilo/event-bus": "^0.1.9",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",

package/src/cli/commands/module-config.test.ts

@@ -11,7 +11,13 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type DbClient, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
-import { handleModuleConfigSet } from './module-config';
+import { resolveDeployPosture } from '../../services/deploy-posture';
+import {
+  FRAMEWORK_CONFIG_KEYS,
+  handleModuleConfigSet,
+  validateFrameworkConfigValue,
+} from './module-config';
+import { pickUpgradePolicy } from './module-upgrade';
 
 describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
   let tempDir: string;
@@ -75,4 +81,74 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
       expect(result.error).not.toContain('vmid'); // infra keys filtered from the hint
     }
   });
+
+  // #515: these describe how celilo TREATS a module, so they must not depend on
+  // the module having declared them. `testmod` declares neither — which is the
+  // bug exactly: `upgrade_policy` was declared by NO module, so `always-safe`
+  // (the only control over unattended-upgrade risk) could never be set.
+  test('accepts upgrade_policy on a module that does not declare it', async () => {
+    const result = await handleModuleConfigSet(['testmod', 'upgrade_policy', 'always-safe']);
+    expect(result.success).toBe(true);
+  });
+
+  test('accepts auto_upgrade on a module that does not declare it', async () => {
+    const result = await handleModuleConfigSet(['testmod', 'auto_upgrade', 'true']);
+    expect(result.success).toBe(true);
+  });
+
+  test('rejects a mistyped policy instead of silently falling back to by-semver', async () => {
+    // `pickUpgradePolicy` fails OPEN: an unrecognized value becomes `by-semver`,
+    // which on a patch means fast posture and NO backup. Accepting this would
+    // leave the operator believing the safe floor was armed.
+    const result = await handleModuleConfigSet(['testmod', 'upgrade_policy', 'alwayssafe']);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('always-safe');
+    }
+  });
+
+  test('rejects a non-boolean auto_upgrade', async () => {
+    const result = await handleModuleConfigSet(['testmod', 'auto_upgrade', 'yes']);
+    expect(result.success).toBe(false);
+  });
+
+  test('the valid-keys hint advertises the celilo-managed keys', async () => {
+    const result = await handleModuleConfigSet(['testmod', 'nope', 'x']);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('upgrade_policy');
+      expect(result.error).toContain('auto_upgrade');
+    }
+  });
+});
+
+describe('validateFrameworkConfigValue (pure)', () => {
+  test('passes through non-framework keys untouched', () => {
+    expect(validateFrameworkConfigValue('app_port', 'anything')).toBeNull();
+  });
+
+  test('accepts every documented value', () => {
+    for (const [key, values] of Object.entries(FRAMEWORK_CONFIG_KEYS)) {
+      for (const v of values) expect(validateFrameworkConfigValue(key, v)).toBeNull();
+    }
+  });
+
+  test('rejects an unlisted value', () => {
+    expect(validateFrameworkConfigValue('upgrade_policy', 'always_safe')).toContain('Allowed');
+  });
+});
+
+// The point of the whole control: with always-safe set, a PATCH upgrade — which
+// by default is fast posture and skips the pre-deploy backup — becomes safe.
+// #515 made this unreachable, so this asserts the chain end to end.
+describe('always-safe actually changes posture on a patch (#515)', () => {
+  test('patch is fast by default, safe once always-safe is chosen', () => {
+    const patch = { installed: '1.0.3', next: '1.0.4' };
+    expect(
+      resolveDeployPosture({ ...patch, modulePolicy: pickUpgradePolicy(undefined) }).posture,
+    ).toBe('fast');
+    expect(
+      resolveDeployPosture({ ...patch, modulePolicy: pickUpgradePolicy('always-safe') }).posture,
+    ).toBe('safe');
+  });
 });

package/src/cli/commands/module-config.ts

@@ -14,6 +14,42 @@ import {
 import { getArg, validateRequiredArgs } from '../parser';
 import type { CommandResult } from '../types';
 
+/**
+ * Operator keys that EVERY module accepts, whether or not its manifest declares
+ * them, with their permitted values.
+ *
+ * These describe how celilo TREATS a module (its CD policy), not how the module
+ * configures itself, so gating them on `variables.owns` had it backwards: it
+ * required each module author to opt into being manageable. The failure was
+ * silent — `upgrade_policy` was declared by no module at all, so
+ * `pickUpgradePolicy()` could only ever read `undefined` and fall back to
+ * `by-semver`, leaving `always-safe` (the ONLY control over unattended-upgrade
+ * risk) permanently unreachable. `auto_upgrade` worked only because lunacycle
+ * happened to declare it. See #515.
+ *
+ * Values are checked at SET time rather than coerced at read time. Both readers
+ * fail OPEN on an unrecognized value — `pickUpgradePolicy()` returns
+ * `by-semver`, which for a patch means fast posture and NO backup. So a typo
+ * like `alwayssafe` would leave the operator believing they had armed the safe
+ * floor while nothing changed. A safety control that fails open on a typo is
+ * worse than no control.
+ */
+export const FRAMEWORK_CONFIG_KEYS: Record<string, readonly string[]> = {
+  auto_upgrade: ['true', 'false'],
+  upgrade_policy: ['by-semver', 'always-safe', 'always-fast'],
+};
+
+/**
+ * PURE (Rule 10.1): validate a framework key's value. Returns an error message,
+ * or null when the key is not a framework key or the value is permitted.
+ */
+export function validateFrameworkConfigValue(key: string, value: string): string | null {
+  const allowed = FRAMEWORK_CONFIG_KEYS[key];
+  if (!allowed) return null;
+  if (allowed.includes(value)) return null;
+  return `Invalid value '${value}' for '${key}'.\n\nAllowed: ${allowed.join(', ')}\n\nRejected rather than coerced: an unrecognized value silently falls back to the PERMISSIVE default (upgrade_policy → by-semver, which skips the pre-deploy backup on a patch), so a typo would look like it took effect.`;
+}
+
 /**
  * Handle module config set command
  *
@@ -54,6 +90,11 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
     };
   }
 
+  // Framework keys bypass the manifest check entirely — see FRAMEWORK_CONFIG_KEYS.
+  const frameworkError = validateFrameworkConfigValue(key, value);
+  if (frameworkError) return { success: false, error: frameworkError };
+  const isFrameworkKey = key in FRAMEWORK_CONFIG_KEYS;
+
   // Validate key against manifest
   const manifest = module.manifestData as Record<string, unknown>;
   const variables = manifest.variables as
@@ -63,14 +104,15 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
 
   // Check if key is declared in manifest
   const declaredVar = declaredVars.find((v) => v.name === key);
-  if (!declaredVar) {
+  if (!declaredVar && !isFrameworkKey) {
     const settableKeys = declaredVars
       .filter((v) => v.source !== 'infrastructure')
       .map((v) => v.name)
       .join(', ');
+    const frameworkKeys = Object.keys(FRAMEWORK_CONFIG_KEYS).join(', ');
     return {
       success: false,
-      error: `Invalid config key '${key}' for module ${moduleId}.\n\nValid keys: ${settableKeys || '(none declared)'}`,
+      error: `Invalid config key '${key}' for module ${moduleId}.\n\nValid keys: ${settableKeys || '(none declared)'}\nCelilo-managed keys (any module): ${frameworkKeys}`,
     };
   }
 
@@ -79,7 +121,7 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
   // variables (vmid, target_ip, target_node, gateway, vlan, lxc_template) are
   // derived by the deploy (IPAM allocates vmid/IP; the container service supplies
   // node/template/gateway/vlan), so a value set here would be ignored.
-  if (declaredVar.source === 'infrastructure') {
+  if (declaredVar?.source === 'infrastructure') {
     return {
       success: false,
       error: `'${key}' is infrastructure-managed by celilo (source: infrastructure) — not operator-settable.\nThe deploy derives it automatically, so a value set here would be silently ignored.\n  • node placement: set the service default for NEW deploys (celilo service reconfigure); move an existing container with 'celilo proxmox migrate' (ISS-0062).\n  • vmid / IP: auto-allocated by IPAM.`,

package/src/cli/commands/module-journal.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test';
+import type { JournalReport } from '../../services/module-journal';
+import { formatJournalReport } from './module-journal';
+
+const system = (over: Partial<JournalReport['systems'][number]> = {}) => ({
+  system: 'signal',
+  hostname: 'signal',
+  ipv4Address: '10.0.20.40',
+  unit: 'signal*',
+  ok: true,
+  lines: [] as string[],
+  ...over,
+});
+
+describe('formatJournalReport', () => {
+  test('renders the journal lines under their host', () => {
+    const { message, allOk } = formatJournalReport({
+      moduleId: 'signal',
+      systems: [system({ lines: ['Received sync sent message'] })],
+    });
+    expect(allOk).toBe(true);
+    expect(message).toContain('signal (10.0.20.40)');
+    expect(message).toContain('Received sync sent message');
+  });
+
+  // The defect class of #501: unreadable must not present as quiet.
+  test('an unreadable host and an empty journal do not look the same', () => {
+    const empty = formatJournalReport({ moduleId: 'signal', systems: [system()] });
+    const broken = formatJournalReport({
+      moduleId: 'signal',
+      systems: [system({ ok: false, error: 'Connection timed out' })],
+    });
+
+    expect(empty.allOk).toBe(true);
+    expect(broken.allOk).toBe(false);
+    expect(broken.message).not.toBe(empty.message);
+    expect(broken.message).toContain('UNREADABLE');
+  });
+
+  test('one unreadable host among several fails the whole read', () => {
+    const { allOk } = formatJournalReport({
+      moduleId: 'forgejo',
+      systems: [system({ lines: ['ok'] }), system({ ok: false, error: 'no route to host' })],
+    });
+    expect(allOk).toBe(false);
+  });
+});

package/src/cli/commands/module-journal.ts

@@ -0,0 +1,98 @@
+/**
+ * Module journal command — read a deployed module's runtime daemon logs
+ * (`journalctl -u <unit>`) through celilo, without SSH to the host.
+ *
+ * Sibling to `celilo module logs`, not an extension of it: `logs` reads the
+ * LOCAL deploy log written by Ansible on celilo-mgr, `journal` reads the
+ * REMOTE daemon's journal on the host that runs the module. Different source,
+ * different failure modes (a host can be unreachable; a log file cannot), and
+ * different answers to different questions. Folding them together would have
+ * meant one command whose meaning depended on a flag.
+ *
+ * Read-only by construction — see services/module-journal.ts.
+ */
+
+import { getDb } from '../../db/client';
+import { type JournalReport, readModuleJournal } from '../../services/module-journal';
+import { getArg, hasFlag, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+const USAGE =
+  'Usage: celilo module journal <id> [--unit <name>] [--lines <n>] [--since <when>] [--grep <pattern>] [--json]';
+
+function numericFlag(value: string | boolean | undefined): number | undefined {
+  return typeof value === 'string' ? Number(value) : undefined;
+}
+
+function stringFlag(value: string | boolean | undefined): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Handle module journal command.
+ */
+export async function handleModuleJournal(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
+  const argError = validateRequiredArgs(args, 1);
+  if (argError) {
+    return { success: false, error: `${argError}\n\n${USAGE}` };
+  }
+
+  const moduleId = getArg(args, 0);
+  if (!moduleId) {
+    return { success: false, error: 'Module ID is required' };
+  }
+
+  const report = readModuleJournal(
+    {
+      moduleId,
+      unit: stringFlag(flags.unit),
+      lines: numericFlag(flags.lines),
+      since: stringFlag(flags.since),
+      grep: stringFlag(flags.grep),
+    },
+    getDb(),
+  );
+
+  if ('error' in report) {
+    return { success: false, error: report.error };
+  }
+
+  if (hasFlag(flags, 'json')) {
+    return {
+      success: true,
+      message: JSON.stringify(report, null, 2),
+      rawOutput: true,
+      data: report,
+    };
+  }
+
+  const { message, allOk } = formatJournalReport(report);
+  return allOk ? { success: true, message } : { success: false, error: message };
+}
+
+/**
+ * Presentation. A host celilo could not read is a FAILURE, not a quiet success
+ * — the defect this whole change exists to fix is unreadable and empty being
+ * byte-identical to the operator.
+ */
+export function formatJournalReport(report: JournalReport): { message: string; allOk: boolean } {
+  const out: string[] = [];
+  for (const sys of report.systems) {
+    out.push(`── ${sys.hostname} (${sys.ipv4Address}) · unit ${sys.unit}`);
+    if (!sys.ok) {
+      out.push(`  ✗ UNREADABLE: ${sys.error}`);
+    } else if (sys.lines.length === 0) {
+      out.push('  (no matching journal lines)');
+    } else {
+      out.push(...sys.lines.map((line) => `  ${line}`));
+    }
+    out.push('');
+  }
+  return {
+    message: out.join('\n').trimEnd(),
+    allOk: report.systems.every((s) => s.ok),
+  };
+}

package/src/cli/completion.ts

@@ -181,6 +181,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'destroy',
       'health',
       'logs',
+      'journal',
       'run-hook',
       'secret',
       'status',
@@ -423,6 +424,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'deploy',
       'destroy',
       'logs',
+      'journal',
       'remove',
       'build',
       'backup',

package/src/cli/generate-zsh-completion.ts

@@ -324,6 +324,10 @@ _celilo_config_keys() {
         fi
         config_keys+=("$key:$desc_text")
       done < <(echo "$manifest_json" | jq -r '.variables.owns[]? | "\\(.name)|\\(.description // "No description")|\\(.required // false)"' 2>/dev/null)
+      # Celilo-managed keys apply to EVERY module regardless of its manifest
+      # (#515), so offer them even when the manifest declares none.
+      config_keys+=("auto_upgrade:Let the registry poll upgrade this module unattended (true|false)")
+      config_keys+=("upgrade_policy:Deploy posture floor for upgrades (by-semver|always-safe|always-fast)")
       if [[ \${#config_keys[@]} -gt 0 ]]; then
         _describe 'config key' config_keys
         return 0

package/src/cli/index.ts

@@ -64,6 +64,7 @@ import { handleModuleDeploy } from './commands/module-deploy';
 import { handleModuleGenerate } from './commands/module-generate';
 import { handleModuleHealth } from './commands/module-health';
 import { handleModuleImport } from './commands/module-import';
+import { handleModuleJournal } from './commands/module-journal';
 import { handleModuleList } from './commands/module-list';
 import { handleModuleLogs } from './commands/module-logs';
 import { handleModuleOperations } from './commands/module-operations';
@@ -1468,6 +1469,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleWhere(parsed.args, parsed.flags);
       case 'logs':
         return handleModuleLogs(parsed.args, parsed.flags);
+      case 'journal':
+        return handleModuleJournal(parsed.args, parsed.flags);
       case 'health':
         return handleModuleHealth(parsed.args, parsed.flags);
       case 'operations':

package/src/services/alerting/inbound-poller.test.ts

@@ -118,6 +118,7 @@ describe('pollInbound', () => {
     });
 
   const alertState = () => db.select().from(alerts).where(eq(alerts.id, 'alert-1')).get()?.state;
+  const ackedBy = () => db.select().from(alerts).where(eq(alerts.id, 'alert-1')).get()?.ackedBy;
 
   test('only transports with routes are polled', () => {
     expect(transportsWithRoutes(db)).toEqual(['signal']);
@@ -326,9 +327,199 @@ describe('pollInbound', () => {
     expect(alertState()).toBe('firing');
   });
 
+  // The seam that was untested. `acknowledgeAlert` returning null was covered
+  // (ack.test.ts), and pollInbound was covered — but not what the REPORT says
+  // when the two meet. Observed live: a reply produced `1 acked` while every
+  // alert still read `ackedBy: null`, because the counter incremented next to
+  // the call instead of observing its result.
+  describe('a token whose alert no longer exists', () => {
+    test('is NOT counted as acked', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run(); // the alert this token names is gone
+
+      const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(report.acked).toBe(0);
+    });
+
+    test('is reported as stale_target rather than silently', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run();
+
+      const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(report.unheard).toEqual([{ senderAddress: PETER, reason: 'stale_target' }]);
+    });
+
+    // The token is still single-use: a dead target must not leave it replayable.
+    test('still consumes the token', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run();
+
+      await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+      const second = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(second.acked).toBe(0);
+      expect(second.unheard).toEqual([{ senderAddress: PETER, reason: 'unknown_token' }]);
+    });
+
+    // Nobody should be told "someone took it" when nobody did.
+    test('broadcasts nothing', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run();
+
+      const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(report.broadcast).toBe(0);
+    });
+  });
+
+  // The counter must track the database, not the attempt. If these two ever
+  // disagree again, the operator sees a success that did not happen.
+  test('report.acked agrees with what the alert row actually says', async () => {
+    const delivery = page(peterRoute.id);
+
+    const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+    expect(report.acked).toBe(1);
+    expect(alertState()).toBe('acked');
+    expect(ackedBy()).toBe(peterRoute.personId);
+  });
+
   test('a route pointing at a transport nobody uses is not polled', () => {
     db.delete(alerts).run();
     expect(transportsWithRoutes(db)).toEqual(['signal']);
     expect(wifeRoute.transportModuleId).toBe('signal');
   });
+
+  /**
+   * Answering a deploy question, at the SEAM.
+   *
+   * This is the coverage #533 was missing. `parseInterviewAnswer` was unit
+   * tested and correct; `pollInbound` was unit tested and correct; and an
+   * answer sent in the shape the page asks for was rejected as `unrecognised`
+   * for months, because nothing exercised an interview delivery THROUGH the
+   * poller. Two green units, wrong wiring — the same shape as the ack counter
+   * above.
+   */
+  describe('an answer to a deploy question', () => {
+    const ask = (routeId: string, eventId = '42') =>
+      mintDelivery(db, {
+        kind: 'interview',
+        targetId: eventId,
+        routeId,
+        now: NOW,
+        ttlMs: 60_000,
+      });
+
+    test('is published against the waiting question and counted as answered', async () => {
+      const question = ask(peterRoute.id, '42');
+      const answered: { eventId: string; value: string }[] = [];
+
+      const report = await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} admin@example.org`)], {
+          answerInterview: (eventId, value) => answered.push({ eventId, value }),
+        }),
+      );
+
+      expect(answered).toEqual([{ eventId: '42', value: 'admin@example.org' }]);
+      expect(report.answered).toBe(1);
+      // An answer is not an acknowledgement; nothing about an alert moved.
+      expect(report.acked).toBe(0);
+      expect(report.unheard).toEqual([]);
+    });
+
+    test('a value containing spaces survives verbatim', async () => {
+      const question = ask(peterRoute.id);
+      const answered: string[] = [];
+
+      await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} my value: with, punctuation`)], {
+          answerInterview: (_id, value) => answered.push(value),
+        }),
+      );
+
+      expect(answered).toEqual(['my value: with, punctuation']);
+    });
+
+    test('the token is consumed, so an answer cannot be replayed', async () => {
+      const question = ask(peterRoute.id);
+      const answered: string[] = [];
+      const withResponder = (body: string) =>
+        pollInbound(
+          db,
+          deps([inbound(PETER, body)], { answerInterview: (_id, v) => answered.push(v) }),
+        );
+
+      await withResponder(`${question.token} first`);
+      const second = await withResponder(`${question.token} second`);
+
+      expect(answered).toEqual(['first']);
+      expect(second.answered).toBe(0);
+      // `unrecognised`, not `unknown_token`: once the token no longer resolves,
+      // `<word> <text>` is indistinguishable from an ordinary sentence, so
+      // celilo declines to assert the operator mistyped a token.
+      expect(second.unheard).toEqual([{ senderAddress: PETER, reason: 'unrecognised' }]);
+    });
+
+    // Naming the question but supplying nothing is its own answer, and the
+    // token must survive so the operator's next attempt can work.
+    test('a token with no value reports needs_value and leaves the token live', async () => {
+      const question = ask(peterRoute.id);
+
+      const first = await pollInbound(
+        db,
+        deps([inbound(PETER, question.token)], { answerInterview: () => {} }),
+      );
+      expect(first.answered).toBe(0);
+      expect(first.unheard).toEqual([{ senderAddress: PETER, reason: 'needs_value' }]);
+
+      const answered: string[] = [];
+      const second = await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} admin@example.org`)], {
+          answerInterview: (_id, v) => answered.push(v),
+        }),
+      );
+      expect(second.answered).toBe(1);
+      expect(answered).toEqual(['admin@example.org']);
+    });
+
+    // With no responder attached there is nothing to publish against, so the
+    // question stays unanswered AND the token stays usable.
+    test('with no responder attached the token is not burned', async () => {
+      const question = ask(peterRoute.id);
+
+      const report = await pollInbound(db, deps([inbound(PETER, `${question.token} value`)]));
+      expect(report.answered).toBe(0);
+      expect(report.unheard).toEqual([{ senderAddress: PETER, reason: 'unrecognised' }]);
+
+      const answered: string[] = [];
+      const retry = await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} value`)], {
+          answerInterview: (_id, v) => answered.push(v),
+        }),
+      );
+      expect(retry.answered).toBe(1);
+      expect(answered).toEqual(['value']);
+    });
+
+    test('an answer from a number the question was not sent to is refused', async () => {
+      const question = ask(peterRoute.id);
+      const answered: string[] = [];
+
+      const report = await pollInbound(
+        db,
+        deps([inbound(WIFE, `${question.token} admin@example.org`)], {
+          answerInterview: (_id, v) => answered.push(v),
+        }),
+      );
+
+      expect(answered).toEqual([]);
+      expect(report.unheard).toEqual([{ senderAddress: WIFE, reason: 'wrong_sender' }]);
+    });
+  });
 });