@indigoai-us/hq-cli 5.345.106 → 5.345.107

package/dist/lib/lanes/reconcile.js

@@ -1673,6 +1673,7 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                 if (!deps.dryRun &&
                     !providerRejection &&
                     !quota &&
+                    classified.remote_control !== true &&
                     repairCandidate &&
                     repairCandidate.envelope === null &&
                     (!repairCandidate.missing || envelopeRepairMode(classified.provider) === "resume")) {
@@ -1715,6 +1716,9 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     if (!repairCandidate.missing)
                         invalidEnvelope = { errors: repair.errors };
                 }
+                if (classified.remote_control === true && repairCandidate?.envelope === null) {
+                    invalidEnvelope = { errors: ["Remote Control turn did not write a valid lane envelope"] };
+                }
                 let repairedClassification = invalidEnvelope
                     ? classifyLaneExit({ envelope: null, hasPartialOutput: false, invalidEnvelope })
                     : classification;

package/dist/lib/lanes/remote-control-lane.d.ts

@@ -0,0 +1,33 @@
+import type { LanesConfig } from "./types.js";
+export interface RemoteControlLaneLaunch {
+    accountHome: string;
+    command: string;
+    args: string[];
+    caPath: string;
+}
+/** Keep every credential and network route tied to the selected pool. */
+export declare function configureRemoteControlChildEnv(env: NodeJS.ProcessEnv, launch: RemoteControlLaneLaunch): void;
+/** Keep account balancing inside the daemon pools that can actually forward. */
+export declare function remoteControlSelectionConfig(config: LanesConfig, env: NodeJS.ProcessEnv): LanesConfig;
+/** Pool readiness replaces the inference account's local login for this turn. */
+export declare function remoteControlAccountsForReadyPools(config: LanesConfig, ready: ReadonlySet<string>, hostname: string): LanesConfig;
+/** Session files stay in account a when the inference pool changes. */
+export declare function remoteControlSessionHome(config: LanesConfig, hostname: string): string;
+export declare function prepareRemoteControlLane(input: {
+    config: LanesConfig;
+    hostname: string;
+    env: NodeJS.ProcessEnv;
+    accountId: string;
+    laneId: string;
+    envelopePath: string;
+    sessionId: string;
+    claudeArgs: string[];
+}): RemoteControlLaneLaunch;
+declare function tmux(socket: string, args: string[]): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+export declare function remoteControlFailureText(socket: string, session: string, capture?: typeof tmux): string;
+export {};
+//# sourceMappingURL=remote-control-lane.d.ts.map

package/dist/lib/lanes/remote-control-lane.js

@@ -0,0 +1,276 @@
+/**
+ * A Claude lane opened as its own Remote Control terminal. The login and
+ * transcript stay in account a; a private hosts mount forces all Anthropic API
+ * requests through the selected daemon pool's token forwarder.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { stripVTControlCharacters } from "node:util";
+import { daemonPaths, ensurePrivateDir } from "../daemon/paths.js";
+import { isOwnedPoolForwarder, poolHostsFile, readRemoteControlPoolsConfig } from "../daemon/remote-control-pools.js";
+import { accountStatus } from "./accounts.js";
+import { effectiveAccountHome } from "./account-home.js";
+import { LanesError } from "./errors.js";
+import { defaultProbe } from "./models.js";
+import { encodeClaudeProjectDir } from "./move-account.js";
+/** Keep every credential and network route tied to the selected pool. */
+export function configureRemoteControlChildEnv(env, launch) {
+    env.CLAUDE_CONFIG_DIR = launch.accountHome;
+    env.NODE_EXTRA_CA_CERTS = launch.caPath;
+    env.IS_SANDBOX = "1";
+    for (const key of Object.keys(env)) {
+        if (/_proxy$/i.test(key) || ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL"].includes(key)) {
+            delete env[key];
+        }
+    }
+}
+/** Keep account balancing inside the daemon pools that can actually forward. */
+export function remoteControlSelectionConfig(config, env) {
+    if (process.platform !== "linux") {
+        throw new LanesError("remote_control_linux_required", "Claude Remote Control account pools require Linux", {});
+    }
+    const home = os.homedir();
+    const paths = daemonPaths(home, env);
+    const pools = readRemoteControlPoolsConfig(paths.remoteControlPoolsPath, Object.keys(config.providers.claude.accounts), home);
+    const ready = new Set(pools.frontendCaPath && fs.existsSync(pools.frontendCaPath)
+        ? pools.pools
+            .filter((pool) => ownedForwarder(path.join(paths.root, "remote-control-pools", "forwarder", `${pool.accountId}.json`), pool.accountId))
+            .map((pool) => pool.accountId)
+        : []);
+    if (ready.size === 0) {
+        throw new LanesError("remote_control_pool_unavailable", "No Claude Remote Control inference pool is running in the local HQ daemon", {});
+    }
+    return remoteControlAccountsForReadyPools(config, ready, os.hostname());
+}
+/** Pool readiness replaces the inference account's local login for this turn. */
+export function remoteControlAccountsForReadyPools(config, ready, hostname) {
+    const loginHome = remoteControlSessionHome(config, hostname);
+    // The forwarder owns the inference credential. Claude itself always uses
+    // account a's home, so selection must not require credentials in B/C/D.
+    const accounts = Object.fromEntries(Object.entries(config.providers.claude.accounts).map(([id, account]) => [
+        id,
+        id !== "a" && ready.has(id)
+            ? { ...account, home: loginHome, hosts: undefined }
+            : {
+                ...account,
+                enabled: false,
+                disabled_reason: id === "a"
+                    ? "Account a is reserved for Remote Control login"
+                    : "The local daemon inference pool is unavailable",
+            },
+    ]));
+    return {
+        ...config,
+        providers: {
+            ...config.providers,
+            claude: { ...config.providers.claude, accounts },
+        },
+    };
+}
+/** Session files stay in account a when the inference pool changes. */
+export function remoteControlSessionHome(config, hostname) {
+    const loginAccount = config.providers.claude.accounts.a;
+    if (!loginAccount) {
+        throw new LanesError("remote_control_login_missing", "Claude account a must be configured for Remote Control login", {});
+    }
+    return effectiveAccountHome(loginAccount, hostname).home;
+}
+function ownedForwarder(readyFile, accountId) {
+    return isOwnedPoolForwarder(readyFile, accountId, (pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, (pid) => {
+        try {
+            return fs.readFileSync(`/proc/${pid}/cmdline`, "utf8").replace(/\0/g, " ");
+        }
+        catch {
+            return null;
+        }
+    });
+}
+export function prepareRemoteControlLane(input) {
+    if (process.platform !== "linux") {
+        throw new LanesError("remote_control_linux_required", "Claude Remote Control account pools require Linux", {});
+    }
+    if (input.accountId === "a") {
+        throw new LanesError("remote_control_token_account_required", "Account a is reserved for Remote Control login; select b or a later account for tokens", {});
+    }
+    const accountA = input.config.providers.claude.accounts.a;
+    if (!accountA) {
+        throw new LanesError("remote_control_login_missing", "Claude account a must be configured for Remote Control login", {});
+    }
+    const status = accountStatus("claude", "a", input.config, {
+        hostname: input.hostname, existsSync: fs.existsSync, probe: defaultProbe, env: input.env,
+    });
+    if (!status.logged_in) {
+        throw new LanesError("remote_control_login_missing", "Claude account a must be logged in for Remote Control", {});
+    }
+    const home = os.homedir();
+    const paths = daemonPaths(home, input.env);
+    const pools = readRemoteControlPoolsConfig(paths.remoteControlPoolsPath, Object.keys(input.config.providers.claude.accounts), home);
+    const pool = pools.pools.find((entry) => entry.accountId === input.accountId);
+    if (!pool || !pools.frontendCaPath || !fs.existsSync(pools.frontendCaPath)) {
+        throw new LanesError("remote_control_pool_missing", `The daemon has no ready Remote Control pool for Claude account ${input.accountId}`, { account: input.accountId });
+    }
+    const readyFile = path.join(paths.root, "remote-control-pools", "forwarder", `${input.accountId}.json`);
+    if (!ownedForwarder(readyFile, input.accountId)) {
+        throw new LanesError("remote_control_pool_unavailable", `The daemon inference forwarder for Claude account ${input.accountId} is not running`, { account: input.accountId });
+    }
+    return {
+        accountHome: effectiveAccountHome(accountA, input.hostname).home,
+        command: process.execPath,
+        args: [
+            fileURLToPath(import.meta.url),
+            "run",
+            paths.root,
+            input.laneId,
+            input.accountId,
+            pool.frontendAddress,
+            input.envelopePath,
+            input.sessionId,
+            ...input.claudeArgs,
+        ],
+        caPath: pools.frontendCaPath,
+    };
+}
+function quote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function tmux(socket, args) {
+    const result = spawnSync("tmux", ["-L", socket, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return { status: result.status, stdout: result.stdout || "", stderr: result.stderr || result.error?.message || "" };
+}
+export function remoteControlFailureText(socket, session, capture = tmux) {
+    const pane = capture(socket, ["capture-pane", "-p", "-S", "-2000", "-t", session]).stdout.trimEnd();
+    const visible = stripVTControlCharacters(pane);
+    const failureLine = visible.split("\n").map((line) => line.trim()).reverse().find((line) => /weekly limit|usage limit|rate limit|quota|usage credits|hit your .+ limit|reached your limit|not logged in|please run \/login|authentication failed|invalid api key/i.test(line));
+    if (!failureLine)
+        return pane;
+    const quota = /weekly limit|usage limit|rate limit|quota|usage credits|hit your .+ limit|reached your limit/i.test(failureLine);
+    const result = JSON.stringify({ type: "result", is_error: true, api_error_status: quota ? 429 : 401, result: failureLine });
+    return `${pane}\n${result}`;
+}
+async function runInside(args) {
+    const [daemonRoot, laneId, accountId, _address, envelopePath, sessionId, ...claudeArgs] = args;
+    if (!daemonRoot || !laneId || !accountId || !envelopePath || !sessionId || claudeArgs.length === 0)
+        return 2;
+    const digest = createHash("sha256").update(laneId).digest("hex").slice(0, 18);
+    const socket = `hq-lane-${digest}`;
+    const session = "lane";
+    const exitDir = path.join(daemonRoot, "remote-control-pools", "lanes");
+    ensurePrivateDir(exitDir);
+    const exitFile = path.join(exitDir, `${digest}.${process.pid}.exit`);
+    const readyFile = path.join(daemonRoot, "remote-control-pools", "forwarder", `${accountId}.json`);
+    const launcher = fileURLToPath(new URL("../../commands/core-job-remote-launcher.js", import.meta.url));
+    const command = [process.execPath, launcher, exitFile, ...claudeArgs].map(quote).join(" ");
+    tmux(socket, ["kill-session", "-t", session]);
+    const started = tmux(socket, ["new-session", "-d", "-s", session, "-c", process.cwd(), command]);
+    if (started.status !== 0) {
+        process.stderr.write(`hq lanes: could not start Remote Control terminal: ${started.stderr}\n`);
+        return 1;
+    }
+    const retained = tmux(socket, ["set-option", "-t", session, "remain-on-exit", "on"]);
+    if (retained.status !== 0) {
+        tmux(socket, ["kill-session", "-t", session]);
+        process.stderr.write(`hq lanes: could not retain Remote Control terminal output: ${retained.stderr}\n`);
+        return 1;
+    }
+    let stopped = false;
+    const stop = () => { stopped = true; tmux(socket, ["kill-session", "-t", session]); };
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+    try {
+        while (!stopped) {
+            if (!ownedForwarder(readyFile, accountId)) {
+                process.stderr.write(`hq lanes: daemon inference forwarder for account ${accountId} stopped\n`);
+                return 1;
+            }
+            if (fs.existsSync(envelopePath)) {
+                // The id was passed to Claude; verify the provider really persisted it
+                // before reporting it to the lane watcher as a resumable session.
+                const transcript = path.join(process.env.CLAUDE_CONFIG_DIR || "", "projects", encodeClaudeProjectDir(process.cwd()), `${sessionId}.jsonl`);
+                for (let attempt = 0; attempt < 20 && !fs.existsSync(transcript); attempt++) {
+                    await new Promise((resolve) => setTimeout(resolve, 500));
+                }
+                if (!fs.existsSync(transcript)) {
+                    process.stderr.write("hq lanes: Remote Control wrote an envelope but its session transcript is missing\n");
+                    return 1;
+                }
+                process.stdout.write(`${JSON.stringify({ type: "result", session_id: sessionId })}\n`);
+                return 0;
+            }
+            if (fs.existsSync(exitFile) || tmux(socket, ["has-session", "-t", session]).status !== 0) {
+                // The launcher retains the pane briefly after Claude exits. Relay its
+                // text so quota and auth rejection classifiers see the provider error.
+                const paneText = remoteControlFailureText(socket, session);
+                if (paneText.trim())
+                    process.stderr.write(`${paneText}\n`);
+                process.stderr.write("hq lanes: Remote Control terminal exited before the lane envelope was written\n");
+                return 1;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+        return 143;
+    }
+    finally {
+        tmux(socket, ["kill-session", "-t", session]);
+        process.off("SIGTERM", stop);
+        process.off("SIGINT", stop);
+        fs.rmSync(exitFile, { force: true });
+    }
+}
+async function runOuter(args) {
+    const [daemonRoot, laneId, accountId, address] = args;
+    if (!daemonRoot || !laneId || !accountId || !address)
+        return 2;
+    const overlayDir = path.join(daemonRoot, "remote-control-pools", "hosts", "lanes");
+    ensurePrivateDir(overlayDir);
+    const overlay = path.join(overlayDir, `${process.pid}.hosts`);
+    fs.writeFileSync(overlay, poolHostsFile(fs.readFileSync("/etc/hosts", "utf8"), {
+        frontendAddress: address,
+    }), { mode: 0o600 });
+    const script = 'set -eu\nmount --make-rprivate /\nmount --bind "$1" /etc/hosts\nshift\nexec "$@"';
+    try {
+        return await new Promise((resolve) => {
+            const child = spawn("unshare", [
+                "--map-root-user", "--mount", "--fork", "--kill-child=TERM",
+                "sh", "-c", script, "hq-lane-rc", overlay,
+                process.execPath, fileURLToPath(import.meta.url), "inside", ...args,
+            ], { cwd: process.cwd(), env: process.env, stdio: "inherit" });
+            let settled = false;
+            const forward = () => child.kill("SIGTERM");
+            const finish = (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                process.off("SIGTERM", forward);
+                process.off("SIGINT", forward);
+                resolve(code);
+            };
+            process.once("SIGTERM", forward);
+            process.once("SIGINT", forward);
+            child.once("error", (error) => {
+                process.stderr.write(`hq lanes: Remote Control namespace could not start: ${error.message}\n`);
+                finish(127);
+            });
+            child.once("exit", (code) => finish(code ?? 1));
+        });
+    }
+    finally {
+        fs.rmSync(overlay, { force: true });
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const [mode, ...args] = process.argv.slice(2);
+    process.exitCode = mode === "inside" ? await runInside(args) : mode === "run" ? await runOuter(args) : 2;
+}
+//# sourceMappingURL=remote-control-lane.js.map

package/dist/lib/lanes/spawn.d.ts

@@ -245,6 +245,11 @@ export declare function buildProviderCommand(provider: LaneProvider, input: {
      * exclusive with `resume`.
      */
     freshTurnPrompt?: string;
+    /** Interactive Claude Remote Control turn with a known provider session id. */
+    remoteControl?: {
+        sessionId: string;
+        name: string;
+    };
 }): ProviderLaunch;
 export declare function workerEnv(base: NodeJS.ProcessEnv, resolved: {
     envVar: string;

package/dist/lib/lanes/spawn.js

@@ -12,6 +12,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { configureRemoteControlChildEnv, prepareRemoteControlLane, remoteControlSelectionConfig } from "./remote-control-lane.js";
 import { PROVIDER_HOME_ENV, accountStatus, isLoggedOut, resolveAccount, selectBalancedAccount, } from "./accounts.js";
 import { effectiveAccountHome } from "./account-home.js";
 import { buildHostCapacitySnapshot } from "./host-capacity.js";
@@ -694,7 +695,7 @@ export async function retryLaneOnAlternateAccount(hqRoot, lane, reason, writer =
         lane.provider_session_id.trim().length > 0
         ? lane.provider_session_id
         : undefined;
-    if (source && sessionId) {
+    if (source && sessionId && lane.remote_control !== true) {
         copySessionFiles(planSessionCopy(lane.provider, {
             sourceHome: lane.provider_home_at_spawn ?? effectiveAccountHome(source, hostname).home,
             targetHome: target.home,
@@ -1546,7 +1547,28 @@ export function buildProviderCommand(provider, input) {
             prompt += ` ${input.extraPrompt}`;
     }
     let args;
-    if (input.resume && parsed === "codex") {
+    if (input.remoteControl && parsed !== "claude") {
+        throw new LanesError("remote_control_requires_claude", "Remote Control requires Claude", { provider: parsed });
+    }
+    if (input.remoteControl && input.resume && input.remoteControl.sessionId !== input.resume.session_id) {
+        throw new LanesError("remote_control_session_mismatch", "Remote Control resume id does not match the recorded session", {});
+    }
+    if (input.remoteControl) {
+        args = [
+            "--remote-control",
+            input.remoteControl.name,
+            ...(input.resume
+                ? ["--resume", input.resume.session_id]
+                : ["--session-id", input.remoteControl.sessionId]),
+            "--permission-mode",
+            "bypassPermissions",
+            "--dangerously-skip-permissions",
+            input.resume?.prompt ?? prompt,
+            "--disallowedTools",
+            "AskUserQuestion",
+        ];
+    }
+    else if (input.resume && parsed === "codex") {
         // `codex exec resume` (0.155.1) takes `[SESSION_ID] [PROMPT]` and has
         // neither `-C` nor `--color`; the session keeps its recorded cwd. `--json`
         // makes the resumed run re-emit `thread.started` with the same id.
@@ -2182,9 +2204,15 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         }
         : undefined;
     const profileChanged = profile !== undefined && existing.worker_profile_hash !== profile.contentHash;
-    const config = loadLanesConfig(hqRoot);
+    const loadedConfig = loadLanesConfig(hqRoot);
+    const config = existing.remote_control === true
+        ? remoteControlSelectionConfig(loadedConfig, env)
+        : loadedConfig;
     const repairRecordedAccount = plan.mode === "resume" &&
         (trigger.kind === "resume" || pendingResume?.trigger === "resume" || pendingResume?.trigger === "watcher");
+    if (existing.remote_control === true && config.providers.claude.accounts.a === undefined) {
+        throw new LanesError("remote_control_login_missing", "Claude account a must be configured for Remote Control login", {});
+    }
     const recordedModel = repairRecordedAccount && existing.model_source === "account"
         ? existing.model
         : undefined;
@@ -2300,7 +2328,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         const source = existing.account
             ? config.providers[existing.provider].accounts[existing.account]
             : undefined;
-        if (source &&
+        if (existing.remote_control !== true &&
+            source &&
             existing.provider_session_id &&
             providerSupportsSessionResume(existing.provider)) {
             copySessionFiles(planSessionCopy(existing.provider, {
@@ -2312,11 +2341,14 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         }
     }
     if (plan.mode === "resume" && existing.provider !== "grok") {
+        const targetHome = existing.remote_control === true
+            ? effectiveAccountHome(config.providers.claude.accounts.a, hostname).home
+            : resolved.home;
         ensureSessionHome({
             provider: existing.provider,
             sessionId: plan.session_id,
             cwd: hqRoot,
-            targetHome: resolved.home,
+            targetHome,
             registeredHomes: Object.values(config.providers[existing.provider].accounts)
                 .map((account) => effectiveAccountHome(account, hostname).home),
             providerHomeAtSpawn: existing.provider_home_at_spawn,
@@ -2347,8 +2379,11 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             };
         });
     }
+    const remoteControlHome = existing.remote_control === true
+        ? effectiveAccountHome(config.providers.claude.accounts.a, hostname).home
+        : undefined;
     try {
-        installDrainHook(lane.provider, resolved.home);
+        installDrainHook(lane.provider, remoteControlHome ?? resolved.home);
     }
     catch (err) {
         process.stderr.write(`hq lanes: drain hook install failed for ${resolved.home}: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -2369,7 +2404,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker);
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: remoteControlHome ?? resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir, lane.registry_worker);
     const laneTurnId = randomUUID();
     childEnv.HQ_LANE_TURN_ID = laneTurnId;
     const model = resolveLaneModel({
@@ -2431,7 +2466,10 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             }),
         }
         : undefined;
-    const command = buildProviderCommand(lane.provider, {
+    const remoteSessionId = existing.remote_control === true
+        ? plan.mode === "resume" ? plan.session_id : randomUUID()
+        : undefined;
+    const providerCommand = buildProviderCommand(lane.provider, {
         hqRoot,
         briefPath,
         envelopePath,
@@ -2443,19 +2481,32 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         profile: profileLaunch,
         workerPolicyDir,
         resume,
+        ...(remoteSessionId ? { remoteControl: { sessionId: remoteSessionId, name: `hq/${lane.lane_id}` } } : {}),
     });
+    const remoteLaunch = remoteSessionId
+        ? prepareRemoteControlLane({
+            config, hostname, env, accountId: resolved.id, laneId: lane.lane_id,
+            envelopePath, sessionId: remoteSessionId, claudeArgs: providerCommand.args,
+        })
+        : undefined;
+    if (remoteLaunch) {
+        configureRemoteControlChildEnv(childEnv, remoteLaunch);
+    }
+    const command = remoteLaunch ?? providerCommand;
     // A systemd PATH mismatch is an environment defect, not a lane failure.
     // Keep the lane eligible for a later reconcile after the installer repairs it.
-    if (!providerCommandOnPath(command.command, childEnv.PATH)) {
+    const missingCommand = [providerCommand.command, ...(remoteLaunch ? ["unshare", "mount", "tmux"] : [])]
+        .find((candidate) => !providerCommandOnPath(candidate, childEnv.PATH));
+    if (missingCommand) {
         const searchedPath = childEnv.PATH ?? "";
         // Only admission may re-queue. A resume (answered questions, operator
         // message) must keep the recorded state so the next reconcile does not
         // infer `admit` and start a fresh run in place of the recorded session;
         // the caller keeps the message text and sees the named error.
         if (trigger.kind !== "admit") {
-            throw new LanesError("provider_binary_missing", `Provider binary ${command.command} for ${lane.provider} is not executable on PATH ${JSON.stringify(searchedPath)}; lane ${lane.lane_id} keeps state ${existing.state}`, {
+            throw new LanesError("provider_binary_missing", `Required binary ${missingCommand} for ${lane.provider} is not executable on PATH ${JSON.stringify(searchedPath)}; lane ${lane.lane_id} keeps state ${existing.state}`, {
                 provider: lane.provider,
-                command: command.command,
+                command: missingCommand,
                 searched_path: searchedPath,
                 lane_id: lane.lane_id,
                 state: existing.state,
@@ -2470,7 +2521,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             terminal_reason: undefined,
             terminal_details: {
                 provider: lane.provider,
-                command: command.command,
+                command: missingCommand,
                 searched_path: searchedPath,
             },
         }));
@@ -2479,7 +2530,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     // lane is never `running` without a worker while `/compact` works.
     let compaction;
     const compactWanted = pendingResume?.compact ?? launch.compact;
-    if (resume && compactWanted !== false) {
+    if (resume && compactWanted !== false && existing.remote_control !== true) {
         const nowFn = deps.now ?? (() => new Date());
         const decision = compactionDue(existing, nowFn().getTime(), providerCompactAfterMs(config.providers[lane.provider]));
         if (decision.due) {
@@ -2589,7 +2640,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             pending_resume: undefined,
             pending_settings: undefined,
             account: resolved.id,
-            provider_home_at_spawn: resolved.home,
+            provider_home_at_spawn: remoteControlHome ?? resolved.home,
             ...(model !== undefined ? { model } : {}),
             ...(model !== undefined
                 ? {

package/dist/lib/lanes/store.js

@@ -426,6 +426,13 @@ export function parseLaneRecord(raw, filePath) {
     const schema_version = requireString(raw.schema_version, "schema_version");
     parseMajorSchema(schema_version, "hq-lane", 1);
     requireString(raw.lane_id, "lane_id");
+    if (raw.remote_control !== undefined && (raw.remote_control !== true || raw.provider !== "claude")) {
+        throw new LaneSchemaError("remote_control requires a Claude lane", {
+            path: filePath,
+            field: "remote_control",
+            value: raw.remote_control,
+        });
+    }
     if (raw.written_by_version !== undefined) {
         const writtenByVersion = requireString(raw.written_by_version, "written_by_version");
         if (!semver.valid(writtenByVersion)) {

package/dist/lib/lanes/types.d.ts

@@ -612,6 +612,8 @@ export interface LaneRecord {
     /** How policy files were delivered on the most recent profile spawn. */
     worker_policy_delivery?: "hook" | "prompt";
     provider: LaneProvider;
+    /** Open each Claude turn as a named Remote Control session using account a's login. */
+    remote_control?: boolean;
     /** Whether provider came from an explicit create override or the worker profile/default. */
     provider_source?: "cli" | "profile" | "default";
     account?: string;

package/dist/lib/lanes/types.js

@@ -235,7 +235,7 @@ export const LANE_FIELD_WRITERS = {
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
     keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile", "spawn"], keep_alive_history: ["reconcile"], keep_alive_blocked_resume_streak: ["reconcile", "spawn", "watcher"], keep_alive_last_resume_at: ["command", "reconcile", "spawn"], keep_alive_next_eligible_at: ["command", "reconcile", "spawn"], keep_alive_exhausted_at: ["command", "reconcile", "spawn"], loop_mode: ["creator"],
-    provider: ["creator", "command"], provider_source: ["creator", "command"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_source: ["creator", "command"], profile_settings_pinned: ["command"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], fallback_question_cancellation_failures: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
+    provider: ["creator", "command"], remote_control: ["creator"], provider_source: ["creator", "command"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_source: ["creator", "command"], profile_settings_pinned: ["command"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], fallback_question_cancellation_failures: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
     version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command", "watcher", "reconcile"], story_switch_pending: ["command", "watcher", "reconcile"], story_switch_unacknowledged: ["command", "watcher", "reconcile"],
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["creator", "command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher", "reconcile"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],

package/dist/lib/lanes/watcher.js

@@ -1564,12 +1564,14 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
         let questionIndexes;
         let recoveredAsk = false;
         const repairCandidate = latestFile ?? missingExpected;
+        const remoteControlLane = readLaneSoft(hqRoot, laneId)?.remote_control === true;
         if (!processAlive &&
             !envelope &&
             !providerRejection &&
             !quota &&
             repairCandidate &&
-            repairCandidate.envelope === null) {
+            repairCandidate.envelope === null &&
+            !remoteControlLane) {
             const lane = repairCandidate.missing ? readLaneSoft(hqRoot, laneId) : null;
             const missingRepairAllowed = !repairCandidate.missing ||
                 (lane !== null && envelopeRepairMode(lane.provider) === "resume");
@@ -1648,6 +1650,11 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
                 }
             }
         }
+        if (!processAlive && !envelope && remoteControlLane && repairCandidate?.envelope === null) {
+            // A headless repair would resume from account a outside the pool's
+            // namespace and could charge that account. Fail the lane instead.
+            invalidEnvelope = { errors: ["Remote Control turn did not write a valid lane envelope"] };
+        }
         if (processAlive === false &&
             envelope &&
             latestFile !== null &&

package/dist/utils/cognito-session.d.ts

@@ -18,8 +18,9 @@
  *   HQ_COGNITO_CALLBACK_PORT   — Loopback OAuth callback port
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
-import { loadCachedTokens, isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
-export { isExpiring, isMachineIdentity, loadCachedTokens };
+import { isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { type KeychainReadOptions } from "./token-keychain.js";
+export { isExpiring, isMachineIdentity };
 /** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
 export type CognitoTokenSource = "person" | "machine";
 /** Actor kind derived from the active token / machine-creds signal. */
@@ -186,11 +187,18 @@ export declare function formatCognitoSubject(tokens: {
     accessToken?: string;
 } | null | undefined): string;
 /**
- * Person cache as stored on disk for `env`. Does not consult hq-cloud's
+ * Person session for `env`: the Keychain item and the token file, the newer
+ * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
  * in-memory fallback, which can surface a different session when the file
  * is missing or unreadable.
  */
-export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv): CognitoTokens | null;
+export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
+/**
+ * The person's cached session: the shared Keychain item and hq-cloud's file
+ * loader, the newer by `expiresAt`. Writes still go only to the file in this
+ * step.
+ */
+export declare function loadCachedTokens(env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
 /**
  * Refresh the active person session and refuse a subject change.
  *