@pareto4/pp-core 1.5.0

package/hooks/pp-context-monitor.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// pp-hook-version: {{PP_VERSION}}
+// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+// Windows/Git Bash, or slow Claude Code piping during large outputs),
+// exit silently instead of hanging until Claude Code kills the process
+// and reports "hook error". See #775, #1162.
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Reject session IDs that contain path traversal sequences or path separators.
+    // session_id is used to construct file paths in /tmp — an unsanitized value
+    // could escape the temp directory and read or write arbitrary files.
+    if (/[/\\]|\.\./.test(sessionId)) {
+      process.exit(0);
+    }
+
+    // Check if context warnings are disabled via config.
+    // Collapsed existsSync+readFileSync into a single read guarded by try/catch
+    // (ENOENT or parse error → use defaults, same as old "planningDir absent" branch).
+    const cwd = data.cwd || process.cwd();
+    try {
+      const configPath = path.join(cwd, '.planning', 'config.json');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.hooks?.context_warnings === false) {
+        process.exit(0);
+      }
+    } catch (e) {
+      // Missing or unparseable config → proceed with defaults (context warnings enabled)
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently.
+    // Collapsed existsSync+readFileSync: ENOENT → exit 0 (identical to old !existsSync branch),
+    // other errors rethrow to the outer catch (swallowed → exit 0, as before).
+    let metricsRaw;
+    try {
+      metricsRaw = fs.readFileSync(metricsPath, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') process.exit(0);
+      throw e;
+    }
+    const metrics = JSON.parse(metricsRaw);
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    // Collapsed existsSync+readFileSync: ENOENT or parse error → keep default warnData
+    // (same as old "file absent" branch). firstWarn tracks whether we read a valid sentinel.
+    try {
+      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      firstWarn = false;
+    } catch (e) {
+      // Missing or corrupted sentinel → firstWarn stays true, warnData stays at defaults
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if GSD is active (has .planning/STATE.md in working directory)
+    const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // On CRITICAL with active GSD project, auto-record session state as a
+    // breadcrumb for /gsd:resume-work (#1974). Fire-and-forget subprocess —
+    // doesn't block the hook or the agent. Fires ONCE per CRITICAL session,
+    // guarded by warnData.criticalRecorded to prevent repeated overwrites
+    // of the "crash moment" record on every debounce cycle.
+    if (isCritical && isGsdActive && !warnData.criticalRecorded) {
+      try {
+        // Runtime-agnostic path: this hook lives at <runtime-config>/hooks/
+        // and gsd-tools.cjs lives at <runtime-config>/gsd-core/bin/.
+        // Using __dirname makes this work on Claude Code, OpenCode, Gemini,
+        // Kilo, etc. without hardcoding ~/.claude/.
+        const gsdTools = path.join(__dirname, '..', 'pp-core', 'bin', 'pp-tools.cjs');
+        // Coerce usedPct to a safe number in case bridge file is malformed
+        const safeUsedPct = Number(usedPct) || 0;
+        const stoppedAt = `context exhaustion at ${safeUsedPct}% (${new Date().toISOString().split('T')[0]})`;
+        spawn(
+          process.execPath,
+          [gsdTools, 'state', 'record-session', '--stopped-at', stoppedAt],
+          { cwd, detached: true, stdio: 'ignore', windowsHide: true }
+        ).unref();
+        warnData.criticalRecorded = true;
+        // Persist the sentinel so subsequent debounce cycles don't re-fire
+        fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      } catch { /* non-critical — don't let state recording break the hook */ }
+    }
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
+          'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/gsd:pause-work at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
+          'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
+    } else {
+      message = isGsdActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. If not between ' +
+          'defined plan steps, inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
+          'starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: (data.hook_event_name && data.hook_event_name.trim())
+          || (process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse"),
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/hooks/pp-cursor-post-tool.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// pp-hook-version: {{PP_VERSION}}
+// gsd-cursor-post-tool.js — Cursor postToolUse hook (issue #777)
+//
+// Cursor invokes this script after each tool call completes.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor postToolUse):
+//   { tool_name, tool_input, tool_output, duration,
+//     conversation_id, generation_id, model, hook_event_name,
+//     cursor_version, workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor postToolUse):
+//   { additional_context?: string }   ← injected as context after the tool use
+//
+// Behaviour:
+//   - After a write-class tool that targets .planning/, reminds the agent
+//     to keep STATE.md current.
+//   - Fails open: any error silently exits 0.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
+const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
+const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    let input;
+    try { input = JSON.parse(raw || '{}'); } catch { process.stdout.write(JSON.stringify({})); return; }
+
+    const toolName = String(
+      input.tool_name || input.toolName || ''
+    ).toLowerCase();
+
+    const isWrite = WRITE_TOOL_RE.test(toolName);
+    if (!isWrite) { process.stdout.write(JSON.stringify({})); return; }
+
+    // Collect only PATH-bearing field values (not free-form content).
+    const paths = [];
+    const walk = (v, depth) => {
+      if (depth > 5 || paths.length > 64) return;
+      if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+      if (v && typeof v === 'object') {
+        for (const k of Object.keys(v)) {
+          const val = v[k];
+          if (typeof val === 'string' && PATH_KEY_RE.test(k)) paths.push(val);
+          else walk(val, depth + 1);
+        }
+      }
+    };
+    walk(input.tool_input || input.toolInput || {}, 0);
+
+    if (paths.some((p) => PLANNING_PATH_RE.test(p))) {
+      process.stdout.write(JSON.stringify({
+        additional_context:
+          'GSD: .planning/ artifact updated — ensure STATE.md reflects the latest phase and progress.',
+      }));
+      return;
+    }
+  } catch { /* fall through to empty response */ }
+
+  process.stdout.write(JSON.stringify({}));
+});

package/hooks/pp-cursor-session-start.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// pp-hook-version: {{PP_VERSION}}
+// gsd-cursor-session-start.js — Cursor sessionStart hook (issue #777)
+//
+// Cursor invokes this script at the start of each agent session.
+// Protocol: JSON from Cursor on stdin; JSON response on stdout.
+//
+// Input schema (cursor sessionStart):
+//   { session_id, is_background_agent, composer_mode, conversation_id,
+//     generation_id, model, hook_event_name, cursor_version,
+//     workspace_roots, user_email, transcript_path }
+//
+// Output schema (cursor sessionStart):
+//   { additional_context?: string }   ← injected into the session as context
+//
+// Behaviour:
+//   - If .planning/STATE.md is present, injects a brief state reminder.
+//   - If absent, nudges the user toward /gsd:new-project.
+//   - Fails open: any error silently exits 0 so a hook bug never wedges Cursor.
+//
+// Cursor docs: https://cursor.com/docs/hooks
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MSG_PRESENT =
+  'GSD: .planning/STATE.md is present — review the current phase and any blockers before acting.';
+const MSG_ABSENT =
+  'GSD: no .planning/ workflow found — run /gsd:new-project to start a tracked workflow.';
+
+let raw = '';
+const stdinTimeout = setTimeout(() => {
+  // Timeout guard: exit silently rather than hanging.
+  process.exit(0);
+}, 10000);
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const statePath = path.join(process.cwd(), '.planning', 'STATE.md');
+    const statePresent = fs.existsSync(statePath);
+    const msg = statePresent ? MSG_PRESENT : MSG_ABSENT;
+    process.stdout.write(JSON.stringify({ additional_context: msg }));
+  } catch {
+    // Fail open — never block a Cursor session because of a GSD hook error.
+    process.stdout.write(JSON.stringify({}));
+  }
+});

package/hooks/pp-ensure-canonical-path.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// pp-hook-version: {{PP_VERSION}}
+//
+// gsd-ensure-canonical-path — SessionStart hook (#997)
+//
+// PROBLEM: GSD agents/commands/templates use markdown `@`-file-includes that
+// hardcode the canonical path `@~/.claude/gsd-core/...` (references, workflows,
+// templates, contexts, bin). Markdown @-includes expand `~` but do NOT expand
+// environment variables, so `${CLAUDE_PLUGIN_ROOT}` cannot be used in them.
+// In a classic `bin/install.js` install the canonical path is a real directory
+// holding the bundled tree, so the includes resolve. In a Claude Code
+// *marketplace plugin* install the plugin manager only unpacks the package
+// into the version-pinned plugin cache and never runs `bin/install.js`, so
+// `~/.claude/gsd-core/` is never created and every @-include resolves to
+// nothing — every agent that depends on one fails (e.g. the executor).
+//
+// FIX: On SessionStart, when running under a plugin install (CLAUDE_PLUGIN_ROOT
+// set and a bundled `gsd-core/` tree found beneath it), ensure
+// `~/.claude/gsd-core/` exists and its immutable subdirs (bin, contexts,
+// references, templates, workflows) are symlinked to the plugin's bundled tree.
+// This changes ZERO @-references, is a no-op in classic installs (where each
+// subdir is already a real directory), preserves user-generated files
+// (USER-PROFILE.md, STATE.md, VERSION, …), prunes stale links so it self-heals
+// after `claude plugin update` rotates the version dir, and uses Windows
+// junctions for symlinks on win32.
+//
+// SECURITY: the resolved bundled-tree path and every per-subdir link target are
+// kept strictly inside the resolved plugin root (realpath-normalised, prefix-
+// checked). A real (non-symlink) file or directory already sitting at a managed
+// link target is NEVER clobbered.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Immutable, bundled subdirectories that the canonical path must expose. These
+// are the directories `@~/.claude/gsd-core/<subdir>/...` includes point into.
+// User-generated artifacts (USER-PROFILE.md, STATE.md, VERSION, config, …) are
+// NOT in this list and are never created, moved, or deleted by this hook.
+const MANAGED_SUBDIRS = ['bin', 'contexts', 'references', 'templates', 'workflows'];
+
+/**
+ * Resolve the canonical runtime config dir for the active runtime.
+ *
+ * Honours CLAUDE_CONFIG_DIR for custom/multi-account setups (mirrors
+ * gsd-check-update.js detectConfigDir), else falls back to ~/.claude. The
+ * canonical GSD tree always lives at `<configDir>/gsd-core`.
+ */
+function resolveConfigDir(homeDir, env) {
+  const envDir = env.CLAUDE_CONFIG_DIR;
+  if (envDir && typeof envDir === 'string' && envDir.trim().length > 0) {
+    return envDir;
+  }
+  return path.join(homeDir, '.claude');
+}
+
+/**
+ * Locate the bundled `gsd-core/` tree beneath a plugin root.
+ *
+ * Claude Code unpacks the package so the bundled tree sits at
+ * `<pluginRoot>/gsd-core/`. Returns the absolute, realpath-normalised path to
+ * that directory, or null if it is absent / not a directory. Resolving with
+ * realpath collapses symlinks/.. so the subsequent containment check is sound.
+ */
+function resolveBundledTree(pluginRoot) {
+  if (!pluginRoot || typeof pluginRoot !== 'string' || pluginRoot.trim().length === 0) {
+    return null;
+  }
+  let root;
+  try {
+    root = fs.realpathSync(pluginRoot);
+  } catch (_) {
+    return null; // plugin root does not exist
+  }
+  const bundled = path.join(root, 'pp-core');
+  let bundledReal;
+  try {
+    // The bundled tree must be a real directory (or a symlink to one) that
+    // resolves to a path inside the plugin root. realpathSync throws ENOENT/
+    // ENOTDIR if <pluginRoot>/gsd-core is absent, so no separate existence
+    // check is needed. Reject anything that does not resolve to a directory.
+    bundledReal = fs.realpathSync(bundled);
+    if (!fs.statSync(bundledReal).isDirectory()) return null;
+  } catch (_) {
+    return null;
+  }
+  // SECURITY: the resolved bundled tree must stay inside the resolved plugin
+  // root. A crafted symlink at <pluginRoot>/gsd-core pointing outside the root
+  // is rejected — we never link the canonical path at content we do not own.
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (bundledReal !== root && !bundledReal.startsWith(rootWithSep)) {
+    return null;
+  }
+  return bundledReal;
+}
+
+/**
+ * The fs.symlinkSync `type` to use for a directory link on a given platform.
+ *
+ * On Windows, unprivileged users cannot create symlinks but CAN create
+ * junctions; 'junction' requires an absolute target (we always pass one). On
+ * POSIX a 'dir' symlink is used. Exported so the win32 branch is unit-testable
+ * without a Windows host.
+ */
+function dirLinkType(platform) {
+  return platform === 'win32' ? 'junction' : 'dir';
+}
+
+/**
+ * Create a directory symlink (junction on win32) from linkPath -> target.
+ * Throws on real failure so the caller records it.
+ */
+function createDirLink(target, linkPath, platform) {
+  fs.symlinkSync(target, linkPath, dirLinkType(platform));
+}
+
+/**
+ * Does `linkPath` already correctly point at `expectedTarget`?
+ * Used to make the hook idempotent — a correct link is left untouched.
+ */
+function linkPointsAt(linkPath, expectedTarget) {
+  try {
+    if (!fs.lstatSync(linkPath).isSymbolicLink()) return false;
+    const resolved = fs.realpathSync(linkPath);
+    return resolved === fs.realpathSync(expectedTarget);
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Ensure the canonical `~/.claude/gsd-core/` path exposes the bundled subdirs.
+ *
+ * Pure, dependency-injected core so tests drive it with a fake home, fake
+ * plugin root, and explicit platform. Returns a structured result describing
+ * exactly what happened (never throws for ordinary conditions — only truly
+ * unexpected I/O errors propagate, and the thin CLI wrapper swallows those so
+ * a hook failure never blocks a session).
+ *
+ * @param {object} opts
+ * @param {string} [opts.homeDir]    home directory (default os.homedir())
+ * @param {string} [opts.pluginRoot] CLAUDE_PLUGIN_ROOT (default from env)
+ * @param {string} [opts.platform]   process.platform override (tests)
+ * @param {object} [opts.env]        environment (default process.env)
+ * @returns {{status:string, canonicalDir?:string, bundledTree?:string,
+ *            linked?:string[], prunedStale?:string[], preserved?:string[],
+ *            skipped?:string[], reason?:string}}
+ */
+function ensureCanonicalPath(opts = {}) {
+  const env = opts.env || process.env;
+  const homeDir = opts.homeDir || os.homedir();
+  const platform = opts.platform || process.platform;
+  const pluginRoot = opts.pluginRoot !== undefined ? opts.pluginRoot : env.CLAUDE_PLUGIN_ROOT;
+
+  // Uniform result contract: every return carries the four action arrays so
+  // callers can read result.linked/etc without first switching on status.
+  const empty = { linked: [], prunedStale: [], preserved: [], skipped: [] };
+
+  // No plugin context → classic/npm install or non-plugin runtime. No-op.
+  const bundledTree = resolveBundledTree(pluginRoot);
+  if (!bundledTree) {
+    return { status: 'noop', reason: 'no-plugin-bundle', ...empty };
+  }
+
+  const configDir = resolveConfigDir(homeDir, env);
+  const canonicalDir = path.join(configDir, 'pp-core');
+
+  // Inspect the canonical path itself exactly once.
+  //  - If it is a SYMLINK, the user (or another tool) deliberately pointed the
+  //    canonical path elsewhere. We must NOT write managed links *through* that
+  //    symlink into a directory we do not own — bail as a no-op.
+  //  - If it is a REAL directory with at least one REAL (non-link) managed
+  //    subdir, this is a classic `bin/install.js` install — leave it alone.
+  let canonicalStat = null;
+  try { canonicalStat = fs.lstatSync(canonicalDir); } catch (_) { canonicalStat = null; }
+
+  if (canonicalStat && canonicalStat.isSymbolicLink()) {
+    return { status: 'noop', reason: 'canonical-is-symlink', canonicalDir, bundledTree, ...empty };
+  }
+
+  if (canonicalStat && canonicalStat.isDirectory()) {
+    for (const sub of MANAGED_SUBDIRS) {
+      try {
+        const subSt = fs.lstatSync(path.join(canonicalDir, sub));
+        if (subSt.isDirectory() && !subSt.isSymbolicLink()) {
+          return { status: 'noop', reason: 'classic-install', canonicalDir, bundledTree, ...empty };
+        }
+      } catch (_) { /* subdir absent — keep checking */ }
+    }
+  }
+
+  // Ensure the canonical directory exists (as a real directory). We never
+  // replace an existing real directory; recursive mkdir is a no-op if present.
+  try {
+    fs.mkdirSync(canonicalDir, { recursive: true });
+  } catch (e) {
+    return { status: 'error', reason: `mkdir-canonical: ${e.code || e.message}`, canonicalDir, bundledTree, ...empty };
+  }
+
+  const linked = [];
+  const prunedStale = [];
+  const preserved = [];
+  const skipped = [];
+
+  // SECURITY: prefix used to confirm every per-subdir link target resolves
+  // strictly inside the bundled tree. Defence-in-depth against a tampered
+  // bundle that ships an internally-escaping symlink at <bundledTree>/<sub>.
+  const bundledWithSep = bundledTree.endsWith(path.sep) ? bundledTree : bundledTree + path.sep;
+
+  for (const sub of MANAGED_SUBDIRS) {
+    const target = path.join(bundledTree, sub);
+    // Only expose subdirs the bundle actually ships, AND only when the target
+    // resolves to a real directory that stays inside the bundled tree. A
+    // subdir whose realpath escapes the bundle (e.g. a planted symlink) is
+    // skipped — we never point the canonical path at content outside the
+    // validated plugin bundle.
+    let targetIsDir = false;
+    try {
+      const targetReal = fs.realpathSync(target);
+      // A NAMED subdir must resolve strictly BELOW the bundled tree root. We do
+      // NOT accept targetReal === bundledTree here: a subdir that self-links to
+      // the tree root would otherwise be exposed at the wrong level (e.g.
+      // `workflows` -> the whole tree), making `@.../workflows/foo` resolve to
+      // `<tree>/foo` instead of `<tree>/workflows/foo`.
+      targetIsDir = fs.statSync(targetReal).isDirectory()
+        && targetReal.startsWith(bundledWithSep);
+    } catch (_) { targetIsDir = false; }
+    if (!targetIsDir) {
+      skipped.push(sub);
+      continue;
+    }
+
+    const linkPath = path.join(canonicalDir, sub);
+
+    // Already a correct link → idempotent no-op.
+    if (linkPointsAt(linkPath, target)) {
+      linked.push(sub);
+      continue;
+    }
+
+    let existing = null;
+    try { existing = fs.lstatSync(linkPath); } catch (_) { existing = null; }
+
+    if (existing) {
+      // lstat().isSymbolicLink() is true for BOTH POSIX symlinks and Windows
+      // junctions, so this single predicate identifies every GSD-managed link.
+      if (existing.isSymbolicLink()) {
+        // A GSD-managed link that is stale or points elsewhere (e.g. previous
+        // plugin version after `claude plugin update`). Prune and recreate.
+        try {
+          fs.unlinkSync(linkPath);
+          prunedStale.push(sub);
+        } catch (e) {
+          skipped.push(sub);
+          continue;
+        }
+      } else {
+        // A REAL file or directory the user (or a classic install) owns. NEVER
+        // clobber it — preserve it untouched. This is the USER-PROFILE.md /
+        // partially-real-canonical-dir safety case.
+        preserved.push(sub);
+        continue;
+      }
+    }
+
+    try {
+      createDirLink(target, linkPath, platform);
+      linked.push(sub);
+    } catch (e) {
+      skipped.push(sub);
+    }
+  }
+
+  return {
+    status: 'ensured',
+    canonicalDir,
+    bundledTree,
+    linked,
+    prunedStale,
+    preserved,
+    skipped,
+  };
+}
+
+module.exports = {
+  ensureCanonicalPath,
+  resolveBundledTree,
+  resolveConfigDir,
+  dirLinkType,
+  MANAGED_SUBDIRS,
+};
+
+// CLI entry: run on SessionStart. Never block the session — any unexpected
+// failure is swallowed (best-effort self-heal). Emit nothing on stdout to keep
+// the hook silent in normal operation.
+if (require.main === module) {
+  try {
+    ensureCanonicalPath();
+  } catch (_) {
+    // Best-effort: a canonical-path failure must never abort a session.
+  }
+  process.exit(0);
+}