vigiles 33.2.0 → 33.3.0

package/dist/cli-main.js

@@ -39,11 +39,13 @@ const frame_js_1 = require("./core/frame.js");
 const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const install_reader_js_1 = require("./core/install-reader.js");
+const skill_links_js_1 = require("./skill-links.js");
 const plugin_declaration_js_1 = require("./plugin-declaration.js");
 const local_files_tracked_js_1 = require("./local-files-tracked.js");
 const local_files_js_1 = require("./local-files.js");
 const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
+const layout_js_1 = require("./core/layout.js");
 const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
 const optimize_js_1 = require("./optimize.js");
@@ -3177,29 +3179,226 @@ function reportInstall(plan, outcome) {
 }
 /**
  * Install vigiles's skills/hooks for the chosen harness(es) via the per-harness
- * `planPluginInstall` decision — Claude Code through the GLOBAL plugin
- * marketplace (nothing vendored into the repo), Codex via AGENTS.md-direct (no
- * global store). The decision is pure and unit-tested; this is the thin IO.
+ * `planPluginInstall` decision. Two carriers: the SKILLS are linked into the
+ * repo (`linkVigilesSkills`), so every clone and container has them after
+ * `npm install`; the GLOBAL install runs where it carries something the links
+ * cannot (`shouldRunGlobalInstall` — Claude Code's plugin carries the hooks).
+ * The decisions are pure and unit-tested; this is the thin IO.
+ *
+ * Returns the links it created or relinked, for the commit hint.
  */
 function installPlugins(harnesses) {
     const { execSync: exec } = require("node:child_process");
     const plans = (0, setup_plan_js_1.planPluginInstall)(harnesses, {
         hasClaude: harnesses.includes("claude") && harnessBinaryPresent("claude"),
     });
-    for (const plan of plans) {
+    const written = plans.flatMap((plan) => {
         console.log("");
-        reportInstall(plan, runInstall(plan, exec));
-    }
+        const home = plan.linkSkills ? harnessSkillsHome(plan.harness) : null;
+        const outcome = home === null ? null : linkVigilesSkills(home, process.cwd());
+        if (outcome !== null)
+            (0, skill_links_js_1.formatSkillLinks)(outcome).forEach((l) => {
+                console.log(l);
+            });
+        const linked = outcome !== null && (0, skill_links_js_1.skillLinksUsable)(outcome);
+        if ((0, setup_plan_js_1.shouldRunGlobalInstall)(plan, linked))
+            reportInstall(plan, runInstall(plan, exec));
+        else
+            console.log(`  No global ${plan.harness} skills install — the linked skills replace it, in every clone.`);
+        return outcome === null ? [] : changedLinks(outcome);
+    });
     // Claude Code gets its hooks from the global marketplace plugin; Codex has no
     // global store, so wire vigiles's proactive nudge hooks into the repo's
     // .codex/config.toml directly (the idiomatic, repo-committed place).
     if (harnesses.includes("codex"))
         wireCodexHooks();
     // Claude Code additionally gets a committed DECLARATION, so a collaborator who
-    // clones and never runs `init` is told the project wants this plugin instead
-    // of hitting the silence that costs a day. It does not install anything.
+    // clones and never runs `init` is told the project wants this plugin (its
+    // hooks) instead of silence. It does not install anything.
     if (harnesses.includes("claude"))
         declareVigilesPlugin();
+    return written;
+}
+/** The repo-relative skills home of the harness `init` calls `name`, or null. */
+function harnessSkillsHome(name) {
+    const adapter = (0, adapter_registry_js_1.getAdapter)(name);
+    return adapter === undefined ? null : (0, layout_js_1.skillsHome)(adapter.layout);
+}
+/** The repo-relative paths of the links this run created or rewrote — the ones git sees change. */
+function changedLinks(outcome) {
+    return outcome.kind === "linked"
+        ? outcome.results
+            .filter((r) => r.status === "created" || r.status === "relinked")
+            .map((r) => `${outcome.physicalHome}/${r.name}`)
+        : [];
+}
+/** The manifest file name the skill-linking code reads. */
+const PACKAGE_JSON = "package.json";
+/** One top-level field of `<dir>/package.json`, or undefined. Never throws. */
+function packageField(dir, field) {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, PACKAGE_JSON), "utf-8"));
+        return typeof pkg === "object" && pkg !== null
+            ? Object.entries(pkg).find(([k]) => k === field)?.[1]
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `package.json`'s `name`, or null. Never throws. */
+function packageNameAt(dir) {
+    const name = packageField(dir, "name");
+    return typeof name === "string" ? name : null;
+}
+/** A thrown value's message. */
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** A path's real location, or null when it does not resolve. Never throws. */
+function realOrNull(path) {
+    try {
+        return (0, node_fs_1.realpathSync)(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** What occupies `path`, for `planSkillLinks`. */
+function observeSkillEntry(path) {
+    const st = (0, node_fs_1.lstatSync)(path, { throwIfNoEntry: false });
+    if (st === undefined)
+        return { kind: "missing" };
+    if (st.isSymbolicLink())
+        return {
+            kind: "link",
+            target: (0, node_fs_1.readlinkSync)(path),
+            resolvesTo: realOrNull(path),
+        };
+    return st.isDirectory() ? { kind: "directory" } : { kind: "file" };
+}
+const LINK_IO = {
+    // "dir" matters only on Windows, where a directory link must say so.
+    symlink: (target, path) => {
+        (0, node_fs_1.symlinkSync)(target, path, "dir");
+    },
+    rename: node_fs_1.renameSync,
+    unlink: node_fs_1.unlinkSync,
+};
+/** Carry out one decision. A failed `symlink` is reported, never thrown. */
+function applySkillLink(decision, absHome) {
+    switch (decision.action) {
+        case "keep":
+            return { name: decision.name, status: "present" };
+        case "refuse":
+            return {
+                name: decision.name,
+                status: "skipped",
+                reason: decision.reason,
+            };
+        case "create":
+        case "replace":
+            try {
+                // Only a link `decideSkillLink` proved ours is ever replaced.
+                (0, skill_links_js_1.writeSkillLink)(LINK_IO, (0, node_path_1.join)(absHome, decision.name), decision.target, decision.action);
+                return {
+                    name: decision.name,
+                    status: decision.action === "replace" ? "relinked" : "created",
+                };
+            }
+            catch (e) {
+                const code = e instanceof Error && "code" in e && typeof e.code === "string"
+                    ? e.code
+                    : "";
+                return {
+                    name: decision.name,
+                    status: "skipped",
+                    reason: (0, skill_links_js_1.linkFailureReason)(code, errorText(e)),
+                };
+            }
+    }
+}
+/**
+ * Why `init` must not write under `absHome`, or null when it may. `.claude` or
+ * its `skills` can be a link to a dotfiles directory outside the repo; creating
+ * the home would follow it and put links where no commit of this repo reaches.
+ * What `mkdir -p` would write through is the nearest part of the path that
+ * already exists, so that is the part judged.
+ */
+function homeEscape(project, home, absHome) {
+    const nearest = (p) => (0, node_fs_1.lstatSync)(p, { throwIfNoEntry: false }) === undefined
+        ? nearest((0, node_path_1.dirname)(p))
+        : p;
+    const anchor = nearest(absHome);
+    const real = realOrNull(anchor);
+    if (real === null)
+        return `${(0, node_path_1.relative)(project, anchor)} is a link that does not resolve, so ${home} cannot be created`;
+    return (0, skill_links_js_1.isWithinProject)(project, real)
+        ? null
+        : `${home} leads to ${real}, outside the repository, and a link written there would not travel with a clone`;
+}
+/** The outcome when `init` makes no links, with the reason it prints. */
+function notLinked(reason) {
+    return { kind: "not-linked", reason };
+}
+/**
+ * Link vigiles's shipped skills into `home` (repo-relative) — the IO half of
+ * `src/skill-links.ts`, which decides everything: where the package is, what
+ * each entry becomes, and what the report says.
+ */
+function linkVigilesSkills(home, cwd) {
+    // Physical, so the relative target computed against the (physical) skills
+    // home is right even when the checkout sits under a symlink (macOS /tmp).
+    const project = (0, node_fs_1.realpathSync)(cwd);
+    const site = (0, skill_links_js_1.locatePackage)(project, {
+        isPackage: (dir) => packageNameAt(dir) === skill_links_js_1.VIGILES_PACKAGE,
+        isRepoRoot: (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, ".git")),
+        isWorkspaceRoot: (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "pnpm-workspace.yaml")) ||
+            packageField(dir, "workspaces") !== undefined,
+    });
+    const pkgText = (0, node_fs_1.existsSync)((0, node_path_1.join)(project, PACKAGE_JSON))
+        ? (0, node_fs_1.readFileSync)((0, node_path_1.join)(project, PACKAGE_JSON), "utf-8")
+        : null;
+    const blocked = (0, skill_links_js_1.linkPrecondition)({
+        isVigilesItself: packageNameAt(project) === skill_links_js_1.VIGILES_PACKAGE,
+        dependsOnVigiles: pkgText !== null && (0, install_reader_js_1.declaresVigilesDependency)(pkgText),
+        installed: site.kind === "installed",
+    });
+    if (blocked !== null)
+        return notLinked(blocked);
+    if (site.kind === "unsure")
+        return notLinked(site.reason);
+    // Names from the installed package when there is one, else from this CLI's
+    // own — the version `init` just declared as the devDependency.
+    const source = site.kind === "installed" ? site.dir : selfRoot();
+    const names = setup_plan_js_1.SHIPPED_SKILLS.filter((n) => (0, node_fs_1.existsSync)((0, node_path_1.join)(source, "skills", n, "SKILL.md")));
+    if (names.length === 0)
+        return notLinked(`no shipped skills found under ${(0, node_path_1.join)(source, "skills")}`);
+    const absHome = (0, node_path_1.resolve)(project, home);
+    const escape = homeEscape(project, home, absHome);
+    if (escape !== null)
+        return notLinked(escape);
+    try {
+        (0, node_fs_1.mkdirSync)(absHome, { recursive: true });
+    }
+    catch (e) {
+        return notLinked(`cannot create ${home}: ${errorText(e)}`);
+    }
+    const physicalHome = (0, node_fs_1.realpathSync)(absHome);
+    const plan = (0, skill_links_js_1.planSkillLinks)({
+        names,
+        site,
+        physicalHome,
+        entries: (n) => observeSkillEntry((0, node_path_1.join)(absHome, n)),
+        realOf: (n) => realOrNull((0, node_path_1.join)(site.dir, "skills", n)),
+    });
+    return {
+        kind: "linked",
+        home,
+        physicalHome: (0, skill_links_js_1.portableTarget)((0, node_path_1.relative)(project, physicalHome)),
+        pending: plan.pending,
+        results: plan.decisions.map((d) => applySkillLink(d, absHome)),
+    };
 }
 /**
  * Write the project-level plugin declaration into `.claude/settings.json`.
@@ -3208,8 +3407,9 @@ function installPlugins(harnesses) {
  * collaborator: an external-source plugin declared project-level does not load
  * until each person installs it on their own machine (the boundary is
  * deliberate — plugins run arbitrary code with the user's privileges). What it
- * buys is that Claude Code then PROMPTS them with the install command, instead
- * of the silence a fresh clone gets today. Silent absence → a prompt.
+ * buys is that Claude Code then PROMPTS them with the install command — for the
+ * HOOKS, which only the plugin carries. The skills reach them through the
+ * committed links (`linkVigilesSkills`), with or without the plugin.
  *
  * MERGES, never clobbers: this file holds the user's hooks, permissions and
  * other plugins. The merge rules are the pure, unit-tested
@@ -3249,8 +3449,9 @@ function declareVigilesPlugin() {
     (0, node_fs_1.writeFileSync)(path, JSON.stringify(edit.settings, null, 2) + "\n");
     console.log("✓ Declared the vigiles plugin in .claude/settings.json (commit it)\n" +
         "  This does NOT install it for anyone else — Claude Code will PROMPT a\n" +
-        "  collaborator to run `claude plugin install vigiles@vigiles`, instead of\n" +
-        "  the silence a fresh clone gets today.\n" +
+        "  collaborator to run `claude plugin install vigiles@vigiles`, which is how\n" +
+        "  they get the hooks. The skills don't wait for it: they come with the\n" +
+        "  linked .claude/skills/ entries.\n" +
         "  Nothing is vendored: the entry is a reference; the plugin still lives in\n" +
         "  the global cache, one copy shared across your repos.");
 }
@@ -3460,10 +3661,9 @@ async function setup(args) {
         console.log("");
         written.push(...wireGha(plan, harnesses));
     }
-    // Plugin/skill install — per-harness (Claude marketplace / Codex direct).
-    if (plan.plugin) {
-        installPlugins(harnesses);
-    }
+    // Skills linked into the repo + the per-harness global install (Claude
+    // marketplace for the hooks / Codex only when nothing could be linked).
+    const linkedSkills = plan.plugin ? installPlugins(harnesses) : [];
     // Agent-specific guidance.
     if (targets.includes("AGENTS.md")) {
         console.log("\n  Codex / Copilot reads AGENTS.md directly — no hooks needed.");
@@ -3483,7 +3683,14 @@ async function setup(args) {
         lint: plan.lint,
         written,
     });
-    printSetupSummary({ plan, strict, targets, adopted, written });
+    printSetupSummary({
+        plan,
+        strict,
+        targets,
+        adopted,
+        // The skill links the plugin step created, so the commit hint names them.
+        written: [...written, ...linkedSkills],
+    });
     // Surface the OTHER mode so both directions are discoverable — the two branches
     // are mutually exclusive (a run is either gate-only or full):
     //   • a gate-only setup → a ONE-LINE nudge to graduate to the full layer;

package/dist/core/adapter.d.ts

@@ -182,6 +182,13 @@ export interface InstallReader {
      * outside its own surface.
      */
     readonly repo: (repoRelative: string) => string | null;
+    /**
+     * The stored target of a repo SYMLINK (what `readlink` returns), or null when
+     * the path is not a link, is missing, or is NOT a path this adapter claims.
+     * It answers the one question `repo` cannot: a committed link whose target is
+     * not installed yet reads as null through `repo`, exactly like no link at all.
+     */
+    readonly repoLink: (repoRelative: string) => string | null;
     /**
      * A file under the user's HOME, or null. This is a read of the MACHINE, never
      * of the repository — the plugin-install record lives there — and everything

package/dist/core/install-reader.js

@@ -30,6 +30,18 @@ function readOrNull(absolute) {
         return null;
     }
 }
+/** A symlink's stored target, or null when it is not a link. Never throws. */
+function linkOrNull(absolute) {
+    try {
+        return (0, node_fs_1.lstatSync)(absolute, { throwIfNoEntry: false })?.isSymbolicLink() ===
+            true
+            ? (0, node_fs_1.readlinkSync)(absolute)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Directory names directly under `dir`, or [] when it is not readable. */
 function dirNames(dir) {
     try {
@@ -80,6 +92,9 @@ function buildInstallReader(adapter, root, opts = {}) {
         repo: (repoRelative) => adapter.claims(repoRelative)
             ? readOrNull((0, node_path_1.resolve)(root, repoRelative))
             : null,
+        repoLink: (repoRelative) => adapter.claims(repoRelative)
+            ? linkOrNull((0, node_path_1.resolve)(root, repoRelative))
+            : null,
         home: (homeRelative) => readOrNull((0, node_path_1.join)(home, homeRelative)),
         repoDependsOnVigiles: pkgJson !== null && declaresVigilesDependency(pkgJson),
         vendoredSkillNames: dirNames((0, node_path_1.join)(root, "node_modules", "vigiles", "skills")),

package/dist/core/layout.d.ts

@@ -241,6 +241,16 @@ export declare function executableSourceDirs(layout: PluginLayout): readonly str
  * written a layout where they differed.
  */
 export declare function materializePrefix(layout: PluginLayout): string;
+/**
+ * Where a REPOSITORY keeps its skills for this harness, repo-relative — the
+ * skill surface under {@link materializePrefix}: `.claude/skills` on Claude
+ * Code, `.agents/skills` on Codex. `null` when the layout has no skill surface.
+ *
+ * `vigiles init` links the package's shipped skills here, so it must be the
+ * directory the harness actually scans for a project; deriving it from the two
+ * fields that already say so keeps a third spelling from appearing.
+ */
+export declare function skillsHome(layout: Pick<PluginLayout, "surfaces" | "userSurfaceRoot">): string | null;
 /**
  * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
  * of that rule, as a RegExp source fragment matching the part of a path AFTER

package/dist/core/layout.js

@@ -4,6 +4,7 @@ exports.RULE_FILE_LEAF_RE = exports.AGENT_FILE_LEAF_RE = exports.SURFACE_KINDS =
 exports.surfaceDirs = surfaceDirs;
 exports.executableSourceDirs = executableSourceDirs;
 exports.materializePrefix = materializePrefix;
+exports.skillsHome = skillsHome;
 exports.rulesHome = rulesHome;
 exports.ruleFileRe = ruleFileRe;
 exports.agentSurfaceName = agentSurfaceName;
@@ -46,6 +47,22 @@ function executableSourceDirs(layout) {
 function materializePrefix(layout) {
     return layout.userSurfaceRoot ?? "";
 }
+/**
+ * Where a REPOSITORY keeps its skills for this harness, repo-relative — the
+ * skill surface under {@link materializePrefix}: `.claude/skills` on Claude
+ * Code, `.agents/skills` on Codex. `null` when the layout has no skill surface.
+ *
+ * `vigiles init` links the package's shipped skills here, so it must be the
+ * directory the harness actually scans for a project; deriving it from the two
+ * fields that already say so keeps a third spelling from appearing.
+ */
+function skillsHome(layout) {
+    const skill = layout.surfaces.skill;
+    if (skill === undefined || skill === "")
+        return null;
+    const root = layout.userSurfaceRoot;
+    return root === undefined || root === "" ? skill : `${root}/${skill}`;
+}
 /**
  * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
  * of that rule, as a RegExp source fragment matching the part of a path AFTER

package/dist/core/run-env.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The environment a child agent run inherits — the one place the runners turn
+ * a caller's `process.env` into a spawn env.
+ *
+ * Two shapes, both driven by the harness's declared {@link RunEnvPolicy}:
+ *
+ * - SCRUBBED (`scrubbedRunEnv`): a throwaway HOME/TMPDIR, the OS essentials, the
+ *   harness's declared auth, and the caller's own named extras. Everything else
+ *   is dropped. The eval tier's `ephemeralEnv` and the harness-tier preflight of
+ *   `experimental_outputStyleArms` use it.
+ * - INHERITED (`withoutSessionIdentity`): the caller's env as-is, minus the
+ *   harness's declared session identity. The default spawn of both tiers.
+ *
+ * In both, the parent session's identity never reaches the child. The core
+ * names no harness: which variables are auth and which are identity is the
+ * adapter's declaration.
+ *
+ * Pure — no fs, no spawn.
+ */
+import type { RunEnvPolicy } from "./runtime.js";
+type EnvLike = Readonly<Record<string, string | undefined>>;
+/**
+ * What ANY spawned process needs to function, whatever the harness: resolve
+ * binaries (`PATH`) and keep the locale and terminal (`LANG`, `LC_*`, `TERM`).
+ * Mirrors what `bwrapArgs` sets back after `--clearenv` in `src/sandbox.ts`.
+ */
+export declare const OS_ESSENTIAL_ENV: readonly string[];
+/**
+ * Build a SCRUBBED run environment: a NEW env with `HOME`/`TMPDIR` set to the
+ * throwaway `opts.home`, the {@link OS_ESSENTIAL_ENV}, the harness's
+ * `policy.keep`, and the caller's `opts.allow`, taken from `base`. Everything
+ * else is dropped, and `policy.sessionIdentity` is dropped even when listed in
+ * `keep` or `allow`.
+ *
+ * Without a policy only the essentials pass: right for a run against a scripted
+ * mock, which needs no auth.
+ */
+export declare function scrubbedRunEnv(base: EnvLike, opts: {
+    readonly home: string;
+    readonly policy?: RunEnvPolicy;
+    readonly allow?: readonly string[];
+}): Readonly<Record<string, string>>;
+/**
+ * The caller's env with the harness's declared session identity removed — the
+ * INHERITED shape. Unset (`undefined`) values are dropped too, so the result is
+ * a plain spawn env. Without a policy nothing is removed.
+ */
+export declare function withoutSessionIdentity(base: EnvLike, policy?: RunEnvPolicy): Readonly<Record<string, string>>;
+export {};
+//# sourceMappingURL=run-env.d.ts.map

package/dist/core/run-env.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OS_ESSENTIAL_ENV = void 0;
+exports.scrubbedRunEnv = scrubbedRunEnv;
+exports.withoutSessionIdentity = withoutSessionIdentity;
+/**
+ * What ANY spawned process needs to function, whatever the harness: resolve
+ * binaries (`PATH`) and keep the locale and terminal (`LANG`, `LC_*`, `TERM`).
+ * Mirrors what `bwrapArgs` sets back after `--clearenv` in `src/sandbox.ts`.
+ */
+exports.OS_ESSENTIAL_ENV = ["PATH", "LANG", "TERM"];
+const OS_ESSENTIAL_PREFIXES = ["LC_"];
+/**
+ * Build a SCRUBBED run environment: a NEW env with `HOME`/`TMPDIR` set to the
+ * throwaway `opts.home`, the {@link OS_ESSENTIAL_ENV}, the harness's
+ * `policy.keep`, and the caller's `opts.allow`, taken from `base`. Everything
+ * else is dropped, and `policy.sessionIdentity` is dropped even when listed in
+ * `keep` or `allow`.
+ *
+ * Without a policy only the essentials pass: right for a run against a scripted
+ * mock, which needs no auth.
+ */
+function scrubbedRunEnv(base, opts) {
+    const identity = new Set(opts.policy?.sessionIdentity ?? []);
+    const exact = new Set([
+        ...exports.OS_ESSENTIAL_ENV,
+        ...(opts.policy?.keep ?? []),
+        ...(opts.allow ?? []),
+    ]);
+    const passes = (k) => !identity.has(k) &&
+        (exact.has(k) || OS_ESSENTIAL_PREFIXES.some((p) => k.startsWith(p)));
+    return {
+        ...defined(base, passes),
+        // Last, so they win over anything passed through.
+        HOME: opts.home,
+        TMPDIR: opts.home,
+    };
+}
+/**
+ * The caller's env with the harness's declared session identity removed — the
+ * INHERITED shape. Unset (`undefined`) values are dropped too, so the result is
+ * a plain spawn env. Without a policy nothing is removed.
+ */
+function withoutSessionIdentity(base, policy) {
+    const identity = new Set(policy?.sessionIdentity ?? []);
+    return defined(base, (k) => !identity.has(k));
+}
+function defined(base, keep) {
+    return Object.fromEntries(Object.entries(base).filter((e) => e[1] !== undefined && keep(e[0])));
+}
+//# sourceMappingURL=run-env.js.map

package/dist/core/runtime.d.ts

@@ -54,5 +54,49 @@ export interface HarnessRuntime {
      * caller resolves the raw string via `agentBinary --version`); unit-testable.
      */
     versionKey(raw: string): string;
+    /**
+     * Which of the caller's environment a child run may inherit — see
+     * {@link RunEnvPolicy}. Absent: a scrubbed run inherits no harness variable,
+     * and nothing is removed from an inherited env.
+     */
+    readonly runEnv?: RunEnvPolicy;
+}
+/**
+ * Which of the caller's environment a CHILD run of this harness may inherit.
+ *
+ * A run spawned from inside a live session of the same harness (an eval started
+ * by an agent, a harness test run from a hook) inherits that session's process
+ * environment, and a harness marks its own session there. Measured on Claude
+ * Code 2.1.292 (2026-10-07): a child `claude -p` started with the parent's
+ * session variables ran AS the parent session — a task it created landed in the
+ * parent's live task list. Which variables are identity and which are auth is a
+ * fact about one harness, so the adapter declares it and the runners apply it
+ * (`src/core/run-env.ts`) without spelling a single name.
+ *
+ * Optional, so an adapter written before this field still type-checks. An
+ * adapter without one gets the strict reading: a scrubbed run inherits no
+ * harness variable at all, and an inherited one has nothing removed.
+ */
+export interface RunEnvPolicy {
+    /**
+     * Exact names a SCRUBBED run (fresh HOME, cleared env) inherits: the
+     * harness's auth and backend selection, nothing else. An allowlist on purpose —
+     * a harness's session variables are open-ended (the Claude Code 2.1.292
+     * binary references several dozen `*SESSION*` / `*SOCKET*` / `*TOKEN*` names),
+     * so a prefix with a few exceptions would keep passing whichever ones nobody
+     * listed.
+     */
+    readonly keep: readonly string[];
+    /**
+     * Auth FILES under HOME (relative paths) that a scrubbed run's throwaway HOME
+     * is seeded with, by copy. The file half of `keep`.
+     */
+    readonly keepHomeFiles: readonly string[];
+    /**
+     * The PARENT session's identity: names no child run ever inherits — not a
+     * scrubbed run, and not a run that otherwise inherits the whole caller env.
+     * Wins over `keep` and over any name a caller allows.
+     */
+    readonly sessionIdentity: readonly string[];
 }
 //# sourceMappingURL=runtime.d.ts.map

package/dist/core/skill-link-target.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Is a symlink's stored target one that `vigiles init` writes — a path ending
+ * in `node_modules/vigiles/skills/<name>`, for the SAME skill name?
+ *
+ * Two readers ask, and must agree, so the answer lives here once:
+ *
+ * - `init` (`../skill-links.ts`): an existing link of this shape that points
+ *   somewhere other than where `init` would link now was made by an earlier
+ *   `init` (for example before a workspace install hoisted the package), so it
+ *   is replaced instead of being refused as the user's;
+ * - `audit` (`../adapters/claude-code/skill-reachability.ts`): only a dangling
+ *   link of this shape is "vigiles's link, run npm install". A dangling link
+ *   that merely shares a skill's NAME is the user's, and the advice would send
+ *   them to fix the wrong thing.
+ *
+ * The test is on path SEGMENTS (either separator, so a link written on Windows
+ * reads the same), not on a substring: `my-node_modules/vigiles/...` is not it.
+ */
+export declare function isVigilesSkillTarget(target: string, name: string): boolean;
+//# sourceMappingURL=skill-link-target.d.ts.map

package/dist/core/skill-link-target.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVigilesSkillTarget = isVigilesSkillTarget;
+/**
+ * Is a symlink's stored target one that `vigiles init` writes — a path ending
+ * in `node_modules/vigiles/skills/<name>`, for the SAME skill name?
+ *
+ * Two readers ask, and must agree, so the answer lives here once:
+ *
+ * - `init` (`../skill-links.ts`): an existing link of this shape that points
+ *   somewhere other than where `init` would link now was made by an earlier
+ *   `init` (for example before a workspace install hoisted the package), so it
+ *   is replaced instead of being refused as the user's;
+ * - `audit` (`../adapters/claude-code/skill-reachability.ts`): only a dangling
+ *   link of this shape is "vigiles's link, run npm install". A dangling link
+ *   that merely shares a skill's NAME is the user's, and the advice would send
+ *   them to fix the wrong thing.
+ *
+ * The test is on path SEGMENTS (either separator, so a link written on Windows
+ * reads the same), not on a substring: `my-node_modules/vigiles/...` is not it.
+ */
+function isVigilesSkillTarget(target, name) {
+    const tail = target
+        .split(/[\\/]+/)
+        .filter((s) => s !== "")
+        .slice(-4);
+    return (tail.length === 4 &&
+        tail[0] === "node_modules" &&
+        tail[1] === "vigiles" &&
+        tail[2] === "skills" &&
+        tail[3] === name);
+}
+//# sourceMappingURL=skill-link-target.js.map