@coworker-jp/aidr 0.1.321 → 0.1.323

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coworker-jp/aidr",
-  "version": "0.1.321",
+  "version": "0.1.323",
   "description": "AIDR setup CLI - installs ai-scanner hooks for 19+ AI coding agents",
   "type": "module",
   "bin": {

package/src/agents/codex.mjs

@@ -52,8 +52,10 @@ const CODEX_AGENTS_MD = `# AIDR Scanner
 
 AIDR security scanner is active for this Codex session. Set the access key
 via the \`AI_SCANNER_ACCESS_KEY\` environment variable. Hooks are registered
-in \`.codex/hooks.json\` and require \`[features] codex_hooks = true\` in
-\`.codex/config.toml\` (this setup writes both for you).
+in \`.codex/hooks.json\` and require \`[features] hooks = true\` in
+\`.codex/config.toml\` (this setup writes both for you). The older
+\`[features] codex_hooks\` spelling is deprecated by Codex — if your config
+still has it, setup renames it to \`hooks\` in place.
 
 Codex currently emits Bash tool events only. Read / Edit / WebFetch / WebSearch
 are not hookable — for those, use Claude Code.
@@ -183,7 +185,7 @@ async function mergeCodexConfigToml(target, { dryRun, stderr = process.stderr })
     if (stat) {
       stderr.write(
         `WARNING: ${target} already exists. (dry-run: would back up)\n` +
-        `Merging [features] codex_hooks; your other settings are preserved.\n`
+        `Merging [features] hooks (the deprecated codex_hooks key is migrated if present); your other settings are preserved.\n`
       );
     }
     process.stdout.write(
@@ -199,7 +201,7 @@ async function mergeCodexConfigToml(target, { dryRun, stderr = process.stderr })
     await fsp.copyFile(target, backupPath);
     stderr.write(
       `WARNING: ${target} already exists. Backed up to ${backupPath}.\n` +
-      `Merging [features] codex_hooks; your other settings are preserved.\n`
+      `Merging [features] hooks (the deprecated codex_hooks key is migrated if present); your other settings are preserved.\n`
     );
   }
 

package/src/templates.mjs

@@ -11,11 +11,44 @@ export function getSettingsJson(accessKey, scope = "project") {
 }
 
 // start_scanner.sh — parameterized by the verify endpoint (prod / dev).
+// ── このスクリプトが端末へ出す文言は ja / en を併記する (issue #2372 条件 3) ──
+//
+// **決定 (2026-09-09): (a) 併記する。** `docs/product/UI_COPY.md` の表の
+// 「`aidr` CLI (端末のターミナルに出る文字列)」の行が既にこう決めており、
+// **その行の理由がこの面にそのまま当たる**:
+//
+//   * **読み手を実行時に特定できない。** 同じ端末で情シスも開発者も読む。
+//   * **出し分ける先が無い。** フックはロケールを持たない bash なので、
+//     1 つの出力を全員が読む。**片方だけにすると、読めない側にとっては
+//     何も書かれていないのと同じである。**
+//
+// この 2 つは「利用者が打ったコマンド」かどうかに依存しない。むしろこの面は
+// CLI より弱い —— **利用者はこの出力を頼んでいない**ので、読めない言語で
+// 出された行は、そのまま読み飛ばされる。
+//
+// **(b)「フックの stderr は en のみ」と明文化する案は採らなかった。** 採れば
+// この面だけが表の 4 行のどれとも違う基準を持つことになり、**なぜここだけ
+// 違うのかを説明できない** (英語だけだったのは判断の結果ではなく、
+// 基準を持たないまま書かれ続けた結果である —— `UI_COPY.md` の
+// `GAP-2355-CLI-COPY-JA-EN-UNEVEN` がその状態を名指ししている)。
+//
+// **★ 短くするために事実や次の行動を削らないこと** (`UI_COPY.md` 【非交渉】)。
+// 1 文が長くなるなら**文を割る**。en 行はそのまま残してある —— 併記は
+// 「英語を日本語で置き換える」ことではない。
+//
+// **ここで揃うのはこのスクリプトだけである** (`GAP-2372-AIDR-JA-EN-PARTIAL`)。
+// `packages/aidr` の他の出力 (`red-team.mjs::redTeamInstallFailureText` など) は
+// 英語のままで、揃えるのは別の作業である。**「aidr は併記済み」と読まないこと。**
 // `agentType` is currently unused inside the script (endpoint-info has moved
 // to schedule-only invocation via aidr --scheduled), but the parameter
 // is kept for signature stability with callers and the wider TS template.
 // eslint-disable-next-line no-unused-vars
 export function getStartScannerSh(downloadBase = "https://pytd2jd5p7.execute-api.ap-northeast-1.amazonaws.com/download", agentType = "claude-code") {
+  // `agentType` is the endpoint-info spelling (`claude-code`); `setup --agent`
+  // takes the installer/portal spelling (`claude`). They differ for exactly one
+  // agent, so the mapping is stated here rather than guessed at the call site —
+  // guessing would make the self-repair below configure the WRONG agent.
+  const setupAgentName = agentType === "claude-code" ? "claude" : agentType;
   // Which installer to quote back at the user, derived from the endpoint this
   // script was generated against. The DEV package must never tell anyone to
   // install PROD (same rule as cli.mjs's INSTALL_COMMAND_HINT) — and here the
@@ -198,6 +231,7 @@ ensure_binary() {
         url="\${DOWNLOAD_BASE}/\${product}/\${PLATFORM_SLUG}"
     fi
     if download_binary "$url" "$dest"; then
+        echo "$product のバイナリを導入しました (\${PLATFORM_SLUG}、チェックサム検証済み)。" >&2
         echo "$product binary installed (\${PLATFORM_SLUG}, checksum verified)" >&2
         return 0
     fi
@@ -221,6 +255,7 @@ report_unscanned_history() {
     # itself is the fallback — printing nothing here would drop the fact.
     local when
     when=$(date -d "@$first" 2>/dev/null || date -r "$first" 2>/dev/null || echo "epoch $first")
+    echo "ai-scanner: この端末では、すでに $count 件のツールコールが検査されないまま実行されています (最初は $when)。" >&2
     echo "ai-scanner: $count tool call(s) have already run unscanned on this machine (first at $when)." >&2
 }
 
@@ -229,8 +264,10 @@ report_unscanned_history() {
 # reads as cosmetic (docs/product/UI_COPY.md 【非交渉】) — and unlike a failed
 # download, re-running the installer cannot fix it, so the action is different.
 unsupported_platform() {
+    echo "ai-scanner: このセッションは検査されていません。このプラットフォーム ($1) 向けのスキャナーが存在しません。" >&2
     echo "ai-scanner: this session is NOT being scanned — there is no scanner build for this platform ($1)." >&2
     report_unscanned_history
+    echo "ai-scanner: ツールコールは動き続けますが、この端末では検査されないまま実行されます。このメッセージを添えて、社内の IT 管理者にご連絡ください。" >&2
     echo "ai-scanner: tool calls keep working, and they run unscanned on this machine. Contact your IT administrator with this message." >&2
 }
 
@@ -282,8 +319,10 @@ if ensure_binary "$HARNESS" ai-harness; then
     # record only ever describes the machine's CURRENT state.
     rm -f "$UNSCANNED_STAMP"
 else
+    echo "ai-scanner: このセッションは検査されていません。ツールコール検査機 (ai-harness) がこの端末になく、今回も導入できませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。" >&2
     echo "ai-scanner: this session is NOT being scanned — the tool-call scanner (ai-harness) is not installed on this machine and could not be installed now: \${UNVERIFIED_REASON:-the download failed}." >&2
     report_unscanned_history
+    echo "ai-scanner: ツールコールは動き続けますが、導入されるまで検査されないまま実行されます。導入コマンド (${installCommand}) をもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
     echo "ai-scanner: tool calls keep working, and they run unscanned until it is in place. Re-run the installer (${installCommand}), or contact your IT administrator with this message." >&2
 fi
 
@@ -295,8 +334,10 @@ if ! ensure_binary "$BIN" ai-scanner; then
     # Only claims scanning is unaffected when it actually is — the harness may
     # have failed too, and the line above is the one that says so.
     if [ "$SCANNING" = 1 ]; then
+        echo "ai-scanner: ツールコールの検査は続いています。ただし定期の端末情報収集は導入できませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。この端末がポータルに現れなくなったら、導入コマンド (${installCommand}) をもう一度実行してください。" >&2
         echo "ai-scanner: tool calls are still being scanned, but the periodic endpoint-inventory collector could not be installed: \${UNVERIFIED_REASON:-the download failed}. Re-run the installer (${installCommand}) if this endpoint stops appearing in the portal." >&2
     else
+        echo "ai-scanner: 定期の端末情報収集も導入できませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。導入コマンド (${installCommand}) をもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
         echo "ai-scanner: the periodic endpoint-inventory collector could not be installed either: \${UNVERIFIED_REASON:-the download failed}. Re-run the installer (${installCommand}), or contact your IT administrator with this message." >&2
     fi
 fi
@@ -325,13 +366,17 @@ if should_check_update; then
     want_host=$(printf '%s' "$DOWNLOAD_BASE" | sed -E 's#^[a-z]+://([^/]+).*#\\1#')
     have_host=$(timeout "$VERSION_TIMEOUT" "$BIN" version 2>/dev/null | sed -n 's#^server: [a-z]*://\\([^/]*\\).*#\\1#p' | head -1)
     if [ -n "$have_host" ] && [ -n "$want_host" ] && [ "$have_host" != "$want_host" ]; then
+        echo "ai-scanner: 導入済みのバイナリは $have_host を見ていますが、この導入は $want_host から配信しています。アクセスキーは決して受け付けられず、検知ログは拒否されて捨てられます。一致するバイナリを取り直しています。" >&2
         echo "ai-scanner: the installed binary talks to $have_host, but this installation provisions from $want_host, so its access key can never be accepted (detection logs are refused and discarded). Re-downloading the matching binary." >&2
         download_binary "\${DOWNLOAD_BASE}/\${PLATFORM_SLUG}" "$BIN" || \\
+            echo "ai-scanner: 食い違ったバイナリを置き換えられませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。手元の検査は続きますが、検知ログは拒否され続けます。導入コマンドをもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
             echo "ai-scanner: could not replace the mismatched binary: \${UNVERIFIED_REASON:-the download failed}. Scanning continues locally, but detection logs will keep being refused. Re-run the installer, or contact your IT administrator with this message." >&2
     elif [ -z "$have_host" ]; then
+        echo "ai-scanner: 導入済みのバイナリがどのライセンスサーバーを見ているか読めなかったので、環境が一致するかは確認していません。検知ログが拒否されているようなら、導入コマンドをもう一度実行してください。" >&2
         echo "ai-scanner: could not read which license server the installed binary uses, so the environment match was NOT checked. If detection logs are being refused, re-run the installer." >&2
     fi
     timeout "$UPDATE_TIMEOUT" "$BIN" update 2>/dev/null || \\
+        echo "ai-scanner: スキャナーは今回、自分を更新できませんでした。すでに持っているルールで検査は続きます。これが繰り返されるなら、導入コマンドをもう一度実行してください。それでも直らなければ社内の IT 管理者にご連絡ください。" >&2
         echo "ai-scanner: the scanner could not update itself just now. It keeps scanning with the rules it already has; if this repeats, re-run the installer or contact your IT administrator." >&2
 
     # Keep the hook binary on the SAME build as the periodic one (issue #2366).
@@ -353,14 +398,98 @@ if should_check_update; then
         scanner_ver=$(timeout "$VERSION_TIMEOUT" "$BIN" version 2>/dev/null | awk 'NR==1{print $2}')
         harness_ver=$(timeout "$VERSION_TIMEOUT" "$HARNESS" version 2>/dev/null | awk 'NR==1{print $2}')
         if [ -n "$scanner_ver" ] && [ -n "$harness_ver" ] && [ "$scanner_ver" != "$harness_ver" ]; then
+            echo "ai-scanner: ツールコール検査機は $harness_ver、この端末は $scanner_ver です。同じビルドで揃うよう、いま取り直しています。" >&2
             echo "ai-scanner: the tool-call scanner is on $harness_ver while this endpoint is on $scanner_ver. Refreshing it so both run one build." >&2
             download_binary "\${DOWNLOAD_BASE}/ai-harness/\${PLATFORM_SLUG}" "$HARNESS" || \\
+                echo "ai-scanner: ツールコール検査機を取り直せませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。検査は $harness_ver のまま続きます。これが繰り返されるなら、導入コマンド (${installCommand}) をもう一度実行してください。" >&2
                 echo "ai-scanner: could not refresh the tool-call scanner: \${UNVERIFIED_REASON:-the download failed}. Scanning continues on $harness_ver; re-run the installer (${installCommand}) if this repeats." >&2
         fi
     fi
     date +%s > "$PULL_STAMP"
 fi
 
+# ── 既に撒かれたラッパーを現行の形へ収束させる (issue #2372、案 1) ────────────
+#
+# **バイナリは自動で届くが、設定は届かない。** アダプタは導入時に 1 度だけ
+# 書かれ、以後どの経路でも書き換わらない一方、自己更新はそれが名指すバイナリを
+# 黙って差し替える。その非対称が #2372 の本体で、ここはその片側を閉じる。
+#
+# **なぜ SessionStart なのか (同意の範囲)**: これは**利用者が自分でエディタを
+# 起動したときにだけ、その利用者として**走る。「そのエディタのフックを直す」と
+# いう範囲から出ない。常駐が利用者の home を書く案 (#2372 案 2) は
+# **同意の範囲の判断なので採らない** —— --agent が常駐を入れないという既存の
+# 判断の、ちょうど裏返しである。
+#
+# **★ この経路が届かない端末が在る (正直に置く)。** 収束させるコードはこの
+# スクリプトの中に在るので、**この版より前の start_scanner.sh を持つ端末には
+# 届かない。** そこは agent_hooks の hook_wiring (endpoint-info) が
+# **数として見えるようにする**部分が受け持つ —— だから #2372 の案 3 は
+# 「あとで」ではなく必須である。GAP-2372-PRE-REPAIR-ADAPTERS-UNREACHED。
+#
+# 4 つの門。**どれも「直せない」を「直した」と読ませないため**にある:
+#   1. hook のバイナリが在る (無ければ上の節が既に名指している)
+#   2. その版が setup を持つ (旧い版は持たない。持たないことは失敗ではない)
+#   3. アクセスキーが env に在る —— **無いまま書くと、鍵の無い settings.json を
+#      置くことになり、いま効いている保護を壊す**
+#   4. 兄弟のラッパーが実際に旧い形である (新しい形なら 1 バイトも書かない)
+CONFIG_ROOT="$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)"
+SELF_DIR="$(dirname "$0")"
+if [ -x "$HARNESS" ] && [ -n "$CONFIG_ROOT" ] && [ -n "\${AI_SCANNER_ACCESS_KEY:-}" ]; then
+    # 旧い形の判定は endpoint-info の hook_wiring と**同じ集合・同じ述語**である
+    # (agent_hooks.rs の HookWiring::from_wrapper_dir / from_wrapper_text)。
+    # 2 つ目の判定を作らない ——作ると、ポータルが数えている集合と、
+    # ここが直す集合がずれる。
+    #
+    # **【2026-09-10 訂正 —— issue #2407】かつてこの行は「同じ述語である」と
+    # 宣言しながら、実体は別のファイルを読んでいた。** 数える側は印
+    # (\`hook_marker\`) 1 本を読んでおり、claude-code のそれは
+    # **\`start_scanner.sh\` そのもの** = 分割後のビルドでは必ず \`ai-harness\` を
+    # 名指すスクリプトである。一方ここが直すのは**その兄弟**なので、
+    # **「新しい start_scanner.sh + 旧い兄弟」= まさに収束に失敗した端末が
+    # \`ai-harness\` (移行済み) として数から消えていた** (DDB 読み戻しで実測)。
+    # **数える側をこの集合へ合わせて直した** —— 直す側に \`start_scanner.sh\` を
+    # 足すのは、数える側の食い違いを 1 ミリも動かさない。
+    #
+    # **下の 4 行 (glob / 除外の case / 2 本の grep) は実体から抜き出されて
+    # 機械照合される** —— \`agent_hooks::tests::w1_the_repair_loop_and_this_module_read_one_set\`
+    # が綴りだけでなく**向き** (\`|| continue\` か \`|| stale=1\` か) まで見る。
+    # 書き換えるときは、あちらの \`WIRING_EXCLUDED_WRAPPERS\` /
+    # \`SCANNER_TOKENS\` / \`HARNESS_TOKENS\` も同じ PR で直すこと。
+    # なぜ grep -E なのか (issue #2372。実測で 1 度落ちている)。
+    # ここは長く BRE の grep -q 'ai-scanner\\|AI_SCANNER_BIN' と書かれていたが、
+    # **この本文は JS のテンプレートリテラルなので、書いたバックスラッシュ 1 つは
+    # 出力に残らない** —— 端末に置かれていたのは 'ai-scanner|AI_SCANNER_BIN' で、
+    # BRE の | はただの文字なので **この行は決して一致せず、収束は 1 度も
+    # 走らなかった** (2026-09-09 に linux-testbed で実測: 旧い形のラッパーを
+    # 置いて start_scanner.sh を回しても 1 バイトも書き換わらない)。
+    # **症状は出ない** —— 収束しないことと「収束すべきものが無い」ことが
+    # 端末側から区別できない。-E にすれば JS の逃がしが要らず (パターンに
+    # バックスラッシュが 1 つも無い)、BSD grep (macOS) が BRE の \\| を
+    # 解さない問題も同時に消える。**BRE へ戻さないこと。**
+    stale=0
+    for w in "$SELF_DIR"/*.sh; do
+        [ -r "$w" ] || continue
+        case "$w" in *"/start_scanner.sh"|*"/stop_scanner.sh") continue ;; esac
+        grep -Eq 'ai-scanner|AI_SCANNER_BIN' "$w" || continue
+        grep -Eq 'ai-harness|AI_HARNESS_BIN' "$w" || stale=1
+    done
+    if [ "$stale" = 1 ] && timeout "$VERSION_TIMEOUT" "$HARNESS" setup --help >/dev/null 2>&1; then
+        # --home を渡すので根の解決は起きない。--scope は settings.json に焼く
+        # 根の綴り ("$CLAUDE_PROJECT_DIR" か "$HOME") を決めるだけなので、
+        # **いまの設置場所から導く** —— 推測すると、リポジトリに置いた設定が
+        # 端末個別の設定として書き直される。
+        if [ "$CONFIG_ROOT" = "$HOME" ]; then repair_scope=user; else repair_scope=project; fi
+        echo "ai-scanner: この端末のフックアダプタは分割前の形で、ツールコール検査機ではなく定期実行のバイナリを呼んでいます。いま更新しています。お手元での操作は要りません。" >&2
+        echo "ai-scanner: this endpoint's hook adapters are the pre-split shape, so they still call the periodic binary instead of the tool-call scanner. Updating them now; no action is needed from you." >&2
+        timeout "$UPDATE_TIMEOUT" "$HARNESS" setup \\
+            --agent ${setupAgentName} --scope "$repair_scope" \\
+            --access-key "$AI_SCANNER_ACCESS_KEY" \\
+            --download-base "$DOWNLOAD_BASE" --home "$CONFIG_ROOT" >/dev/null 2>&1 || \\
+            echo "ai-scanner: この端末のフックアダプタは分割前の形のままで、今回は更新できませんでした。ツールコールは、すでに導入済みのバイナリが検査し続けます。このメッセージが繰り返されるなら、導入コマンド (${installCommand}) をもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
+            echo "ai-scanner: the hook adapters on this endpoint are still the pre-split shape and could not be updated just now. Tool calls keep being scanned by the binary already installed; if this message repeats, re-run the installer (${installCommand}) or contact your IT administrator with this message." >&2
+    fi
+fi
+
 exit 0
 `;
 }

package/src/toml-merge.mjs

@@ -1,14 +1,54 @@
 // Line-based TOML merger for Codex's ~/.codex/config.toml feature flag.
-// Codex requires `[features] codex_hooks = true` to activate hook dispatch.
+//
+// Codex requires `[features] hooks = true` to activate hook dispatch. The older
+// spelling `[features] codex_hooks = true` is a **deprecated alias**: Codex still
+// honours it, but prints
+//
+//   ⚠ `[features].codex_hooks` is deprecated. Use `[features].hooks` instead.
+//
+// on every start (issue #2367). So we write the canonical key and *migrate* any
+// legacy key we find, instead of leaving both around.
+//
 // Users may already have their own config (model settings, other features), so
 // we must merge rather than overwrite.
 //
-// Scope: *only* handles a single key inside a single section. No full TOML
-// parser, no external deps. Preserves comments, blank lines, ordering, and
+// Scope: *only* handles a single logical flag inside a single section. No full
+// TOML parser, no external deps. Preserves comments, blank lines, ordering, and
 // other sections exactly.
+//
+// ── Migration decision table (merge) ─────────────────────────────────
+// Only the *first* `[features]` section is considered (duplicate table headers
+// are invalid TOML anyway — see the known limitation at the bottom of this file).
+//
+//   old key | new key | result
+//   --------+---------+--------------------------------------------------------
+//   absent  | absent  | insert `hooks = true` right under the section header
+//   absent  | true    | no-op (byte-identical output)
+//   absent  | false   | value flipped to true, line position/comment preserved
+//   true    | absent  | line RENAMED in place -> `hooks = true`
+//                       (indentation, position and trailing comment preserved)
+//   false   | absent  | same rename, and the value is set to true
+//   any     | any     | the canonical `hooks` line wins and is set to true;
+//                       the deprecated `codex_hooks` line is REMOVED entirely.
+//                       This is the only case where a trailing comment can be
+//                       lost, because it is attached to the line we delete.
+//                       Conflicting values need no tie-break: setup means
+//                       "hooks on", so the result is always `hooks = true`.
+//
+// Standalone comment lines are never deleted, even when they sit directly above
+// a removed legacy key — deleting prose a user wrote is worse than leaving it.
+//
+// ── unmerge ──────────────────────────────────────────────────────────
+// Strips BOTH spellings, so a config written by an older aidr (legacy key) is
+// fully cleaned up by a newer aidr's uninstall. Everything else in `[features]`
+// (the user's own flags and comments) survives; the section header is dropped
+// only when nothing but blanks/comments would remain.
 
 const SECTION = "features";
-const KEY = "codex_hooks";
+// Canonical key. Codex >= the version that introduced `[features].hooks`.
+export const FEATURE_KEY = "hooks";
+// Deprecated alias still accepted by Codex, but it prints a warning (#2367).
+export const LEGACY_FEATURE_KEY = "codex_hooks";
 const VALUE = "true";
 
 // Match a section header line: optional leading whitespace, `[name]`, optional trailing comment.
@@ -20,10 +60,22 @@ function sectionHeader(name) {
 // Match any section header (used to find section boundaries).
 const ANY_SECTION_RE = /^\s*\[\s*[^\]]+\s*\](?:\s*#.*)?$/;
 
-// Match `key = value` with optional trailing comment; capture the value token.
+// Match `key = value` with optional trailing comment.
+// Groups: 1 = indent, 2 = key, 3 = ` = `, 4 = value token, 5 = trailing comment.
+// The `^\s*` anchor means the `hooks` matcher can never hit a `codex_hooks`
+// line (and vice versa) — the key must start the line after whitespace only.
 function keyAssignment(key) {
   const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(`^(\\s*${escaped}\\s*=\\s*)([^#\\n]*?)(\\s*(?:#.*)?)$`);
+  return new RegExp(`^(\\s*)(${escaped})(\\s*=\\s*)([^#\\n]*?)(\\s*(?:#.*)?)$`);
+}
+
+const CANONICAL_RE = keyAssignment(FEATURE_KEY);
+const LEGACY_RE = keyAssignment(LEGACY_FEATURE_KEY);
+
+// Rewrite a matched assignment line as `<indent>hooks<eq>true<trailing>`.
+function rewriteAsEnabled(line, re) {
+  const m = re.exec(line);
+  return `${m[1]}${FEATURE_KEY}${m[3]}${VALUE}${m[5]}`;
 }
 
 // Detect obvious malformed TOML so we fail closed instead of silently corrupting.
@@ -61,37 +113,64 @@ function findSectionRange(lines, section) {
   return { start, end };
 }
 
-// Merge `[features] codex_hooks = true` into the given TOML text, preserving
-// everything else. Idempotent: re-running on an already-merged file is a no-op.
+// Locate the first canonical / first legacy assignment inside a section range.
+function findKeys(lines, range) {
+  let canonical = -1;
+  let legacy = -1;
+  for (let i = range.start + 1; i < range.end; i++) {
+    if (canonical === -1 && CANONICAL_RE.test(lines[i])) canonical = i;
+    if (legacy === -1 && LEGACY_RE.test(lines[i])) legacy = i;
+  }
+  return { canonical, legacy };
+}
+
+// Merge `[features] hooks = true` into the given TOML text, migrating the
+// deprecated `codex_hooks` spelling and preserving everything else.
+// Idempotent: re-running on an already-merged file returns the input verbatim.
 export function mergeCodexHookFeature(text) {
   const input = text ?? "";
   if (input !== "") validate(input);
 
   // Empty file / whitespace-only: write a fresh minimal TOML.
   if (input.trim() === "") {
-    return `[${SECTION}]\n${KEY} = ${VALUE}\n`;
+    return `[${SECTION}]\n${FEATURE_KEY} = ${VALUE}\n`;
   }
 
   const lines = input.split("\n");
   // Preserve final newline state — JSON.stringify-style: if original ended with
   // "\n", .split gives a trailing "" element we'll keep and rejoin with.
   const range = findSectionRange(lines, SECTION);
-  const assignRe = keyAssignment(KEY);
 
   if (range) {
-    // Section exists — look for the key inside it.
-    for (let i = range.start + 1; i < range.end; i++) {
-      const m = assignRe.exec(lines[i]);
-      if (m) {
-        const currentValue = m[2].trim();
-        if (currentValue === VALUE) return input; // already correct, no-op
-        lines[i] = `${m[1]}${VALUE}${m[3]}`;      // overwrite `false` / other
-        return lines.join("\n");
-      }
+    const { canonical, legacy } = findKeys(lines, range);
+
+    if (canonical !== -1 && legacy !== -1) {
+      // Both spellings present. The canonical line wins (position + comment
+      // kept); the deprecated alias line goes away, which is what silences the
+      // warning. Conflicting values resolve to `true` because that is what this
+      // setup means.
+      lines[canonical] = rewriteAsEnabled(lines[canonical], CANONICAL_RE);
+      lines.splice(legacy, 1);
+      return lines.join("\n");
     }
+
+    if (legacy !== -1) {
+      // Legacy only — rename in place so ordering, indentation and any trailing
+      // comment survive. `codex_hooks = false` becomes `hooks = true`.
+      lines[legacy] = rewriteAsEnabled(lines[legacy], LEGACY_RE);
+      return lines.join("\n");
+    }
+
+    if (canonical !== -1) {
+      const m = CANONICAL_RE.exec(lines[canonical]);
+      if (m[4].trim() === VALUE) return input; // already correct, no-op
+      lines[canonical] = rewriteAsEnabled(lines[canonical], CANONICAL_RE);
+      return lines.join("\n");
+    }
+
     // Key absent — insert right after the section header (before any subkeys),
     // so the new line doesn't get buried under a long section.
-    lines.splice(range.start + 1, 0, `${KEY} = ${VALUE}`);
+    lines.splice(range.start + 1, 0, `${FEATURE_KEY} = ${VALUE}`);
     return lines.join("\n");
   }
 
@@ -100,12 +179,14 @@ export function mergeCodexHookFeature(text) {
   const needsLeadingBlank = input.length > 0 && !input.endsWith("\n\n");
   const prefix = input.endsWith("\n") ? "" : "\n";
   const spacer = needsLeadingBlank ? "\n" : "";
-  return `${input}${prefix}${spacer}[${SECTION}]\n${KEY} = ${VALUE}\n`;
+  return `${input}${prefix}${spacer}[${SECTION}]\n${FEATURE_KEY} = ${VALUE}\n`;
 }
 
-// Reverse of mergeCodexHookFeature: strip our `codex_hooks = true` line.
-// - Removes the key line.
-// - Removes an empty `[features]` section if our line was the only content.
+// Reverse of mergeCodexHookFeature: strip our feature flag line(s).
+// - Removes `hooks` AND the deprecated `codex_hooks` (a config written by an
+//   older aidr carries the legacy spelling; leaving it behind would keep the
+//   deprecation warning alive after uninstall).
+// - Removes an empty `[features]` section if our line(s) were the only content.
 // Returns { text, empty } — empty=true means the TOML is now effectively blank
 // so the caller can delete the file entirely.
 export function unmergeCodexHookFeature(text) {
@@ -120,17 +201,17 @@ export function unmergeCodexHookFeature(text) {
     return { text: input, empty: input.trim() === "" };
   }
 
-  const assignRe = keyAssignment(KEY);
-  let removedIdx = -1;
+  const removed = [];
   for (let i = range.start + 1; i < range.end; i++) {
-    if (assignRe.test(lines[i])) { removedIdx = i; break; }
+    if (CANONICAL_RE.test(lines[i]) || LEGACY_RE.test(lines[i])) removed.push(i);
   }
 
-  if (removedIdx === -1) {
+  if (removed.length === 0) {
     return { text: input, empty: input.trim() === "" };
   }
 
-  lines.splice(removedIdx, 1);
+  // Delete back-to-front so earlier indices stay valid.
+  for (let k = removed.length - 1; k >= 0; k--) lines.splice(removed[k], 1);
 
   // Re-evaluate the section bounds after removal.
   const newRange = findSectionRange(lines, SECTION);
@@ -165,3 +246,10 @@ export function unmergeCodexHookFeature(text) {
   const result = lines.join("\n");
   return { text: result, empty: result.trim() === "" };
 }
+
+// ── Known limitation (declared, not fixed) ───────────────────────────
+// Only the FIRST `[features]` table is inspected. A file with two `[features]`
+// headers is already invalid TOML (duplicate table), so Codex would reject it
+// before our flag mattered; handling it here would mean writing a real parser.
+// If such a file ever appears, a legacy key living in the second block would
+// survive the migration and the deprecation warning would persist.