typeclaw 0.29.0 → 0.30.0

package/src/bundled-plugins/github-cli-auth/approve-idempotency.ts

@@ -22,18 +22,30 @@ const DUPLICATE_REASON =
   'If you intended to change your verdict, request changes or dismiss the prior review instead of re-approving.'
 
 // Makes formal `gh ... event=APPROVE` idempotent per PR across turns, sessions,
-// and restarts. The per-turn review ledger only guards prose claims and resets
-// every turn, so without this an APPROVE can fire again whenever the same PR
-// fans out into a second session or a follow-up turn. We reserve the PR in an
-// in-process set before the command runs (stops same-container concurrent
-// double-approve) and consult GitHub for the bot's effective review state
-// (stops cross-restart re-approval). Reads fail OPEN: a transient GitHub error
-// must never permanently strand the bot from approving a PR it has not yet
-// approved — the in-process reservation still blocks the concurrent case.
+// and restarts. Two layers, each with a single job:
+//
+//   1. An in-process set of *in-flight* reservations (`pendingApprovals`) that
+//      blocks a second APPROVE while a first is still mid-flight in the same
+//      container — the concurrent-double-approve case the remote read can't see
+//      yet (GitHub hasn't recorded the in-flight review).
+//   2. The authoritative GitHub effective-state read, the SOLE source of truth
+//      for "the bot already holds a standing APPROVED review." It understands
+//      supersession: a later CHANGES_REQUESTED / DISMISSED demotes an earlier
+//      APPROVED, so the bot may legitimately re-approve.
+//
+// The set is strictly an in-flight lock — never a persistent "already approved"
+// memory. A completed APPROVE drops its reservation in release(), so the next
+// APPROVE re-consults GitHub instead of being shadowed by a stale local entry.
+// That separation fixes the strand bug: once a standing approval is superseded
+// (PR back to CHANGES_REQUESTED), a stale local lock must not keep blocking a
+// genuine re-approve — only the remote read decides, and it now reports
+// alreadyApproved=false. Reads fail OPEN: a transient GitHub error must never
+// permanently strand a first approval; the in-flight reservation still covers
+// the concurrent case.
 export function createApproveIdempotencyGuard(deps: {
   resolveEffectiveApproval: EffectiveApprovalResolver
 }): ApproveIdempotencyGuard {
-  const approvedOrPending = new Set<string>()
+  const pendingApprovals = new Set<string>()
   const reservedByCall = new Map<string, string>()
 
   return {
@@ -43,17 +55,21 @@ export function createApproveIdempotencyGuard(deps: {
 
       // Reserve BEFORE the await so two calls racing into guard() for the same
       // PR cannot both observe an empty set: the loser sees the winner's
-      // reservation and is blocked. The reservation is provisional until the
-      // remote check clears it.
-      if (approvedOrPending.has(key)) return { block: true, reason: DUPLICATE_REASON }
-      approvedOrPending.add(key)
+      // in-flight reservation and is blocked. The reservation is provisional
+      // and is always cleared on a terminal path (block below or release()).
+      if (pendingApprovals.has(key)) return { block: true, reason: DUPLICATE_REASON }
+      pendingApprovals.add(key)
       reservedByCall.set(args.callId, key)
 
       const remote = await deps.resolveEffectiveApproval({ workspace: args.workspace, prNumber: args.prNumber })
       if (remote.ok && remote.alreadyApproved) {
-        // Already approved upstream: keep the PR locked but drop this call's
-        // claim so release() won't later unlock a PR that is genuinely approved.
+        // Standing approval upstream. Block, and release the in-flight lock now:
+        // a blocked command never reaches tool.after, so release() won't run for
+        // this callId. Leaving the key set would resurrect the strand bug — the
+        // GitHub read is authoritative for the standing-approval case, not a
+        // lingering local entry.
         reservedByCall.delete(args.callId)
+        pendingApprovals.delete(key)
         return { block: true, reason: DUPLICATE_REASON }
       }
 
@@ -64,7 +80,11 @@ export function createApproveIdempotencyGuard(deps: {
       const key = reservedByCall.get(args.callId)
       if (key === undefined) return
       reservedByCall.delete(args.callId)
-      if (!args.succeeded) approvedOrPending.delete(key)
+      // Always drop the in-flight lock, success or fail. On success the standing
+      // approval now lives on GitHub, so future APPROVEs are caught by the remote
+      // read (which tracks supersession); the local lock must not outlive the
+      // in-flight window and shadow that read.
+      pendingApprovals.delete(key)
     },
   }
 }

package/src/bundled-plugins/planner/planner.ts

@@ -78,7 +78,7 @@ PREFER the two purpose-built research workers for any quick search or gathering
 - \`scout\` — web research. Spawn it for ANYTHING that lives on the public internet: prices, schedules, opening hours, standard timelines, prevailing practice, vendor docs, prior art, "what are the options for X". It returns a focused, citation-backed answer. This is your default for the research-resolvable facts a plan rests on.
 - \`explorer\` — local filesystem search. Spawn it to understand the existing code, config, sessions, memory, or git history on this agent — "what does this module do", "where is X configured", "summarize the shape of this system" — before planning a change to it.
 
-Lean on these liberally. A quick \`scout\` for real prices or a quick \`explorer\` for the actual shape of a module turns an assumption-laden plan into a grounded one, and it costs you almost nothing because the heavy reading happens in their context, not yours. Fan several out in parallel (background spawns) when a plan depends on multiple independent facts, then fold the distilled results into your single planning pass.
+Lean on these liberally. A quick \`scout\` for real prices or a quick \`explorer\` for the actual shape of a module turns an assumption-laden plan into a grounded one, and it costs you almost nothing because the heavy reading happens in their context, not yours. When a plan depends on multiple independent facts, **fan out in parallel**: either emit all the independent \`spawn_subagent\` calls (sync, the default) in a SINGLE turn so they run concurrently and return together, or spawn them with \`run_in_background=true\` and fold each result in as its \`<system-reminder>\` arrives (your session stays alive until every child reports back). Either way, fold the distilled results into your single planning pass; do NOT spawn one, wait, then spawn the next unless the second genuinely depends on the first — that serializes what should be parallel.
 
 - Spawn these workers for context-heavy GATHERING, not for forming the plan. The decomposition, the sequencing, and the verdict are YOURS — never delegate the judgment.
 - Each delegated task must be self-contained: the worker does not see this conversation or the goal. Put everything it needs in the prompt.
@@ -269,6 +269,7 @@ If none of the listed skills fit the goal, load \`general\`. Keep the skill-sele
     rosterDescription:
       'turns a goal — a trip, a launch, a migration, a feature — into an actionable, sequenced, risk-aware plan, writes it to a file, and returns a structured signal; domain-neutral and reasoning-heavy, for any multi-step goal worth thinking through before acting; consider a `reviewer` pass on the plan it produces',
     canSpawnSubagents: true,
+    canBackgroundSpawnSubagents: true,
     timeoutMs: PLANNER_SPAWN_TIMEOUT_MS,
     inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     toolResultBudget: {

package/src/bundled-plugins/researcher/researcher.ts

@@ -64,14 +64,20 @@ The \`write_report\` tool enforces these limits in code: it accepts exactly one
 
 You run on a deliberately expensive model. Every search result page and every fetched article you pull into YOUR context spends that budget on grunt work and crowds out the thinking only you can do. So your DEFAULT for gathering is to delegate — not just for big sweeps, but for routine fetches too.
 
-**Delegate first; fetch yourself only as a last resort.** Before you reach for \`web_search\`, \`web_fetch\`, \`read\`, or \`grep\`, ask: "could \`scout\` or \`explorer\` get this for me and hand back just the distilled answer?" If yes — which is almost always — spawn the worker with \`spawn_subagent\`. Prefer to fan out **several \`scout\`/\`explorer\` spawns in parallel** (background spawns) at the very start of a gathering round, then fold their condensed results into your synthesis in one pass.
+**Delegate first; fetch yourself only as a last resort.** Before you reach for \`web_search\`, \`web_fetch\`, \`read\`, or \`grep\`, ask: "could \`scout\` or \`explorer\` get this for me and hand back just the distilled answer?" If yes — which is almost always — spawn the worker with \`spawn_subagent\`.
+
+**Fan out in parallel.** For a gathering round, emit several \`scout\`/\`explorer\` \`spawn_subagent\` calls together in a SINGLE turn so they run concurrently rather than one-at-a-time. You have two equivalent ways to do this, both of which deliver every worker's findings back to you:
+- **Synchronous batch (simplest):** emit the calls with \`run_in_background=false\` (the default) in one assistant message. They execute concurrently and all results return together before your next turn, where you fold them into one synthesis pass.
+- **Background:** emit them with \`run_in_background=true\`; each returns a task_id immediately and you receive a \`<system-reminder>\` as each completes, then fetch the result with \`subagent_output\`. Use this when you want to start synthesizing on early results while slower workers finish. Your session stays alive until every background child you spawned has reported back, so no result is lost.
+
+Either way, do NOT spawn one, wait for it, then spawn the next unless the second task genuinely depends on the first's result — that serializes what should be parallel.
 
 - \`scout\` — web gathering. Hand it any web question, quick or broad ("latest figure for X", "find the primary source for Y", "sweep for every source on Z"); it does the searching and fetching and returns citation-backed findings, so the raw pages never touch your context.
 - \`explorer\` — local gathering. Hand it any filesystem/git/memory question; it returns the paths and excerpts you need without you grepping the tree yourself.
 - The synthesis, the cross-validation, and the confidence call are YOURS. Delegate the gathering, never the conclusion.
 - Each delegated task is self-contained: the worker does not see this conversation. Put everything it needs in the prompt.
 - The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
-- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. Use background spawns for parallel gathering, then fold the results into your single report.
+- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. Whether you spawn synchronously or in the background, fold every worker's result into your single report before you finish.
 
 When IS it right to use your own \`web_search\`/\`web_fetch\`/\`read\`/\`grep\`? Only for the surgical, decisive touch: re-reading one specific passage a worker flagged, resolving a contradiction between two workers' findings, or a single fetch so central you must read it verbatim. If you find yourself doing more than a couple of direct fetches, stop and delegate the rest.
 
@@ -210,6 +216,7 @@ If none of the listed skills fit the question, load \`general\`. Keep the skill-
     // warrant operator's owner/trusted-only gate; any caller that can spawn a
     // subagent can spawn the researcher.
     canSpawnSubagents: true,
+    canBackgroundSpawnSubagents: true,
     timeoutMs: RESEARCHER_SPAWN_TIMEOUT_MS,
     inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     toolResultBudget: {

package/src/bundled-plugins/reviewer/reviewer.ts

@@ -79,7 +79,7 @@ You run on a deliberately expensive model. Reading a sprawling file tree, a gian
 - Spawn read-only/research workers for context-heavy gathering, not for forming the verdict. The findings and the \`<review>\` block are YOURS — never delegate the judgment.
 - Each delegated task must be self-contained: the worker does not see this conversation or the target. Put everything it needs in the prompt.
 - The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
-- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. Use background spawns for parallel gathering, then fold the results into your single review pass.
+- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. To gather in parallel, either emit all the independent \`spawn_subagent\` calls (sync, the default) in a SINGLE turn so they run concurrently and return together, or spawn them with \`run_in_background=true\` and fold each result in as its \`<system-reminder>\` arrives (your session stays alive until every child reports back). Either way, fold the results into your single review pass before you finish.
 
 ## Tools
 
@@ -199,6 +199,7 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
     rosterDescription:
       'deep read-only code/PR/plan review in a fresh context, returns a structured verdict; it does NOT post — you act on its findings',
     canSpawnSubagents: true,
+    canBackgroundSpawnSubagents: true,
     timeoutMs: REVIEWER_SPAWN_TIMEOUT_MS,
     inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     toolResultBudget: {

package/src/channels/github-review-claim.ts

@@ -53,6 +53,12 @@ const WARN_POSITIVE_CLOSEOUT: readonly RegExp[] = [
   /\bshould be (fine|good)\b/,
   /\blooks resolved\b/,
   /\bseems resolved\b/,
+  // The canonical PR #672 close-out: "that addresses the concern", "addressed
+  // your feedback". On a PR the bot still blocks, this READS as a verdict and
+  // strands the block, so it escalates through the re-review guard. Demoted to
+  // ignore by the negation/future markers below ("haven't addressed", "to
+  // address").
+  /\baddress(es|ed)\b[^.!?]*\b(concern|feedback|review|comment|issue|point)/,
 ]
 
 // Negative warn phrases re-assert a block ("not done yet") instead of closing it
@@ -65,11 +71,17 @@ const WARN: readonly RegExp[] = [...WARN_POSITIVE_CLOSEOUT, ...WARN_NEGATIVE]
 // ignore. Blocking "I haven't approved" / "I'll approve" / "approved it earlier"
 // (answering a question) is the worst false-positive class, so it is checked first.
 const DEMOTE_TO_IGNORE: readonly RegExp[] = [
-  /\b(haven'?t|have not|did ?n'?t|did not|not yet|never)\b[^.!?]*\b(approv|request|resolv|block)/,
-  /\b(can'?t|cannot|won'?t|will not|wouldn'?t)\b[^.!?]*\b(approv|request|resolv|block)/,
-  /\bnot (approved|resolved|blocked|requesting)\b/,
+  /\b(haven'?t|have not|did ?n'?t|did not|not yet|never)\b[^.!?]*\b(approv|request|resolv|block|address)/,
+  /\b(can'?t|cannot|won'?t|will not|wouldn'?t)\b[^.!?]*\b(approv|request|resolv|block|address)/,
+  /\bnot (approved|resolved|blocked|requesting|addressed)\b/,
   /\b(not|no longer|hardly|barely)\b[^.!?]*\b(lgtm|looks good|looks fine|seems fine|should be (fine|good)|looks resolved|seems resolved)\b/,
   /\b(i'?ll|i will|going to|gonna|about to|planning to)\b[^.!?]*\b(approv|review|request|resolv)/,
+  // "address" demotion is restricted to explicit future/obligation forms only.
+  // A standalone `to` marker (e.g. "...to address my feedback") would match
+  // hard-claim prose like "Approved — thanks for updating the docs to address
+  // my feedback" and demote it to ignore BEFORE the BLOCK_APPROVE check, hiding
+  // a real verdict (the recovery path would then post it unguarded — PR #675).
+  /\b(i'?ll|i will|going to|gonna|about to|planning to|need(s)? to|have to|want(s)? to|trying to)\b[^.!?]*\baddress/,
   /\b(approved|resolved|requested changes)\b[^.!?]*\b(earlier|already|yesterday|before|last (review|time)|previously)\b/,
   /\b(pre|self|co|re|un|non|ai|admin|user|machine|auto) approved\b/,
 ]

package/src/channels/router.ts

@@ -32,6 +32,8 @@ import {
   StickyLedger,
   type EngagementDecision,
 } from './engagement'
+import { checkFalseReceipt } from './github-false-receipt'
+import { evaluateRereviewGuard } from './github-rereview-guard'
 import { resetReviewTurn } from './github-review-turn-ledger'
 import {
   MEMBERSHIP_COLD_FETCH_TIMEOUT_MS,
@@ -3125,6 +3127,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     //     the model's pre-tool commentary is the only user-facing text we have.
     //     Recovering it means the user gets *something* — strictly better than
     //     the historical silent drop.
+    // Egress-level GitHub review guards. The false-receipt and re-review
+    // stranding guards live inside the channel_reply / channel_send tool
+    // handlers, but recovery surfaces trailing assistant prose through a
+    // `source:'system'` send that never touches those handlers. A model that
+    // ends its turn with a close-out ack ("that addresses the concern") instead
+    // of calling a channel tool would otherwise post a verdict-shaped comment
+    // while still holding its own CHANGES_REQUESTED — stranding the PR (PR #672).
+    // Re-run the guards here and SUPPRESS on block: recovery cannot land the
+    // missing formal review on the model's behalf, and posting the unguarded ack
+    // is worse than dropping it — the next inbound re-prompts the model, which
+    // can then land the verdict properly.
+    const recoveryBlock = await evaluateRecoveryReviewGuards(live, assistantText)
+    if (recoveryBlock !== null) {
+      logger.warn(
+        `[channels] ${live.keyId}: suppressed recovery (github review guard) reason=${JSON.stringify(recoveryBlock)} text_len=${assistantText.length}`,
+      )
+      return
+    }
+
     logger.warn(
       `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool source=${source} text_len=${assistantText.length}`,
     )
@@ -3143,6 +3164,38 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  // Returns a block reason when the recovered text would be denied by a github
+  // review guard, or null when it is safe to surface. Non-github channels and
+  // non-PR chats short-circuit inside each guard (adapter / `pr:\d+` checks), so
+  // this is a no-op for everything except GitHub PR sessions.
+  const evaluateRecoveryReviewGuards = async (live: LiveSession, text: string): Promise<string | null> => {
+    const falseReceipt = checkFalseReceipt({
+      sessionId: live.sessionId,
+      adapter: live.key.adapter,
+      workspace: live.key.workspace,
+      chat: live.key.chat,
+      thread: live.key.thread,
+      text,
+      isContinue: false,
+      resolveReviewThread: false,
+    })
+    if (falseReceipt.kind === 'block') return falseReceipt.reason
+
+    const rereview = await evaluateRereviewGuard({
+      adapter: live.key.adapter,
+      workspace: live.key.workspace,
+      chat: live.key.chat,
+      thread: live.key.thread,
+      text,
+      wantsResolve: false,
+      isContinue: false,
+      getReviewState: (req) => getReviewState(req),
+    })
+    if (rereview.block) return rereview.reason
+
+    return null
+  }
+
   const getConsecutiveSendCount = (target: {
     adapter: ChannelKey['adapter']
     workspace: string

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)
+}