@opengsd/gsd-core 1.12.0 → 1.14.0

package/bin/install.js

@@ -183,10 +183,11 @@ function isCodexHooksFeatureKey(key) {
   return CODEX_HOOKS_FEATURE_ALL_KEYS.includes(key);
 }
 
-// #768 \u2014 Claude Code permissions.allow / permissions.deny entries.
+// #768 \u2014 Claude Code permissions.allow entries.
 // Pre-populated during Claude installs to eliminate first-run approval friction
-// for gsd-core's own known-safe tool calls, and to add defense-in-depth deny
-// entries for common credential files.
+// for gsd-core's own known-safe tool calls. (The defense-in-depth deny entries
+// for credential files that #768 also wrote are retired \u2014 see
+// GSD_CLAUDE_LEGACY_DENY_PERMISSIONS below.)
 //
 // Format: each string uses Claude Code's documented permission rule syntax \u2014
 //   "Tool(pattern)"  e.g. "Bash(npx gsd-core *)", "Read(.planning/*)"
@@ -204,7 +205,20 @@ const GSD_CLAUDE_ALLOW_PERMISSIONS = Object.freeze([
   'Read(STATE.md)',
   'Edit(STATE.md)',
 ]);
-const GSD_CLAUDE_DENY_PERMISSIONS = Object.freeze([
+// #4221 \u2014 Retired deny rules. #768 wrote these three `Read()` deny rules
+// into settings.json; Claude Code 2.1.259 hardened the Bash-side enforcement
+// of Read() deny rules so that ANY such rule makes every
+// `cd DIR && grep/cat relative-path` compound prompt for approval, even in
+// `auto` permission mode \u2014 and GSD subagents emit hundreds of those per
+// session. The same protection now ships as the managed PreToolUse hook
+// hooks/gsd-secret-read-guard.js (a hook denial is not a permission rule and
+// never arms that check). Unlike the #2278 allow-side migration, there is no
+// surviving "current" deny list: the constant is RENAMED to its legacy role
+// and only ever filtered, never added. Byte-equal strings only \u2014 a user's
+// own hand-written identical rule is indistinguishable and is removed too
+// (the install manifest never recorded permission strings, so a
+// manifest-gated cleanup is not possible).
+const GSD_CLAUDE_LEGACY_DENY_PERMISSIONS = Object.freeze([
   'Read(.env)',
   'Read(.env.*)',
   'Read(.secrets)',
@@ -236,6 +250,13 @@ const GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS = Object.freeze([
  * so existing installs end up with the working `Edit(...)` forms instead of
  * both the dead legacy entry and its replacement sitting side by side.
  *
+ * Migration (#4221): the retired GSD_CLAUDE_LEGACY_DENY_PERMISSIONS entries
+ * are removed from permissions.deny (byte-equal only). Nothing is added to
+ * deny any more: an absent `deny` key is left absent (never created as an
+ * empty array), and a `deny` array emptied BY THIS FILTER is deleted so the
+ * retirement leaves no `"deny": []` residue; a user's pre-existing empty
+ * `deny: []` is untouched.
+ *
  * Defensive: if settings is not a plain object, returns immediately without
  * throwing. If permissions.allow / permissions.deny exist but are not arrays
  * (malformed settings), they are replaced with valid arrays.
@@ -252,7 +273,7 @@ function mergeClaudePermissions(settings) {
   if (!Array.isArray(settings.permissions.allow)) {
     settings.permissions.allow = [];
   }
-  if (!Array.isArray(settings.permissions.deny)) {
+  if (settings.permissions.deny !== undefined && !Array.isArray(settings.permissions.deny)) {
     settings.permissions.deny = [];
   }
 
@@ -265,9 +286,13 @@ function mergeClaudePermissions(settings) {
       settings.permissions.allow.push(entry);
     }
   }
-  for (const entry of GSD_CLAUDE_DENY_PERMISSIONS) {
-    if (!settings.permissions.deny.includes(entry)) {
-      settings.permissions.deny.push(entry);
+  if (Array.isArray(settings.permissions.deny)) {
+    const before = settings.permissions.deny.length;
+    settings.permissions.deny = settings.permissions.deny.filter(
+      (e) => !GSD_CLAUDE_LEGACY_DENY_PERMISSIONS.includes(e)
+    );
+    if (settings.permissions.deny.length === 0 && before > 0) {
+      delete settings.permissions.deny;
     }
   }
 }
@@ -411,7 +436,7 @@ const GSD_CHANGESET_FILES = [
   'github-release-notes.cjs', 'lint.cjs', 'new.cjs',
   'README.md', // documentation only — not user-authored
 ];
-const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs', 'drift-scan.cjs', 'alias-drift-families.cjs', 'exit-code-registry.cjs', 'ndjson-reporter.cjs', 'ci-job-timing.cjs'];
+const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs', 'drift-scan.cjs', 'alias-drift-families.cjs', 'exit-code-registry.cjs', 'ndjson-reporter.cjs', 'ci-job-timing.cjs', 'shellcheck-fetch.cjs', 'npm-version-check-diagnosis.cjs', 'platform-conformance-tier.generated.cjs', 'suite-detection.cjs', 'macos-conformance-tier.generated.cjs'];
 
 /**
  * Resolve a runtime's shared-hooks directory name from its descriptor.
@@ -519,6 +544,13 @@ const {
   RUNTIME_PROFILE_MAP: GSD_RUNTIME_PROFILE_MAP,
   isAnthropicFlavoredModel: gsdIsAnthropicFlavoredModel,
 } = require(path.join(_gsdLibDir, 'model-catalog.cjs'));
+// #4145: shared hash-first recovery for gsd-pristine/ baselines stored at an
+// unexpected path (e.g. without the gsd-core/ prefix an earlier release's
+// writer dropped). Same module the reapply verifier uses, so the two readers
+// cannot drift apart again.
+const {
+  findPristineByHash: gsdFindPristineByHash,
+} = require(path.join(_gsdLibDir, 'pristine-baseline.cjs'));
 // #2875 Part 2: MODEL_PROFILES + resolveTierEntry are now consumed only by
 // install-model-override-resolver.cjs's readGsdRuntimeProfileResolver
 // (required below) — this installer no longer needs its own bindings.
@@ -790,6 +822,10 @@ const {
 const {
   resolveRuntimeArtifactLayout,
 } = require(path.join(_gsdLibDir, 'runtime-artifact-layout.cjs'));
+const {
+  readSurface,
+  resolveSurface,
+} = require(path.join(_gsdLibDir, 'surface.cjs'));
 const {
   assertDestWithinConfigHome,
   createRuntimeArtifactInstallPlan,
@@ -1256,6 +1292,7 @@ const removeKimiHooksToml = hooksSurface.removeKimiHooksToml;
 // callers continue to work and there is a single implementation. (All call
 // sites are below this line, so the const binding has no TDZ hazard.)
 const processAttribution = runtimeArtifactConversion.processAttribution;
+const filterRuntimeNotesForTarget = runtimeArtifactConversion.filterRuntimeNotesForTarget;
 // computePathPrefix: implementation lives in runtimeArtifactConversion
 // (ADR-1508 / #1511 Phase 2 — single owner). Re-bound here so install.js call
 // sites continue to work. #2876 retired the sibling
@@ -1333,34 +1370,13 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
 }
 
 /**
- * Ensure hooks.json contains exactly one managed GSD hook entry for the given
- * Codex event, wired to gsd-context-monitor.js. Preserves user-owned entries.
- *
- * Used for the new Codex events added in #772:
- *   SubagentStart — inject context / GSD_AGENT_NAME awareness at subagent open
- *   Stop          — post-session context headroom tracking
- *   PostToolUse   — mirror the Claude Code PostToolUse context monitor
- *
- * All three events are routed through gsd-context-monitor.js — the same hook
- * used for PostToolUse in the Claude Code baseline — so context-headroom
- * warnings surface at these key Codex session lifecycle moments.
- *
- * On Windows (#3426): writes a gsd-context-monitor.cmd shim alongside the .js
- * file and uses the .cmd path as the hook command — exactly the same fix as
- * SessionStart uses for gsd-check-update — to avoid the bash.exe POSIX-exec
- * failure when Codex's hook dispatcher tries to run node.exe through Git Bash.
- *
- * @param {string} targetDir
- * @param {string} eventName - One of 'SubagentStart', 'Stop', 'PostToolUse'.
- * @param {{ absoluteRunner: string|null, platform?: NodeJS.Platform }} opts
- * @returns {{ changed: boolean, wrote: boolean, path: string }}
- */
-function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
-  return hooksSurface.ensureCodexHooksJsonEvent(targetDir, eventName, opts);
-}
-
-/**
- * Remove a GSD-managed event entry from hooks.json. Called during uninstall.
+ * Remove a GSD-managed event entry from hooks.json. Called during uninstall,
+ * and (#2586) unconditionally during install/reinstall to clean up a
+ * pre-#2586 install's stale gsd-context-monitor.js registrations — GSD no
+ * longer ADDS entries for these events (see CODEX_HOOKS_TO_COPY /
+ * cleanupOrphanedCodexContextMonitorScript in bin/install.js's Codex branch),
+ * only removes recognized ones, so the `ensureCodexHooksJsonEvent` wrapper
+ * that used to add them was removed as dead code.
  *
  * @param {string} targetDir
  * @param {string} eventName
@@ -1796,8 +1812,20 @@ const kiloAgentPermissionOrder = [
   'lsp',
 ];
 
+const kiloMcpPermissionPattern = /^mcp__([A-Za-z0-9_-]+)__((?:[A-Za-z0-9_-]+)|\*)$/;
+
+// Derives Kilo's native `{server}_{tool}` MCP permission key (kilo.ai/docs —
+// external, fixed format). Not injective: both capture groups allow `_`, so
+// e.g. `mcp__a_b__c` and `mcp__a__b_c` derive the same key. The `Set` below
+// resolves any such collision deterministically to first-seen-wins — see
+// src/runtime-artifact-conversion.cts's regression test. Mirrors that file's
+// convertClaudeToKiloPermissionTool exactly (#4032).
 function convertClaudeToKiloPermissionTool(claudeTool) {
-  return claudeToKiloAgentPermissions[claudeTool] || null;
+  const builtinPermission = claudeToKiloAgentPermissions[claudeTool];
+  if (builtinPermission) return builtinPermission;
+
+  const mcpPermission = kiloMcpPermissionPattern.exec(claudeTool);
+  return mcpPermission ? `${mcpPermission[1]}_${mcpPermission[2]}` : null;
 }
 
 function buildKiloAgentPermissionBlock(claudeTools) {
@@ -1814,6 +1842,10 @@ function buildKiloAgentPermissionBlock(claudeTools) {
   for (const permission of kiloAgentPermissionOrder) {
     lines.push(`  ${permission}: ${allowedPermissions.has(permission) ? 'allow' : 'deny'}`);
   }
+  for (const permission of allowedPermissions) {
+    if (kiloAgentPermissionOrder.includes(permission)) continue;
+    lines.push(`  ${permission}: allow`);
+  }
 
   return lines;
 }
@@ -2384,7 +2416,7 @@ function convertClaudeAgentToCopilotAgent(content, isGlobal = false) {
  * @param {boolean} [isGlobal=false] - Whether this is a global install
  */
 function convertClaudeToAntigravityContent(content, isGlobal = false) {
-  let c = content;
+  let c = filterRuntimeNotesForTarget(content, 'antigravity');
   if (isGlobal) {
     // #3738: global skills install under ~/.gemini/config/skills (the dir AGY
     // scans for global discovery), so skills-path references must divert there
@@ -2520,7 +2552,7 @@ function convertSlashCommandsToCursorSkillMentions(content) {
 }
 
 function convertClaudeToCursorMarkdown(content) {
-  let converted = convertSlashCommandsToCursorSkillMentions(content);
+  let converted = convertSlashCommandsToCursorSkillMentions(filterRuntimeNotesForTarget(content, 'cursor'));
   // Replace tool name references in body text
   converted = converted.replace(/\bBash\(/g, 'Shell(');
   converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
@@ -2641,7 +2673,7 @@ function convertSlashCommandsToTraeSkillMentions(content) {
 }
 
 function convertClaudeToTraeMarkdown(content) {
-  let converted = convertSlashCommandsToTraeSkillMentions(content);
+  let converted = convertSlashCommandsToTraeSkillMentions(filterRuntimeNotesForTarget(content, 'trae'));
   converted = converted.replace(/\bBash\(/g, 'Shell(');
   converted = converted.replace(/\bEdit\(/g, 'StrReplace(');
   // Replace general-purpose subagent type with Trae's equivalent "general_purpose_task"
@@ -2767,7 +2799,7 @@ function convertSlashCommandsToCodebuddySkillMentions(content) {
 }
 
 function convertClaudeToCodebuddyMarkdown(content) {
-  let converted = convertSlashCommandsToCodebuddySkillMentions(content);
+  let converted = convertSlashCommandsToCodebuddySkillMentions(filterRuntimeNotesForTarget(content, 'codebuddy'));
   // CodeBuddy uses the same tool names as Claude Code (Bash, Edit, Read, Write, etc.)
   // No tool name conversion needed
   converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
@@ -2859,7 +2891,7 @@ function convertClaudeAgentToCodebuddyAgent(content) {
 // ── Cline converters ────────────────────────────────────────────────────────
 
 function convertClaudeToCliineMarkdown(content) {
-  let converted = content;
+  let converted = filterRuntimeNotesForTarget(content, 'cline');
   // Cline uses the same tool names as Claude Code — no tool name conversion needed
   converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.clinerules`');
   converted = converted.replace(/\.\/CLAUDE\.md/g, '.clinerules');
@@ -3782,7 +3814,7 @@ function rewriteBareGsdToolsCommandsForCodex(content) {
 }
 
 function convertClaudeToCodexMarkdown(content) {
-  let converted = convertSlashCommandsToCodexSkillMentions(content);
+  let converted = convertSlashCommandsToCodexSkillMentions(filterRuntimeNotesForTarget(content, 'codex'));
   converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
   // Remove /clear references — Codex has no equivalent command
   // Handle backtick-wrapped: `\/clear` then: → (removed)
@@ -3849,26 +3881,37 @@ Execute mode fallback:
 ## C. Task() → spawn_agent Mapping
 GSD workflows use \`Task(...)\` (Claude Code syntax). Translate to Codex collaboration tools:
 
-**Schema detection (required first step):** Codex exposes two \`spawn_agent\` schemas:
-- **agent_type-capable schema** (e.g. \`multi_agent_v2\`): \`spawn_agent\` accepts \`agent_type\`, \`message\`, \`reasoning_effort\`, \`fork_context\`, etc. — typed GSD agent dispatch is available.
-- **Generic schema** (\`multi_agent_v1\`): \`spawn_agent\` accepts only \`message\`, \`items\`, \`fork_context\` — there is **no \`agent_type\` field**. Typed GSD agent dispatch is unavailable in this session.
+**Schema detection (required first step):** Before spawning, inspect the \`spawn_agent\`
+tool's visible parameter schema (via \`tool_search\` or the tool list). Use the presence
+of \`agent_type\` only to choose typed dispatch versus the generic-agent workaround.
+Detect optional fields independently: \`model\`, \`reasoning_effort\`, \`task_name\`,
+\`fork_turns\`, and \`fork_context\` may be added or removed without \`agent_type\` changing.
+Never infer one field from a schema/version label or from the presence of another field.
 
-Before spawning, inspect the \`spawn_agent\` tool's visible parameter schema (via \`tool_search\` or the tool list) to determine which form is active.
+- **agent_type-capable schema:** \`spawn_agent\` advertises \`agent_type\` — typed GSD agent dispatch is available.
+- **Generic schema:** \`spawn_agent\` does not advertise \`agent_type\` — typed GSD agent dispatch is unavailable in this session, even if other optional fields are present.
 
 Typed mapping (agent_type-capable schema only):
 - \`Task(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
 - \`Agent(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
-- \`Task(model="...")\` → omit. \`spawn_agent\` has no inline \`model\` parameter;
-  GSD embeds the resolved per-agent model directly into each agent's \`.toml\`
-  at install time so \`model_overrides\` from \`.planning/config.json\` and
-  \`~/.gsd/defaults.json\` are honored automatically by Codex's agent router.
-- Resolved \`reasoning_effort="low|medium|high|xhigh"\` (\`xhigh\` is a GSD/Codex tier, not a generic runtime enum) → pass \`reasoning_effort\`
-  to \`spawn_agent\` when the runtime/tool supports it. Omit missing, empty,
-  inherited, or unsupported values; do not invent one-off effort literals in
-  workflow prose.
+- \`Task(model="{resolved_model}")\` → pass \`model="{resolved_model}"\` when the
+  visible \`spawn_agent\` schema advertises \`model\` and the resolved value is explicit.
+  This is how \`model_profile\` tier routing, including \`adaptive\`, reaches the child agent.
+  Omit \`model\` only when the schema does not advertise \`model\`, or when the value is
+  missing, empty, or \`"inherit"\`; omission deliberately inherits the session/static agent
+  configuration. Explicit \`model_overrides\` may also be embedded in agent \`.toml\` files,
+  but ordinary profile-resolved models are not, so a TOML file is not a reason to discard
+  an available inline value.
+- Before each typed spawn, obtain the paired effort for its role with
+  \`gsd_run query resolve-model <subagent_type> --pick effort\` when the workflow has not
+  already exposed it. The resolver's unified \`effort\` field maps to the Codex spawn argument
+  \`reasoning_effort\`; do not look for a resolver field named \`reasoning_effort\`.
+  Pass it when the visible \`spawn_agent\` schema advertises \`reasoning_effort\`. Omit the
+  field when it is not advertised, or when the value is missing, empty, \`"inherit"\`, or
+  unsupported; do not invent one-off effort literals in workflow prose.
 - \`fork_context: false\` by default — GSD agents load their own context via \`<required_reading>\` blocks
-- \`task_name\` — required by the collaboration schema; provide a descriptive name for each spawned task
-- \`fork_turns\` — optional parameter controlling turn-forking depth; coexists with \`fork_context\` (not a replacement)
+- \`task_name\` — when advertised, provide a descriptive name for each spawned task
+- \`fork_turns\` — when advertised, controls turn-forking depth; coexists with \`fork_context\` (not a replacement)
 - \`Task(isolation="worktree")\` / \`Agent(isolation="worktree")\` → no direct \`spawn_agent\` mapping,
   but Codex declares \`dispatch.isolation: orchestrator-worktree\` (#2584). Codex
   \`spawn_agent\` still does not create or bind a git worktree; instead GSD itself
@@ -7152,7 +7195,7 @@ function neutralizeAgentReferences(content, instructionFile) {
 
 function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
   // Replace tool name references in content (applies to all files)
-  let convertedContent = content;
+  let convertedContent = filterRuntimeNotesForTarget(content, 'opencode');
   convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
   convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
   convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
@@ -7314,7 +7357,7 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
 // tests/runtime-converters.test.cjs (#2093).
 function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverride = null } = {}) {
   // Replace tool name references in content (applies to all files)
-  let convertedContent = content;
+  let convertedContent = filterRuntimeNotesForTarget(content, 'kilo');
   convertedContent = convertedContent.replace(/\bAskUserQuestion\b/g, 'question');
   convertedContent = convertedContent.replace(/\bSlashCommand\b/g, 'skill');
   convertedContent = convertedContent.replace(/\bTodoWrite\b/g, 'todowrite');
@@ -7372,7 +7415,8 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
 
     if (isAgent && inAgentTools) {
       if (trimmed.startsWith('- ')) {
-        agentTools.push(trimmed.substring(2).trim());
+        const tool = runtimeArtifactConversion._decodeToolScalar(trimmed.substring(2));
+        if (tool !== null) agentTools.push(tool);
         continue;
       }
       if (trimmed && !trimmed.startsWith('-')) {
@@ -7384,8 +7428,12 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
     if (trimmed.startsWith('tools:')) {
       if (isAgent) {
         const toolsValue = trimmed.substring(6).trim();
-        if (toolsValue) {
-          const tools = toolsValue.split(',').map(t => t.trim()).filter(t => t);
+        // A comment-only value (`tools: # note`) is not real inline content —
+        // fall through to the block-list scan instead of decoding the
+        // comment as a bogus tool name and dropping the list (mirrors
+        // src/runtime-artifact-conversion.cts's convertClaudeToKiloFrontmatter, #4032).
+        if (toolsValue && !toolsValue.startsWith('#')) {
+          const tools = runtimeArtifactConversion._splitToolScalars(toolsValue).map(runtimeArtifactConversion._decodeToolScalar).filter(tool => tool !== null);
           agentTools.push(...tools);
         } else {
           inAgentTools = true;
@@ -7451,7 +7499,8 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
       if (trimmed.startsWith('- ')) {
         const tool = trimmed.substring(2).trim();
         if (isAgent) {
-          agentTools.push(tool);
+          const decoded = runtimeArtifactConversion._decodeToolScalar(tool);
+          if (decoded !== null) agentTools.push(decoded);
         } else {
           allowedTools.push(tool);
         }
@@ -7862,6 +7911,8 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
         content = composeWorkflow(content, { sourcePath: srcPath });
       }
 
+      content = filterRuntimeNotesForTarget(content, runtime);
+
       if (!dispatch.mdSkipGenericRewrite) {
         const globalClaudeRegex = /~\/\.claude\//g;
         const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
@@ -8416,6 +8467,16 @@ function uninstall(isGlobal, runtime = DEFAULT_RUNTIME) {
         console.log(`  ${green}✓${reset} Removed managed Codex ${eventName} hook from hooks.json`);
       }
     }
+    // #2586: uninstall's own symmetric half of the orphaned-script cleanup —
+    // same GSD-owned + unreferenced gate as the install-time call.
+    const uninstallMonitorCleanup = hooksSurface.cleanupOrphanedCodexContextMonitorScript(targetDir);
+    for (const deletedPath of uninstallMonitorCleanup.deleted) {
+      removedCount++;
+      console.log(`  ${green}✓${reset} Removed orphaned Codex hook script (${path.basename(deletedPath)})`);
+    }
+    for (const warning of uninstallMonitorCleanup.warnings) {
+      console.warn(`  ${yellow}⚠${reset}  Could not remove orphaned Codex hook script ${warning.path}: ${warning.reason}`);
+    }
   }
 
   // 1a-kimi. Non-layout Kimi side-effect (#2095 EoS/kimi Upgrade 1): kimi's
@@ -9039,17 +9100,29 @@ function uninstall(isGlobal, runtime = DEFAULT_RUNTIME) {
         );
         if (settings.permissions.allow.length !== before) {
           permissionsModified = true;
+          // #4221: an array this filter emptied was GSD-only \u2014 remove the
+          // key rather than leave an empty array behind (Antigravity symmetry).
+          if (settings.permissions.allow.length === 0) {
+            delete settings.permissions.allow;
+          }
         }
       }
       if (Array.isArray(settings.permissions.deny)) {
         const before = settings.permissions.deny.length;
+        // #4221: the deny rules are retired, so this is a legacy-only filter.
         settings.permissions.deny = settings.permissions.deny.filter(
-          (e) => !GSD_CLAUDE_DENY_PERMISSIONS.includes(e)
+          (e) => !GSD_CLAUDE_LEGACY_DENY_PERMISSIONS.includes(e)
         );
         if (settings.permissions.deny.length !== before) {
           permissionsModified = true;
+          if (settings.permissions.deny.length === 0) {
+            delete settings.permissions.deny;
+          }
         }
       }
+      if (permissionsModified && Object.keys(settings.permissions).length === 0) {
+        delete settings.permissions;
+      }
       if (permissionsModified) {
         settingsModified = true;
         console.log(`  ${green}✓${reset} Removed GSD permissions from settings.json`);
@@ -10079,6 +10152,86 @@ function populatePristineDir({ packageSrc, pristineDir, modified, runtime, pathP
   return written;
 }
 
+/**
+ * #4145: recover a pristine baseline from a hash-matching orphan stored at an
+ * unexpected path under gsd-pristine/ (e.g. without the gsd-core/ prefix an
+ * earlier release's writer dropped).
+ *
+ * The preserve-check's strict join (pristineDir + manifest-keyed relPath)
+ * misses such snapshots, so they were pushed into regeneration from the
+ * incoming release — and when the file changed upstream, the candidate's hash
+ * could never satisfy the recorded outgoing hash, leaving the correct
+ * baseline permanently unconsumed and unpruned (the self-perpetuating state
+ * #4145 reports). Hash equality with pristine_hashes is the same authority
+ * the #3657 drift guard trusts, so an exact match cannot be the wrong
+ * baseline no matter where under gsd-pristine/ it lives.
+ *
+ * Recovery = relocation: copy the orphan to the canonical manifest-keyed path
+ * (hash-verified after the copy) and remove the orphan only once the
+ * canonical copy is verified in place. Returns true when the canonical path
+ * ended up holding recorded-hash bytes. Never deletes anything it cannot
+ * vouch for by hash, and never consumes a path that is the canonical path of
+ * ANY manifest file (see canonicalSkip below) — only genuine orphans, which
+ * no strict-join reader ever consults, are eligible for removal.
+ */
+function recoverOrphanedPristine(pristineDir, relPath, recordedHash, canonicalSkip) {
+  if (!recordedHash) return false;
+  let orphanRel;
+  try {
+    // canonicalSkip = the normalized manifest keys: a file already sitting at
+    // any canonical path can never be (re-)adopted through the scan. Without
+    // this, two modified files sharing byte-identical outgoing content would
+    // repeatedly "rescue" each other's canonical away (relocate + delete at
+    // its home path) in alternating updates — bytes identical, state unstable.
+    // It also keeps drift (#3657) / stale (#3407) territory with the caller.
+    orphanRel = gsdFindPristineByHash(pristineDir, recordedHash, canonicalSkip);
+  } catch {
+    return false;
+  }
+  if (!orphanRel) return false;
+  const outRef = resolveInstallRelativePath(pristineDir, relPath);
+  if (!outRef) return false;
+  try {
+    fs.mkdirSync(path.dirname(outRef.fullPath), { recursive: true });
+    fs.copyFileSync(path.join(pristineDir, orphanRel), outRef.fullPath);
+    // Verify the relocated copy before removing the orphan — only a
+    // hash-matching canonical counts as recovered.
+    if (fileHash(outRef.fullPath) !== recordedHash) {
+      try { fs.rmSync(outRef.fullPath, { force: true }); } catch { /* best-effort */ }
+      return false;
+    }
+    // Orphan removal is best-effort: the canonical copy is already verified,
+    // so a failed unlink leaves a harmless duplicate, never data loss.
+    try { fs.rmSync(path.join(pristineDir, orphanRel), { force: true }); } catch { /* best-effort */ }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * #4135: honest N-of-M accounting for gsd-pristine/ baselines after an
+ * update. The #3407 promotion rule keeps only hash-validated candidates
+ * (byte-identical across the version span), so a multi-version update
+ * legitimately ends with near-zero baselines — the collapse itself is NOT a
+ * bug to hide; hiding it is. This renders the covered-of-total line the
+ * update output prints either way, so "1 of 13" can never present like a
+ * fully-covered run. Pure function (typed return) so tests lock the exact
+ * contract without matching console prose.
+ */
+function describeBaselineCoverage(totalModified, covered) {
+  const total = Math.max(0, totalModified);
+  const have = Math.min(Math.max(0, covered), total);
+  const uncovered = total - have;
+  return {
+    complete: uncovered === 0,
+    uncovered,
+    text: uncovered === 0
+      ? `gsd-pristine/ baselines cover ${have} of ${total} modified file(s)`
+      : `gsd-pristine/ baselines cover ${have} of ${total} modified file(s) — ${uncovered} will be reported no_baseline by the reapply verifier`,
+  };
+}
+
 /**
  * Detect user-modified GSD files by comparing against install manifest.
  * Backs up modified files to gsd-local-patches/ for reapply after update.
@@ -10111,19 +10264,57 @@ function saveLocalPatches(configDir, pristineCtx) {
   const modified = [];
   const pristineHashes = {};
 
+  // #4086: skills/ manifest keys may live OUTSIDE configDir at the runtime's
+  // ACTUAL skills root — codex global installs to $HOME/.agents/skills (the
+  // ADR-1239 skills-kind `home` override), which writeManifest() already
+  // hashes from via _resolveSkillsRootDir (#2088/#3738). Resolving every key
+  // against configDir alone made every skills/ key miss here, so user
+  // modifications to Codex skills were never hash-compared, never backed up,
+  // and were silently overwritten by the next update. configDir stays FIRST
+  // (Postel: runtimes whose skills genuinely live under configDir resolve
+  // byte-identically to before); the skills root is a fallback, only for keys
+  // under the SAME descriptor-driven manifest prefix writeManifest uses, and
+  // only when that root resolves outside configDir. Containment + symlink
+  // guards apply to the alternate root too (resolveInstallRelativePath).
+  const patchRuntime = (pristineCtx && pristineCtx.runtime) || manifest.runtime || null;
+  const patchScope = manifest.scope === 'local' ? 'local' : 'global';
+  let skillsRedirect = null;
+  if (patchRuntime) {
+    const skillsRoot = _resolveSkillsRootDir(patchRuntime, configDir, patchScope);
+    const resolvedConfig = path.resolve(configDir);
+    if (
+      skillsRoot &&
+      skillsRoot !== resolvedConfig &&
+      !skillsRoot.startsWith(resolvedConfig + path.sep)
+    ) {
+      const prefix = _hostBehaviors(patchRuntime).skillsManifestPrefix || 'skills/';
+      skillsRedirect = { root: skillsRoot, prefix };
+    }
+  }
+
   for (const [relPath, originalHash] of Object.entries(manifest.files || {})) {
     const safeRef = resolveInstallRelativePath(configDir, relPath);
     if (!safeRef) continue;
     const { relPath: safeRelPath, fullPath } = safeRef;
-    if (!fs.existsSync(fullPath)) continue;
-    const currentHash = fileHash(fullPath);
+    let installedPath = fullPath;
+    if (!fs.existsSync(installedPath) && skillsRedirect && safeRelPath.startsWith(skillsRedirect.prefix)) {
+      const altRef = resolveInstallRelativePath(
+        skillsRedirect.root,
+        safeRelPath.slice(skillsRedirect.prefix.length)
+      );
+      if (altRef && fs.existsSync(altRef.fullPath)) {
+        installedPath = altRef.fullPath;
+      }
+    }
+    if (!fs.existsSync(installedPath)) continue;
+    const currentHash = fileHash(installedPath);
     if (currentHash !== originalHash) {
       // Back up the user's modified version
       const backupRef = resolveInstallRelativePath(patchesDir, safeRelPath);
       if (!backupRef) continue;
       const backupPath = backupRef.fullPath;
       fs.mkdirSync(path.dirname(backupPath), { recursive: true });
-      fs.copyFileSync(fullPath, backupPath);
+      fs.copyFileSync(installedPath, backupPath);
       modified.push(safeRelPath);
       pristineHashes[safeRelPath] = originalHash;
     }
@@ -10187,6 +10378,15 @@ function saveLocalPatches(configDir, pristineCtx) {
       const stalePaths = new Set();
       // Track which relPaths were successfully regenerated (from either missing or stale).
       const regeneratedPaths = new Set();
+      // #4145: track which relPaths were recovered by relocating a hash-matching
+      // orphan (stored at an unexpected path, e.g. without the gsd-core/ prefix).
+      const rescuedPaths = new Set();
+      // #4145: the set of paths that are SOME file's canonical pristine path
+      // (every normalized manifest key). The orphan scan must never consume
+      // these — see recoverOrphanedPristine.
+      const canonicalSkip = new Set(
+        Object.keys(manifest.files || {}).map((k) => normalizeInstallRelativePath(k)).filter(Boolean),
+      );
       const missingPaths = [];
       for (const relPath of modified) {
         const outRef = resolveInstallRelativePath(pristineDir, relPath);
@@ -10208,6 +10408,17 @@ function saveLocalPatches(configDir, pristineCtx) {
             stalePaths.add(relPath);
           }
         }
+        // #4145: canonical absent (or just removed as stale) — before falling
+        // into regeneration, try to recover the baseline from a hash-matching
+        // orphan elsewhere under gsd-pristine/ and relocate it to the canonical
+        // path. This is the self-heal for snapshots an earlier release stored
+        // without the gsd-core/ prefix: without it the state repeats forever
+        // (regeneration candidates from the incoming release can never satisfy
+        // the recorded outgoing hash when upstream changed the file).
+        if (recoverOrphanedPristine(pristineDir, relPath, pristineHashes[relPath], canonicalSkip)) {
+          rescuedPaths.add(relPath);
+          continue;
+        }
         // File absent from gsd-pristine/ (or just removed above as stale):
         // attempt hash-validated regeneration from new-release source.
         missingPaths.push(relPath);
@@ -10250,19 +10461,38 @@ function saveLocalPatches(configDir, pristineCtx) {
       }
       // `regenerated` = total files successfully regenerated (from missing OR stale).
       const regenerated = regeneratedPaths.size;
+      // `rescued` = files recovered by relocating a hash-matching orphan to its
+      // canonical path (#4145) — distinct from preservation (canonical already
+      // correct) and regeneration (bytes re-derived from new-release source).
+      const rescued = rescuedPaths.size;
       // `removed` = stale entries that were deleted and NOT subsequently regenerated.
       // Entries that were stale-deleted but then successfully regenerated are counted
-      // only in `regenerated` — the counts are non-overlapping.
-      const removed = [...stalePaths].filter(p => !regeneratedPaths.has(p)).length;
+      // only in `regenerated`; stale-deleted-then-orphan-rescued entries are counted
+      // only in `rescued` — the counts are non-overlapping.
+      const removed = [...stalePaths].filter(p => !regeneratedPaths.has(p) && !rescuedPaths.has(p)).length;
       if (preserved > 0) {
         console.log('  ' + green + '✓' + reset + '  Preserved ' + cyan + 'gsd-pristine/' + reset + ' (' + preserved + ' file(s)) for three-way merge');
       }
+      if (rescued > 0) {
+        console.log('  ' + green + '✓' + reset + '  Recovered ' + cyan + 'gsd-pristine/' + reset + ' (' + rescued + ' file(s)) by recorded hash from a legacy-path snapshot and relocated them (#4145)');
+      }
       if (regenerated > 0) {
         console.log('  ' + green + '✓' + reset + '  Regenerated ' + cyan + 'gsd-pristine/' + reset + ' (' + regenerated + ' file(s)) via hash-validated new-release source');
       }
       if (removed > 0) {
         console.log('  ' + yellow + 'i' + reset + '  Removed ' + removed + ' stale gsd-pristine/ snapshot(s); regenerated ' + regenerated + ' of those — falls back to over-broad verify heuristic for the rest');
       }
+      // #4135: the honest N-of-M coverage line. Preserved/rescued/regenerated
+      // are disjoint buckets (see their accounting comments above), so their
+      // sum is exactly the files that ended this update with a hash-valid
+      // baseline. A partial result renders as an info line, not an error:
+      // the collapse is legitimate (#3407), hiding it was the bug.
+      const coverage = describeBaselineCoverage(modified.length, preserved + rescued + regenerated);
+      if (coverage.complete) {
+        console.log('  ' + green + '✓' + reset + '  ' + coverage.text);
+      } else {
+        console.log('  ' + yellow + 'i' + reset + '  ' + coverage.text);
+      }
     }
   }
   return modified;
@@ -10512,7 +10742,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // one) is honored on every profile, `full` included (#2322 blocker 2).
   const _commandsDir = path.join(src, 'commands', 'gsd');
   const _skillsManifest = _isCoreProfileAlias ? new Map() : loadSkillsManifest(_commandsDir);
-  const _resolvedProfile = resolveProfile({
+  let _resolvedProfile = resolveProfile({
     modes: [_activeProfileName],
     manifest: _skillsManifest,
     registry: _installedCapabilityRegistry,
@@ -10863,6 +11093,28 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     return Array.isArray(scopeLayout) && scopeLayout.length > 0;
   })();
 
+  // Install the distribution-owned gsd-core tree before layout materialization.
+  // installRuntimeArtifacts then provisions the durable Runtime Surface corpus
+  // exactly once into this final tree instead of having that corpus overwritten
+  // by a later whole-tree copy and needing a second provisioning pass.
+  const skillSrc = path.join(src, 'gsd-core');
+  const skillDest = path.join(targetDir, 'gsd-core');
+  const _gsdArtifactsStagingRoot = _tryResolveUserArtifactStagingRoot(targetDir);
+  if (_gsdArtifactsStagingRoot === null) {
+    console.warn(`  ${yellow}!${reset} Skipping gsd-core/${USER_OWNED_ARTIFACTS.join(', gsd-core/')} preservation (staging unavailable) — it will be lost if present.`);
+    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
+  } else {
+    const stagedGsdArtifacts = stageUserArtifacts(skillDest, USER_OWNED_ARTIFACTS, _gsdArtifactsStagingRoot);
+    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
+    restoreStagedUserArtifacts(skillDest, stagedGsdArtifacts);
+    discardStagedUserArtifacts(stagedGsdArtifacts);
+  }
+  if (verifyInstalled(skillDest, 'gsd-core')) {
+    console.log(`  ${green}✓${reset} Installed workflow assets`);
+  } else {
+    failures.push('gsd-core');
+  }
+
   // #2624: write the .gsd-source marker. Extracted from its former late position so it can be
   // called BEFORE staging reads the marker (see the call site below). Scoped to the Claude-global
   // layout (issue #1477) — the only install path that ships the skills layout without a
@@ -10879,6 +11131,9 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           // ADR-1239 Phase B write-confinement: the descriptor-sourced marker filename
           // must resolve under targetDir (parity with the other descriptor-driven writes).
           const _markerPath = assertDestWithinConfigHome(targetDir, _hostBehaviors(runtime).sourceMarkerFile);
+          if (hasExistingSymlinkBetween(path.resolve(targetDir), _markerPath, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+            throw new Error(`compatibility marker "${_markerPath}" contains an untrusted symlink`);
+          }
           fs.writeFileSync(_markerPath, gsdSourceCommands + '\n', 'utf8');
         } catch (err) {
           // Non-fatal: install proceeds. But on the Claude-global layout walk-up
@@ -10905,6 +11160,19 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   if (_isSkillsRuntime) {
     // Layout-driven install for skills-based runtimes (full and minimal modes)
     const scope = _installScopeId;
+    // Preserve an existing Runtime Surface selection during upgrades. The
+    // installer refreshes the source corpus first, then emits exactly the
+    // already-committed selection instead of widening it to the base profile.
+    const _committedSurface = readSurface(targetDir);
+    if (_committedSurface) {
+      _resolvedProfile = resolveSurface(
+        targetDir,
+        loadSkillsManifest(_commandsDir),
+        undefined,
+        _installedCapabilityRegistry,
+        _committedSurface,
+      );
+    }
     // ADR-1239 upgrade 3 / #2088: a kind may declare an alternate install `home`
     // (e.g. Codex skills -> $HOME/.agents/skills) instead of the runtime's normal
     // configDir. Resolve the ACTUAL on-disk skills root here, descriptor-driven
@@ -11197,36 +11465,6 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     _installNativePluginIfDeclared(runtime, targetDir, _hostBehaviors(runtime), src);
   }
 
-  // Copy gsd-core skill with path replacement
-  // Stage user-generated files DURABLY to disk before the wipe-and-copy so
-  // they survive re-install even if the process dies mid-copy (#2875 /
-  // #1874-F19) — copyWithPathReplacement wipes and recursively re-copies the
-  // entire gsd-core/ tree, the single longest operation in the install, on
-  // the path every user takes (40-design.md "Site 4 is far worse...").
-  const skillSrc = path.join(src, 'gsd-core');
-  const skillDest = path.join(targetDir, 'gsd-core');
-  // #2875 defect fix: this IS the mainline install step (installing
-  // gsd-core/ itself) — unlike the optional legacy-cleanup blocks above,
-  // install must still be able to proceed and actually write gsd-core/ even
-  // when the staging root cannot be resolved. Degrade by skipping ONLY the
-  // USER_OWNED_ARTIFACTS preserve/restore wrapper around the copy (warn),
-  // never the copy itself.
-  const _gsdArtifactsStagingRoot = _tryResolveUserArtifactStagingRoot(targetDir);
-  if (_gsdArtifactsStagingRoot === null) {
-    console.warn(`  ${yellow}!${reset} Skipping gsd-core/${USER_OWNED_ARTIFACTS.join(', gsd-core/')} preservation (staging unavailable) — it will be lost if present.`);
-    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
-  } else {
-    const stagedGsdArtifacts = stageUserArtifacts(skillDest, USER_OWNED_ARTIFACTS, _gsdArtifactsStagingRoot);
-    copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
-    restoreStagedUserArtifacts(skillDest, stagedGsdArtifacts);
-    discardStagedUserArtifacts(stagedGsdArtifacts);
-  }
-  if (verifyInstalled(skillDest, 'gsd-core')) {
-    console.log(`  ${green}✓${reset} Installed workflow assets`);
-  } else {
-    failures.push('gsd-core');
-  }
-
   // #2624: the .gsd-source marker is now written by _writeGsdSourceMarker()
   // BEFORE staging reads it (see the early call above the _isSkillsRuntime
   // block). The former write lived here — AFTER staging — which on an upgrade
@@ -11314,7 +11552,8 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   } else if (_isSkillsRuntime) {
     console.log(`  ${dim}↳${reset} Agents installed via descriptor-driven layout (${runtime})`);
   } else {
-    const _standaloneAgentsResult = installAgentsKindStandalone(runtime, targetDir, _installScopeId, _resolvedProfile, pathPrefix, getCommitAttribution, _installedCapabilityRegistry);
+    const _standaloneProjectDir = isGlobal ? process.cwd() : targetDir;
+    const _standaloneAgentsResult = installAgentsKindStandalone(runtime, targetDir, _installScopeId, _resolvedProfile, pathPrefix, getCommitAttribution, _installedCapabilityRegistry, _standaloneProjectDir);
     if (_standaloneAgentsResult) {
       // #2875 defect fix: installAgentsKindStandalone now returns `null`
       // (rather than a truthy result pointing at an empty destDir) whenever a
@@ -12064,13 +12303,29 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     //   require()s managed-hooks-registry.cjs for MANAGED_HOOKS — so all four must be
     //   installed/refreshed together for every profile, or Codex is wired to a dependency
     //   chain the same installer never delivers.
-    // We deliberately do *not* copy gsd-graphify-update.sh or hooks/lib/ for Codex
-    // in this change (graphify auto-update support for Codex is out of scope for #3579).
+    // We deliberately do *not* copy gsd-graphify-update.sh for Codex in this
+    // change (graphify auto-update support for Codex is out of scope for #3579).
+    // hooks/lib/ WAS excluded here for the same reason, and that stopped being
+    // correct when #3911 (2ea5efc15) gave gsd-context-monitor.js a real
+    // `require('./lib/hook-exit.js')`: the allowlist below is flat and never
+    // recursed, so the hook shipped without its helper and died with
+    // MODULE_NOT_FOUND at load, before its own try/catch, on every registered
+    // event (#4087, #4098). The libs are now derived from what the staged
+    // scripts actually require rather than hand-listed — see the
+    // stageTransitiveHookLibs call after the copy loop. The #3579 boundary is
+    // preserved: helpers no staged Codex hook requires (graphify tooling among
+    // them) are still not shipped.
+    // #2586: gsd-context-monitor.js is deliberately NOT copied for Codex.
+    // It reads the statusline bridge file (${TMPDIR}/claude-ctx-{session_id}.json)
+    // written only by hooks/gsd-statusline.js, which Codex never installs — so
+    // every registered event was a guaranteed silent no-op (readSentinel throws
+    // ENOENT -> allow(undefined), every invocation, every event, no exceptions).
+    // A pre-#2586 install's stale copy + hooks.json registrations are cleaned
+    // up below (see the CODEX_EXTENDED_HOOK_EVENTS loop), not re-added here.
     const CODEX_HOOKS_TO_COPY = [
       'gsd-check-update.js',
       'gsd-check-update-worker.js',
       'managed-hooks-registry.cjs',
-      'gsd-context-monitor.js',
     ];
     const codexHooksSrc = path.join(src, 'hooks', 'dist');
     if (fs.existsSync(codexHooksSrc)) {
@@ -12081,6 +12336,12 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       // is not the same as an allowlisted file landing in it — see the marker
       // gate below.
       let codexStagedHooks = false;
+      // The entries THIS invocation actually staged. Seeding the lib scan from
+      // `existsSync` over the destination instead would also pick up a file
+      // left by a PREVIOUS install whose source is no longer staged — e.g. a
+      // name dropped from the allowlist — and derive helpers for a hook that is
+      // no longer shipped (review of #4087).
+      const codexStagedEntries = [];
       for (const entry of fs.readdirSync(codexHooksSrc)) {
         if (!CODEX_HOOKS_TO_COPY.includes(entry)) continue;
         const srcFile = path.join(codexHooksSrc, entry);
@@ -12115,8 +12376,43 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
         }
         codexStagedHooks = true;
+        codexStagedEntries.push(entry);
+      }
+      // Stage the hooks/lib/ helpers the staged scripts require, transitively
+      // (#4087, #4098). Shares writeCursorHooksJson's walker rather than a
+      // second copy: both reduced bundles hand-pick SCRIPTS, and the identical
+      // MODULE_NOT_FOUND was already fixed once for Cursor in 704859e9c. A flat
+      // list of today's three helpers would re-break the next time a
+      // Codex-bundled hook grows a lib dependency, which is exactly how this
+      // regressed. Gated on codexStagedHooks for the same reason the CommonJS
+      // marker below is: hooks/ is shared space, and staging nothing must not
+      // leave a GSD-owned lib/ behind in a directory GSD created but did not
+      // fill (#2544). Seeded from the copies staged by THIS invocation, so the
+      // scan sees the same bytes Node will load and never derives helpers for a
+      // hook left behind by an earlier install.
+      let codexStagedLibs = [];
+      if (codexStagedHooks) {
+        codexStagedLibs = hooksSurface.stageTransitiveHookLibs({
+          seedSources: codexStagedEntries
+            .map((entry) => fs.readFileSync(path.join(codexHooksDest, entry), 'utf8')),
+          srcLibDir: path.join(codexHooksSrc, 'lib'),
+          destLibDir: path.join(codexHooksDest, 'lib'),
+          runtimeLabel: 'Codex',
+          // Same substitutions the .js branch above applies to hook scripts, so
+          // a helper that ever gains a runtime path or version token is
+          // rewritten identically instead of shipping a Claude-shaped path.
+          // No-ops on today's helpers, which carry neither.
+          transform: (content) => content
+            .replace(/'\.claude'/g, configDirReplacement)
+            .replace(/\/\.claude\//g, `/${getDirName(runtime)}/`)
+            .replace(/\.claude\//g, `${getDirName(runtime)}/`)
+            .replace(/\{\{GSD_VERSION\}\}/g, pkg.version),
+        });
       }
       console.log(`  ${green}✓${reset} Installed hooks (Codex)`);
+      if (codexStagedLibs.length > 0) {
+        console.log(`  ${green}✓${reset} Installed hooks/lib/ helpers (${codexStagedLibs.join(', ')})`);
+      }
       // #2717: write the CommonJS marker into hooks/ alongside the staged .js
       // scripts. Codex is excluded from installSharedHooksBundle by the
       // !isCodex gate, so it never received the marker the shared-bundle path
@@ -12231,35 +12527,48 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           }
         }
 
-        // ── Codex extended hook events (#772, #2088) ─────────────────────────
-        // Codex CLI stabilised a full hook-event set in rust-v0.137.0. GSD
-        // registers CODEX_EXTENDED_HOOK_EVENTS (#2088 adds the 6 documented
-        // events beyond the original #772 three) — all routed through
-        // gsd-context-monitor.js so context-headroom warnings surface at each
-        // lifecycle point: SubagentStart/SubagentStop (subagent open/close),
-        // Stop (final-response), PreToolUse/PostToolUse (tool boundaries),
-        // PermissionRequest (approval prompts), Pre/PostCompact (context
-        // compaction), and UserPromptSubmit (per-turn context injection). The
-        // context-monitor script decides per-payload what to do; unregistered
-        // events simply never fire.
-        //
-        // Guard: only register when the context-monitor file exists and the node
-        // runner is available — same guards as the SessionStart path above.
-        const contextMonitorFile = path.join(targetDir, 'hooks', 'gsd-context-monitor.js');
-        if (codexNodeRunner && fs.existsSync(contextMonitorFile)) {
-          for (const codexEvent of CODEX_EXTENDED_HOOK_EVENTS) {
-            const eventWrite = ensureCodexHooksJsonEvent(targetDir, codexEvent, {
-              absoluteRunner: codexNodeRunner,
-              platform: process.platform,
-            });
-            if (eventWrite.wrote) {
-              console.log(`  ${green}✓${reset} Configured Codex hooks (${codexEvent} via hooks.json)`);
-            } else if (eventWrite.changed) {
-              console.log(`  ${green}✓${reset} Verified Codex hooks (${codexEvent} via hooks.json)`);
-            }
+        // #2586: Codex's hook payload carries no context/token-usage field
+        // (confirmed against codex-rs/hooks/src/schema.rs), so agent-facing
+        // context warnings and GSD phase/lifecycle display cannot be
+        // supported on this runtime — state that plainly during install
+        // rather than silently omitting the capability. Matches
+        // capabilities/codex/capability.json's hostBehaviors.unsupportedFeatures.
+        console.log(`  ${dim}↳${reset} Codex: agent-facing context warnings and GSD phase/lifecycle display are unsupported (Codex's hook payload has no context-usage metric)`);
+
+        // ── Codex extended hook events (#772, #2088) — REMOVED by #2586 ──────
+        // gsd-context-monitor.js is no longer copied or registered for Codex
+        // (see the CODEX_HOOKS_TO_COPY comment above): every one of these
+        // events was a guaranteed silent no-op, since the metrics bridge file
+        // it reads is only ever written by Claude's own statusline hook.
+        // Every event in CODEX_EXTENDED_HOOK_EVENTS is unconditionally
+        // reconciled here — not gated on the script existing — so a
+        // pre-#2586 install's stale registrations (exact current shape, or a
+        // recognized legacy shape via isManagedHookCommand's
+        // includeLegacyAliases) are stripped on reinstall. Mirrors the
+        // unconditional uninstall-time loop over the same constant. A
+        // registration whose command does not match the managed shape (a
+        // hand-customized entry) survives untouched — see
+        // reconcileCodexHooksJsonEvent's isManagedHookCommand filter.
+        for (const codexEvent of CODEX_EXTENDED_HOOK_EVENTS) {
+          const eventCleanup = removeCodexHooksJsonEvent(targetDir, codexEvent);
+          if (eventCleanup.changed) {
+            console.log(`  ${green}✓${reset} Removed stale Codex ${codexEvent} context-monitor hook from hooks.json`);
           }
-        } else if (!codexNodeRunner) {
-          console.warn(`  ${yellow}⚠${reset}  Skipped Codex extended hook-event registration — Node runner unavailable.`);
+        }
+        // Delete the orphaned script (+ Windows .cmd shim) left by a
+        // pre-#2586 install, but ONLY once no surviving hooks.json
+        // registration under any event still references it, and only when
+        // the on-disk file is GSD's own (see design doc's Ownership check —
+        // a content-signature check, not manifest membership, so this works
+        // on the very first reinstall after upgrading, with no bootstrap
+        // gap). A deletion failure never reverts the (already safe,
+        // already-written) hooks.json cleanup above — must-have #8.
+        const monitorCleanup = hooksSurface.cleanupOrphanedCodexContextMonitorScript(targetDir);
+        for (const deletedPath of monitorCleanup.deleted) {
+          console.log(`  ${green}✓${reset} Removed orphaned Codex hook script (${path.basename(deletedPath)})`);
+        }
+        for (const warning of monitorCleanup.warnings) {
+          console.warn(`  ${yellow}⚠${reset}  Could not remove orphaned Codex hook script ${warning.path}: ${warning.reason}`);
         }
         // ── end Codex extended hook events ────────────────────────────────────
       }
@@ -13881,7 +14190,7 @@ module.exports = {
     mergeClaudePermissions,
     GSD_CLAUDE_ALLOW_PERMISSIONS,
     GSD_CLAUDE_LEGACY_ALLOW_PERMISSIONS,
-    GSD_CLAUDE_DENY_PERMISSIONS,
+    GSD_CLAUDE_LEGACY_DENY_PERMISSIONS,
     GSD_CODEX_MARKER,
     // #3897 rung 3 (ADR-3473 §8.3, HALT.md option 2)
     CODEX_SANDBOX_HOLDS,
@@ -13945,6 +14254,7 @@ module.exports = {
     reportLocalPatches,
     validateHookFields,
     populatePristineDir,
+    describeBaselineCoverage,
     _resolveUserArtifactStagingRoot,
     _tryResolveUserArtifactStagingRoot,
     finishInstall,