@joenandez/academy 0.4.0-rc.1

package/scripts/cli/create.mjs

@@ -0,0 +1,242 @@
+import { existsSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pendingMarkerPath } from '../../hooks/memory_store.mjs';
+import {
+  ACADEMY_ROOT,
+  AGENTS_ROOT,
+  CLI_NAME,
+  activeCommandName,
+  NIGHTLY_JOB_CRON,
+  agentDir,
+  contractError,
+  contractOk,
+  LockTimeoutError,
+  RuntimeUnavailableError,
+  resolveExecutable,
+  validateAgentsRoot,
+  validateName,
+} from './core.mjs';
+import { assertNotArchived } from './archived.mjs';
+import { LogCorruptError, appendLifecycleEvent } from './eventlog.mjs';
+import { agentRecord } from './inspect.mjs';
+import { deleteNightlyConsolidation } from './lifecycle.mjs';
+import {
+  renderAcademySystemPrompt,
+  scaffoldBootFiles,
+  writeAgentClaudeMd,
+  writeAgentYaml,
+  writeOwnershipMarker,
+  writePluginSymlink,
+  writeSettingsLocal,
+  writeSkillsScaffold,
+} from './scaffold.mjs';
+
+// Every executable Academy needs is resolved this way so a missing binary
+// raises RuntimeUnavailableError instead of exiting mid-operation.
+export const MUST_EXIST = { throwOnMissing: true };
+
+export function createAgent(name, json = false) {
+  const { dir, nightlyTask } = provisionAgent(name, json);
+  reportCreated(name, dir, nightlyTask, json);
+}
+
+// The one creation path. `create` reports what it returns as a create and the
+// headless hire reports the same thing as a hire, so an agent hired without a
+// terminal is indistinguishable from a created one in ownership, scheduling and
+// events. A second scaffolder would be a second definition of what an Academy
+// agent is, and the two would disagree the first time one of them learned a
+// rule the other did not.
+export function provisionAgent(name, json = false) {
+  const dir = assertAgentNameFree(name, json);
+  scaffoldAgentDir(dir, name, json);
+  const nightlyTask = registerNightlyConsolidationTask(dir, name);
+  if (!nightlyTask.registered && !nightlyTask.skipped) {
+    rmSync(dir, { recursive: true, force: true });
+    failNightlyRegistration(name, nightlyTask, json);
+  }
+  try {
+    appendLifecycleEvent('agent_created', name, dir);
+  } catch (error) {
+    if (nightlyTask.registered) deleteNightlyConsolidation(name, realpathSync(dir));
+    rmSync(dir, { recursive: true, force: true });
+    failLifecyclePublish(name, error, json);
+  }
+  return { dir, nightlyTask };
+}
+
+// The name question, asked before anything is written. The headless hire asks
+// it before it resolves a runtime, so a name that is already taken never
+// becomes a child process holding an explicit write permission.
+export function assertAgentNameFree(name, json = false) {
+  validateName(name);
+  validateAgentsRoot();
+  // A fresh agent must not take a name the holding area still owns: unarchiving
+  // it afterwards could only ever collide.
+  assertNotArchived(name, json);
+  const dir = agentDir(name);
+  if (!existsSync(dir)) return dir;
+  const message = `Agent "${name}" already exists at ${dir}`;
+  if (json) {
+    contractError(activeCommandName(), 'agent_exists', message, { name, dir: resolve(dir) });
+  }
+  console.error(message);
+  process.exit(1);
+}
+
+function scaffoldAgentDir(dir, name, json) {
+  try {
+    mkdirSync(dir, { recursive: false });
+    const today = scaffoldBootFiles(dir, name);
+    writeAgentYaml(dir, name, today);
+    writeAgentClaudeMd(dir, name);
+    writeSkillsScaffold(dir, name);
+    writeSettingsLocal(dir);
+    writePluginSymlink(dir);
+    writeOwnershipMarker(dir, name);
+    renderAcademySystemPrompt(dir, name);
+  } catch (error) {
+    rmSync(dir, { recursive: true, force: true });
+    if (json) throw error;
+    console.error(`Error: failed to create agent "${name}": ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// A host with no scheduler binary used to exit from inside the resolver, which
+// skipped the rollback, the event, and the envelope, and left an orphan agent
+// that no client could see and no retry could replace.
+function failNightlyRegistration(name, nightlyTask, json) {
+  const message = `failed to register nightly consolidation job for "${name}": ${nightlyTask.reason}`;
+  if (json) contractError(activeCommandName(), 'runtime_unavailable', message, { name });
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+// Reached only after the scaffold is rolled back, so the envelope reports a
+// create that left nothing behind.
+function failLifecyclePublish(name, error, json) {
+  const message = `failed to publish lifecycle event for "${name}": ${error.message}`;
+  if (json) {
+    if (error instanceof LockTimeoutError || error instanceof LogCorruptError) {
+      contractError(activeCommandName(), error.code, message, error.fields);
+    }
+    throw error;
+  }
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function reportCreated(name, dir, nightlyTask, json) {
+  if (json) {
+    contractOk('create', {
+      created: true,
+      ...agentRecord(name),
+      scheduledJobId: nightlyTask.registered ? nightlyTask.id : null,
+    });
+    return;
+  }
+
+  console.log(`Created agent "${name}" at ${dir}`);
+  if (nightlyTask.registered) {
+    console.log(
+      `Registered nightly consolidation job "${nightlyTask.id}" (${NIGHTLY_JOB_CRON} ${nightlyTask.timezone}).`,
+    );
+  } else {
+    console.log(`Nightly consolidation job not registered: ${nightlyTask.reason}`);
+  }
+  console.log('');
+  console.log('Next:');
+  console.log(`  ${CLI_NAME} hire           # interactive hire flow to populate the 8 surfaces`);
+  console.log(`  ${CLI_NAME} run ${name}    # launch Claude Code in the agent's home`);
+}
+
+function localTimezone() {
+  return (
+    process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'America/Los_Angeles'
+  );
+}
+
+// The job is registered once and then runs unattended for months, so it carries
+// no runtime: a token here would be a snapshot of the scalar as it stood on
+// registration day, and the child run would rewrite every later operator edit
+// back to it. `nightly` reads the persisted scalar instead.
+export function registerNightlyConsolidationTask(dir, name) {
+  const id = `${name}-nightly-consolidation`;
+  if (process.env.ACADEMY_SKIP_NIGHTLY_TASK === '1') {
+    return {
+      id,
+      registered: false,
+      skipped: true,
+      reason: 'skipped by ACADEMY_SKIP_NIGHTLY_TASK=1',
+    };
+  }
+
+  const timezone = localTimezone();
+  const runArgs = ['nightly', name];
+  let academyBin;
+  let helmTasksBin;
+  try {
+    academyBin = resolveExecutable('ACADEMY_BIN', join(ACADEMY_ROOT, 'bin', 'academy'), MUST_EXIST);
+    helmTasksBin = resolveExecutable('ACADEMY_HELM_TASKS_BIN', 'helm-tasks', MUST_EXIST);
+  } catch (error) {
+    if (!(error instanceof RuntimeUnavailableError)) throw error;
+    return { id, registered: false, reason: error.message };
+  }
+
+  const args = [
+    'schedule',
+    '--cwd',
+    dir,
+    '--id',
+    id,
+    '--cron',
+    NIGHTLY_JOB_CRON,
+    '--timezone',
+    timezone,
+    '--condition-file-exists',
+    pendingMarkerPath(dir),
+    '--command',
+    academyBin,
+    '--env-json',
+    JSON.stringify({ AGENTS_ROOT: resolve(AGENTS_ROOT) }),
+    '--replace',
+    '--tags',
+    'academy,nightly,consolidation',
+    '--timeout-sec',
+    '3600',
+    '--',
+    ...runArgs,
+  ];
+
+  const result = spawnSync(helmTasksBin, args, {
+    cwd: dir,
+    encoding: 'utf8',
+    env: process.env,
+  });
+
+  if (result.error) return { id, registered: false, reason: result.error.message };
+  if (result.status !== 0) {
+    const reason = helmFailureReason(result.stderr || result.stdout, result.status);
+    return { id, registered: false, reason };
+  }
+  return { id, registered: true, timezone };
+}
+
+export function helmFailureReason(output, status) {
+  const fallback = `helm-tasks exited ${status}`;
+  const text = output?.trim();
+  if (!text) return fallback;
+  try {
+    const parsed = JSON.parse(text);
+    const message = parsed.errors?.[0]?.message || parsed.data?.activation?.health?.reason;
+    if (message) return message;
+  } catch {
+    // Fall through to text truncation for non-JSON helm output.
+  }
+  return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `hire` — launch Claude Code with the hire skill loaded
+// ─────────────────────────────────────────────────────────────────────────────

package/scripts/cli/doctor.mjs

@@ -0,0 +1,203 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  ACADEMY_ROOT,
+  AGENTS_ROOT,
+  CONTRACT_VERSION,
+  agentDir,
+  auditAgentsRoot,
+  contractOk,
+  printJson,
+  resolveExecutable,
+} from './core.mjs';
+import { eventLogPath } from './eventlog.mjs';
+import { isAgentDirectory } from './inspect.mjs';
+import { backfillPlan } from './migrate.mjs';
+import { runtimeProviderOrNull } from './runtime.mjs';
+import { unattributableSessionCount } from './sessions.mjs';
+
+// The frozen capability answer at contract_version 1. `notes`, `nightly`,
+// `clean`, `root`, and `run` all keep working and none of them is contract, so
+// none of them appears here: `notes` writes a surface, `root` duplicates
+// `agentsRoot`, `nightly` is called by the scheduler Academy registers, `clean`
+// traces to no criterion, and `run` spawns with inherited stdio and can never
+// emit an envelope.
+const PUBLISHED_COMMANDS = [
+  'doctor',
+  'list',
+  'inspect',
+  'tokens',
+  'budget',
+  'sessions',
+  'events',
+  'create',
+  'hire',
+  'rename',
+  'archive',
+  'unarchive',
+  'delete',
+  'migrate',
+];
+
+/** Published above and built by no phase yet. Empty: every command is real. */
+export const UNIMPLEMENTED_COMMANDS = [];
+
+/** The executable each published provider needs, as [env override, PATH name]. */
+const RUNTIME_EXECUTABLES = {
+  claude_code: ['ACADEMY_CLAUDE_BIN', 'claude'],
+  codex: ['ACADEMY_CODEX_BIN', 'codex'],
+};
+
+// The availability gate. Read-only, and it reports every healthy part of a
+// degraded install rather than failing: a client calls this before it renders
+// anything, so an answer it cannot parse is an Academy it cannot show at all.
+export function reportHealth(json) {
+  const audit = auditAgentsRoot();
+  const payload = {
+    contracts: [CONTRACT_VERSION],
+    version: reportedVersion(),
+    packageRoot: ACADEMY_ROOT,
+    agentsRoot: audit.root,
+    eventLog: eventLogPath(),
+    commands: PUBLISHED_COMMANDS,
+    runtimes: runtimeAvailability(),
+    errors: audit.problem ? [] : healthErrors(),
+  };
+
+  if (audit.problem) return reportUnusableRoot(payload, audit.problem, json);
+  if (json) return contractOk('doctor', payload);
+  printReport(payload);
+}
+
+// The one state answered with ok:false. Academy can still describe itself, but
+// every agent-addressed command raises `unsafe_agent_path` on exactly this
+// root, so a client told ok:true would render an interface whose first call
+// fails. The whole payload ships anyway, because a client parsing the failure
+// still needs the version and contract it is talking to.
+function reportUnusableRoot(payload, problem, json) {
+  if (json) {
+    printJson(
+      {
+        contract_version: CONTRACT_VERSION,
+        ok: false,
+        command: 'doctor',
+        ...payload,
+        error: { code: 'unsafe_agent_path', message: problem, agentsRoot: payload.agentsRoot },
+      },
+      process.stderr,
+    );
+  } else {
+    printReport(payload);
+    console.error(`Error: ${problem}`);
+  }
+  process.exit(1);
+}
+
+// Two builds with different capabilities must never report the same version.
+// A published version covers installs, because npm forbids reusing one. It does
+// not cover checkouts, so a checkout names its own commit as semver build
+// metadata. No `.git` means no checkout — including an install that happens to
+// sit inside somebody else's repository.
+function reportedVersion() {
+  const { version } = JSON.parse(readFileSync(join(ACADEMY_ROOT, 'package.json'), 'utf8'));
+  const build = describeCheckout();
+  return build ? `${version}+${build}` : version;
+}
+
+// Git prefers GIT_DIR over discovery from cwd, and any git hook, `git rebase
+// --exec`, or CI wrapper exports one. Left inherited, two Academy checkouts
+// invoked under the same GIT_DIR report an identical version — the collision
+// `version` exists to prevent. The repository is named outright and every
+// inherited git variable is dropped. `--dirty` walks the work tree, so the one
+// command a client calls before rendering anything is bounded in time too.
+const INHERITED_GIT_VARS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'];
+
+function gitCleanEnv() {
+  const env = { ...process.env };
+  for (const name of INHERITED_GIT_VARS) delete env[name];
+  return env;
+}
+
+function describeCheckout() {
+  if (!existsSync(join(ACADEMY_ROOT, '.git'))) return null;
+  const described = spawnSync(
+    'git',
+    [
+      '--git-dir',
+      join(ACADEMY_ROOT, '.git'),
+      '--work-tree',
+      ACADEMY_ROOT,
+      'describe',
+      '--always',
+      '--dirty',
+    ],
+    { cwd: ACADEMY_ROOT, encoding: 'utf8', timeout: 2000, env: gitCleanEnv() },
+  );
+  if (described.error || described.status !== 0) return null;
+  return described.stdout.trim().replace(/[^0-9A-Za-z-]/g, '-') || null;
+}
+
+function runtimeAvailability() {
+  return Object.fromEntries(
+    Object.entries(RUNTIME_EXECUTABLES).map(([provider, [envName, fallback]]) => [
+      provider,
+      { available: executableExists(envName, fallback) },
+    ]),
+  );
+}
+
+// A probe, not a resolution. `resolveExecutable` exits or throws for the
+// commands that need the binary, and doctor may do neither. The existence check
+// covers an env override pointing at a path that is not there.
+function executableExists(envName, fallback) {
+  try {
+    return existsSync(resolveExecutable(envName, fallback, { throwOnMissing: true }));
+  } catch {
+    return false;
+  }
+}
+
+// The health channel, and it is not the error channel. A code here names a
+// degraded thing and how much of it there is; it never appears inside an
+// `error` object, and none of the fifteen command-failure codes appears here.
+// Zero counts are omitted, so a healthy install reports an empty array.
+// `unowned_agents` is counted from the backfill's own plan, not from a second
+// ownership sweep. A count a client acts on must equal what `migrate` then
+// repairs, and two enumerations of "unowned" drift the moment one of them
+// learns a rule the other has not.
+function healthErrors() {
+  return [
+    { code: 'unowned_agents', count: backfillPlan().repair.length },
+    { code: 'invalid_runtime_agents', count: agentNames().filter(hasUnreadableRuntime).length },
+    { code: 'unattributable_sessions', count: unattributableSessionCount() },
+  ].filter((entry) => entry.count > 0);
+}
+
+function hasUnreadableRuntime(name) {
+  return runtimeProviderOrNull(agentDir(name)) === null;
+}
+
+// Guarded rather than raised: a root that passed the audit and then cannot be
+// listed is still a root doctor must report the rest of the build against.
+function agentNames() {
+  try {
+    return readdirSync(AGENTS_ROOT).filter(isAgentDirectory).sort();
+  } catch {
+    return [];
+  }
+}
+
+function printReport(payload) {
+  console.log(`academy ${payload.version}  contract ${CONTRACT_VERSION}`);
+  console.log(`  packageRoot  ${payload.packageRoot}`);
+  console.log(`  agentsRoot   ${payload.agentsRoot}`);
+  console.log(`  eventLog     ${payload.eventLog}`);
+  for (const [provider, { available }] of Object.entries(payload.runtimes)) {
+    console.log(`  runtime      ${provider.padEnd(12)} ${available ? 'available' : 'unavailable'}`);
+  }
+  console.log(`  commands     ${payload.commands.join(' ')}`);
+  for (const entry of payload.errors) {
+    console.log(`  health       ${entry.code} ${entry.count}`);
+  }
+}

package/scripts/cli/eventlog.mjs

@@ -0,0 +1,129 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { AGENTS_ROOT, withFileLock } from './core.mjs';
+
+// The lifecycle event log is the durable history of every specialist hired and
+// removed. It is append-only and never trimmed, so the sequence it carries is
+// permanent and a client can dedup and resume on it.
+
+function agentsRootParent() {
+  return dirname(resolve(AGENTS_ROOT));
+}
+
+export function eventLogPath() {
+  return join(agentsRootParent(), 'events.jsonl');
+}
+
+// Raised when the event log holds bytes but no record Academy can sequence
+// from. Thrown rather than exited so the caller can roll its work back first.
+export class LogCorruptError extends Error {
+  constructor(message, eventLog) {
+    super(message);
+    this.code = 'log_corrupt';
+    this.fields = { eventLog };
+  }
+}
+
+function readEventLog(eventsPath) {
+  if (!existsSync(eventsPath)) return null;
+  const text = readFileSync(eventsPath, 'utf8');
+  return text.trim() === '' ? null : text;
+}
+
+function recordSeq(line) {
+  if (line.trim() === '') return null;
+  try {
+    const { seq } = JSON.parse(line);
+    return Number.isInteger(seq) && seq >= 1 ? seq : null;
+  } catch {
+    return null;
+  }
+}
+
+// Scan backwards to the last record that parses. A final line torn by a
+// disk-full or a kill -9 must never reset the sequence to 1: duplicate seq
+// values in one log silently corrupt every client that dedups on them.
+function lastSeq(text, eventsPath) {
+  const lines = text.split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const seq = recordSeq(lines[i]);
+    if (seq !== null) return seq;
+  }
+  throw new LogCorruptError(
+    `Event log ${eventsPath} has bytes but no parseable record. Move it aside to start a new log.`,
+    eventsPath,
+  );
+}
+
+function logCreatedRecord() {
+  // The log declares its own identity in its own first record, so a deleted and
+  // rebuilt log is a new logId and a client can tell the epochs apart.
+  return { seq: 1, event: 'log_created', logId: randomUUID(), ts: new Date().toISOString() };
+}
+
+export function appendLifecycleEvent(event, name, dir, extra = {}) {
+  const parent = agentsRootParent();
+  const eventsPath = eventLogPath();
+  withFileLock(join(parent, 'events.lock'), () => {
+    const text = readEventLog(eventsPath);
+    const records = text === null ? [logCreatedRecord()] : [];
+    const previous = text === null ? 1 : lastSeq(text, eventsPath);
+    records.push({
+      seq: previous + 1,
+      event,
+      agentName: name,
+      agentDir: dir,
+      ts: new Date().toISOString(),
+      ...extra,
+    });
+    // A torn final line has no newline. Start a fresh one so this record lands
+    // parseable instead of extending the damaged line.
+    const separator = text !== null && !text.endsWith('\n') ? '\n' : '';
+    appendFileSync(eventsPath, separator + records.map((r) => `${JSON.stringify(r)}\n`).join(''));
+  });
+}
+
+// The replay read. Deliberately more forgiving than the append path: a log with
+// bytes but no parseable record is an operator repair only when Academy is
+// about to write to it. On replay it simply carries no servable sequence, and
+// the one replay rule in `events` answers that without a second code.
+export function readSequencedRecords() {
+  const text = readEventLog(eventLogPath());
+  if (text === null) return [];
+  return text
+    .split('\n')
+    .map(parseRecord)
+    .filter((record) => record !== null);
+}
+
+function parseRecord(line) {
+  if (line.trim() === '') return null;
+  try {
+    const record = JSON.parse(line);
+    return Number.isInteger(record.seq) && record.seq >= 1 ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+// The bounds a client dedups and resumes on, derived from records the caller
+// already holds. A command that ships records must publish the bounds of those
+// same records: read the log twice and the watermark can be strictly newer than
+// the response, so a client adopting it as its resume point skips every record
+// that landed in between, permanently.
+export function boundsOf(records) {
+  if (records.length === 0) return { firstSeq: 0, lastSeq: 0, logId: null };
+  return {
+    firstSeq: records[0].seq,
+    lastSeq: records[records.length - 1].seq,
+    logId: records[0].logId ?? null,
+  };
+}
+
+// `firstSeq` is derived, not assumed: nothing trims, so it reads 1 for every
+// log Academy has written, and deriving it keeps that an observation rather
+// than a promise.
+export function readEventLogWatermark() {
+  return boundsOf(readSequencedRecords());
+}

package/scripts/cli/events.mjs

@@ -0,0 +1,80 @@
+import { checkAgentsRoot, contractOk, exitJsonError } from './core.mjs';
+import { boundsOf, readSequencedRecords } from './eventlog.mjs';
+
+// Delivery is at-least-once and `seq` is the dedup key: a client applies each
+// seq exactly once, so replaying an overlapping range must derive the same
+// state. Nothing here filters by anything but the sequence.
+export function readEvents({ since, logId, json, invalidOption }) {
+  if (invalidOption !== undefined) return unreadableInvocation(invalidOption, json);
+  checkAgentsRoot(json);
+  // One read. The bounds are derived from the very records this call ships, so
+  // the watermark a client adopts can never be newer than what it was given.
+  const records = readSequencedRecords();
+  const bounds = boundsOf(records);
+  const requestedSeq = parseWatermark(since);
+
+  if (!servable(requestedSeq, logId, bounds)) {
+    replayUnavailable(since, logId, bounds, json);
+    return;
+  }
+
+  const events = records.filter((record) => record.seq > requestedSeq);
+  if (json) {
+    contractOk('events', { ...bounds, events });
+    return;
+  }
+  printEvents(bounds, events);
+}
+
+// Answered before the log is touched. A client that asked for --json and got
+// human text has no code, no contract_version and no way to tell a rejected
+// invocation from a crash, so the option it cannot use is named in the envelope.
+// `invalid_spec` is the published code for a request Academy will not accept.
+function unreadableInvocation(option, json) {
+  const message = `Unknown events option: ${option}. Use --since <seq> [--logid <id>] [--json].`;
+  if (json) exitJsonError('invalid_spec', message, { option });
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+/** A watermark is a non-negative integer. Zero means "I have applied nothing". */
+function parseWatermark(since) {
+  return /^\d+$/.test(String(since)) ? Number(since) : null;
+}
+
+// One failure rule, not a table. A watermark that cannot be served exactly is
+// never answered with an empty success, because a client cannot tell that
+// apart from "you are up to date" and would silently diverge.
+function servable(requestedSeq, logId, bounds) {
+  if (requestedSeq === null) return false;
+  if (requestedSeq > bounds.lastSeq) return false;
+  return logId === null || logId === bounds.logId;
+}
+
+function replayUnavailable(since, logId, bounds, json) {
+  const message = logIdMismatch(logId, bounds)
+    ? `Event log ${bounds.logId ?? '(absent)'} is not the log ${logId} this watermark came from. Re-sync from list.`
+    : `Sequence ${since} cannot be served from a log holding ${bounds.firstSeq}..${bounds.lastSeq}. Re-sync from list.`;
+  const fields = { requestedSeq: normaliseRequested(since), ...bounds };
+  if (json) exitJsonError('replay_unavailable', message, fields);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function logIdMismatch(logId, bounds) {
+  return logId !== null && logId !== bounds.logId;
+}
+
+// Echo an unreadable watermark back verbatim so the client can see what it
+// sent; a readable one is echoed as the number it is.
+function normaliseRequested(since) {
+  const parsed = parseWatermark(since);
+  return parsed === null ? String(since) : parsed;
+}
+
+function printEvents(bounds, events) {
+  console.log(`log ${bounds.logId ?? '(none)'}  seq ${bounds.firstSeq}..${bounds.lastSeq}`);
+  for (const record of events) {
+    console.log(`  ${String(record.seq).padStart(6)}  ${record.event}  ${record.agentName ?? ''}`);
+  }
+}