@skillcdn/console 0.3.0 → 0.3.1

package/src/cli/cli.ts

@@ -16,6 +16,7 @@ import {
   type RestClaim,
   type RestDecision,
   type RestMember,
+  type RestPackConnectStarted,
   type RestPerson,
   type RestSkillBrowse,
   type RestSkillFile,
@@ -28,7 +29,9 @@ import {
   type ColorName,
   GOAL_STATES,
   type GoalState,
+  PEOPLE_VISIBILITIES,
   PERSON_ROLES,
+  type PeopleVisibility,
   type PersonRole,
   PROJECT_ROLES,
   PROJECT_VISIBILITIES,
@@ -40,6 +43,7 @@ import {
   TASK_STATES,
   type TaskPriority,
   type TaskState,
+  WEEK_STARTS,
 } from "../vocabulary.js";
 import { loadWebRoot, type WebRoot, WebRootError } from "../web.js";
 import {
@@ -53,7 +57,7 @@ import {
   withLogin,
   withoutLogin,
 } from "./credentials.js";
-import type { DirectorySettings, DirectoryStore } from "./directory.js";
+import { type DirectorySettings, type DirectoryStore, THE_SENTENCE } from "./directory.js";
 import {
   formatAnswer,
   formatCategoryLine,
@@ -80,6 +84,9 @@ import {
   formatVersion,
   formatVersionLine,
   formatWork,
+  formatWorkspace,
+  moment,
+  setMomentZone,
 } from "./format.js";
 import { COMMAND_HELP, helpFor, ownSkillPath, usage } from "./help.js";
 import { describeInstall, type Install, updateCommandFor } from "./install.js";
@@ -310,6 +317,14 @@ async function open(io: CliIo, values: Values): Promise<Session> {
     throw failed(wordsOf(resolved));
   }
   const { url, token } = resolved;
+  // Moments are printed in the workspace's time zone as the login kept it (ADR-0035); the
+  // environment's pair keeps nothing, and they stay as the API gives them.
+  setMomentZone(
+    resolved.via === "login"
+      ? credentials?.logins.find((kept) => kept.url === url && kept.account === resolved.account)
+          ?.timeZone
+      : undefined,
+  );
   const client = clientOf(io, url, token);
   const projectKey = async () =>
     text(values, "project") ?? io.env.CONSOLE_PROJECT ?? directory?.project;
@@ -484,18 +499,25 @@ async function personIdOf(
   return (await personOf(session, value)).id;
 }
 
-/** The person a login names, among the workspace's; the logins are as people sign in. */
+/**
+ * The person a login names, among the workspace's, found by their exact login as people sign in
+ * (ADR-0035): whom the console shows the person, and, for an owner of a project, anyone of the
+ * workspace, so that someone the People page does not show can still be listed.
+ */
 async function personOf(session: Session, login: string): Promise<RestPerson> {
-  const { items } = await session.client.people();
-  const found = items.find((person) => person.login.toLowerCase() === login.toLowerCase());
+  const found = await session.client.findPerson(login);
   if (found === undefined) {
     throw misuse(
-      `Nobody of the workspace is called ${login}. console people lists everyone, by login.`,
+      `Nobody of the workspace is called ${login}, or they are not yours to see. console people lists whom you see, by login.`,
     );
   }
   return found;
 }
 
+/** Who sees whom, as the command takes it: with a hyphen or an underscore. */
+const peopleVisibilityOf = (value: string): PeopleVisibility =>
+  wordOf(value.replaceAll("-", "_"), PEOPLE_VISIBILITIES, "who sees whom");
+
 /** One word of a vocabulary, or the refusal to understand. */
 function wordOf<T extends string>(value: string, words: readonly T[], what: string): T {
   const found = words.find((word) => word === value);
@@ -652,7 +674,14 @@ async function keep(
   }
   const next = withLogin(
     credentials,
-    { url, account: person.login, token, agent, since: new Date(io.now()).toISOString() },
+    {
+      url,
+      account: person.login,
+      token,
+      agent,
+      since: new Date(io.now()).toISOString(),
+      timeZone: me.workspace.timeZone ?? undefined,
+    },
     { default: asDefault },
   );
   const kept = await io.store.save(next);
@@ -826,6 +855,24 @@ function agentOf(env: CliIo["env"]): string | undefined {
   return undefined;
 }
 
+/**
+ * Keeps the workspace's time zone on the login the command used (ADR-0035), so that moments are
+ * printed in it from now on without asking; the environment's pair keeps nothing.
+ */
+async function rememberZone(io: CliIo, session: Session, zone: string | undefined): Promise<void> {
+  setMomentZone(zone);
+  if (session.via !== "login" || session.credentials === undefined) {
+    return;
+  }
+  const kept = session.credentials.logins.find(
+    (login) => login.url === session.url && login.account === session.account,
+  );
+  if (kept === undefined || kept.timeZone === zone) {
+    return;
+  }
+  await io.store.save(withLogin(session.credentials, { ...kept, timeZone: zone }));
+}
+
 const whoami: Command = async (args, io) => {
   const { values } = parse(args, {}, false);
   const session = await open(io, values);
@@ -834,6 +881,7 @@ const whoami: Command = async (args, io) => {
   if (person === null) {
     throw failed("The console does not know this token. Sign in again: console login");
   }
+  await rememberZone(io, session, me.workspace.timeZone ?? undefined);
   const key = await session.projectKey();
   const command = parseVersion(io.version);
   const server = parseVersion(me.console?.version);
@@ -914,12 +962,15 @@ const use: Command = async (args, io) => {
   const bound = pinUrl
     ? ` at ${session.url}${pinAccount && session.account !== undefined ? ` as ${session.account}` : ""}`
     : "";
-  answer(
-    io,
-    session,
-    project,
-    () =>
+  answer(io, session, project, () =>
+    [
       `Working in ${project.name} (${project.key})${bound} from this directory on: kept in ${kept}, which is meant to be committed in a private repository and left out of a public one. What its people ask of agents: console rules.`,
+      // Nothing sends an agent to the console until the checkout says so; the sentence is the
+      // skill's (references/the-sentence.md), printed here as `skillcdn use` prints its own.
+      "Then put this sentence into the checkout's agreement (AGENTS.md, or CLAUDE.md where that is the file agents read), as it is, so that every agent working here is sent to the console:",
+      "",
+      THE_SENTENCE,
+    ].join("\n"),
   );
   return EXIT.ok;
 };
@@ -1333,7 +1384,12 @@ const newTask: Command = async (args, io) => {
     ...(body === undefined ? {} : { body }),
     ...fields,
   });
-  answer(io, session, made, () => `Task #${made.number} written: ${made.title}\nid: ${made.id}`);
+  answer(
+    io,
+    session,
+    made,
+    () => `Task #${made.number} written: ${made.title}\ntask id: ${made.id}`,
+  );
   return EXIT.ok;
 };
 
@@ -1556,6 +1612,9 @@ const take: Command = async (args, io) => {
   answer(io, session, { run, task: taken, comments: comments.items, rules }, () =>
     [
       `Run ${run.id} began on #${found.number} ${found.title}, as "${run.agent}" for ${run.person.login}. The task is in progress and theirs.${tookOver}${elsewhere}`,
+      // The ids on a line of their own, each named: a run's and a task's begin alike, and a
+      // task has a number for people as well.
+      `run id: ${run.id}  task id: ${found.id}  (task #${found.number})`,
       "",
       formatTask(taken, undefined, undefined, comments.items),
       "",
@@ -1701,7 +1760,7 @@ const ask: Command = async (args, io) => {
   io.stdout(
     session.json
       ? `${JSON.stringify(raised, null, 2)}\n`
-      : `Decision ${raised.id} raised on run ${runId}; the run waits for a person.\n${formatOptions(raised)}\n`,
+      : `Decision ${raised.id} raised on run ${runId}; the run waits for a person.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
   );
   return settle(io, session, project, raised, seconds, true);
 };
@@ -1950,7 +2009,7 @@ const newGoal: Command = async (args, io) => {
     ...(startsOn === undefined ? {} : { startsOn }),
     ...(dueOn === undefined ? {} : { dueOn }),
   });
-  answer(io, session, made, () => `Goal set: ${made.title}\nid: ${made.id}`);
+  answer(io, session, made, () => `Goal set: ${made.title}\ngoal id: ${made.id}`);
   return EXIT.ok;
 };
 
@@ -2186,6 +2245,81 @@ const people: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+// The workspace's settings (ADR-0035): read by everyone, changed by an administrator, themselves
+// on the Settings page or through their agent here (ADR-0021).
+const WORKSPACE_FLAGS =
+  "--people-visibility <everyone|shared-projects>, --week-start <auto|monday|sunday>, --time-zone <zone|none>";
+const WORKSPACE_USAGE = `Say what to do: console workspace  |  console workspace edit [${WORKSPACE_FLAGS.replaceAll(", ", "] [")}]  |  console workspace pack-token --connect|--stdin|--remove`;
+
+const workspace: Command = async (args, io) => {
+  const [verb, ...rest] = args;
+  if (verb === undefined || verb.startsWith("--")) {
+    const { values } = parse(args, {}, false);
+    const session = await open(io, values);
+    const me = await session.client.me();
+    await rememberZone(io, session, me.workspace.timeZone ?? undefined);
+    answer(io, session, me.workspace, () => formatWorkspace(me.workspace));
+    return EXIT.ok;
+  }
+  if (verb === "edit") {
+    const { values } = parse(
+      rest,
+      {
+        "people-visibility": { type: "string" },
+        "week-start": { type: "string" },
+        "time-zone": { type: "string" },
+      },
+      false,
+    );
+    const visibility = text(values, "people-visibility");
+    const weekStart = text(values, "week-start");
+    const zone = text(values, "time-zone");
+    if (visibility === undefined && weekStart === undefined && zone === undefined) {
+      throw misuse(`Say what to change: ${WORKSPACE_FLAGS}`);
+    }
+    const session = await open(io, values);
+    const changed = await session.client.updateWorkspace({
+      ...(visibility === undefined ? {} : { peopleVisibility: peopleVisibilityOf(visibility) }),
+      ...(weekStart === undefined
+        ? {}
+        : { weekStart: wordOf(weekStart, WEEK_STARTS, "a day the week begins on") }),
+      ...(zone === undefined ? {} : { timeZone: zone === "none" ? null : zone }),
+    });
+    await rememberZone(io, session, changed.timeZone ?? undefined);
+    answer(io, session, changed, () => formatWorkspace(changed));
+    return EXIT.ok;
+  }
+  if (verb === "pack-token") {
+    const { values, positionals } = parse(rest, PACK_TOKEN_FLAGS);
+    if (positionals.length > 0) {
+      throw misuse(
+        "The workspace's token names no project: console workspace pack-token --connect, --stdin or --remove",
+      );
+    }
+    const way = wayOf(values);
+    const session = await open(io, values);
+    const { client } = session;
+    return packToken(
+      io,
+      session,
+      way,
+      {
+        set: (token) => client.setWorkspacePackToken({ token }),
+        remove: () => client.removeWorkspacePackToken(),
+        connect: () => client.connectWorkspacePackToken(),
+        async standing() {
+          const state = await client.workspacePackTokenConnection();
+          return state.status === "connected"
+            ? { status: "connected", held: state.workspace }
+            : state;
+        },
+      },
+      formatWorkspace,
+    );
+  }
+  throw misuse(WORKSPACE_USAGE);
+};
+
 const PERSON_USAGE =
   "Say what to do: console person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>";
 
@@ -2309,35 +2443,118 @@ const editProject: Command = async (args, io) => {
   return EXIT.ok;
 };
 
-/** The pack token (ADR-0028): read from standard input and never from an argument, so that no shell keeps it. */
-const projectPackToken: Command = async (args, io) => {
-  const { values, positionals } = parse(args, {
-    stdin: { type: "boolean" },
-    remove: { type: "boolean" },
-  });
-  const key = theOne(
-    positionals,
-    "Say which project: console project pack-token <key> --stdin, or console project pack-token <key> --remove",
-  );
-  if (on(values, "stdin") === on(values, "remove")) {
+/** How a pack's connection ended short of a token (ADR-0036), in words for the person. */
+const PACK_CONNECT_ENDED = {
+  expired: "The code expired before anyone approved it. Run the command again for a new one.",
+  declined: "The request was declined at SkillCDN, or the code was spent.",
+  refused:
+    "SkillCDN refused the request: the repository is not one the person may open, the pack is public and needs no token, or they hold as many tokens as one may.",
+} as const;
+
+/** How a SkillCDN token is to change, one of the three the flags name. */
+const wayOf = (values: Values): "connect" | "stdin" | "remove" => {
+  const ways = (["connect", "stdin", "remove"] as const).filter((way) => on(values, way));
+  const [way] = ways;
+  if (way === undefined || ways.length !== 1) {
     throw misuse(
-      "Say one of --stdin, which reads the token from standard input, and --remove, which takes it away.",
+      "Say one of --connect, which asks SkillCDN for a code a person approves; --stdin, which reads a token made by hand from standard input; and --remove, which takes the token away.",
     );
   }
-  const session = await open(io, values);
-  const project = session.client.project(key);
-  if (on(values, "remove")) {
-    const changed = await project.removePackToken();
-    answer(io, session, changed, () => formatProject(changed));
+  return way;
+};
+
+/** Whose SkillCDN token the command works: a project's, or the workspace's for the organization's pack. */
+interface TokenHolder<T> {
+  set(token: string): Promise<T>;
+  remove(): Promise<T>;
+  connect(): Promise<RestPackConnectStarted>;
+  standing(): Promise<
+    | { readonly status: "none" }
+    | { readonly status: "pending" }
+    | { readonly status: "ended"; readonly reason: keyof typeof PACK_CONNECT_ENDED }
+    | { readonly status: "connected"; readonly held: T }
+  >;
+}
+
+/**
+ * The SkillCDN token (ADR-0028): connected with a code a person approves at SkillCDN (ADR-0036),
+ * or read from standard input and never from an argument, so that no shell keeps it; or taken
+ * away. The same for a project's and for the workspace's.
+ */
+async function packToken<T>(
+  io: CliIo,
+  session: Session,
+  way: "connect" | "stdin" | "remove",
+  holder: TokenHolder<T>,
+  format: (held: T) => string,
+): Promise<number> {
+  if (way === "remove") {
+    const changed = await holder.remove();
+    answer(io, session, changed, () => format(changed));
     return EXIT.ok;
   }
+  if (way === "connect") {
+    const started = await holder.connect();
+    io.stdout(
+      `To connect the pack, a person who may open its repository opens ${started.url} signed in at SkillCDN, checks that the page shows the code ${started.code}, and approves; the console receives the SkillCDN token and keeps it sealed, shown to nobody.\nWaiting for that, until ${moment(started.expiresAt)}.\n`,
+    );
+    for (;;) {
+      await io.sleep(started.intervalSeconds * 1000);
+      const state = await holder.standing();
+      if (state.status === "pending") {
+        continue;
+      }
+      if (state.status === "connected") {
+        answer(io, session, state.held, () => `Connected.\n${format(state.held)}`);
+        return EXIT.ok;
+      }
+      if (state.status === "ended") {
+        throw failed(PACK_CONNECT_ENDED[state.reason]);
+      }
+      throw failed(
+        "The console no longer waits for the connection; run the command again for a new code.",
+      );
+    }
+  }
   const token = (await io.readStdin()).trim();
   if (token.length === 0) {
     throw failed("No token was given on standard input.");
   }
-  const changed = await project.setPackToken({ token });
-  answer(io, session, changed, () => formatProject(changed));
+  const changed = await holder.set(token);
+  answer(io, session, changed, () => format(changed));
   return EXIT.ok;
+}
+
+const PACK_TOKEN_FLAGS = {
+  connect: { type: "boolean" },
+  stdin: { type: "boolean" },
+  remove: { type: "boolean" },
+} as const;
+
+const projectPackToken: Command = async (args, io) => {
+  const { values, positionals } = parse(args, PACK_TOKEN_FLAGS);
+  const key = theOne(
+    positionals,
+    "Say which project: console project pack-token <key> --connect, --stdin or --remove",
+  );
+  const way = wayOf(values);
+  const session = await open(io, values);
+  const project = session.client.project(key);
+  return packToken(
+    io,
+    session,
+    way,
+    {
+      set: (token) => project.setPackToken({ token }),
+      remove: () => project.removePackToken(),
+      connect: () => project.connectPackToken(),
+      async standing() {
+        const state = await project.packTokenConnection();
+        return state.status === "connected" ? { status: "connected", held: state.project } : state;
+      },
+    },
+    formatProject,
+  );
 };
 
 const projectIcon: Command = async (args, io) => {
@@ -2564,6 +2781,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   rules,
   people,
   person,
+  workspace,
   project,
   members,
   member,
@@ -2715,6 +2933,8 @@ function hintFor(error: ApiError, io: CliIo, seen: ConsoleSeen): string {
       return "The person is listed already. console member role <login> <owner|member> changes what they are.\n";
     case "member.not_found":
       return "The person is not listed in the project. console members lists those who are.\n";
+    case "member.open_project":
+      return "The project is open to the workspace, so everyone of it is a member already. console member add <login> --role owner lists an owner; console member role <login> member takes one back to member.\n";
     case "category.key_taken":
       return "A category has that key already. console categories lists them.\n";
     case "category.not_found":

package/src/cli/credentials.ts

@@ -22,6 +22,11 @@ export interface Login {
   readonly agent: string | undefined;
   /** When the command was signed in, when known. */
   readonly since: string | undefined;
+  /**
+   * The workspace's time zone as the console last said it, at login or whoami (ADR-0035): what
+   * the command prints moments in, without asking again; none when the workspace names none.
+   */
+  readonly timeZone?: string | undefined;
 }
 
 /** Everything the command keeps: the logins, and the console a directory that names none works at. */
@@ -71,6 +76,7 @@ const loginSchema = z.object({
   token: z.string().check(z.minLength(1), z.maxLength(1024)),
   agent: z.optional(z.string().check(z.maxLength(200))),
   since: z.optional(z.string().check(z.maxLength(40))),
+  timeZone: z.optional(z.string().check(z.minLength(1), z.maxLength(64))),
 });
 const fileSchema = z.object({
   version: z.literal(2),
@@ -95,6 +101,7 @@ export function parseCredentials(json: unknown): Credentials | undefined {
         token: login.token,
         agent: login.agent,
         since: login.since,
+        ...(login.timeZone === undefined ? {} : { timeZone: login.timeZone }),
       })),
     };
   }

package/src/cli/directory.ts

@@ -15,6 +15,15 @@ import * as z from "zod/mini";
 /** The file's name, in the working directory or one above it. */
 export const DIRECTORY_FILE = ".skillcdn-console.json";
 
+/**
+ * The sentence a checkout's agreement carries to send the agents working there to the console:
+ * the one the skill working-the-board keeps (references/the-sentence.md) and this repository's
+ * own agreement carries. `console use` prints it, since nothing tells an agent to look until the
+ * checkout says so, as `skillcdn use` prints the sentence for a pack.
+ */
+export const THE_SENTENCE =
+  "**Bound to a console?** When `.skillcdn-console.json` is in this checkout, or `console whoami` names a project, work the task through that SkillCDN console (`console help` says how).";
+
 /** How large the file may be before it is not read: a few names, never more. */
 const MAX_FILE_CHARS = 16 * 1024;
 

package/src/cli/format.ts

@@ -19,6 +19,7 @@ import type {
   RestVersion,
   RestVersionSummary,
   RestWork,
+  RestWorkspace,
 } from "../schemas.js";
 
 // What the command prints: one line per thing in a list, a few lines for one thing in full.
@@ -27,6 +28,48 @@ import type {
 
 const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? "" : "s"}`;
 
+/** The time zone moments are printed in: the workspace's, as the command last learned it (ADR-0035); none leaves them as the API gives them. */
+let momentZone: string | undefined;
+
+/** Says which time zone the moments printed from now on are in, or none. */
+export function setMomentZone(zone: string | undefined): void {
+  momentZone = zone;
+}
+
+/**
+ * An instant as the command prints it: in the workspace's time zone, as ISO 8601 with its
+ * offset (`2026-10-18T15:04:17+09:00`), when a zone is known; else as the API gave it, in UTC.
+ */
+export function moment(iso: string): string {
+  if (momentZone === undefined) {
+    return iso;
+  }
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) {
+    return iso;
+  }
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat("en-US", {
+      timeZone: momentZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      timeZoneName: "longOffset",
+    }).formatToParts(date);
+  } catch {
+    return iso;
+  }
+  const of = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((part) => part.type === type)?.value ?? "";
+  const offset = of("timeZoneName").replace("GMT", "");
+  return `${of("year")}-${of("month")}-${of("day")}T${of("hour")}:${of("minute")}:${of("second")}${offset === "" ? "Z" : offset}`;
+}
+
 const indent = (text: string): string =>
   text
     .trimEnd()
@@ -54,7 +97,7 @@ export function formatProject(project: RestProject): string {
     `project ${project.key}: ${project.name}`,
     `visibility: ${project.visibility}  role: ${project.role}  skills: ${project.skillsAddress ?? "the organization's"}`,
     `color: ${project.color ?? "none"}  symbol: ${project.symbol ?? "none"}  image: ${project.icon === null ? "none" : project.icon.contentType}`,
-    `pack token: ${project.packToken === null ? "none" : `set ${project.packToken.setAt}`}`,
+    `pack token: ${project.packToken === null ? "none" : `set ${moment(project.packToken.setAt)}`}`,
   ];
   if (project.description.trim().length > 0) {
     lines.push("", project.description.trimEnd());
@@ -78,9 +121,25 @@ export function formatListingLine(listing: RestListing): string {
   return `${listing.login}  (let in at ${HOST_NAMES[listing.host]}, not signed in yet)`;
 }
 
+/** The workspace as its Settings page shows it: what it is called, who sees whom, the week, the time zone, where the skills come from, and what tokens may last. */
+export function formatWorkspace(workspace: RestWorkspace): string {
+  const visibility = workspace.peopleVisibility ?? "everyone";
+  const zone = workspace.timeZone ?? null;
+  const token = workspace.skills.packToken ?? null;
+  return [
+    `workspace ${workspace.name}`,
+    `people visibility: ${visibility}  (${visibility === "everyone" ? "everyone sees everyone" : "a member sees only the people they share a project with; an administrator sees everyone"})`,
+    `week begins on: ${workspace.weekStart ?? "auto"}  (auto: the system default, as each device has it)`,
+    `time zone: ${zone ?? "none"}  (${zone === null ? "moments are printed as the API gives them, in UTC" : "moments are printed in it, as ISO 8601 with its offset"})`,
+    `skills: ${workspace.skills.address ?? "no address of the organization's"}  at ${workspace.skills.source}`,
+    `SkillCDN token: ${token === null ? "none" : `set ${moment(token.setAt)}`}  (${token === null ? "the organization's pack is read with none" : "the organization's pack is read with it by a project with no address and no token of its own"})`,
+    `token days at most: ${workspace.tokenDaysAtMost ?? "a person chooses"}`,
+  ].join("\n");
+}
+
 /** One member of a project: their login, what they are in it, and since when. */
 export function formatMemberLine(member: RestMember): string {
-  return `${member.person.login}  ${member.role}  (since ${member.addedAt.slice(0, 10)})`;
+  return `${member.person.login}  ${member.role}  (since ${moment(member.addedAt).slice(0, 10)})`;
 }
 
 /** The line under a page of a listing that has more after it: how to ask for the next page. */
@@ -121,9 +180,9 @@ function scheduleLines(task: RestTask): string[] {
     lines.push(plan.join("  "));
   }
   const happened = [
-    task.startedAt === null ? undefined : `started: ${task.startedAt}`,
-    task.doneAt === null ? undefined : `done: ${task.doneAt}`,
-    task.archivedAt === null ? undefined : `archived: ${task.archivedAt}`,
+    task.startedAt === null ? undefined : `started: ${moment(task.startedAt)}`,
+    task.doneAt === null ? undefined : `done: ${moment(task.doneAt)}`,
+    task.archivedAt === null ? undefined : `archived: ${moment(task.archivedAt)}`,
   ].filter((part) => part !== undefined);
   if (happened.length > 0) {
     lines.push(happened.join("  "));
@@ -181,7 +240,7 @@ export function formatTask(
 export function formatComment(comment: RestComment): string {
   const who =
     comment.agent === null ? comment.author.login : `${comment.author.login} as ${comment.agent}`;
-  const lines = [`  ${who}, ${comment.createdAt}, comment ${comment.id}:`];
+  const lines = [`  ${who}, ${moment(comment.createdAt)}, comment ${comment.id}:`];
   if (comment.body.trim().length > 0) {
     lines.push(indent(comment.body));
   }
@@ -199,7 +258,7 @@ export function formatRunLine(run: RestRun): string {
     notes.push(`waiting for decision ${run.waitingFor}`);
   }
   if (run.endedAt === null) {
-    notes.push(`last heard ${run.lastHeardAt}`);
+    notes.push(`last heard ${moment(run.lastHeardAt)}`);
   }
   return `${run.id}  ${run.status}  ${run.agent} for ${run.person.login}  task #${run.taskNumber}  (${notes.join(", ")})`;
 }
@@ -208,7 +267,7 @@ export function formatRunLine(run: RestRun): string {
 export function formatRun(run: RestRun, fileUrl?: (artifactId: string) => string): string {
   const lines = [
     formatRunLine(run),
-    `started: ${run.startedAt}${run.endedAt === null ? "" : `  ended: ${run.endedAt}`}`,
+    `started: ${moment(run.startedAt)}${run.endedAt === null ? "" : `  ended: ${moment(run.endedAt)}`}`,
   ];
   if (run.summary !== null) {
     lines.push("", "summary:", indent(run.summary));
@@ -216,7 +275,7 @@ export function formatRun(run: RestRun, fileUrl?: (artifactId: string) => string
   if (run.reports.length > 0) {
     lines.push("", "reports:");
     for (const report of run.reports) {
-      lines.push(`  [${report.createdAt}]`, indent(report.body));
+      lines.push(`  [${moment(report.createdAt)}]`, indent(report.body));
     }
   }
   if (run.artifacts.length > 0) {
@@ -246,7 +305,7 @@ function formatRulesHalf(where: "the workspace" | "this project", rules: RestRul
   const facts =
     page === null
       ? undefined
-      : `v${page.version}, by ${writer(page.updatedBy, page.agent)}; ${page.updatedAt}`;
+      : `v${page.version}, by ${writer(page.updatedBy, page.agent)}; ${moment(page.updatedAt)}`;
   if (rules.source === "none" || rules.body === null) {
     return `Rules of ${where}: none of its own; the workspace's hold.`;
   }
@@ -397,7 +456,7 @@ export function formatDocumentLine(document: RestDocumentSummary): string {
   if (document.archivedAt !== null) {
     notes.push("archived");
   }
-  return `${document.path}  ${document.title}  (${notes.join(", ")}; ${document.updatedAt})`;
+  return `${document.path}  ${document.title}  (${notes.join(", ")}; ${moment(document.updatedAt)})`;
 }
 
 /** A folder's folders and pages, or the pages a search found. */
@@ -419,7 +478,7 @@ export function formatDocument(
 ): string {
   const lines = [
     `${document.path}: ${document.title}`,
-    `version ${document.version}, by ${writer(document.updatedBy, document.agent)} at ${document.updatedAt}${document.archivedAt === null ? "" : `; archived ${document.archivedAt}`}`,
+    `version ${document.version}, by ${writer(document.updatedBy, document.agent)} at ${moment(document.updatedAt)}${document.archivedAt === null ? "" : `; archived ${moment(document.archivedAt)}`}`,
     `id: ${document.id}`,
   ];
   if (document.body.trim().length > 0) {
@@ -453,7 +512,7 @@ export function formatDocument(
 }
 
 export function formatVersionLine(version: RestVersionSummary): string {
-  return `v${version.number}  ${version.title}  (by ${writer(version.author, version.agent)}; ${version.createdAt})`;
+  return `v${version.number}  ${version.title}  (by ${writer(version.author, version.agent)}; ${moment(version.createdAt)})`;
 }
 
 /** One version of a document, with its body as it was. */