@astrale-os/cli 0.7.0-alpha.0 → 0.8.0-alpha.0

package/README.md

@@ -30,8 +30,9 @@ npm install -g @astrale-os/cli
 ```
 
 The npm build bundles all dependencies, so no private-registry access is needed.
-`astrale studio` launches a local web GUI to author and inspect a domain; it runs
-on [Bun](https://bun.sh), so install Bun and keep it on `PATH` to use that command
+`astrale studio` launches a local web GUI to author and inspect a domain, with
+local Claude Code and Codex agent harnesses (`--harness claude|codex`); it runs on
+[Bun](https://bun.sh), so install Bun and keep it on `PATH` to use that command
 (the rest of the CLI needs only Node ≥ 20). The curl-installed standalone binary
 above does not include the studio — use the npm install for `astrale studio`.
 

package/dist/astrale.js

@@ -2576,7 +2576,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "0.7.0-alpha.0",
+    version: "0.8.0-alpha.0",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -2606,8 +2606,7 @@ var init_package = __esm(() => {
     type: "module",
     exports: {
       "./keys": "./src/lib/keys.ts",
-      "./paths": "./src/lib/paths.ts",
-      "./connect-core": "./src/connect-core.ts"
+      "./paths": "./src/lib/paths.ts"
     },
     publishConfig: {
       access: "public",
@@ -59080,24 +59079,14 @@ async function obtainToken(idp, opts, scope2) {
     scope: scope2,
     audience: opts.audience
   });
-  if (opts.onVerification) {
-    opts.onVerification({
-      verificationUri: device.verification_uri ?? device.verification_uri_complete ?? "",
-      verificationUriComplete: device.verification_uri_complete,
-      userCode: device.user_code,
-      expiresIn: device.expires_in,
-      message: device.message
-    });
-  } else {
-    if (device.verification_uri_complete)
-      log.info(`Open: ${device.verification_uri_complete}`);
-    else if (device.verification_uri)
-      log.info(`Open: ${device.verification_uri}`);
-    if (device.user_code)
-      log.info(`Code: ${device.user_code}`);
-    if (device.message)
-      log.dim(`  ${device.message}`);
-  }
+  if (device.verification_uri_complete)
+    log.info(`Open: ${device.verification_uri_complete}`);
+  else if (device.verification_uri)
+    log.info(`Open: ${device.verification_uri}`);
+  if (device.user_code)
+    log.info(`Code: ${device.user_code}`);
+  if (device.message)
+    log.dim(`  ${device.message}`);
   return pollDeviceToken({
     idp,
     deviceCode: device.device_code,
@@ -69909,11 +69898,59 @@ var init_resolve7 = __esm(() => {
   VIEW_PATH_RE = /^\/:[^\s/:@]+:view\.[a-z][a-z0-9-]*$/;
 });
 
-// src/lib/view/server.ts
+// src/lib/view/assets.ts
 import { existsSync as existsSync5 } from "node:fs";
+import { copyFile as copyFile2 } from "node:fs/promises";
+import { dirname as dirname8, join as join12 } from "node:path";
+import { fileURLToPath } from "node:url";
+function viewerDistDir(moduleUrl = import.meta.url, entry = process.argv[1] ?? ".") {
+  const override = process.env.ASTRALE_VIEWER_DIR;
+  if (override)
+    return override;
+  const moduleDirectory = dirname8(fileURLToPath(moduleUrl));
+  const published = join12(moduleDirectory, "..", "viewer", "dist");
+  const source = join12(moduleDirectory, "..", "..", "..", "viewer", "dist");
+  const legacy = join12(dirname8(entry), "..", "viewer", "dist");
+  const complete = [published, source, legacy].find(hasViewerBundle);
+  if (complete)
+    return complete;
+  if (hasViewerSource(join12(source, "..")))
+    return source;
+  return published;
+}
+async function ensureViewerAssets(moduleUrl = import.meta.url, entry = process.argv[1] ?? ".") {
+  const dist = viewerDistDir(moduleUrl, entry);
+  if (hasViewerBundle(dist))
+    return dist;
+  const srcDir = join12(dist, "..");
+  const bun = globalThis.Bun;
+  if (bun && hasViewerSource(srcDir)) {
+    const result = await bun.build({
+      entrypoints: [join12(srcDir, "main.ts")],
+      outdir: dist,
+      target: "browser",
+      minify: false
+    });
+    if (!result.success)
+      throw new Error(`viewer build failed: ${result.logs.join(`
+`)}`);
+    await copyFile2(join12(srcDir, "index.html"), join12(dist, "index.html"));
+    return dist;
+  }
+  throw new Error(`viewer bundle missing at ${dist} — reinstall the CLI (or run \`bun scripts/build.ts\` in a dev checkout)`);
+}
+function hasViewerBundle(directory) {
+  return existsSync5(join12(directory, "main.js")) && existsSync5(join12(directory, "index.html"));
+}
+function hasViewerSource(directory) {
+  return existsSync5(join12(directory, "main.ts")) && existsSync5(join12(directory, "index.html"));
+}
+var init_assets = () => {};
+
+// src/lib/view/server.ts
 import { readFile as readFile11 } from "node:fs/promises";
 import { createServer } from "node:http";
-import { dirname as dirname8, join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 import { Readable } from "node:stream";
 function startViewServer(config2) {
   const { session, proxy } = config2;
@@ -69971,11 +70008,11 @@ function startViewServer(config2) {
       return;
     }
     if (sub === "/" || sub === "/index.html") {
-      await serveAsset(res, join12(hostDir, "index.html"), "text/html; charset=utf-8");
+      await serveAsset(res, join13(hostDir, "index.html"), "text/html; charset=utf-8");
       return;
     }
     if (sub === "/main.js") {
-      await serveAsset(res, join12(hostDir, "main.js"), "text/javascript; charset=utf-8");
+      await serveAsset(res, join13(hostDir, "main.js"), "text/javascript; charset=utf-8");
       return;
     }
     if (sub === "/config.json" && req.method === "GET") {
@@ -70060,34 +70097,6 @@ function startViewServer(config2) {
   server.listen(session.port, "127.0.0.1");
   return server;
 }
-function viewerDistDir() {
-  const override = process.env.ASTRALE_VIEWER_DIR;
-  if (override)
-    return override;
-  return join12(dirname8(process.argv[1] ?? "."), "..", "viewer", "dist");
-}
-async function ensureViewerAssets() {
-  const dist = viewerDistDir();
-  if (existsSync5(join12(dist, "main.js")) && existsSync5(join12(dist, "index.html")))
-    return dist;
-  const srcDir = join12(dist, "..");
-  const bun = globalThis.Bun;
-  if (bun && existsSync5(join12(srcDir, "main.ts"))) {
-    const result = await bun.build({
-      entrypoints: [join12(srcDir, "main.ts")],
-      outdir: dist,
-      target: "browser",
-      minify: false
-    });
-    if (!result.success)
-      throw new Error(`viewer build failed: ${result.logs.join(`
-`)}`);
-    const { copyFile: copyFile2 } = await import("node:fs/promises");
-    await copyFile2(join12(srcDir, "index.html"), join12(dist, "index.html"));
-    return dist;
-  }
-  throw new Error(`viewer bundle missing at ${dist} — reinstall the CLI (or run \`bun scripts/build.ts\` in a dev checkout)`);
-}
 function jwtExpiry(token) {
   try {
     const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8"));
@@ -70144,7 +70153,9 @@ var TOKEN_REFRESH_MARGIN_MS, FALLBACK_TOKEN_TTL_MS = 3600000, IDLE_SWEEP_MS = 60
 var init_server = __esm(() => {
   init_kernel2();
   init_ca_fetch();
+  init_assets();
   init_session2();
+  init_assets();
   TOKEN_REFRESH_MARGIN_MS = 5 * 60000;
 });
 
@@ -70225,7 +70236,7 @@ __export(exports_view, {
 import { randomBytes } from "node:crypto";
 import { closeSync, existsSync as existsSync6, openSync, statSync } from "node:fs";
 import { mkdir as mkdir10, readdir as readdir3, readFile as readFile12, writeFile as writeFile9 } from "node:fs/promises";
-import { dirname as dirname9, join as join13 } from "node:path";
+import { dirname as dirname9, join as join14 } from "node:path";
 async function resolveSession(spec, opts) {
   const parsed = spec ? parseViewSpec(spec) : undefined;
   if (parsed?.kind === "target" && opts.target) {
@@ -70301,7 +70312,7 @@ async function resolveServeRuntime() {
   if (node2 && entry?.endsWith(".js") && existsSync6(entry))
     return { file: node2, args: [entry] };
   if (node2 && entry?.endsWith(".ts")) {
-    const dist = join13(dirname9(entry), "..", "dist", "astrale.js");
+    const dist = join14(dirname9(entry), "..", "dist", "astrale.js");
     await ensureDevDist(entry, dist);
     if (existsSync6(dist))
       return { file: node2, args: [dist] };
@@ -70319,7 +70330,7 @@ async function ensureDevDist(entry, dist) {
   const bun = globalThis.Bun;
   if (!bun)
     return;
-  const srcDir = join13(dirname9(entry), "..", "src");
+  const srcDir = join14(dirname9(entry), "..", "src");
   if (existsSync6(dist) && !await newerThan(srcDir, statSync(dist).mtimeMs))
     return;
   console.error("(dev) building dist/astrale.js for the session server…");
@@ -70335,7 +70346,7 @@ async function newerThan(dir, mtimeMs) {
   for (const item of entries) {
     if (!item.isFile())
       continue;
-    if (statSync(join13(item.parentPath, item.name)).mtimeMs > mtimeMs)
+    if (statSync(join14(item.parentPath, item.name)).mtimeMs > mtimeMs)
       return true;
   }
   return false;
@@ -70944,28 +70955,28 @@ __export(exports_studio, {
   default: () => studio_default
 });
 import { existsSync as existsSync8, realpathSync } from "node:fs";
-import { dirname as dirname10, join as join14, resolve } from "node:path";
+import { dirname as dirname10, join as join15, resolve } from "node:path";
 function resolveStudioDir() {
   const candidates = [];
   if (process.env.ASTRALE_STUDIO_DIR)
     candidates.push(process.env.ASTRALE_STUDIO_DIR);
   try {
     const entryDir = dirname10(realpathSync(process.argv[1] ?? ""));
-    candidates.push(join14(entryDir, "..", "studio"), join14(entryDir, "studio"));
+    candidates.push(join15(entryDir, "..", "studio"), join15(entryDir, "studio"));
   } catch {}
   for (const c of candidates) {
-    if (existsSync8(join14(c, "server", "index.ts")))
+    if (existsSync8(join15(c, "server", "index.ts")))
       return resolve(c);
   }
   throw new Error(`Domain Studio assets not found (looked in: ${candidates.join(", ") || "<none>"}). ` + `Reinstall the astrale CLI, or set ASTRALE_STUDIO_DIR to a studio checkout.`);
 }
 function isDevSource(studioDir) {
-  return existsSync8(join14(studioDir, "vite.config.ts")) && existsSync8(join14(studioDir, "client", "src"));
+  return existsSync8(join15(studioDir, "vite.config.ts")) && existsSync8(join15(studioDir, "client", "src"));
 }
 function resolveViteBin(studioDir) {
   for (const c of [
-    join14(studioDir, "node_modules", ".bin", "vite"),
-    join14(studioDir, "..", "..", "node_modules", ".bin", "vite")
+    join15(studioDir, "node_modules", ".bin", "vite"),
+    join15(studioDir, "..", "..", "node_modules", ".bin", "vite")
   ]) {
     if (existsSync8(c))
       return c;
@@ -71040,6 +71051,11 @@ var init_studio = __esm(() => {
       },
       { flags: "--prod", description: "Serve the prebuilt client (the default)" },
       { flags: "--schema-dir <dir>", description: "Schema entry dir to scan for (default: schema)" },
+      {
+        flags: "--harness <name>",
+        description: "Lock the agent harness for this Studio process",
+        choices: ["claude", "codex"]
+      },
       ...RAW_OUTPUT_OPTIONS
     ],
     afterHelpText: `
@@ -71063,6 +71079,10 @@ Behavior:
   By default the command just PRINTS the URL — it does not pop a browser (that's
   invasive when you already have a tab open). Pass --open to launch one.
 
+  Agent harness: choose Claude Code or Codex per domain in Studio Settings. Pass
+  --harness claude|codex to lock this process to one harness. Each harness uses
+  its existing local authentication and keeps an independent resumable session.
+
   The command stays attached and supervises its child processes; Ctrl-C tears
   them all down (a second Ctrl-C force-kills). With --json it prints a
   { url, port, mode, workspace } descriptor.
@@ -71071,6 +71091,7 @@ Examples:
   $ astrale studio                 # start the studio + print its URL (no browser)
   $ astrale studio --open          # …and open it in a browser
   $ astrale studio ./my-domain
+  $ astrale studio --harness codex
   $ astrale studio --port 4400
   $ astrale studio --dev           # live-edit the studio itself (from source)
 `,
@@ -71173,12 +71194,13 @@ Examples:
               DOMAIN_STUDIO_DEV: "1",
               VITE_URL: `http://127.0.0.1:${vitePort}`,
               PORT: String(studioPort),
-              DOMAIN_STUDIO_HOST: "127.0.0.1"
+              DOMAIN_STUDIO_HOST: "127.0.0.1",
+              ...opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}
             }
           }), "server");
         } else {
-          const dist = join14(studioDir, "client", "dist");
-          if (!existsSync8(join14(dist, "index.html"))) {
+          const dist = join15(studioDir, "client", "dist");
+          if (!existsSync8(join15(dist, "index.html"))) {
             throw new Error(`studio client not built at ${dist} — run: pnpm --filter @astrale-os/studio build`);
           }
           serverChild = supervise(spawnHandle("bun", ["server/index.ts", workspace, "--port", String(studioPort), "--no-open"], {
@@ -71188,7 +71210,8 @@ Examples:
               ...process.env,
               DOMAIN_STUDIO_DIST: dist,
               PORT: String(studioPort),
-              DOMAIN_STUDIO_HOST: "127.0.0.1"
+              DOMAIN_STUDIO_HOST: "127.0.0.1",
+              ...opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}
             }
           }), "server");
         }
@@ -73033,21 +73056,21 @@ var init_status4 = __esm(() => {
 
 // src/telemetry/store.ts
 import { existsSync as existsSync9, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
-import { join as join15 } from "node:path";
+import { join as join16 } from "node:path";
 function sessionsRoot() {
-  return join15(createPaths().home, "sessions");
+  return join16(createPaths().home, "sessions");
 }
 function sessionDir(id) {
-  return join15(sessionsRoot(), id);
+  return join16(sessionsRoot(), id);
 }
 function eventsPath(id) {
-  return join15(sessionDir(id), "events.jsonl");
+  return join16(sessionDir(id), "events.jsonl");
 }
 function metaPath(id) {
-  return join15(sessionDir(id), "meta.json");
+  return join16(sessionDir(id), "meta.json");
 }
 function markerPath(id) {
-  return join15(sessionDir(id), ".analyzed");
+  return join16(sessionDir(id), ".analyzed");
 }
 function readJsonSafe(path4) {
   try {
@@ -73125,12 +73148,12 @@ var init_list4 = __esm(() => {
 // src/telemetry/adapters/claude-code.ts
 import { existsSync as existsSync10, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join16 } from "node:path";
+import { join as join17 } from "node:path";
 function mungeCwd(cwd) {
   return cwd.replace(/[^a-zA-Z0-9]/g, "-");
 }
-function claudeCodeAdapter(base2 = join16(homedir3(), ".claude")) {
-  const projectsDir = join16(base2, "projects");
+function claudeCodeAdapter(base2 = join17(homedir3(), ".claude")) {
+  const projectsDir = join17(base2, "projects");
   function detect2() {
     try {
       return existsSync10(projectsDir);
@@ -73154,7 +73177,7 @@ function claudeCodeAdapter(base2 = join16(homedir3(), ".claude")) {
       for (const dir of dirs) {
         if (dir !== munged && !dir.startsWith(prefix))
           continue;
-        const projectPath = join16(projectsDir, dir);
+        const projectPath = join17(projectsDir, dir);
         let files;
         try {
           files = readdirSync3(projectPath);
@@ -73164,7 +73187,7 @@ function claudeCodeAdapter(base2 = join16(homedir3(), ".claude")) {
         for (const file2 of files) {
           if (!file2.endsWith(".jsonl"))
             continue;
-          const transcriptPath = join16(projectPath, file2);
+          const transcriptPath = join17(projectPath, file2);
           try {
             const st = statSync3(transcriptPath);
             const mtimeMs = st.mtime.getTime();
@@ -73200,7 +73223,7 @@ var init_claude_code = __esm(() => {
 import { existsSync as existsSync11, openSync as openSync2, readdirSync as readdirSync4, readSync, statSync as statSync4 } from "node:fs";
 import { closeSync as closeSync2 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-import { join as join17 } from "node:path";
+import { join as join18 } from "node:path";
 function readFirstLine(path4) {
   let fd = null;
   try {
@@ -73240,8 +73263,8 @@ function numericDirs(path4) {
     return [];
   }
 }
-function codexAdapter(base2 = join17(homedir4(), ".codex")) {
-  const sessionsDir = join17(base2, "sessions");
+function codexAdapter(base2 = join18(homedir4(), ".codex")) {
+  const sessionsDir = join18(base2, "sessions");
   function detect2() {
     try {
       return existsSync11(sessionsDir);
@@ -73256,12 +73279,12 @@ function codexAdapter(base2 = join17(homedir4(), ".codex")) {
       const endMs = window2.end.getTime();
       const lowerMs = startMs - DAY_MS;
       for (const yyyy of numericDirs(sessionsDir)) {
-        for (const mm of numericDirs(join17(sessionsDir, yyyy))) {
-          for (const dd of numericDirs(join17(sessionsDir, yyyy, mm))) {
+        for (const mm of numericDirs(join18(sessionsDir, yyyy))) {
+          for (const dd of numericDirs(join18(sessionsDir, yyyy, mm))) {
             const dayStart = Date.UTC(Number(yyyy), Number(mm) - 1, Number(dd));
             if (dayStart > endMs + DAY_MS || dayStart + DAY_MS <= lowerMs)
               continue;
-            scanDay(join17(sessionsDir, yyyy, mm, dd), root, startMs, endMs, sessions);
+            scanDay(join18(sessionsDir, yyyy, mm, dd), root, startMs, endMs, sessions);
           }
         }
       }
@@ -73283,7 +73306,7 @@ function scanDay(dayPath, root, startMs, endMs, out) {
   for (const file2 of files) {
     if (!file2.startsWith("rollout-") || !file2.endsWith(".jsonl"))
       continue;
-    const transcriptPath = join17(dayPath, file2);
+    const transcriptPath = join18(dayPath, file2);
     try {
       const st = statSync4(transcriptPath);
       const mtimeMs = st.mtime.getTime();
@@ -73430,7 +73453,7 @@ var init_gate = () => {};
 // src/telemetry/analyze.ts
 import { spawn as spawn3 } from "node:child_process";
 import { appendFileSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join18 } from "node:path";
+import { join as join19 } from "node:path";
 function writeMarker(id, marker) {
   writeFileSync2(markerPath(id), JSON.stringify(marker, null, 2) + `
 `);
@@ -73526,7 +73549,7 @@ async function analyzeSession(id, opts = {}) {
   const guides = new Map(adapters.map((a) => [a.name, a.readingGuide]));
   const prompt = buildPrompt({ id, root, signals: signals2, guides, file: opts.file ?? false });
   const dir = sessionDir(id);
-  writeFileSync2(join18(dir, "analyzer-prompt.md"), prompt);
+  writeFileSync2(join19(dir, "analyzer-prompt.md"), prompt);
   const outcome = await runClaude(prompt, dir, opts);
   const marker = {
     analyzedAt: new Date().toISOString(),
@@ -73534,7 +73557,7 @@ async function analyzeSession(id, opts = {}) {
     note: outcome.note
   };
   writeMarker(id, marker);
-  return { ...marker, reportPath: join18(dir, "report.md") };
+  return { ...marker, reportPath: join19(dir, "report.md") };
 }
 function runClaude(prompt, cwd, opts) {
   return new Promise((resolve2) => {
@@ -73564,7 +73587,7 @@ function runClaude(prompt, cwd, opts) {
     child.on("close", (code) => {
       clearTimeout(timer);
       try {
-        appendFileSync(join18(cwd, "analyzer.log"), out + (err ? `
+        appendFileSync(join19(cwd, "analyzer.log"), out + (err ? `
 --- stderr ---
 ${err}` : ""));
       } catch {}
@@ -73614,9 +73637,9 @@ var init_settings = __esm(() => {
 
 // src/telemetry/trigger.ts
 import { existsSync as existsSync12, mkdirSync as mkdirSync2, readFileSync as readFileSync6, rmSync as rmSync2, unlinkSync, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join19 } from "node:path";
+import { join as join20 } from "node:path";
 function lockPath() {
-  return join19(sessionsRoot(), ".analyzer.lock");
+  return join20(sessionsRoot(), ".analyzer.lock");
 }
 function releaseLock() {
   try {
@@ -74375,12 +74398,12 @@ function redactArgv(argv) {
 init_store2();
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync13, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname12, join as join20 } from "node:path";
+import { dirname as dirname12, join as join21 } from "node:path";
 var MAX_ID_LEN = 64;
 function findGitRoot(start) {
   let dir = start;
   for (;; ) {
-    if (existsSync13(join20(dir, ".git")))
+    if (existsSync13(join21(dir, ".git")))
       return dir;
     const parent = dirname12(dir);
     if (parent === dir)
@@ -74481,7 +74504,7 @@ init_settings();
 init_store2();
 import { spawn as spawn4 } from "node:child_process";
 import { existsSync as existsSync14, mkdirSync as mkdirSync4, readFileSync as readFileSync7, rmSync as rmSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join21 } from "node:path";
+import { join as join22 } from "node:path";
 var LOCK_STALE_MS2 = 30 * 60 * 1000;
 var GC_AGE_MS2 = 30 * 24 * 60 * 60 * 1000;
 var GC_MAX_PER_RUN = 20;
@@ -74500,7 +74523,7 @@ function gcOldSessions(sessions) {
   } catch {}
 }
 function lockPath2() {
-  return join21(sessionsRoot(), ".analyzer.lock");
+  return join22(sessionsRoot(), ".analyzer.lock");
 }
 function claimLock() {
   const path4 = lockPath2();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.7.0-alpha.0",
+  "version": "0.8.0-alpha.0",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -30,8 +30,7 @@
   "type": "module",
   "exports": {
     "./keys": "./src/lib/keys.ts",
-    "./paths": "./src/lib/paths.ts",
-    "./connect-core": "./src/connect-core.ts"
+    "./paths": "./src/lib/paths.ts"
   },
   "publishConfig": {
     "access": "public",

package/src/commands/studio.ts

@@ -16,6 +16,7 @@ type StudioOpts = RawOutputOpts & {
   dev?: boolean
   prod?: boolean
   schemaDir?: string
+  harness?: string
 }
 
 // Uncommon, safe bands in the IANA Registered range (well below the OS
@@ -162,6 +163,11 @@ export default {
     },
     { flags: '--prod', description: 'Serve the prebuilt client (the default)' },
     { flags: '--schema-dir <dir>', description: 'Schema entry dir to scan for (default: schema)' },
+    {
+      flags: '--harness <name>',
+      description: 'Lock the agent harness for this Studio process',
+      choices: ['claude', 'codex'],
+    },
     ...RAW_OUTPUT_OPTIONS,
   ],
   afterHelpText: `
@@ -185,6 +191,10 @@ Behavior:
   By default the command just PRINTS the URL — it does not pop a browser (that's
   invasive when you already have a tab open). Pass --open to launch one.
 
+  Agent harness: choose Claude Code or Codex per domain in Studio Settings. Pass
+  --harness claude|codex to lock this process to one harness. Each harness uses
+  its existing local authentication and keeps an independent resumable session.
+
   The command stays attached and supervises its child processes; Ctrl-C tears
   them all down (a second Ctrl-C force-kills). With --json it prints a
   { url, port, mode, workspace } descriptor.
@@ -193,6 +203,7 @@ Examples:
   $ astrale studio                 # start the studio + print its URL (no browser)
   $ astrale studio --open          # …and open it in a browser
   $ astrale studio ./my-domain
+  $ astrale studio --harness codex
   $ astrale studio --port 4400
   $ astrale studio --dev           # live-edit the studio itself (from source)
 `,
@@ -331,6 +342,7 @@ Examples:
                 VITE_URL: `http://127.0.0.1:${vitePort}`,
                 PORT: String(studioPort),
                 DOMAIN_STUDIO_HOST: '127.0.0.1',
+                ...(opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}),
               },
             },
           ),
@@ -355,6 +367,7 @@ Examples:
                 DOMAIN_STUDIO_DIST: dist,
                 PORT: String(studioPort),
                 DOMAIN_STUDIO_HOST: '127.0.0.1',
+                ...(opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}),
               },
             },
           ),