typeclaw 0.28.2 → 0.30.0

package/src/init/dockerfile.ts

@@ -12,6 +12,12 @@ export const DOCKERFILE = 'Dockerfile'
 export type BuildDockerfileOptions = {
   // Null or omitted = emit the full inline heavy stack (dev mode, tests).
   baseImageVersion?: string | null
+  // Host-locale decision for `cjkFonts: 'auto'`. Callers that have a host
+  // locale (start/init) pass the resolved boolean; when omitted, `'auto'`
+  // falls back to NOT installing (the slim default) so a context without a
+  // host signal — e.g. a bare `buildDockerfile()` in tests — stays small and
+  // deterministic.
+  cjkFontsAuto?: boolean
 }
 
 // Apt packages that EVERY image must have — git for the agent runtime,
@@ -98,33 +104,6 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
-// yq is the YAML/JSON/XML processor the `explorer` and `reviewer` subagent
-// prompts advertise alongside `jq` as a sanctioned one-shot read-only
-// pipeline tool (`... | yq`). Like `jq` (shipped in baseline), a binary that
-// is not in the container base image is invisible inside the per-tool bwrap
-// sandbox that wraps agent bash calls — the sandbox only `--ro-bind`s `/usr`
-// + `/bin` from the container, and there is no per-call install path. So `yq`
-// ships unconditionally, same rationale as `jq`/`bubblewrap`/`util-linux`.
-//
-// This is Mike Farah's Go `yq` (https://github.com/mikefarah/yq), NOT the
-// Python jq-wrapper of the same name in Debian's `yq` apt package. The
-// prompts pair `yq` with `jq` for jq-style expression pipelines, which is
-// Farah's syntax — the Python tool's CLI is incompatible. Distributed as a
-// per-arch static binary (no apt package on trixie for the Go variant), so
-// it follows the pinned-version + per-arch SHA256 + `sha256sum -c` pattern of
-// curl-impersonate and cloudflared rather than the apt baseline list.
-//
-// To bump: pick a release from https://github.com/mikefarah/yq/releases,
-// then for each arch download yq_linux_<arch> and `shasum -a 256` it (or read
-// the SHA-256 column from the release's `checksums` file, cross-indexed via
-// `checksums_hashes_order`). Update all three constants in the same commit;
-// the build fails loudly at `sha256sum -c` on a mismatch. Version literal is
-// the release tag exactly as it appears on GitHub (with `v` prefix).
-export const YQ_VERSION = 'v4.53.2'
-export const YQ_SHA256_AMD64 = 'd56bf5c6819e8e696340c312bd70f849dc1678a7cda9c2ad63eebd906371d56b'
-export const YQ_SHA256_ARM64 = '03061b2a50c7a498de2bbb92d7cb078ce433011f085a4994117c2726be4106ea'
-export const YQ_RELEASE_URL_BASE = 'https://github.com/mikefarah/yq/releases/download'
-
 // cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
 // SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
 // all three constants in the same commit, and the build fails loudly at
@@ -1068,22 +1047,26 @@ type AptFeature = {
   toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
 }
 
-const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts' | 'xvfb', AptFeature> = {
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'xvfb', AptFeature> = {
   ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
   gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
   tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
   python: {
     toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
   },
-  cjkFonts: { toAptArgs: (v) => (v === true ? [CJK_FONTS_PACKAGE] : []) },
   xvfb: { toAptArgs: (v) => (v === true ? ['xvfb'] : []) },
 }
 
+function resolveCjkFonts(value: boolean | 'auto', auto: boolean): boolean {
+  return value === 'auto' ? auto : value
+}
+
 export function buildDockerfile(
   config: DockerfileConfig = defaultConfig(),
   options: BuildDockerfileOptions = {},
 ): string {
-  const toggleAptArgs = collectToggleAptArgs(config)
+  const cjkFonts = resolveCjkFonts(config.cjkFonts, options.cjkFontsAuto ?? false)
+  const toggleAptArgs = collectToggleAptArgs(config, cjkFonts)
   const ghKeyringLayer = renderGhKeyringLayer(config.gh)
   const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
@@ -1215,8 +1198,6 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
-${LAYER_2_6_YQ}
-
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1296,8 +1277,6 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
-${LAYER_2_6_YQ}
-
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1352,24 +1331,6 @@ RUN ARCH_TARBALL="$(if [ "$TARGETARCH" = "arm64" ]; then echo aarch64-linux-gnu;
  && rm curl-impersonate.tar.gz \\
  && /usr/local/bin/curl_${CURL_IMPERSONATE_PROFILE} --version > /dev/null`
 
-// Layer 2.6: install pinned Mike Farah `yq` (Go) so the explorer/reviewer
-// subagents' advertised `... | yq` pipelines resolve inside the bwrap
-// sandbox. Unconditional like the apt baseline (jq, git): a missing binary
-// is invisible to sandboxed bash, so this is not behind a toggle. Placed
-// after curl-impersonate (curl + ca-certificates from baseline guaranteed
-// present) and before agent-browser so an agent-browser bump doesn't
-// invalidate this layer. See the YQ_* constants above for the bump recipe
-// and the Go-vs-Python `yq` rationale.
-const LAYER_2_6_YQ = `# Layer 2.6 (stable): pinned Mike Farah yq for sandbox-visible YAML pipelines.
-RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \\
- && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${YQ_SHA256_ARM64}; else echo ${YQ_SHA256_AMD64}; fi)" \\
- && cd /tmp \\
- && curl -fsSL -o yq "${YQ_RELEASE_URL_BASE}/${YQ_VERSION}/yq_linux_\${ARCH_BIN}" \\
- && echo "\${ARCH_SHA}  yq" | sha256sum -c - \\
- && chmod +x yq \\
- && mv yq /usr/local/bin/yq \\
- && /usr/local/bin/yq --version > /dev/null`
-
 const LAYER_3_AGENT_BROWSER_ARM64_CONFIG = `# Layer 3 (stable, arm64 only): point agent-browser at the apt-installed
 # chromium. Independent of the npm install below so it stays cached across
 # agent-browser version bumps.
@@ -1510,8 +1471,8 @@ function defaultConfig(): DockerfileConfig {
     gh: true,
     python: true,
     tmux: true,
-    cjkFonts: true,
-    cloudflared: true,
+    cjkFonts: 'auto',
+    cloudflared: false,
     xvfb: true,
     claudeCode: false,
     codexCli: false,
@@ -1519,11 +1480,13 @@ function defaultConfig(): DockerfileConfig {
   }
 }
 
-function collectToggleAptArgs(config: DockerfileConfig): string[] {
+function collectToggleAptArgs(config: DockerfileConfig, cjkFonts: boolean): string[] {
   const args: string[] = []
-  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts', 'xvfb'] as const) {
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }
+  if (cjkFonts) args.push(CJK_FONTS_PACKAGE)
+  args.push(...APT_FEATURES.xvfb.toAptArgs(config.xvfb))
   return args
 }
 

package/src/init/hatching.ts

@@ -38,7 +38,7 @@ Routing answers:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
    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\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or is in Korean asking for 친근/귀엽/다정한 tone, append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
+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\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or asks for that kind of tone in any language (e.g. Korean 친근/귀엽/다정한, Japanese かわいい/親しみやすい, Chinese 可爱/亲切, Spanish tierno/cariñoso), append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
 
 **Do not ask what they want you to do, what project you'll work on, or why they installed you.** That reveals itself when they give you a real task. Probing here makes the tool feel heavy for someone just trying it out.
 

package/src/init/index.ts

@@ -14,6 +14,7 @@ import {
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
 import { commitSystemFile } from '@/git/system-commit'
 import { createSecretsStoreForAgent, type Channels, type Secret, SecretsBackend } from '@/secrets'
+import { hostLocaleIsCjk } from '@/shared/host-locale'
 import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
@@ -660,7 +661,10 @@ export async function writeDockerAssets(root: string): Promise<DockerAssetsResul
     const typeclawConfig = await readTypeclawConfig(root)
     await writeFile(
       join(root, DOCKERFILE),
-      buildDockerfile(typeclawConfig.docker.file, { baseImageVersion: resolveBaseImageVersion(root) }),
+      buildDockerfile(typeclawConfig.docker.file, {
+        baseImageVersion: resolveBaseImageVersion(root),
+        cjkFontsAuto: hostLocaleIsCjk(),
+      }),
       { flag: 'wx' },
     ).catch(ignoreExists)
 

package/src/migrations/index.ts

@@ -0,0 +1,35 @@
+import { MIGRATION_ID, migrateSecretsV1ToV2, type SecretsMigrationResult } from './secrets-v1-to-v2'
+
+export { MIGRATION_ID, migrateSecretsV1ToV2, type SecretsMigrationResult }
+
+export type Migration = {
+  id: string
+  run: (agentDir: string) => SecretsMigrationResult
+}
+
+export type MigrationOutcome = { id: string; changed: boolean; summary: string; error?: string }
+
+const MIGRATIONS: readonly Migration[] = [{ id: MIGRATION_ID, run: migrateSecretsV1ToV2 }]
+
+// Each migration is isolated: a throw is captured per-migration so one folder's
+// unsafe state (e.g. both auth.json and a non-empty secrets.json) is reported
+// loudly without aborting boot or blocking later migrations. Returns one
+// outcome per registered migration so the caller can log what happened.
+export function runStartupMigrations(
+  agentDir: string,
+  log: (message: string) => void = (m) => console.warn(m),
+): MigrationOutcome[] {
+  const outcomes: MigrationOutcome[] = []
+  for (const migration of MIGRATIONS) {
+    try {
+      const result = migration.run(agentDir)
+      if (result.changed) log(`migration ${migration.id}: ${result.summary}`)
+      outcomes.push({ id: migration.id, changed: result.changed, summary: result.summary })
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err)
+      log(`migration ${migration.id} failed: ${error}`)
+      outcomes.push({ id: migration.id, changed: false, summary: 'failed', error })
+    }
+  }
+  return outcomes
+}

package/src/migrations/secrets-v1-to-v2.ts

@@ -0,0 +1,344 @@
+import { chmodSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import lockfile from 'proper-lockfile'
+
+import { parseSecretsFile, SECRETS_FILE_VERSION } from '@/secrets/schema'
+
+// PR #638 removed the in-memory v1->v2 upgrade that `parseSecretsFile` used to
+// perform, so a `secrets.json` still in v1 now fails to parse:
+// `hydrateChannelEnvFromSecrets` swallows the failure as `{}`, no token env vars
+// are injected, and channel adapters (Discord, Slack, Telegram) never connect.
+// This is the one-shot on-disk replacement, run once at boot rather than on
+// every parse, so the v2-only runtime keeps working without a read-time shim.
+
+const SCHEMA_REL = './node_modules/typeclaw/secrets.schema.json'
+const FILE_MODE = 0o600
+
+const LEGACY_FILENAME = 'auth.json'
+const TARGET_FILENAME = 'secrets.json'
+
+// Frozen, migration-local reverse map (env-var name -> { adapterId, field }).
+// Intentionally a private copy rather than an inversion of
+// `CHANNEL_FIELD_ENV` in src/secrets/defaults.ts: re-importing live runtime
+// defaults would (a) re-couple current code to deleted legacy surface area,
+// and (b) let a future change to the runtime env-var names silently rewrite
+// the semantics of this historical migration. A v1 file written years ago must
+// migrate the same way regardless of what the live adapters key off today.
+const LEGACY_CHANNEL_ENV_TO_FIELD: Record<string, { adapterId: string; field: string }> = {
+  DISCORD_BOT_TOKEN: { adapterId: 'discord-bot', field: 'token' },
+  SLACK_BOT_TOKEN: { adapterId: 'slack-bot', field: 'botToken' },
+  SLACK_APP_TOKEN: { adapterId: 'slack-bot', field: 'appToken' },
+  TELEGRAM_BOT_TOKEN: { adapterId: 'telegram-bot', field: 'token' },
+}
+
+export const MIGRATION_ID = '0001-secrets-v1-to-v2'
+
+export type SecretsMigrationResult = { changed: boolean; summary: string }
+
+// Idempotent: a folder already at v2 (or with no legacy file) returns
+// `changed: false`. Errors that indicate ambiguous/unsafe state throw with an
+// actionable message rather than guessing.
+//
+// Concurrency: secrets.json is the lock resource SecretsBackend (provider add,
+// OAuth refresh, channel add) and credential exporters use, so we hold ITS lock
+// across the entire precedence resolution AND upgrade. The lock requires the
+// file to exist, so when only auth.json is present we first seed secrets.json
+// with exclusive create-if-absent semantics (never overwriting a file a
+// concurrent writer may have just written), then lock, then re-read precedence
+// from fresh on-disk state under the lock.
+export function migrateSecretsV1ToV2(agentDir: string): SecretsMigrationResult {
+  const legacyPath = join(agentDir, LEGACY_FILENAME)
+  const targetPath = join(agentDir, TARGET_FILENAME)
+
+  if (!existsSync(legacyPath) && !existsSync(targetPath)) {
+    return { changed: false, summary: 'no secrets file to migrate' }
+  }
+
+  seedTargetIfAbsent(targetPath)
+
+  return withFileLock(targetPath, () => {
+    resolvePrecedenceUnderLock(legacyPath, targetPath)
+    return upgradeFileInPlace(targetPath)
+  })
+}
+
+// Creates an empty v2 envelope at secrets.json only if it does not already
+// exist, using exclusive create ('wx') so a concurrent writer that wrote real
+// credentials between our existsSync check and here is never clobbered — the
+// EEXIST is swallowed because the file we need to lock now exists, which is all
+// we required. A freshly-seeded empty envelope is indistinguishable from "no
+// target" to resolvePrecedenceUnderLock (isEmptyEnvelope returns true), so
+// "only auth.json" collapses into the "secrets.json empty -> auth wins" branch.
+function seedTargetIfAbsent(targetPath: string): void {
+  if (existsSync(targetPath)) return
+  try {
+    writeFileSync(targetPath, stringifyEmptyEnvelope(), { encoding: 'utf8', mode: FILE_MODE, flag: 'wx' })
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+  }
+}
+
+// auth.json precedence, run ENTIRELY under the secrets.json lock so the read,
+// the rename/unlink decision, and the rename itself can't interleave with a
+// concurrent secrets.json writer. Preserves the deleted migrateLegacyAuthJson
+// semantics so no credential is ever silently dropped:
+//   - no auth.json              -> operate on secrets.json as-is
+//   - droppable auth.json       -> unlink auth.json, operate on secrets.json
+//   - secrets.json empty seed   -> auth.json wins (rename over the empty seed)
+//   - both non-empty            -> hard error (can't pick a source of truth)
+function resolvePrecedenceUnderLock(legacyPath: string, targetPath: string): void {
+  if (!existsSync(legacyPath)) return
+
+  if (isDroppableLegacyFile(legacyPath)) {
+    unlinkSync(legacyPath)
+    return
+  }
+
+  if (isEmptyEnvelope(targetPath)) {
+    renameWithRaceFallback(legacyPath, targetPath)
+    chmodSync(targetPath, FILE_MODE)
+    return
+  }
+
+  throw new Error(
+    `Both ${LEGACY_FILENAME} and a non-empty ${TARGET_FILENAME} exist in the agent folder. ` +
+      `Inspect manually and remove the stale file before re-running.`,
+  )
+}
+
+function upgradeFileInPlace(path: string): SecretsMigrationResult {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return { changed: false, summary: 'secrets file unreadable; skipped' }
+  }
+  if (raw.trim() === '') return { changed: false, summary: 'secrets file empty; skipped' }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`secrets file is not valid JSON: ${err instanceof Error ? err.message : String(err)}`)
+  }
+
+  // Already current: parseSecretsFile only accepts v2 post-#638, so a successful
+  // parse means there is nothing to do.
+  if (parseSecretsFile(parsed).ok) return { changed: false, summary: 'already v2; no change' }
+
+  const upgraded = upgradeToV2(parsed)
+  if (upgraded === null) {
+    throw new Error(
+      'secrets file is neither a valid v2 envelope nor a recognized legacy (v1 / pre-envelope) shape; ' +
+        'leaving it untouched for manual inspection',
+    )
+  }
+
+  // Re-validate the product of our own transform before persisting. A transform
+  // that emitted an invalid v2 file would brick the next read; failing here is
+  // strictly safer than writing garbage.
+  const check = parseSecretsFile(upgraded)
+  if (!check.ok) {
+    throw new Error(`internal: migrated secrets file failed v2 validation: ${check.reason}`)
+  }
+
+  writeEnvelopeAtomic(path, check.file)
+  return { changed: true, summary: `upgraded secrets file to v${SECRETS_FILE_VERSION}` }
+}
+
+// Recognizes the two pre-v2 shapes the deleted parseSecretsFile branches used
+// to accept and returns a v2-shaped object. Returns null when the input matches
+// neither (caller turns that into a loud, no-write error).
+//
+//   v1 envelope:      { version: 1, llm: {...}, channels: { adapter: { ENV: value } } }
+//   pre-envelope flat: { providerId: { type, key } } at the top level
+function upgradeToV2(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return null
+  const obj = raw as Record<string, unknown>
+
+  if (obj.version === 1) {
+    return upgradeV1Envelope(obj)
+  }
+
+  if (looksLikeFlatProviders(obj)) {
+    return upgradeV1Envelope({ version: 1, llm: obj, channels: {} })
+  }
+
+  return null
+}
+
+function upgradeV1Envelope(obj: Record<string, unknown>): Record<string, unknown> {
+  const llm = isPlainObject(obj.llm) ? obj.llm : {}
+  const legacyChannels = isPlainObject(obj.channels) ? obj.channels : {}
+
+  const providers: Record<string, unknown> = {}
+  for (const [providerId, cred] of Object.entries(llm)) {
+    if (!isPlainObject(cred)) continue
+    if (cred.type === 'api_key' && typeof cred.key === 'string') {
+      providers[providerId] = { type: 'api_key', key: { value: cred.key } }
+    } else {
+      // OAuth and any unknown credential type pass through verbatim — they are
+      // not env-injectable and the v2 schema accepts them via catchall.
+      providers[providerId] = cred
+    }
+  }
+
+  const channels: Record<string, Record<string, unknown>> = {}
+  for (const [adapterId, slot] of Object.entries(legacyChannels)) {
+    if (!isPlainObject(slot)) continue
+    const upgradedSlot: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(slot)) {
+      if (typeof value !== 'string') {
+        // A non-string value means this isn't the flat env-keyed v1 channel
+        // shape (e.g. a kakaotalk block, which is structured). Preserve it
+        // verbatim so the catchall keeps it valid; do not try to reshape.
+        upgradedSlot[key] = value
+        continue
+      }
+      const mapping = LEGACY_CHANNEL_ENV_TO_FIELD[key]
+      if (mapping && mapping.adapterId === adapterId) {
+        upgradedSlot[mapping.field] = { value }
+      } else {
+        // Unknown env-var key on a known adapter, or an unknown adapter:
+        // preserve under the original key but still wrap as a v2 Secret so the
+        // resulting file is valid v2.
+        upgradedSlot[key] = { value }
+      }
+    }
+    channels[adapterId] = upgradedSlot
+  }
+
+  const result: Record<string, unknown> = {
+    $schema: typeof obj.$schema === 'string' ? obj.$schema : SCHEMA_REL,
+    version: SECRETS_FILE_VERSION,
+    providers,
+    channels,
+  }
+  return result
+}
+
+// A flat pre-envelope file is a top-level record of provider credentials. Every
+// value must be a credential object with a `type` field; anything else means we
+// don't recognize the shape and should not guess.
+function looksLikeFlatProviders(obj: Record<string, unknown>): boolean {
+  const entries = Object.entries(obj).filter(([k]) => k !== '$schema')
+  if (entries.length === 0) return false
+  return entries.every(([, value]) => isPlainObject(value) && typeof value.type === 'string')
+}
+
+function isEmptyEnvelope(path: string): boolean {
+  const parsed = readJsonOrNull(path)
+  if (parsed === undefined) return true
+  if (parsed === null) return false
+  const result = parseSecretsFile(parsed)
+  if (!result.ok) return false
+  return Object.keys(result.file.providers).length === 0 && Object.keys(result.file.channels).length === 0
+}
+
+// True only when a legacy auth.json carries nothing worth keeping, so dropping
+// it in favor of an existing secrets.json is safe: a missing/blank file, or a
+// valid-but-empty v2 envelope. Anything else parseable — a legacy shape with
+// credentials OR a parseable-but-unrecognized object — returns false so
+// resolveLegacyFilename falls through to the both-non-empty hard error rather
+// than silently deleting a file whose contents we can't account for.
+function isDroppableLegacyFile(path: string): boolean {
+  const parsed = readJsonOrNull(path)
+  if (parsed === undefined) return true
+  if (parsed === null) return false
+  const v2 = parseSecretsFile(parsed)
+  if (!v2.ok) return false
+  return Object.keys(v2.file.providers).length === 0 && Object.keys(v2.file.channels).length === 0
+}
+
+// undefined = file missing/blank (treat as empty); null = present but invalid
+// JSON (treat as "has content we can't safely drop").
+function readJsonOrNull(path: string): unknown {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return undefined
+  }
+  if (raw.trim() === '') return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+function stringifyEmptyEnvelope(): string {
+  return `${JSON.stringify({ $schema: SCHEMA_REL, version: SECRETS_FILE_VERSION, providers: {}, channels: {} }, null, 2)}\n`
+}
+
+function writeEnvelopeAtomic(path: string, envelope: unknown): void {
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(tmp, `${JSON.stringify(envelope, null, 2)}\n`, { encoding: 'utf8', mode: FILE_MODE })
+  try {
+    renameSync(tmp, path)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // best-effort cleanup of the temp file when rename fails
+    }
+    throw err
+  }
+  chmodSync(path, FILE_MODE)
+}
+
+// renameSync is atomic per syscall, but two concurrent migration runs can both
+// observe auth.json exists and secrets.json does not, then race on the rename.
+// One wins; the loser gets ENOENT because the source is already gone — that is
+// a successful migration from its POV, so recheck the target and swallow it.
+function renameWithRaceFallback(from: string, to: string): void {
+  try {
+    renameSync(from, to)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT' && existsSync(to)) return
+    throw err
+  }
+}
+
+// Mirror SecretsBackend's lock discipline so a concurrent credential write
+// (provider add, OAuth refresh, channel add) can't interleave with the
+// read-transform-write. proper-lockfile needs the target to exist; the target
+// always exists by the time we lock (resolveLegacyFilename guarantees it).
+function withFileLock<T>(path: string, fn: () => T): T {
+  let release: (() => void) | undefined
+  try {
+    release = acquireSyncLockWithRetry(path)
+    return fn()
+  } finally {
+    release?.()
+  }
+}
+
+const SYNC_LOCK_RETRIES = 10
+const SYNC_LOCK_DELAY_MS = 20
+
+function acquireSyncLockWithRetry(path: string): () => void {
+  let lastError: unknown
+  for (let attempt = 1; attempt <= SYNC_LOCK_RETRIES; attempt++) {
+    try {
+      return lockfile.lockSync(path, { realpath: false })
+    } catch (error) {
+      const code =
+        typeof error === 'object' && error !== null && 'code' in error
+          ? String((error as { code: unknown }).code)
+          : undefined
+      if (code !== 'ELOCKED' || attempt === SYNC_LOCK_RETRIES) throw error
+      lastError = error
+      const start = Date.now()
+      while (Date.now() - start < SYNC_LOCK_DELAY_MS) {
+        // intentionally empty: synchronous busy-wait to match SecretsBackend
+      }
+    }
+  }
+  throw (lastError as Error | undefined) ?? new Error('Failed to acquire secrets store lock')
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/run/bundled-plugins.ts

@@ -6,6 +6,8 @@ import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import operatorPlugin from '@/bundled-plugins/operator'
+import plannerPlugin from '@/bundled-plugins/planner'
+import researcherPlugin from '@/bundled-plugins/researcher'
 import reviewerPlugin from '@/bundled-plugins/reviewer'
 import scoutPlugin from '@/bundled-plugins/scout'
 import securityPlugin from '@/bundled-plugins/security'
@@ -59,5 +61,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
   { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
   { name: 'reviewer', version: undefined, source: '<bundled>', defined: reviewerPlugin },
+  { name: 'researcher', version: undefined, source: '<bundled>', defined: researcherPlugin },
+  { name: 'planner', version: undefined, source: '<bundled>', defined: plannerPlugin },
   { name: 'operator', version: undefined, source: '<bundled>', defined: operatorPlugin },
 ]

package/src/run/index.ts

@@ -42,6 +42,7 @@ import {
 } from '@/cron'
 import { CLI_VERSION } from '@/init/cli-version'
 import { createMcpManager } from '@/mcp'
+import { runStartupMigrations } from '@/migrations'
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createPluginLogger } from '@/plugin/context'
 import type { CronHandlerContext } from '@/plugin/types'
@@ -194,6 +195,12 @@ export async function startAgent({
     materializedSkills: null,
   })
 
+  // Graduate any pre-0.20.0 on-disk shapes (v1 secrets.json, legacy auth.json)
+  // to the current v2 envelope before anything reads secrets — otherwise the
+  // v2-only parser rejects the file and hydrate below sees no channels. Runs
+  // exactly once per folder; a folder already at v2 is a no-op.
+  runStartupMigrations(cwd)
+
   // Channel adapters read `process.env[TOKEN_ENV]` (see channels/manager.ts).
   // Hydrate fills any unset env var from secrets.json#channels via env-wins:
   // values already in process.env (from `docker --env-file .env`) are kept
@@ -329,6 +336,8 @@ export async function startAgent({
         ...(subagentOptions?.spawnedByRole !== undefined ? { spawnedByRole: subagentOptions.spawnedByRole } : {}),
         ...(subagentOptions?.spawnedByOrigin !== undefined ? { spawnedByOrigin: subagentOptions.spawnedByOrigin } : {}),
       }
+      const allowBackgroundFromSubagent =
+        entry.pluginSubagent.canBackgroundSpawnSubagents === true && entry.pluginSubagent.canSpawnSubagents === true
       const created = await createSessionWithDispose({
         systemPromptOverride: entry.pluginSubagent.systemPrompt,
         sessionManager,
@@ -359,6 +368,7 @@ export async function startAgent({
               liveSubagentRegistry,
               subagentRegistry: snap.subagents,
               createSessionForSubagent,
+              allowBackgroundFromSubagent,
             }
           : {}),
         ...(entry.pluginSubagent.profile !== undefined ? { profile: entry.pluginSubagent.profile } : {}),
@@ -380,6 +390,9 @@ export async function startAgent({
         agentDir: cwd,
         origin,
         getTranscriptPath: () => sessionManager.getSessionFile(),
+        ...(allowBackgroundFromSubagent
+          ? { backgroundDrain: { stream, sessionId, liveRegistry: liveSubagentRegistry } }
+          : {}),
       }
     }
     return defaultCreateSessionForSubagent(subagent, subagentOptions)

package/src/sandbox/availability.ts

@@ -33,3 +33,15 @@ async function probe(bwrap: string): Promise<boolean> {
 export function _resetBwrapAvailabilityCacheForTests(): void {
   availabilityCache.clear()
 }
+
+// The bun binary this process runs as (process.execPath). build.ts re-exposes
+// it at /proc/self/exe over the masked /proc so sandboxed package runners can
+// self-locate. This is correct ONLY in the bun-centric container: the base
+// image (oven/bun:1-slim) ships no real node — `node` is a bun symlink and
+// bunx/npx/pnpx all resolve to bun (Bun's fake-node model), so every runtime
+// reading /proc/self/exe IS bun. A real node binary would self-locate to the
+// wrong ELF here; if node is ever added to the image this must resolve the
+// actual interpreter instead.
+export function resolveProcSelfExe(): string {
+  return process.execPath
+}

package/src/sandbox/build.ts

@@ -103,6 +103,18 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
     // (leaks the outer container's /proc/N/environ — including
     // FIREWORKS_API_KEY — into the sandbox). See sandbox.mdx.
     argv.push('--tmpfs', '/proc')
+
+    // Re-expose ONLY the bun ELF at /proc/self/exe so sandboxed package runners
+    // can self-locate; /proc/N/environ stays masked by the tmpfs above. The
+    // caller passes bun's path (see resolveProcSelfExe): in this bun-centric
+    // container bunx/npx/pnpx all resolve to bun, so bun IS the runtime reading
+    // /proc/self/exe. --symlink (not --ro-bind /proc/self/exe): /proc/self at
+    // setup time is bwrap's pid, so a bind would capture bwrap's own binary.
+    // Must come AFTER --tmpfs /proc (last-op-wins) or the tmpfs erases it.
+    if (policy.procSelfExe !== undefined) {
+      argv.push('--ro-bind', policy.procSelfExe, policy.procSelfExe)
+      argv.push('--symlink', policy.procSelfExe, '/proc/self/exe')
+    }
   }
 
   for (const mount of policy.mounts ?? []) {

package/src/sandbox/index.ts

@@ -1,5 +1,5 @@
 export { buildSandboxedCommand, type SandboxedCommand } from './build'
-export { ensureBwrapAvailable, _resetBwrapAvailabilityCacheForTests } from './availability'
+export { ensureBwrapAvailable, resolveProcSelfExe, _resetBwrapAvailabilityCacheForTests } from './availability'
 export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
 export {
   resolveProtectedZones,