@alfe.ai/claude-code-host 0.1.14 → 0.1.16

package/dist/index.d.cts

@@ -849,6 +849,43 @@ 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. `missing` is
+ * legacy: hosts since the AI-proxy fallback (2026-10-15) never send it.
+ */
+type ClaudeCredentialHealth = "ok" | "missing" | "invalid";
+/**
+ * Which auth the host's turns run on: the stored credential, the machine's
+ * own `claude` login (self-hosted only), or the Alfe AI proxy (Alfe credits).
+ */
+type ClaudeCredentialSource = "credential" | "local_login" | "ai_proxy";
+/** Body of PUT /agent/claude-credential/status. */
+interface ClaudeCredentialStatusReport {
+  status: ClaudeCredentialHealth;
+  /** The auth source the status describes. Omitted only by older hosts. */
+  source?: ClaudeCredentialSource;
+  /** 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
@@ -865,6 +902,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 (the host then falls back
+   * to the local `claude` login when self-hosted, else the Alfe AI proxy). 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
@@ -2224,6 +2277,131 @@ 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.
+ *
+ * Every turn runs on exactly ONE auth source (`ChildAuth`), resolved by the
+ * host (see DEVELOPING.md "Auth source resolution"):
+ *
+ *  - `credential`  — the agent's stored Claude credential, set as exactly one
+ *    variable: `CLAUDE_CODE_OAUTH_TOKEN` (subscription token from
+ *    `claude setup-token`) or `ANTHROPIC_API_KEY` (Anthropic API key).
+ *  - `local_login` — self-hosted only: no auth variable, so `claude` uses the
+ *    machine's own login (and whatever provider the operator configured).
+ *  - `ai_proxy`    — the Alfe AI proxy via the daemon's loopback proxy:
+ *    `ANTHROPIC_BASE_URL` = the local proxy, `ANTHROPIC_AUTH_TOKEN` = a
+ *    placeholder the local proxy replaces with the daemon's agent key, and
+ *    every model alias pinned to an Alfe registry id (the proxy routes exact
+ *    registry ids only; the CLI's built-in aliases resolve to dated ids that
+ *    are a 409 there).
+ *
+ * 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. Credential and proxy modes also drop provider
+ *    overrides (Bedrock/Vertex/Foundry); proxy mode additionally drops model
+ *    and header overrides so nothing reaches the proxy that it cannot price.
+ *
+ * 2. **Inject the source last.** Nothing in `base` or `extra` can override the
+ *    injected credential or proxy settings. A credential lives only in the
+ *    host's memory and this env, never on disk, never logged. Proxy settings
+ *    never appear in a credential or local-login env.
+ *
+ * 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 a credential or the AI proxy is in use,
+ * so an inherited `CLAUDE_CODE_USE_BEDROCK=1` (say) can't send the turn to
+ * Bedrock and ignore the chosen source. On a local login they are left alone:
+ * the machine's own `claude` setup is the source, whatever provider it uses.
+ */
+
+/** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
+declare const BRIDGE_ENV_VAR = "ALFE_CLAUDE_BRIDGE";
+/**
+ * Placeholder `ANTHROPIC_AUTH_TOKEN` (sent as `Authorization: Bearer`) for
+ * proxy mode. `@alfe.ai/ai-proxy-local` keeps an incoming `alfe_…` key and
+ * replaces anything else with the daemon's agent key (as `x-api-key`, dropping
+ * `authorization`), so the agent key itself never enters the `claude` env (a
+ * managed agent has Bash). Never `alfe_…`.
+ */
+declare const PROXY_API_KEY_PLACEHOLDER = "alfe-local-proxy";
+/**
+ * Default local AI proxy (`DEFAULT_AI_PROXY_PORT` in `@alfe.ai/ai-proxy-local`).
+ * The daemon passes the URL it actually bound as `ALFE_LOCAL_AI_PROXY_URL`;
+ * this is the fallback. Bare host, no `/v1`: `claude` appends `/v1/messages`.
+ */
+declare const DEFAULT_LOCAL_AI_PROXY_URL = "http://127.0.0.1:18193";
+/**
+ * The model `claude -p --model` runs in proxy mode when the agent has no
+ * `defaultModel` (or the daemon's lookup timed out). `claude`'s own default is
+ * a dated id the proxy cannot route. Haiku 4.5 is the one Claude model seeded
+ * on every stage (the memory integration depends on it), so it is the only
+ * id guaranteed to route; the dashboard always sets a model, so this is rare.
+ */
+declare const PROXY_DEFAULT_MODEL = "claude-haiku-4-5";
+/**
+ * Fixed model env in proxy mode, Alfe registry ids (`AnthropicModel` in
+ * `@alfe/types`; the child-env test asserts it). `ANTHROPIC_SMALL_FAST_MODEL`
+ * drives background calls (titles, summaries); `ANTHROPIC_DEFAULT_HAIKU_MODEL`
+ * resolves the `haiku` alias. Haiku 4.5 because it is seeded on every stage.
+ * claude 2.1.284/2.1.287 read these and {@link PROXY_AGENT_MODEL_ENV_VARS}.
+ */
+declare const PROXY_MODEL_ENV: {
+  readonly ANTHROPIC_SMALL_FAST_MODEL: "claude-haiku-4-5";
+  readonly ANTHROPIC_DEFAULT_HAIKU_MODEL: "claude-haiku-4-5";
+};
+/**
+ * The `sonnet` / `opus` aliases (subagents) resolve to the agent's OWN model
+ * in proxy mode: the agents service validated it against the registry, while a
+ * fixed 5.x id may not be enabled on the workspace.
+ */
+declare const PROXY_AGENT_MODEL_ENV_VARS: readonly ["ANTHROPIC_DEFAULT_SONNET_MODEL", "ANTHROPIC_DEFAULT_OPUS_MODEL"];
+/** Set only in proxy mode (besides the auth pair). */
+
+/** 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>;
+/** The auth source of one `claude` child. */
+type ChildAuth = {
+  mode: 'credential';
+  credential: ChildCredential;
+} | {
+  mode: 'local_login';
+}
+/** `model` = the turn's registry model id (`--model`); also the sonnet/opus aliases. */ | {
+  mode: 'ai_proxy';
+  baseUrl: string;
+  model: 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 for a credential or the proxy, plus model overrides for the
+ * proxy) → set the bridge marker → set the source's variables. Neither `base`
+ * nor `extra` can smuggle an auth variable in or override the source.
+ * `auth` omitted = local login.
+ */
+declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>, auth?: ChildAuth): NodeJS.ProcessEnv;
+//#endregion
 //#region src/stream-mapper.d.ts
 /**
  * Claude Code `--output-format stream-json` → Alfe chat-activity mapper.
@@ -2314,6 +2492,17 @@ 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;
+  /**
+   * The refusal was a 403 (forbidden: an org or provider policy), not a dead
+   * login or key. Present only with `authFailed`.
+   */
+  authForbidden?: true;
 }
 type MapperEmission = ActivityEmission | TextEmission | EndEmission;
 interface PendingTool {
@@ -2333,6 +2522,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;
 /**
@@ -2382,6 +2573,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];
 /**
@@ -2404,6 +2615,10 @@ 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;
+  /** With `authFailed`: the refusal was a 403 (policy), not a dead login/key. */
+  authForbidden?: true;
 }
 interface RunTurnParams {
   /** The user prompt for this turn. */
@@ -2416,7 +2631,10 @@ interface RunTurnParams {
   mcpConfigPath?: string;
   /** Persona + reply-style text appended to the system prompt. Omitted → none. */
   appendSystemPrompt?: string;
-  /** Bare Claude model id for `--model` (subscription models only). Omitted → CLI default. */
+  /**
+   * Bare Claude model id for `--model`. Omitted → CLI default (never in proxy
+   * mode: the host always passes a registry id there).
+   */
   model?: string;
   /** Tool allow-list (defaults to DEFAULT_ALLOWED_TOOLS). */
   allowedTools?: readonly string[];
@@ -2449,12 +2667,21 @@ declare class SessionDriver {
   private abortCurrent;
   private readonly bin;
   private readonly baseEnv;
+  private readonly auth;
+  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 turn's auth source, applied to the child env after the scrub
+     * (`buildChildEnv`). Absent → the machine's own `claude` login.
+     */
+    auth?: ChildAuth;
+    /** Managed VM: Bash allowed + deny rules (see MANAGED_ALLOWED_TOOLS). */
+    managed?: boolean;
     logger?: Logger;
     /** Test seam: inject a fake `spawn`. */
     __spawn?: typeof spawn;
@@ -2475,6 +2702,118 @@ 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;
+/** Why the Alfe AI proxy refused a request it otherwise authenticated. */
+type ProxyDenial = 'credits' | 'usage_limit' | 'model_unavailable';
+/**
+ * Classify an Alfe AI proxy refusal from the text `claude` reports. The proxy
+ * answers credit and usage-limit denials on `/v1/messages` with a 429
+ * `rate_limit_error` (never 402, see services/ai DEVELOPING.md "Credit denials
+ * on LLM routes are 429"); claude 2.1.287 surfaces it as
+ * `API Error: Request rejected (429) · <message>` (fixture
+ * `turn-proxy-credits.stream.jsonl`). Credit texts also say "usage limit
+ * reached", so they are checked first. An Anthropic subscription limit
+ * ("Claude AI usage limit reached") is not an Alfe denial.
+ */
+declare function classifyProxyDenial(text: string): ProxyDenial | null;
+/** HTTP statuses on a `result` event that mean "credential refused". */
+
+type ProbeOutcome = {
+  result: 'ok';
+}
+/** `forbidden`: a 403 (an org or provider policy), not a dead login or key. */ | {
+  result: 'invalid';
+  forbidden?: true;
+}
+/** The Alfe AI proxy authenticated the agent but refused the request. */ | {
+  result: 'denied';
+  denial: ProxyDenial;
+} | {
+  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.
+ * `model` is `haiku` (the alias) on a credential or local login, and the
+ * registry Haiku id through the AI proxy.
+ */
+declare function buildProbeArgs(model?: string): string[];
+declare function parseProbeOutput(stdout: string, stderr: string, exitCode: number | null): ProbeOutcome;
+interface AuthProbeOptions {
+  /** The auth source to check (a credential, the local login, or the AI proxy). */
+  auth: ChildAuth;
+  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 on the given auth source: Anthropic with the agent's
+ * credential or the machine's own login, or the Alfe AI proxy (a Haiku ping
+ * billed from Alfe credits). Never throws.
+ */
+declare function runAuthProbe(opts: AuthProbeOptions): Promise<ProbeOutcome>;
+/** Which auth the host's turns run on (projected as `claudeCredentialSource`). */
+type CredentialSource = 'credential' | 'local_login' | 'ai_proxy';
+interface CredentialStatusReport {
+  /** `missing` is legacy; this host never sends it (it falls back to the AI proxy). */
+  status: 'ok' | 'missing' | 'invalid';
+  source?: CredentialSource;
+  /** 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). */
@@ -2492,12 +2831,34 @@ interface ClaudeCodeHostConfig {
   /**
    * Bare Claude model id for `claude -p --model` (e.g. `claude-opus-4-8` or the
    * `opus`/`sonnet`/`haiku` aliases). Sourced from the agent's `defaultModel`
-   * via `ALFE_DEFAULT_MODEL`. Omitted → the operator's `claude` CLI default.
+   * via `ALFE_DEFAULT_MODEL`. Omitted → the operator's `claude` CLI default on
+   * a credential or local login, `PROXY_DEFAULT_MODEL` on the AI proxy.
    * NEVER provider-qualified (`anthropic/…`) — that's an OpenClaw-only shape.
    */
   model?: string;
+  /**
+   * Managed VM (`ALFE_MANAGED=1|true`, set by the daemon). Enables Bash. With
+   * no stored credential a managed agent always runs on the Alfe AI proxy (no
+   * local login to fall back to). Self-hosted when false/absent.
+   */
+  managed?: boolean;
+  /**
+   * The daemon's loopback AI proxy (`ALFE_LOCAL_AI_PROXY_URL`). Defaults to
+   * `DEFAULT_LOCAL_AI_PROXY_URL`.
+   */
+  localAiProxyUrl?: string;
   logger?: Logger;
 }
+declare const CREDENTIAL_INVALID_MESSAGE = "This agent's Claude credential is invalid or expired. Update it in agent settings.";
+declare const OUT_OF_CREDITS_MESSAGE = "This agent is out of Alfe credits. Add credits in Alfe Billing, or add a Claude credential in agent settings, then resend your message.";
+declare const USAGE_LIMIT_MESSAGE = "This agent hit an Alfe usage limit. Raise the limit in Alfe or wait for it to reset, then resend your message.";
+declare const LOCAL_LOGIN_SWITCHED_MESSAGE = "Your machine's Claude login stopped working, so this agent switched to Alfe credits. Please resend your message.";
+declare const LOCAL_LOGIN_REFUSED_MESSAGE = "Claude refused this machine's claude login (403). Check the account or its organisation policy, or add a Claude credential in agent settings.";
+declare const MODEL_UNAVAILABLE_MESSAGE = "This agent's model isn't available on this workspace. Choose another Claude model in agent settings, then resend your message.";
+declare const PROXY_AUTH_FAILED_MESSAGE = "Alfe AI rejected this agent's key. Reconnect the agent (run `alfe setup` on its machine), or add a Claude credential 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;
   /**
@@ -2521,14 +2882,104 @@ 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;
+  /** How often a fallen-back self-hosted agent re-checks its local login. */
+  private readonly localLoginRecheckMs;
+  private localLoginRecheck;
+  /** In memory only. Never logged, never persisted. */
+  private credential;
+  /**
+   * The auth every new turn runs on, resolved once the credential fetch
+   * answers (see `resolveAuthSource`). Null before that.
+   */
+  private authSource;
+  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 (and once
+     * more for a local-login turn re-run on the AI proxy) with its auth.
+     */
+    makeDriver?: (auth: ChildAuth) => SessionDriver;
     chat?: ChatServiceClient;
     api?: AgentApiClient;
+    /** Start-up auth check (test seam; default: a minimal `claude -p`). */
+    probe?: (auth: ChildAuth, signal: AbortSignal) => Promise<ProbeOutcome>;
+    credentialWaitMs?: number;
+    /** Delay before restarting a credential loader that threw (default 5 s). */
+    loaderRestartMs?: number;
+    /**
+     * After falling back from a refused local login, re-probe it this often
+     * and switch back when it works (default: the status-report interval).
+     */
+    localLoginRecheckMs?: 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;
+  /**
+   * A method, not a property read: `stopping` flips across awaits, which
+   * control-flow narrowing cannot see.
+   */
+  private isStopping;
+  /** Same reason as `isStopping`: `authSource` can change across an await. */
+  private currentAuthSource;
+  /** The auth a new turn runs on. Local login until the fetch has answered. */
+  private childAuth;
+  /**
+   * A self-hosted agent with no credential whose local login was refused (401
+   * or an explicit auth message, never a 403): run new turns through the Alfe
+   * AI proxy, and re-check the login periodically so a re-login moves the agent
+   * back off Alfe credits. Never for a stored credential (the user chose it; a
+   * refusal there needs their fix) and never on managed.
+   */
+  private fallBackToProxy;
+  private scheduleLocalLoginRecheck;
+  /** While fallen back: one local-login probe; back to the login when it works. */
+  private recheckLocalLogin;
+  /**
+   * Start-up check: one minimal real call on the resolved source, reported to
+   * the cloud. A refused local login falls back to the proxy and checks that.
+   */
+  private checkCredential;
+  /** Report the current auth source as working or refused. */
+  private reportStatus;
+  /**
+   * 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>;
   /**
@@ -2539,10 +2990,44 @@ declare class ClaudeCodeHost {
   private handleAgent;
   private deliverAgentOutcome;
   private runAgentTurn;
+  /**
+   * Settle a failed turn (C3) after storing its message as the assistant's
+   * reply, so the history shows what the user saw. Stored first: a client that
+   * reloads on the failure must find it. Best-effort: a store failure never
+   * changes the outcome.
+   */
+  private failTurn;
+  /**
+   * 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.
    */
+  /**
+   * Run one turn on `auth` with its own driver, registered as the session's
+   * running turn so `chat.abort` reaches it. Proxy turns always carry a
+   * registry model.
+   */
+  private runTurnOn;
   private runWithResumeFallback;
   private forwardEmission;
   private handleChatAbort;
@@ -2559,45 +3044,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';
@@ -2629,6 +3075,12 @@ interface ChatMessage {
   role: 'user' | 'assistant';
   content: string;
   timestamp: number;
+  /**
+   * `'error'`: the failure message a turn settled with, stored so the history
+   * shows what the user saw. History only: memory ingest and the resume
+   * preamble skip it (it is not something the agent said).
+   */
+  kind?: 'error';
   senderId?: string;
   senderName?: string;
   components?: StoredMessageComponent[];
@@ -2664,7 +3116,10 @@ type ChatActivityRecord = {
 interface SessionData {
   sessionId: string;
   agentId: string;
+  /** Always `CHAT_SESSION_CHANNEL` for sessions this host writes. */
   channel: string;
+  /** The chat surface that opened the conversation (`mobile`, `dashboard`, ...). */
+  clientType?: string;
   tenantId?: string;
   userId?: string;
   createdAt: string;
@@ -2677,7 +3132,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;
@@ -2689,10 +3162,26 @@ interface SessionSummary {
   preview?: string;
   messageCount: number;
 }
+/**
+ * The channel every chat session is stored on. Every chat client lists with
+ * `sessions.list { channel: 'alfe' }` and openclaw-chat stores `'alfe'`, so any
+ * other value hides the conversation from the rail.
+ */
+
 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>;
+declare function createSession(sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string, clientType?: string): Promise<SessionData>;
+/**
+ * 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>;
+/**
+ * Store the failure message a turn settled with as the assistant's reply, so
+ * the history shows what the user saw. Returns its index, or -1 when the
+ * session does not exist.
+ */
+
 /**
  * Append a turn's terminalized activity records. Called ONCE per turn (from the
  * dispatch `finally`) — never per-delta.
@@ -2712,4 +3201,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_UNAVAILABLE_MESSAGE, type ChatActivityRecord, type ChatMessage, type ChildAuth, type ChildCredential, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, type CredentialSource, type CredentialStatusReport, CredentialStatusReporter, DEFAULT_ALLOWED_TOOLS, DEFAULT_LOCAL_AI_PROXY_URL, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type HostCredential, LOCAL_LOGIN_REFUSED_MESSAGE, LOCAL_LOGIN_SWITCHED_MESSAGE, MANAGED_ALLOWED_TOOLS, MANAGED_DISALLOWED_TOOLS, MODEL_UNAVAILABLE_MESSAGE, type MapperEmission, type MapperState, OUT_OF_CREDITS_MESSAGE, PROXY_AGENT_MODEL_ENV_VARS, PROXY_API_KEY_PLACEHOLDER, PROXY_AUTH_FAILED_MESSAGE, PROXY_DEFAULT_MODEL, PROXY_MODEL_ENV, type ProbeOutcome, type ProxyDenial, 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, USAGE_LIMIT_MESSAGE, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, buildProbeArgs, classifyProxyDenial, collectTurnActivityRecords, createMapperState, createSession, getSession, isAuthFailureText, listSessions, loadCredentialWithRetry, mapStreamEvent, mapStreamEvents, parseProbeOutput, resolveHostConfig, runAuthProbe, saveSession, stripAgentPrefix };