@opengsd/gsd-core 1.5.0-rc.2 → 1.5.0-rc.4

package/hooks/dist/gsd-ensure-canonical-path.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_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, 'gsd-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, 'gsd-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);
+}

package/hooks/dist/gsd-statusline.js

@@ -312,7 +312,7 @@ function runStatusline() {
     const totalCtx = data.context_window?.total_tokens || 1_000_000;
     const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
     const AUTO_COMPACT_BUFFER_PCT = acw > 0
-      ? Math.min(100, (acw / totalCtx) * 100)
+      ? Math.min(100, Math.max(0, (1 - acw / totalCtx) * 100))
       : 16.5;
     let ctx = '';
     if (remaining != null) {

package/hooks/dist/managed-hooks-registry.cjs

@@ -22,6 +22,7 @@ const MANAGED_HOOKS = [
   'gsd-context-monitor.js',
   'gsd-cursor-post-tool.js',
   'gsd-cursor-session-start.js',
+  'gsd-ensure-canonical-path.js',
   'gsd-graphify-update.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',

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

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_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, 'gsd-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, 'gsd-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);
+}

package/hooks/gsd-statusline.js

@@ -312,7 +312,7 @@ function runStatusline() {
     const totalCtx = data.context_window?.total_tokens || 1_000_000;
     const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
     const AUTO_COMPACT_BUFFER_PCT = acw > 0
-      ? Math.min(100, (acw / totalCtx) * 100)
+      ? Math.min(100, Math.max(0, (1 - acw / totalCtx) * 100))
       : 16.5;
     let ctx = '';
     if (remaining != null) {

package/hooks/hooks.json

@@ -3,6 +3,7 @@
     "SessionStart": [
       {
         "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-ensure-canonical-path.js\"", "timeout": 5 },
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-check-update.js\"" }
         ]
       }

package/hooks/managed-hooks-registry.cjs

@@ -22,6 +22,7 @@ const MANAGED_HOOKS = [
   'gsd-context-monitor.js',
   'gsd-cursor-post-tool.js',
   'gsd-cursor-session-start.js',
+  'gsd-ensure-canonical-path.js',
   'gsd-graphify-update.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',