@modelprofile.com/authswitch 10.0.0 → 10.1.0

package/ts/classes.claudenative.ts

@@ -6,9 +6,25 @@ import { claudeRequest } from './claudehttp.js';
 import { writeSecretFileAtomically } from './helpers.js';
 import { HarnessProcesses } from './classes.harnessprocesses.js';
 
-/** The private file and lock contract verified for this Claude Code release. */
-export const CLAUDE_NATIVE_HANDOFF_VERSION = '2.1.273';
+/**
+ * The earliest Claude Code whose native file contract this adapter writes: `.credentials.json` beside
+ * `.claude.json`, and the lock protocol and live credential pickup verified for 2.1.273 (hints.md).
+ */
+export const CLAUDE_NATIVE_MINIMUM_VERSION = '2.1.273';
+/**
+ * The releases whose lock table, live credential pickup and refresh compare-and-swap were read from their own
+ * bundle (hints.md). A Claude Code session may keep running in the home a handoff writes only when it runs one
+ * of these; an installed release above the floor that is not listed is proven by `claude auth status` instead,
+ * and only while no session runs in that home.
+ */
+export const CLAUDE_NATIVE_VERIFIED_RELEASES: readonly string[] = ['2.1.273', '2.1.282'];
+/**
+ * Token files Claude Code reads at fixed paths when no descriptor variable names one (2.1.282 `KI`, `YGn`):
+ * the remote container's hand-off of an OAuth token or an API key. Either one outranks the native login.
+ */
+const REMOTE_CREDENTIAL_FILES = ['/home/claude/.claude/remote/.oauth_token', '/home/claude/.claude/remote/.api_key'] as const;
 const MAX_NATIVE_FILE_BYTES = 4 * 1024 * 1024;
+const AUTH_STATUS_TIMEOUT_MS = 4_000;
 const MAX_PROCESS_CONTEXT_BYTES = 1024 * 1024;
 const PROFILE_TIMEOUT_MS = 10_000;
 const ACCOUNT_CACHES = [
@@ -19,7 +35,8 @@ const ACCOUNT_CACHES = [
 const CREDENTIAL_OVERRIDES = [
   'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR', 'ANTHROPIC_API_KEY',
   'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_PROFILE', 'CLAUDE_CODE_USE_BEDROCK',
-  'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'ANTHROPIC_BASE_URL',
+  'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'CLAUDE_CODE_USE_ANTHROPIC_AWS',
+  'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD', 'CLAUDE_CODE_USE_MANTLE', 'ANTHROPIC_BASE_URL',
   'ANTHROPIC_FEDERATION_RULE_ID', 'ANTHROPIC_ORGANIZATION_ID',
   'ANTHROPIC_IDENTITY_TOKEN_FILE', 'ANTHROPIC_IDENTITY_TOKEN', 'ANTHROPIC_WORKSPACE_ID',
   'ANTHROPIC_UNIX_SOCKET', 'CLAUDE_CODE_REMOTE', 'CLAUDE_CODE_SIMPLE',
@@ -37,8 +54,9 @@ export class ClaudeNativeEffectiveAuthUnsupportedError extends Error {
 
   constructor(public readonly reason: TAuthSwitchClaudeProofFailure) {
     super(reason === 'unsupported_release'
-      ? `Native Claude handoff requires Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} for every active session.`
-      : `Cannot prove that Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} uses its native claude.ai login (${reason}).`);
+      ? `Native Claude handoff requires Claude Code ${CLAUDE_NATIVE_MINIMUM_VERSION} or newer, and a session `
+        + `running in this home must run a verified release (${CLAUDE_NATIVE_VERIFIED_RELEASES.join(', ')}).`
+      : `Cannot prove that Claude Code uses its native claude.ai login (${reason}).`);
   }
 }
 
@@ -95,6 +113,20 @@ export type TClaudeNativePrepareResult =
 
 export interface IClaudeNativeLockedSession {
   readStable(): IClaudeNativeSnapshot;
+  /**
+   * Proves that Claude Code itself selects the native login of `expected` in this home. A verified release is
+   * proven by the adapter's own reading of its selector; any other release above the floor is asked through
+   * `claude auth status --json`, which names the organization and the account's email, the only account
+   * identifiers it reports. Throws `ClaudeNativeEffectiveAuthUnsupportedError` when it cannot be proven, and
+   * `ClaudeCodeLockOutcomeUnknownError` when the locks were lost while it asked.
+   */
+  proveEffectiveLogin(expected: IClaudeNativeLogin): Promise<void>;
+  /**
+   * Writes back the exact bytes a written plan replaced, while the locks that guarded the write are still held.
+   * True once both files read back as they were; false, writing nothing, when the pair is no longer exactly
+   * what the plan wrote.
+   */
+  restorePreparedSource(plan: IClaudeNativePreparedWrite): boolean;
   verifyProfileIdentity(snapshot: IClaudeNativeSnapshot,
     expected: IClaudeNativeIdentity): Promise<IClaudeNativeProfileProof>;
   prepareWrite(input: {
@@ -115,6 +147,12 @@ export interface IClaudeNativeLockedSession {
 export interface IClaudeNativeVersionProbe {
   installedVersion(): string;
   runningContexts(): readonly IClaudeNativeRunningContext[];
+  /**
+   * What `claude auth status --json` prints under `env`, whatever its exit code, or null when it does not
+   * answer. Asynchronous on purpose: it runs while the vendor locks are held, and their renewal timers must keep
+   * running.
+   */
+  authStatus(env: NodeJS.ProcessEnv): Promise<string | null>;
 }
 
 /** Only selector keys and paths, never a process's credential values, leave the /proc reader. */
@@ -171,8 +209,30 @@ const onlyDigests = (value: IClaudeNativeDigests): IClaudeNativeDigests => ({
 });
 const preparedWrites = new WeakMap<IClaudeNativePreparedWrite, {
   session: ClaudeNativeLockedSession; credentialRaw: string; configRaw: string;
-  originalConfigRaw: Buffer | null; targetAccessToken: string;
+  originalCredentialRaw: Buffer | null; originalConfigRaw: Buffer | null; targetAccessToken: string;
 }>();
+/** A written plan's original bytes, kept until the handoff proves the write or restores them. */
+const writtenPlans = new WeakMap<IClaudeNativePreparedWrite, {
+  session: ClaudeNativeLockedSession; credentialRaw: string; configRaw: string;
+  originalCredentialRaw: Buffer; originalConfigRaw: Buffer;
+}>();
+
+const parseClaudeVersion = (value: string): [number, number, number] | null => {
+  const match = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})$/.exec(value);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+};
+const atLeast = (version: [number, number, number], minimum: [number, number, number]): boolean => {
+  for (let index = 0; index < 3; index++) {
+    if (version[index] !== minimum[index]) return version[index] > minimum[index];
+  }
+  return true;
+};
+
+/** Which proof applies to one operation: the adapter's own selector reading, or Claude Code's own answer. */
+interface IClaudeNativeSupport {
+  runningSessions: number;
+  proof: 'verified_release' | 'auth_status';
+}
 const sameIdentity = (left: IClaudeNativeIdentity, right: IClaudeNativeIdentity): boolean =>
   left.accountUuid === right.accountUuid && left.organizationUuid === right.organizationUuid;
 
@@ -303,6 +363,15 @@ const assertNoKnownNativeLoginOverride = (env: NodeJS.ProcessEnv, processRoot?:
   for (const key of CREDENTIAL_OVERRIDES) {
     if (env[key]) throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
   }
+  for (const file of REMOTE_CREDENTIAL_FILES) {
+    try {
+      plugins.fs.lstatSync(processViewPath(file, processRoot));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+    }
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+  }
   const configDir = env.ANTHROPIC_CONFIG_DIR?.trim()
     || (env.XDG_CONFIG_HOME?.trim()
       ? plugins.path.join(env.XDG_CONFIG_HOME.trim(), 'anthropic')
@@ -504,6 +573,20 @@ class ClaudeNativeVersionProbe implements IClaudeNativeVersionProbe {
     } catch { return 'unknown'; }
   }
 
+  public authStatus(env: NodeJS.ProcessEnv): Promise<string | null> {
+    // Well inside the shortest lock renewal window (the config lock renews every 5 s); it answers in ~200 ms.
+    return new Promise(resolve => {
+      const child = plugins.childProcess.execFile(this.executable, ['auth', 'status', '--json'], {
+        encoding: 'utf8', timeout: AUTH_STATUS_TIMEOUT_MS, maxBuffer: 64 * 1024, windowsHide: true, env,
+      }, (error, stdout) => {
+        // A logged-out status still prints its JSON and exits 1; only no answer at all is null.
+        const exited = error === null || typeof error.code === 'number';
+        resolve(exited && stdout ? stdout : null);
+      });
+      child.stdin?.end();
+    });
+  }
+
   public runningContexts(): readonly IClaudeNativeRunningContext[] {
     const contexts: IClaudeNativeRunningContext[] = [];
     // Keep candidates from every mount namespace: a bind mount can expose the same inode.
@@ -597,7 +680,7 @@ export class ClaudeNativeAdapter {
     this.platform = options.platform ?? process.platform;
   }
 
-  private assertSupported(): number {
+  private assertSupported(): IClaudeNativeSupport {
     if (this.platform !== 'linux') throw new Error('Native Claude handoff requires the verified Linux file backend.');
     const home = plugins.fs.lstatSync(this.options.configDir);
     if (!home.isDirectory() || home.isSymbolicLink() || home.uid !== process.getuid?.()
@@ -621,9 +704,12 @@ export class ClaudeNativeAdapter {
     for (const file of this.settingsFiles) {
       assertSettingsSelectNative(file);
     }
-    if (this.versionProbe.installedVersion() !== CLAUDE_NATIVE_HANDOFF_VERSION) {
+    const installedText = this.versionProbe.installedVersion();
+    const installed = parseClaudeVersion(installedText);
+    if (!installed || !atLeast(installed, parseClaudeVersion(CLAUDE_NATIVE_MINIMUM_VERSION)!)) {
       throw new ClaudeNativeEffectiveAuthUnsupportedError('unsupported_release');
     }
+    const installedVerified = CLAUDE_NATIVE_VERIFIED_RELEASES.includes(installedText);
     let runningSessions = 0;
     const nativeHomeIdentity = directoryIdentity(this.options.configDir);
     const configParentIdentity = directoryIdentity(configParent);
@@ -636,7 +722,9 @@ export class ClaudeNativeAdapter {
         || !sameDirectory(running.configParentIdentity, configParentIdentity)) {
         throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
       }
-      if (running.version !== CLAUDE_NATIVE_HANDOFF_VERSION) {
+      // A session keeps taking its own locks and picking up the swapped login while the handoff runs, so
+      // it must be a release whose lock and pickup contract was read from its bundle.
+      if (running.version === null || !CLAUDE_NATIVE_VERIFIED_RELEASES.includes(running.version)) {
         throw new ClaudeNativeEffectiveAuthUnsupportedError('unsupported_release');
       }
       if (!running.env || !running.cwd || running.hasSettingsOverride === null
@@ -650,7 +738,34 @@ export class ClaudeNativeAdapter {
       assertProjectSettingsSelectNative(running.cwd, running.processRoot);
       runningSessions++;
     }
-    return runningSessions;
+    // An installed release nobody verified is proven by its own answer, which says nothing about how a session
+    // already running would take the locks or pick up the swap; it is written only while none runs here.
+    if (!installedVerified && runningSessions > 0) {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('unsupported_release');
+    }
+    return { runningSessions, proof: installedVerified ? 'verified_release' : 'auth_status' };
+  }
+
+  /**
+   * Claude Code's own account of the login it selects in this home: `claude auth status --json` under the
+   * adapter's environment. It must be the claude.ai login of `expected`, read from this home, with no API key.
+   */
+  private async proveEffectiveLogin(expected: IClaudeNativeLogin): Promise<void> {
+    if (this.assertSupported().proof === 'verified_release') return;
+    const organizationUuid = expected.oauthAccount.organizationUuid;
+    const email = typeof expected.oauthAccount.emailAddress === 'string' ? expected.oauthAccount.emailAddress : null;
+    const raw = await this.versionProbe.authStatus(this.env);
+    let status: unknown;
+    try { status = raw === null ? null : JSON.parse(raw); } catch { status = null; }
+    if (!isRecord(status) || typeof status.loggedIn !== 'boolean' || typeof status.authMethod !== 'string') {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('unsupported_release');
+    }
+    if (status.loggedIn !== true || status.authMethod !== 'claude.ai' || status.apiProvider !== 'firstParty'
+      || (status.apiKeySource !== undefined && status.apiKeySource !== null)
+      || status.configDirectory !== this.options.configDir || status.orgId !== organizationUuid
+      || (status.email ?? null) !== email) {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+    }
   }
 
   /** The caller keeps its NoSQLDB journal and both ownership transactions inside this callback. */
@@ -659,12 +774,13 @@ export class ClaudeNativeAdapter {
     return this.locks.holdAsync(async lease => {
       this.assertSupported();
       const session = new ClaudeNativeLockedSession(this.credentialFile, this.options.configFile,
-        this.fetcher, lease, () => this.assertSupported());
+        this.fetcher, lease, () => this.assertSupported().runningSessions,
+        expected => this.proveEffectiveLogin(expected));
       const firstSnapshot = session.readStable();
       const result = await action(session);
       try {
         lease.assertHeld();
-        const afterRunningSessions = this.assertSupported();
+        const afterRunningSessions = this.assertSupported().runningSessions;
         if (firstSnapshot.runningEffectiveAuth === 'no_scoped_sessions' && afterRunningSessions > 0) {
           throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
         }
@@ -680,7 +796,34 @@ export class ClaudeNativeAdapter {
 class ClaudeNativeLockedSession implements IClaudeNativeLockedSession {
   constructor(private readonly credentialFile: string, private readonly configFile: string,
     private readonly fetcher: typeof fetch, private readonly lease: IClaudeCodeLockLease,
-    private readonly assertSupported: () => number) {}
+    private readonly assertSupported: () => number,
+    private readonly proveEffective: (expected: IClaudeNativeLogin) => Promise<void>) {}
+
+  public async proveEffectiveLogin(expected: IClaudeNativeLogin): Promise<void> {
+    this.lease.assertHeld();
+    await this.proveEffective(expected);
+    // Asserted after the answer, before anything is decided or written on it.
+    this.lease.assertHeld();
+  }
+
+  public restorePreparedSource(plan: IClaudeNativePreparedWrite): boolean {
+    this.lease.assertHeld();
+    const written = writtenPlans.get(plan);
+    if (!written || written.session !== this) throw new Error('Claude native write plan is not held by this lease.');
+    writtenPlans.delete(plan);
+    let current: ReturnType<typeof readPair>;
+    try { current = readPair(this.credentialFile, this.configFile); } catch { return false; }
+    if (!sameRaw(current.credentialRaw, Buffer.from(written.credentialRaw))
+      || !sameRaw(current.configRaw, Buffer.from(written.configRaw))) return false;
+    this.lease.assertHeld();
+    writeSecretFileAtomically(this.credentialFile, written.originalCredentialRaw.toString('utf8'));
+    writeSecretFileAtomically(this.configFile, written.originalConfigRaw.toString('utf8'));
+    this.lease.assertHeld();
+    const restored = readPair(this.credentialFile, this.configFile);
+    return sameRaw(restored.credentialRaw, written.originalCredentialRaw)
+      && sameRaw(restored.configRaw, written.originalConfigRaw)
+      && sameDigests(digests(restored), plan.before);
+  }
 
   private observation(): IClaudeNativeDigests | null {
     try { return digests(readPair(this.credentialFile, this.configFile)); }
@@ -811,7 +954,7 @@ class ClaudeNativeLockedSession implements IClaudeNativeLockedSession {
       targetIdentity: Object.freeze({ ...input.expectedIdentity }),
       profile: Object.freeze({ ...profile }),
     });
-    preparedWrites.set(plan, { session: this, credentialRaw, configRaw,
+    preparedWrites.set(plan, { session: this, credentialRaw, configRaw, originalCredentialRaw: original.credentialRaw,
       originalConfigRaw: original.configRaw, targetAccessToken: String(target.login.claudeAiOauth.accessToken) });
     return { kind: 'prepared', plan };
   }
@@ -864,6 +1007,10 @@ class ClaudeNativeLockedSession implements IClaudeNativeLockedSession {
         || plan.profile.accessTokenDigest !== hash(String(snapshot.login.claudeAiOauth.accessToken))) {
         return { kind: 'uncertain', reason: 'native_write_or_readback_failed', observed: onlyDigests(snapshot) };
       }
+      if (prepared.originalCredentialRaw !== null && prepared.originalConfigRaw !== null) {
+        writtenPlans.set(plan, { session: this, credentialRaw: prepared.credentialRaw, configRaw: prepared.configRaw,
+          originalCredentialRaw: prepared.originalCredentialRaw, originalConfigRaw: prepared.originalConfigRaw });
+      }
       return { kind: 'written', snapshot, profile: plan.profile };
     } catch {
       return { kind: 'uncertain', reason: 'native_write_or_readback_failed', observed: this.observation() };

package/ts/classes.cli.ts

@@ -9,7 +9,8 @@ import { readAccountList } from './classes.accountlist.js';
 import { AccountListRenderer } from './classes.listrenderer.js';
 import { accountLimits, activeAccounts, CondensedRenderer } from './classes.limits.js';
 import { consoleHeading, consoleTable } from './consoletable.js';
-import { accountName, credentialDriftNote, readAccountBadges, until, usagePercentText } from './accounts.js';
+import { accountName, credentialDriftNote, readAccountBadges, usagePercentText } from './accounts.js';
+import { until } from './timetext.js';
 import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
 import { defaultPreusePrompt, preuseAccounts, preuseCountsText, PreuseError, preuseTargets, validatePreuseOptions,
   type IPreuseRunSummary, type TPreuseAccountResult, type TPreuseOutcome, type TPreuseRunEvent } from './preuse.js';

package/ts/classes.codexpreuse.ts

@@ -1,8 +1,8 @@
 import * as plugins from './plugins.js';
 import type { ICodexIdentity } from './interfaces.js';
 import type { IHarnessPreuseOptions, IHarnessPreuseResult } from './interfaces.harness.js';
-import { PreuseError, PreuseFailureError, PreuseLimitError, preuseMayHaveConsumed, validatePreuseOptions,
-  type IPreuseLimit } from './preuse.js';
+import type { IAuthSwitchPreuseLimit } from './authority-contract.js';
+import { PreuseError, PreuseFailureError, PreuseLimitError, preuseMayHaveConsumed, validatePreuseOptions } from './preuse.js';
 import { parseOpenAiTokenClaims } from './openaiauth.js';
 import { OpenAiBackendError, readOpenAiAccountUsage, type IOpenAiAccountUsage } from './openaiusage.js';
 import { usageWindowPeriod } from './accounts.js';
@@ -14,7 +14,7 @@ const PREUSE_TIMEOUT_MS = 180_000;
  * The limit the account's own usage reading says is reached, or null. Every window at its limit must reset
  * before a prompt can pass, so the one that resets last is named.
  */
-const reachedLimit = (usage: IOpenAiAccountUsage): IPreuseLimit | null => {
+const reachedLimit = (usage: IOpenAiAccountUsage): IAuthSwitchPreuseLimit | null => {
   const limit = usage.rateLimits.rateLimit;
   if (!limit || (limit.allowed && !limit.limitReached)) return null;
   const exhausted = [limit.primaryWindow, limit.secondaryWindow]

package/ts/classes.limits.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
-import { accountTypeText, compactSince, compactUntil, credentialDriftNote, localDate, orderedUsageWindows, usagePercentText } from './accounts.js';
+import { accountTypeText, credentialDriftNote, orderedUsageWindows, usagePercentText } from './accounts.js';
+import { compactSince, compactUntil, localDate } from './timetext.js';
 import { consoleHeading, consoleNote, consoleTable } from './consoletable.js';
 import type { IAccountList, IAccountLimitRow, IAccountLimits, IActiveAccountDrift, IActiveAccountRow, IActiveAccounts, IHarnessAccountList } from './interfaces.list.js';
 import type { IAccountType, IAuthHarness, IHarnessBilling, IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';

package/ts/classes.listrenderer.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
-import { accountUsageWindows, compactUsageLine, credentialDriftProblem, localDate, localDateTime, localiseTimestamps } from './accounts.js';
+import { accountUsageWindows, compactUsageLine, credentialDriftProblem } from './accounts.js';
+import { localDate, localDateTime, localiseTimestamps } from './timetext.js';
 import { accountBilling, accountCell, accountLimits, accountType, CondensedRenderer, nextRenewal, renewalCell, UNAVAILABLE, usageColor, type THarnessTraits } from './classes.limits.js';
 import { consoleHeading, consoleNote, consoleTable, consoleWidth } from './consoletable.js';
 import type { IHarnessStatusFact, IHarnessStatusSummary } from './interfaces.harness.js';

package/ts/classes.tui.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome } from './interfaces.harness.js';
-import { accountBadge, accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usageWindowName, until, readAccountRows, type IAccountRow } from './accounts.js';
+import { accountBadge, accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usageWindowName, readAccountRows, type IAccountRow } from './accounts.js';
+import { until } from './timetext.js';
 import { defaultPreusePrompt, preuseAccounts, preuseCountsText, preuseTargets, type TPreuseAccountResult } from './preuse.js';
 import { plainText } from './formatting.js';
 import { AuthSwitchOperations, authSwitchMutationReplacesLogin, type TAuthSwitchMutation } from './classes.operations.js';

package/ts/classes.watch.ts

@@ -1,4 +1,5 @@
-import { accountBadge, accountName, durationText, localTime, readAccountRows, type IAccountRow } from './accounts.js';
+import { accountBadge, accountName, durationText, readAccountRows, type IAccountRow } from './accounts.js';
+import { localTime } from './timetext.js';
 import { pause } from './helpers.js';
 import { bold, dim, green, orange, plainText, red } from './formatting.js';
 import { decideWatchAction, type IWatchReading } from './watchpolicy.js';

package/ts/index.ts

@@ -11,6 +11,7 @@ export * from './classes.claudestatus.js';
 export * from './classes.codexstatus.js';
 export * from './classes.codexpreuse.js';
 export * from './preuse.js';
+export * from './preuse-text.js';
 export * from './helpers.js';
 export * from './classes.codexhome.js';
 export * from './classes.codexauth.js';

package/ts/preuse-text.ts

@@ -0,0 +1,40 @@
+/**
+ * The sentences that name what stopped a preuse, with no Node dependency.
+ *
+ * A preuse receipt carries its limit and its cause as data (`IAuthSwitchPreuseOperation.limit` and `.failure`);
+ * the command line and a host that shows receipts, AGL's web client for one, must word them alike. This module
+ * therefore loads nothing but the time text it renders a reset with, which imports nothing either, so that it can
+ * be bundled for a browser through the `@modelprofile.com/authswitch/preuse-text` entry point. The receipt types
+ * are type-only imports, which the emitted JavaScript drops.
+ */
+import type { IAuthSwitchPreuseFailure, IAuthSwitchPreuseLimit } from './authority-contract.js';
+import { localDateTime, until } from './timetext.js';
+
+export { localDateTime } from './timetext.js';
+
+/**
+ * `Weekly usage limit reached, resets in 16h 46min (2026-09-27 05:12)`: human text, so the reset reads in local time.
+ * The limit itself keeps its ISO `resetsAt` for receipts and JSON output.
+ */
+export const describePreuseLimit = (limitArg: IAuthSwitchPreuseLimit, nowArg: number): string => {
+  const name = `${limitArg.window === null ? '' : `${limitArg.window} `}${limitArg.kind === 'usage_limit' ? 'usage' : 'rate'} limit reached`;
+  const countdown = limitArg.resetsAt === null ? null : until(limitArg.resetsAt, nowArg);
+  const at = localDateTime(limitArg.resetsAt);
+  const reset = limitArg.resetsAt === null ? ''
+    : countdown === 'due' ? `, due to reset now (${at})` : `, resets in ${countdown} (${at})`;
+  return `${name.charAt(0).toUpperCase()}${name.slice(1)}${reset}`;
+};
+
+/** `the provider answered HTTP 503`: the cause of a failed preuse, as the tail of a sentence. */
+export const describePreuseFailure = (failureArg: IAuthSwitchPreuseFailure): string => {
+  const status = failureArg.status === null ? null : `HTTP ${failureArg.status}`;
+  switch (failureArg.kind) {
+    case 'http': return `the provider answered ${status ?? 'with an HTTP error'}`;
+    case 'stream':
+      return `the answer stream reported an error${failureArg.providerCode === null ? '' : ` (code ${failureArg.providerCode})`}`;
+    case 'response': return `the provider's answer${status ? ` (${status})` : ''} could not be read`;
+    case 'network': return 'no answer arrived: the connection failed';
+    case 'aborted': return 'the request was aborted';
+    case 'unknown': return 'the request ended in an error that names no cause';
+  }
+};

package/ts/preuse.ts

@@ -1,4 +1,6 @@
-import { localDateTime, orderedUsageWindows, until } from './accounts.js';
+import type { IAuthSwitchPreuseFailure, IAuthSwitchPreuseLimit } from './authority-contract.js';
+import { orderedUsageWindows } from './accounts.js';
+import { describePreuseFailure, describePreuseLimit } from './preuse-text.js';
 import type { IAuthHarness, IHarnessAccount, IHarnessPreuseOptions, IHarnessPreuseResult, IHarnessUsageWindow } from './interfaces.harness.js';
 
 export const defaultPreusePrompt = 'Write 2000 words about strawberries.';
@@ -18,31 +20,8 @@ export class PreuseError extends Error {
   constructor(messageArg: string, public readonly requestStarted = false) { super(messageArg); }
 }
 
-/**
- * A limit that kept a preuse prompt from being answered.
- *
- * `usage_limit` is the account's quota, spent until it resets; `rate_limit` a short throttle. `window` names the
- * window by its length (`weekly`, `five-hour`) and `resetsAt` is an ISO time; either is null when the account's
- * usage reading or the provider's refusal did not state it.
- */
-export interface IPreuseLimit {
-  kind: 'usage_limit' | 'rate_limit';
-  window: string | null;
-  resetsAt: string | null;
-}
-
-/**
- * `Weekly usage limit reached, resets in 16h 46min (2026-09-27 05:12)`: human text, so the reset reads in local time.
- * The limit itself keeps its ISO `resetsAt` for receipts and JSON output.
- */
-export const describePreuseLimit = (limitArg: IPreuseLimit, nowArg: number): string => {
-  const name = `${limitArg.window === null ? '' : `${limitArg.window} `}${limitArg.kind === 'usage_limit' ? 'usage' : 'rate'} limit reached`;
-  const countdown = limitArg.resetsAt === null ? null : until(limitArg.resetsAt, nowArg);
-  const at = localDateTime(limitArg.resetsAt);
-  const reset = limitArg.resetsAt === null ? ''
-    : countdown === 'due' ? `, due to reset now (${at})` : `, resets in ${countdown} (${at})`;
-  return `${name.charAt(0).toUpperCase()}${name.slice(1)}${reset}`;
-};
+/** The authority's `IAuthSwitchPreuseLimit`, under the name the package root has exported since 10.0.0. */
+export type IPreuseLimit = IAuthSwitchPreuseLimit;
 
 /**
  * A preuse a limit stopped. `usage` is the account's own usage reading before anything was sent; `provider`
@@ -50,7 +29,7 @@ export const describePreuseLimit = (limitArg: IPreuseLimit, nowArg: number): str
  * answer: a refusal before its answer consumed nothing.
  */
 export class PreuseLimitError extends PreuseError {
-  constructor(public readonly limit: IPreuseLimit, public readonly source: 'usage' | 'provider',
+  constructor(public readonly limit: IAuthSwitchPreuseLimit, public readonly source: 'usage' | 'provider',
     public readonly generationStarted: boolean, nowArg: number) {
     const described = describePreuseLimit(limit, nowArg);
     super(source === 'usage' ? `${described}. No preuse prompt was sent.`
@@ -61,37 +40,12 @@ export class PreuseLimitError extends PreuseError {
   }
 }
 
-/**
- * Why a sent preuse prompt failed without a limit, and never with the provider's text.
- *
- * `http` is an answer with an HTTP error status; `stream` an error the answer stream reported after it began,
- * with the machine-readable code the provider stated and no status, since its answer was a success; `response` an answer that could not be read;
- * `network` a connection that failed before any answer; `aborted` an abort that was neither the caller's nor the
- * deadline; `unknown` anything else. `status` and `providerCode` are null when the failure did not state them.
- */
-export interface IPreuseFailure {
-  kind: 'http' | 'stream' | 'response' | 'network' | 'aborted' | 'unknown';
-  status: number | null;
-  providerCode: string | null;
-}
-
-/** `the provider answered HTTP 503`: the cause of a failed preuse, as the tail of a sentence. */
-export const describePreuseFailure = (failureArg: IPreuseFailure): string => {
-  const status = failureArg.status === null ? null : `HTTP ${failureArg.status}`;
-  switch (failureArg.kind) {
-    case 'http': return `the provider answered ${status ?? 'with an HTTP error'}`;
-    case 'stream':
-      return `the answer stream reported an error${failureArg.providerCode === null ? '' : ` (code ${failureArg.providerCode})`}`;
-    case 'response': return `the provider's answer${status ? ` (${status})` : ''} could not be read`;
-    case 'network': return 'no answer arrived: the connection failed';
-    case 'aborted': return 'the request was aborted';
-    case 'unknown': return 'the request ended in an error that names no cause';
-  }
-};
+/** The authority's `IAuthSwitchPreuseFailure`, under the name the package root has exported since 10.0.0. */
+export type IPreuseFailure = IAuthSwitchPreuseFailure;
 
 /** A sent preuse prompt that failed for the stated cause; its tokens may have been consumed. */
 export class PreuseFailureError extends PreuseError {
-  constructor(public readonly failure: IPreuseFailure) {
+  constructor(public readonly failure: IAuthSwitchPreuseFailure) {
     super(`Preuse did not complete: ${describePreuseFailure(failure)}. ${preuseMayHaveConsumed}`, true);
   }
 }

package/ts/timetext.ts

@@ -0,0 +1,76 @@
+/**
+ * Human time text: countdowns to a deadline and timestamps in local calendar time.
+ *
+ * It imports nothing, so the browser-safe `./preuse-text` entry point can render a reset exactly as the
+ * command line does without pulling a Node built-in into a bundle.
+ */
+
+/** A countdown is a snapshot of the provider's deadline, not proof a quota has reset. */
+export const until = (timestampArg: string | null, nowArg: number): string => {
+  if (timestampArg === null) return 'Not scheduled';
+  const remaining = Date.parse(timestampArg) - nowArg;
+  if (!Number.isFinite(remaining)) return 'Unavailable';
+  if (remaining <= 0) return 'due';
+  const minutes = Math.floor(remaining / 60000);
+  if (!minutes) return '<1min';
+  const days = Math.floor(minutes / 1440);
+  const hours = Math.floor(minutes % 1440 / 60);
+  return [days ? `${days}d` : '', hours ? `${hours}h` : '', minutes % 60 ? `${minutes % 60}min` : ''].filter(Boolean).join(' ');
+};
+/**
+ * A two-unit countdown for condensed tables: `2h 13m`, `3d 4h`, `45m`.
+ *
+ * `until` stays the long form used by the list view and the TUI. This one trades the third unit for
+ * a column that never wraps, and it never invents a deadline: an unknown or unparseable timestamp is
+ * reported as such rather than as zero time remaining.
+ */
+const twoUnits = (millisecondsArg: number): string => {
+  const minutes = Math.floor(millisecondsArg / 60000);
+  const days = Math.floor(minutes / 1440);
+  const hours = Math.floor(minutes % 1440 / 60);
+  if (days) return hours ? `${days}d ${hours}h` : `${days}d`;
+  if (hours) return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`;
+  return `${minutes}m`;
+};
+export const compactUntil = (timestampArg: string | null, nowArg: number, unavailableArg = 'n/a'): string => {
+  if (timestampArg === null) return 'not scheduled';
+  const remaining = Date.parse(timestampArg) - nowArg;
+  if (!Number.isFinite(remaining)) return unavailableArg;
+  if (remaining <= 0) return 'due';
+  return remaining < 60000 ? '<1m' : twoUnits(remaining);
+};
+/**
+ * The same two-unit form for a past timestamp, for "saved 3d 4h ago".
+ *
+ * The result is always a bare duration or the caller's unavailable marker, never a phrase: callers
+ * suffix it ("... ago"), and a phrase would read as "just now ago". A span under a minute is `<1m`,
+ * exactly as `compactUntil` reports one.
+ */
+export const compactSince = (timestampArg: string | null, nowArg: number, unavailableArg = 'n/a'): string => {
+  if (timestampArg === null) return unavailableArg;
+  const elapsed = nowArg - Date.parse(timestampArg);
+  if (!Number.isFinite(elapsed)) return unavailableArg;
+  return elapsed < 60000 ? '<1m' : twoUnits(elapsed);
+};
+const twoDigits = (valueArg: number): string => String(valueArg).padStart(2, '0');
+/**
+ * A timestamp in local calendar time: `2026-10-08`, or `2026-10-08 23:14` with the time. Human output never prints
+ * a raw ISO timestamp; an unknown or unparseable one reads as the caller's unavailable marker.
+ */
+const localTimestamp = (timestampArg: string | null, withTimeArg: boolean, unavailableArg: string): string => {
+  const time = timestampArg === null ? Number.NaN : Date.parse(timestampArg);
+  if (!Number.isFinite(time)) return unavailableArg;
+  const date = new Date(time);
+  const day = `${date.getFullYear()}-${twoDigits(date.getMonth() + 1)}-${twoDigits(date.getDate())}`;
+  return withTimeArg ? `${day} ${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}` : day;
+};
+export const localDate = (timestampArg: string | null, unavailableArg = 'n/a'): string => localTimestamp(timestampArg, false, unavailableArg);
+export const localDateTime = (timestampArg: string | null, unavailableArg = 'n/a'): string => localTimestamp(timestampArg, true, unavailableArg);
+/** A moment's local time of day with seconds, `14:02:07`, for a log line whose date is implied. */
+export const localTime = (timeArg: number): string => {
+  const date = new Date(timeArg);
+  return [date.getHours(), date.getMinutes(), date.getSeconds()].map(twoDigits).join(':');
+};
+const ISO_TIMESTAMP = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})/g;
+/** Provider text with every ISO 8601 timestamp in it rewritten as local date and time. */
+export const localiseTimestamps = (textArg: string): string => textArg.replace(ISO_TIMESTAMP, match => localDateTime(match, match));

package/ts/watchpolicy.ts

@@ -1,4 +1,5 @@
-import { compactUntil, usagePercentText } from './accounts.js';
+import { usagePercentText } from './accounts.js';
+import { compactUntil } from './timetext.js';
 import { plainText } from './formatting.js';
 import type { IHarnessUsageWindow } from './interfaces.harness.js';