@moor-sh/mcp 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moor-sh/mcp",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "MCP server for moor - lets AI agents (Claude Code, Cursor, etc.) manage your moor projects via the moor HTTP API.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -810,22 +810,27 @@ server.registerTool(
   },
 );
 
-// #80 PR #4: moor_update_apply — kick off a transient-respawner update of
+// #80: moor_update_apply — kick off a transient-respawner update of
 // moor itself. The respawner runs async; this tool returns the audit_id
-// immediately. Poll moor_update_status (or, eventually, moor_update_audit)
-// for the outcome.
+// immediately. Poll moor_update_audit (history of attempts) or
+// moor_update_status (version change) for the outcome.
 //
-// IMPORTANT: PR #4 has no rollback. A failed compose-up / --wait timeout /
-// health check writes a `failed` marker and exits; compose state is left
-// as Compose left it. Recovery: manual `docker compose up`, OR wait for the
-// 30-min stale-in_progress sweep to reclaim the audit row. Automatic
-// rollback (retag + `--pull never`) lands in PR #5.
+// Outcomes (encoded in the audit row's `state` field, surfaced by
+// moor_update_audit):
+//   - success         : new image is healthy.
+//   - failed          : pull failed before moor was replaced (no rollback).
+//   - rolled_back     : up/health failed; rollback to prev image succeeded.
+//   - rollback_failed : up/health failed AND rollback also failed —
+//                       operator must investigate (manual recovery).
+//   - in_progress     : respawner still running.
+//   - crashed         : 30-min grace elapsed without a marker
+//                       (respawner died or moor never read the marker).
 server.registerTool(
   "moor_update_apply",
   {
     title: "Apply moor update (transient respawner)",
     description:
-      "Update moor in-place via a transient respawner container. Runs preflight, enables drain, takes a fresh DB backup, then launches a one-shot Compose-aware respawner that pulls + re-creates the moor service. The respawner writes a marker file when done; this tool returns the audit_id immediately so the caller can poll. PR #4 happy path ONLY — no automatic rollback. A failed up/health writes `failed` and leaves the compose state; recovery may require manual `docker compose up`. Bypass is per-blocker: pass {bypass:['active_work']} to interrupt in-flight builds/execs/crons via the existing shutdown coordinator; {bypass:['unknown_digest']} when the registry comparison was inconclusive. Backup is mandatory and not bypassable.",
+      "Update moor in-place via a transient respawner container. Runs preflight, enables drain, takes a fresh DB backup, then launches a one-shot Compose-aware respawner that pulls + re-creates the moor service. The respawner writes a marker file when done; this tool returns the audit_id immediately so the caller can poll via moor_update_audit. Outcomes: success | failed (pull failed pre-replacement) | rolled_back (up/health failed, automatic rollback succeeded) | rollback_failed (rollback also failed — manual recovery needed) | crashed (no marker after 30-min grace). Bypass is per-blocker: pass {bypass:['active_work']} to interrupt in-flight builds/execs/crons via the existing shutdown coordinator; {bypass:['unknown_digest']} when the registry comparison was inconclusive. Backup is mandatory and not bypassable.",
     inputSchema: z.object({
       target_digest: z
         .string()
@@ -850,7 +855,13 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Update started: audit_id=${audit_id}. Respawner is running async. Poll moor_update_status to watch the version change. Expected transitions: in_progress → success (clean apply) or → failed (compose/health failure; PR #4 has no rollback so the compose state is left where Compose left it). If the new moor never becomes healthy enough to ingest the marker, the audit row may stay in_progress until the 30-min stale sweep marks it crashed — at which point manual recovery (docker compose up) may be required.`,
+            text: `Update started: audit_id=${audit_id}. Respawner is running async. Poll moor_update_audit to watch the outcome, or moor_update_status to watch the version. Possible terminal states:
+  - success         (new image healthy)
+  - failed          (pull failed before moor was replaced)
+  - rolled_back     (up/health failed; automatic rollback succeeded; drain stays on)
+  - rollback_failed (up/health failed AND rollback failed; manual recovery)
+  - crashed         (no marker after 30-min grace; respawner died)
+Recovery: rolled_back means moor is on the previous image again; the failed update is captured in error_log. rollback_failed or crashed mean an operator should investigate (likely manual docker compose up).`,
           },
         ],
       };
@@ -868,6 +879,57 @@ server.registerTool(
   },
 );
 
+// #80 PR #6: moor_update_audit — recent history of moor_update_apply
+// attempts. Read-only diagnostic; the orchestration lives entirely on
+// the moor side. Tail-truncates error_log / rollback_error per-field
+// so a crashed update with a long error doesn't blow up the token
+// budget; opt in to a larger tail when actively debugging.
+//
+// Rendering helpers (shortDigest / fmtDuration / tailLog / renderAuditRow
+// / renderAuditList) live in ./update-audit-render and are unit-tested
+// directly — this tool is a thin shell around them.
+import { MAX_LOG_TAIL_BYTES, renderAuditList, type UpdateAuditApiRow } from "./update-audit-render";
+
+server.registerTool(
+  "moor_update_audit",
+  {
+    title: "Update history (audit log)",
+    description:
+      "Read-only: recent moor_update_apply attempts and their outcomes. Each row shows audit_id, state (success | failed | rolled_back | rollback_failed | in_progress | crashed), duration, digest deltas, backup path, and any error logs. error_log preserves the ORIGINAL apply failure (never overwritten by rollback step details); rollback_error is set only on rollback_failed. Default tail is 4 KiB per log field; pass tail_bytes=0 to omit log bodies entirely (keeps the metadata line and replaces the body with a sized marker), or up to 16384 to read more.",
+    inputSchema: z.object({
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("How many most-recent attempts to return. Default 20, max 200."),
+      tail_bytes: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_LOG_TAIL_BYTES)
+        .optional()
+        .describe(
+          "Max bytes of error_log and rollback_error returned inline per row. Default 4096 (4 KiB). 0 to omit log bodies entirely; 16384 max.",
+        ),
+    }),
+  },
+  async ({ limit, tail_bytes }) => {
+    const qs = new URLSearchParams();
+    if (limit !== undefined) qs.set("limit", String(limit));
+    const path = qs.toString()
+      ? `/api/server/update/audit?${qs.toString()}`
+      : "/api/server/update/audit";
+    const res = await apiGet(path);
+    if (!res.ok) throw new Error(`update audit failed: ${res.status} ${await res.text()}`);
+    const { rows } = (await res.json()) as { rows: UpdateAuditApiRow[] };
+    return {
+      content: [{ type: "text", text: renderAuditList(rows, { tail_bytes }) }],
+    };
+  },
+);
+
 server.registerTool(
   "moor_cleanup_plan",
   {
@@ -2195,6 +2257,191 @@ server.registerTool(
   },
 );
 
+// --- Registry credentials ---
+//
+// Server-wide credentials used by the pull path to attach
+// X-Registry-Auth on /images/create for private images. Read shape
+// is write-only: the raw secret never leaves the API. Tool descriptions
+// flag that *inputs* (add/update) carry the secret over the tool-call
+// path and are visible to the MCP client - same security model as
+// moor_env_set. structuredContent mirrors the API metadata shape so
+// agents can reason over it without scraping the human text.
+
+type RegistryCredentialMetadata = {
+  id: number;
+  hostname: string;
+  username: string;
+  secret: { configured: true; kind: "github_classic_pat" | "github_fine_grained_pat" | "unknown" };
+  created_at: string;
+  updated_at: string;
+};
+
+function renderCredentialLine(c: RegistryCredentialMetadata): string {
+  return `id=${c.id} ${c.hostname} user=${c.username} kind=${c.secret.kind} updated=${c.updated_at}`;
+}
+
+server.registerTool(
+  "moor_registry_credentials_list",
+  {
+    title: "List Registry Credentials",
+    description:
+      "List all stored Docker registry credentials. Returns metadata only - the raw secret value is never returned by any read path. Each row carries `secret: { configured: true, kind }` where kind is derived from known token prefixes (github_classic_pat, github_fine_grained_pat) or 'unknown'.",
+  },
+  async () => {
+    const res = await apiGet("/api/server/registry-credentials");
+    if (!res.ok) throw new Error(`Failed: ${res.status} ${await res.text()}`);
+    const data = (await res.json()) as { rows: RegistryCredentialMetadata[] };
+    const text =
+      data.rows.length === 0
+        ? "No registry credentials configured. The pull path falls back to anonymous for every registry."
+        : data.rows.map(renderCredentialLine).join("\n");
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: { rows: data.rows },
+    };
+  },
+);
+
+server.registerTool(
+  "moor_registry_credential_get",
+  {
+    title: "Get Registry Credential",
+    description:
+      "Get a single stored registry credential by id. Returns metadata only - the raw secret is never returned. Use this before moor_registry_credential_delete to confirm the hostname you intend to delete.",
+    inputSchema: z.object({
+      id: z
+        .number()
+        .int()
+        .positive()
+        .describe("Credential id (from moor_registry_credentials_list)"),
+    }),
+  },
+  async ({ id }) => {
+    const res = await apiGet(`/api/server/registry-credentials/${id}`);
+    if (res.status === 404) throw new Error(`credential id=${id} not found`);
+    if (!res.ok) throw new Error(`Failed: ${res.status} ${await res.text()}`);
+    const row = (await res.json()) as RegistryCredentialMetadata;
+    return {
+      content: [{ type: "text", text: renderCredentialLine(row) }],
+      structuredContent: row as unknown as Record<string, unknown>,
+    };
+  },
+);
+
+server.registerTool(
+  "moor_registry_credential_add",
+  {
+    title: "Add Registry Credential",
+    description:
+      "Store a credential for a Docker registry. The pull path will attach X-Registry-Auth to /images/create whenever an image ref matches this hostname. Hostname must be the bare host as it appears in the image ref (e.g. ghcr.io, docker.io, localhost:5000) - no scheme, no path. Note: the secret value passes through the MCP client and tool-call transport, same security model as moor_env_set; rotate via moor_registry_credential_update if it has been exposed.",
+    inputSchema: z.object({
+      hostname: z
+        .string()
+        .describe(
+          "Bare registry host as parsed from an image ref. Examples: ghcr.io, docker.io, localhost:5000, registry.example.com:5000. No scheme, no path.",
+        ),
+      username: z
+        .string()
+        .describe("Registry username. For GHCR with a classic PAT, use your GitHub username."),
+      secret: z
+        .string()
+        .describe(
+          "Registry password or token. For GHCR, a classic PAT with read:packages is the documented path. Visible to the MCP client on input.",
+        ),
+    }),
+  },
+  async ({ hostname, username, secret }) => {
+    const res = await apiPost("/api/server/registry-credentials", { hostname, username, secret });
+    if (!res.ok) throw new Error(`Failed: ${res.status} ${await res.text()}`);
+    const row = (await res.json()) as RegistryCredentialMetadata;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Added credential for ${row.hostname} (id=${row.id}, kind=${row.secret.kind}).`,
+        },
+      ],
+      structuredContent: row as unknown as Record<string, unknown>,
+    };
+  },
+);
+
+server.registerTool(
+  "moor_registry_credential_update",
+  {
+    title: "Update Registry Credential",
+    description:
+      "Rotate username and/or secret on an existing credential. Hostname is intentionally not patchable - changing the lookup key on an existing row would silently break the pull path. To change hostnames, delete and re-create. Requires at least one of username or secret. Note: the secret value passes through the MCP client on input - same security model as moor_env_set.",
+    inputSchema: z.object({
+      id: z.number().int().positive().describe("Credential id to update"),
+      username: z.string().optional().describe("New username (optional)"),
+      secret: z
+        .string()
+        .optional()
+        .describe("New secret (optional). Visible to the MCP client on input."),
+    }),
+  },
+  async ({ id, username, secret }) => {
+    if (username === undefined && secret === undefined) {
+      throw new Error("must provide at least one of username or secret to update");
+    }
+    const patch: Record<string, string> = {};
+    if (username !== undefined) patch.username = username;
+    if (secret !== undefined) patch.secret = secret;
+    const res = await apiPut(`/api/server/registry-credentials/${id}`, patch);
+    if (res.status === 404) throw new Error(`credential id=${id} not found`);
+    if (!res.ok) throw new Error(`Failed: ${res.status} ${await res.text()}`);
+    const row = (await res.json()) as RegistryCredentialMetadata;
+    const rotated: string[] = [];
+    if (username !== undefined) rotated.push("username");
+    if (secret !== undefined) rotated.push("secret");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Updated credential id=${id} (${row.hostname}): rotated ${rotated.join(" + ")}. kind=${row.secret.kind}.`,
+        },
+      ],
+      structuredContent: row as unknown as Record<string, unknown>,
+    };
+  },
+);
+
+server.registerTool(
+  "moor_registry_credential_delete",
+  {
+    title: "Delete Registry Credential",
+    description:
+      "Delete a stored registry credential. Requires confirm_hostname to match the resolved row's hostname exactly - guards against deleting the wrong row from a stale id. After deletion, pulls for that registry fall back to anonymous. Irreversible.",
+    inputSchema: z.object({
+      id: z.number().int().positive().describe("Credential id to delete"),
+      confirm_hostname: z
+        .string()
+        .describe(
+          "Must equal the credential row's hostname exactly. Resolved via moor_registry_credential_get and compared before deletion.",
+        ),
+    }),
+  },
+  async ({ id, confirm_hostname }) => {
+    const getRes = await apiGet(`/api/server/registry-credentials/${id}`);
+    if (getRes.status === 404) throw new Error(`credential id=${id} not found`);
+    if (!getRes.ok)
+      throw new Error(`Failed to fetch credential: ${getRes.status} ${await getRes.text()}`);
+    const row = (await getRes.json()) as RegistryCredentialMetadata;
+    if (confirm_hostname !== row.hostname) {
+      throw new Error(
+        `confirm_hostname "${confirm_hostname}" does not match resolved hostname "${row.hostname}". Refusing to delete.`,
+      );
+    }
+    const delRes = await apiDelete(`/api/server/registry-credentials/${id}`);
+    if (!delRes.ok) throw new Error(`Failed to delete: ${delRes.status} ${await delRes.text()}`);
+    return {
+      content: [{ type: "text", text: `Deleted credential for ${row.hostname} (id=${id}).` }],
+      structuredContent: { deleted: { id, hostname: row.hostname } },
+    };
+  },
+);
+
 function formatMs(ms: number): string {
   if (ms < 1000) return `${ms}ms`;
   const s = Math.floor(ms / 1000);

package/src/update-audit-render.test.ts

@@ -0,0 +1,171 @@
+// Tests for the moor_update_audit renderer. Pure functions — no
+// network, no DB. Lives next to its consumer so the formatting
+// operators actually see has direct test coverage.
+
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_LOG_TAIL_BYTES,
+  fmtDuration,
+  MAX_LOG_TAIL_BYTES,
+  renderAuditList,
+  renderAuditRow,
+  shortDigest,
+  tailLog,
+  type UpdateAuditApiRow,
+} from "./update-audit-render";
+
+function row(overrides: Partial<UpdateAuditApiRow> = {}): UpdateAuditApiRow {
+  return {
+    id: 1,
+    state: "success",
+    started_at: "2026-05-25 00:00:00",
+    duration_ms: 50_000,
+    from_digest: `sha256:${"a".repeat(64)}`,
+    to_digest: `sha256:${"b".repeat(64)}`,
+    prev_image_id: `sha256:${"c".repeat(64)}`,
+    backup_path: "/app/data/moor.db.backup-1",
+    error_log: null,
+    rollback_error: null,
+    ...overrides,
+  };
+}
+
+describe("shortDigest", () => {
+  test("formats sha256:<64 hex> as sha256:<7>…<7>", () => {
+    expect(shortDigest(`sha256:${"a".repeat(64)}`)).toBe(
+      `sha256:${"a".repeat(7)}…${"a".repeat(7)}`,
+    );
+  });
+  test("strips the repo prefix from repo@sha256:... form", () => {
+    expect(shortDigest(`ghcr.io/caiopizzol/moor@sha256:${"b".repeat(64)}`)).toBe(
+      `sha256:${"b".repeat(7)}…${"b".repeat(7)}`,
+    );
+  });
+  test("non-digest input passes through unchanged", () => {
+    expect(shortDigest("sha256:short")).toBe("sha256:short");
+    expect(shortDigest("not-a-digest")).toBe("not-a-digest");
+  });
+  test("null/undefined → '(none)'", () => {
+    expect(shortDigest(null)).toBe("(none)");
+    expect(shortDigest(undefined)).toBe("(none)");
+  });
+});
+
+describe("fmtDuration", () => {
+  test("null → em dash", () => expect(fmtDuration(null)).toBe("—"));
+  test("sub-second values in ms", () => expect(fmtDuration(420)).toBe("420ms"));
+  test("seconds for [1s, 60s)", () => expect(fmtDuration(50_000)).toBe("50s"));
+  test("minutes+seconds at and above 60s", () => {
+    expect(fmtDuration(60_000)).toBe("1m0s");
+    expect(fmtDuration(125_000)).toBe("2m5s");
+  });
+});
+
+describe("tailLog", () => {
+  test("null/undefined → '' (no field rendered by caller)", () => {
+    expect(tailLog(null, 100)).toBe("");
+    expect(tailLog(undefined, 100)).toBe("");
+  });
+  test("short string passes through unchanged", () => {
+    expect(tailLog("short", 100)).toBe("short");
+  });
+  test("long string is tail-truncated with a visible marker", () => {
+    const big = "x".repeat(10_000);
+    const out = tailLog(big, 1000);
+    expect(out).toContain("[...9000 earlier bytes truncated]");
+    expect(out.endsWith("x".repeat(1000))).toBe(true);
+  });
+  test("tail_bytes=0 elides the field body entirely with a sized marker", () => {
+    const out = tailLog("hello world", 0);
+    expect(out).toBe("[...11 bytes elided (tail_bytes=0)]");
+  });
+  test("tail_bytes=0 on null/undefined → ''", () => {
+    expect(tailLog(null, 0)).toBe("");
+    expect(tailLog(undefined, 0)).toBe("");
+  });
+});
+
+describe("renderAuditRow", () => {
+  test("success: includes id, state, duration, from/to, backup; no error_log line", () => {
+    const out = renderAuditRow(row());
+    expect(out).toContain("audit_id=1");
+    expect(out).toContain("state=success");
+    expect(out).toContain("duration=50s");
+    expect(out).toContain("from: sha256:aaaaaaa");
+    expect(out).toContain("to: sha256:bbbbbbb");
+    expect(out).toContain("prev_image_id: sha256:ccccccc");
+    expect(out).toContain("backup: /app/data/moor.db.backup-1");
+    expect(out).not.toContain("error_log");
+    expect(out).not.toContain("rollback_error");
+  });
+
+  test("rolled_back: error_log shown, rollback_error omitted", () => {
+    const out = renderAuditRow(row({ state: "rolled_back", error_log: "health check failed" }));
+    expect(out).toContain("state=rolled_back");
+    expect(out).toContain("error_log: health check failed");
+    expect(out).not.toContain("rollback_error");
+  });
+
+  test("rollback_failed: BOTH error_log and rollback_error rendered", () => {
+    const out = renderAuditRow(
+      row({
+        state: "rollback_failed",
+        error_log: "apply up failed",
+        rollback_error: "rollback tag failed",
+      }),
+    );
+    expect(out).toContain("state=rollback_failed");
+    expect(out).toContain("error_log: apply up failed");
+    expect(out).toContain("rollback_error: rollback tag failed");
+  });
+
+  test("tail_bytes truncates long error_log per-field with marker", () => {
+    const long = "X".repeat(5000);
+    const out = renderAuditRow(row({ error_log: long }), { tail_bytes: 100 });
+    expect(out).toContain("[...4900 earlier bytes truncated]");
+  });
+
+  test("tail_bytes=0 elides log body but keeps the field line", () => {
+    const out = renderAuditRow(row({ error_log: "anything" }), { tail_bytes: 0 });
+    expect(out).toContain("error_log: [...");
+    expect(out).toContain("bytes elided (tail_bytes=0)");
+    expect(out).not.toContain("anything");
+  });
+
+  test("tail_bytes is clamped to MAX_LOG_TAIL_BYTES", () => {
+    // No assertion against the actual byte count; just verify the
+    // constant is honored and the function tolerates an over-cap input.
+    expect(MAX_LOG_TAIL_BYTES).toBeGreaterThan(DEFAULT_LOG_TAIL_BYTES);
+    const long = "Y".repeat(MAX_LOG_TAIL_BYTES + 1000);
+    const out = renderAuditRow(row({ error_log: long }), { tail_bytes: 999_999 });
+    expect(out).toContain("earlier bytes truncated");
+  });
+
+  test("prev_image_id null → no prev line", () => {
+    const out = renderAuditRow(row({ prev_image_id: null }));
+    expect(out).not.toContain("prev_image_id");
+  });
+
+  test("backup_path null → no backup line", () => {
+    const out = renderAuditRow(row({ backup_path: null }));
+    expect(out).not.toContain("backup:");
+  });
+
+  test("non-digest from/to (rare edge) passes through via shortDigest fallback", () => {
+    const out = renderAuditRow(row({ from_digest: "weird", to_digest: null }));
+    expect(out).toContain("from: weird");
+    expect(out).toContain("to: (none)");
+  });
+});
+
+describe("renderAuditList", () => {
+  test("empty → friendly hint", () => {
+    expect(renderAuditList([])).toContain("no update attempts recorded yet");
+  });
+  test("multi-row separated by blank line", () => {
+    const out = renderAuditList([row({ id: 2 }), row({ id: 1 })]);
+    expect(out.split("\n\n").length).toBe(2);
+    expect(out).toContain("audit_id=2");
+    expect(out).toContain("audit_id=1");
+  });
+});

package/src/update-audit-render.ts

@@ -0,0 +1,94 @@
+// #80 PR #6: pure renderers for moor_update_audit. Lives next to its
+// consumer (the MCP tool) so the formatting that operators actually
+// see has direct test coverage.
+//
+// Each row renders as a multi-line block with id, state, duration,
+// digest deltas, prev_image_id, backup path, and per-field tailed
+// error_log / rollback_error.
+
+/** API row shape returned by GET /api/server/update/audit. Subset of
+ *  the full DB row — only what the renderer needs. */
+export type UpdateAuditApiRow = {
+  id: number;
+  state: string;
+  started_at: string;
+  duration_ms: number | null;
+  from_digest: string | null;
+  to_digest: string | null;
+  prev_image_id: string | null;
+  backup_path: string | null;
+  error_log: string | null;
+  rollback_error: string | null;
+};
+
+export const DEFAULT_LOG_TAIL_BYTES = 4096;
+export const MAX_LOG_TAIL_BYTES = 16384;
+
+/** Pure: short-form a sha256 digest for compact rendering (first 7 +
+ *  last 7). Accepts both raw `sha256:<hex>` and `repo@sha256:<hex>`
+ *  forms; returns the input unchanged on anything else. */
+export function shortDigest(s: string | null | undefined): string {
+  if (!s) return "(none)";
+  const m = s.match(/^(?:[^@]+@)?sha256:([0-9a-f]{64})$/);
+  if (!m) return s;
+  const hex = m[1];
+  return `sha256:${hex.slice(0, 7)}…${hex.slice(-7)}`;
+}
+
+/** Pure: human-readable duration. Mirrors the format moor_runs uses. */
+export function fmtDuration(ms: number | null): string {
+  if (ms == null) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  return `${m}m${rem}s`;
+}
+
+/** Pure: tail-truncate a string to maxBytes with a visible marker.
+ *  maxBytes=0 means omit the field body entirely (returns the marker
+ *  alone). Used per-field for error_log + rollback_error so a
+ *  crashed update with a long log doesn't blow up the token budget. */
+export function tailLog(s: string | null | undefined, maxBytes: number): string {
+  if (s == null) return "";
+  if (maxBytes <= 0) {
+    const enc = new TextEncoder();
+    return `[...${enc.encode(s).length} bytes elided (tail_bytes=0)]`;
+  }
+  const enc = new TextEncoder();
+  const bytes = enc.encode(s);
+  if (bytes.length <= maxBytes) return s;
+  const dropped = bytes.length - maxBytes;
+  const tail = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(dropped));
+  return `[...${dropped} earlier bytes truncated]\n${tail}`;
+}
+
+/** Pure: render one audit row. tail_bytes applies separately to
+ *  error_log and rollback_error; absent fields are skipped. */
+export function renderAuditRow(row: UpdateAuditApiRow, opts: { tail_bytes?: number } = {}): string {
+  const tail = Math.min(opts.tail_bytes ?? DEFAULT_LOG_TAIL_BYTES, MAX_LOG_TAIL_BYTES);
+  const lines: string[] = [
+    `audit_id=${row.id} state=${row.state} duration=${fmtDuration(row.duration_ms)} started=${row.started_at}`,
+    `  from: ${shortDigest(row.from_digest)} → to: ${shortDigest(row.to_digest)}`,
+  ];
+  if (row.prev_image_id) lines.push(`  prev_image_id: ${shortDigest(row.prev_image_id)}`);
+  if (row.backup_path) lines.push(`  backup: ${row.backup_path}`);
+  if (row.error_log) lines.push(`  error_log: ${tailLog(row.error_log, tail)}`);
+  if (row.rollback_error) {
+    lines.push(`  rollback_error: ${tailLog(row.rollback_error, tail)}`);
+  }
+  return lines.join("\n");
+}
+
+/** Pure: render a list of rows separated by a blank line. Empty list
+ *  returns the documented "no updates yet" string. */
+export function renderAuditList(
+  rows: UpdateAuditApiRow[],
+  opts: { tail_bytes?: number } = {},
+): string {
+  if (rows.length === 0) {
+    return "no update attempts recorded yet. Run moor_update_apply to start one.";
+  }
+  return rows.map((r) => renderAuditRow(r, opts)).join("\n\n");
+}