@astrale-os/cli 0.4.0-alpha.13

package/studio/server/state/harness-gateway.ts

@@ -0,0 +1,181 @@
+/**
+ * harness-gateway.ts — point the agent harness at a custom Anthropic-compatible
+ * model gateway (e.g. an Astrale `ai-gateway` model node) instead of Claude
+ * Code's built-in auth. Two scopes, layered:
+ *   - per-domain : `<domain>/.domain-studio/harness-gateway.json` — AUTHORITATIVE
+ *                  when present (its presence is the override, even when disabled).
+ *   - global     : `~/.domain-studio/harness-gateway.json` — the studio-wide
+ *                  default applied to every domain that has no local override.
+ *
+ * The config never escapes the studio's spawned child: `harnessGatewayEnv` turns
+ * it into ANTHROPIC_* env that runner / ask / loadout merge into the `claude`
+ * subprocess env ONLY — never the studio's own process env, the user's shell, or
+ * a `claude` they run themselves outside the studio.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import type {
+  HarnessGatewayAuth,
+  HarnessGatewayConfig,
+  HarnessGatewayState,
+} from '../../shared/types'
+
+import { acquireGatewayToken } from './harness-token'
+import { readJson, removeState, writeJson } from './store'
+
+/** Per-domain file (lives under the domain's `.domain-studio/`, gitignored). */
+const LOCAL_FILE = 'harness-gateway.json'
+/** Studio-wide default — a sibling-named hidden dir in the user's home. */
+const GLOBAL_FILE = join(homedir(), '.domain-studio', 'harness-gateway.json')
+
+/** Coerce a wire/disk auth block into a well-formed discriminated union. Default
+ *  is `mint` (no secret on disk). A legacy `{ apiKey }` shape maps to `token` mode. */
+function normalizeAuth(input: any): HarnessGatewayAuth {
+  if (input?.mode === 'token' || (input?.token != null && input?.mode == null))
+    return { mode: 'token', token: typeof input.token === 'string' ? input.token.trim() : '' }
+  if (input?.mode === 'host') return { mode: 'host' }
+  const instance = typeof input?.instance === 'string' ? input.instance.trim() : ''
+  return { mode: 'mint', ...(instance ? { instance } : {}) }
+}
+
+/** Coerce a wire/disk value into a well-formed config (trim, drop blanks). */
+function normalize(input: any): HarnessGatewayConfig {
+  const model = typeof input?.model === 'string' ? input.model.trim() : ''
+  // back-compat: a pre-union config stored only `apiKey` → treat as a static token
+  const authInput =
+    input?.auth ?? (typeof input?.apiKey === 'string' ? { mode: 'token', token: input.apiKey } : undefined)
+  return {
+    enabled: input?.enabled === true,
+    baseUrl: typeof input?.baseUrl === 'string' ? input.baseUrl.trim() : '',
+    ...(model ? { model } : {}),
+    auth: normalizeAuth(authInput),
+  }
+}
+
+function readLocal(root: string): HarnessGatewayConfig | null {
+  const raw = readJson<HarnessGatewayConfig | null>(root, LOCAL_FILE, null)
+  return raw ? normalize(raw) : null
+}
+
+function readGlobal(): HarnessGatewayConfig | null {
+  if (!existsSync(GLOBAL_FILE)) return null
+  try {
+    return normalize(JSON.parse(readFileSync(GLOBAL_FILE, 'utf8')))
+  } catch {
+    return null
+  }
+}
+
+/** Write (or, on null, delete) the global default. Not under any domain root, so
+ *  it bypasses the store's domain-scoped write-allowlist by design. */
+function writeGlobal(cfg: HarnessGatewayConfig | null): void {
+  if (cfg === null) {
+    if (existsSync(GLOBAL_FILE)) rmSync(GLOBAL_FILE, { force: true })
+    return
+  }
+  mkdirSync(dirname(GLOBAL_FILE), { recursive: true })
+  writeFileSync(GLOBAL_FILE, JSON.stringify(cfg, null, 2))
+}
+
+/** Resolve the layered state. A PRESENT local override wins outright — even when
+ *  disabled, which is exactly how you turn the gateway off for one domain despite
+ *  a global default. With no local override, the global default applies. */
+export function getHarnessGatewayState(root: string): HarnessGatewayState {
+  const local = readLocal(root)
+  const global = readGlobal()
+  if (local) {
+    return { local, global, effective: local.enabled ? local : null, source: local.enabled ? 'domain' : 'none' }
+  }
+  return {
+    local: null,
+    global,
+    effective: global?.enabled ? global : null,
+    source: global?.enabled ? 'global' : 'none',
+  }
+}
+
+export interface SetHarnessGatewayInput {
+  scope: 'domain' | 'global'
+  config: Partial<HarnessGatewayConfig>
+}
+
+/** Persist the config to the chosen scope. Writing GLOBAL also clears any local
+ *  override so this domain (and every un-overridden one) inherits it — that is the
+ *  "apply to all domains" intent. */
+export function setHarnessGateway(root: string, input: SetHarnessGatewayInput): HarnessGatewayState {
+  const cfg = normalize(input.config)
+  if (input.scope === 'global') {
+    writeGlobal(cfg)
+    removeState(root, LOCAL_FILE)
+  } else {
+    writeJson(root, LOCAL_FILE, cfg)
+  }
+  return getHarnessGatewayState(root)
+}
+
+/** Drop the override at a scope (revert to the layer below / default harness auth). */
+export function clearHarnessGateway(root: string, scope: 'domain' | 'global'): HarnessGatewayState {
+  if (scope === 'global') writeGlobal(null)
+  else removeState(root, LOCAL_FILE)
+  return getHarnessGatewayState(root)
+}
+
+/** The config that takes effect for a domain (or undefined ⇒ default harness auth). */
+export function resolveHarnessGateway(root: string): HarnessGatewayConfig | undefined {
+  return getHarnessGatewayState(root).effective ?? undefined
+}
+
+/** The gateway audience (origin) for a domain's effective config — the token
+ *  audience to mint/relay for. Null when no gateway is configured / URL invalid. */
+export function gatewayAudience(root: string): string | null {
+  const cfg = resolveHarnessGateway(root)
+  if (!cfg?.enabled || !cfg.baseUrl) return null
+  try {
+    return new URL(cfg.baseUrl).origin
+  } catch {
+    return null
+  }
+}
+
+/** Either the ANTHROPIC_* env to inject (empty ⇒ no gateway configured), or a
+ *  human error when a gateway IS configured but its token can't be obtained — so
+ *  callers fail loudly instead of silently falling back to the default Claude auth. */
+export type HarnessEnvResult =
+  | { ok: true; env: Record<string, string> }
+  | { ok: false; error: string }
+
+/**
+ * Resolve the ANTHROPIC_* env for a domain's harness child. Derives the gateway
+ * audience from the URL, acquires the bearer token per auth mode (mint / static /
+ * host-supplied), and sets `ANTHROPIC_AUTH_TOKEN` (Authorization: Bearer — the
+ * custom-gateway path, which sidesteps the x-api-key approval prompt) plus the
+ * model labels. The Astrale gateway pins the real model by URL, so `model` is
+ * only for display.
+ */
+export async function resolveHarnessEnv(root: string): Promise<HarnessEnvResult> {
+  const cfg = resolveHarnessGateway(root)
+  if (!cfg || !cfg.enabled || !cfg.baseUrl) return { ok: true, env: {} }
+  let audience: string
+  try {
+    audience = new URL(cfg.baseUrl).origin
+  } catch {
+    return { ok: false, error: `invalid gateway base URL: ${cfg.baseUrl}` }
+  }
+  let token: string
+  try {
+    token = await acquireGatewayToken(cfg, audience)
+  } catch (e) {
+    return { ok: false, error: (e as Error)?.message ?? String(e) }
+  }
+  const env: Record<string, string> = {
+    ANTHROPIC_BASE_URL: cfg.baseUrl,
+    ANTHROPIC_AUTH_TOKEN: token,
+  }
+  if (cfg.model) {
+    env.ANTHROPIC_MODEL = cfg.model
+    env.ANTHROPIC_SMALL_FAST_MODEL = cfg.model
+  }
+  return { ok: true, env }
+}

package/studio/server/state/instance.ts

@@ -0,0 +1,244 @@
+/**
+ * state/instance.ts — the deploy/install bridge to Astrale.
+ *
+ * The ACTIVE instance is GLOBAL (not per-domain) and the `astrale` CLI owns it —
+ * we never keep our own copy: `listInstances` reads `astrale instance list`,
+ * `setActiveInstance` runs `astrale instance use`. Install + drift are GROUND
+ * TRUTH, queried from the target instance (`astrale get /<origin>`) — NOT a local
+ * record — so a deploy done outside the studio (CLI/terminal) is still seen.
+ *
+ * Deploy (`pnpm prod`) = the managed astrale adapter: deploy + auto-install on
+ * the configured instance; we capture the printed service URL.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type {
+  DeployRecord,
+  DeployResult,
+  InstanceInfo,
+  InstanceStatus,
+  InstancesState,
+} from '../../shared/types'
+import type { DomainHandle } from '../domain'
+
+import { schemaHashOf } from '../introspect/hash'
+import { readJson, writeJson } from './store'
+
+const DEPLOY_REC = 'deploy.json'
+
+function hasProdScript(root: string): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+    return typeof pkg?.scripts?.prod === 'string'
+  } catch {
+    return false
+  }
+}
+
+async function astraleJson(args: string[]): Promise<any | null> {
+  try {
+    const proc = Bun.spawn(['astrale', ...args], { stdout: 'pipe', stderr: 'ignore' })
+    const out = await new Response(proc.stdout).text()
+    await proc.exited
+    return JSON.parse(out)
+  } catch {
+    return null
+  }
+}
+
+// ── global: the CLI's instances (source of truth = `astrale instance ...`) ──
+
+/** The active instance name — from `astrale instance active` (local, reliable). */
+async function activeName(): Promise<string | null> {
+  const a = await astraleJson(['instance', 'active', '--json'])
+  return a?.name ?? null
+}
+
+/** Public wrapper — the create-domain endpoint stamps this as `--instance` on the scaffold. */
+export const activeInstanceName = activeName
+
+export async function listInstances(): Promise<InstancesState> {
+  // The plain `instance list` fetches signing keys for EVERY bookmark, so one
+  // unreachable bookmark (e.g. a stopped localhost kernel) errors out the whole
+  // command. `--bookmarked` is local-only (reliable); `--admin-only` adds the
+  // managed instances best-effort (skipped if the admin call is unavailable).
+  const local = await astraleJson(['instance', 'list', '--bookmarked', '--json'])
+  const active: string | null = local?.active ?? (await activeName())
+  const instances: InstanceInfo[] = []
+  for (const b of local?.bookmarks ?? []) {
+    instances.push({
+      name: b.name,
+      url: b.url ?? '',
+      active: !!b.active || b.name === active,
+      kind: 'bookmark',
+    })
+  }
+  const managed = await astraleJson(['instance', 'list', '--admin-only', '--json'])
+  for (const m of managed?.instances ?? []) {
+    if (!m.slug || instances.some((i) => i.name === m.slug)) continue
+    instances.push({ name: m.slug, url: m.url ?? '', active: m.slug === active, kind: 'managed' })
+  }
+  if (active && !instances.some((i) => i.name === active)) {
+    instances.unshift({ name: active, url: '', active: true, kind: 'bookmark' })
+  }
+  return { active, instances }
+}
+
+export async function setActiveInstance(
+  name: string,
+): Promise<{ ok: boolean; active: string | null; output: string }> {
+  try {
+    // --adopt-default: never block on an interactive identity prompt;
+    // --skip-jwks-check: don't do a network /meta↔JWKS check (which fails for an
+    // unreachable bookmark like a stopped localhost kernel). Switching is then a
+    // deterministic local write to instances.json.
+    const proc = Bun.spawn(
+      ['astrale', 'instance', 'use', name, '--adopt-default', '--skip-jwks-check'],
+      { stdout: 'pipe', stderr: 'pipe' },
+    )
+    const [out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    const code = await proc.exited
+    const combined = `${out}\n${err}`.trim()
+    if (code !== 0) return { ok: false, active: await activeName(), output: combined.slice(-1000) }
+    return { ok: true, active: await activeName(), output: combined.slice(-1000) }
+  } catch (e: any) {
+    return { ok: false, active: null, output: String(e?.message ?? e) }
+  }
+}
+
+// ── per-domain: deploy target + GROUND-TRUTH install/drift (queried from the instance) ──
+
+export function lastDeploy(root: string): DeployRecord | null {
+  return readJson<DeployRecord | null>(root, DEPLOY_REC, null)
+}
+
+/**
+ * Ask the target instance for the domain node (`astrale get /<origin> -i <instance>`).
+ * Installed ⇒ the kernel returns the Domain node (with the installed schema in
+ * `props.schema`); `NOT_FOUND` ⇒ not installed; anything else (offline / not
+ * authed / unknown instance) ⇒ unknown (never falsely "not installed").
+ */
+async function getInstalledDomain(
+  origin: string,
+  instance: string,
+  timeoutMs = 8000,
+): Promise<{ state: 'installed' | 'not-installed' | 'unknown'; schema: unknown | null }> {
+  try {
+    const proc = Bun.spawn(['astrale', 'get', `/${origin}`, '-i', instance, '--json'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const timer = setTimeout(() => {
+      try {
+        proc.kill()
+      } catch {
+        /* already exited */
+      }
+    }, timeoutMs)
+    try {
+      const [out, err] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ])
+      await proc.exited
+      let parsed: any = null
+      try {
+        parsed = JSON.parse(out)
+      } catch {
+        /* non-JSON */
+      }
+      if (parsed?.error === 'NOT_FOUND' || /\bNOT_FOUND\b/.test(`${out}\n${err}`))
+        return { state: 'not-installed', schema: null }
+      if (parsed?.path && parsed?.props) {
+        let schema: unknown = null
+        try {
+          schema = parsed.props.schema ? JSON.parse(parsed.props.schema) : null
+        } catch {
+          /* schema absent/unparseable — still installed */
+        }
+        return { state: 'installed', schema }
+      }
+      return { state: 'unknown', schema: null }
+    } finally {
+      clearTimeout(timer)
+    }
+  } catch {
+    return { state: 'unknown', schema: null }
+  }
+}
+
+export async function instanceStatus(
+  handle: DomainHandle,
+  deployTarget: string | null,
+  origin: string | null,
+  localHash: string | null,
+): Promise<InstanceStatus> {
+  const deployable = hasProdScript(handle.root)
+  const last = lastDeploy(handle.root)
+  let install: InstanceStatus['install'] = 'unknown'
+  let installedHash: string | null = null
+  let drift: InstanceStatus['drift'] = 'unknown'
+
+  if (origin && deployTarget) {
+    const probe = await getInstalledDomain(origin, deployTarget)
+    if (probe.state === 'installed') {
+      install = 'installed'
+      installedHash = probe.schema ? schemaHashOf(probe.schema) : null
+      drift =
+        installedHash && localHash
+          ? installedHash === localHash
+            ? 'in-sync'
+            : 'drifted'
+          : 'unknown'
+    } else if (probe.state === 'not-installed') {
+      install = 'not-installed'
+    }
+  }
+
+  return { deployTarget, deployable, install, drift, localHash, installedHash, lastDeploy: last }
+}
+
+const SVC_URL = /https:\/\/[\w-]+\.svc\.[\w.-]+\.astrale\.ai\b/
+
+/** Run `pnpm prod` (deploy + managed auto-install). Outward-facing — only call on an explicit request. */
+export async function runDeploy(
+  handle: DomainHandle,
+  localHash: string | null,
+): Promise<DeployResult> {
+  if (!hasProdScript(handle.root)) {
+    return {
+      ok: false,
+      url: null,
+      output:
+        'This domain has no "prod" script in package.json — it is not deployable via `pnpm prod`.',
+    }
+  }
+  let out = ''
+  let err = ''
+  let code = 1
+  try {
+    const proc = Bun.spawn(['pnpm', 'prod'], { cwd: handle.root, stdout: 'pipe', stderr: 'pipe' })
+    ;[out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    code = await proc.exited
+  } catch (e: any) {
+    return { ok: false, url: null, output: `failed to start pnpm: ${e?.message ?? e}` }
+  }
+  const combined = `${out}\n${err}`.trim()
+  const url = combined.match(SVC_URL)?.[0] ?? null
+  const ok = code === 0
+  if (ok)
+    writeJson(handle.root, DEPLOY_REC, {
+      at: new Date().toISOString(),
+      schemaHash: localHash ?? '',
+      ok: true,
+      url: url ?? undefined,
+    } satisfies DeployRecord)
+  return { ok, url, output: combined.slice(-6000) }
+}

package/studio/server/state/integrations.ts

@@ -0,0 +1,55 @@
+/**
+ * integrations.ts — persists user-declared integrations at integrations.json
+ * ({ integrations: Integration[] }). `detectedSubfolders` is a caller-supplied
+ * hint (a shallow readdir of integrations/) merged in on read, never persisted.
+ * ALL writes go through store.ts.
+ */
+import type { Integration, IntegrationsState } from '../../shared/types'
+
+import { readJson, writeJson } from './store'
+
+const PATH = 'integrations.json'
+
+interface IntegrationsFile {
+  integrations: Integration[]
+}
+
+function read(root: string): Integration[] {
+  return readJson<IntegrationsFile>(root, PATH, { integrations: [] }).integrations
+}
+
+function write(root: string, integrations: Integration[]): void {
+  writeJson(root, PATH, { integrations })
+}
+
+export function readIntegrations(root: string, detectedSubfolders: string[]): IntegrationsState {
+  return { integrations: read(root), detectedSubfolders }
+}
+
+export function upsertIntegration(
+  root: string,
+  input: { id?: string; name: string; kind: string; status: string; notes?: string },
+): Integration {
+  const integrations = read(root)
+  const id = input.id ?? crypto.randomUUID()
+  const next: Integration = {
+    id,
+    name: input.name,
+    kind: input.kind,
+    status: input.status,
+    notes: input.notes,
+  }
+  const idx = integrations.findIndex((it) => it.id === id)
+  if (idx === -1) integrations.push(next)
+  else integrations[idx] = next
+  write(root, integrations)
+  return next
+}
+
+export function deleteIntegration(root: string, id: string): boolean {
+  const integrations = read(root)
+  const kept = integrations.filter((it) => it.id !== id)
+  if (kept.length === integrations.length) return false
+  write(root, kept)
+  return true
+}

package/studio/server/state/layout.ts

@@ -0,0 +1,55 @@
+/**
+ * layout.ts — persisted manual graph layout per domain. Positions are keyed by
+ * node id (e.g. `class.Monitor`), so they survive schema changes: removed nodes'
+ * positions are harmless, new nodes fall back to auto-layout. Stamped with the
+ * schemaHash for reference. Persisted via the allow-listed store (layout.json).
+ */
+import { readJson, removeState, writeJson } from './store'
+
+export interface NodePosition {
+  x: number
+  y: number
+  /** persisted size — only expanded module containers carry one. */
+  w?: number
+  h?: number
+}
+
+export interface LayoutState {
+  schemaHash?: string
+  /** node id → manual position (only nodes the user has moved) */
+  positions: Record<string, NodePosition>
+}
+
+const FILE = 'layout.json'
+
+export function readLayout(root: string): LayoutState {
+  return readJson<LayoutState>(root, FILE, { positions: {} })
+}
+
+export function saveLayout(
+  root: string,
+  positions: Record<string, NodePosition>,
+  schemaHash?: string,
+): LayoutState {
+  const next: LayoutState = { schemaHash, positions }
+  writeJson(root, FILE, next)
+  return next
+}
+
+export function setNodePositions(
+  root: string,
+  updates: Record<string, NodePosition>,
+  schemaHash?: string,
+): LayoutState {
+  const cur = readLayout(root)
+  const next: LayoutState = {
+    schemaHash: schemaHash ?? cur.schemaHash,
+    positions: { ...cur.positions, ...updates },
+  }
+  writeJson(root, FILE, next)
+  return next
+}
+
+export function resetLayout(root: string): void {
+  removeState(root, FILE)
+}

package/studio/server/state/settings.ts

@@ -0,0 +1,39 @@
+/**
+ * settings.ts — per-domain power-user overrides for values the studio otherwise
+ * hard-codes (first: the integrations/ folder name). Stored at
+ * `.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 { readJson, writeJson } from './store'
+
+const PATH = 'settings.json'
+
+export const DEFAULT_SETTINGS: StudioSettings = {
+  agentEffort: 'high',
+  integrationsDir: 'integrations',
+  introspectTimeoutMs: 20000,
+  instancePollMs: 30000,
+  updatesPollMs: 600000,
+  viewProbeTimeoutMs: 8000,
+}
+
+function normalizeSettings(input: Partial<StudioSettings>): Partial<StudioSettings> {
+  const out = { ...input }
+  if (out.agentEffort !== undefined && !AGENT_EFFORT_LEVELS.includes(out.agentEffort as any))
+    delete out.agentEffort
+  return out
+}
+
+export function readSettings(root: string): StudioSettings {
+  return {
+    ...DEFAULT_SETTINGS,
+    ...normalizeSettings(readJson<Partial<StudioSettings>>(root, PATH, {})),
+  }
+}
+
+export function updateSettings(root: string, patch: Partial<StudioSettings>): StudioSettings {
+  const next: StudioSettings = { ...readSettings(root), ...normalizeSettings(patch) }
+  writeJson(root, PATH, next)
+  return next
+}

package/studio/server/state/store.ts

@@ -0,0 +1,97 @@
+/**
+ * store.ts — the ONLY filesystem-write gateway in the studio. It REJECTS any
+ * write whose resolved path is not under `<domain>/.domain-studio/`. This makes
+ * the read-only-domain rule a code-enforced invariant (§17 of the spec): the
+ * studio can never write domain source. Reads of domain source are allowed and
+ * done elsewhere; this module never writes outside the dotted folder.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+
+export const DOT = '.domain-studio'
+
+export function dotDir(domainRoot: string): string {
+  return join(domainRoot, DOT)
+}
+
+function assertInsideDot(domainRoot: string, target: string): string {
+  const abs = resolve(target)
+  const root = resolve(dotDir(domainRoot))
+  if (abs !== root && !abs.startsWith(root + sep)) {
+    throw new Error(`write-allowlist violation: ${abs} is outside ${root}`)
+  }
+  return abs
+}
+
+export function ensureDir(domainRoot: string, subpath = ''): string {
+  const target = subpath ? join(dotDir(domainRoot), subpath) : dotDir(domainRoot)
+  assertInsideDot(domainRoot, target)
+  mkdirSync(target, { recursive: true })
+  return target
+}
+
+export function writeState(domainRoot: string, subpath: string, contents: string): void {
+  const target = join(dotDir(domainRoot), subpath)
+  const abs = assertInsideDot(domainRoot, target)
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, contents)
+}
+
+export function writeJson(domainRoot: string, subpath: string, value: unknown): void {
+  writeState(domainRoot, subpath, JSON.stringify(value, null, 2))
+}
+
+/** Binary write (e.g. dropped documents), allow-listed to the dotted folder. */
+export function writeStateBuffer(domainRoot: string, subpath: string, data: Uint8Array): void {
+  const target = join(dotDir(domainRoot), subpath)
+  const abs = assertInsideDot(domainRoot, target)
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, data)
+}
+
+/** Absolute path of a state file (allow-listed) — for reading/serving. */
+export function statePath(domainRoot: string, subpath: string): string {
+  return assertInsideDot(domainRoot, join(dotDir(domainRoot), subpath))
+}
+
+export function readState(domainRoot: string, subpath: string): string | null {
+  const target = join(dotDir(domainRoot), subpath)
+  if (!existsSync(target)) return null
+  return readFileSync(target, 'utf8')
+}
+
+export function readJson<T>(domainRoot: string, subpath: string, fallback: T): T {
+  const raw = readState(domainRoot, subpath)
+  if (raw == null) return fallback
+  try {
+    return JSON.parse(raw) as T
+  } catch {
+    return fallback
+  }
+}
+
+export function listState(domainRoot: string, subpath: string): string[] {
+  const target = join(dotDir(domainRoot), subpath)
+  if (!existsSync(target)) return []
+  return readdirSync(target)
+}
+
+export function removeState(domainRoot: string, subpath: string): void {
+  const target = join(dotDir(domainRoot), subpath)
+  const abs = assertInsideDot(domainRoot, target)
+  if (existsSync(abs)) rmSync(abs, { recursive: true, force: true })
+}
+
+export function stateExists(domainRoot: string, subpath: string): boolean {
+  return existsSync(join(dotDir(domainRoot), subpath))
+}
+
+/** Initialise the dotted folder skeleton + a .cache/.gitignore (never touches the user's root .gitignore). */
+export function initDotDir(domainRoot: string): void {
+  ensureDir(domainRoot)
+  ensureDir(domainRoot, 'context/user')
+  ensureDir(domainRoot, 'context/auto')
+  ensureDir(domainRoot, '.cache')
+  if (!stateExists(domainRoot, '.cache/.gitignore'))
+    writeState(domainRoot, '.cache/.gitignore', '*\n')
+}