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

package/dist/host-config.js

@@ -1,74 +1,402 @@
 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):
+* THREE non-negotiable invariants:
+*
+* 1. **Scrub inherited Claude auth.** `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
+*    / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` are removed from BOTH
+*    the parent env and any caller `extra`. A self-hosted Mac very often has
+*    these set for other tooling; if one reaches `claude` it silently switches
+*    accounts or billing plane (or routes through a proxy). The break is
+*    silent: the turn "works" but bills the wrong account.
 *
-* 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. **Inject the agent's own credential, last.** When the agents service holds
+*    a Claude credential for this agent, it is set AFTER the scrub as exactly
+*    one variable: `CLAUDE_CODE_OAUTH_TOKEN` (subscription token from
+*    `claude setup-token`) or `ANTHROPIC_API_KEY` (Anthropic API key). Nothing
+*    else can override it. With no credential, no auth variable is set and
+*    `claude` uses the machine's own login (self-hosted fallback). The value
+*    lives only in the host's memory and this env — never on disk, never logged.
 *
-* 2. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
+* 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 an agent credential is injected, so an
+* inherited `CLAUDE_CODE_USE_BEDROCK=1` (say) can't send the turn to Bedrock
+* and ignore the stored credential. Without a credential they are left alone:
+* the machine's own `claude` setup is the fallback, whatever provider it uses.
+*/
+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";
+/** 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 when a credential is injected) → set the bridge
+* marker → set the agent credential (if any). Neither `base` nor `extra` can
+* smuggle an auth variable in or override the injected credential.
 */
-function buildChildEnv(base, extra) {
+function buildChildEnv(base, extra, credential) {
 	const merged = {
 		...base,
-		...extra,
-		[BRIDGE_ENV_VAR]: "1"
+		...extra
 	};
 	const scrubbed = new Set(SCRUBBED_ANTHROPIC_ENV_VARS);
+	if (credential) for (const key of PROVIDER_OVERRIDE_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 (credential) env[CREDENTIAL_ENV_VAR[credential.kind]] = credential.value;
 	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));
+}
+/** 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. */
+function buildProbeArgs() {
+	return [
+		"-p",
+		"--input-format",
+		"text",
+		"--output-format",
+		"json",
+		"--model",
+		"haiku",
+		"--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 : "";
+		if (isAuthFailureStatus(record.api_error_status) || isAuthFailureText(text)) return { 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 against Anthropic with the agent's credential (or,
+* when none is stored, the machine's own login). Never throws.
+*/
+function runAuthProbe(opts) {
+	const spawnImpl = opts.spawnImpl ?? spawn;
+	const env = buildChildEnv(opts.baseEnv, { MAX_THINKING_TOKENS: "0" }, opts.credential);
+	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(), {
+				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.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 +511,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 +591,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 +599,8 @@ function mapStreamEvent(state, raw, nowMs) {
 			isError,
 			finalText: isError ? "" : finalText,
 			...durationMs !== void 0 ? { durationMs } : {},
-			...errorMessage ? { errorMessage } : {}
+			...errorMessage ? { errorMessage } : {},
+			...authFailed ? { authFailed: true } : {}
 		}];
 	}
 	return [];
@@ -408,6 +739,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 +811,16 @@ var SessionDriver = class {
 	abortCurrent = null;
 	bin;
 	baseEnv;
+	credential;
+	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.credential = opts?.credential ?? null;
+		this.managed = opts?.managed ?? false;
 		this.log = opts?.logger ?? console;
 		this.spawnImpl = opts?.__spawn ?? spawn;
 	}
@@ -485,7 +844,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 +858,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 +879,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.credential);
 		return new Promise((resolve) => {
 			let child;
 			try {
@@ -556,18 +917,21 @@ 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 } : {}
 				});
 			};
 			const requestTermination = (reason) => {
@@ -619,9 +983,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);
 			});
@@ -719,8 +1084,14 @@ 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;
 }
+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();
@@ -780,17 +1151,38 @@ async function createSession(sessionId, agentId, channel, tenantId, userId) {
 		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 withSessionLock(sessionId, async () => {
 		const session = await getSession(sessionId);
-		if (!session) return;
+		if (!session) return -1;
 		session.messages.push({
 			role,
 			content,
@@ -801,11 +1193,145 @@ async function addMessage(sessionId, role, content, senderId, senderName, compon
 			...attachments?.length ? { attachments } : {}
 		});
 		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). Whitespace-only messages are skipped (the service rejects empty
+* content) 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.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 +1341,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 +1351,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,6 +1393,196 @@ 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
@@ -903,8 +1615,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 +1629,10 @@ 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 LOCAL_LOGIN_FAILED_MESSAGE = "Claude Code is not signed in on this machine. Run `claude` and log in, or add a Claude credential in agent settings.";
+const CREDENTIAL_MISSING_MESSAGE = "This agent has no Claude credential. Add a Claude subscription token or an Anthropic API key in agent settings.";
+const CREDENTIAL_UNAVAILABLE_MESSAGE = "This agent's Claude credential couldn't be loaded yet. Try again in a moment.";
 const MAX_AGENT_MESSAGE_BYTES = 256 * 1024;
 const MAX_SESSION_KEY_CHARS = 768;
 const MAX_IDENTIFIER_CHARS = 512;
@@ -1130,18 +1844,49 @@ 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;
+	/** In memory only. Never logged, never persisted. */
+	credential = 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 ?? ((credential) => new SessionDriver({
 			logger: this.log,
-			baseEnv: process.env
+			baseEnv: process.env,
+			credential,
+			managed: cfg.managed === true
 		}));
 		this.api = deps?.api ?? new AgentApiClient({
 			apiKey: cfg.apiKey,
 			apiUrl: cfg.apiUrl
 		});
+		this.probe = deps?.probe ?? ((credential, signal) => runAuthProbe({
+			credential,
+			baseEnv: process.env,
+			cwd: tmpdir(),
+			signal
+		}));
+		this.credentialWaitMs = deps?.credentialWaitMs ?? 15e3;
+		this.loaderRestartMs = deps?.loaderRestartMs ?? 5e3;
+		this.credentialRetry = deps?.credentialRetry ?? {};
+		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 +1903,137 @@ 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.credentialLoaded = true;
+		this.resolveCredentialReady();
+		await this.checkCredential();
+	}
+	childCredential() {
+		return this.credential ? {
+			kind: this.credential.kind,
+			value: this.credential.value
+		} : null;
+	}
+	/** Start-up health check: one minimal real call, reported to the cloud. */
+	async checkCredential() {
+		if (!this.credential && this.cfg.managed) {
+			await this.reporter.report({
+				status: "missing",
+				detail: "No Claude credential is stored for this agent"
+			});
+			return;
+		}
+		const outcome = await this.probe(this.childCredential(), this.credentialAbort.signal);
+		if (this.stopping) return;
+		if (outcome.result === "unknown") {
+			this.log.warn(`[claude-host] Claude auth check inconclusive (${outcome.reason}); the next turn will tell`);
+			return;
+		}
+		await this.reportAuth(outcome.result === "ok");
+	}
+	/** Report the credential (or the local login) as working or refused. */
+	async reportAuth(ok) {
+		if (!this.credentialLoaded) return;
+		const revision = this.credential?.revision;
+		if (ok) await this.reporter.report({
+			status: "ok",
+			...revision ? { revision } : { detail: "Using this machine's claude login" }
+		});
+		else if (revision) await this.reporter.report({
+			status: "invalid",
+			detail: "Anthropic rejected the stored credential",
+			revision
+		});
+		else await this.reporter.report({
+			status: "missing",
+			detail: "No Claude credential, and the claude login on this machine is not signed in"
+		});
+	}
+	/**
+	* 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;
+		if (!this.credential && this.cfg.managed) return CREDENTIAL_MISSING_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();
+		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 +2122,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,17 +2178,29 @@ 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) {
+			complete({
+				ok: false,
+				payload: { message: 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 driver = this.makeDriver(this.childCredential());
 		const cancellation = new AbortController();
 		this.runningTurns.set(sessionKey, {
 			runId,
@@ -1308,7 +2213,7 @@ var ClaudeCodeHost = class {
 				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) => {
@@ -1332,12 +2237,21 @@ var ClaudeCodeHost = class {
 			return;
 		}
 		if (result.isError) {
+			if (result.authFailed) {
+				complete({
+					ok: false,
+					payload: { message: this.credential ? CREDENTIAL_INVALID_MESSAGE : LOCAL_LOGIN_FAILED_MESSAGE }
+				});
+				await this.reportAuth(false);
+				return;
+			}
 			complete({
 				ok: false,
 				payload: { message: result.errorMessage ?? "Claude Code turn failed" }
 			});
 			return;
 		}
+		this.reportAuth(true);
 		if (result.finalText) await addMessage(bareSessionId, "assistant", result.finalText);
 		const notification = result.finalText ? {
 			conversationId: bareSessionId,
@@ -1350,22 +2264,60 @@ var ClaudeCodeHost = class {
 			payload: { sessionKey },
 			...notification ? { notification } : {}
 		});
+		await this.ingestPendingMemory(bareSessionId, params);
+	}
+	/**
+	* 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 {
-			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 } : {},
+			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) {
-			this.log.warn(`[claude-host] memoryIngest failed (non-fatal): ${err instanceof Error ? err.message : String(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] CLAUDE.md sync failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
 		}
 	}
 	/**
@@ -1440,6 +2392,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,7 +2444,6 @@ 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) {
@@ -1551,6 +2507,28 @@ 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(":");
@@ -1566,22 +2544,36 @@ 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();
 	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"
 	};
 }
+/**
+* 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 { buildProbeArgs as A, collectTurnActivityRecords as C, AUTH_PROBE_TIMEOUT_MS as D, mapStreamEvents as E, BRIDGE_ENV_VAR as F, CREDENTIAL_ENV_VAR as I, SCRUBBED_ANTHROPIC_ENV_VARS as L, loadCredentialWithRetry as M, parseProbeOutput as N, CredentialStatusReporter as O, runAuthProbe as P, buildChildEnv as R, WARM_STREAMING_SUPPORTED as S, mapStreamEvent as T, MANAGED_ALLOWED_TOOLS as _, ClaudeCodeHost as a, TERMINATION_GRACE_MS as b, addMessage as c, getSession as d, listSessions as f, DEFAULT_PERMISSION_MODE as g, DEFAULT_ALLOWED_TOOLS as h, CREDENTIAL_UNAVAILABLE_MESSAGE as i, isAuthFailureText as j, STATUS_REPORT_INTERVAL_MS as k, appendActivity as l, CLAUDE_PERMISSION_MODES as m, CREDENTIAL_INVALID_MESSAGE as n, LOCAL_LOGIN_FAILED_MESSAGE as o, saveSession as p, CREDENTIAL_MISSING_MESSAGE as r, stripAgentPrefix as s, resolveHostConfig as t, createSession as u, MANAGED_DISALLOWED_TOOLS as v, createMapperState as w, TURN_TIMEOUT_MS as x, SessionDriver as y };