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

package/studio/server/agent/run/transcript.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { AgentRun } from '../../../shared/types'
+
+import { readJson, writeJson } from '../../state/store'
+import { currentRun, hydrateRun } from './live-state'
+import { readLastRun } from './transcript'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('reconciles a run orphaned by restart and hydrates its terminal snapshot', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-agent-transcript-'))
+  roots.push(root)
+  const domainId = `domain-${crypto.randomUUID()}`
+  const running: AgentRun = {
+    id: crypto.randomUUID(),
+    domainId,
+    harness: 'codex',
+    status: 'running',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    summary: 'interrupted work',
+    targetCommentIds: [],
+    events: [],
+    sessionId: 'thread-1',
+  }
+  writeJson(root, '.cache/agent/last-run.json', running)
+
+  expect(readLastRun(domainId, root)).toMatchObject({
+    status: 'interrupted',
+    sessionId: 'thread-1',
+    error: expect.stringContaining('studio restarted'),
+  })
+  expect(readJson<AgentRun>(root, '.cache/agent/last-run.json', running).status).toBe('interrupted')
+
+  hydrateRun(domainId, root)
+  expect(currentRun(domainId)).toMatchObject({
+    status: 'interrupted',
+    sessionId: 'thread-1',
+  })
+})

package/studio/server/agent/run/transcript.ts

@@ -0,0 +1,30 @@
+import type { AgentRun } from '../../../shared/types'
+
+import { readJson, writeJson } from '../../state/store'
+
+const LAST_RUN_FILE = '.cache/agent/last-run.json'
+const runFile = (id: string) => `.cache/agent/runs/${id}.json`
+
+/** Persist the latest run pointer and, when terminal, its transcript. */
+export function persistRun(root: string, run: AgentRun, transcript = false): void {
+  try {
+    writeJson(root, LAST_RUN_FILE, run)
+    if (transcript) writeJson(root, runFile(run.id), run)
+  } catch {
+    /* run history is best-effort */
+  }
+}
+
+/** Rehydrate the latest run and reconcile one orphaned by a Studio restart. */
+export function readLastRun(domainId: string, root: string): AgentRun | null {
+  const last = readJson<AgentRun | null>(root, LAST_RUN_FILE, null)
+  if (!last || last.domainId !== domainId) return null
+  if (last.status === 'running' || last.status === 'queued') {
+    last.status = 'interrupted'
+    last.finishedAt = last.finishedAt ?? new Date().toISOString()
+    last.error =
+      'the studio restarted during this turn — your conversation is preserved; submit again to continue'
+    persistRun(root, last)
+  }
+  return last
+}

package/studio/server/agent/run/usage.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { AgentRun } from '../../../shared/types'
+
+import { readUsage, recordRun } from './usage'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function run(values: Partial<AgentRun>): AgentRun {
+  return {
+    id: crypto.randomUUID(),
+    domainId: 'test',
+    harness: 'mock',
+    status: 'succeeded',
+    createdAt: new Date().toISOString(),
+    summary: 'test',
+    targetCommentIds: [],
+    events: [],
+    ...values,
+  }
+}
+
+test('records only reported usage and accumulates domain totals', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-agent-usage-'))
+  roots.push(root)
+  recordRun(root, run({}))
+  expect(readUsage(root)).toEqual({ runs: 0, tokens: 0, costUsd: 0 })
+
+  recordRun(root, run({ tokens: 10, costUsd: 0.25, finishedAt: '2026-01-01T00:00:00.000Z' }))
+  recordRun(root, run({ tokens: 5, costUsd: 0.1, finishedAt: '2026-01-02T00:00:00.000Z' }))
+  expect(readUsage(root)).toMatchObject({
+    runs: 2,
+    tokens: 15,
+    costUsd: 0.35,
+    lastRunAt: '2026-01-02T00:00:00.000Z',
+    lastTokens: 5,
+    lastCostUsd: 0.1,
+  })
+})

package/studio/server/{state → agent/run}/usage.ts

@@ -1,12 +1,12 @@
 /**
  * usage.ts — domain-attributable agent spend. Accumulates tokens + USD from THIS
- * studio's own agent runs on THIS domain (not machine-wide — that lives in
- * ~/.claude/stats-cache.json and is out of scope here). Stored at
+ * studio's own agent runs on THIS domain (not the selected harness's machine-wide
+ * usage, which is out of scope here). Stored at
  * `.domain-studio/usage.json`; surfaced read-only in the Settings dialog.
  */
-import type { AgentRun, DomainUsage } from '../../shared/types'
+import type { AgentRun, DomainUsage } from '../../../shared/types'
 
-import { readJson, writeJson } from './store'
+import { readJson, writeJson } from '../../state/store'
 
 const PATH = 'usage.json'
 

package/studio/server/agent/stream.ts

@@ -0,0 +1,37 @@
+/** Lifecycle-safe NDJSON writer for cancellable agent response streams. */
+export class NdjsonChannel {
+  private readonly encoder = new TextEncoder()
+  private closed = false
+
+  constructor(
+    private readonly target: ReadableStreamDefaultController<Uint8Array>,
+    private readonly abortController: AbortController,
+  ) {}
+
+  send(value: unknown): boolean {
+    if (this.closed) return false
+    try {
+      this.target.enqueue(this.encoder.encode(`${JSON.stringify(value)}\n`))
+      return true
+    } catch {
+      this.cancel()
+      return false
+    }
+  }
+
+  close(): void {
+    if (this.closed) return
+    this.closed = true
+    try {
+      this.target.close()
+    } catch {
+      /* client already canceled */
+    }
+  }
+
+  cancel(): void {
+    if (this.closed) return
+    this.closed = true
+    this.abortController.abort()
+  }
+}

package/studio/server/agent/{session-id.ts → telemetry.ts}

@@ -1,5 +1,5 @@
 /**
- * Explicit telemetry session id for studio-driven agents. Injected as
+ * Explicit telemetry session id for Studio-driven agents. Injected as
  * ASTRALE_SESSION into the harness child so every `astrale` call it makes
  * buckets into one surface-owned session per domain per hour (hour scoping
  * keeps a post-analysis resume from reopening an analyzed session in the

package/studio/server/api-agent-loadout.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { setHarnessGateway } from './agent/harness/gateway/config'
+import { getHarness } from './agent/harness/selection'
+import { handleApi } from './api'
+import { registerDomain, unregisterDomain } from './domain'
+
+const roots: string[] = []
+const domainIds: string[] = []
+const originalHarness = process.env.DOMAIN_STUDIO_HARNESS
+let restoreLoadout: (() => void) | undefined
+
+afterEach(() => {
+  restoreLoadout?.()
+  restoreLoadout = undefined
+  if (originalHarness === undefined) delete process.env.DOMAIN_STUDIO_HARNESS
+  else process.env.DOMAIN_STUDIO_HARNESS = originalHarness
+  while (domainIds.length) unregisterDomain(domainIds.pop()!)
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('loadout fails closed instead of probing ambient Claude when gateway auth fails', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-loadout-gateway-'))
+  roots.push(root)
+  mkdirSync(join(root, 'schema'))
+  writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+  writeFileSync(join(root, 'domain.ts'), 'export default {}\n')
+  writeFileSync(join(root, 'schema/index.ts'), 'export const Test = {}\n')
+  const handle = registerDomain(root)!
+  domainIds.push(handle.id)
+
+  process.env.DOMAIN_STUDIO_HARNESS = 'claude'
+  const harness = getHarness(root)
+  const originalLoadout = harness.loadout
+  let probes = 0
+  harness.loadout = async () => {
+    probes += 1
+    throw new Error('ambient Claude must not be probed')
+  }
+  restoreLoadout = () => {
+    harness.loadout = originalLoadout
+  }
+  setHarnessGateway(root, {
+    scope: 'domain',
+    config: {
+      enabled: true,
+      baseUrl: 'https://gateway.example/v1/models/test',
+      auth: { mode: 'host' },
+    },
+  })
+
+  const url = new URL(`http://127.0.0.1/api/domain/${encodeURIComponent(handle.id)}/agent/loadout`)
+  const response = await handleApi(new Request(url), url, () => {})
+  expect(response?.status).toBe(200)
+  const body = await response!.json()
+  expect(body).toMatchObject({
+    ok: false,
+    tools: [],
+    mcpServers: [],
+    skills: [],
+    agents: [],
+  })
+  expect(body.detail).toContain('model gateway auth failed')
+  expect(body.detail).toContain('no valid host-supplied token')
+  expect(probes).toBe(0)
+})

package/studio/server/api.ts

@@ -4,16 +4,7 @@
  */
 import type { StudioEvent } from '../shared/types'
 
-import { buildSystemPrompt } from './agent/prompt'
-import { getHarness, listHarnesses } from './agent/registry'
-import {
-  cancelRun,
-  getSessionId,
-  getSnapshot,
-  resetConversation,
-  setSessionId,
-  submitRun,
-} from './agent/runner'
+import { handleAgentRoute } from './agent/routes'
 import { getBundle, getAnatomy, getCore, invalidate } from './cache'
 import { type DomainHandle, allDomains, depsInstalled, getDomain } from './domain'
 import { schemaRefs } from './introspect/schema-refs'
@@ -47,14 +38,6 @@ import {
 import { isEnvName, readEnvModel, writeEnvUpdates } from './state/env'
 import { detectGit } from './state/git'
 import { refreshAuto } from './state/handoff'
-import {
-  clearHarnessGateway,
-  gatewayAudience,
-  getHarnessGatewayState,
-  resolveHarnessEnv,
-  setHarnessGateway,
-} from './state/harness-gateway'
-import { setHostToken } from './state/harness-token'
 import {
   activeInstanceName,
   instanceStatus,
@@ -66,7 +49,6 @@ import { deleteIntegration, readIntegrations, upsertIntegration } from './state/
 import { readLayout, resetLayout, saveLayout, setNodePositions } from './state/layout'
 import { readSettings, updateSettings } from './state/settings'
 import { applyUpdates, getUpdates } from './state/updates'
-import { readUsage } from './state/usage'
 import { closeViewSession, getViewRuntime, launchViewSession } from './state/views'
 import { readVisibility, resetVisibility, saveVisibility } from './state/visibility'
 import { restartViewDevServer } from './view-dev-server'
@@ -331,142 +313,8 @@ export async function handleApi(req: Request, url: URL, notify: Notify): Promise
     }
   }
 
-  // ── agent loop (live, harness-agnostic) ──
-  if (rest === '/agent') {
-    if (req.method === 'GET') return json(await getSnapshot(id))
-    return badReq('use /agent/submit or /agent/cancel')
-  }
-  if (rest === '/agent/submit' && req.method === 'POST') {
-    const r = await submitRun(handle, notify, {
-      message: typeof body.message === 'string' ? body.message : undefined,
-      resume: body.resume === true,
-    })
-    // 200 + {error} (not 409) — the rejections ("already running" / "no open threads")
-    // are expected states, surfaced as a friendly client toast rather than a thrown error.
-    return r.error ? json({ error: r.error }) : json(r.run)
-  }
-  if (rest === '/agent/cancel' && req.method === 'POST') {
-    return json({ ok: cancelRun(id) })
-  }
-  if (rest === '/agent/reset' && req.method === 'POST') {
-    // forget the resumable conversation — the next submit starts a fresh session
-    return json({ ok: resetConversation(id) })
-  }
-  if (rest === '/agent/session') {
-    if (req.method === 'GET') return json(getSessionId(id))
-    if (req.method === 'POST') {
-      const ok = setSessionId(id, typeof body.sessionId === 'string' ? body.sessionId : '')
-      if (!ok) return badReq('the session id cannot be changed while a turn is running')
-      return json(getSessionId(id))
-    }
-    return badReq('GET or POST')
-  }
-  if (rest === '/agent/prompt/system' && req.method === 'GET') {
-    return json({ bridge: true, systemPrompt: buildSystemPrompt({ bridge: true }) })
-  }
-  if (rest === '/agent/harness' && req.method === 'GET') {
-    const h = getHarness()
-    const health = h.health
-      ? await h.health()
-      : { ok: await h.isAvailable(), bin: h.id, version: undefined, detail: undefined }
-    const options = listHarnesses().filter((o) => o.id !== 'mock' || o.id === h.id)
-    const message = health.ok
-      ? `Detected${health.version ? ` — ${health.version}` : ''}`
-      : (health.detail ?? `${h.label} is not detected. Is it installed and on your PATH?`)
-    return json({
-      id: h.id,
-      label: h.label,
-      bin: health.bin ?? h.id,
-      ok: health.ok,
-      version: health.version,
-      message,
-      options,
-    })
-  }
-  // What the harness ACTUALLY loaded for this domain's cwd — skills (reconciled against
-  // on-disk installs), MCP servers + status, tools, agents. Read-only window into the agent.
-  if (rest === '/agent/loadout' && req.method === 'GET') {
-    const h = getHarness()
-    if (!h.loadout)
-      return json({
-        ok: false,
-        detail: `${h.label} does not expose a loadout`,
-        tools: [],
-        mcpServers: [],
-        skills: [],
-        agents: [],
-        builtinCommandCount: 0,
-        probedAt: Date.now(),
-      })
-    const er = await resolveHarnessEnv(root)
-    return json(await h.loadout(root, er.ok ? er.env : undefined))
-  }
-  // Custom model-gateway config for the harness (per-domain + studio-global), e.g.
-  // routing Claude Code through an Astrale ai-gateway model node. The token/url are
-  // injected into the harness CHILD only — never the studio env or the user's shell.
-  if (rest === '/agent/harness-gateway') {
-    if (req.method === 'GET') return json(getHarnessGatewayState(root))
-    if (req.method === 'POST') {
-      const scope = body.scope === 'global' ? 'global' : 'domain'
-      if (body.action === 'set')
-        return json(setHarnessGateway(root, { scope, config: body.config ?? {} }))
-      if (body.action === 'clear') return json(clearHarnessGateway(root, scope))
-      return badReq('unknown harness-gateway action')
-    }
-  }
-  // EMBED seam: when the studio runs inside the Astrale GUI, the host (which holds
-  // the shell connection) relays a delegation token here for `host` auth mode. It
-  // is keyed by the configured gateway's audience and kept in memory only.
-  if (rest === '/agent/harness-gateway/host-token' && req.method === 'POST') {
-    const audience = gatewayAudience(root)
-    if (!audience) return badReq('no gateway base URL configured for this domain')
-    return json({ ok: setHostToken(audience, String(body.token ?? '')) })
-  }
-  // Domain-attributable agent spend (this studio's runs on this domain only).
-  if (rest === '/agent/usage' && req.method === 'GET') return json(readUsage(root))
-  // Raw SKILL.md for a skill command (the "view skill" action).
-  if (rest === '/agent/skill' && req.method === 'GET') {
-    const command = url.searchParams.get('command')
-    const h = getHarness()
-    if (!command || !h.skillContent) return notFound()
-    const c = await h.skillContent(root, command)
-    return c ? json(c) : notFound()
-  }
-  // Ask: a quick, ephemeral, FORKED side-question — streamed as newline-delimited
-  // JSON ({delta} chunks then a final {done}|{error}). Bypasses the run lock and
-  // never touches comments.json or the parent session.
-  if (rest === '/agent/ask' && req.method === 'POST') {
-    const { runAsk } = await import('./agent/ask')
-    const ctrl = new AbortController()
-    req.signal?.addEventListener('abort', () => ctrl.abort(), { once: true }) // client disconnect → kill the fork
-    const enc = new TextEncoder()
-    const stream = new ReadableStream<Uint8Array>({
-      async start(controller) {
-        const send = (o: unknown) => controller.enqueue(enc.encode(`${JSON.stringify(o)}\n`))
-        try {
-          const result = await runAsk(handle, body, ctrl.signal, (delta) => send({ delta }))
-          send(
-            result.isError ? { error: result.errorMessage || 'ask failed' } : { done: result.text },
-          )
-        } catch (e: any) {
-          send({ error: String(e?.message ?? e) })
-        } finally {
-          controller.close()
-        }
-      },
-      cancel() {
-        ctrl.abort()
-      },
-    })
-    return new Response(stream, {
-      headers: { 'content-type': 'application/x-ndjson', 'cache-control': 'no-cache' },
-    })
-  }
-  // bridge write-back routes (token-guarded) handled by the agent bridge module
-  if (rest.startsWith('/agent/bridge/')) {
-    const { handleBridge } = await import('./agent/bridge')
-    return handleBridge(handle, rest.slice('/agent/bridge/'.length), req, body, notify)
-  }
+  const agentResponse = await handleAgentRoute({ req, url, rest, body, handle, notify })
+  if (agentResponse) return agentResponse
 
   // ── context ──
   if (rest === '/context') {

package/studio/server/index.ts

@@ -11,7 +11,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
-import { setBridgePort } from './agent/bridge'
+import { setBridgePort } from './agent/bridge/grant'
 import { handleApi } from './api'
 import { resolveTarget } from './detect'
 import { allDomains } from './domain'
@@ -90,9 +90,10 @@ function serveStatic(pathname: string): Response {
   )
 }
 
-// Bind to loopback by default. The studio triggers a LOCAL agent that edits code
-// and runs shell (bypassPermissions) — exposing the trigger on 0.0.0.0 would be
-// RCE on the LAN. Power users behind a trusted tunnel can opt in via DOMAIN_STUDIO_HOST.
+// Bind to loopback by default. Studio can trigger a LOCAL harness that edits code
+// and runs commands with the configured access level — exposing the trigger on
+// 0.0.0.0 would be RCE on the LAN. Power users behind a trusted tunnel can opt in
+// via DOMAIN_STUDIO_HOST.
 const HOST = process.env.DOMAIN_STUDIO_HOST || '127.0.0.1'
 const LOOPBACK = HOST === '127.0.0.1' || HOST === 'localhost' || HOST === '::1'
 
@@ -136,7 +137,7 @@ if (!LOOPBACK) {
   console.warn(
     `  ⚠ SECURITY: bound to ${HOST} (not loopback). The Submit-to-agent trigger is the\n` +
       `    only thing standing between the network and an agent that edits code + runs shell\n` +
-      `    (bypassPermissions). Anyone who can reach this port can trigger it. Use only behind\n` +
+      `    with its configured access. Anyone who can reach this port can trigger it. Use only behind\n` +
       `    a trusted tunnel; unset DOMAIN_STUDIO_HOST to bind 127.0.0.1.\n`,
   )
 }

package/studio/server/state/comments.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { readComments, upsertComment } from './comments'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('missing comment stores do not share entries across domains', () => {
+  const rootA = mkdtempSync(join(tmpdir(), 'studio-comments-a-'))
+  const rootB = mkdtempSync(join(tmpdir(), 'studio-comments-b-'))
+  roots.push(rootA, rootB)
+
+  upsertComment(rootA, {
+    anchors: ['A'],
+    anchorRefs: [{ ref: 'class.A', kind: 'schema' }],
+    text: 'only in A',
+  })
+
+  expect(readComments(rootA).comments.map((comment) => comment.thread[0]!.text)).toEqual([
+    'only in A',
+  ])
+  expect(readComments(rootB).comments).toEqual([])
+})

package/studio/server/state/comments.ts

@@ -14,10 +14,10 @@ import { readJson, writeJson } from './store'
 
 const FILE = 'comments.json'
 
-const EMPTY: CommentStore = { schemaVersion: '', comments: [] }
-
 export function readComments(root: string): CommentStore {
-  const store = readJson<CommentStore>(root, FILE, { ...EMPTY })
+  // Allocate a fresh array for every missing store. A module-level EMPTY object
+  // would share its nested `comments` array across domains until each persisted.
+  const store = readJson<CommentStore>(root, FILE, { schemaVersion: '', comments: [] })
   return {
     schemaVersion: store.schemaVersion ?? '',
     comments: Array.isArray(store.comments) ? store.comments : [],

package/studio/server/state/settings.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { readSettings, updateSettings } from './settings'
+import { writeJson } from './store'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('remembers sanitized model overrides independently per harness', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-settings-models-'))
+  roots.push(root)
+
+  const saved = updateSettings(root, {
+    agentModels: {
+      ' Codex ': ' gpt-5.6-sol ',
+      claude: ' opus ',
+      empty: ' ',
+    },
+  })
+
+  expect(saved.agentModels).toEqual({
+    codex: 'gpt-5.6-sol',
+    claude: 'opus',
+  })
+  expect(readSettings(root).agentModels).toEqual(saved.agentModels)
+})
+
+test('rejects malformed model maps and entries without discarding unrelated settings', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-settings-bad-models-'))
+  roots.push(root)
+  writeJson(root, 'settings.json', { agentModels: ['gpt-bad'], agentEffort: 'low' })
+
+  const settings = readSettings(root)
+  expect(settings.agentModels).toEqual({})
+  expect(settings.agentEffort).toBe('low')
+
+  writeJson(root, 'settings.json', {
+    agentModels: { codex: null, claude: { id: 'opus' }, valid: ' model-ok ' },
+  })
+  expect(readSettings(root).agentModels).toEqual({ valid: 'model-ok' })
+})
+
+test('drops destructive timing values from disk and API patches', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-settings-timings-'))
+  roots.push(root)
+  writeJson(root, 'settings.json', {
+    introspectTimeoutMs: -1,
+    instancePollMs: 1_000.5,
+    updatesPollMs: 9_999,
+    viewProbeTimeoutMs: 120_001,
+  })
+
+  expect(readSettings(root)).toMatchObject({
+    introspectTimeoutMs: 20_000,
+    instancePollMs: 30_000,
+    updatesPollMs: 600_000,
+    viewProbeTimeoutMs: 8_000,
+  })
+
+  const saved = updateSettings(root, {
+    introspectTimeoutMs: Number.POSITIVE_INFINITY,
+    instancePollMs: 1_000,
+    updatesPollMs: 86_400_000,
+    viewProbeTimeoutMs: 250,
+  })
+  expect(saved).toMatchObject({
+    introspectTimeoutMs: 20_000,
+    instancePollMs: 1_000,
+    updatesPollMs: 86_400_000,
+    viewProbeTimeoutMs: 250,
+  })
+})

package/studio/server/state/settings.ts

@@ -4,13 +4,20 @@
  * `.domain-studio/settings.json`; missing keys fall back to DEFAULT_SETTINGS.
  * Surfaced subtly in the UI (command palette + a faint gear) for power users.
  */
-import { AGENT_EFFORT_LEVELS, type StudioSettings } from '../../shared/types'
+import {
+  parseStudioNumericSetting,
+  STUDIO_NUMERIC_LIMITS,
+  type NumericStudioSetting,
+} from '../../shared/settings-values'
+import { AGENT_ACCESS_LEVELS, AGENT_EFFORT_LEVELS, type StudioSettings } from '../../shared/types'
 import { readJson, writeJson } from './store'
 
 const PATH = 'settings.json'
 
 export const DEFAULT_SETTINGS: StudioSettings = {
   agentEffort: 'high',
+  agentAccess: 'full',
+  agentModels: {},
   integrationsDir: 'integrations',
   introspectTimeoutMs: 20000,
   instancePollMs: 30000,
@@ -20,8 +27,28 @@ export const DEFAULT_SETTINGS: StudioSettings = {
 
 function normalizeSettings(input: Partial<StudioSettings>): Partial<StudioSettings> {
   const out = { ...input }
+  for (const key of Object.keys(STUDIO_NUMERIC_LIMITS) as NumericStudioSetting[]) {
+    if (out[key] === undefined) continue
+    const value = parseStudioNumericSetting(key, out[key])
+    if (value === null) delete out[key]
+    else out[key] = value
+  }
   if (out.agentEffort !== undefined && !AGENT_EFFORT_LEVELS.includes(out.agentEffort as any))
     delete out.agentEffort
+  if (out.agentAccess !== undefined && !AGENT_ACCESS_LEVELS.includes(out.agentAccess as any))
+    delete out.agentAccess
+  if (out.agentModels !== undefined) {
+    if (!out.agentModels || typeof out.agentModels !== 'object' || Array.isArray(out.agentModels)) {
+      delete out.agentModels
+    } else {
+      out.agentModels = Object.fromEntries(
+        Object.entries(out.agentModels)
+          .filter((entry): entry is [string, string] => typeof entry[1] === 'string')
+          .map(([harness, model]) => [harness.trim().toLowerCase(), model.trim()])
+          .filter(([harness, model]) => !!harness && !!model),
+      )
+    }
+  }
   return out
 }
 

package/studio/shared/agent-effort.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from 'bun:test'
+
+import { effectiveAgentEffort } from './agent-effort'
+
+test('normalizes persisted effort when switching harness vocabularies', () => {
+  expect(effectiveAgentEffort(['low', 'medium', 'high', 'xhigh'], 'max')).toBe('xhigh')
+  expect(effectiveAgentEffort(['low', 'medium', 'high', 'xhigh'], 'ultracode')).toBe('xhigh')
+  expect(effectiveAgentEffort(['low', 'medium', 'high'], 'minimal')).toBe('low')
+  expect(effectiveAgentEffort(['medium', 'high'], 'xhigh')).toBe('high')
+  expect(effectiveAgentEffort(['medium'], 'low')).toBe('medium')
+  expect(effectiveAgentEffort(['low'], undefined)).toBeUndefined()
+})