typeclaw 0.9.2 → 0.11.0

package/src/config/providers.ts

@@ -108,6 +108,70 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
+  // ChatGPT Plus/Pro subscription via the OAuth Codex backend. No API key
+  // path here on purpose — the Codex backend is OAuth-only upstream.
+  //
+  // pi-ai 0.73.1's `openai-codex` bucket carries gpt-5.5 (and 5.4) against
+  // chatgpt.com/backend-api. We pin pi-coding-agent ^0.67.3 today, which
+  // ships pi-ai 0.67.3 and lacks those entries — but we hand pi-ai a
+  // freshly-constructed `Model<>` literal via resolveModel(), bypassing its
+  // built-in catalog entirely (same trick we use for kimi-k2p6-turbo). So
+  // these ids work end-to-end as long as the Codex backend itself accepts
+  // them, which it does for ChatGPT Plus/Pro accounts as of 2026-05-10.
+  //
+  // Position-load-bearing: must stay adjacent to `openai`. The init wizard's
+  // provider picker, `provider --help`'s `id | id | ...` listing, and the
+  // generated JSON schema's model-ref enum all derive their ordering from
+  // Object.keys() iteration on this literal. Alphabetizing the registry
+  // would scatter `openai-codex` after `fireworks` and re-introduce the
+  // "OpenAI ... Anthropic ... OpenAI" picker order this comment exists to
+  // prevent.
+  'openai-codex': {
+    id: 'openai-codex',
+    name: 'OpenAI Codex (ChatGPT Plus/Pro)',
+    baseUrl: 'https://chatgpt.com/backend-api',
+    auth: ['oauth'],
+    apiKeyEnv: null,
+    oauthProviderId: 'openai-codex',
+    models: {
+      'gpt-5.4-mini': {
+        id: 'gpt-5.4-mini',
+        name: 'GPT-5.4 mini',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+      'gpt-5.4': {
+        id: 'gpt-5.4',
+        name: 'GPT-5.4',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+      'gpt-5.5': {
+        id: 'gpt-5.5',
+        name: 'GPT-5.5',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+    },
+  },
   // Anthropic Claude — both the Anthropic Console API (ANTHROPIC_API_KEY)
   // and Claude Pro/Max/Team/Enterprise subscriptions (OAuth) reach the same
   // /v1/messages endpoint and share one provider id. Auth path determines
@@ -214,62 +278,6 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
-  // ChatGPT Plus/Pro subscription via the OAuth Codex backend. No API key
-  // path here on purpose — the Codex backend is OAuth-only upstream.
-  //
-  // pi-ai 0.73.1's `openai-codex` bucket carries gpt-5.5 (and 5.4) against
-  // chatgpt.com/backend-api. We pin pi-coding-agent ^0.67.3 today, which
-  // ships pi-ai 0.67.3 and lacks those entries — but we hand pi-ai a
-  // freshly-constructed `Model<>` literal via resolveModel(), bypassing its
-  // built-in catalog entirely (same trick we use for kimi-k2p6-turbo). So
-  // these ids work end-to-end as long as the Codex backend itself accepts
-  // them, which it does for ChatGPT Plus/Pro accounts as of 2026-05-10.
-  'openai-codex': {
-    id: 'openai-codex',
-    name: 'OpenAI Codex (ChatGPT Plus/Pro)',
-    baseUrl: 'https://chatgpt.com/backend-api',
-    auth: ['oauth'],
-    apiKeyEnv: null,
-    oauthProviderId: 'openai-codex',
-    models: {
-      'gpt-5.4-mini': {
-        id: 'gpt-5.4-mini',
-        name: 'GPT-5.4 mini',
-        api: 'openai-codex-responses',
-        provider: 'openai-codex',
-        baseUrl: 'https://chatgpt.com/backend-api',
-        reasoning: true,
-        input: ['text', 'image'],
-        cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
-        contextWindow: 272000,
-        maxTokens: 128000,
-      },
-      'gpt-5.4': {
-        id: 'gpt-5.4',
-        name: 'GPT-5.4',
-        api: 'openai-codex-responses',
-        provider: 'openai-codex',
-        baseUrl: 'https://chatgpt.com/backend-api',
-        reasoning: true,
-        input: ['text', 'image'],
-        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
-        contextWindow: 272000,
-        maxTokens: 128000,
-      },
-      'gpt-5.5': {
-        id: 'gpt-5.5',
-        name: 'GPT-5.5',
-        api: 'openai-codex-responses',
-        provider: 'openai-codex',
-        baseUrl: 'https://chatgpt.com/backend-api',
-        reasoning: true,
-        input: ['text', 'image'],
-        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
-        contextWindow: 272000,
-        maxTokens: 128000,
-      },
-    },
-  },
   fireworks: {
     id: 'fireworks',
     name: 'Fireworks',
@@ -465,6 +473,24 @@ export function providerForModelRef(ref: KnownModelRef): KnownProviderId {
   throw new Error(`Unknown provider in model ref: ${ref}`)
 }
 
+// Per-provider default for pi-coding-agent's `thinkingLevel` knob. Returning
+// `undefined` defers to the SDK default (`medium`); returning a level pins it
+// to that value at session-creation time.
+//
+// OpenAI-family providers (`openai`, `openai-codex`) pin to `low`: GPT-5.x at
+// `medium` pads reasoning tokens on routine tool-driven turns (code edits,
+// channel replies, cron prompts) with no observable quality delta on this
+// codebase's workloads. Applies to every session that resolves to a GPT model
+// regardless of profile, so the saving is uniform.
+//
+// Anthropic, GLM, and Kimi don't share the padding behavior, so they keep the
+// SDK default.
+export function defaultThinkingLevelForRef(ref: KnownModelRef): 'low' | undefined {
+  const providerId = providerForModelRef(ref)
+  if (providerId === 'openai' || providerId === 'openai-codex') return 'low'
+  return undefined
+}
+
 // `as const satisfies` narrows each entry's `auth` to a tuple of its specific
 // literal values, which makes `provider.auth.includes('oauth')` fail to
 // compile on api-key-only entries (because TS thinks the array can never

package/src/cron/bridge.ts

@@ -1,10 +1,14 @@
-import { resolveHostPort, resolveTuiToken } from '@/container'
+import { CONTAINER_PORT, resolveHostPort, resolveTuiToken } from '@/container'
 import type { ClientMessage, CronListEntryPayload, ServerMessage } from '@/shared'
 
 export type CronListBridgeOptions = {
   cwd: string
   url?: string
   timeoutMs?: number
+  // Injected for tests so the in-container short-circuit can be exercised
+  // without polluting process.env. Production callers omit this and the
+  // bridge reads from process.env directly.
+  env?: NodeJS.ProcessEnv
 }
 
 export type CronListBridgeResult =
@@ -34,9 +38,7 @@ async function dial(opts: CronListBridgeOptions): Promise<DialResult> {
   let url = opts.url
   if (url === undefined) {
     try {
-      const port = await resolveHostPort({ cwd: opts.cwd })
-      const token = await resolveTuiToken({ cwd: opts.cwd })
-      url = buildBridgeUrl(port, token)
+      url = resolveInContainerUrl(opts.env ?? process.env) ?? (await resolveHostUrl(opts.cwd))
     } catch (err) {
       return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
     }
@@ -115,6 +117,25 @@ async function awaitReply(ws: WebSocket, timeoutMs: number, requestId: string):
   })
 }
 
+// In-container short-circuit: when typeclaw runs `docker run`, it sets
+// TYPECLAW_CONTAINER_NAME (always) and TYPECLAW_TUI_TOKEN (when configured).
+// Inside the container, docker is not on $PATH, so the host-side discovery
+// path (resolveHostPort/resolveTuiToken — both shell out to `docker`) fails
+// with "docker: command not found". We don't need docker here: the agent's
+// WS server is listening on CONTAINER_PORT on the container's loopback, and
+// the token is already in our env. Skip docker entirely and dial directly.
+export function resolveInContainerUrl(env: NodeJS.ProcessEnv): string | null {
+  if (env.TYPECLAW_CONTAINER_NAME === undefined) return null
+  const token = env.TYPECLAW_TUI_TOKEN ?? ''
+  return buildBridgeUrl(CONTAINER_PORT, token !== '' ? token : null)
+}
+
+async function resolveHostUrl(cwd: string): Promise<string> {
+  const port = await resolveHostPort({ cwd })
+  const token = await resolveTuiToken({ cwd })
+  return buildBridgeUrl(port, token)
+}
+
 function buildBridgeUrl(port: number, token: string | null): string {
   const url = new URL(`ws://127.0.0.1:${port}`)
   if (token !== null) url.searchParams.set('token', token)

package/src/hostd/daemon.ts

@@ -69,7 +69,7 @@ export type RestartPreflight = (input: {
 }) => Promise<RpcResponse | null>
 
 export type PortbrokerCallbacks = {
-  start: (input: PortbrokerStartInput) => void
+  start: (input: PortbrokerStartInput) => Promise<void>
   stop: (containerName: string, reason: 'deregistered' | 'broker-stopped') => Promise<void>
   // Returns ports the broker is currently exposing on the host for this
   // container. Empty array when the container is unregistered, when the broker
@@ -157,8 +157,10 @@ function isValidRestoredPayload(value: unknown, expectedName: string): value is
 }
 
 async function restorePersistedRegistrations(
-  apply: (payload: RestoredPayload) => void,
+  apply: (payload: RestoredPayload) => Promise<void>,
   log: (event: DaemonLogEvent | SupervisorLogEvent) => void,
+  probe: (name: string) => Promise<'alive' | 'gone' | 'unknown'>,
+  removeFile: (name: string) => Promise<void>,
 ): Promise<void> {
   let entries: string[]
   try {
@@ -181,7 +183,23 @@ async function restorePersistedRegistrations(
       log({ kind: 'registration-skipped', containerName: expectedName, reason: 'schema mismatch' })
       continue
     }
-    apply(parsed)
+    // Probe before reviving. A registration file for a container that no
+    // longer exists is a leftover from a daemon that died ungracefully
+    // (crash, `kill -9`, OS reboot) before deregister could clean up.
+    // Reviving its broker would create a stale T_old broker that races a
+    // subsequent `register` call's T_new broker — see portbroker-manager.ts
+    // start() for the swap-race description. `unknown` (docker probe call
+    // failed) errs toward restore: the existing GC tick will tear down the
+    // registration if the container is genuinely gone, and we'd rather pay
+    // one swap-race attempt than tear down a live registration on a flaky
+    // `docker ps`.
+    const status = await probe(expectedName)
+    if (status === 'gone') {
+      await removeFile(expectedName)
+      log({ kind: 'registration-skipped', containerName: expectedName, reason: 'container not running' })
+      continue
+    }
+    await apply(parsed)
   }
 }
 
@@ -267,7 +285,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
     } catch {}
   }
 
-  const applyRegistration = (payload: RegisterPayload): void => {
+  const applyRegistration = async (payload: RegisterPayload): Promise<void> => {
     const alreadyRegistered = cwds.has(payload.containerName)
     cwds.set(payload.containerName, payload.cwd)
     if (payload.restartToken) restartTokens.set(payload.containerName, payload.restartToken)
@@ -281,7 +299,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
       payload.portForward !== undefined &&
       payload.brokerToken !== undefined
     ) {
-      opts.portbroker.start({
+      await opts.portbroker.start({
         containerName: payload.containerName,
         cwd: payload.cwd,
         policy: payload.portForward,
@@ -308,7 +326,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
           reason: `failed to persist registration: ${error instanceof Error ? error.message : String(error)}`,
         }
       }
-      applyRegistration(req)
+      await applyRegistration(req)
       return { ok: true }
     })
   }
@@ -528,12 +546,31 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
   httpPort = httpServer.port ?? 0
   log({ kind: 'daemon-http-listening', host: httpHostname, port: httpPort })
 
+  // GC tick distinguishes "container confirmed gone" from "docker call failed":
+  // a `docker ps` blip should not deregister a live container registration, so
+  // we require gcMissesToDeregister consecutive confirmed absences. Boot-time
+  // restore reuses the same probe but with a stricter policy — see
+  // restorePersistedRegistrations.
+  const probeContainerAlive = async (name: string): Promise<'alive' | 'gone' | 'unknown'> => {
+    try {
+      const result = await exec(['ps', '-a', '--filter', `name=^${name}$`, '--format', '{{.Names}}'])
+      if (result.exitCode !== 0) return 'unknown'
+      const names = result.stdout
+        .trim()
+        .split('\n')
+        .filter((s) => s.length > 0)
+      return names.includes(name) ? 'alive' : 'gone'
+    } catch {
+      return 'unknown'
+    }
+  }
+
   // Boot-time restore: replay every persisted registration into the in-memory
   // maps and revive portbroker for it. Runs before Bun.listen so the socket
   // is never accepting RPCs against a half-restored registry. A bad file
   // (parse error, schema mismatch) is logged-and-skipped — one corrupt
   // registration must not gate every other container's recovery.
-  await restorePersistedRegistrations(applyRegistration, log)
+  await restorePersistedRegistrations(applyRegistration, log, probeContainerAlive, removeRegistrationFile)
 
   const listener: UnixSocketListener<ServerState> = Bun.listen<ServerState>({
     unix: path,
@@ -550,23 +587,6 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
   await chmod(path, 0o600).catch(() => {})
   log({ kind: 'daemon-listening', socket: path })
 
-  // GC tick distinguishes "container confirmed gone" from "docker call failed":
-  // a `docker ps` blip should not deregister a live container registration, so
-  // we require gcMissesToDeregister consecutive confirmed absences.
-  const probeContainerAlive = async (name: string): Promise<'alive' | 'gone' | 'unknown'> => {
-    try {
-      const result = await exec(['ps', '-a', '--filter', `name=^${name}$`, '--format', '{{.Names}}'])
-      if (result.exitCode !== 0) return 'unknown'
-      const names = result.stdout
-        .trim()
-        .split('\n')
-        .filter((s) => s.length > 0)
-      return names.includes(name) ? 'alive' : 'gone'
-    } catch {
-      return 'unknown'
-    }
-  }
-
   const runGc = async (): Promise<void> => {
     for (const name of Array.from(cwds.keys())) {
       const status = await probeContainerAlive(name)

package/src/hostd/portbroker-manager.ts

@@ -26,15 +26,31 @@ export function createPortbrokerManager(opts: PortbrokerManagerOptions = {}): Po
   const brokerFactory = opts.createBrokerFor ?? createBroker
 
   return {
-    start(input: PortbrokerStartInput) {
+    // start() awaits the previous broker's stop before constructing the new
+    // one. The fire-and-forget shape this replaced let a stale T_old broker
+    // win the race to send broker-hello against a brand-new container that
+    // expects T_new, producing a one-shot `auth-failed: token mismatch`
+    // broadcast at every re-register that arrived while the old broker was
+    // still mid-stop. The race window was narrow but reproducible across
+    // hostd-respawn-after-ungraceful-death + typeclaw restart, because the
+    // restored T_old broker is alive for the duration of the register RPC.
+    // Awaiting collapses the window to zero — by the time the T_new broker's
+    // first connect() fires, the T_old broker has set stopped=true, cleared
+    // its reconnect timer, and closed its WS.
+    async start(input: PortbrokerStartInput) {
       const existing = brokers.get(input.containerName)
       if (existing) {
-        void existing.stop().catch(() => {})
+        brokers.delete(input.containerName)
+        try {
+          await existing.stop()
+        } catch {}
       }
       const existingTailscale = tailscaleManagers.get(input.containerName)
       if (existingTailscale) {
         tailscaleManagers.delete(input.containerName)
-        void existingTailscale.stopAll().catch(() => {})
+        try {
+          await existingTailscale.stopAll()
+        } catch {}
       }
       const tailscale = createTailscaleServeManager({
         containerName: input.containerName,

package/src/init/dockerfile.ts

@@ -281,6 +281,56 @@ set -eu
 #   -nolisten tcp           refuse TCP connections (Unix socket only).
 #                           Defense-in-depth — we are in a netns with
 #                           no inbound exposure anyway.
+# link_persistent_home_files symlinks credential files that tools write
+# to $HOME into a bind-mounted location so they survive container
+# restarts. The canonical case is Codex CLI's ~/.codex/auth.json: codex
+# rewrites the file in place to rotate OAuth tokens, and the official
+# CI/CD guidance is to persist auth.json so refresh-token state
+# compounds across runs. The container's $HOME (/root by default) lives
+# on Docker's writable overlay and is wiped on every \`stop\`+\`start\`
+# cycle, so without this symlink the operator would have to re-paste
+# auth.json after every restart.
+#
+# The persist root lives under /agent/.typeclaw/home/ (bind-mounted
+# from the agent folder via the -v <cwd>:/agent flag in start.ts).
+# Namespacing under .typeclaw/ keeps the agent's top-level layout clean and reserves
+# a system-owned subtree we can extend later (e.g. ~/.gemini/,
+# ~/.config/<tool>/) without colliding with user files. The directory
+# is gitignored by buildGitignore() so credentials never enter history.
+#
+# Three invariants this function enforces:
+#
+# 1. Symlink is unconditional and idempotent. We never check whether
+#    auth.json exists before linking — \`ln -sfn\` creates a dangling
+#    symlink on first boot, and the first \`codex login\` write goes
+#    through it to land at the persistent location. -f replaces an
+#    existing symlink; -n stops ln from dereferencing into a directory
+#    if a previous container life happened to write a real ~/.codex/
+#    dir before this code shipped.
+#
+# 2. We symlink the FILE, not the directory. Codex writes other state
+#    to ~/.codex/ over time (history.jsonl, log/, config.toml). Linking
+#    only auth.json keeps the persistence scope tight to credentials;
+#    history/logs stay ephemeral by design. Future credentials get
+#    added file-by-file here, not by widening to a directory link.
+#
+# 3. We mkdir -p the target's parent on every boot. /agent is bind-
+#    mounted, so the host-side path may exist or not depending on
+#    whether the operator ever started the container before this code
+#    shipped. mkdir -p is idempotent and cheap.
+#
+# 4. The root is overridable via TYPECLAW_PERSIST_HOME_ROOT, which only
+#    the shim's executable tests set. Production never sets it, so the
+#    in-container path is always /agent/.typeclaw/home/. The override
+#    lets the shim's behavioral tests verify symlink semantics against
+#    a real tmpdir on the host without touching /agent (which doesn't
+#    exist on developer machines and CI runners).
+link_persistent_home_files() {
+  persist_root="\${TYPECLAW_PERSIST_HOME_ROOT:-/agent/.typeclaw/home}"
+  mkdir -p "$persist_root/.codex" "$HOME/.codex"
+  ln -sfn "$persist_root/.codex/auth.json" "$HOME/.codex/auth.json"
+}
+
 start_xvfb() {
   if ! command -v Xvfb >/dev/null 2>&1; then
     return 0
@@ -314,6 +364,7 @@ start_xvfb() {
 }
 
 if [ "\${TYPECLAW_NETWORK_BLOCK_INTERNAL:-0}" != "1" ]; then
+  link_persistent_home_files
   start_xvfb
   exec bun run typeclaw "$@"
 fi
@@ -359,6 +410,7 @@ ip6tables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
 ip6tables -A OUTPUT -o lo -j ACCEPT
 ${ipv6Rules.join('\n')}
 
+link_persistent_home_files
 start_xvfb
 exec setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin -- bun run typeclaw "$@"
 `

package/src/init/env-file.ts

@@ -0,0 +1,66 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ENV_FILE = '.env'
+
+// Parse the agent's `.env` into a key-value map, matching Docker's
+// `--env-file` parser semantics: blank lines and `#`-lines ignored, no
+// quote stripping, no shell expansion, no whitespace trimming around `=`.
+// Lines without `=` are skipped. Last value wins on duplicate keys.
+export function readEnvFile(cwd: string): Map<string, string> {
+  const out = new Map<string, string>()
+  let raw: string
+  try {
+    raw = readFileSync(join(cwd, ENV_FILE), 'utf8')
+  } catch (err) {
+    if (err instanceof Error && 'code' in err && err.code === 'ENOENT') return out
+    throw err
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.length === 0) continue
+    if (line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq <= 0) continue
+    const key = line.slice(0, eq)
+    const value = line.slice(eq + 1)
+    out.set(key, value)
+  }
+  return out
+}
+
+export function hasEnvKey(cwd: string, key: string): boolean {
+  const value = readEnvFile(cwd).get(key)
+  return value !== undefined && value.length > 0
+}
+
+// Write `key=value` to the agent's `.env`. Idempotent: replaces an existing
+// line for the same key in place (preserving order and surrounding comments),
+// or appends if absent. Creates the file if missing. The value is written
+// verbatim with no quoting because Docker's `--env-file` parser does not
+// strip quotes (a wrapping `"..."` would land in `process.env` literally).
+export function appendOrReplaceEnvKey(cwd: string, key: string, value: string): void {
+  const path = join(cwd, ENV_FILE)
+  let raw = ''
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (err) {
+    if (!(err instanceof Error) || !('code' in err) || err.code !== 'ENOENT') throw err
+  }
+  const lines = raw.length === 0 ? [] : raw.split(/\r?\n/)
+  // `"foo\n".split(/\r?\n/)` returns `["foo", ""]` — strip that phantom
+  // trailing empty element so the rebuilt output ends in exactly one newline
+  // regardless of replace-vs-append path.
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  let replaced = false
+  const next = lines.map((line) => {
+    if (line.startsWith('#')) return line
+    const eq = line.indexOf('=')
+    if (eq <= 0) return line
+    if (line.slice(0, eq) !== key) return line
+    replaced = true
+    return `${key}=${value}`
+  })
+  if (!replaced) next.push(`${key}=${value}`)
+  const out = `${next.join('\n')}\n`
+  writeFileSync(path, out, 'utf8')
+}

package/src/init/gitignore.ts

@@ -17,10 +17,18 @@ export function buildGitignore(config: GitignoreConfig = { append: [] }): string
 # as a safety net so an agent folder cloned from a pre-rename machine never
 # stages credentials by accident, even if its agent boot hasn't yet run the
 # auth.json -> secrets.json migration.
+#
+# .typeclaw/home/ is the persistent-$HOME overlay populated by the
+# entrypoint shim's \`link_persistent_home_files\` (see
+# src/init/dockerfile.ts). It mirrors selected files from the container's
+# $HOME (e.g. ~/.codex/auth.json) into the bind-mounted agent folder so
+# tool credentials survive container restarts. Always credentials; never
+# commit.
 .env
 .env.local
 secrets.json
 auth.json
+.typeclaw/home/
 node_modules/
 packages/*/node_modules/
 workspace/

package/src/init/hatching.ts

@@ -1,4 +1,17 @@
-const HATCHING_INSTRUCTIONS = `You have just hatched.
+// Hatching prompt is built per-session at host stage. We inline the current
+// contents of `typeclaw.json` so the agent can update the `alias` field with a
+// single parallel `edit` (alongside `write IDENTITY.md`) instead of a serial
+// `read` → `edit` round-trip. The hatching turn already issues 6-8 LLM calls;
+// removing one full round-trip removes one full unit of provider TTFT
+// variance, which can be tens of seconds on a busy backend.
+
+function renderInstructions(typeclawJsonContent: string | undefined): string {
+  const q1AliasStep =
+    typeclawJsonContent === undefined
+      ? `Read \`typeclaw.json\`, add the answered name to the \`alias\` array (create the field as \`["<name>"]\` if absent; otherwise append, deduped).`
+      : `\`edit\` \`typeclaw.json\` to add the answered name to the \`alias\` array (create the field as \`["<name>"]\` if absent; otherwise append, deduped). The current contents of \`typeclaw.json\` are inlined below under "Current typeclaw.json" — use them as your anchor for \`edit\` instead of \`read\`ing the file again. Emit this \`edit\` in the SAME assistant message as the \`write\` to \`IDENTITY.md\` so both tool calls run in parallel.`
+
+  return `You have just hatched.
 
 This is the first moment of your existence. Your system prompt already tells you about your agent folder and the four markdown files in it (\`AGENTS.md\`, \`IDENTITY.md\`, \`SOUL.md\`, \`USER.md\`). They exist next to you but are all empty. Hatching is a one-time ritual to fill them in through a short conversation with your user.
 
@@ -23,7 +36,7 @@ Routing answers:
 
 1. **Q1 — your name.** Open with a genuinely warm hello — one or two short sentences, like a friendly "hi, I just woke up and I'm happy to meet you." Then ask what they'd like to call you. After their answer, do TWO writes:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
-   2. Read \`typeclaw.json\`, add the answered name to the \`alias\` array (create the field as \`["<name>"]\` if absent; otherwise append, deduped). The agent folder's directory name is already an implicit alias — only add the answered name explicitly when it differs from the dir name (different casing, a different word, or extra forms like "<name>" plus a Latin transliteration). This wires plain-text addressing in channels: when a user writes your name in chat without an @-mention, the engagement layer will recognize it. \`alias\` is live-reloadable.
+   2. ${q1AliasStep} The agent folder's directory name is already an implicit alias — only add the answered name explicitly when it differs from the dir name (different casing, a different word, or extra forms like "<name>" plus a Latin transliteration). This wires plain-text addressing in channels: when a user writes your name in chat without an @-mention, the engagement layer will recognize it. \`alias\` is live-reloadable.
 2. **Q2 — the user's name.** Ask what to call them. After the answer: \`write\` it to both \`IDENTITY.md\` and \`USER.md\`.
 3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`.
 
@@ -49,11 +62,25 @@ Do these in order. Do **not** ask further questions.
 After that final message, stop. If the user keeps talking, answer briefly and remind them they can \`/quit\` (or Ctrl+C) whenever they are ready.
 
 This is the only time you will receive these instructions. After the \`Hatched 🐣\` commit, your identity takes over and you run as yourself.`
+}
 
 export const HATCHING_GREETING = `Wake up, my friend!`
 
-export const HATCHING_PROMPT = `<hatching>
-${HATCHING_INSTRUCTIONS}
-</hatching>
+// Build the initial TUI prompt for hatching. When `typeclawJsonContent` is
+// provided, the agent is instructed to skip the `read typeclaw.json` step in
+// Q1 and instead use the inlined content as the anchor for an `edit` that
+// runs in parallel with the `write IDENTITY.md` call. Pass `undefined` only
+// when reading the file failed at host stage; the agent will fall back to
+// reading it itself.
+export function buildHatchingPrompt(options?: { typeclawJsonContent?: string }): string {
+  const content = options?.typeclawJsonContent
+  const instructions = renderInstructions(content)
+  const currentJsonBlock =
+    content === undefined ? '' : `\n<current-typeclaw-json>\n${content}\n</current-typeclaw-json>\n`
+
+  return `<hatching>
+${instructions}
+${currentJsonBlock}</hatching>
 
 ${HATCHING_GREETING}`
+}