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

package/dist/host-config.js

@@ -1,74 +1,527 @@
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
 import { ChatServiceClient, resolveAlfeChat } from "@alfe.ai/chat";
+import { existsSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import { existsSync } from "node:fs";
-import { resolveConfig } from "@alfe.ai/config";
+import { resolveAgentWorkspace, resolveConfig, resolveRuntimeHome } from "@alfe.ai/config";
 //#region src/child-env.ts
 /**
 * Child-process environment construction for spawned `claude` CLI processes.
 *
-* TWO non-negotiable invariants (Phase 2 plan, audit B2 + the hard
-* constraints):
+* 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).
 *
-* 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.
+* Invariants:
 *
-* 2. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
+* 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.
 */
-/** Anthropic env vars that force API-key / proxy auth and MUST be scrubbed. */
+/** Claude auth env vars that MUST NOT be inherited by a `claude` child. */
 const SCRUBBED_ANTHROPIC_ENV_VARS = [
 	"ANTHROPIC_API_KEY",
 	"ANTHROPIC_BASE_URL",
-	"ANTHROPIC_AUTH_TOKEN"
+	"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.
+*/
+const PROVIDER_OVERRIDE_ENV_VARS = [
+	"CLAUDE_CODE_USE_BEDROCK",
+	"CLAUDE_CODE_USE_VERTEX",
+	"CLAUDE_CODE_USE_FOUNDRY",
+	"CLAUDE_CODE_SKIP_BEDROCK_AUTH",
+	"CLAUDE_CODE_SKIP_VERTEX_AUTH",
+	"CLAUDE_CODE_SKIP_FOUNDRY_AUTH",
+	"ANTHROPIC_BEDROCK_BASE_URL",
+	"ANTHROPIC_VERTEX_BASE_URL",
+	"ANTHROPIC_VERTEX_PROJECT_ID",
+	"ANTHROPIC_FOUNDRY_BASE_URL",
+	"ANTHROPIC_FOUNDRY_RESOURCE",
+	"ANTHROPIC_FOUNDRY_API_KEY",
+	"AWS_BEARER_TOKEN_BEDROCK"
 ];
 /** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
 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_…`.
+*/
+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`.
+*/
+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.
+*/
+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}.
+*/
+const PROXY_MODEL_ENV = {
+	ANTHROPIC_SMALL_FAST_MODEL: "claude-haiku-4-5",
+	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.
+*/
+const PROXY_AGENT_MODEL_ENV_VARS = ["ANTHROPIC_DEFAULT_SONNET_MODEL", "ANTHROPIC_DEFAULT_OPUS_MODEL"];
+/**
+* Inherited overrides that would send a proxy turn a model or header the proxy
+* can't price or doesn't expect. Dropped in proxy mode only.
+*/
+const PROXY_SCRUBBED_ENV_VARS = [
+	...[
+		...Object.keys(PROXY_MODEL_ENV),
+		...PROXY_AGENT_MODEL_ENV_VARS,
+		"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"
+	],
+	"ANTHROPIC_MODEL",
+	"ANTHROPIC_DEFAULT_FABLE_MODEL",
+	"ANTHROPIC_CUSTOM_HEADERS",
+	"CLAUDE_CODE_SUBAGENT_MODEL"
+];
+/** The single env var each credential kind is exported as. */
+const CREDENTIAL_ENV_VAR = {
+	oauth_token: "CLAUDE_CODE_OAUTH_TOKEN",
+	api_key: "ANTHROPIC_API_KEY"
+};
+/**
 * 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.
+* 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.
 */
-function buildChildEnv(base, extra) {
+function buildChildEnv(base, extra, auth = { mode: "local_login" }) {
 	const merged = {
 		...base,
-		...extra,
-		[BRIDGE_ENV_VAR]: "1"
+		...extra
 	};
 	const scrubbed = new Set(SCRUBBED_ANTHROPIC_ENV_VARS);
+	if (auth.mode !== "local_login") for (const key of PROVIDER_OVERRIDE_ENV_VARS) scrubbed.add(key);
+	if (auth.mode === "ai_proxy") for (const key of PROXY_SCRUBBED_ENV_VARS) scrubbed.add(key);
 	const env = {};
 	for (const [key, value] of Object.entries(merged)) if (!scrubbed.has(key)) env[key] = value;
+	env[BRIDGE_ENV_VAR] = "1";
+	if (auth.mode === "credential") env[CREDENTIAL_ENV_VAR[auth.credential.kind]] = auth.credential.value;
+	else if (auth.mode === "ai_proxy") {
+		env.ANTHROPIC_BASE_URL = auth.baseUrl;
+		env.ANTHROPIC_AUTH_TOKEN = PROXY_API_KEY_PLACEHOLDER;
+		Object.assign(env, PROXY_MODEL_ENV);
+		for (const key of PROXY_AGENT_MODEL_ENV_VARS) env[key] = auth.model;
+		env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
+	}
 	return env;
 }
 //#endregion
+//#region src/credential.ts
+/**
+* The agent's Claude credential, on the host side: fetching it, checking it
+* against Anthropic, classifying auth failures, and reporting health.
+*
+* Contract (see DEVELOPING.md "Claude credential"):
+*  - Fetched with the agent API key (`GET /agent/claude-credential`) on every
+*    host start. The daemon restarts the host when the credential changes, so
+*    a start IS the refetch. A failed fetch retries with backoff forever; the
+*    host never exits over it (that would crash-loop the daemon).
+*  - The value lives only in memory and in each `claude` child env
+*    (`buildChildEnv`). Never logged, never written to disk.
+*  - Health is checked once per start with the cheapest call that actually
+*    reaches Anthropic. `claude auth status` does NOT: with an env token it
+*    reports `loggedIn: true` for any string (verified on claude 2.1.284), so
+*    the probe is a one-turn `claude -p` on haiku with no tools, a one-line
+*    system prompt and thinking off (measured 381 input + 4 output tokens,
+*    $0.0004 at list price, under a second).
+*/
+function sleepFor(ms, signal) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(done, ms);
+		function done() {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", done);
+			resolve();
+		}
+		signal.addEventListener("abort", done, { once: true });
+	});
+}
+/**
+* Fetch until it answers. `{ credential: null }` = nothing stored (a real
+* answer); `null` = aborted before any answer.
+*/
+async function loadCredentialWithRetry(fetchCredential, opts) {
+	const base = opts.baseDelayMs ?? 1e3;
+	const max = opts.maxDelayMs ?? 6e4;
+	const random = opts.random ?? Math.random;
+	const sleep = opts.sleep ?? sleepFor;
+	const aborted = () => opts.signal.aborted;
+	for (let attempt = 0;; attempt += 1) {
+		if (aborted()) return null;
+		try {
+			const credential = await fetchCredential();
+			opts.log.info(credential ? `[claude-host] Claude credential loaded (${credential.kind})` : "[claude-host] no Claude credential stored for this agent");
+			return { credential };
+		} catch (err) {
+			if (aborted()) return null;
+			const cap = Math.min(max, base * 2 ** attempt);
+			const delay = Math.round(cap * (.5 + random() / 2));
+			opts.log.warn(`[claude-host] could not load the Claude credential (${err instanceof Error ? err.message : String(err)}); retrying in ${String(delay)}ms`);
+			await sleep(delay, opts.signal);
+		}
+	}
+}
+/**
+* Messages `claude` prints when Anthropic (or the CLI) refuses the credential.
+* Captured from claude 2.1.284 (`src/__fixtures__/turn-auth-*.stream.jsonl`)
+* plus the documented expiry message. Rate limits, overload and timeouts are
+* deliberately NOT here — they say nothing about the credential.
+*/
+const AUTH_FAILURE_MARKERS = [
+	"authentication_failed",
+	"failed to authenticate",
+	"invalid api key",
+	"invalid x-api-key",
+	"oauth access token is invalid",
+	"oauth token has expired",
+	"oauth token has been revoked",
+	"invalid bearer token",
+	"not logged in",
+	"please run /login"
+];
+function isAuthFailureText(text) {
+	const lower = text.toLowerCase();
+	return AUTH_FAILURE_MARKERS.some((marker) => lower.includes(marker));
+}
+/**
+* Proxy texts for a model this workspace or agent cannot use: 409
+* `model_route_denied` (unknown, disabled or mis-routed registry id) and 403
+* `model_not_approved` (tenant model policy). The 403 must not read as a
+* refused key.
+*/
+const MODEL_UNAVAILABLE_MARKERS = [
+	"model_route_denied",
+	"model_not_approved",
+	"model is not available",
+	"is restricted to:",
+	"not approved for this organization",
+	"requires an anthropic-routed model",
+	"no supported standard inference route",
+	"cannot use the standard data plane",
+	"not an enabled reviewed"
+];
+/**
+* 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.
+*/
+function classifyProxyDenial(text) {
+	const lower = text.toLowerCase();
+	if (lower.includes("no ai credits left") || lower.includes("partner account cannot run ai requests") || lower.includes("insufficient_credits") || lower.includes("credits_exhausted")) return "credits";
+	if (/\balfe (?:daily |weekly |monthly )?usage limit reached\b/.test(lower)) return "usage_limit";
+	if (MODEL_UNAVAILABLE_MARKERS.some((marker) => lower.includes(marker))) return "model_unavailable";
+	return null;
+}
+/** HTTP statuses on a `result` event that mean "credential refused". */
+function isAuthFailureStatus(status) {
+	return status === 401 || status === 403;
+}
+const AUTH_PROBE_TIMEOUT_MS = 6e4;
+const MAX_PROBE_OUTPUT_CHARS = 64e3;
+/**
+* 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.
+*/
+function buildProbeArgs(model = "haiku") {
+	return [
+		"-p",
+		"--input-format",
+		"text",
+		"--output-format",
+		"json",
+		"--model",
+		model,
+		"--tools",
+		"",
+		"--system-prompt",
+		"Reply with the single word OK.",
+		"--max-turns",
+		"1",
+		"--no-session-persistence",
+		"--strict-mcp-config",
+		"--setting-sources",
+		""
+	];
+}
+function parseProbeOutput(stdout, stderr, exitCode) {
+	const lines = stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+	for (let index = lines.length - 1; index >= 0; index -= 1) {
+		let event;
+		try {
+			event = JSON.parse(lines[index]);
+		} catch {
+			continue;
+		}
+		if (!event || typeof event !== "object") continue;
+		const record = event;
+		if (record.type !== "result") continue;
+		if (record.is_error === false) return { result: "ok" };
+		const text = typeof record.result === "string" ? record.result : "";
+		const denial = classifyProxyDenial(text);
+		if (denial) return {
+			result: "denied",
+			denial
+		};
+		if (isAuthFailureStatus(record.api_error_status) || isAuthFailureText(text)) return record.api_error_status === 403 ? {
+			result: "invalid",
+			forbidden: true
+		} : { result: "invalid" };
+		return {
+			result: "unknown",
+			reason: `probe failed (${typeof record.api_error_status === "number" ? `HTTP ${String(record.api_error_status)}` : "no auth error"})`
+		};
+	}
+	if (isAuthFailureText(stderr)) return { result: "invalid" };
+	return {
+		result: "unknown",
+		reason: `probe produced no result (exit ${String(exitCode)})`
+	};
+}
+/**
+* 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.
+*/
+function runAuthProbe(opts) {
+	const spawnImpl = opts.spawnImpl ?? spawn;
+	const env = buildChildEnv(opts.baseEnv, { MAX_THINKING_TOKENS: "0" }, opts.auth);
+	const model = opts.auth.mode === "ai_proxy" ? PROXY_MODEL_ENV.ANTHROPIC_DEFAULT_HAIKU_MODEL : void 0;
+	return new Promise((resolve) => {
+		if (opts.signal?.aborted) {
+			resolve({
+				result: "unknown",
+				reason: "host stopping"
+			});
+			return;
+		}
+		let settled = false;
+		let stdout = "";
+		let stderr = "";
+		const finish = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			opts.signal?.removeEventListener("abort", onAbort);
+			resolve(outcome);
+		};
+		const kill = () => {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+		};
+		function onAbort() {
+			kill();
+			finish({
+				result: "unknown",
+				reason: "host stopping"
+			});
+		}
+		let child;
+		try {
+			child = spawnImpl(opts.claudeBin ?? "claude", buildProbeArgs(model), {
+				cwd: opts.cwd,
+				env,
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			resolve({
+				result: "unknown",
+				reason: `could not start claude: ${err instanceof Error ? err.message : String(err)}`
+			});
+			return;
+		}
+		opts.signal?.addEventListener("abort", onAbort, { once: true });
+		const timer = setTimeout(() => {
+			kill();
+			finish({
+				result: "unknown",
+				reason: "probe timed out"
+			});
+		}, opts.timeoutMs ?? 6e4);
+		timer.unref();
+		const stdoutDecoder = new StringDecoder("utf8");
+		const stderrDecoder = new StringDecoder("utf8");
+		child.stdout?.on("data", (chunk) => {
+			stdout = `${stdout}${stdoutDecoder.write(chunk)}`.slice(-MAX_PROBE_OUTPUT_CHARS);
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr = `${stderr}${stderrDecoder.write(chunk)}`.slice(-MAX_PROBE_OUTPUT_CHARS);
+		});
+		child.on("error", (err) => {
+			finish({
+				result: "unknown",
+				reason: `claude process error: ${err.message}`
+			});
+		});
+		child.on("close", (code) => {
+			finish(parseProbeOutput(stdout, stderr, code));
+		});
+		try {
+			child.stdin?.end("ping");
+		} catch {}
+	});
+}
+/** An unchanged status is re-sent at most this often (a liveness signal). */
+const STATUS_REPORT_INTERVAL_MS = 15 * 6e4;
+/**
+* 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.
+*/
+var CredentialStatusReporter = class {
+	lastKey = null;
+	lastSentAt = 0;
+	chain = Promise.resolve();
+	now;
+	log;
+	constructor(send, opts) {
+		this.send = send;
+		this.log = opts.log;
+		this.now = opts.now ?? Date.now;
+	}
+	report(report) {
+		this.chain = this.chain.then(() => this.deliver(report));
+		return this.chain;
+	}
+	async deliver(report) {
+		const key = JSON.stringify([
+			report.status,
+			report.source ?? null,
+			report.revision ?? null,
+			report.detail ?? null
+		]);
+		if (key === this.lastKey && this.now() - this.lastSentAt < 9e5) return;
+		try {
+			const { accepted } = await this.send(report);
+			this.lastKey = key;
+			this.lastSentAt = this.now();
+			this.log.info(`[claude-host] Claude credential status ${report.status} ${accepted ? "reported" : "ignored (credential changed since)"}`);
+		} catch (err) {
+			this.log.warn(`[claude-host] could not report Claude credential status ${report.status}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+};
+//#endregion
 //#region src/stream-mapper.ts
+/**
+* Claude Code `--output-format stream-json` → Alfe chat-activity mapper.
+*
+* This is the load-bearing core of the bridge. It consumes the newline-delimited
+* JSON events emitted by `claude -p ... --output-format stream-json
+* --include-partial-messages` and translates them into the SAME wire shapes the
+* `@alfe.ai/openclaw-chat` plugin emits, so the chat service / adapter / UI
+* treat a Claude Code turn identically to an OpenClaw turn.
+*
+* Ground truth: a real captured turn (thinking + Read tool + text + result) at
+* `src/__fixtures__/turn-read-tool.stream.jsonl`. The mapper test runs against
+* that fixture (TEST-FIRST).
+*
+* Event model (verified against the fixture + Claude Code stream-json docs):
+*   - `{type:'system', subtype:'init', session_id}` — carries the claude
+*     session id we persist for `--resume`.
+*   - `{type:'stream_event', event:{type:'content_block_delta', delta:{
+*        type:'thinking_delta', thinking}}}` — a thinking chunk.
+*   - `{type:'stream_event', event:{type:'content_block_delta', delta:{
+*        type:'text_delta', text}}}` — a visible-text chunk (accumulate → the
+*        CUMULATIVE snapshot the adapter length-slices).
+*   - `{type:'assistant', message:{content:[{type:'tool_use', id, name,
+*        input}]}}` — a tool CALL. The non-streaming `assistant` message has the
+*        COMPLETE id/name/input (the streaming `content_block_start` has empty
+*        input, filled by `input_json_delta`), so we correlate off THIS.
+*   - `{type:'user', message:{content:[{type:'tool_result', tool_use_id,
+*        content, is_error?}]}}` — a tool RESULT. `tool_use_id === tool_use.id`.
+*   - `{type:'result', is_error, result, duration_ms}` — the turn end.
+*
+* The mapper is a PURE reducer over one event: it takes the running state and an
+* event, mutates the state, and returns the list of `MapperEmission`s to send.
+* It performs NO IO — the host does the sending / persisting. `progressText` /
+* the 250ms mid-tool throttle from openclaw-chat is inert here: Claude Code has
+* no mid-tool progress analog, so we deliberately don't implement it.
+*/
 function createMapperState() {
 	return {
 		claudeSessionId: null,
 		seq: 0,
 		visibleText: "",
 		pendingTools: /* @__PURE__ */ new Map(),
-		ended: false
+		ended: false,
+		authFailed: false
 	};
 }
 const MAX_ARGS_CHARS = 2e3;
@@ -183,6 +636,7 @@ function mapStreamEvent(state, raw, nowMs) {
 		return [];
 	}
 	if (type === "assistant") {
+		if (evt.error === "authentication_failed") state.authFailed = true;
 		const content = asRecord$1(evt.message)?.content;
 		if (!Array.isArray(content)) return [];
 		const emissions = [];
@@ -262,6 +716,7 @@ function mapStreamEvent(state, raw, nowMs) {
 		const durationRaw = evt.duration_ms;
 		const durationMs = typeof durationRaw === "number" && Number.isFinite(durationRaw) ? Math.max(0, durationRaw) : void 0;
 		const errorMessage = isError ? asString(evt.result) ?? asString(evt.subtype) ?? "Claude Code turn failed" : void 0;
+		const authFailed = isError && (state.authFailed || isAuthFailureStatus(evt.api_error_status) || isAuthFailureText(asString(evt.result) ?? ""));
 		return [{
 			type: "turn-end",
 			seq: state.seq++,
@@ -269,7 +724,9 @@ function mapStreamEvent(state, raw, nowMs) {
 			isError,
 			finalText: isError ? "" : finalText,
 			...durationMs !== void 0 ? { durationMs } : {},
-			...errorMessage ? { errorMessage } : {}
+			...errorMessage ? { errorMessage } : {},
+			...authFailed ? { authFailed: true } : {},
+			...authFailed && evt.api_error_status === 403 ? { authForbidden: true } : {}
 		}];
 	}
 	return [];
@@ -408,6 +865,30 @@ const DEFAULT_ALLOWED_TOOLS = [
 	"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.
+*/
+const MANAGED_ALLOWED_TOOLS = [...DEFAULT_ALLOWED_TOOLS, "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.
+*/
+const MANAGED_DISALLOWED_TOOLS = [
+	"Bash(gws auth)",
+	"Bash(gws auth:*)",
+	"Read(~/.config/gws-*/**)"
+];
 const CLAUDE_PERMISSION_MODES = [
 	"acceptEdits",
 	"auto",
@@ -456,12 +937,16 @@ var SessionDriver = class {
 	abortCurrent = null;
 	bin;
 	baseEnv;
+	auth;
+	managed;
 	log;
 	/** Injected spawn — tests replace this with a fake child. */
 	spawnImpl;
 	constructor(opts) {
 		this.bin = opts?.claudeBin ?? DEFAULT_CLAUDE_BIN;
 		this.baseEnv = opts?.baseEnv ?? process.env;
+		this.auth = opts?.auth ?? { mode: "local_login" };
+		this.managed = opts?.managed ?? false;
 		this.log = opts?.logger ?? console;
 		this.spawnImpl = opts?.__spawn ?? spawn;
 	}
@@ -485,7 +970,7 @@ var SessionDriver = class {
 		return this.runPerTurn(params);
 	}
 	buildArgs(params) {
-		const allowed = (params.allowedTools ?? DEFAULT_ALLOWED_TOOLS).join(",");
+		const allowed = (params.allowedTools ?? (this.managed ? MANAGED_ALLOWED_TOOLS : DEFAULT_ALLOWED_TOOLS)).join(",");
 		const permissionMode = params.permissionMode ?? "dontAsk";
 		if (!CLAUDE_PERMISSION_MODES.includes(permissionMode)) throw new Error(`Unsupported Claude permission mode: ${permissionMode}`);
 		const args = [
@@ -499,8 +984,10 @@ var SessionDriver = class {
 			"--permission-mode",
 			permissionMode,
 			"--allowedTools",
-			allowed
+			allowed,
+			"--strict-mcp-config"
 		];
+		if (this.managed) args.push("--disallowedTools", MANAGED_DISALLOWED_TOOLS.join(","));
 		if (params.model) args.push("--model", params.model);
 		if (params.claudeSessionId) args.push("--resume", params.claudeSessionId);
 		if (params.mcpConfigPath) args.push("--mcp-config", params.mcpConfigPath);
@@ -518,7 +1005,7 @@ var SessionDriver = class {
 		let stderr = "";
 		let rateLimited = false;
 		const args = this.buildArgs(params);
-		const env = buildChildEnv(this.baseEnv);
+		const env = buildChildEnv(this.baseEnv, void 0, this.auth);
 		return new Promise((resolve) => {
 			let child;
 			try {
@@ -556,18 +1043,22 @@ var SessionDriver = class {
 				this.abortCurrent = null;
 				const end = emissions.find((e) => e.type === "turn-end");
 				const endIsError = end?.type === "turn-end" ? end.isError : false;
+				const endAuthFailed = end?.type === "turn-end" && end.authFailed === true;
 				const endText = end?.type === "turn-end" ? end.finalText : state.visibleText;
 				const endErrMsg = end?.type === "turn-end" ? end.errorMessage : void 0;
 				const finalIsError = isError || endIsError;
 				const finalErrMsg = errorMessage ?? endErrMsg ?? (finalIsError ? rateLimited || looksRateLimited(stderr) ? "Claude subscription rate limit hit — try again shortly" : stderr.trim().slice(0, 500) || "Claude Code turn failed" : void 0);
 				const retainedEmissions = latestTextEmission ? [...emissions, latestTextEmission].sort((a, b) => a.seq - b.seq) : emissions;
+				const authFailed = finalIsError && !aborted && terminationReason === null && (end ? endAuthFailed : isAuthFailureText(stderr));
 				resolve({
 					claudeSessionId: state.claudeSessionId,
 					emissions: retainedEmissions,
 					isError: finalIsError,
 					finalText: finalIsError ? "" : endText,
 					...finalErrMsg ? { errorMessage: finalErrMsg } : {},
-					aborted
+					aborted,
+					...authFailed ? { authFailed: true } : {},
+					...authFailed && end?.type === "turn-end" && end.authForbidden ? { authForbidden: true } : {}
 				});
 			};
 			const requestTermination = (reason) => {
@@ -619,9 +1110,10 @@ var SessionDriver = class {
 					}
 				}
 			});
+			const stderrDecoder = new StringDecoder("utf8");
 			child.stderr.on("data", (chunk) => {
 				if (settled) return;
-				const text = chunk.toString("utf-8");
+				const text = stderrDecoder.write(chunk);
 				rateLimited ||= looksRateLimited(text);
 				stderr = `${stderr}${text}`.slice(-MAX_STDERR_CHARS);
 			});
@@ -694,6 +1186,27 @@ async function writeTextAtomically(path, contents) {
 *
 * where `sessionId = conversationId ?? sessionKey`.
 */
+/**
+* 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.
+*/
+const CHAT_SESSION_CHANNEL = "alfe";
+/**
+* Values hosts up to 0.1.16 stored as `channel`: the chat surface label
+* (`params.clientType ?? 'chat'`). Read as `CHAT_SESSION_CHANNEL`; the file is
+* rewritten on its next save.
+*/
+const LEGACY_SURFACE_CHANNELS = new Set([
+	"chat",
+	"dashboard",
+	"mobile",
+	"desktop",
+	"widget",
+	"unknown"
+]);
+/** Legacy values that never named a real surface, so carry no `clientType`. */
+const LEGACY_PLACEHOLDER_CHANNELS = new Set(["chat", "unknown"]);
 function sessionsDir() {
 	return process.env.ALFE_SESSIONS_DIR ?? join(homedir(), ".alfe", "sessions", "chat");
 }
@@ -712,6 +1225,7 @@ function sessionPath(sessionId) {
 function asSessionData(value, expectedSessionId) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 	const record = value;
+	normaliseLegacyChannel(record);
 	if (typeof record.sessionId !== "string" || expectedSessionId !== void 0 && record.sessionId !== expectedSessionId || typeof record.agentId !== "string" || typeof record.channel !== "string" || typeof record.createdAt !== "string" || typeof record.updatedAt !== "string" || !Array.isArray(record.messages)) return null;
 	if (!record.messages.every((message) => {
 		if (!message || typeof message !== "object" || Array.isArray(message)) return false;
@@ -719,8 +1233,21 @@ function asSessionData(value, expectedSessionId) {
 		return (item.role === "user" || item.role === "assistant") && typeof item.content === "string" && typeof item.timestamp === "number" && Number.isFinite(item.timestamp);
 	})) return null;
 	if (record.activity !== void 0 && !Array.isArray(record.activity)) return null;
+	if (record.memory !== void 0 && !isMemoryCursor(record.memory)) delete record.memory;
 	return value;
 }
+/** Map a pre-0.1.17 surface-label channel (or none) onto `CHAT_SESSION_CHANNEL`. */
+function normaliseLegacyChannel(record) {
+	const channel = record.channel;
+	if (channel !== void 0 && !(typeof channel === "string" && LEGACY_SURFACE_CHANNELS.has(channel))) return;
+	if (typeof channel === "string" && !LEGACY_PLACEHOLDER_CHANNELS.has(channel) && record.clientType === void 0) record.clientType = channel;
+	record.channel = CHAT_SESSION_CHANNEL;
+}
+function isMemoryCursor(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const cursor = value;
+	return Number.isSafeInteger(cursor.ingestEpoch) && cursor.ingestEpoch >= 0 && Number.isSafeInteger(cursor.lastIngestedIndex) && cursor.lastIngestedIndex >= -1;
+}
 async function cleanupOldSessions() {
 	if (Date.now() - lastCleanupAt < CLEANUP_INTERVAL_MS) return;
 	const dir = sessionsDir();
@@ -770,42 +1297,216 @@ async function saveSession(session) {
 	session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
 	await writeTextAtomically(sessionPath(session.sessionId), JSON.stringify(session, null, 2));
 }
-async function createSession(sessionId, agentId, channel, tenantId, userId) {
+async function createSession(sessionId, agentId, channel, tenantId, userId, clientType) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const session = {
 		sessionId,
 		agentId,
 		channel,
+		...clientType ? { clientType } : {},
 		tenantId,
 		userId,
 		createdAt: now,
 		updatedAt: now,
-		messages: []
+		messages: [],
+		memory: {
+			ingestEpoch: await nextIngestEpoch(),
+			lastIngestedIndex: -1
+		}
 	};
 	await saveSession(session);
 	cleanupOldSessions();
 	return session;
 }
 const writeLocks = /* @__PURE__ */ new Map();
+/** Run `fn` under the per-session write lock and return its result. */
+async function withSessionLock(sessionId, fn) {
+	const prev = writeLocks.get(sessionId) ?? Promise.resolve();
+	let result;
+	const next = prev.catch(() => void 0).then(async () => {
+		result = await fn();
+	}).finally(() => {
+		if (writeLocks.get(sessionId) === next) writeLocks.delete(sessionId);
+	});
+	writeLocks.set(sessionId, next);
+	await next;
+	return result;
+}
+/**
+* Append a message. Returns its index (position in `messages`), the stable
+* memory-ingest index, or -1 when the session does not exist.
+*/
 async function addMessage(sessionId, role, content, senderId, senderName, components, attachments) {
-	const next = (writeLocks.get(sessionId) ?? Promise.resolve()).then(async () => {
+	return appendMessage(sessionId, {
+		role,
+		content,
+		...senderId ? { senderId } : {},
+		...senderName ? { senderName } : {},
+		...components?.length ? { components } : {},
+		...attachments?.length ? { attachments } : {}
+	});
+}
+/**
+* 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.
+*/
+async function addErrorMessage(sessionId, content) {
+	return appendMessage(sessionId, {
+		role: "assistant",
+		content,
+		kind: "error"
+	});
+}
+async function appendMessage(sessionId, message) {
+	return withSessionLock(sessionId, async () => {
 		const session = await getSession(sessionId);
-		if (!session) return;
+		if (!session) return -1;
+		const last = session.messages.at(-1)?.timestamp ?? 0;
 		session.messages.push({
-			role,
-			content,
-			timestamp: Date.now(),
-			...senderId ? { senderId } : {},
-			...senderName ? { senderName } : {},
-			...components?.length ? { components } : {},
-			...attachments?.length ? { attachments } : {}
+			...message,
+			timestamp: Math.max(Date.now(), last + 1)
 		});
 		await saveSession(session);
-	}).finally(() => {
-		if (writeLocks.get(sessionId) === next) writeLocks.delete(sessionId);
+		return session.messages.length - 1;
+	});
+}
+const MAX_MEMORY_MESSAGE_BYTES = 6e4;
+/** Allowance per message for role/index/JSON structure. */
+const MEMORY_MESSAGE_OVERHEAD_BYTES = 64;
+function serialisedBytes(text) {
+	return Buffer.byteLength(JSON.stringify(text), "utf8");
+}
+/**
+* Longest prefix of `text` whose JSON-serialised UTF-8 size is at most
+* `maxBytes`, never splitting a surrogate pair.
+*/
+function capSerialisedBytes(text, maxBytes) {
+	if (serialisedBytes(text) <= maxBytes) return text;
+	let lo = 0;
+	let hi = text.length;
+	while (lo < hi) {
+		const mid = Math.ceil((lo + hi) / 2);
+		if (serialisedBytes(text.slice(0, mid)) <= maxBytes) lo = mid;
+		else hi = mid - 1;
+	}
+	let end = lo;
+	const last = text.charCodeAt(end - 1);
+	if (end > 0 && last >= 55296 && last <= 56319) end -= 1;
+	return text.slice(0, end);
+}
+let epochChain = Promise.resolve();
+function epochStatePath() {
+	return join(sessionsDir(), ".ingest-epoch");
+}
+async function readLastEpoch() {
+	try {
+		const parsed = JSON.parse(await readFile(epochStatePath(), "utf-8"));
+		const epoch = parsed && typeof parsed === "object" ? parsed.epoch : void 0;
+		return Number.isSafeInteger(epoch) && epoch >= 0 ? epoch : 0;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Next conversation-lineage epoch: `max(Date.now(), lastIssued + 1)`, persisted
+* (same guard as openclaw-memory-cloud's `ingest-epoch.ts`). The memory service
+* treats an OLDER epoch than the one it stored as stale and drops the batch, so
+* a clock that stepped backwards must never produce a smaller epoch.
+*/
+async function nextIngestEpoch() {
+	const run = async () => {
+		await ensureDir();
+		const epoch = Math.max(Date.now(), await readLastEpoch() + 1);
+		await writeTextAtomically(epochStatePath(), `${JSON.stringify({ epoch })}\n`);
+		return epoch;
+	};
+	const result = epochChain.then(run, run);
+	epochChain = result.catch(() => void 0);
+	return result;
+}
+/**
+* Cursor for a session written before the cursor existed. The old host
+* ingested every turn as indices 0 and 1, so the service stored exactly the
+* messages at positions 0/1 (when the session had them) and dropped the rest.
+* Start at 2 so the dropped backlog is backfilled through the batch bound.
+*/
+async function initialCursor(session) {
+	return {
+		ingestEpoch: await nextIngestEpoch(),
+		lastIngestedIndex: session.messages.length >= 2 ? 1 : -1
+	};
+}
+/**
+* Give a pre-cursor session its cursor. Call BEFORE appending the turn's user
+* message, so a turn that then fails still leaves that message pending.
+* No-op for a session that already has one (or does not exist).
+*/
+async function ensureMemoryCursor(sessionId) {
+	await withSessionLock(sessionId, async () => {
+		const session = await getSession(sessionId);
+		if (!session || session.memory) return;
+		session.memory = await initialCursor(session);
+		await saveSession(session);
+	});
+}
+/**
+* The messages not yet accepted by the memory service, oldest first, bounded
+* by count and serialised bytes (always at least one message when any is
+* pending). Error replies (history only) and whitespace-only messages (the
+* service rejects empty content) are skipped but still covered: `throughIndex` is the last index this batch
+* accounts for, sent or skipped. Leftovers go out with the next turn's batch.
+*/
+async function pendingMemoryBatch(sessionId, opts = {}) {
+	const maxMessages = opts.maxMessages ?? 20;
+	const maxBytes = opts.maxBytes ?? 2e5;
+	return withSessionLock(sessionId, async () => {
+		const session = await getSession(sessionId);
+		if (!session) return null;
+		if (!session.memory) {
+			session.memory = await initialCursor(session);
+			await saveSession(session);
+		}
+		const messages = [];
+		let throughIndex = session.memory.lastIngestedIndex;
+		let bytes = 0;
+		for (let index = session.memory.lastIngestedIndex + 1; index < session.messages.length && messages.length < maxMessages; index += 1) {
+			const message = session.messages[index];
+			if (message.kind === "error" || message.content.trim() === "") {
+				throughIndex = index;
+				continue;
+			}
+			const content = capSerialisedBytes(message.content, MAX_MEMORY_MESSAGE_BYTES);
+			const size = serialisedBytes(content) + MEMORY_MESSAGE_OVERHEAD_BYTES;
+			if (messages.length > 0 && bytes + size > maxBytes) break;
+			bytes += size;
+			messages.push({
+				role: message.role,
+				content,
+				index
+			});
+			throughIndex = index;
+		}
+		return {
+			ingestEpoch: session.memory.ingestEpoch,
+			messages,
+			throughIndex
+		};
+	});
+}
+/**
+* Record that the memory service has dealt with messages up to `lastIndex`.
+* Ignored unless it moves the cursor forward within the same epoch, so a late
+* or duplicate acknowledgement can never move it back.
+*/
+async function markMemoryIngested(sessionId, ingestEpoch, lastIndex) {
+	await withSessionLock(sessionId, async () => {
+		const session = await getSession(sessionId);
+		const cursor = session?.memory;
+		if (!session || cursor?.ingestEpoch !== ingestEpoch || lastIndex <= cursor.lastIngestedIndex || lastIndex >= session.messages.length) return;
+		cursor.lastIngestedIndex = lastIndex;
+		await saveSession(session);
 	});
-	writeLocks.set(sessionId, next);
-	await next;
 }
 const MAX_ACTIVITY_PER_SESSION = 500;
 const MAX_ACTIVITY_THINKING_CHARS = 16e3;
@@ -815,7 +1516,7 @@ const MAX_ACTIVITY_THINKING_CHARS = 16e3;
 */
 async function appendActivity(sessionId, entries) {
 	if (entries.length === 0) return;
-	const next = (writeLocks.get(sessionId) ?? Promise.resolve()).then(async () => {
+	await withSessionLock(sessionId, async () => {
 		const session = await getSession(sessionId);
 		if (!session) return;
 		const capped = entries.map((e) => e.kind === "thinking" && e.text.length > MAX_ACTIVITY_THINKING_CHARS ? {
@@ -825,11 +1526,7 @@ async function appendActivity(sessionId, entries) {
 		const combined = [...session.activity ?? [], ...capped];
 		session.activity = combined.length > MAX_ACTIVITY_PER_SESSION ? combined.slice(combined.length - MAX_ACTIVITY_PER_SESSION) : combined;
 		await saveSession(session);
-	}).finally(() => {
-		if (writeLocks.get(sessionId) === next) writeLocks.delete(sessionId);
 	});
-	writeLocks.set(sessionId, next);
-	await next;
 }
 async function listSessions(filters, limit = 50) {
 	await ensureDir();
@@ -871,16 +1568,207 @@ async function listSessions(filters, limit = 50) {
 	return summaries.slice(0, boundedLimit);
 }
 //#endregion
+//#region src/persona.ts
+/**
+* Host-owned `CLAUDE.md` — the persona Claude Code auto-loads from its cwd.
+*
+* The agent's persona lives in the workspace persona files (IDENTITY.md,
+* SOUL.md, AGENTS.md, USER.md, BOOTSTRAP.md). `alfe setup` seeds them from the
+* agent's template (seed-if-missing, agent-owned — the same semantics OpenClaw
+* uses), and the agent may edit them itself. OpenClaw reads those files live
+* every turn; Claude Code only reads `CLAUDE.md`. So the host regenerates
+* `CLAUDE.md` from them on start and before every turn, which keeps it as
+* current as OpenClaw's view of the same files.
+*
+* File layout:
+*
+*   <!-- alfe:managed:start -->
+*   <!-- Managed by Alfe. ... -->
+*
+*   <persona sections>
+*   <!-- alfe:managed:end. Add your own notes below this line; Alfe keeps them. -->
+*   <user notes, kept verbatim>
+*
+* Everything above the end marker is overwritten. Everything after it is
+* preserved, so self-hosted users can add local notes.
+*/
+/** Persona files, in the order they appear in `CLAUDE.md`. */
+const PERSONA_FILES = [
+	"IDENTITY.md",
+	"SOUL.md",
+	"AGENTS.md",
+	"USER.md",
+	"BOOTSTRAP.md"
+];
+/**
+* Start-line prefix. The full line records the sha256 of the managed region
+* the host last wrote (`<!-- alfe:managed:start sha256=<hex> -->`), so a hand
+* edit above the end marker is detected and backed up before it is replaced.
+*/
+const MANAGED_START = "<!-- alfe:managed:start";
+const MANAGED_END = "<!-- alfe:managed:end. Add your own notes below this line; Alfe keeps them. -->";
+const MANAGED_NOTICE = "<!-- Managed by Alfe. Regenerated from IDENTITY.md, SOUL.md, AGENTS.md, USER.md and BOOTSTRAP.md in this folder; edit those files instead. Everything above alfe:managed:end is overwritten. -->";
+/** Matches the end marker even if a future version changes its trailing text. */
+const END_PREFIX = "<!-- alfe:managed:end";
+/** Separator between persona sections (also what the old CLI seed used). */
+const SECTION_SEPARATOR = "\n\n---\n\n";
+/**
+* Claude Code loads `CLAUDE.md` into every turn's context, so the persona is
+* capped per file and in total. Truncation is stated in the file itself.
+*/
+const MAX_PERSONA_FILE_CHARS = 2e4;
+const MAX_PERSONA_TOTAL_CHARS = 6e4;
+function truncate(text, max, note) {
+	if (text.length <= max) return text;
+	let end = max;
+	const last = text.charCodeAt(end - 1);
+	if (last >= 55296 && last <= 56319) end -= 1;
+	return `${text.slice(0, end)}\n\n[Truncated by Alfe: ${note}; the rest is not loaded.]`;
+}
+/**
+* Join the present persona files (stable order, trimmed, blanks skipped),
+* capped per file and in total. Returns undefined when there is no persona
+* content.
+*/
+function composePersonaBody(files) {
+	const sections = [];
+	for (const name of PERSONA_FILES) {
+		const content = files[name]?.trim();
+		if (content) sections.push(truncate(content, MAX_PERSONA_FILE_CHARS, `${name} is longer than ${String(MAX_PERSONA_FILE_CHARS)} characters`));
+	}
+	if (sections.length === 0) return void 0;
+	return truncate(sections.join(SECTION_SEPARATOR), MAX_PERSONA_TOTAL_CHARS, `the persona is longer than ${String(MAX_PERSONA_TOTAL_CHARS)} characters`);
+}
+function sha256(text) {
+	return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+* Render the next `CLAUDE.md` from the persona body and the current file.
+* Returns undefined when nothing should be written: there is no persona and
+* the existing file (if any) is not Alfe-managed.
+*/
+function renderClaudeMd(body, existing) {
+	const endAt = existing === void 0 ? -1 : existing.indexOf(END_PREFIX);
+	let notes = "";
+	if (existing !== void 0 && endAt >= 0) {
+		const lineEnd = existing.indexOf("\n", endAt);
+		notes = lineEnd < 0 ? "" : existing.slice(lineEnd + 1);
+	} else if (existing !== void 0 && existing.trim() !== "" && existing.trim() !== body) notes = existing.endsWith("\n") ? existing : `${existing}\n`;
+	if (body === void 0 && endAt < 0) return void 0;
+	const region = `${MANAGED_NOTICE}\n\n${body ? `${body}\n` : ""}`;
+	return `${MANAGED_START} sha256=${sha256(region)} -->\n${region}${MANAGED_END}\n${notes}`;
+}
+/**
+* True when the managed region of a host-written file no longer matches the
+* hash the host recorded, i.e. someone edited above the end marker. Files
+* without a recorded hash are treated as unedited.
+*/
+function managedRegionEdited(existing) {
+	const firstLineEnd = existing.indexOf("\n");
+	const endAt = existing.indexOf(END_PREFIX);
+	if (firstLineEnd < 0 || endAt < firstLineEnd) return false;
+	const recorded = /^<!-- alfe:managed:start sha256=([0-9a-f]{64}) -->$/u.exec(existing.slice(0, firstLineEnd))?.[1];
+	if (!recorded) return false;
+	return sha256(existing.slice(firstLineEnd + 1, endAt)) !== recorded;
+}
+/**
+* True for an unmarked `CLAUDE.md` in the format the CLI used to seed:
+* persona sections joined by `---`, whose first section is still the content
+* of a current persona file. Such a file is a stale persona snapshot (often
+* including BOOTSTRAP.md), not user notes.
+*/
+function isLegacyComposedClaudeMd(existing, files) {
+	if (existing.includes(END_PREFIX)) return false;
+	const first = existing.split(SECTION_SEPARATOR)[0]?.trim();
+	if (!first) return false;
+	return PERSONA_FILES.some((name) => files[name]?.trim() === first);
+}
+async function readOptional(path) {
+	try {
+		return await readFile(path, "utf-8");
+	} catch (err) {
+		if (err.code === "ENOENT") return void 0;
+		throw err;
+	}
+}
+function timestamp() {
+	return `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/gu, "-")}-${randomUUID().slice(0, 8)}`;
+}
+/**
+* Regenerate `<workspace>/CLAUDE.md` from the workspace persona files. Creates
+* the workspace directory if missing (it is `claude`'s cwd). Skips the write
+* when the content is unchanged. Returns true when it wrote.
+*
+* Before overwriting it preserves anything that is not a plain host-written
+* file: an old CLI-composed persona snapshot is moved to `CLAUDE.md.pre-alfe`,
+* and a managed region edited by hand is copied to
+* `CLAUDE.md.edited-<timestamp>.bak`. Both are logged.
+*/
+async function syncClaudeMd(workspace, log) {
+	await mkdir(workspace, { recursive: true });
+	const files = {};
+	for (const name of PERSONA_FILES) {
+		const text = await readOptional(join(workspace, name));
+		if (text !== void 0) files[name] = text;
+	}
+	const body = composePersonaBody(files);
+	const target = join(workspace, "CLAUDE.md");
+	let existing = await readOptional(target);
+	if (existing !== void 0 && existing.trim() !== body && isLegacyComposedClaudeMd(existing, files)) {
+		const aside = existsSync(`${target}.pre-alfe`) ? `${target}.pre-alfe-${timestamp()}` : `${target}.pre-alfe`;
+		await rename(target, aside);
+		log?.warn(`[claude-host] moved an old setup-generated CLAUDE.md to ${aside}; the persona is now regenerated from the persona files`);
+		existing = void 0;
+	}
+	const next = renderClaudeMd(body, existing);
+	if (next === void 0 || next === existing) return false;
+	if (existing !== void 0 && managedRegionEdited(existing)) {
+		const backup = `${target}.edited-${timestamp()}.bak`;
+		await writeTextAtomically(backup, existing);
+		log?.warn(`[claude-host] CLAUDE.md was edited above the alfe:managed:end marker; saved a copy to ${backup} before regenerating. Edit the persona files or add notes below the marker instead.`);
+	}
+	await writeTextAtomically(target, next);
+	return true;
+}
+//#endregion
+//#region src/memory-recall.ts
+/**
+* Memory recall helpers. Mirrors `packages/openclaw-memory-cloud/src/auto-recall.ts`
+* so a claude-code agent recalls the same way an OpenClaw agent does: tier 1
+* (facts) always, plus tier 2 (topic context) when the message names a topic.
+* Copied rather than imported: the host must not depend on an OpenClaw plugin
+* package. Keep the two in step.
+*/
+const STOP_WORDS = /^(The|And|But|For|With|This|That|What|How|Why|When|Where)$/;
+/**
+* Topic hint = the first capitalised word (a likely proper noun) after the
+* first word, longer than two characters and not a stop word, lower-cased.
+*/
+function extractTopicHint(message) {
+	const words = message.split(/\s+/);
+	for (let i = 1; i < words.length; i++) {
+		const word = words[i];
+		if (word && word.length > 2 && /^[A-Z]/.test(word) && !STOP_WORDS.test(word)) return word.toLowerCase();
+	}
+}
+/** Tier 2 (facts + topic context) needs a topic; otherwise tier 1 (facts). */
+function recallTier(topicHint) {
+	return topicHint ? 2 : 1;
+}
+/** Recall is best-effort and must not hold up a turn. Matches auto-recall. */
+const RECALL_TIMEOUT_MS = 5e3;
+//#endregion
 //#region src/host.ts
 /**
-* ClaudeCodeHost — the persistent chat bridge for a self-hosted Claude Code
-* agent.
+* ClaudeCodeHost — the persistent chat bridge for a Claude Code agent
+* (self-hosted or managed).
 *
 * It holds ONE `ChatServiceClient` (reused verbatim from `@alfe.ai/chat`, with
 * NO custom reconnect — the client already backs off with jitter and guards
 * against orphan sockets), registers the inbound RPC handlers the chat service
-* calls, and drives the `SessionDriver` to run `claude -p` turns on the user's
-* subscription.
+* calls, and drives the `SessionDriver` to run `claude -p` turns on one auth
+* source: the agent's stored credential, a self-hosted machine's own login, or
+* the Alfe AI proxy (see DEVELOPING.md "Auth source resolution").
 *
 * Every wire shape here is byte-for-byte the shape the `@alfe.ai/openclaw-chat`
 * plugin emits, so the chat service / adapter / UI treat a Claude Code turn
@@ -903,8 +1791,6 @@ const VOICE_REPLY_SYSTEM_PROMPT = [
 	"- If the full answer is long or detailed, give the short spoken version and offer to send the details to the chat.",
 	"This is guidance on speaking STYLE only. Do NOT skip tool calls you would otherwise make, and never omit information the user actually needs."
 ].join("\n");
-/** Cross-agent tool steering (every turn). Mirrors CROSS_AGENT_TOOLS_SYSTEM_PROMPT. */
-const CROSS_AGENT_TOOLS_SYSTEM_PROMPT = ["Cross-agent messaging: to contact another Alfe agent (IDs like agt_…), use list_agents to discover and message_agent to send.", "The runtime's built-in session tools do NOT know Alfe agent IDs and will fail — never use them to reach another agent."].join("\n");
 /**
 * Short, AUTHORITATIVE persona pointer for `--append-system-prompt`. The full
 * persona (SOUL/IDENTITY/AGENTS/…) is delivered as the workspace `CLAUDE.md`,
@@ -919,6 +1805,29 @@ const PERSONA_POINTER_SYSTEM_PROMPT = [
 	"Your identity, persona, voice, and operating instructions live in CLAUDE.md and the other files in your workspace.",
 	"Fully embody that persona in how you speak and act; respond AS that agent, not as a generic coding assistant."
 ].join("\n");
+const CREDENTIAL_INVALID_MESSAGE = "This agent's Claude credential is invalid or expired. Update it in agent settings.";
+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.";
+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.";
+const LOCAL_LOGIN_SWITCHED_MESSAGE = "Your machine's Claude login stopped working, so this agent switched to Alfe credits. Please resend your message.";
+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.";
+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.";
+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.";
+const CREDENTIAL_UNAVAILABLE_MESSAGE = "This agent's Claude credential couldn't be loaded yet. Try again in a moment.";
+/** Fixed status details (never `claude` output). */
+const SOURCE_OK_DETAIL = {
+	local_login: "Using this machine's claude login",
+	ai_proxy: "Using Alfe AI credits"
+};
+const DENIAL_DETAIL = {
+	credits: "Using Alfe AI credits. This workspace is out of credits.",
+	usage_limit: "Using Alfe AI credits. An Alfe usage limit has been reached.",
+	model_unavailable: "Using Alfe AI credits. The agent's model is not available on this workspace."
+};
+const DENIAL_MESSAGE = {
+	credits: OUT_OF_CREDITS_MESSAGE,
+	usage_limit: USAGE_LIMIT_MESSAGE,
+	model_unavailable: MODEL_UNAVAILABLE_MESSAGE
+};
 const MAX_AGENT_MESSAGE_BYTES = 256 * 1024;
 const MAX_SESSION_KEY_CHARS = 768;
 const MAX_IDENTIFIER_CHARS = 512;
@@ -1130,18 +2039,58 @@ var ClaudeCodeHost = class {
 	claudeSessionSave = Promise.resolve();
 	stopping = false;
 	stopPromise = null;
+	/**
+	* Resolves once the first fetch has answered. Null until `start()` (the
+	* direct handleRequest test seam runs on the local login, no wait).
+	*/
+	credentialReady = null;
+	resolveCredentialReady = () => void 0;
+	/** Turns wait for the first fetch only until this time (start + wait). */
+	credentialDeadline = 0;
+	credentialLoaded = false;
+	/** Turns waiting for the credential, before queue admission (chat.abort). */
+	waitingTurns = /* @__PURE__ */ new Map();
+	loaderRestartMs;
+	/** How often a fallen-back self-hosted agent re-checks its local login. */
+	localLoginRecheckMs;
+	localLoginRecheck = null;
+	/** In memory only. Never logged, never persisted. */
+	credential = null;
+	/**
+	* The auth every new turn runs on, resolved once the credential fetch
+	* answers (see `resolveAuthSource`). Null before that.
+	*/
+	authSource = null;
+	credentialAbort = new AbortController();
+	reporter;
+	probe;
+	credentialWaitMs;
+	credentialRetry;
 	constructor(cfg, deps) {
 		this.cfg = cfg;
 		this.log = cfg.logger ?? console;
 		this.claudeSessionsPath = cfg.claudeSessionsPath ?? join(homedir(), ".alfe", "claude-code", "sessions.json");
-		this.makeDriver = deps?.makeDriver ?? (() => new SessionDriver({
+		this.makeDriver = deps?.makeDriver ?? ((auth) => new SessionDriver({
 			logger: this.log,
-			baseEnv: process.env
+			baseEnv: process.env,
+			auth,
+			managed: cfg.managed === true
 		}));
 		this.api = deps?.api ?? new AgentApiClient({
 			apiKey: cfg.apiKey,
 			apiUrl: cfg.apiUrl
 		});
+		this.probe = deps?.probe ?? ((auth, signal) => runAuthProbe({
+			auth,
+			baseEnv: process.env,
+			cwd: tmpdir(),
+			signal
+		}));
+		this.credentialWaitMs = deps?.credentialWaitMs ?? 15e3;
+		this.loaderRestartMs = deps?.loaderRestartMs ?? 5e3;
+		this.credentialRetry = deps?.credentialRetry ?? {};
+		this.localLoginRecheckMs = deps?.localLoginRecheckMs ?? 9e5;
+		this.reporter = new CredentialStatusReporter((report) => this.api.reportClaudeCredentialStatus(report), { log: this.log });
 		this.chat = deps?.chat ?? new ChatServiceClient({
 			wsUrl: cfg.wsUrl,
 			apiKey: cfg.apiKey,
@@ -1158,12 +2107,208 @@ var ClaudeCodeHost = class {
 	async start() {
 		if (this.stopping) throw new Error("Claude Code host is stopping");
 		await this.loadClaudeSessionIds();
+		await this.syncPersona();
+		this.credentialReady = new Promise((resolve) => {
+			this.resolveCredentialReady = resolve;
+		});
+		this.credentialDeadline = Date.now() + this.credentialWaitMs;
+		this.runCredentialLoader();
 		this.chat.start();
 	}
+	/**
+	* 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.
+	*/
+	runCredentialLoader() {
+		this.loadCredential().catch((err) => {
+			if (this.stopping) return;
+			this.log.error(`[claude-host] credential load failed unexpectedly (${err instanceof Error ? err.message : String(err)}); restarting it`);
+			setTimeout(() => {
+				if (!this.stopping) this.runCredentialLoader();
+			}, this.loaderRestartMs).unref();
+		});
+	}
+	async loadCredential() {
+		const loaded = await loadCredentialWithRetry(async () => {
+			const credential = await this.api.getClaudeCredential();
+			return credential ? {
+				kind: credential.kind,
+				value: credential.value,
+				revision: credential.revision
+			} : null;
+		}, {
+			signal: this.credentialAbort.signal,
+			log: this.log,
+			...this.credentialRetry
+		});
+		if (!loaded) return;
+		this.credential = loaded.credential;
+		this.authSource = loaded.credential ? "credential" : this.cfg.managed ? "ai_proxy" : "local_login";
+		this.credentialLoaded = true;
+		this.resolveCredentialReady();
+		await this.checkCredential();
+	}
+	/**
+	* A method, not a property read: `stopping` flips across awaits, which
+	* control-flow narrowing cannot see.
+	*/
+	isStopping() {
+		return this.stopping;
+	}
+	/** Same reason as `isStopping`: `authSource` can change across an await. */
+	currentAuthSource() {
+		return this.authSource;
+	}
+	/** The auth a new turn runs on. Local login until the fetch has answered. */
+	childAuth() {
+		if (this.authSource === "credential" && this.credential) return {
+			mode: "credential",
+			credential: {
+				kind: this.credential.kind,
+				value: this.credential.value
+			}
+		};
+		if (this.authSource === "ai_proxy") return {
+			mode: "ai_proxy",
+			baseUrl: this.cfg.localAiProxyUrl ?? "http://127.0.0.1:18193",
+			model: this.cfg.model ?? "claude-haiku-4-5"
+		};
+		return { mode: "local_login" };
+	}
+	/**
+	* 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.
+	*/
+	fallBackToProxy(why) {
+		if (this.authSource !== "local_login") return;
+		this.log.warn(`[claude-host] the claude login on this machine was refused (${why}); using the Alfe AI proxy`);
+		this.authSource = "ai_proxy";
+		this.scheduleLocalLoginRecheck();
+	}
+	scheduleLocalLoginRecheck() {
+		if (this.localLoginRecheck || this.stopping) return;
+		this.localLoginRecheck = setTimeout(() => {
+			this.localLoginRecheck = null;
+			this.recheckLocalLogin();
+		}, this.localLoginRecheckMs);
+		this.localLoginRecheck.unref();
+	}
+	/** While fallen back: one local-login probe; back to the login when it works. */
+	async recheckLocalLogin() {
+		if (this.isStopping() || this.authSource !== "ai_proxy" || this.credential || this.cfg.managed) return;
+		let outcome;
+		try {
+			outcome = await this.probe({ mode: "local_login" }, this.credentialAbort.signal);
+		} catch (err) {
+			outcome = {
+				result: "unknown",
+				reason: err instanceof Error ? err.message : String(err)
+			};
+		}
+		if (this.isStopping() || this.currentAuthSource() !== "ai_proxy") return;
+		if (outcome.result === "ok") {
+			this.log.info("[claude-host] the claude login on this machine works again; leaving the Alfe AI proxy");
+			this.authSource = "local_login";
+			await this.reportStatus("ok");
+			return;
+		}
+		this.scheduleLocalLoginRecheck();
+	}
+	/**
+	* 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.
+	*/
+	async checkCredential() {
+		let outcome = await this.probe(this.childAuth(), this.credentialAbort.signal);
+		if (this.stopping) return;
+		if (outcome.result === "invalid" && !outcome.forbidden && this.authSource === "local_login") {
+			this.fallBackToProxy("start-up check");
+			outcome = await this.probe(this.childAuth(), this.credentialAbort.signal);
+			if (this.isStopping()) return;
+		}
+		switch (outcome.result) {
+			case "unknown":
+				this.log.warn(`[claude-host] Claude auth check inconclusive (${outcome.reason}); the next turn will tell`);
+				return;
+			case "denied":
+				if (outcome.denial === "model_unavailable") {
+					this.log.warn("[claude-host] the probe model is unavailable through the Alfe AI proxy; the next turn will tell");
+					return;
+				}
+				await this.reportStatus("ok", DENIAL_DETAIL[outcome.denial]);
+				return;
+			default: await this.reportStatus(outcome.result);
+		}
+	}
+	/** Report the current auth source as working or refused. */
+	async reportStatus(status, detail) {
+		const source = this.authSource;
+		if (!this.credentialLoaded || !source) return;
+		const revision = source === "credential" ? this.credential?.revision : void 0;
+		const fixedDetail = detail ?? (status === "ok" ? source === "credential" ? void 0 : SOURCE_OK_DETAIL[source] : source === "credential" ? "Anthropic rejected the stored credential" : source === "ai_proxy" ? "The Alfe AI proxy rejected this agent's key" : "The claude login on this machine is not signed in");
+		await this.reporter.report({
+			status,
+			source,
+			...fixedDetail ? { detail: fixedDetail } : {},
+			...revision ? { revision } : {}
+		});
+	}
+	/**
+	* 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`.
+	*/
+	async awaitCredential(cancellation) {
+		if (!this.credentialReady || this.credentialLoaded) return "ready";
+		const remaining = this.credentialDeadline - Date.now();
+		if (remaining <= 0) return "timeout";
+		let timer;
+		let onAbort;
+		try {
+			return await Promise.race([
+				this.credentialReady.then(() => "ready"),
+				new Promise((resolve) => {
+					timer = setTimeout(() => {
+						resolve("timeout");
+					}, remaining);
+				}),
+				new Promise((resolve) => {
+					onAbort = () => {
+						resolve("aborted");
+					};
+					if (cancellation.aborted) onAbort();
+					else cancellation.addEventListener("abort", onAbort, { once: true });
+				})
+			]);
+		} finally {
+			if (timer) clearTimeout(timer);
+			if (onAbort) cancellation.removeEventListener("abort", onAbort);
+		}
+	}
+	/**
+	* 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.
+	*/
+	credentialGateMessage() {
+		if (!this.credentialReady) return null;
+		if (!this.credentialLoaded) return CREDENTIAL_UNAVAILABLE_MESSAGE;
+		return null;
+	}
 	/** Stop admission, abort owned children, and give active turns time to settle. */
 	stop() {
 		if (this.stopPromise) return this.stopPromise;
 		this.stopping = true;
+		this.credentialAbort.abort();
+		if (this.localLoginRecheck) {
+			clearTimeout(this.localLoginRecheck);
+			this.localLoginRecheck = null;
+		}
+		for (const waiting of this.waitingTurns.values()) for (const turn of waiting) turn.cancellation.abort();
 		this.queues.stop();
 		for (const { driver, cancellation } of this.runningTurns.values()) {
 			cancellation.abort();
@@ -1252,6 +2397,29 @@ var ClaudeCodeHost = class {
 			resolveCompletion(outcome);
 			if (idem) this.pruneIdempotency();
 		};
+		if (this.credentialReady && !this.credentialLoaded) {
+			const waiting = {
+				runId: params.idempotencyKey ?? req.id,
+				cancellation: new AbortController()
+			};
+			const set = this.waitingTurns.get(sessionKey) ?? /* @__PURE__ */ new Set();
+			set.add(waiting);
+			this.waitingTurns.set(sessionKey, set);
+			let outcome;
+			try {
+				outcome = await this.awaitCredential(waiting.cancellation.signal);
+			} finally {
+				set.delete(waiting);
+				if (set.size === 0) this.waitingTurns.delete(sessionKey);
+			}
+			if (outcome === "aborted") {
+				complete({
+					ok: true,
+					payload: { sessionKey }
+				});
+				return;
+			}
+		}
 		const coalesceKey = params.coalesce === "replace" ? sessionKey : void 0;
 		try {
 			await this.queues.enqueue(sessionKey, () => this.runAgentTurn(req, params, complete), coalesceKey ? {
@@ -1285,36 +2453,55 @@ var ClaudeCodeHost = class {
 		const runId = params.idempotencyKey ?? req.id;
 		const isVoice = params.origin === "voice";
 		await this.ensureSession(bareSessionId, params);
+		await ensureMemoryCursor(bareSessionId);
 		await addMessage(bareSessionId, "user", params.message, params.identityId ?? params.userId, params.displayName);
+		const credentialProblem = this.credentialGateMessage();
+		if (credentialProblem) {
+			await this.failTurn(bareSessionId, complete, credentialProblem);
+			return;
+		}
 		let memoryContext = "";
 		try {
-			memoryContext = (await this.api.memoryLoadContext()).formatted.slice(0, MAX_MEMORY_CONTEXT_CHARS);
+			const topicHint = extractTopicHint(params.message);
+			memoryContext = (await withTimeout(this.api.memoryLoadContext(recallTier(topicHint), topicHint), RECALL_TIMEOUT_MS)).formatted.slice(0, MAX_MEMORY_CONTEXT_CHARS);
 		} catch (err) {
 			this.log.warn(`[claude-host] memoryLoadContext failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
 		}
 		if (this.stopping) throw new Error("Claude Code host is stopping");
+		await this.syncPersona();
+		const mcpConfigPath = this.cfg.mcpConfigPath && existsSync(this.cfg.mcpConfigPath) ? this.cfg.mcpConfigPath : void 0;
 		const appendSystemPrompt = this.buildSystemPrompt(memoryContext, isVoice);
 		const claudeSessionId = this.claudeSessionIds.get(bareSessionId) ?? null;
-		const driver = this.makeDriver();
 		const cancellation = new AbortController();
-		this.runningTurns.set(sessionKey, {
-			runId,
-			driver,
-			cancellation
-		});
+		let auth = this.childAuth();
+		let switchedWithoutRerun = false;
 		let result;
 		try {
-			result = await this.runWithResumeFallback(driver, bareSessionId, cancellation.signal, {
+			result = await this.runTurnOn(auth, sessionKey, runId, cancellation, bareSessionId, {
 				prompt: params.message,
 				claudeSessionId,
 				cwd: this.cfg.workspace,
-				...this.cfg.mcpConfigPath ? { mcpConfigPath: this.cfg.mcpConfigPath } : {},
+				...mcpConfigPath ? { mcpConfigPath } : {},
 				...appendSystemPrompt ? { appendSystemPrompt } : {},
-				...this.cfg.model ? { model: this.cfg.model } : {},
 				onEmission: (emission) => {
 					this.forwardEmission(runId, sessionKey, emission);
 				}
 			}, isVoice);
+			if (auth.mode === "local_login" && result.isError && result.authFailed && !result.authForbidden && !result.aborted && !cancellation.signal.aborted && !this.isStopping()) {
+				this.fallBackToProxy("turn refused");
+				if (producedVisibleOutput(result.emissions)) switchedWithoutRerun = true;
+				else auth = this.childAuth();
+				if (!switchedWithoutRerun && auth.mode === "ai_proxy") result = await this.runTurnOn(auth, sessionKey, runId, cancellation, bareSessionId, {
+					prompt: params.message,
+					claudeSessionId,
+					cwd: this.cfg.workspace,
+					...mcpConfigPath ? { mcpConfigPath } : {},
+					...appendSystemPrompt ? { appendSystemPrompt } : {},
+					onEmission: (emission) => {
+						this.forwardEmission(runId, sessionKey, emission);
+					}
+				}, isVoice);
+			}
 		} finally {
 			this.runningTurns.delete(sessionKey);
 		}
@@ -1332,12 +2519,30 @@ var ClaudeCodeHost = class {
 			return;
 		}
 		if (result.isError) {
-			complete({
-				ok: false,
-				payload: { message: result.errorMessage ?? "Claude Code turn failed" }
-			});
+			const denial = auth.mode === "ai_proxy" ? classifyProxyDenial(result.errorMessage ?? "") : null;
+			if (denial) {
+				await this.failTurn(bareSessionId, complete, DENIAL_MESSAGE[denial]);
+				await this.reportStatus("ok", DENIAL_DETAIL[denial]);
+				return;
+			}
+			if (switchedWithoutRerun) {
+				await this.failTurn(bareSessionId, complete, LOCAL_LOGIN_SWITCHED_MESSAGE);
+				return;
+			}
+			if (result.authFailed && auth.mode === "local_login") {
+				await this.failTurn(bareSessionId, complete, result.authForbidden ? LOCAL_LOGIN_REFUSED_MESSAGE : CREDENTIAL_INVALID_MESSAGE);
+				await this.reportStatus("invalid");
+				return;
+			}
+			if (result.authFailed) {
+				await this.failTurn(bareSessionId, complete, auth.mode === "ai_proxy" ? PROXY_AUTH_FAILED_MESSAGE : CREDENTIAL_INVALID_MESSAGE);
+				await this.reportStatus("invalid");
+				return;
+			}
+			await this.failTurn(bareSessionId, complete, result.errorMessage ?? "Claude Code turn failed");
 			return;
 		}
+		this.reportStatus("ok");
 		if (result.finalText) await addMessage(bareSessionId, "assistant", result.finalText);
 		const notification = result.finalText ? {
 			conversationId: bareSessionId,
@@ -1350,28 +2555,101 @@ var ClaudeCodeHost = class {
 			payload: { sessionKey },
 			...notification ? { notification } : {}
 		});
+		await this.ingestPendingMemory(bareSessionId, params);
+	}
+	/**
+	* 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.
+	*/
+	async failTurn(bareSessionId, complete, message) {
 		try {
-			const messages = [{
-				role: "user",
-				content: params.message,
-				index: 0
-			}, ...result.finalText ? [{
-				role: "assistant",
-				content: result.finalText,
-				index: 1
-			}] : []];
-			await this.api.memoryIngest(bareSessionId, messages, {
-				...params.identityId ?? params.userId ? { userId: params.identityId ?? params.userId } : {},
+			await addErrorMessage(bareSessionId, message);
+		} catch (err) {
+			this.log.warn(`[claude-host] failed to store a turn error in history: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		complete({
+			ok: false,
+			payload: { message }
+		});
+	}
+	/**
+	* 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.
+	*/
+	async ingestPendingMemory(bareSessionId, params) {
+		let batch = null;
+		try {
+			batch = await pendingMemoryBatch(bareSessionId);
+			if (!batch) return;
+			if (batch.messages.length === 0) {
+				await markMemoryIngested(bareSessionId, batch.ingestEpoch, batch.throughIndex);
+				return;
+			}
+			const userId = params.identityId ?? params.userId;
+			const result = await this.api.memoryIngest(bareSessionId, batch.messages, {
+				...userId ? { userId } : {},
 				...params.displayName ? { userName: params.displayName } : {}
-			});
+			}, batch.ingestEpoch);
+			if (result.messageCount < batch.messages.length) this.log.warn(`[claude-host] memory service trimmed ${String(batch.messages.length - result.messageCount)} oldest message(s) from an ingest batch; they are not recoverable`);
+			await markMemoryIngested(bareSessionId, batch.ingestEpoch, batch.throughIndex);
+		} catch (err) {
+			const status = err?.status;
+			const message = err instanceof Error ? err.message : String(err);
+			if (batch && batch.messages.length > 0 && isPoisonIngestStatus(status)) {
+				const oldest = batch.messages[0];
+				this.log.warn(`[claude-host] memoryIngest rejected (${String(status)}); skipping message ${String(oldest.index)} so the conversation keeps capturing: ${message}`);
+				await markMemoryIngested(bareSessionId, batch.ingestEpoch, oldest.index).catch(() => void 0);
+				return;
+			}
+			this.log.warn(`[claude-host] memoryIngest failed (non-fatal, retried next turn): ${message}`);
+		}
+	}
+	/** Regenerate CLAUDE.md from the workspace persona files. Never fatal. */
+	async syncPersona() {
+		try {
+			if (await syncClaudeMd(this.cfg.workspace, this.log)) this.log.info("[claude-host] CLAUDE.md regenerated from persona files");
 		} catch (err) {
-			this.log.warn(`[claude-host] memoryIngest failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+			this.log.warn(`[claude-host] CLAUDE.md sync failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
 		}
 	}
 	/**
 	* 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.
+	*/
+	runTurnOn(auth, sessionKey, runId, cancellation, bareSessionId, baseParams, isVoice) {
+		const driver = this.makeDriver(auth);
+		this.runningTurns.set(sessionKey, {
+			runId,
+			driver,
+			cancellation
+		});
+		const model = auth.mode === "ai_proxy" ? auth.model : this.cfg.model;
+		return this.runWithResumeFallback(driver, bareSessionId, cancellation.signal, {
+			...baseParams,
+			...model ? { model } : {}
+		}, isVoice);
+	}
 	async runWithResumeFallback(driver, bareSessionId, cancellation, baseParams, isVoice) {
 		const cancelled = () => cancellation.aborted || this.stopping;
 		const aborted = (result) => ({
@@ -1440,6 +2718,11 @@ var ClaudeCodeHost = class {
 			active.driver.abort();
 			aborted = true;
 		}
+		const waiting = sessionKey ? this.waitingTurns.get(sessionKey) : void 0;
+		for (const turn of waiting ?? []) if (runId === void 0 || typeof runId === "string" && runId.length > 0 && runId.length <= 256 && turn.runId === runId) {
+			turn.cancellation.abort();
+			aborted = true;
+		}
 		this.chat.sendResponse(req.id, true, { aborted });
 	}
 	async handleSessionsList(req) {
@@ -1487,13 +2770,12 @@ var ClaudeCodeHost = class {
 		const parts = [PERSONA_POINTER_SYSTEM_PROMPT];
 		if (memoryContext) parts.push(`# Relevant memory\n\n${memoryContext}`);
 		if (isVoice) parts.push(VOICE_REPLY_SYSTEM_PROMPT);
-		parts.push(CROSS_AGENT_TOOLS_SYSTEM_PROMPT);
 		return parts.join("\n\n");
 	}
 	async buildHistoryPreamble(bareSessionId) {
 		const session = await getSession(bareSessionId);
 		if (!session || session.messages.length === 0) return "";
-		const prior = session.messages.slice(0, -1).slice(-10);
+		const prior = session.messages.slice(0, -1).filter((m) => m.kind !== "error").slice(-10);
 		if (prior.length === 0) return "";
 		return `Earlier in this conversation:\n${prior.map((m) => `${m.role === "assistant" ? "Assistant" : "User"}: ${m.content}`).join("\n")}`;
 	}
@@ -1503,7 +2785,7 @@ var ClaudeCodeHost = class {
 			if (params.tenantId && existing.tenantId && params.tenantId !== existing.tenantId || params.userId && existing.userId && params.userId !== existing.userId) throw new Error("Session ownership metadata mismatch");
 			return;
 		}
-		await createSession(bareSessionId, params.agentId, params.clientType ?? "chat", params.tenantId, params.userId);
+		await createSession(bareSessionId, params.agentId, CHAT_SESSION_CHANNEL, params.tenantId, params.userId, params.clientType);
 	}
 	async loadClaudeSessionIds() {
 		try {
@@ -1551,12 +2833,41 @@ var ClaudeCodeHost = class {
 		}
 	}
 };
+/**
+* Statuses where resending the same batch can never succeed. 429 and 5xx are
+* transient; 401/403 are credential problems that must not drop memories.
+*/
+function isPoisonIngestStatus(status) {
+	return status === 400 || status === 413 || status === 422;
+}
+/** Reject when `operation` outlives `timeoutMs` (the operation is not cancelled). */
+async function withTimeout(operation, timeoutMs) {
+	let timer;
+	const timeout = new Promise((_resolve, reject) => {
+		timer = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error("Memory recall timed out"));
+		}, timeoutMs);
+		timer.unref();
+	});
+	try {
+		return await Promise.race([operation, timeout]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
 /** Strip the `agent:{agentId}:` prefix from a full server session key. */
 function stripAgentPrefix(sessionKey) {
 	const parts = sessionKey.split(":");
 	if (parts.length >= 3 && parts[0] === "agent") return parts.slice(2).join(":");
 	return sessionKey;
 }
+/**
+* True when a turn already showed the user something (text or any activity
+* card). A refused turn that did is never re-run: its tools may have run.
+*/
+function producedVisibleOutput(emissions) {
+	return emissions.some((emission) => emission.type === "chat-activity" || emission.type === "chat-delta" && emission.text.trim().length > 0);
+}
 //#endregion
 //#region src/host-config.ts
 /**
@@ -1566,22 +2877,57 @@ function stripAgentPrefix(sessionKey) {
 * `main()` (which would start the process on import).
 */
 /**
-* Build the host config. Throws (→ non-zero exit from the CLI) when the chat
-* URL / api key can't resolve.
+* Pure builder (test seam). `home` is the claude-code runtime HOME
+* (`[runtimes.claude-code].workspace`, e.g. `~/.claude-code`), NOT the agent's
+* working directory and NOT `resolveConfig().workspacePath` (that follows the
+* ACTIVE runtime and is `~/.openclaw` on an env-only config). `claude` must run in the agent workspace
+* (`<home>/workspace`, where `CLAUDE.md` and the persona files live) so it
+* auto-loads the persona; the generated `--mcp-config` stays in the home where
+* `ClaudeCodeMcpSync` writes it.
 */
-function resolveHostConfig() {
-	const resolved = resolveConfig();
-	const chat = resolveAlfeChat({ apiKey: resolved.apiKey });
+function buildHostConfig(resolved, home, chat, env) {
 	if (!chat.apiKey || !chat.chatWsUrl) throw new Error("Unable to resolve chat service URL / API key from ~/.alfe/config.toml. Run `alfe login`.");
+	const model = env.ALFE_DEFAULT_MODEL?.trim();
+	const managedFlag = env.ALFE_MANAGED?.trim().toLowerCase();
+	const localAiProxyUrl = parseLoopbackUrl(env.ALFE_LOCAL_AI_PROXY_URL);
 	return {
 		wsUrl: chat.chatWsUrl,
 		apiKey: chat.apiKey,
 		apiUrl: resolved.apiUrl,
-		workspace: resolved.workspacePath,
-		mcpConfigPath: join(homedir(), ".claude-code", "mcp-config.json"),
+		workspace: resolveAgentWorkspace("claude-code", home),
+		mcpConfigPath: join(home, "mcp-config.json"),
 		claudeSessionsPath: join(homedir(), ".alfe", "claude-code", "sessions.json"),
-		...process.env.ALFE_DEFAULT_MODEL?.trim() ? { model: process.env.ALFE_DEFAULT_MODEL.trim() } : {}
+		...model ? { model } : {},
+		managed: managedFlag === "1" || managedFlag === "true",
+		...localAiProxyUrl ? { localAiProxyUrl } : {}
 	};
 }
+/**
+* The daemon's loopback AI proxy URL (`ALFE_LOCAL_AI_PROXY_URL`), as a bare
+* origin. Only plain-http loopback is accepted: the proxy-mode `claude` child
+* sends every model request there, so a stray value must never point it off
+* the machine. Anything else → undefined (the host default applies).
+*/
+function parseLoopbackUrl(raw) {
+	const value = raw?.trim();
+	if (!value) return void 0;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return;
+	}
+	if (url.protocol !== "http:") return void 0;
+	if (url.hostname !== "127.0.0.1" && url.hostname !== "localhost") return void 0;
+	return url.origin;
+}
+/**
+* Build the host config. Throws (→ non-zero exit from the CLI) when the chat
+* URL / api key can't resolve.
+*/
+function resolveHostConfig() {
+	const resolved = resolveConfig();
+	return buildHostConfig(resolved, resolveRuntimeHome("claude-code"), resolveAlfeChat({ apiKey: resolved.apiKey }), process.env);
+}
 //#endregion
-export { buildChildEnv as C, SCRUBBED_ANTHROPIC_ENV_VARS as S, collectTurnActivityRecords as _, appendActivity as a, mapStreamEvents as b, listSessions as c, DEFAULT_ALLOWED_TOOLS as d, DEFAULT_PERMISSION_MODE as f, WARM_STREAMING_SUPPORTED as g, TURN_TIMEOUT_MS as h, addMessage as i, saveSession as l, TERMINATION_GRACE_MS as m, ClaudeCodeHost as n, createSession as o, SessionDriver as p, stripAgentPrefix as r, getSession as s, resolveHostConfig as t, CLAUDE_PERMISSION_MODES as u, createMapperState as v, BRIDGE_ENV_VAR as x, mapStreamEvent as y };
+export { mapStreamEvents as A, BRIDGE_ENV_VAR as B, SessionDriver as C, collectTurnActivityRecords as D, WARM_STREAMING_SUPPORTED as E, classifyProxyDenial as F, PROXY_DEFAULT_MODEL as G, DEFAULT_LOCAL_AI_PROXY_URL as H, isAuthFailureText as I, buildChildEnv as J, PROXY_MODEL_ENV as K, loadCredentialWithRetry as L, CredentialStatusReporter as M, STATUS_REPORT_INTERVAL_MS as N, createMapperState as O, buildProbeArgs as P, parseProbeOutput as R, MANAGED_DISALLOWED_TOOLS as S, TURN_TIMEOUT_MS as T, PROXY_AGENT_MODEL_ENV_VARS as U, CREDENTIAL_ENV_VAR as V, PROXY_API_KEY_PLACEHOLDER as W, saveSession as _, LOCAL_LOGIN_REFUSED_MESSAGE as a, DEFAULT_PERMISSION_MODE as b, OUT_OF_CREDITS_MESSAGE as c, stripAgentPrefix as d, addMessage as f, listSessions as g, getSession as h, ClaudeCodeHost as i, AUTH_PROBE_TIMEOUT_MS as j, mapStreamEvent as k, PROXY_AUTH_FAILED_MESSAGE as l, createSession as m, CREDENTIAL_INVALID_MESSAGE as n, LOCAL_LOGIN_SWITCHED_MESSAGE as o, appendActivity as p, SCRUBBED_ANTHROPIC_ENV_VARS as q, CREDENTIAL_UNAVAILABLE_MESSAGE as r, MODEL_UNAVAILABLE_MESSAGE as s, resolveHostConfig as t, USAGE_LIMIT_MESSAGE as u, CLAUDE_PERMISSION_MODES as v, TERMINATION_GRACE_MS as w, MANAGED_ALLOWED_TOOLS as x, DEFAULT_ALLOWED_TOOLS as y, runAuthProbe as z };