@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/src/hosts/claude-continuation.ts

@@ -1,7 +1,12 @@
 import { isRecord } from "../value-guards";
 import { randomUUID } from "node:crypto";
-import { summarizeClaudeEvents } from "./claude-events";
+import {
+  summarizeClaudeEvents,
+  parseClaudeEvents,
+  type ClaudeEvents,
+} from "./claude-events";
 import { workspaceFingerprint } from "./workspace-fingerprint";
+import { MAX_EVENT_BYTES, MAX_STDERR_BYTES } from "./process-lifecycle";
 
 export type ClaudeProcessResult = { code: number; out: string; err: string };
 export type ClaudeSession = { option: "--session-id" | "--resume"; id: string };
@@ -11,29 +16,32 @@ type Observation = {
   data: Record<string, unknown>;
 };
 type ClaudeTurns = ClaudeProcessResult & {
+  events: ClaudeEvents;
+  initialEvents?: ClaudeEvents;
+  followUpEvents?: ClaudeEvents;
   initialOut?: string;
   followUpOut?: string;
   continuation?: Observation;
   sessionResultsBound?: boolean;
 };
 
-function boundResult(stream: string, session: string): boolean {
-  try {
-    const results = stream
-      .split("\n")
-      .filter((line) => line.trim())
-      .map((line): unknown => JSON.parse(line))
-      .filter(isRecord)
-      .filter((entry) => entry.type === "result");
-    const [result] = results;
-    return (
-      results.length === 1 &&
-      result !== undefined &&
-      result.session_id === session
-    );
-  } catch {
-    return false;
-  }
+function boundResult(stream: ClaudeEvents, session: string): boolean {
+  if (stream.lines.some((line) => !line.parsed)) return false;
+  const results = stream.lines
+    .filter((line) => line.parsed)
+    .map((line) => line.value)
+    .filter(isRecord)
+    .filter((entry) => entry.type === "result");
+  const [result] = results;
+  return (
+    results.length === 1 &&
+    result !== undefined &&
+    result.session_id === session
+  );
+}
+
+function parsedTurn(result: ClaudeProcessResult) {
+  return { ...result, events: parseClaudeEvents(result.out) };
 }
 
 /** Resume a declared follow-up in the same isolated native Claude session. */
@@ -46,15 +54,18 @@ export async function runClaudeTurns(options: {
     session?: ClaudeSession,
   ) => Promise<ClaudeProcessResult>;
 }): Promise<ClaudeTurns> {
-  if (options.followUpPrompt === undefined) return options.run(options.prompt);
+  if (options.followUpPrompt === undefined)
+    return parsedTurn(await options.run(options.prompt));
   const sessionId = randomUUID();
   const initialFingerprint = await workspaceFingerprint(options.workspace);
-  const initial = await options.run(options.prompt, {
-    option: "--session-id",
-    id: sessionId,
-  });
-  const summary = summarizeClaudeEvents(initial.out, initial.code);
-  const initialBound = boundResult(initial.out, sessionId);
+  const initial = parsedTurn(
+    await options.run(options.prompt, {
+      option: "--session-id",
+      id: sessionId,
+    }),
+  );
+  const summary = summarizeClaudeEvents(initial.events, initial.code);
+  const initialBound = boundResult(initial.events, sessionId);
   if (!summary.complete || !initialBound)
     return {
       ...initial,
@@ -62,10 +73,12 @@ export async function runClaudeTurns(options: {
       sessionResultsBound: initialBound,
     };
   const beforeFollowUp = await workspaceFingerprint(options.workspace);
-  const followUp = await options.run(options.followUpPrompt, {
-    option: "--resume",
-    id: sessionId,
-  });
+  const followUp = parsedTurn(
+    await options.run(options.followUpPrompt, {
+      option: "--resume",
+      id: sessionId,
+    }),
+  );
   return combinedTurns(
     initial,
     followUp,
@@ -76,17 +89,18 @@ export async function runClaudeTurns(options: {
 }
 
 function combinedOutput(
-  initial: ClaudeProcessResult,
-  followUp: ClaudeProcessResult,
+  initial: ReturnType<typeof parsedTurn>,
+  followUp: ReturnType<typeof parsedTurn>,
 ) {
   const out = `${initial.out.trimEnd()}\n${followUp.out.trimStart()}`;
-  const err = [initial.err.trimEnd(), followUp.err.trimStart()]
+  const stderr = [initial.err.trimEnd(), followUp.err.trimStart()]
     .filter(Boolean)
     .join("\n");
-  if (
-    Buffer.byteLength(out, "utf8") > 8 * 1024 * 1024 ||
-    Buffer.byteLength(err, "utf8") > 64 * 1024
-  )
+  const err = new TextDecoder("utf-8", { ignoreBOM: true }).decode(
+    Buffer.from(stderr, "utf8").subarray(0, MAX_STDERR_BYTES),
+    { stream: true },
+  );
+  if (Buffer.byteLength(out, "utf8") > MAX_EVENT_BYTES)
     throw new Error("Claude combined process output exceeds its limit");
   return { out, err };
 }
@@ -112,14 +126,14 @@ function continuationObservation(
 }
 
 function combinedTurns(
-  initial: ClaudeProcessResult,
-  followUp: ClaudeProcessResult,
+  initial: ReturnType<typeof parsedTurn>,
+  followUp: ReturnType<typeof parsedTurn>,
   sessionId: string,
   initialFingerprint: string | null,
   beforeFollowUp: string | null,
 ): ClaudeTurns {
-  const followUpSummary = summarizeClaudeEvents(followUp.out, followUp.code);
-  const sessionResultsBound = boundResult(followUp.out, sessionId);
+  const followUpSummary = summarizeClaudeEvents(followUp.events, followUp.code);
+  const sessionResultsBound = boundResult(followUp.events, sessionId);
   const bound = followUpSummary.complete && sessionResultsBound;
   const { out, err } = combinedOutput(initial, followUp);
   return {
@@ -128,6 +142,9 @@ function combinedTurns(
     err,
     initialOut: initial.out,
     followUpOut: followUp.out,
+    events: { lines: [...initial.events.lines, ...followUp.events.lines] },
+    initialEvents: initial.events,
+    followUpEvents: followUp.events,
     sessionResultsBound,
     continuation: continuationObservation(
       bound,

package/src/hosts/claude-credential.ts

@@ -1,45 +1,60 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { homedir } from "node:os";
-
-const MAX_CREDENTIAL_BYTES = 1024 * 1024;
-
-async function savedClaudeCredential(): Promise<string | undefined> {
-  const path = join(
-    process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"),
-    ".credentials.json",
-  );
-  try {
-    await stat(path);
-    return path;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-    throw new Error("Claude saved credential is unreadable or unavailable", {
-      cause: error,
-    });
-  }
-}
+import { nativeStateParent } from "../native-transcript-state";
+import {
+  coversLifetime,
+  parseClaudeLogin,
+  rotatedLoginBytes,
+  sameTokens,
+  tokenDigest,
+  type ClaudeLogin,
+} from "./claude-login";
+import {
+  claudeLoginRecovery,
+  type ClaudeLoginRecovery,
+} from "./claude-login-recovery";
+import { refreshClaudeLogin } from "./claude-login-refresh";
+import {
+  claudeLoginStore,
+  MAX_CREDENTIAL_BYTES,
+  requireBoundedCredential,
+  type ClaudeKeychain,
+  type ClaudeLoginStore,
+} from "./claude-login-store";
+import { withClaudeRefreshLock } from "./claude-refresh-lock";
 
 export const CLAUDE_AUTH_VARIABLES = [
   "ANTHROPIC_API_KEY",
   "CLAUDE_CODE_OAUTH_TOKEN",
 ] as const;
 
+/** Margin beyond the execution budget, matching Claude's own refresh window. */
+export const CLAUDE_LOGIN_MARGIN_MS = 5 * 60_000;
+
+/** What a saved login must provide before a trial may use it. */
+export interface ClaudeLoginRequirement {
+  /** Claude binary used for parent-owned refresh. */
+  binary: string;
+  /** Remaining access-token lifetime the complete execution needs. */
+  lifetimeMs: number;
+}
+
 /** Keep the CLI's authentication separate from the candidate tool environment. */
 export async function stageClaudeAuthentication(
   configRoot: string,
-  sourceFile?: string,
+  sourceFile: string | undefined,
+  requirement: ClaudeLoginRequirement,
 ) {
+  await mkdir(configRoot, { recursive: true, mode: 0o700 });
   const environment = authenticationEnvironment(sourceFile);
-  if (Object.keys(environment).length) {
-    await mkdir(configRoot, { recursive: true, mode: 0o700 });
-    return {
-      credentialFile: join(configRoot, ".credentials.json"),
-      environment,
-    };
-  }
+  if (!Object.keys(environment).length)
+    environment.CLAUDE_CODE_OAUTH_TOKEN = await claudeAccessToken(
+      sourceFile,
+      requirement,
+    );
   return {
-    credentialFile: await stageClaudeCredential(configRoot, sourceFile),
+    // Trials never receive a saved login; the path only anchors private state.
+    credentialFile: join(configRoot, ".credentials.json"),
     environment,
   };
 }
@@ -63,44 +78,126 @@ function authenticationEnvironment(sourceFile: string | undefined) {
   return environment;
 }
 
-/** Copy only a bounded login credential into one private host state. */
-export async function stageClaudeCredential(
-  configRoot: string,
-  sourceFile?: string,
+async function platformKeychain(): Promise<ClaudeKeychain | undefined> {
+  if (process.platform !== "darwin") return undefined;
+  const { claudeKeychain } = await import("./claude-keychain");
+  return claudeKeychain;
+}
+
+/**
+ * Provide an access token from the selected saved login. The parent alone
+ * refreshes it, so a rotating refresh token never enters disposable state.
+ */
+export async function claudeAccessToken(
+  sourceFile: string | undefined,
+  requirement: ClaudeLoginRequirement,
 ): Promise<string> {
-  sourceFile ??= await savedClaudeCredential();
-  await mkdir(configRoot, { recursive: true, mode: 0o700 });
-  let credential: Buffer;
-  try {
-    credential = await readCredential(sourceFile);
-  } catch (error) {
-    throw new Error("Claude credential is unreadable or unavailable", {
-      cause: error,
-    });
-  }
-  requireBoundedCredential(credential);
-  const target = join(configRoot, ".credentials.json");
-  await writeFile(target, credential, { flag: "wx", mode: 0o600 });
-  return target;
+  const store = await claudeLoginStore(sourceFile, await platformKeychain());
+  const recovery = await claudeLoginRecovery(
+    await nativeStateParent(),
+    store.origin,
+  );
+  const login = await storedLogin(store);
+  if (
+    coversLifetime(login, requirement.lifetimeMs) &&
+    !(await recovery.pending())
+  )
+    return login.accessToken;
+  return withClaudeRefreshLock(store.lockRoot, () =>
+    lockedAccessToken(store, recovery, requirement),
+  );
+}
+
+async function storedLogin(store: ClaudeLoginStore): Promise<ClaudeLogin> {
+  return parseClaudeLogin(requireBoundedCredential(await store.read()));
+}
+
+/** Re-read under the lock: another process may already have refreshed. */
+async function lockedAccessToken(
+  store: ClaudeLoginStore,
+  recovery: ClaudeLoginRecovery,
+  requirement: ClaudeLoginRequirement,
+): Promise<string> {
+  const current = await recoveredLogin(store, recovery);
+  if (coversLifetime(current, requirement.lifetimeMs))
+    return current.accessToken;
+  const rotated = await refreshClaudeLogin(
+    requirement.binary,
+    refreshableLogin(current),
+    recovery.workRoot,
+  );
+  await recovery.retain(current, rotated);
+  await persistRotation(store, recovery, current, rotated);
+  await recovery.discard();
+  return usableAccessToken(rotated, requirement.lifetimeMs);
+}
+
+function refreshableLogin(
+  login: ClaudeLogin,
+): ClaudeLogin & { refreshToken: string } {
+  const { refreshToken } = login;
+  if (!refreshToken || !login.scopes.length)
+    throw new Error(
+      "Claude saved login has expired and cannot be refreshed; run claude and /login",
+    );
+  return { ...login, refreshToken };
 }
 
-async function readCredential(sourceFile: string | undefined) {
-  if (!sourceFile) {
-    if (process.platform !== "darwin")
-      throw new Error("Claude keychain credential is unavailable");
-    const { keychainCredential } = await import("./claude-keychain");
-    return keychainCredential();
+function usableAccessToken(login: ClaudeLogin, lifetimeMs: number): string {
+  if (!coversLifetime(login, lifetimeMs))
+    throw new Error(
+      `Claude login lifetime cannot cover the ${String(Math.ceil(lifetimeMs / 60_000))}-minute execution budget`,
+    );
+  return login.accessToken;
+}
+
+/** Complete a rotation left pending when its store could not be updated. */
+async function recoveredLogin(
+  store: ClaudeLoginStore,
+  recovery: ClaudeLoginRecovery,
+): Promise<ClaudeLogin> {
+  const current = await storedLogin(store);
+  const pending = await recovery.pending();
+  if (!pending) return current;
+  if (pending.replaces !== tokenDigest(current.refreshToken)) {
+    // The store moved on through another login; never overwrite it.
+    await recovery.discard();
+    return current;
   }
-  if ((await stat(sourceFile)).size > MAX_CREDENTIAL_BYTES)
-    throw new Error("oversized credential");
-  return readFile(sourceFile);
+  const rotated = parseClaudeLogin(
+    rotatedLoginBytes(current, { ...current, oauth: pending.oauth }),
+  );
+  await writeVerified(store, recovery, current, rotated);
+  await recovery.discard();
+  return rotated;
 }
 
-function requireBoundedCredential(credential: Buffer): void {
-  if (
-    credential.byteLength === 0 ||
-    credential.byteLength > MAX_CREDENTIAL_BYTES ||
-    !credential.toString("utf8").trim()
-  )
-    throw new Error("Claude credential is empty or oversized");
+/** Compare-and-swap against the refresh token the rotation consumed. */
+async function persistRotation(
+  store: ClaudeLoginStore,
+  recovery: ClaudeLoginRecovery,
+  replaced: ClaudeLogin,
+  rotated: ClaudeLogin,
+): Promise<void> {
+  const latest = await storedLogin(store);
+  if (latest.refreshToken !== replaced.refreshToken) return;
+  await writeVerified(store, recovery, latest, rotated);
+}
+
+async function writeVerified(
+  store: ClaudeLoginStore,
+  recovery: ClaudeLoginRecovery,
+  latest: ClaudeLogin,
+  rotated: ClaudeLogin,
+): Promise<void> {
+  try {
+    await store.write(rotatedLoginBytes(latest, rotated));
+    if (!sameTokens(await storedLogin(store), rotated))
+      throw new Error("the stored login does not match the rotation");
+  } catch (cause) {
+    throw new Error(
+      `Claude refreshed the saved login but could not update ${store.origin}; Sevro retained the refreshed login at ${recovery.path} and restores it on the next run once the store is writable`,
+      { cause },
+    );
+  }
 }

package/src/hosts/claude-events.ts

@@ -9,6 +9,32 @@ export class ClaudeEventError extends Error {
 }
 
 type Entry = Record<string, unknown>;
+export type ClaudeEventLine =
+  { parsed: true; value: unknown } | { parsed: false; error: unknown };
+export interface ClaudeEvents {
+  lines: readonly ClaudeEventLine[];
+}
+
+/** Decode JSON once; consumers retain their own event validity rules. */
+export function parseClaudeEvents(stream: string | ClaudeEvents): ClaudeEvents {
+  if (typeof stream !== "string") return stream;
+  if (Buffer.byteLength(stream, "utf8") > MAX_EVENT_STREAM_BYTES)
+    throw new ClaudeEventError("Claude event stream exceeds 8 MiB");
+  return {
+    lines: stream
+      .split("\n")
+      .filter((line) => line.trim())
+      .map(parseLine),
+  };
+}
+
+function parseLine(line: string): ClaudeEventLine {
+  try {
+    return { parsed: true, value: JSON.parse(line) as unknown };
+  } catch (error) {
+    return { parsed: false, error };
+  }
+}
 
 function nonnegative(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
@@ -78,38 +104,28 @@ export interface ClaudeEventSummary {
   usageComplete: boolean;
 }
 
-/** Parse bounded Claude stream JSON without retaining its private event bodies. */
+/** Summarize decoded events without exposing their private bodies. */
 export function summarizeClaudeEvents(
-  stream: string,
+  stream: string | ClaudeEvents,
   exitCode: number,
 ): ClaudeEventSummary {
-  if (Buffer.byteLength(stream, "utf8") > MAX_EVENT_STREAM_BYTES)
-    throw new ClaudeEventError("Claude event stream exceeds 8 MiB");
-  const { results, malformed } = parseResultEvents(stream);
+  const { results, malformed } = parseResultEvents(parseClaudeEvents(stream));
   return resultSummary(results, malformed, exitCode);
 }
 
-function parseResultEvents(stream: string) {
+function parseResultEvents(stream: ClaudeEvents) {
   const results: Entry[] = [];
   let malformed = false;
-  for (const line of stream.split("\n")) {
-    if (!line.trim()) continue;
-    try {
-      const event = parseValidEvent(line);
-      if (event.type === "result") results.push(event);
-    } catch {
+  for (const line of stream.lines) {
+    if (!line.parsed || !validEvent(line.value)) {
       malformed = true;
+      continue;
     }
+    if (line.value.type === "result") results.push(line.value);
   }
   return { results, malformed };
 }
 
-function parseValidEvent(line: string): Entry {
-  const event: unknown = JSON.parse(line);
-  if (!validEvent(event)) throw new ClaudeEventError("Malformed Claude event");
-  return event;
-}
-
 function summarizeUsage(results: Entry[], malformed: boolean) {
   const usages = results.map((result) => usage(result.usage));
   const validUsages = usages.filter((value): value is Usage => value !== null);

package/src/hosts/claude-keychain.ts

@@ -1,22 +1,20 @@
 import { existsSync } from "node:fs";
+import {
+  MAX_CREDENTIAL_BYTES,
+  requireBoundedCredential,
+  type ClaudeKeychain,
+} from "./claude-login-store";
 
-const MAX_CREDENTIAL_BYTES = 1024 * 1024;
+const SECURITY = "/usr/bin/security";
+/** `security` reports errSecItemNotFound with this exit status. */
+const ITEM_NOT_FOUND = 44;
+/** Claude Code's bound for one `security -i` command line. */
+const INTERACTIVE_LINE_LIMIT = 4032;
+const KEYCHAIN_TIMEOUT_MS = 10_000;
 
-function keychainProcess() {
-  if (process.platform !== "darwin" || !existsSync("/usr/bin/security"))
+function requireSecurity(): void {
+  if (process.platform !== "darwin" || !existsSync(SECURITY))
     throw new Error("Claude keychain credential is unavailable");
-  const account = process.env.USER ?? process.env.LOGNAME;
-  return Bun.spawn(
-    [
-      "/usr/bin/security",
-      "find-generic-password",
-      "-s",
-      "Claude Code-credentials",
-      ...(account ? ["-a", account] : []),
-      "-w",
-    ],
-    { stdout: "pipe", stderr: "ignore" },
-  );
 }
 
 async function boundedCredentialStream(
@@ -35,21 +33,30 @@ async function boundedCredentialStream(
   return Buffer.concat(chunks);
 }
 
-export async function keychainCredential(): Promise<Buffer> {
-  const proc = keychainProcess();
+async function findItem(
+  service: string,
+  account: string,
+): Promise<Buffer | undefined> {
+  requireSecurity();
+  const proc = Bun.spawn(
+    [SECURITY, "find-generic-password", "-a", account, "-s", service, "-w"],
+    { stdout: "pipe", stderr: "ignore" },
+  );
   const timer = setTimeout(() => {
     proc.kill("SIGKILL");
-  }, 10_000);
+  }, KEYCHAIN_TIMEOUT_MS);
   const reader = proc.stdout.getReader();
   try {
     const credential = await boundedCredentialStream(reader);
-    if ((await proc.exited) !== 0)
+    const code = await proc.exited;
+    if (code === ITEM_NOT_FOUND) return undefined;
+    if (code !== 0)
       throw new Error("Claude keychain credential is unavailable");
-    return credential;
+    return requireBoundedCredential(credential);
   } catch (error) {
     proc.kill("SIGKILL");
     await proc.exited;
-    throw new Error("Claude keychain credential is unavailable", {
+    throw new Error("Claude credential is unreadable or unavailable", {
       cause: error,
     });
   } finally {
@@ -57,3 +64,53 @@ export async function keychainCredential(): Promise<Buffer> {
     reader.releaseLock();
   }
 }
+
+/** Mirror Claude Code's update so the secret stays off argv when it fits. */
+function updateCommand(service: string, account: string, bytes: Buffer) {
+  const hex = bytes.toString("hex");
+  const line = `add-generic-password -U -a "${account}" -s "${service}" -X "${hex}"\n`;
+  return line.length <= INTERACTIVE_LINE_LIMIT
+    ? { command: [SECURITY, "-i"], stdin: Buffer.from(line) }
+    : {
+        command: [
+          SECURITY,
+          "add-generic-password",
+          "-U",
+          "-a",
+          account,
+          "-s",
+          service,
+          "-X",
+          hex,
+        ],
+        stdin: undefined,
+      };
+}
+
+async function updateItem(
+  service: string,
+  account: string,
+  bytes: Buffer,
+): Promise<void> {
+  requireSecurity();
+  const { command, stdin } = updateCommand(service, account, bytes);
+  const proc = Bun.spawn(command, {
+    stdin: stdin ?? "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  const timer = setTimeout(() => {
+    proc.kill("SIGKILL");
+  }, KEYCHAIN_TIMEOUT_MS);
+  try {
+    if ((await proc.exited) !== 0)
+      throw new Error("Claude keychain login could not be updated");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export const claudeKeychain: ClaudeKeychain = {
+  read: findItem,
+  write: updateItem,
+};