@alfe.ai/claude-code-host 0.1.13 → 0.1.15

package/dist/index.d.cts

@@ -48,12 +48,18 @@ declare class AgentApiTransport {
    * @param extra.retry Whether to retry once on transient failures. Safe reads
    *   (GET/HEAD/OPTIONS) default to true; mutations default to false. Set true
    *   only when the endpoint's server-side contract is explicitly idempotent.
+   * @param extra.retryStatuses Narrow the HTTP statuses that trigger the retry
+   *   (default 500/502/503/504). Network errors and timeouts are always retried
+   *   when `retry` is on. Pass a subset when a status in the default set is a
+   *   deterministic answer for this endpoint (e.g. a 502 that means "upstream
+   *   denied", which a retry cannot change).
    * @param extra.signal Optional caller cancellation combined with the client's
    *   own timeout budget. Aborting either signal cancels the request.
    */
   request<T>(path: string, options?: RequestInit, extra?: {
     timeoutMs?: number;
     retry?: boolean;
+    retryStatuses?: ReadonlySet<number>;
     signal?: AbortSignal;
   }): Promise<T>;
 }
@@ -82,7 +88,37 @@ interface ConnectProviderAccounts {
   provider: string;
   accounts: ConnectProviderAccount[];
 }
+/**
+ * One AWS CLI profile an agent may use (`GET /agent/connect/aws/accounts`).
+ * `roleArn` is null for a connection's Direct identity. Carries no secret
+ * material; sessions are minted per call via `getAwsSession`.
+ */
+interface AwsProfile {
+  profile: string;
+  roleArn: string | null;
+  accountId: string;
+  region: string;
+  label: string | null;
+  connectionId: string;
+  accountIdentifier: string;
+  displayName: string | null;
+  connectedAt: string;
+}
+/** AWS CLI `credential_process` output (Version 1), as minted by Connect. */
+interface AwsSessionCredentials {
+  Version: 1;
+  AccessKeyId: string;
+  SecretAccessKey: string;
+  SessionToken: string;
+  /** ISO 8601 expiry. */
+  Expiration: string;
+}
 declare class ConnectCredentialsApi extends ApiBase {
+  /** Platform application identity for private, local Telegram login. Never expose this to tools. */
+  telegramGetApplication(): Promise<{
+    apiId: number;
+    apiHash: string;
+  }>;
   /**
    * Discover all active Connections visible to this agent for one provider.
    * Preserve the provider-specific credential projection without guessing a
@@ -476,7 +512,9 @@ declare class ConnectCredentialsApi extends ApiBase {
    * endpoint walks the agent's full visible scope chain to find a matching
    * connection (works for inherited team/project Microsoft connections).
    */
-  refreshMicrosoftAccountToken(accountIdentifier: string): Promise<{
+  refreshMicrosoftAccountToken(accountIdentifier: string, options?: {
+    connectionId?: string;
+  }): Promise<{
     accessToken: string;
     accessTokenExpiresAt: string;
     expiresAt: string;
@@ -691,12 +729,33 @@ declare class ConnectCredentialsApi extends ApiBase {
    * the fresh `accessJwt`) — callers typically ignore it and re-fetch via
    * `getSocialAccounts` for a consistent shape.
    */
-  refreshSocialAccount(provider: string, accountIdentifier: string): Promise<{
+  refreshSocialAccount(provider: string, accountIdentifier: string, options?: {
+    connectionId?: string;
+  }): Promise<{
     accountIdentifier: string;
     accessToken: string;
     accessTokenExpiresAt: string;
     expiresAt: string;
   }>;
+  /**
+   * List the AWS CLI profiles visible to this agent across every in-scope AWS
+   * connection. Each entry names the `connectionId` + `profile` pair that
+   * {@link getAwsSession} mints a session for. Fields are selected explicitly;
+   * the wire row is never spread.
+   */
+  getAwsProfiles(): Promise<AwsProfile[]>;
+  /**
+   * Mint short-lived AWS session credentials for one profile of one AWS
+   * connection, in the AWS CLI `credential_process` (Version 1) shape. The
+   * server re-checks scope + active status on every call (403 otherwise; 404
+   * for an unknown profile; 403 `aws_access_denied` when AWS denies the
+   * assume, 502 on older servers). Minting has no persistent side effect, so
+   * one retry is safe, but only on genuinely transient failures (500/503/504
+   * and network errors): a denial is deterministic and a retry just doubles
+   * the latency of every failing `aws` call. The response is secret material:
+   * never log it.
+   */
+  getAwsSession(connectionId: string, profile: string): Promise<AwsSessionCredentials>;
 }
 //# sourceMappingURL=connect-credentials.d.ts.map
 //#endregion
@@ -790,6 +849,33 @@ interface AgentWorkspaceInfo {
   teamIds?: string[];
   projectIds?: string[];
 }
+/**
+ * The agent's own Claude credential (claude-code runtime), from
+ * GET /agent/claude-credential. `oauth_token` is a Claude subscription token
+ * (`claude setup-token`) for `CLAUDE_CODE_OAUTH_TOKEN`; `api_key` is an
+ * Anthropic API key for `ANTHROPIC_API_KEY`. `revision` changes on every
+ * dashboard write. Hold the value in memory only — never log or persist it.
+ */
+interface AgentClaudeCredential {
+  kind: "oauth_token" | "api_key";
+  value: string;
+  revision: string;
+  updatedAt: string;
+}
+/** Claude auth health a claude-code host reports for its agent. */
+type ClaudeCredentialHealth = "ok" | "missing" | "invalid";
+/** Body of PUT /agent/claude-credential/status. */
+interface ClaudeCredentialStatusReport {
+  status: ClaudeCredentialHealth;
+  /** Short (≤200 chars), fixed host-side explanation. Never `claude` output or a secret. */
+  detail?: string;
+  /**
+   * The credential revision the host checked (from `getClaudeCredential()`);
+   * omit when it found none. The server drops reports for a superseded
+   * revision and answers `{ accepted: false }`.
+   */
+  revision?: string;
+}
 declare class WorkspaceApi extends ApiBase {
   /**
    * GET /agent/workspace — workspace config for the authenticated agent
@@ -806,6 +892,22 @@ declare class WorkspaceApi extends ApiBase {
   }): Promise<{
     files: Record<string, string>;
   }>;
+  /**
+   * GET /agent/claude-credential — the authenticated claude-code agent's own
+   * Claude credential, or `null` when none is stored (a self-hosted host then
+   * falls back to the local `claude` login). Fetch on every runtime start: the
+   * daemon restarts the host whenever the credential changes.
+   */
+  getClaudeCredential(): Promise<AgentClaudeCredential | null>;
+  /**
+   * PUT /agent/claude-credential/status — report whether this claude-code agent
+   * can authenticate to Claude. `accepted: false` means the report described a
+   * credential that has since been replaced; nothing was written. Not retried
+   * automatically (a mutation): the host re-reports on its next signal.
+   */
+  reportClaudeCredentialStatus(report: ClaudeCredentialStatusReport): Promise<{
+    accepted: boolean;
+  }>;
 }
 //# sourceMappingURL=workspace.d.ts.map
 //#endregion
@@ -1392,17 +1494,34 @@ declare class IdentityApi extends ApiBase {
     platformId: string;
     kind?: "user" | "agent" | "service" | "bot" | "workspace";
     displayName?: string;
+    /**
+     * Provider `email` only: the sender address, matched read-only against an
+     * existing identity's verified email contact. Ignored for other providers.
+     */
+    email?: string;
+    /**
+     * Provider `email` only: `true` when this agent verified the sender
+     * (SPF/DKIM/DMARC). Unverified email senders are never matched to an
+     * identity. Ignored for other providers.
+     */
+    emailVerified?: boolean;
   }): Promise<{
     identityId: string | null;
     status: string;
     created?: boolean;
     reason?: string;
     /**
-     * Flattened auriclabs permission strings for the resolved identity
-     * (scope-prefixed where applicable). Empty array on miss / org service
-     * outage — the runtime gate fails closed in that case.
+     * Flattened auriclabs permission strings that apply at the calling
+     * agent's own scope (`agent:<agentId>`, plus unscoped entries). A sender
+     * with no identity still receives the tenant's `principalKind="all"`
+     * grants. Empty when nothing applies, or when `permissionsUnavailable`.
      */
     permissions: string[];
+    /**
+     * `true` when the org service could not resolve permissions. The empty
+     * `permissions` is then an outage, not a denial: retry rather than deny.
+     */
+    permissionsUnavailable?: boolean;
   }>;
   searchIdentities(args?: {
     q?: string;
@@ -1632,6 +1751,48 @@ declare class WebhooksApi extends ApiBase {
 }
 //# sourceMappingURL=webhooks.d.ts.map
 //#endregion
+//#region src/domains/wallet.d.ts
+interface AgentWalletAccount {
+  connectionId: string;
+  chainType: "ethereum" | "solana";
+  address: string;
+}
+type AgentWalletTransferStatus = "pending_approval" | "processing" | "succeeded" | "rejected" | "failed";
+interface AgentWalletTransfer {
+  requestId: string;
+  agentId: string;
+  connectionId: string;
+  chainType: "ethereum" | "solana";
+  network: string;
+  fromAddress: string;
+  toAddress: string;
+  amount: string;
+  reason?: string;
+  status: AgentWalletTransferStatus;
+  providerStatus?: string;
+  providerActionId?: string;
+  failureReason?: string;
+  billingStatus: "unmetered" | "metered" | "failed";
+  createdAt: string;
+  updatedAt: string;
+  decidedAt?: string;
+}
+declare class WalletApi extends ApiBase {
+  listWalletAccounts(): Promise<AgentWalletAccount[]>;
+  /** Create a proposal only; a human approves it in the Alfe dashboard. */
+  requestWalletTransfer(input: {
+    connectionId: string;
+    chainType: "ethereum" | "solana";
+    network: "ethereum" | "base" | "arbitrum" | "optimism" | "solana";
+    fromAddress: string;
+    toAddress: string;
+    amount: string;
+    reason?: string;
+  }): Promise<AgentWalletTransfer>;
+  getWalletTransfer(requestId: string): Promise<AgentWalletTransfer>;
+}
+//# sourceMappingURL=wallet.d.ts.map
+//#endregion
 //#region src/domains/chat.d.ts
 declare class ChatApi extends ApiBase {
   ensureDirectConversation(identityId: string): Promise<{
@@ -2003,7 +2164,7 @@ declare class TeamsApi extends ApiBase {
 
 //#endregion
 //#region src/index.d.ts
-interface AgentApiClient extends SyncApi, IntegrationsApi, WorkspaceApi, ConnectCredentialsApi, TeamsApi, ChatApi, SecretsApi, IdentityApi, MemoryApi, SearchApi, KnowledgeApi, DatabaseApi, MobileApi, RemoteApi, SelfApi, VoiceApi, ImagesApi, WebhooksApi {}
+interface AgentApiClient extends SyncApi, IntegrationsApi, WorkspaceApi, ConnectCredentialsApi, TeamsApi, ChatApi, SecretsApi, IdentityApi, MemoryApi, SearchApi, KnowledgeApi, DatabaseApi, MobileApi, RemoteApi, SelfApi, VoiceApi, ImagesApi, WebhooksApi, WalletApi {}
 declare class AgentApiClient extends ApiBase {
   constructor(config: AgentApiClientConfig);
 }
@@ -2106,6 +2267,64 @@ declare class ChatServiceClient {
  * Resolution priority: explicit overrides → config file → env vars.
  */
 //#endregion
+//#region src/child-env.d.ts
+/**
+ * Child-process environment construction for spawned `claude` CLI processes.
+ *
+ * THREE non-negotiable invariants:
+ *
+ * 1. **Scrub inherited Claude auth.** `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
+ *    / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` are removed from BOTH
+ *    the parent env and any caller `extra`. A self-hosted Mac very often has
+ *    these set for other tooling; if one reaches `claude` it silently switches
+ *    accounts or billing plane (or routes through a proxy). The break is
+ *    silent: the turn "works" but bills the wrong account.
+ *
+ * 2. **Inject the agent's own credential, last.** When the agents service holds
+ *    a Claude credential for this agent, it is set AFTER the scrub as exactly
+ *    one variable: `CLAUDE_CODE_OAUTH_TOKEN` (subscription token from
+ *    `claude setup-token`) or `ANTHROPIC_API_KEY` (Anthropic API key). Nothing
+ *    else can override it. With no credential, no auth variable is set and
+ *    `claude` uses the machine's own login (self-hosted fallback). The value
+ *    lives only in the host's memory and this env — never on disk, never logged.
+ *
+ * 3. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
+ *    (`alfe claude hook ...` in `packages/cli/src/commands/claude.ts`) check
+ *    `process.env.ALFE_CLAUDE_BRIDGE` FIRST and no-op when set, so the host —
+ *    not the interactive-session hooks — owns memory recall/capture for bridged
+ *    turns. Omitting this double-captures every message. The env var NAME is a
+ *    cross-phase contract; do not rename without updating the CLI.
+ */
+/** Claude auth env vars that MUST NOT be inherited by a `claude` child. */
+declare const SCRUBBED_ANTHROPIC_ENV_VARS: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"];
+/**
+ * Provider-selection and endpoint overrides that would route `claude` away from
+ * the Anthropic API. Dropped whenever an agent credential is injected, so an
+ * inherited `CLAUDE_CODE_USE_BEDROCK=1` (say) can't send the turn to Bedrock
+ * and ignore the stored credential. Without a credential they are left alone:
+ * the machine's own `claude` setup is the fallback, whatever provider it uses.
+ */
+
+/** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
+declare const BRIDGE_ENV_VAR = "ALFE_CLAUDE_BRIDGE";
+/** The agent's Claude credential, as fetched from `GET /agent/claude-credential`. */
+interface ChildCredential {
+  kind: 'oauth_token' | 'api_key';
+  value: string;
+}
+/** The single env var each credential kind is exported as. */
+declare const CREDENTIAL_ENV_VAR: Record<ChildCredential['kind'], string>;
+/**
+ * Build the env handed to a spawned `claude` child. Pure — takes the base env
+ * explicitly so it unit-tests without touching `process.env`.
+ *
+ * Order: merge `base` + `extra` → drop every scrubbed var (plus provider
+ * overrides when a credential is injected) → set the bridge
+ * marker → set the agent credential (if any). Neither `base` nor `extra` can
+ * smuggle an auth variable in or override the injected credential.
+ */
+declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>, credential?: ChildCredential | null): NodeJS.ProcessEnv;
+//#endregion
 //#region src/stream-mapper.d.ts
 /**
  * Claude Code `--output-format stream-json` → Alfe chat-activity mapper.
@@ -2196,6 +2415,12 @@ interface EndEmission {
   durationMs?: number;
   /** Error reason (present when `isError`). Goes under `payload.message` (C3). */
   errorMessage?: string;
+  /**
+   * True when Claude refused the credential (assistant `error:
+   * "authentication_failed"`, a 401/403 `api_error_status`, or a known auth
+   * message). Present only on error turns.
+   */
+  authFailed?: true;
 }
 type MapperEmission = ActivityEmission | TextEmission | EndEmission;
 interface PendingTool {
@@ -2215,6 +2440,8 @@ interface MapperState {
   pendingTools: Map<string, PendingTool>;
   /** Whether the terminal `result` event has been seen. */
   ended: boolean;
+  /** Set by an assistant `error: "authentication_failed"` frame. */
+  authFailed: boolean;
 }
 declare function createMapperState(): MapperState;
 /**
@@ -2264,6 +2491,26 @@ declare const WARM_STREAMING_SUPPORTED = false;
  * shell. Callers that want a wider set pass `allowedTools` explicitly.
  */
 declare const DEFAULT_ALLOWED_TOOLS: readonly ["Read", "Grep", "Glob", "LS", "Edit", "Write", "WebFetch", "WebSearch", "Task", "TodoWrite"];
+/**
+ * Managed VMs (`ALFE_MANAGED=1|true`) add `Bash` to the allow-list. The VM is
+ * the agent's own machine (no user data beside the agent's workspace), and
+ * shell access is what makes a managed coding agent useful. Still
+ * `--permission-mode dontAsk` (never bypass), and the managed VM runs as root:
+ * claude refuses only `--dangerously-skip-permissions` under root, not
+ * `dontAsk`. `Edit`/`Write` are already in the default set; `MultiEdit` is not
+ * a tool in the pinned claude (2.1.x), so it is not listed.
+ */
+declare const MANAGED_ALLOWED_TOOLS: readonly ["Read", "Grep", "Glob", "LS", "Edit", "Write", "WebFetch", "WebSearch", "Task", "TodoWrite", "Bash"];
+/**
+ * Deny rules layered on the managed allow-list (`--disallowedTools`, which
+ * wins over `--allowedTools`). They keep the agent from re-running Google
+ * Workspace CLI auth and from reading its token directory with the Read tool.
+ * They are NOT a security boundary: with Bash allowed, `cat`, `cp`, `env` and
+ * friends can still read anything the root user can. Verified on claude
+ * 2.1.284: a `Bash(<prefix>:*)` rule denies the matching command under
+ * `dontAsk` while other Bash commands run.
+ */
+declare const MANAGED_DISALLOWED_TOOLS: readonly ["Bash(gws auth)", "Bash(gws auth:*)", "Read(~/.config/gws-*/**)"];
 declare const CLAUDE_PERMISSION_MODES: readonly ["acceptEdits", "auto", "manual", "dontAsk", "plan"];
 type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODES)[number];
 /**
@@ -2286,6 +2533,8 @@ interface DriverTurnResult {
   errorMessage?: string;
   /** True if the turn was aborted via `abort()` (SIGINT). */
   aborted: boolean;
+  /** Present (true) when the turn failed because Claude refused the credential. */
+  authFailed?: true;
 }
 interface RunTurnParams {
   /** The user prompt for this turn. */
@@ -2331,12 +2580,21 @@ declare class SessionDriver {
   private abortCurrent;
   private readonly bin;
   private readonly baseEnv;
+  private readonly credential;
+  private readonly managed;
   private readonly log;
   /** Injected spawn — tests replace this with a fake child. */
   private readonly spawnImpl;
   constructor(opts?: {
     claudeBin?: string;
     baseEnv?: NodeJS.ProcessEnv;
+    /**
+     * The agent's Claude credential, injected into the child env after the
+     * scrub. Null/absent → the machine's own `claude` login.
+     */
+    credential?: ChildCredential | null;
+    /** Managed VM: Bash allowed + deny rules (see MANAGED_ALLOWED_TOOLS). */
+    managed?: boolean;
     logger?: Logger;
     /** Test seam: inject a fake `spawn`. */
     __spawn?: typeof spawn;
@@ -2357,6 +2615,89 @@ declare class SessionDriver {
   private runPerTurn;
 }
 //#endregion
+//#region src/credential.d.ts
+interface HostCredential extends ChildCredential {
+  /** Non-secret revision; travels with status reports as the fence. */
+  revision: string;
+}
+interface LoadCredentialOptions {
+  /** Aborted on host stop; the loop then resolves `null`. */
+  signal: AbortSignal;
+  log: Logger;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  /** Jitter source in [0,1]; the delay is `cap * (0.5 + random/2)`. */
+  random?: () => number;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Fetch until it answers. `{ credential: null }` = nothing stored (a real
+ * answer); `null` = aborted before any answer.
+ */
+declare function loadCredentialWithRetry(fetchCredential: () => Promise<HostCredential | null>, opts: LoadCredentialOptions): Promise<{
+  credential: HostCredential | null;
+} | null>;
+declare function isAuthFailureText(text: string): boolean;
+/** HTTP statuses on a `result` event that mean "credential refused". */
+
+type ProbeOutcome = {
+  result: 'ok';
+} | {
+  result: 'invalid';
+} | {
+  result: 'unknown';
+  reason: string;
+};
+declare const AUTH_PROBE_TIMEOUT_MS = 60000;
+/** argv for the probe. No tools, no session file, no MCP, no settings files. */
+declare function buildProbeArgs(): string[];
+declare function parseProbeOutput(stdout: string, stderr: string, exitCode: number | null): ProbeOutcome;
+interface AuthProbeOptions {
+  credential: ChildCredential | null;
+  baseEnv: NodeJS.ProcessEnv;
+  /** Any existing directory; the probe reads and writes nothing there. */
+  cwd: string;
+  claudeBin?: string;
+  timeoutMs?: number;
+  spawnImpl?: typeof spawn;
+  /** Host stop: the child is SIGKILLed and the probe settles `unknown`. */
+  signal?: AbortSignal;
+}
+/**
+ * One minimal real turn against Anthropic with the agent's credential (or,
+ * when none is stored, the machine's own login). Never throws.
+ */
+declare function runAuthProbe(opts: AuthProbeOptions): Promise<ProbeOutcome>;
+interface CredentialStatusReport {
+  status: 'ok' | 'missing' | 'invalid';
+  /** Fixed, host-authored text only. Never `claude` output. */
+  detail?: string;
+  revision?: string;
+}
+/** An unchanged status is re-sent at most this often (a liveness signal). */
+declare const STATUS_REPORT_INTERVAL_MS: number;
+/**
+ * Sends health reports on change, or when the same report is older than
+ * {@link STATUS_REPORT_INTERVAL_MS}. Sends are serialized; a failed send is
+ * not remembered, so the next signal retries. Never throws.
+ */
+declare class CredentialStatusReporter {
+  private readonly send;
+  private lastKey;
+  private lastSentAt;
+  private chain;
+  private readonly now;
+  private readonly log;
+  constructor(send: (report: CredentialStatusReport) => Promise<{
+    accepted: boolean;
+  }>, opts: {
+    log: Logger;
+    now?: () => number;
+  });
+  report(report: CredentialStatusReport): Promise<void>;
+  private deliver;
+}
+//#endregion
 //#region src/host.d.ts
 interface ClaudeCodeHostConfig {
   /** Chat service WS URL (e.g. wss://chat.dev.alfe.ai/ws). */
@@ -2378,8 +2719,20 @@ interface ClaudeCodeHostConfig {
    * NEVER provider-qualified (`anthropic/…`) — that's an OpenClaw-only shape.
    */
   model?: string;
+  /**
+   * Managed VM (`ALFE_MANAGED=1|true`, set by the daemon). Enables Bash, and a
+   * missing Claude credential is a hard "missing" state (no local login to
+   * fall back to). Self-hosted when false/absent.
+   */
+  managed?: boolean;
   logger?: Logger;
 }
+declare const CREDENTIAL_INVALID_MESSAGE = "This agent's Claude credential is invalid or expired. Update it in agent settings.";
+declare const LOCAL_LOGIN_FAILED_MESSAGE = "Claude Code is not signed in on this machine. Run `claude` and log in, or add a Claude credential in agent settings.";
+declare const CREDENTIAL_MISSING_MESSAGE = "This agent has no Claude credential. Add a Claude subscription token or an Anthropic API key in agent settings.";
+declare const CREDENTIAL_UNAVAILABLE_MESSAGE = "This agent's Claude credential couldn't be loaded yet. Try again in a moment.";
+/** How long a turn waits for the start-up credential fetch before failing. */
+
 declare class ClaudeCodeHost {
   private readonly chat;
   /**
@@ -2403,14 +2756,69 @@ declare class ClaudeCodeHost {
   private claudeSessionSave;
   private stopping;
   private stopPromise;
+  /**
+   * Resolves once the first fetch has answered. Null until `start()` (the
+   * direct handleRequest test seam runs on the local login, no wait).
+   */
+  private credentialReady;
+  private resolveCredentialReady;
+  /** Turns wait for the first fetch only until this time (start + wait). */
+  private credentialDeadline;
+  private credentialLoaded;
+  /** Turns waiting for the credential, before queue admission (chat.abort). */
+  private readonly waitingTurns;
+  private readonly loaderRestartMs;
+  /** In memory only. Never logged, never persisted. */
+  private credential;
+  private readonly credentialAbort;
+  private readonly reporter;
+  private readonly probe;
+  private readonly credentialWaitMs;
+  private readonly credentialRetry;
   constructor(cfg: ClaudeCodeHostConfig, deps?: {
-    /** Per-turn driver factory (test seam). Called once per turn. */
-    makeDriver?: () => SessionDriver;
+    /**
+     * Per-turn driver factory (test seam). Called once per turn with the
+     * agent's credential (null → the machine's own `claude` login).
+     */
+    makeDriver?: (credential: ChildCredential | null) => SessionDriver;
     chat?: ChatServiceClient;
     api?: AgentApiClient;
+    /** Start-up auth check (test seam; default: a minimal `claude -p`). */
+    probe?: (credential: ChildCredential | null, signal: AbortSignal) => Promise<ProbeOutcome>;
+    credentialWaitMs?: number;
+    /** Delay before restarting a credential loader that threw (default 5 s). */
+    loaderRestartMs?: number;
+    credentialRetry?: {
+      baseDelayMs?: number;
+      maxDelayMs?: number;
+    };
   });
   /** Start the chat WS. Non-blocking — the client reconnects internally. */
   start(): Promise<void>;
+  /**
+   * Run the fetch + check, restarting it after an unexpected throw so a bug
+   * can never leave the host without a credential until the next restart.
+   */
+  private runCredentialLoader;
+  private loadCredential;
+  private childCredential;
+  /** Start-up health check: one minimal real call, reported to the cloud. */
+  private checkCredential;
+  /** Report the credential (or the local login) as working or refused. */
+  private reportAuth;
+  /**
+   * Wait for the first credential answer BEFORE queue admission, so a waiting
+   * turn holds no slot. Bounded by the start-up deadline: once it has passed,
+   * later turns stop waiting until the load completes. Cancelled by
+   * `chat.abort` or host stop through `cancellation`.
+   */
+  private awaitCredential;
+  /**
+   * Instant credential gate inside the turn (no waiting: `handleAgent` already
+   * waited). Returns a user-facing failure message, or null when the turn may
+   * run. A host driven without `start()` runs on the local login.
+   */
+  private credentialGateMessage;
   /** Stop admission, abort owned children, and give active turns time to settle. */
   stop(): Promise<void>;
   /**
@@ -2421,6 +2829,27 @@ declare class ClaudeCodeHost {
   private handleAgent;
   private deliverAgentOutcome;
   private runAgentTurn;
+  /**
+   * Send every message the memory service has not accepted yet. Indices are
+   * the messages' positions in the session file, so they advance across turns
+   * and survive host restarts; the per-conversation `ingestEpoch` tells the
+   * service when that index space restarted. Ingest under the BARE session
+   * id: the same key the session-store filename and the memory backfill use,
+   * so there is one memory lineage.
+   *
+   * Cursor rules:
+   * - success: advance through the batch. If the server trimmed the batch
+   *   (`messageCount` < sent) it kept the NEWEST messages and its watermark
+   *   moved past the dropped head, so a resend would be filtered anyway;
+   *   advance and warn. The byte bounds keep this path unreachable normally.
+   * - non-retryable 4xx (400/413/422): skip only the oldest message, so one
+   *   poison message cannot wedge the conversation.
+   * - anything else (429, 5xx, network): leave the cursor; the next turn
+   *   resends.
+   */
+  private ingestPendingMemory;
+  /** Regenerate CLAUDE.md from the workspace persona files. Never fatal. */
+  private syncPersona;
   /**
    * Run a turn; on a `--resume` failure (stale/missing claude session id) start
    * fresh and prepend the last-N stored messages so the model keeps context.
@@ -2441,45 +2870,6 @@ declare class ClaudeCodeHost {
 /** Strip the `agent:{agentId}:` prefix from a full server session key. */
 declare function stripAgentPrefix(sessionKey: string): string;
 //#endregion
-//#region src/child-env.d.ts
-/**
- * Child-process environment construction for spawned `claude` CLI processes.
- *
- * TWO non-negotiable invariants (Phase 2 plan, audit B2 + the hard
- * constraints):
- *
- * 1. **Scrub `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` /
- *    `ANTHROPIC_AUTH_TOKEN`.** A self-hosted Mac very often has these set (for
- *    other tooling). If ANY of them reaches `claude`, the CLI silently switches
- *    from the user's Claude subscription (OAuth) to API-key/proxy auth — which
- *    is exactly what this whole runtime exists to avoid (no Agent SDK, no
- *    proxy, subscription only). The break is SILENT: the turn "works" but bills
- *    the wrong plane. So we strip them unconditionally from the child env.
- *
- * 2. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
- *    (`alfe claude hook ...` in `packages/cli/src/commands/claude.ts`) check
- *    `process.env.ALFE_CLAUDE_BRIDGE` FIRST and no-op when set, so the host —
- *    not the interactive-session hooks — owns memory recall/capture for bridged
- *    turns. Omitting this double-captures every message. The env var NAME is a
- *    cross-phase contract; do not rename without updating the CLI.
- */
-/** Anthropic env vars that force API-key / proxy auth and MUST be scrubbed. */
-declare const SCRUBBED_ANTHROPIC_ENV_VARS: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
-/** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
-declare const BRIDGE_ENV_VAR = "ALFE_CLAUDE_BRIDGE";
-/**
- * Build the env handed to a spawned `claude` child. Pure — takes the base env
- * explicitly so it unit-tests without touching `process.env`.
- *
- * - Every scrubbed Anthropic var is DELETED (not blanked) so `claude`'s
- *   env-detection treats it as absent.
- * - `ALFE_CLAUDE_BRIDGE=1` is set.
- * - Any caller-supplied `extra` entries are layered last (e.g. a per-turn
- *   marker) but can NEVER re-introduce a scrubbed var — the scrub runs after
- *   the merge as the final gate.
- */
-declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>): NodeJS.ProcessEnv;
-//#endregion
 //#region src/session/session-store.d.ts
 type StoredMessageComponent = {
   type: 'link_button';
@@ -2559,7 +2949,25 @@ interface SessionData {
    * pre-persistence files.
    */
   activity?: ChatActivityRecord[];
+  /**
+   * Alfe memory ingest cursor. Message indices are POSITIONS in `messages`
+   * (append-only, never trimmed), so they are stable across host restarts and
+   * match the index space the memory backfill uses for these files.
+   * `ingestEpoch` is stamped once per conversation lineage (when this file is
+   * created) and tells the memory service the index space restarted, e.g.
+   * after the 30-day cleanup deleted the file and the conversation resumed.
+   * Absent on files written before the cursor existed.
+   */
+  memory?: SessionMemoryCursor;
+}
+interface SessionMemoryCursor {
+  /** Per-conversation-lineage epoch sent as `ingestEpoch`. */
+  ingestEpoch: number;
+  /** Highest message index the memory service has accepted (-1 = none). */
+  lastIngestedIndex: number;
 }
+/** One message as sent to `memoryIngest`. */
+
 interface SessionSummary {
   sessionId: string;
   agentId: string;
@@ -2574,7 +2982,20 @@ interface SessionSummary {
 declare function getSession(sessionId: string): Promise<SessionData | null>;
 declare function saveSession(session: SessionData): Promise<void>;
 declare function createSession(sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string): Promise<SessionData>;
-declare function addMessage(sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]): Promise<void>;
+/**
+ * Append a message. Returns its index (position in `messages`), the stable
+ * memory-ingest index, or -1 when the session does not exist.
+ */
+declare function addMessage(sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]): Promise<number>;
+/**
+ * Memory ingest bounds, in serialised UTF-8 bytes. The ingest endpoint
+ * forwards the whole body as ONE SQS message and trims the OLDEST messages
+ * past 250,000 bytes (`services/memory/api-agents/ingest/fit-batch.ts`); a
+ * trimmed head is lost for good because the consumer's watermark jumps past
+ * it. Staying well under that limit means the server never trims. Bytes, not
+ * characters: one CJK character is three UTF-8 bytes.
+ */
+
 /**
  * Append a turn's terminalized activity records. Called ONCE per turn (from the
  * dispatch `finally`) — never per-delta.
@@ -2594,4 +3015,4 @@ declare function listSessions(filters?: {
  */
 declare function resolveHostConfig(): ClaudeCodeHostConfig;
 //#endregion
-export { type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, type ChatActivityRecord, type ChatMessage, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type MapperEmission, type MapperState, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, collectTurnActivityRecords, createMapperState, createSession, getSession, listSessions, mapStreamEvent, mapStreamEvents, resolveHostConfig, saveSession, stripAgentPrefix };
+export { AUTH_PROBE_TIMEOUT_MS, type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, CREDENTIAL_ENV_VAR, CREDENTIAL_INVALID_MESSAGE, CREDENTIAL_MISSING_MESSAGE, CREDENTIAL_UNAVAILABLE_MESSAGE, type ChatActivityRecord, type ChatMessage, type ChildCredential, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, type CredentialStatusReport, CredentialStatusReporter, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type HostCredential, LOCAL_LOGIN_FAILED_MESSAGE, MANAGED_ALLOWED_TOOLS, MANAGED_DISALLOWED_TOOLS, type MapperEmission, type MapperState, type ProbeOutcome, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, STATUS_REPORT_INTERVAL_MS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, buildProbeArgs, collectTurnActivityRecords, createMapperState, createSession, getSession, isAuthFailureText, listSessions, loadCredentialWithRetry, mapStreamEvent, mapStreamEvents, parseProbeOutput, resolveHostConfig, runAuthProbe, saveSession, stripAgentPrefix };