@opsee/cli 0.11.13 → 0.11.18

package/src/foreman/account.ts

@@ -1,9 +1,10 @@
-import { constants } from "node:fs";
+import { accessSync, constants, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { isVendor, VENDORS, type Vendor } from "./vendor.js";
 import type { AccountStore } from "./account-store.js";
-import { oneLine, printableOneLine } from "./core/text.js";
+import { formatTable, oneLine, printableOneLine } from "./core/text.js";
+import { describeAge, headroom, thresholdHold, type AccountUsage } from "./usage.js";
 
 /**
  * An Account (see ../../CONTEXT.md): one identity for one vendor, registered by path or key
@@ -26,6 +27,22 @@ export const DEFAULT_CAP = 2;
  * nothing below would refuse it: the Run would obligingly put a hundred Workers on one login. */
 export const MAX_CAP = 32;
 
+/**
+ * How much of a window may be spent before the Foreman stops offering the Account new Tasks (the
+ * multi-account headroom design, §4).
+ *
+ * 90 because that is the point Claude Code fires its own `allowed_warning` — so at the default the
+ * Foreman acts on the first warning the vendor gives rather than on a number it invented.
+ */
+export const DEFAULT_THRESHOLD_PCT = 90;
+
+/** The lowest threshold that still leaves an Account usable. Below this a busy Account spends most
+ * of every window held back, which is indistinguishable from not having registered it. */
+export const MIN_THRESHOLD_PCT = 50;
+
+/** A threshold of 100 is "hold only what the vendor says is spent"; past that is not a percentage. */
+export const MAX_THRESHOLD_PCT = 100;
+
 /** The least a stall timeout may be set to. Below this a Worker that is only thinking, or running
  * the project's test suite, is stopped as `stalled` every time, and the Task spends its attempts
  * (`DEFAULT_ATTEMPT_RETRIES`) in seconds without a single turn having had a chance. */
@@ -148,6 +165,21 @@ export function resumeAccount(store: AccountStore, name: string): Account | unde
   return updateAccount(store, name, (account) => ({ ...account, paused: null }));
 }
 
+/**
+ * Whether this Account could take work at this moment: not quarantined, not Paused, and not one
+ * another Foreman already has Workers on.
+ *
+ * One name for the question, because it was being asked in pieces. `core/scheduler.ts` says plainly
+ * that eligibility "is decided in core/run.ts before and after this, and deliberately not here", so
+ * a third hand-rolled `filter(a => !isQuarantined(a))` in a command module was the shape of that
+ * rule coming apart.
+ *
+ * `busy` is the Process Table's answer where a caller has one; without it the other two still hold.
+ */
+export function isUsableNow(account: Pick<Account, "name" | "paused" | "quarantined">, now: number, busy?: (name: string) => boolean): boolean {
+  return !isQuarantined(account) && !isPaused(account, now) && !busy?.(account.name);
+}
+
 /** True while the Account is quarantined (OPS-288). No `now`, unlike `isPaused`: a quarantine has no
  * reset, so nothing about it changes with the clock. */
 export function isQuarantined(account: Pick<Account, "quarantined">): boolean {
@@ -242,6 +274,9 @@ interface AccountBase {
   /** How long a Worker on this Account may go silent before its turn is stopped as `stalled`
    * (story 33). Unset falls back to the Run's `--stall-timeout` and then to the CLI's default. */
   stallTimeoutMs?: number;
+  /** How much of a window may be spent before this Account is held back (`DEFAULT_THRESHOLD_PCT`).
+   * Per-Account because a Max subscription and a Pro one do not want the same number. */
+  thresholdPct?: number;
 }
 
 /** A subscription the user has already signed into, isolated in its own config directory; the
@@ -270,6 +305,11 @@ export interface ConfigDirFs {
   accessSync(path: string, mode: number): void;
 }
 
+/** The real file system behind `ConfigDirFs`: the two calls registration is allowed to make, and
+ * no more. Here rather than in the CLI so that everything registering an Account — the command, its
+ * tests — goes through the same two functions the boundary test audits. */
+export const realConfigDirFs: ConfigDirFs = { statSync, accessSync };
+
 /** A registration the user got wrong; reported as a plain message, never a stack. */
 export class AccountError extends Error {}
 
@@ -285,7 +325,9 @@ export interface AccountSpec {
 const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
-function expandHome(path: string): string {
+/** `~` and `~/…` against the user's home. Exported because `account add --login` expands the same
+ * flag before the vendor sees it, and two implementations drifted on bare `~`. */
+export function expandHome(path: string): string {
   return path === "~" || path.startsWith("~/") ? homedir() + path.slice(1) : path;
 }
 
@@ -319,7 +361,17 @@ export function validateConfigDir(fs: ConfigDirFs, dir: string): string {
 
 /** Validates the spec against the file system and the existing Accounts, then stores the new one.
  * Names are unique across vendors; a directory or key may back only one Account per vendor. */
-export function registerAccount(store: AccountStore, fs: ConfigDirFs, spec: AccountSpec): Account {
+/**
+ * Everything `registerAccount` refuses a spec for, *except* what needs the file system.
+ *
+ * Split out so a caller that is about to do something irreversible on the spec's behalf can find
+ * out first: `account add --login` makes a directory and runs an interactive sign-in, and running
+ * all of this afterwards meant a name collision cost the user a full login and registered nothing.
+ *
+ * Returns the validated vendor and name; throws `AccountError` exactly as registration does, so the
+ * message a caller sees is the same either way.
+ */
+export function validateAccountSpec(store: AccountStore, spec: AccountSpec): { vendor: Vendor; name: string } {
   if (!isVendor(spec.vendor)) {
     throw new AccountError(`Unknown vendor "${spec.vendor}". Vendors: ${VENDORS.join(", ")}`);
   }
@@ -338,15 +390,23 @@ export function registerAccount(store: AccountStore, fs: ConfigDirFs, spec: Acco
   if (!NAME_PATTERN.test(name)) {
     throw new AccountError("Account names are letters, digits, '.', '_' and '-' and start with a letter or digit");
   }
-
-  const existing = store.load();
-  if (existing.some((a) => a.name === name)) {
+  if (store.load().some((a) => a.name === name)) {
     throw new AccountError(
       spec.name === undefined
         ? `An Account named "${name}" already exists; pass --name to register a second ${vendor} Account`
         : `An Account named "${name}" already exists`,
     );
   }
+  return { vendor, name };
+}
+
+export function registerAccount(store: AccountStore, fs: ConfigDirFs, spec: AccountSpec): Account {
+  // The same guards `account add --login` asks for up front, in one place: two copies of five
+  // refusals with identical messages would drift, and the one that drifted would be the one a
+  // caller had already acted on.
+  const { vendor, name } = validateAccountSpec(store, spec);
+  const cap = spec.cap ?? DEFAULT_CAP;
+  const existing = store.load();
 
   // A registration is a fresh record, so re-adding an Account is how a human lifts a quarantine
   // (OPS-288): the state and its streak are not carried over from anything.
@@ -383,6 +443,12 @@ export interface AccountSettings {
   cap?: number;
   maxTurns?: number;
   stallTimeoutMs?: number;
+  thresholdPct?: number;
+}
+
+/** The threshold in force for this Account: its own, or the default. */
+export function thresholdFor(account: Pick<Account, "thresholdPct">): number {
+  return account.thresholdPct ?? DEFAULT_THRESHOLD_PCT;
 }
 
 /** Changes an existing Account's scheduling limits (story 27): the cap that decides how many Slots
@@ -394,13 +460,19 @@ export function setAccountLimits(store: AccountStore, name: string, settings: Ac
   if (!account) {
     throw new AccountError(`No Account named "${name}"`);
   }
-  if (settings.cap === undefined && settings.maxTurns === undefined && settings.stallTimeoutMs === undefined) {
-    throw new AccountError("foreman account set needs at least one of --cap, --max-turns, --stall-timeout");
+  if (
+    settings.cap === undefined &&
+    settings.maxTurns === undefined &&
+    settings.stallTimeoutMs === undefined &&
+    settings.thresholdPct === undefined
+  ) {
+    throw new AccountError("foreman account set needs at least one of --cap, --max-turns, --stall-timeout, --threshold");
   }
   for (const [flag, value] of [
     ["--cap", settings.cap],
     ["--max-turns", settings.maxTurns],
     ["--stall-timeout", settings.stallTimeoutMs],
+    ["--threshold", settings.thresholdPct],
   ] as const) {
     if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
       throw new AccountError(`${flag} must be a positive integer`);
@@ -414,11 +486,19 @@ export function setAccountLimits(store: AccountStore, name: string, settings: Ac
   if (settings.stallTimeoutMs !== undefined && settings.stallTimeoutMs < MIN_STALL_TIMEOUT_MS) {
     throw new AccountError(`--stall-timeout is at least ${MIN_STALL_TIMEOUT_MS}ms; below that a Worker that is only thinking is stopped as stalled`);
   }
+  // Both ends again: a threshold so low the Account is held back most of the time, and one past
+  // what a percentage of a window can be.
+  if (settings.thresholdPct !== undefined && (settings.thresholdPct < MIN_THRESHOLD_PCT || settings.thresholdPct > MAX_THRESHOLD_PCT)) {
+    throw new AccountError(
+      `--threshold is a percentage from ${MIN_THRESHOLD_PCT} to ${MAX_THRESHOLD_PCT}; it is how much of a rate-limit window may be spent before the Account is held back`,
+    );
+  }
   const updated: Account = {
     ...account,
     cap: settings.cap ?? account.cap,
     maxTurns: settings.maxTurns ?? account.maxTurns,
     stallTimeoutMs: settings.stallTimeoutMs ?? account.stallTimeoutMs,
+    thresholdPct: settings.thresholdPct ?? account.thresholdPct,
   };
   store.save(existing.map((a) => (a === account ? updated : a)));
   return updated;
@@ -442,19 +522,31 @@ export function removeAccount(store: AccountStore, name: string): Account {
  * Quarantine (OPS-288) is reported ahead of a pause, and swallows it: an Account may well have been
  * Paused before its credential died, and of the two facts only one still needs the reader to do
  * something. It names the remedy for the same reason, since nothing lifts it by itself. */
-export function formatAccountTable(accounts: Account[], now: number = Date.now()): string[] {
+export function formatAccountTable(
+  accounts: Account[],
+  now: number = Date.now(),
+  usage?: ReadonlyMap<string, AccountUsage>,
+): string[] {
   const state = (a: Account): string => {
     if (a.quarantined) return `quarantined since ${a.quarantined.at} (${printableOneLine(a.quarantined.reason)}); re-add it or: opsee foreman account resume ${a.name}`;
     const until = pausedUntil(a, now);
     if (until) return `paused until ${a.paused!.until}${a.paused!.reason ? ` (${oneLine(a.paused!.reason)})` : ""}`;
-    return a.paused ? `active (pause lapsed ${a.paused.until})` : "active";
+    // A hold the Foreman chose is reported differently from a pause the vendor imposed, because the
+    // two ask different things of a reader: a pause is "Anthropic refused this", a hold is "we
+    // stopped offering it work at your threshold", which `--threshold` can lift at once.
+    const record = usage?.get(a.name);
+    const hold = thresholdHold(record, thresholdFor(a), now);
+    if (hold) return `held until ${hold.until.toISOString()} (${hold.reason}, ${describeAge(hold.observedAt, now)})`;
+    const lapsed = a.paused ? `active (pause lapsed ${a.paused.until})` : "active";
+    const left = headroom(record, now);
+    if (left.kind === "unknown") return lapsed;
+    return `${lapsed} (${left.remainingPct}% left of ${left.tightest}, ${describeAge(left.observedAt, now)})`;
   };
   const rows = [
     ["NAME", "VENDOR", "TYPE", "SOURCE", "CAP", "STATE"],
     ...accounts.map((a) => [a.name, a.vendor, a.type, describeSource(a), String(a.cap), state(a)]),
   ];
-  const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
-  return rows.map((r) => r.map((cell, i) => (i === r.length - 1 ? cell : cell.padEnd(widths[i]))).join("  "));
+  return formatTable(rows);
 }
 
 export function describeAccount(account: Account): string {
@@ -469,6 +561,7 @@ export function describeLimits(account: Account): string {
   const perTurn = [
     account.maxTurns === undefined ? "" : `max turns ${account.maxTurns}`,
     account.stallTimeoutMs === undefined ? "" : `stall timeout ${account.stallTimeoutMs}ms`,
+    account.thresholdPct === undefined ? "" : `threshold ${account.thresholdPct}%`,
   ].filter(Boolean);
   return `cap ${account.cap} (${slots})${perTurn.length ? `, ${perTurn.join(", ")}` : ""}`;
 }

package/src/foreman/claude-worker-adapter.ts

@@ -1,5 +1,6 @@
 import type { Account } from "./account.js";
 import { COMPLETION_REPORT_CONTRACT, completedEvent } from "./completion-report.js";
+import type { UsageWindow } from "./usage.js";
 import { VENDOR_CONFIG_DIR_ENV } from "./vendor.js";
 import type { InteractiveCommand, InteractiveSessionRequest, McpServerSpec, OutputContract, TurnFailureReason, TurnHandle, TurnRequest, TurnSandbox, WorkerAdapter } from "./worker-adapter.js";
 import {
@@ -227,6 +228,97 @@ export function resetAtFromLimitText(text: string): string | undefined {
   return epoch ? new Date(Number(epoch[1]) * 1000).toISOString() : undefined;
 }
 
+/** One window inside `rate_limit_info.unifiedWindows`: a fraction spent and an epoch-second reset. */
+interface RateLimitWindow {
+  utilization?: number;
+  resetsAt?: number;
+}
+
+/**
+ * `rate_limit_info` as Claude Code emits it (see the recorded fixtures in `__fixtures__/claude`).
+ *
+ * `unifiedWindows` is the valuable part and the reason no credential is needed to know an Account's
+ * headroom while it is working: the vendor sends every window it tracks, with the fraction spent
+ * and the reset, on every `rate_limit_event` — including the `allowed_warning` that fires at 90%
+ * of a window, long before anything is refused.
+ */
+interface RateLimitInfo {
+  status?: string;
+  resetsAt?: number;
+  rateLimitType?: string;
+  utilization?: number;
+  /** The fraction of the window whose crossing fired this warning: 0.9 in the recorded fixtures. */
+  surpassedThreshold?: number;
+  unifiedWindows?: Record<string, RateLimitWindow>;
+}
+
+/** Where the vendor's own warning fires, when the line does not carry `surpassedThreshold`. Claude
+ * Code documents the warning at 90% of a window, and the fixtures bear it out. */
+export const WARNING_USED_PCT = 90;
+
+/**
+ * The vendor's windows as usage observations, or undefined when it reported nothing usable.
+ *
+ * Two shapes are accepted: `unifiedWindows` when it is there, and the flat
+ * `rateLimitType`/`utilization`/`resetsAt` trio otherwise, which is what an older Claude Code sends
+ * and what the flat fields still mirror for the window that triggered the event.
+ *
+ * A window is dropped unless it has both a utilization and a reset. A utilization with no reset
+ * describes no interval — nothing downstream can tell whether it is still current (`usage.ts`
+ * `isLive`) — and a reset with no utilization is not a measurement: `status: "allowed"` with no
+ * number is the vendor declining to say, and recording that as 0% would make a nearly-spent
+ * Account look fresh.
+ */
+export function usageWindowsFrom(info: RateLimitInfo | undefined, observedAt: string): Record<string, UsageWindow> | undefined {
+  if (!info) return undefined;
+  const source: Record<string, RateLimitWindow> =
+    info.unifiedWindows && typeof info.unifiedWindows === "object"
+      ? info.unifiedWindows
+      : info.rateLimitType
+        ? { [info.rateLimitType]: { utilization: info.utilization, resetsAt: info.resetsAt } }
+        : {};
+  // What a line with no utilization still tells us. `allowed_warning` means a threshold of this
+  // window was crossed, and a refusal means it is spent — both are real observations, where a plain
+  // `allowed` with no number is the vendor declining to say and must stay unrecorded.
+  //
+  // It applies to **one** window: the one `rateLimitType` names, which is the window the event is
+  // about. Spreading it across every window of `unifiedWindows` would write the five-hour warning's
+  // 90% onto a seven-day window the vendor said nothing about, and `thresholdHold` would then take
+  // the Account out of rotation until the *weekly* reset — up to seven days, on a number nobody
+  // measured. A status describes the window that raised it and no other.
+  const implied = impliedUsedPct(info);
+  const impliedFor = info.rateLimitType;
+  const windows: Record<string, UsageWindow> = {};
+  for (const [name, window] of Object.entries(source)) {
+    const measured = typeof window?.utilization === "number" && Number.isFinite(window.utilization) ? window.utilization : undefined;
+    const utilization = measured ?? (name === impliedFor ? implied : undefined);
+    const resetsAt = window?.resetsAt;
+    if (typeof utilization !== "number" || !Number.isFinite(utilization)) continue;
+    if (typeof resetsAt !== "number" || !Number.isFinite(resetsAt)) continue;
+    windows[name] = {
+      // A fraction to a percentage, to one decimal: `0.93 * 100` is 93.00000000000001 in binary
+      // floating point, and an Account's usage should not read as that.
+      usedPct: Math.max(0, Math.min(100, Math.round(utilization * 1000) / 10)),
+      resetsAt: new Date(resetsAt * 1000).toISOString(),
+      observedAt,
+      source: "in_band",
+    };
+  }
+  return Object.keys(windows).length === 0 ? undefined : windows;
+}
+
+/** What the status alone implies about a window the vendor sent no utilization for, as a fraction,
+ * or undefined when it implies nothing. A refusal is a spent window; a warning is one past the
+ * threshold the line names, or past the documented 90% when it names none. */
+function impliedUsedPct(info: RateLimitInfo): number | undefined {
+  if (info.status === "allowed_warning") {
+    const named = info.surpassedThreshold;
+    return typeof named === "number" && Number.isFinite(named) && named > 0 ? named : WARNING_USED_PCT / 100;
+  }
+  // Anything that is not `allowed` and not a warning is a refusal (`handleRateLimit` treats it so).
+  return info.status !== undefined && info.status !== "allowed" ? 1 : undefined;
+}
+
 /** The Claude Code tool through which `--json-schema` output is delivered; its input is the report. */
 export const STRUCTURED_OUTPUT_TOOL = "StructuredOutput";
 
@@ -235,7 +327,7 @@ interface StreamLine {
   subtype?: string;
   session_id?: string;
   message?: { content?: unknown };
-  rate_limit_info?: { status?: string; resetsAt?: number; rateLimitType?: string };
+  rate_limit_info?: RateLimitInfo;
   is_error?: boolean;
   result?: unknown;
   structured_output?: unknown;
@@ -291,6 +383,13 @@ class ClaudeTurn extends ProcessTurn {
   }
 
   private handleRateLimit(info: StreamLine["rate_limit_info"]): void {
+    // Every rate-limit line is worth something, whatever its status: the vendor puts its windows
+    // and their utilizations on all of them, and an `allowed_warning` at 90% is the whole point —
+    // it is the one warning that arrives before a Task has been spent finding the limit. These
+    // numbers used to be discarded here along with the status.
+    const windows = usageWindowsFrom(info, new Date().toISOString());
+    if (windows) this.emit({ type: "usage", windows });
+
     // `allowed` and `allowed_warning` are advisory (a warning fires at 90% of a window and the run
     // goes on); only a refusal is reported, and it fails the turn only if the result confirms it.
     if (!info || info.status === "allowed" || info.status === "allowed_warning") return;

package/src/foreman/config-skeleton.ts

@@ -0,0 +1,167 @@
+import { existsSync, lstatSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/**
+ * The shared config skeleton (the multi-account headroom design, §5).
+ *
+ * One config directory per Account is what makes multi-account work without touching a credential
+ * (claude-launcher.ts): a directory the user has logged into is a whole identity, and the vendor's
+ * own variable selects it. The cost is that everything else in there — settings, skills, commands —
+ * would live in each Account separately, so a change had to be made several times.
+ *
+ * This narrows that to history and per-account state, by symlinking the account-independent entries
+ * from one canonical directory into each Account's. Symlinks and not copies, so the canonical file
+ * stays the single thing a human edits and there is no second copy to drift.
+ *
+ * **It moves no bytes.** Every operation here is `lstat`, `readlink`, `symlink` and `rm` of a link:
+ * nothing is ever opened or read, so a credential sitting beside an allowlisted file is not read
+ * even by accident. That is what keeps this inside the boundary ADR-0013 draws, and
+ * `config-skeleton.test.ts` holds it to it.
+ */
+
+/**
+ * The entries that are the same whoever is logged in.
+ *
+ * An allowlist, never a denylist or a scan of the directory: a vendor that adds a file holding
+ * identity would otherwise be shared between Accounts the first time someone ran this, and nobody
+ * would find out until two Accounts were one. Anything not named here is simply not the skeleton's
+ * business.
+ */
+export const SKELETON_ENTRIES: readonly string[] = ["settings.json", "CLAUDE.md", "skills", "commands", "agents", ".mcp.json"];
+
+/** Anything that looks like it carries identity, refused whatever the caller asked for. The
+ * allowlist above already excludes these; this is the second lock, for a caller passing `entries`
+ * of its own. */
+const CREDENTIAL_SHAPED = /credential|token|keychain|auth|secret|session/i;
+
+/**
+ * Files that are never shared however they are asked for, by exact name.
+ *
+ * `.claude.json` is the one worth naming: it does not read as credential-shaped, it sits right
+ * beside the entries that *are* shared, and it carries the account's own identity and project
+ * state. Linking it between two Accounts would quietly make them one Account — the exact failure
+ * this whole design exists to avoid — and nothing above would have refused it.
+ */
+const NEVER_SHARED: readonly string[] = [".claude.json", ".credentials.json"];
+
+export interface SkeletonRequest {
+  /** The directory the shared files really live in — normally the user's own `~/.claude`. */
+  canonical: string;
+  /** The Account config directories to link them into. */
+  targets: readonly string[];
+  /** Defaults to `SKELETON_ENTRIES`. */
+  entries?: readonly string[];
+}
+
+export type SkeletonOutcome =
+  /** A new link was made. */
+  | "linked"
+  /** A link that pointed elsewhere now points at the canonical entry. */
+  | "relinked"
+  /** The right link was already there. */
+  | "already"
+  /** The canonical directory does not have this entry, so there is nothing to share. */
+  | "missing"
+  /** The target directory does not exist; a config directory is the vendor's login to create. */
+  | "no-target"
+  /** The target *is* the canonical directory. */
+  | "self"
+  /** Deliberately not done, with a reason: a real file in the way, or a credential-shaped name. */
+  | "refused";
+
+export interface SkeletonResult {
+  target: string;
+  entry: string;
+  outcome: SkeletonOutcome;
+  note?: string;
+}
+
+export function syncSkeleton(request: SkeletonRequest): SkeletonResult[] {
+  const canonical = resolve(request.canonical);
+  const entries = request.entries ?? SKELETON_ENTRIES;
+  const results: SkeletonResult[] = [];
+
+  for (const rawTarget of request.targets) {
+    const target = resolve(rawTarget);
+    for (const entry of entries) {
+      const refusal = unsafe(entry);
+      if (refusal) {
+        results.push({ target, entry, outcome: "refused", note: refusal });
+        continue;
+      }
+      if (target === canonical) {
+        results.push({ target, entry, outcome: "self", note: "this is the canonical directory; its files are the originals" });
+        continue;
+      }
+      if (!isDirectory(target)) {
+        results.push({ target, entry, outcome: "no-target", note: "no such config directory; the vendor's own login creates one" });
+        continue;
+      }
+      const source = join(canonical, entry);
+      if (!existsSync(source)) {
+        results.push({ target, entry, outcome: "missing" });
+        continue;
+      }
+      results.push(link(source, join(target, entry), target, entry));
+    }
+  }
+  return results;
+}
+
+/** Why this entry will not be touched, or undefined when it is fine. */
+function unsafe(entry: string): string | undefined {
+  if (entry === "" || entry === "." || entry === "..") return "not a file name";
+  // One path segment only. An entry with a separator in it could place a link anywhere, and an
+  // entry with `..` could reach out of the config directory entirely.
+  if (entry.includes("/") || entry.includes("\\") || entry.includes("..")) return "an entry is one file name, not a path";
+  if (NEVER_SHARED.includes(entry)) return `${entry} carries this Account's own identity, and is never shared between Accounts`;
+  if (CREDENTIAL_SHAPED.test(entry)) return "this is credential-shaped, and a credential is never shared between Accounts";
+  return undefined;
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Makes `at` a symlink to `source`, or explains why it was left alone. */
+function link(source: string, at: string, target: string, entry: string): SkeletonResult {
+  let existing: ReturnType<typeof lstatSync> | undefined;
+  try {
+    existing = lstatSync(at);
+  } catch {
+    existing = undefined;
+  }
+  if (existing?.isSymbolicLink()) {
+    let points: string | undefined;
+    try {
+      points = readlinkSync(at);
+    } catch {
+      points = undefined;
+    }
+    if (points !== undefined && resolve(points) === source) return { target, entry, outcome: "already" };
+    // Only ever a symlink is removed here, and only after `lstat` has said it is one — so nothing
+    // a person wrote can be lost by this branch.
+    rmSync(at);
+    symlinkSync(source, at);
+    return { target, entry, outcome: "relinked", note: `it pointed at ${points ?? "somewhere unreadable"}` };
+  }
+  if (existing) {
+    return {
+      target,
+      entry,
+      outcome: "refused",
+      note: `this Account has its own ${entry} here; move or delete it to share the canonical one`,
+    };
+  }
+  symlinkSync(source, at);
+  return { target, entry, outcome: "linked" };
+}
+
+/** One line per result, for the command to print. Ordered as the sync happened. */
+export function formatSkeletonResults(results: readonly SkeletonResult[]): string[] {
+  return results.map((r) => `  ${r.outcome.padEnd(9)} ${r.entry}${r.outcome === "linked" || r.outcome === "relinked" || r.outcome === "already" ? ` in ${r.target}` : r.note ? ` — ${r.note}` : ""}`);
+}