@modelprofile.com/authswitch 2.1.2

package/ts/classes.codexauth.ts

@@ -0,0 +1,199 @@
+import * as plugins from './plugins.js';
+import type { IActiveAuth, ICodexIdentity, TAuthSource } from './interfaces.js';
+import { CodexHome } from './classes.codexhome.js';
+import { writeSecretFileAtomically } from './helpers.js';
+
+/**
+ * Decodes the payload of a JWT without verifying it.
+ *
+ * authswitch never uses these claims for authorization -- only to label a stash
+ * with the account it belongs to -- so signature verification would buy nothing.
+ */
+const decodeJwtPayload = (tokenArg: string): Record<string, unknown> | null => {
+  const segments = tokenArg.split('.');
+  if (segments.length < 2) {
+    return null;
+  }
+  try {
+    const decoded = Buffer.from(segments[1], 'base64url').toString('utf8');
+    const parsed: unknown = JSON.parse(decoded);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+const asString = (valueArg: unknown): string | null =>
+  typeof valueArg === 'string' && valueArg.length > 0 ? valueArg : null;
+
+/**
+ * Walks an arbitrary JSON value and returns the first string that looks like a JWT.
+ * Used as a fallback so a Codex schema change cannot silently break stash labelling.
+ */
+const findFirstJwt = (valueArg: unknown, depthArg = 0): string | null => {
+  if (depthArg > 6) {
+    return null;
+  }
+  if (typeof valueArg === 'string') {
+    return /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+$/.test(valueArg) ? valueArg : null;
+  }
+  if (Array.isArray(valueArg)) {
+    for (const itemArg of valueArg) {
+      const found = findFirstJwt(itemArg, depthArg + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (valueArg && typeof valueArg === 'object') {
+    for (const itemArg of Object.values(valueArg as Record<string, unknown>)) {
+      const found = findFirstJwt(itemArg, depthArg + 1);
+      if (found) return found;
+    }
+  }
+  return null;
+};
+
+/**
+ * Reads, writes and clears the Codex file credential store, and derives the
+ * account identity used to key a stash.
+ *
+ * Nothing in this class logs or returns a token value; only the raw string that
+ * callers copy verbatim between the active slot and the stash.
+ */
+export class CodexAuth {
+  public readonly codexHome: CodexHome;
+
+  constructor(codexHomeArg: CodexHome) {
+    this.codexHome = codexHomeArg;
+  }
+
+  /**
+   * Extracts the account identity from the content of an auth.json.
+   * Returns null when the file holds no recognisable credential.
+   */
+  public identityFromRaw(rawArg: string): ICodexIdentity | null {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawArg);
+    } catch {
+      return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+    const record = parsed as Record<string, unknown>;
+
+    const tokens = (record.tokens ?? null) as Record<string, unknown> | null;
+    const idToken =
+      (tokens ? asString(tokens.id_token) : null) ?? findFirstJwt(record);
+
+    if (idToken) {
+      const claims = decodeJwtPayload(idToken) ?? {};
+      const authClaim = (claims['https://api.openai.com/auth'] ?? {}) as Record<string, unknown>;
+      const profileClaim = (claims['https://api.openai.com/profile'] ?? {}) as Record<string, unknown>;
+      const email =
+        asString(claims.email) ??
+        asString(profileClaim.email) ??
+        asString(authClaim.user_email);
+      const accountId =
+        asString(authClaim.chatgpt_account_id) ??
+        (tokens ? asString(tokens.account_id) : null) ??
+        asString(record.account_id);
+      if (email) {
+        return {
+          kind: 'chatgpt',
+          email: email.toLowerCase(),
+          accountId,
+          planType: asString(authClaim.chatgpt_plan_type),
+          userId: asString(authClaim.user_id) ?? asString(claims.sub),
+        };
+      }
+      if (accountId) {
+        // An OAuth credential we cannot label by email is still worth stashing;
+        // key it by account id so it round-trips instead of being silently dropped.
+        return {
+          kind: 'chatgpt',
+          email: `account:${accountId}`,
+          accountId,
+          planType: asString(authClaim.chatgpt_plan_type),
+          userId: asString(authClaim.user_id) ?? asString(claims.sub),
+        };
+      }
+    }
+
+    const apiKey = asString(record.OPENAI_API_KEY) ?? asString(record.openai_api_key);
+    if (apiKey) {
+      const fingerprint = this.fingerprint(apiKey);
+      return {
+        kind: 'apikey',
+        email: `apikey:${fingerprint}`,
+        accountId: null,
+        planType: null,
+        userId: null,
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * A short, non-reversible label for an API key so two different keys get two
+   * different stashes without the key itself ever being written down.
+   */
+  private fingerprint(secretArg: string): string {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < secretArg.length; index++) {
+      hash ^= secretArg.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+  }
+
+  /** Reads the active credential, if any. */
+  public readActive(): IActiveAuth {
+    const authFilePath = this.codexHome.authFilePath;
+    if (!plugins.fs.existsSync(authFilePath)) {
+      return {
+        source: this.detectNonFileSource(),
+        authFilePath,
+        identity: null,
+        raw: null,
+      };
+    }
+    const raw = plugins.fs.readFileSync(authFilePath, 'utf8');
+    return {
+      source: 'file',
+      authFilePath,
+      identity: this.identityFromRaw(raw),
+      raw,
+    };
+  }
+
+  /**
+   * When no auth.json exists the credential is either absent or held by an OS
+   * keyring. The age-encrypted secrets directory is the observable marker of the
+   * keyring-backed store, so use it to tell the two apart.
+   */
+  private detectNonFileSource(): TAuthSource {
+    if (plugins.fs.existsSync(this.codexHome.secretsDir)) {
+      return 'keyring';
+    }
+    return 'none';
+  }
+
+  /** Writes a credential into the active slot atomically and owner-only. */
+  public writeActive(rawArg: string): void {
+    plugins.fs.mkdirSync(this.codexHome.dir, { recursive: true });
+    writeSecretFileAtomically(this.codexHome.authFilePath, rawArg);
+  }
+
+  /** Removes the active credential. Safe to call when none exists. */
+  public clearActive(): void {
+    if (plugins.fs.existsSync(this.codexHome.authFilePath)) {
+      plugins.fs.rmSync(this.codexHome.authFilePath);
+    }
+  }
+}

package/ts/classes.codexdaemon.ts

@@ -0,0 +1,137 @@
+import * as plugins from './plugins.js';
+import type { ICommandResult, IDaemonStatus } from './interfaces.js';
+import { CodexHome } from './classes.codexhome.js';
+import { describeCodexFailure } from './helpers.js';
+
+/**
+ * Drives the Codex CLI itself for everything Codex already exposes.
+ *
+ * The local app-server holds the remote-control websocket, keeps the state
+ * database open, and refreshes tokens on its own schedule, so a credential swap
+ * has to happen while it is stopped. Codex ships
+ * `codex app-server daemon {start,stop,version}` for exactly this, so authswitch
+ * goes through those rather than signalling pids behind Codex' back.
+ */
+export class CodexDaemon {
+  public readonly codexHome: CodexHome;
+  private readonly binary: string;
+
+  constructor(codexHomeArg: CodexHome, binaryArg?: string) {
+    this.codexHome = codexHomeArg;
+    this.binary = binaryArg ?? process.env.AUTHSWITCH_CODEX_BIN ?? 'codex';
+  }
+
+  /** Whether the Codex CLI can be executed at all. */
+  public isAvailable(): boolean {
+    return this.run(['--version']).ok;
+  }
+
+  /**
+   * Authoritative daemon status, straight from Codex.
+   * Returns null when the Codex CLI cannot be reached or answers unexpectedly,
+   * which callers treat as "unknown" rather than "stopped".
+   */
+  public status(): IDaemonStatus | null {
+    const result = this.run(['app-server', 'daemon', 'version']);
+    if (!result.ok) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(result.stdout.trim()) as Record<string, unknown>;
+      return {
+        running: parsed.status === 'running',
+        backend: typeof parsed.backend === 'string' ? parsed.backend : null,
+        appServerVersion:
+          typeof parsed.appServerVersion === 'string' ? parsed.appServerVersion : null,
+        cliVersion: typeof parsed.cliVersion === 'string' ? parsed.cliVersion : null,
+        socketPath: typeof parsed.socketPath === 'string' ? parsed.socketPath : null,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /** True when remote control is enabled for future daemon starts. */
+  public isRemoteControlEnabled(): boolean {
+    const settingsPath = this.codexHome.appServerSettingsPath;
+    if (!plugins.fs.existsSync(settingsPath)) {
+      return false;
+    }
+    try {
+      const parsed = JSON.parse(plugins.fs.readFileSync(settingsPath, 'utf8')) as {
+        remoteControlEnabled?: boolean;
+      };
+      return parsed.remoteControlEnabled === true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** The pid of the managed daemon, when its pid file is readable. */
+  public daemonPid(): number | null {
+    const pidPath = this.codexHome.appServerPidPath;
+    if (!plugins.fs.existsSync(pidPath)) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(plugins.fs.readFileSync(pidPath, 'utf8')) as { pid?: number };
+      return typeof parsed.pid === 'number' ? parsed.pid : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Whether a daemon is up. Prefers Codex' own answer and falls back to the pid
+   * file so the check still works when the Codex CLI is not on PATH.
+   */
+  public isDaemonRunning(): boolean {
+    const status = this.status();
+    if (status !== null) {
+      return status.running;
+    }
+    const pid = this.daemonPid();
+    if (pid === null) {
+      return false;
+    }
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public stop(): ICommandResult {
+    return this.run(['app-server', 'daemon', 'stop']);
+  }
+
+  public start(): ICommandResult {
+    return this.run(['app-server', 'daemon', 'start']);
+  }
+
+  /** A one-line diagnosis of a failed invocation, suitable for an error message. */
+  public describeFailure(resultArg: ICommandResult): string {
+    return describeCodexFailure(
+      this.binary,
+      resultArg.stdout,
+      resultArg.stderr,
+      resultArg.spawnError,
+    );
+  }
+
+  private run(argsArg: string[]): ICommandResult {
+    const result = plugins.childProcess.spawnSync(this.binary, argsArg, {
+      encoding: 'utf8',
+      timeout: 60_000,
+      env: { ...process.env, CODEX_HOME: this.codexHome.dir },
+    });
+    return {
+      ok: result.status === 0,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+      code: result.status,
+      spawnError: result.error ? result.error.message : null,
+    };
+  }
+}

package/ts/classes.codexharness.ts

@@ -0,0 +1,233 @@
+import { CodexSwitcher } from './classes.codexswitcher.js';
+import { CodexAccountStatus } from './classes.codexstatus.js';
+import { CodexPreuse } from './classes.codexpreuse.js';
+import { PreuseError } from './preuse.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessAccountStatus, IHarnessOutcome, IHarnessState, IHarnessPreuseOptions, IHarnessPreuseResult } from './interfaces.harness.js';
+import type { IStashListing } from './interfaces.js';
+import { countPaired, enrollmentState } from './helpers.js';
+import { beginSavedOpenAiLogin } from './classes.login.js';
+import { plainText } from './formatting.js';
+import type { IHarnessLoginOptions, IHarnessLoginProvider } from './interfaces.harness.js';
+
+/** Codex-specific credentials, remote-control handling and service status. */
+export class CodexHarness implements IAuthHarness {
+  public readonly id = 'codex';
+  public readonly label = 'Codex';
+  public readonly loginHint = 'Use authswitch codex login to sign in and save another account.';
+  public readonly loginProviders: IHarnessLoginProvider[] = [{ providerId: 'openai', label: 'OpenAI', flows: ['device'] }];
+  public readonly diagnosticsLabel = 'Check credential storage and remote control';
+
+  constructor(
+    private readonly switcher = new CodexSwitcher(),
+    private readonly accountStatus: Pick<CodexAccountStatus, 'read'> = new CodexAccountStatus(),
+    private readonly preuse: Pick<CodexPreuse, 'run'> = new CodexPreuse(),
+  ) {}
+
+  public beginLogin(options: IHarnessLoginOptions = { providerId: 'openai', flow: 'device' }) {
+    return beginSavedOpenAiLogin(result => {
+      const credential = result.credential;
+      const raw = JSON.stringify({ auth_mode: 'chatgpt', OPENAI_API_KEY: null, tokens: {
+        access_token: credential.accessToken, refresh_token: credential.refreshToken,
+        id_token: credential.idToken, account_id: result.account.accountId,
+      }, last_refresh: new Date().toISOString() }, null, 2) + '\n';
+      const identity = this.switcher.auth.identityFromRaw(raw);
+      if (!identity) throw new Error('The new login has no Codex account identity.');
+      const previous = this.switcher.stashes.readMeta(identity.email);
+      this.switcher.stashes.write(identity, raw, previous?.enrollments ?? [], this.switcher.home.dir);
+      if (!this.switcher.stashes.readBack(identity.email, raw)) throw new Error('The new Codex login could not be verified.');
+      return { outcome: { lines: [`Saved ${plainText(identity.email)}. Select it to switch Codex.`], problems: [] }, account: { id: identity.email, label: identity.email } };
+    }, options);
+  }
+
+  public readState(): IHarnessState {
+    const active = this.switcher.readActive();
+    const accounts: IHarnessAccount[] = this.switcher.list().map((entryArg) => {
+      const raw = this.switcher.stashes.readAuth(entryArg.email);
+      const identity = raw === null ? null : this.switcher.auth.identityFromRaw(raw);
+      const valid = identity !== null && identity.email === entryArg.email && identity.accountId === entryArg.accountId && identity.kind === entryArg.kind;
+      const isActive = active.identity !== null && active.identity.email === entryArg.email && active.identity.accountId === entryArg.accountId && active.identity.kind === entryArg.kind;
+      const isStashed = valid && (!isActive || raw === active.raw);
+      return {
+        id: entryArg.email,
+        label: entryArg.email,
+        isActive,
+        isStashed,
+        savedAt: entryArg.stashedAt,
+        details: [this.formatRemoteControl(entryArg).trim(), ...(!valid ? ['saved credential missing or does not match its metadata'] : !isStashed ? ['the current login has changed since it was saved'] : [])],
+      };
+    });
+    if (active.identity && !accounts.some((accountArg) => accountArg.isActive)) {
+      accounts.unshift({ id: this.activeAccountId(active.identity.email, active.identity.accountId), label: active.identity.email, isActive: true,
+        isStashed: false, savedAt: null, details: [] });
+    }
+    return {
+      accounts,
+      saveUnavailableReason: active.source === 'keyring'
+        ? 'This login is stored in an OS keyring and cannot be saved by authswitch.'
+        : !active.identity ? 'No identifiable login to save. ' + this.loginHint
+        : accounts.some((accountArg) => accountArg.label === active.identity!.email && !accountArg.isActive)
+          ? 'A different Codex account with this email is already saved. The email-based Codex store cannot keep both; refusing to replace it.' : null,
+    };
+  }
+
+  public async readAccountStatus(accountIdArg: string): Promise<IHarnessAccountStatus> {
+    const credential = this.readAccountCredential(accountIdArg);
+    if (!credential) return { facts: [], problems: ['No matching credential is available for status lookup.'] };
+    return this.accountStatus.read(credential.raw, credential.identity);
+  }
+
+  public async preuseAccount(accountIdArg: string, optionsArg: IHarnessPreuseOptions): Promise<IHarnessPreuseResult> {
+    const credential = this.readAccountCredential(accountIdArg);
+    if (!credential) throw new PreuseError('No matching credential is available for preuse.');
+    return this.preuse.run(credential.raw, credential.identity, optionsArg);
+  }
+
+  private readAccountCredential(accountIdArg: string) {
+    const active = this.switcher.readActive();
+    const meta = this.switcher.stashes.list().find((entryArg) => entryArg.email === accountIdArg);
+    // The active credential may have been refreshed since its last stash.
+    const useActive = active.identity && (this.activeAccountId(active.identity.email, active.identity.accountId) === accountIdArg ||
+      (meta && active.identity.email === meta.email && active.identity.accountId === meta.accountId && active.identity.kind === meta.kind));
+    const raw = useActive ? active.raw : meta ? this.switcher.stashes.readAuth(meta.email) : null;
+    const identity = raw === null ? null : this.switcher.auth.identityFromRaw(raw);
+    if (!identity || (!useActive && (!meta || identity.email !== meta.email || identity.accountId !== meta.accountId || identity.kind !== meta.kind))) {
+      return null;
+    }
+    return { raw: raw!, identity };
+  }
+
+  private activeAccountId(emailArg: string, accountIdArg: string | null): string {
+    return JSON.stringify(['active', emailArg, accountIdArg]);
+  }
+
+  public resolveAccount(referenceArg: string): { id: string } | { candidates: string[] } {
+    const result = this.switcher.stashes.resolve(referenceArg);
+    return 'email' in result ? { id: result.email } : result;
+  }
+
+  public switchAccount(accountIdArg: string): IHarnessOutcome {
+    const result = this.switcher.use(accountIdArg);
+    return {
+      lines: [`switched ${result.from ? result.from + ' -> ' : ''}${result.to}`,
+        ...result.notes.map((noteArg) => '  ' + noteArg)],
+      problems: result.problems,
+    };
+  }
+
+  public removeAccount(accountIdArg: string): IHarnessOutcome {
+    const removed = this.switcher.drop(accountIdArg);
+    return { lines: [removed ? 'dropped ' + accountIdArg : 'nothing to drop'],
+      problems: removed ? [] : ['The saved account no longer exists.'] };
+  }
+
+  public saveCurrent(optionsArg: { keepActive: boolean }): IHarnessOutcome {
+    const { keepActive } = optionsArg;
+    const lines: string[] = [];
+    const result = this.switcher.stash({ keepActive });
+    const entry = result.entry;
+    const paired = countPaired(entry.enrollments);
+    const enrollmentNote =
+      paired > 0
+        ? `with ${paired} remote-control pairing(s)`
+        : entry.enrollments.length > 0
+          ? `with ${entry.enrollments.length} registered enrollment(s) but no pairing - run \`codex remote-control pair\` to make this account reachable`
+          : 'no remote-control enrollment found for this account';
+    lines.push(`stashed ${entry.email} ${enrollmentNote}\n`);
+    lines.push(
+      keepActive
+        ? `the credential is still active\n`
+        : `the active credential slot is now empty - run \`codex login\` for another account\n`,
+    );
+    return { lines, problems: result.problems };
+  }
+
+  private formatRemoteControl(listingArg: IStashListing): string {
+    if (listingArg.enrollmentsPaired > 0) {
+      const unpaired = listingArg.enrollmentsTotal - listingArg.enrollmentsPaired;
+      const extra = unpaired > 0 ? ` +${unpaired} unpaired` : '';
+      return ` remote-control:${listingArg.enrollmentsPaired}${extra}`;
+    }
+    if (listingArg.enrollmentsTotal > 0) {
+      return ` remote-control:not paired (${listingArg.enrollmentsTotal} registered)`;
+    }
+    return ' remote-control:none';
+  }
+
+  public diagnose(): IHarnessOutcome {
+    const active = this.switcher.readActive();
+    const lines: string[] = [];
+
+    lines.push(`codex home        ${this.switcher.home.dir}`);
+    lines.push(`state database    ${this.switcher.home.statePath ?? 'not found'}`);
+    lines.push(`stash directory   ${this.switcher.stashes.rootDir}`);
+
+    const incomplete = this.switcher.stashes.incomplete();
+    if (incomplete.length > 0) {
+      lines.push(
+        `incomplete stashes ${incomplete.join(', ')} - a credential without metadata; remove the directory or re-stash the account`,
+      );
+    }
+
+    const sourceLabel =
+      active.source === 'file'
+        ? 'file'
+        : active.source === 'keyring'
+          ? 'keyring (not switchable)'
+          : 'none';
+    lines.push(`credential store  ${sourceLabel}`);
+    lines.push(`active account    ${active.identity ? active.identity.email : 'none'}`);
+
+    const remoteAvailable = this.switcher.remoteControl.isAvailable();
+    lines.push(`enrollment table  ${remoteAvailable ? 'present' : 'missing'}`);
+    if (remoteAvailable) {
+      const all = this.switcher.remoteControl.read();
+      const paired = countPaired(all);
+      lines.push(
+        `enrollments       ${all.length} (${paired} paired)`,
+      );
+      const activeAccountId = active.identity?.accountId ?? null;
+      for (const enrollmentArg of all) {
+        const state = enrollmentState(enrollmentArg);
+        const label =
+          state === 'paired'
+            ? 'paired'
+            : state === 'disabled'
+              ? 'disabled'
+              : 'not paired';
+        const whose =
+          activeAccountId !== null && enrollmentArg.accountId === activeAccountId
+            ? ' this account'
+            : ' another account';
+        lines.push(
+          `  - ${enrollmentArg.serverName || '(unnamed)'} ${label}${whose} ${enrollmentArg.websocketUrl}`,
+        );
+      }
+      if (paired === 0 && all.length > 0) {
+        lines.push(
+          `  note a registered enrollment is not a pairing - run \`codex remote-control pair\` to pair this machine`,
+        );
+      }
+    }
+
+    lines.push(
+      `remote control    ${this.switcher.daemon.isRemoteControlEnabled() ? 'enabled for future starts' : 'disabled'}`,
+    );
+
+    const daemonStatus = this.switcher.daemon.status();
+    if (daemonStatus === null) {
+      const pid = this.switcher.daemon.daemonPid();
+      lines.push(
+        `app-server        codex CLI unreachable${pid === null ? '' : ` (pid file says ${pid})`}`,
+      );
+    } else if (daemonStatus.running) {
+      const pid = this.switcher.daemon.daemonPid();
+      lines.push(
+        `app-server        running v${daemonStatus.appServerVersion ?? '?'}${pid === null ? '' : ` pid ${pid}`}`,
+      );
+    } else {
+      lines.push(`app-server        not running`);
+    }
+
+    return { lines, problems: [] };
+  }
+}

package/ts/classes.codexhome.ts

@@ -0,0 +1,68 @@
+import * as plugins from './plugins.js';
+
+/**
+ * Resolves the Codex home directory and every path inside it that authswitch touches.
+ *
+ * Codex honours the CODEX_HOME environment variable and falls back to ~/.codex.
+ * Every path is derived here so a test can point the whole tool at a fixture directory.
+ */
+export class CodexHome {
+  public readonly dir: string;
+
+  constructor(dirArg?: string) {
+    this.dir = dirArg ?? process.env.CODEX_HOME ?? plugins.path.join(plugins.os.homedir(), '.codex');
+  }
+
+  /** The file credential store. Present when Codex uses file storage rather than an OS keyring. */
+  public get authFilePath(): string {
+    return plugins.path.join(this.dir, 'auth.json');
+  }
+
+  /** Directory holding the age-encrypted credential store used when a keyring backs the key. */
+  public get secretsDir(): string {
+    return plugins.path.join(this.dir, 'secrets');
+  }
+
+  public get configPath(): string {
+    return plugins.path.join(this.dir, 'config.toml');
+  }
+
+  public get appServerDaemonDir(): string {
+    return plugins.path.join(this.dir, 'app-server-daemon');
+  }
+
+  public get appServerSettingsPath(): string {
+    return plugins.path.join(this.appServerDaemonDir, 'settings.json');
+  }
+
+  public get appServerPidPath(): string {
+    return plugins.path.join(this.appServerDaemonDir, 'app-server.pid');
+  }
+
+  /**
+   * Codex versions its state database by schema generation (state_5.sqlite today).
+   * Resolve the highest-numbered one that exists rather than hardcoding a number
+   * that a Codex upgrade would silently invalidate.
+   */
+  public get statePath(): string | null {
+    let entries: string[];
+    try {
+      entries = plugins.fs.readdirSync(this.dir);
+    } catch {
+      return null;
+    }
+    const candidates = entries
+      .map((entryArg) => /^state_(\d+)\.sqlite$/.exec(entryArg))
+      .filter((matchArg): matchArg is RegExpExecArray => matchArg !== null)
+      .map((matchArg) => ({ name: matchArg[0], generation: Number(matchArg[1]) }))
+      .sort((leftArg, rightArg) => rightArg.generation - leftArg.generation);
+    if (candidates.length === 0) {
+      return null;
+    }
+    return plugins.path.join(this.dir, candidates[0].name);
+  }
+
+  public exists(): boolean {
+    return plugins.fs.existsSync(this.dir);
+  }
+}