@graphit/cli 0.2.379 → 0.2.384

package/scripts/plugin-status/claude-install.mjs

@@ -0,0 +1,215 @@
+// Feature #1042: the Claude Code installed-plugin inspection and `--repair`, split
+// out of plugin-status.mjs unchanged. The entry script passes its plugin root and
+// REPAIRABLE_BUNDLE_ENTRIES in (the list stays in the entry file, where a test reads it).
+
+import { chmodSync, cpSync, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  CLAUDE_MARKETPLACE_NAME,
+  CLAUDE_PLUGIN_NAME,
+  PLUGIN_ID,
+  atomicWriteJson,
+  isStrictSemver,
+  isWithinDirectory,
+  readFrontmatterVersion,
+  sanitizePathPart,
+  tryReadJson,
+  versionIsBehind,
+} from "./common.mjs";
+
+export function claudePluginsRoot() {
+  return process.env.CLAUDE_PLUGINS_ROOT ?? join(homedir(), ".claude", "plugins");
+}
+
+function claudeInstalledPluginsPath(root = claudePluginsRoot()) {
+  return join(root, "installed_plugins.json");
+}
+
+function claudeVersionedCachePath(version, root = claudePluginsRoot()) {
+  return join(
+    root,
+    "cache",
+    CLAUDE_MARKETPLACE_NAME,
+    CLAUDE_PLUGIN_NAME,
+    sanitizePathPart(version),
+  );
+}
+
+function readClaudeInstalledFile(root = claudePluginsRoot()) {
+  const path = claudeInstalledPluginsPath(root);
+  const data = tryReadJson(path);
+  if (!data || typeof data !== "object") return null;
+  return { path, data };
+}
+
+function graphitInstallEntries(installedData) {
+  const plugins = installedData.plugins && typeof installedData.plugins === "object"
+    ? installedData.plugins
+    : installedData;
+  const raw = plugins?.[PLUGIN_ID];
+  if (!raw) return [];
+  if (Array.isArray(raw)) {
+    return raw
+      .filter((entry) => entry && typeof entry === "object")
+      .map((entry) => ({ entry }));
+  }
+  if (typeof raw === "object") {
+    return [{ entry: raw }];
+  }
+  return [];
+}
+
+function pluginEntryVersion(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  const installPath = typeof entry.installPath === "string" ? entry.installPath : null;
+  const skillVersion = installPath
+    ? readFrontmatterVersion(join(installPath, "skills", "graphit", "SKILL.md"))
+    : null;
+  const versionJson = installPath
+    ? tryReadJson(join(installPath, "skills", "graphit", "VERSION.json"))?.version
+    : null;
+  return {
+    installPath,
+    entryVersion: typeof entry.version === "string" ? entry.version : null,
+    skillVersion,
+    versionJson: versionJson ?? null,
+    effectiveVersion: skillVersion ?? versionJson ?? (typeof entry.version === "string" ? entry.version : null),
+  };
+}
+
+function repairSourceLooksCurrent(sourceRoot, currentVersion) {
+  if (!isStrictSemver(currentVersion)) return false;
+  const skillVersion = readFrontmatterVersion(join(sourceRoot, "skills", "graphit", "SKILL.md"));
+  const versionJson = tryReadJson(join(sourceRoot, "skills", "graphit", "VERSION.json"))?.version;
+  const claudePlugin = tryReadJson(join(sourceRoot, ".claude-plugin", "plugin.json"))?.version;
+  return skillVersion === currentVersion && versionJson === currentVersion && claudePlugin === currentVersion;
+}
+
+function copyRepairableBundle(sourceRoot, targetRoot, repairableEntries) {
+  if (!isWithinDirectory(targetRoot, claudePluginsRoot())) {
+    throw new Error(`Refusing to repair outside Claude plugins directory: ${targetRoot}`);
+  }
+
+  const tmpRoot = `${targetRoot}.tmp-${process.pid}-${Date.now()}`;
+  rmSync(tmpRoot, { recursive: true, force: true });
+  mkdirSync(tmpRoot, { recursive: true });
+  try {
+    for (const entry of repairableEntries) {
+      const source = join(sourceRoot, entry);
+      if (!existsSync(source)) continue;
+      cpSync(source, join(tmpRoot, entry), {
+        recursive: true,
+        force: true,
+        verbatimSymlinks: true,
+      });
+    }
+    try {
+      chmodSync(join(tmpRoot, "bin", "graphit"), 0o755);
+    } catch {
+      // Windows or missing wrapper; integrity checks catch real packaging drift.
+    }
+    mkdirSync(dirname(targetRoot), { recursive: true });
+    rmSync(targetRoot, { recursive: true, force: true });
+    renameSync(tmpRoot, targetRoot);
+  } catch (error) {
+    rmSync(tmpRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function updateClaudeInstalledEntriesOnDisk(installedFile, staleRecords, targetPath, currentVersion) {
+  const now = new Date().toISOString();
+  for (const record of staleRecords) {
+    record.entry.installPath = targetPath;
+    record.entry.version = currentVersion;
+    record.entry.lastUpdated = now;
+    if (typeof record.entry.installedAt !== "string") {
+      record.entry.installedAt = now;
+    }
+  }
+  atomicWriteJson(installedFile.path, installedFile.data);
+}
+
+export function inspectClaudeInstalledPlugin(currentVersion, repair, { pluginRoot, repairableEntries }) {
+  const installedFile = readClaudeInstalledFile();
+  if (!installedFile) return { findings: [], metadata: [] };
+
+  const metadata = [];
+  const entries = graphitInstallEntries(installedFile.data);
+  if (entries.length === 0) return { findings: [], metadata };
+
+  const staleRecords = [];
+  for (const record of entries) {
+    const versionInfo = pluginEntryVersion(record.entry);
+    metadata.push({
+      label: `Claude Code installed ${PLUGIN_ID}`,
+      version: versionInfo.effectiveVersion,
+      installPath: versionInfo.installPath,
+      entryVersion: versionInfo.entryVersion,
+      skillVersion: versionInfo.skillVersion,
+      scope: record.entry.scope ?? "user",
+      projectPath: record.entry.projectPath ?? null,
+    });
+
+    if (
+      versionIsBehind(versionInfo.effectiveVersion, currentVersion) ||
+      versionIsBehind(versionInfo.entryVersion, currentVersion)
+    ) {
+      staleRecords.push({ ...record, versionInfo });
+    }
+  }
+
+  if (staleRecords.length === 0) return { findings: [], metadata };
+
+  const staleVersions = [...new Set(staleRecords.map((record) => record.versionInfo.effectiveVersion ?? "unknown"))].join(", ");
+  const targetPath = claudeVersionedCachePath(currentVersion);
+
+  if (!repair) {
+    return {
+      metadata,
+      findings: [
+        {
+          type: "claude-installed-plugin-stale",
+          message: `Claude Code installed Graphit plugin is stale (${staleVersions}), expected ${currentVersion}`,
+          remediation: "Run `graphit plugin status --repair`, then restart/reload Claude Code. If you prefer the native plugin manager, run `/plugin marketplace update graphit-plugin`, then `/plugin update graphit@graphit-plugin`, then restart/reload.",
+        },
+      ],
+    };
+  }
+
+  try {
+    if (!repairSourceLooksCurrent(pluginRoot, currentVersion)) {
+      throw new Error(`current npm/plugin bundle at ${pluginRoot} is missing synced ${currentVersion} plugin files`);
+    }
+    const targetSkillVersion = readFrontmatterVersion(join(targetPath, "skills", "graphit", "SKILL.md"));
+    if (targetSkillVersion !== currentVersion) {
+      copyRepairableBundle(pluginRoot, targetPath, repairableEntries);
+    }
+    updateClaudeInstalledEntriesOnDisk(installedFile, staleRecords, targetPath, currentVersion);
+    return {
+      metadata,
+      findings: [
+        {
+          type: "claude-installed-plugin-repaired",
+          message: `Claude Code installed Graphit plugin was stale (${staleVersions}); repaired disk cache to ${currentVersion}`,
+          remediation: `Restart/reload Claude Code so it loads the repaired plugin cache at ${targetPath}. The already-running session may still have the old SKILL.md in memory until then.`,
+          repaired: true,
+          installPath: targetPath,
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      metadata,
+      findings: [
+        {
+          type: "claude-installed-plugin-stale",
+          message: `Claude Code installed Graphit plugin is stale (${staleVersions}), expected ${currentVersion}; auto-repair failed: ${error instanceof Error ? error.message : String(error)}`,
+          remediation: "Run `/plugin marketplace update graphit-plugin`, then `/plugin update graphit@graphit-plugin`, then restart/reload Claude Code. `graphit plugin status --repair` can repair from the npm bundle once the local files are writable.",
+        },
+      ],
+    };
+  }
+}

package/scripts/plugin-status/cloud-refresh.mjs

@@ -0,0 +1,97 @@
+// Feature #1042: on a cloud session's fresh start, update the installed plugin to the
+// latest release before the session uses it. Cloud environments reuse a setup-script
+// snapshot for about a week, and the agent itself may not run `claude plugin update`
+// (auto mode denies it) or `/reload-plugins` (user-only); a hook is configured code, and
+// a cloud VM is thrown away after the run, so an update there touches nothing that lasts.
+// Laptops never reach this module: their sessions keep today's "update available" notice.
+
+import { execFile } from "node:child_process";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { compareVersions, isStrictSemver, tryParseJson, tryReadJson } from "./common.mjs";
+
+const DEFAULT_BUDGET_MS = 90_000;
+
+export function cloudRefreshApplies({ hookEvent, source, env }) {
+  return (
+    hookEvent === "SessionStart" &&
+    source === "startup" &&
+    env.CLAUDE_CODE_REMOTE === "true" &&
+    env.GRAPHIT_PLUGIN_SELF_UPDATE !== "0"
+  );
+}
+
+// Claude Code installs a marketplace plugin at <plugins>/cache/<marketplace>/<plugin>/<version>
+// and keeps the marketplace clone at <plugins>/marketplaces/<marketplace>. Anything else
+// (a --plugin-dir checkout, the npm package) is not ours to update.
+function pluginCacheLayout(pluginRoot) {
+  const pluginDir = dirname(resolve(pluginRoot));
+  const marketplaceDir = dirname(pluginDir);
+  const cacheDir = dirname(marketplaceDir);
+  if (basename(cacheDir) !== "cache") return null;
+  return { pluginsRoot: dirname(cacheDir), marketplace: basename(marketplaceDir), plugin: basename(pluginDir) };
+}
+
+function marketplaceVersion({ pluginsRoot, marketplace, plugin }) {
+  const clone = join(pluginsRoot, "marketplaces", marketplace, ".claude-plugin");
+  const plugins = tryReadJson(join(clone, "marketplace.json"))?.plugins;
+  const listed = Array.isArray(plugins) ? plugins.find((entry) => entry?.name === plugin) : null;
+  return listed?.version ?? tryReadJson(join(clone, "plugin.json"))?.version ?? null;
+}
+
+function installedVersionFromList(stdout, id) {
+  const parsed = tryParseJson(stdout);
+  const entries = Array.isArray(parsed) ? parsed : parsed?.plugins ?? parsed?.installed ?? [];
+  if (!Array.isArray(entries)) return null;
+  const entry = entries.find((item) => item?.id === id || `${item?.name}@${item?.marketplace}` === id);
+  return isStrictSemver(entry?.version) ? entry.version : null;
+}
+
+function runClaude(args, deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) return Promise.resolve({ error: "timeout" });
+  return new Promise((done) => {
+    execFile("claude", args, { timeout: remaining, killSignal: "SIGKILL", maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (!error) return done({ stdout });
+      if (error.code === "ENOENT") return done({ error: "claude not found" });
+      if (error.killed) return done({ error: "timeout" });
+      const lastLine = String(stderr ?? "").trim().split("\n").pop();
+      return done({ error: lastLine || `exit ${error.code}` });
+    });
+  });
+}
+
+// Returns the one line the hook prints at a cloud startup. Never throws: every failure
+// leaves the installed version in place and says why.
+export async function refreshPluginInCloud({ pluginRoot, installed, fetchLatest, env }) {
+  const line = (text) => `Graphit plugin: ${text}`;
+  if (!isStrictSemver(installed)) return line("update skipped: the installed version is unreadable");
+
+  // Stage 1 - the cheap gate: nothing newer published, nothing to do.
+  const latest = await fetchLatest();
+  if (!isStrictSemver(latest)) return line(`update failed, running ${installed}: could not read the published version`);
+  if (compareVersions(latest, installed) <= 0) return line(`current (${installed})`);
+
+  const layout = pluginCacheLayout(pluginRoot);
+  if (!layout) return line(`update skipped, running ${installed}: not a plugin-cache install`);
+  const id = `${layout.plugin}@${layout.marketplace}`;
+  const budget = Number(env.GRAPHIT_PLUGIN_REFRESH_BUDGET_MS);
+  const deadline = Date.now() + (budget > 0 ? budget : DEFAULT_BUDGET_MS);
+
+  // Stage 2 - npm publishes before the marketplace; update only what the marketplace offers.
+  const catalog = await runClaude(["plugin", "marketplace", "update", layout.marketplace], deadline);
+  if (catalog.error) return line(`update failed, running ${installed}: ${catalog.error}`);
+  const offered = marketplaceVersion(layout);
+  if (isStrictSemver(offered) && compareVersions(offered, installed) <= 0) {
+    return line(`marketplace still at ${offered} (npm has ${latest})`);
+  }
+
+  // Stage 3 - the update itself, then the version now on disk.
+  const update = await runClaude(["plugin", "update", id], deadline);
+  if (update.error) return line(`update failed, running ${installed}: ${update.error}`);
+  const list = await runClaude(["plugin", "list", "--json"], deadline);
+  const after = list.error ? null : installedVersionFromList(list.stdout, id);
+  if (!after) return line(`updated ${installed} -> unknown on disk (could not read the installed version)`);
+  if (compareVersions(after, installed) <= 0) return line(`update failed, running ${installed}: version unchanged after update`);
+  return line(`updated ${installed} -> ${after} on disk`);
+}

package/scripts/plugin-status/common.mjs

@@ -0,0 +1,107 @@
+// Feature #1042: shared constants and pure helpers, split out of plugin-status.mjs
+// (855 lines) before the cloud refresh lands. No module-level state and no
+// process.argv/env reads, so every sibling module can import it.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export const PACKAGE_NAME = "@graphit/cli";
+export const PLUGIN_ID = "graphit@graphit-plugin";
+export const CLAUDE_MARKETPLACE_NAME = "graphit-plugin";
+export const CLAUDE_PLUGIN_NAME = "graphit";
+// Project #246: version-cache schema. Bump when the cache shape changes; older
+// caches are then treated as a miss and refetched (self-healing).
+export const CACHE_SCHEMA_VERSION = 1;
+// Strict semver. The wrapper enforces the same shape (SEC-6); keep them in sync.
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+export function tryReadJson(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return readJson(path);
+  } catch {
+    return null;
+  }
+}
+
+export function tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+export function readFrontmatterVersion(path) {
+  try {
+    const content = readFileSync(path, "utf-8");
+    return content.match(/^skill_version:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function isStrictSemver(value) {
+  return typeof value === "string" && SEMVER_RE.test(value);
+}
+
+export function compareVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+
+  for (let index = 0; index < 3; index += 1) {
+    const leftPart = leftParts[index] ?? 0;
+    const rightPart = rightParts[index] ?? 0;
+    if (leftPart > rightPart) return 1;
+    if (leftPart < rightPart) return -1;
+  }
+
+  return 0;
+}
+
+export function versionIsBehind(version, currentVersion) {
+  if (!isStrictSemver(currentVersion)) return false;
+  if (!version || !isStrictSemver(version)) return true;
+  return compareVersions(version, currentVersion) < 0;
+}
+
+export function sanitizePathPart(value) {
+  return value.replace(/[^a-zA-Z0-9\-_.]/g, "-");
+}
+
+export function isWithinDirectory(child, parent) {
+  const parentResolved = resolve(parent);
+  const childResolved = resolve(child);
+  const rel = relative(parentResolved, childResolved);
+  return rel === "" || (!!rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+export function realpathSafe(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+// SEC-4: atomic write (tmp + rename) so concurrent SessionStart writers can never
+// leave a torn/partial file for the wrapper or a later read.
+export function atomicWriteJson(path, obj) {
+  const tmpPath = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(tmpPath, JSON.stringify(obj), "utf-8");
+    renameSync(tmpPath, path);
+  } catch {
+    // Writes here must never break startup hooks; clean up any temp file.
+    try {
+      rmSync(tmpPath, { force: true });
+    } catch {
+      // ignore
+    }
+  }
+}

package/scripts/plugin-status/hook-io.mjs

@@ -0,0 +1,200 @@
+// Feature #1042: the hook-only paths of plugin-status.mjs, split out unchanged
+// except that stdin is read once by the entry script and passed in (it can be read
+// only once, and the cloud refresh also needs the SessionStart payload).
+
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+import {
+  CACHE_SCHEMA_VERSION,
+  atomicWriteJson,
+  compareVersions,
+  realpathSafe,
+  tryReadJson,
+} from "./common.mjs";
+
+// Nudge throttle (US-3.2 / US-4.1: ~once/day). State is graphit-owned and atomic.
+const NUDGE_TTL_MS = 24 * 60 * 60 * 1000;
+
+function nudgeStatePath(cacheRoot) {
+  return join(cacheRoot, "nudge-state.json");
+}
+
+function readNudgeState(cacheRoot) {
+  const state = tryReadJson(nudgeStatePath(cacheRoot));
+  if (state && state.schemaVersion === CACHE_SCHEMA_VERSION && state.nudges && typeof state.nudges === "object") {
+    return state;
+  }
+  return { schemaVersion: CACHE_SCHEMA_VERSION, nudges: {} };
+}
+
+function nudgeAllowed(state, key) {
+  const last = state.nudges[key];
+  return typeof last !== "number" || Date.now() - last >= NUDGE_TTL_MS;
+}
+
+function persistNudges(cacheRoot, state, keys) {
+  if (keys.length === 0) return;
+  for (const key of keys) state.nudges[key] = Date.now();
+  atomicWriteJson(nudgeStatePath(cacheRoot), state);
+}
+
+// 4.1 (SEC-5): find a `graphit` on PATH that is NOT this plugin's bundled wrapper -
+// i.e. a legacy global @graphit/cli install. Because plugin executables are
+// appended to PATH (Phase 2 finding), any global install shadows the wrapper, so
+// its mere presence is the migration trigger. Returns the first such path or null.
+function detectForeignGraphit(pluginRoot) {
+  const pathValue = process.env.PATH ?? "";
+  if (!pathValue) return null;
+  const names = process.platform === "win32" ? ["graphit.cmd", "graphit.ps1", "graphit"] : ["graphit"];
+  // On Windows the plugin ships graphit.cmd / graphit.ps1 alongside the POSIX
+  // `graphit`, so excluding only `bin/graphit` would leave our own .cmd/.ps1
+  // wrappers looking like a foreign global. Exclude every bundled wrapper name.
+  const ownWrapperReals = new Set(
+    names.map((name) => realpathSafe(join(pluginRoot, "bin", name))),
+  );
+  for (const dir of pathValue.split(delimiter).filter(Boolean)) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (!existsSync(candidate)) continue;
+      const real = realpathSafe(candidate);
+      if (ownWrapperReals.has(real)) continue; // our own bundled wrapper
+      if (/[/\\]plugins[/\\]/.test(real)) continue; // a plugin-cache wrapper
+      return candidate;
+    }
+  }
+  return null;
+}
+
+// `raw` is the hook's stdin (null when it could not be read). A UserPromptSubmit run
+// continues only for a Graphit update/status question; every other run continues.
+export function shouldRunForPrompt(hookEvent, raw, parsed) {
+  if (hookEvent !== "UserPromptSubmit") return true;
+  if (raw === null) return false;
+
+  const prompt = String(parsed?.prompt ?? parsed?.user_prompt ?? raw).toLowerCase();
+  return (
+    prompt.includes("graphit") &&
+    /\b(update|version|status|doctor|plugin|stale|staleness)\b/.test(prompt)
+  );
+}
+
+// Feature #743: stamp a per-session marker so the CLI can tell whether the plugin
+// actually loaded THIS session. This SessionStart hook only runs when Claude Code
+// loaded the plugin at session start - a mid-session install never runs it, so the
+// marker is absent and the CLI can warn. The SessionStart payload carries session_id
+// (the same value as the Bash tool's CLAUDE_CODE_SESSION_ID - both from getSessionId()),
+// and the marker is keyed by it so concurrent sessions never clobber each other.
+export function stampSessionMarker(hookEvent, parsed, cacheRoot) {
+  if (hookEvent !== "SessionStart") return;
+  const sessionId = String(parsed?.session_id ?? "").trim();
+  // The id becomes a filename, so accept only an id-shaped token (path-safety).
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(sessionId)) return;
+  const dir = join(cacheRoot, "sessions");
+  try {
+    mkdirSync(dir, { recursive: true });
+    // Feature #765: marker CONTENT is a capability signal. The CLI arms the
+    // skill-invocation tripwire only when the marker declares skill-ack; legacy
+    // markers (bare timestamp) keep it dormant, so a new npm CLI over an old
+    // bundle can never block a session that cannot stamp.
+    //
+    // This is an implication, NOT an equivalence: within the plugin-bundle install
+    // path the hook, SKILL.md, and CLI bin ship together, so caps => the loaded
+    // SKILL.md teaches the attestation. It does NOT hold for legacy copied
+    // snapshots (`graphit setup --legacy-copy`, see src/skill-version.ts), where a
+    // stale copied SKILL.md can be loaded alongside a current plugin hook. Those
+    // sessions are why every block message carries the "already invoked?" escape.
+    writeFileSync(
+      join(dir, sessionId),
+      JSON.stringify({ caps: ["skill-ack"], ts: Date.now() }),
+      "utf-8",
+    );
+    pruneOldSessionMarkers(dir);
+  } catch {
+    // Best-effort: a missing marker only costs an extra (harmless) CLI warning.
+  }
+}
+
+// Feature #765: the `--skill-ack` session attestation is stamped in src/skill-guard.ts
+// (`stampSkillAck`), called from the `plugin status` command BEFORE it delegates here.
+// It deliberately does NOT live in this script: stamping must not depend on a second
+// artifact, or a package missing this file could leave the gate armed with no way to
+// clear it. A failed write is reported there rather than swallowed.
+
+function pruneOldSessionMarkers(dir) {
+  const cutoff = Date.now() - 48 * 60 * 60 * 1000;
+  try {
+    for (const name of readdirSync(dir)) {
+      try {
+        if (statSync(join(dir, name)).mtimeMs < cutoff) unlinkSync(join(dir, name));
+      } catch {
+        /* skip an unreadable entry */
+      }
+    }
+  } catch {
+    /* dir missing or unreadable - nothing to prune */
+  }
+}
+
+// Feature #1042: the SessionStart hook's Claude Code timeout is 120 s so the cloud
+// refresh fits, which also applies to a laptop's startup. Every other hook run arms
+// this cutoff, so a laptop can never wait longer than the 5 s it did before. unref'd:
+// it never keeps a finished run alive.
+export function armCutoff(ms, exit = (code) => process.exit(code)) {
+  const timer = setTimeout(() => exit(0), ms);
+  timer.unref();
+  return timer;
+}
+
+// Build the SessionStart agent nudges. Unlike --json (full diagnostics), the hook
+// surfaces only user-actionable, throttled items: the migration nudge (4.1), the
+// thin-layer /plugin update nudge (4.3), and legacy copied-skill cleanup. It does
+// NOT emit founder-only publish drift, nor the npm-install-g binary message - under
+// the plugin model the binary auto-updates via npx, so the bundle nudge is correct.
+export function buildHookNudges(status, { cacheRoot, pluginRoot, suppressPluginUpdate = false }) {
+  const state = readNudgeState(cacheRoot);
+  const lines = [];
+  const shown = [];
+
+  // 4.1 Migration: a global @graphit/cli shadows the plugin's npx-backed wrapper.
+  const foreignGraphit = detectForeignGraphit(pluginRoot);
+  if (foreignGraphit && nudgeAllowed(state, "legacy-global")) {
+    lines.push(
+      `- A legacy global \`graphit\` (@graphit/cli) at ${foreignGraphit} shadows the plugin's bundled CLI ` +
+        "(plugin executables are appended to PATH, so a global install wins). The plugin now delivers the CLI " +
+        "automatically via npx - tell the user once and offer to run `npm uninstall -g @graphit/cli` so it takes over.",
+    );
+    shown.push("legacy-global");
+  }
+
+  // 4.3 Thin-layer: the plugin bundle is behind npm latest (the binary itself
+  // auto-updates via npx; only the skill/hook/wrapper bundle needs a manual update).
+  // Feature #1042: a cloud startup already updated (or reported why not), and its
+  // agent cannot run /plugin update anyway, so the notice is left out there.
+  if (
+    !suppressPluginUpdate &&
+    status.latestVersion &&
+    compareVersions(status.latestVersion, status.currentVersion) > 0 &&
+    nudgeAllowed(state, "plugin-update")
+  ) {
+    lines.push(
+      `- A newer Graphit plugin is available (${status.currentVersion} -> ${status.latestVersion}). ` +
+        "Tell the user once to update it with `/plugin marketplace update graphit-plugin`, then " +
+        "`/plugin update graphit@graphit-plugin`, then restart Claude Code; the CLI itself already runs the latest release.",
+    );
+    shown.push("plugin-update");
+  }
+
+  // Legacy copied skill snapshots are real user-side issues - surface until removed.
+  for (const finding of status.findings) {
+    if (finding.type === "legacy-copied-skill-present" || finding.type === "copied-skill-stale") {
+      lines.push(`- ${finding.message}. ${finding.remediation}`);
+    }
+  }
+
+  if (lines.length === 0) return null;
+  return {
+    context: ["Graphit plugin status check found actionable update/version information.", ...lines].join("\n"),
+    persist: () => persistNudges(cacheRoot, state, shown),
+  };
+}