wicked-crew 0.7.25 → 0.7.26

package/dist/skills/live-generations.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Which published generations a LIVE run may still be reading (design v3 DECISION 1: "old
+ * generations are reaped only after no live session references them").
+ *
+ * The engine resolves `WICKED_SKILLS_SNAPSHOT` at every worker spawn and reports the generation it
+ * ADMITTED as a `skillsSnapshotHanded` CoreEvent ({session, gen, …}) — the authoritative record of
+ * which generation each session's spawn was actually handed. Crew keeps TWO kinds of pin:
+ *
+ *   session pins   a session is tracked from its first event; a `skillsSnapshotHanded` pins the
+ *                  EXACT generation the engine reports (its `gen` field), never "whatever `current`
+ *                  happens to be when crew observes some later event" (codex round 3); every
+ *                  generation published WHILE the session is live is pinned to it too — its next
+ *                  unit spawn reads (and will report) the new `current`; the terminal frame
+ *                  (`sessionCompleted` / `sessionFailed` / `runCancelled` — the same triple
+ *                  api/seat-health.ts drops assignments on) releases every pin the session held.
+ *
+ *   launch pins    EXPLICIT ACCOUNTING for the gap between a launch and the engine's report. When
+ *                  the daemon hands a launch to the engine (`CoreAdapter.onLaunch`: launchRun,
+ *                  resumeRun, confirmGate, launchCampaign, resumeCampaign — every path a spawn can
+ *                  come from; the campaign's own DAG-node runs are pinned as the engine announces
+ *                  them, `campaignNodeStarted`, under the campaign's umbrella pin), crew opens a pin
+ *                  for that launch holding the generation the env exports RIGHT NOW, and every
+ *                  generation published after that is added to it (the spawn may read any of them).
+ *                  A launch pin is released ONLY when the engine reports the handed generation for
+ *                  that session (`skillsSnapshotHanded` — the session pin takes over), when the
+ *                  run/campaign reaches a terminal state, or when the engine REJECTED the launch
+ *                  (nothing will ever read it). It never expires by publish count or age (codex
+ *                  round 4: a bounded window let a run's generation be reaped while its handoff
+ *                  report was still outstanding — publish count bounds nothing about handoff delay).
+ *                  Reaping skips any generation with an unreleased launch pin.
+ *
+ * The ledger is in-memory: the engine is in-process, so a daemon restart ends every worker it
+ * spawned, and a resumed run's launch (`resumeRun`) opens a fresh launch pin.
+ */
+import type { CoreEvent } from '../core/types.js';
+export type LiveGenerationObservation = 'pinned' | 'released' | 'ignored';
+/** What the daemon hands the engine: a run (launch / resume / gate answer) or a campaign. */
+export type LaunchKind = 'run' | 'campaign';
+export declare class LiveGenerations {
+    /** Session pins: session id → the generations the engine reported + every one published since. */
+    private readonly sessions;
+    /** Launch pins: `run:<id>` / `campaign:<id>` → the generations the launch may read, until it is accounted for. */
+    private readonly launchPins;
+    /** The generation the env exports right now (`exported`), or `null` when none is (fallback / unpublished). */
+    private exportedGen;
+    private static key;
+    /**
+     * Fold one CoreEvent: track a live session, pin the EXACT generation the engine reports on a
+     * `skillsSnapshotHanded` (releasing that session's launch pin — the engine has accounted for the
+     * launch), release on a terminal frame; pin a campaign's node run as the engine announces it and
+     * release the campaign's pin on its terminal frame. A non-`skillsSnapshotHanded` session event
+     * only tracks the session — it never pins "current at event time" (the bug codex round 3
+     * replaced): the generation a spawn actually used comes from the engine's own report, and the
+     * pre-report window is covered by the launch pin.
+     */
+    observe(event: CoreEvent): LiveGenerationObservation;
+    /**
+     * The env now exports generation `gen` to new launches (`WICKED_SKILLS_SNAPSHOT`;
+     * runtime.afterPublish), or nothing (`null`). A launch pin opened after this starts from it.
+     */
+    exported(gen: number | null): void;
+    /**
+     * The daemon is handing a launch to the engine (before the engine call, so no spawn can read the
+     * env ahead of the pin): open its launch pin at the generation the env exports right now. The pin
+     * accumulates every later publish (`published`) and is released only by the engine's report for
+     * that session, the run's / campaign's terminal frame, or `launchRejected`.
+     */
+    launched(kind: LaunchKind, id: string): void;
+    /** The engine REFUSED the launch (the call rejected): nothing will read it — release its pin. */
+    launchRejected(kind: LaunchKind, id: string): void;
+    /** A generation was just published: every live session and every open launch may read it at its next spawn. */
+    published(gen: number): void;
+    /** The union of every live session's pins and every open launch pin — what the reaper must keep. */
+    pinned(): ReadonlySet<number>;
+    /** Live sessions being tracked (diagnostics + tests). */
+    liveSessions(): string[];
+    /** Launches handed to the engine and not yet accounted for (`run:<id>` / `campaign:<id>`; diagnostics + tests). */
+    openLaunches(): string[];
+}
+//# sourceMappingURL=live-generations.d.ts.map

package/dist/skills/live-generations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-generations.d.ts","sourceRoot":"","sources":["../../src/skills/live-generations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAclD,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1E,6FAA6F;AAC7F,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,UAAU,CAAC;AAe5C,qBAAa,eAAe;IAC1B,kGAAkG;IAClG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,kHAAkH;IAClH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,8GAA8G;IAC9G,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,MAAM,CAAC,GAAG;IAIlB;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,yBAAyB;IAoCpD;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIlC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAO5C,iGAAiG;IACjG,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAIlD,+GAA+G;IAC/G,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK5B,oGAAoG;IACpG,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC;IAO7B,yDAAyD;IACzD,YAAY,IAAI,MAAM,EAAE;IAIxB,mHAAmH;IACnH,YAAY,IAAI,MAAM,EAAE;CAGzB"}

package/dist/skills/live-generations.js

@@ -0,0 +1,163 @@
+/**
+ * Which published generations a LIVE run may still be reading (design v3 DECISION 1: "old
+ * generations are reaped only after no live session references them").
+ *
+ * The engine resolves `WICKED_SKILLS_SNAPSHOT` at every worker spawn and reports the generation it
+ * ADMITTED as a `skillsSnapshotHanded` CoreEvent ({session, gen, …}) — the authoritative record of
+ * which generation each session's spawn was actually handed. Crew keeps TWO kinds of pin:
+ *
+ *   session pins   a session is tracked from its first event; a `skillsSnapshotHanded` pins the
+ *                  EXACT generation the engine reports (its `gen` field), never "whatever `current`
+ *                  happens to be when crew observes some later event" (codex round 3); every
+ *                  generation published WHILE the session is live is pinned to it too — its next
+ *                  unit spawn reads (and will report) the new `current`; the terminal frame
+ *                  (`sessionCompleted` / `sessionFailed` / `runCancelled` — the same triple
+ *                  api/seat-health.ts drops assignments on) releases every pin the session held.
+ *
+ *   launch pins    EXPLICIT ACCOUNTING for the gap between a launch and the engine's report. When
+ *                  the daemon hands a launch to the engine (`CoreAdapter.onLaunch`: launchRun,
+ *                  resumeRun, confirmGate, launchCampaign, resumeCampaign — every path a spawn can
+ *                  come from; the campaign's own DAG-node runs are pinned as the engine announces
+ *                  them, `campaignNodeStarted`, under the campaign's umbrella pin), crew opens a pin
+ *                  for that launch holding the generation the env exports RIGHT NOW, and every
+ *                  generation published after that is added to it (the spawn may read any of them).
+ *                  A launch pin is released ONLY when the engine reports the handed generation for
+ *                  that session (`skillsSnapshotHanded` — the session pin takes over), when the
+ *                  run/campaign reaches a terminal state, or when the engine REJECTED the launch
+ *                  (nothing will ever read it). It never expires by publish count or age (codex
+ *                  round 4: a bounded window let a run's generation be reaped while its handoff
+ *                  report was still outstanding — publish count bounds nothing about handoff delay).
+ *                  Reaping skips any generation with an unreleased launch pin.
+ *
+ * The ledger is in-memory: the engine is in-process, so a daemon restart ends every worker it
+ * spawned, and a resumed run's launch (`resumeRun`) opens a fresh launch pin.
+ */
+/** The frames after which a session spawns nothing more. */
+const TERMINAL_EVENT_TYPES = new Set(['sessionCompleted', 'sessionFailed', 'runCancelled']);
+/** The frames after which a campaign launches no more node runs. */
+const CAMPAIGN_TERMINAL_EVENT_TYPES = new Set(['campaignCompleted', 'campaignFailed', 'campaignCancelled']);
+/** The engine's per-spawn record of the generation it handed a session. */
+const SKILLS_SNAPSHOT_HANDED = 'skillsSnapshotHanded';
+/** The engine's announcement of a campaign DAG-node run: `{campaign, node, runId}`. */
+const CAMPAIGN_NODE_STARTED = 'campaignNodeStarted';
+/** The generation a `skillsSnapshotHanded` reports, or `null` (a live-cache fallback carries no
+ *  reapable generation — `gen: null`). */
+function handedGeneration(event) {
+    const gen = event.gen;
+    if (typeof gen !== 'string' || !/^\d+$/.test(gen))
+        return null;
+    const n = Number(gen);
+    return Number.isInteger(n) && n >= 1 ? n : null;
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+export class LiveGenerations {
+    /** Session pins: session id → the generations the engine reported + every one published since. */
+    sessions = new Map();
+    /** Launch pins: `run:<id>` / `campaign:<id>` → the generations the launch may read, until it is accounted for. */
+    launchPins = new Map();
+    /** The generation the env exports right now (`exported`), or `null` when none is (fallback / unpublished). */
+    exportedGen = null;
+    static key(kind, id) {
+        return `${kind}:${id}`;
+    }
+    /**
+     * Fold one CoreEvent: track a live session, pin the EXACT generation the engine reports on a
+     * `skillsSnapshotHanded` (releasing that session's launch pin — the engine has accounted for the
+     * launch), release on a terminal frame; pin a campaign's node run as the engine announces it and
+     * release the campaign's pin on its terminal frame. A non-`skillsSnapshotHanded` session event
+     * only tracks the session — it never pins "current at event time" (the bug codex round 3
+     * replaced): the generation a spawn actually used comes from the engine's own report, and the
+     * pre-report window is covered by the launch pin.
+     */
+    observe(event) {
+        const campaign = nonEmpty(event.campaign);
+        if (campaign !== undefined && event.session === undefined) {
+            if (CAMPAIGN_TERMINAL_EVENT_TYPES.has(event.type)) {
+                return this.launchPins.delete(LiveGenerations.key('campaign', campaign)) ? 'released' : 'ignored';
+            }
+            if (event.type === CAMPAIGN_NODE_STARTED) {
+                const runId = nonEmpty(event.runId);
+                if (runId === undefined)
+                    return 'ignored';
+                this.launched('run', runId);
+                return 'pinned';
+            }
+            return 'ignored';
+        }
+        const session = nonEmpty(event.session);
+        if (session === undefined)
+            return 'ignored';
+        if (TERMINAL_EVENT_TYPES.has(event.type)) {
+            const hadSession = this.sessions.delete(session);
+            const hadLaunch = this.launchPins.delete(LiveGenerations.key('run', session));
+            return hadSession || hadLaunch ? 'released' : 'ignored';
+        }
+        let gens = this.sessions.get(session);
+        if (gens === undefined) {
+            gens = new Set();
+            this.sessions.set(session, gens);
+        }
+        if (event.type === SKILLS_SNAPSHOT_HANDED) {
+            const gen = handedGeneration(event);
+            if (gen !== null)
+                gens.add(gen);
+            // The engine has accounted for this launch — which generation it used (or that it used
+            // none: a live-cache fallback). The durable session pin lives until the terminal frame.
+            this.launchPins.delete(LiveGenerations.key('run', session));
+        }
+        return 'pinned';
+    }
+    /**
+     * The env now exports generation `gen` to new launches (`WICKED_SKILLS_SNAPSHOT`;
+     * runtime.afterPublish), or nothing (`null`). A launch pin opened after this starts from it.
+     */
+    exported(gen) {
+        this.exportedGen = gen;
+    }
+    /**
+     * The daemon is handing a launch to the engine (before the engine call, so no spawn can read the
+     * env ahead of the pin): open its launch pin at the generation the env exports right now. The pin
+     * accumulates every later publish (`published`) and is released only by the engine's report for
+     * that session, the run's / campaign's terminal frame, or `launchRejected`.
+     */
+    launched(kind, id) {
+        const key = LiveGenerations.key(kind, id);
+        const gens = this.launchPins.get(key) ?? new Set();
+        if (this.exportedGen !== null)
+            gens.add(this.exportedGen);
+        this.launchPins.set(key, gens);
+    }
+    /** The engine REFUSED the launch (the call rejected): nothing will read it — release its pin. */
+    launchRejected(kind, id) {
+        this.launchPins.delete(LiveGenerations.key(kind, id));
+    }
+    /** A generation was just published: every live session and every open launch may read it at its next spawn. */
+    published(gen) {
+        for (const gens of this.sessions.values())
+            gens.add(gen);
+        for (const gens of this.launchPins.values())
+            gens.add(gen);
+    }
+    /** The union of every live session's pins and every open launch pin — what the reaper must keep. */
+    pinned() {
+        const out = new Set();
+        for (const gens of this.sessions.values())
+            for (const gen of gens)
+                out.add(gen);
+        for (const gens of this.launchPins.values())
+            for (const gen of gens)
+                out.add(gen);
+        return out;
+    }
+    /** Live sessions being tracked (diagnostics + tests). */
+    liveSessions() {
+        return [...this.sessions.keys()].sort();
+    }
+    /** Launches handed to the engine and not yet accounted for (`run:<id>` / `campaign:<id>`; diagnostics + tests). */
+    openLaunches() {
+        return [...this.launchPins.keys()].sort();
+    }
+}
+//# sourceMappingURL=live-generations.js.map

package/dist/skills/live-generations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-generations.js","sourceRoot":"","sources":["../../src/skills/live-generations.ts"],"names":[],"mappings":"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"}

package/dist/skills/plugin-source.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Where the shipped baseline comes from: the LIVE installed wicked-garden plugin.
+ *
+ * The daemon seeds (and refreshes) its skills root from the plugin Claude Code actually runs —
+ * the marketplace cache under `<CLAUDE_CONFIG_DIR|~/.claude>/plugins/cache/wicked-garden/
+ * wicked-garden/<version>` (highest version wins). That is the ONLY automatic source (design v3
+ * §3/§8; codex review of #480): the hand-installed `<config dir>/plugins/wicked-garden` copy is the
+ * exact stale artifact the operator's `clis.toml` hack pointed workers at (12.28.1 while the live
+ * cache was 12.32.0 — design v3 §"Verified mechanics"), so it is never a fallback. NEVER a repo
+ * checkout by default either. `WICKED_CREW_SKILLS_SOURCE` is the one explicit override — for
+ * tests, and for an operator who deliberately wants a checkout or that hand copy. A machine without
+ * the cache has no source at all: crew does not vendor garden — the seed says "install garden
+ * first" loudly (`SkillsSourceUnavailableError`) and the runtime leaves the engine input unset.
+ *
+ * # No-follow BELOW the root (codex round 6 on #480)
+ *
+ * The source ROOT may legitimately be reached through a symlink — operators symlink `~/.claude`,
+ * and the marketplace cache may sit behind a linked config dir — so the root is resolved ONCE
+ * (`realPluginRoot`, the one place a link is followed) and every designated entry BELOW it is
+ * lstat-walked (`noFollowEntry`): the manifest dir, `plugin.json`, each catalog, each root file,
+ * each bundle directory and everything inside it. A symlink among them is refused by name
+ * (`PluginSourceSymlinkError`) — a seed refuses to start (the runtime's `skills.config`), a
+ * refresh answers a `blocked` envelope — and nothing is copied: a linked catalog or a linked skill
+ * dir would otherwise copy bytes from outside the declared source into the daemon's root and hand
+ * them to every worker.
+ */
+import type { SkillSourceKind } from '../core/types.js';
+/** Explicit plugin-source override — the seam tests and proof scripts aim at a fixture plugin. */
+export declare const SKILLS_SOURCE_ENV = "WICKED_CREW_SKILLS_SOURCE";
+/** Relative path of the Claude Code plugin manifest inside a plugin root. */
+export declare const PLUGIN_MANIFEST_REL: string;
+export interface PluginSource {
+    /** Absolute plugin root (the directory holding `.claude-plugin/plugin.json`). */
+    path: string;
+    kind: SkillSourceKind;
+    /** `version` from the plugin manifest. */
+    plugin_version: string;
+}
+/** The Claude Code config dir the plugin cache lives under: `CLAUDE_CONFIG_DIR`, else `~/.claude`. */
+export declare function claudeConfigDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * A designated entry of the plugin source is a symlink — the seed/refresh is refused by name and
+ * nothing is copied (module header). `entry` is the plugin-relative POSIX path of the link.
+ */
+export declare class PluginSourceSymlinkError extends Error {
+    readonly root: string;
+    readonly entry: string;
+    readonly target: string;
+    constructor(root: string, entry: string, target: string);
+}
+/**
+ * The plugin root with every link resolved — the ONE place a link is followed (an operator's
+ * symlinked config dir reaches the root). `null` when it does not exist or is not a directory.
+ */
+export declare function realPluginRoot(dir: string): string | null;
+/**
+ * `join(root, ...segments)` after lstat-walking every segment BELOW the canonical root: a symlink at
+ * any of them throws `PluginSourceSymlinkError` naming it; a component that does not exist (or sits
+ * below a regular file) answers `null`. `sourceSpelling` is the root as the operator spelled it, for
+ * the error.
+ */
+export declare function noFollowEntry(root: string, segments: ReadonlyArray<string>, sourceSpelling?: string): string | null;
+/**
+ * The plugin manifest's `version` at `dir`, or `null` when `dir` is not a plugin root. The manifest
+ * is read NO-FOLLOW below the (once-resolved) root: a symlinked `.claude-plugin/` or `plugin.json`
+ * throws `PluginSourceSymlinkError` — never a version read through a link (codex round 6).
+ */
+export declare function pluginVersionAt(dir: string): string | null;
+/**
+ * A TOTAL order over version strings, so "highest version wins" never depends on `readdir` order
+ * (Copilot on #480). Numeric dotted order first (`12.9.0` < `12.32.0`; a shorter release sorts
+ * before a longer one with the same prefix; a non-integer segment sorts below any integer). A
+ * prerelease suffix (`12.0.0-beta`, everything after the first `-`) sorts BELOW its release
+ * (`12.0.0-beta` < `12.0.0`), and two prereleases compare identifier by identifier the semver way
+ * (numeric identifiers numerically and before alphanumeric ones, then lexically, shorter first).
+ * Distinct strings NEVER compare equal: whatever survives all of that (`12.00.0` vs `12.0.0`) is
+ * ordered lexically.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Classify a plugin root: a git checkout when it carries `.git`; the installed plugin when it
+ * sits under a `plugins/` directory (the marketplace cache or the hand-installed copy); anything
+ * else is an explicit plugin-shaped directory (an unpacked tarball, a test fixture).
+ */
+export declare function classifySource(dir: string): SkillSourceKind;
+/** A `PluginSource` for an explicit plugin root, or `null` when it is not a plugin root. */
+export declare function pluginSourceAt(dir: string): PluginSource | null;
+/** The marketplace cache dir the live plugin versions live under, for a config dir. */
+export declare function livePluginCacheDir(configDir: string): string;
+/**
+ * Discover the live installed plugin: the explicit `WICKED_CREW_SKILLS_SOURCE` override, else the
+ * highest version in the marketplace cache. NOTHING else — in particular not the hand-installed
+ * `plugins/wicked-garden` copy (see the module header). `env`/`home` are injectable so tests never
+ * read the developer's real config dir. Returns `null` when nothing is installed — the caller says
+ * "install garden first" loudly.
+ */
+export declare function discoverLivePlugin(opts?: {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): PluginSource | null;
+export interface GitState {
+    git_sha: string | null;
+    git_dirty: boolean;
+    /** Present when the source is a checkout but git could not answer — the caller logs it. */
+    error?: string;
+}
+/** The checkout's HEAD sha + dirty flag; `{null,false}` for a non-checkout source. */
+export declare function gitStateOf(source: PluginSource): GitState;
+//# sourceMappingURL=plugin-source.d.ts.map

package/dist/skills/plugin-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-source.d.ts","sourceRoot":"","sources":["../../src/skills/plugin-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAIxD,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,QAAwC,CAAC;AAEzE,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;IACtB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAGtG;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAFd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM;CAS1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,cAAc,GAAE,MAAa,GAAG,MAAM,GAAG,IAAI,CAezH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAa5D;AA+CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAI3D;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAG/D;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,YAAY,GAAG,IAAI,CAerB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,QAAQ,CAuBzD"}

package/dist/skills/plugin-source.js

@@ -0,0 +1,272 @@
+/**
+ * Where the shipped baseline comes from: the LIVE installed wicked-garden plugin.
+ *
+ * The daemon seeds (and refreshes) its skills root from the plugin Claude Code actually runs —
+ * the marketplace cache under `<CLAUDE_CONFIG_DIR|~/.claude>/plugins/cache/wicked-garden/
+ * wicked-garden/<version>` (highest version wins). That is the ONLY automatic source (design v3
+ * §3/§8; codex review of #480): the hand-installed `<config dir>/plugins/wicked-garden` copy is the
+ * exact stale artifact the operator's `clis.toml` hack pointed workers at (12.28.1 while the live
+ * cache was 12.32.0 — design v3 §"Verified mechanics"), so it is never a fallback. NEVER a repo
+ * checkout by default either. `WICKED_CREW_SKILLS_SOURCE` is the one explicit override — for
+ * tests, and for an operator who deliberately wants a checkout or that hand copy. A machine without
+ * the cache has no source at all: crew does not vendor garden — the seed says "install garden
+ * first" loudly (`SkillsSourceUnavailableError`) and the runtime leaves the engine input unset.
+ *
+ * # No-follow BELOW the root (codex round 6 on #480)
+ *
+ * The source ROOT may legitimately be reached through a symlink — operators symlink `~/.claude`,
+ * and the marketplace cache may sit behind a linked config dir — so the root is resolved ONCE
+ * (`realPluginRoot`, the one place a link is followed) and every designated entry BELOW it is
+ * lstat-walked (`noFollowEntry`): the manifest dir, `plugin.json`, each catalog, each root file,
+ * each bundle directory and everything inside it. A symlink among them is refused by name
+ * (`PluginSourceSymlinkError`) — a seed refuses to start (the runtime's `skills.config`), a
+ * refresh answers a `blocked` envelope — and nothing is copied: a linked catalog or a linked skill
+ * dir would otherwise copy bytes from outside the declared source into the daemon's root and hand
+ * them to every worker.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readdirSync, readlinkSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+import { PLUGIN_NAME } from './frontmatter.js';
+import { readFileNoFollow } from './tree.js';
+/** Explicit plugin-source override — the seam tests and proof scripts aim at a fixture plugin. */
+export const SKILLS_SOURCE_ENV = 'WICKED_CREW_SKILLS_SOURCE';
+/** Relative path of the Claude Code plugin manifest inside a plugin root. */
+export const PLUGIN_MANIFEST_REL = join('.claude-plugin', 'plugin.json');
+/** The Claude Code config dir the plugin cache lives under: `CLAUDE_CONFIG_DIR`, else `~/.claude`. */
+export function claudeConfigDir(env = process.env, home = homedir()) {
+    const configured = env['CLAUDE_CONFIG_DIR'];
+    return configured !== undefined && configured !== '' ? configured : join(home, '.claude');
+}
+/**
+ * A designated entry of the plugin source is a symlink — the seed/refresh is refused by name and
+ * nothing is copied (module header). `entry` is the plugin-relative POSIX path of the link.
+ */
+export class PluginSourceSymlinkError extends Error {
+    root;
+    entry;
+    target;
+    constructor(root, entry, target) {
+        super(`plugin source ${root}: ${entry} is a symlink (-> ${target}) — the plugin source is copied into the daemon's skills root and ` +
+            'handed to every worker, so a link among its designated files or directories would copy whatever it reaches; ' +
+            'refused, nothing was copied (the source root itself may be reached through a link; its contents may not)');
+        this.root = root;
+        this.entry = entry;
+        this.target = target;
+        this.name = 'PluginSourceSymlinkError';
+    }
+}
+/**
+ * The plugin root with every link resolved — the ONE place a link is followed (an operator's
+ * symlinked config dir reaches the root). `null` when it does not exist or is not a directory.
+ */
+export function realPluginRoot(dir) {
+    let real;
+    try {
+        real = realpathSync(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT' || err.code === 'ENOTDIR')
+            return null;
+        throw err;
+    }
+    return lstatSync(real).isDirectory() ? real : null;
+}
+/**
+ * `join(root, ...segments)` after lstat-walking every segment BELOW the canonical root: a symlink at
+ * any of them throws `PluginSourceSymlinkError` naming it; a component that does not exist (or sits
+ * below a regular file) answers `null`. `sourceSpelling` is the root as the operator spelled it, for
+ * the error.
+ */
+export function noFollowEntry(root, segments, sourceSpelling = root) {
+    let cur = root;
+    for (let i = 0; i < segments.length; i += 1) {
+        cur = join(cur, segments[i]);
+        let st;
+        try {
+            st = lstatSync(cur);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return null;
+            throw err;
+        }
+        if (st.isSymbolicLink())
+            throw new PluginSourceSymlinkError(sourceSpelling, segments.slice(0, i + 1).join('/'), readlinkSync(cur));
+    }
+    return cur;
+}
+/**
+ * The plugin manifest's `version` at `dir`, or `null` when `dir` is not a plugin root. The manifest
+ * is read NO-FOLLOW below the (once-resolved) root: a symlinked `.claude-plugin/` or `plugin.json`
+ * throws `PluginSourceSymlinkError` — never a version read through a link (codex round 6).
+ */
+export function pluginVersionAt(dir) {
+    const root = realPluginRoot(dir);
+    if (root === null)
+        return null;
+    const manifest = noFollowEntry(root, PLUGIN_MANIFEST_REL.split(sep), dir);
+    if (manifest === null || !lstatSync(manifest).isFile())
+        return null;
+    const parsed = JSON.parse(readFileNoFollow(manifest).toString('utf8')); // the entry the walk judged is the one read (v3.5 §3)
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const version = parsed.version;
+    return typeof version === 'string' && version !== '' ? version : null;
+}
+/**
+ * A TOTAL order over version strings, so "highest version wins" never depends on `readdir` order
+ * (Copilot on #480). Numeric dotted order first (`12.9.0` < `12.32.0`; a shorter release sorts
+ * before a longer one with the same prefix; a non-integer segment sorts below any integer). A
+ * prerelease suffix (`12.0.0-beta`, everything after the first `-`) sorts BELOW its release
+ * (`12.0.0-beta` < `12.0.0`), and two prereleases compare identifier by identifier the semver way
+ * (numeric identifiers numerically and before alphanumeric ones, then lexically, shorter first).
+ * Distinct strings NEVER compare equal: whatever survives all of that (`12.00.0` vs `12.0.0`) is
+ * ordered lexically.
+ */
+export function compareVersions(a, b) {
+    if (a === b)
+        return 0;
+    const [coreA, preA] = splitPrerelease(a);
+    const [coreB, preB] = splitPrerelease(b);
+    const core = compareDotted(coreA, coreB);
+    if (core !== 0)
+        return core;
+    if (preA === null && preB !== null)
+        return 1;
+    if (preA !== null && preB === null)
+        return -1;
+    if (preA !== null && preB !== null) {
+        const pre = comparePrerelease(preA, preB);
+        if (pre !== 0)
+            return pre;
+    }
+    return a < b ? -1 : 1;
+}
+/** `12.0.0-beta.1` → [`12.0.0`, `beta.1`]; no `-` → [`v`, null]. */
+function splitPrerelease(v) {
+    const dash = v.indexOf('-');
+    return dash === -1 ? [v, null] : [v.slice(0, dash), v.slice(dash + 1)];
+}
+/** Dotted numeric segments: shorter-first on a shared prefix, a non-integer segment below any integer. */
+function compareDotted(a, b) {
+    const pa = a.split('.');
+    const pb = b.split('.');
+    const n = Math.max(pa.length, pb.length);
+    for (let i = 0; i < n; i += 1) {
+        const sa = pa[i];
+        const sb = pb[i];
+        if (sa === undefined)
+            return -1;
+        if (sb === undefined)
+            return 1;
+        const na = /^\d+$/.test(sa) ? Number(sa) : -1;
+        const nb = /^\d+$/.test(sb) ? Number(sb) : -1;
+        if (na !== nb)
+            return na < nb ? -1 : 1;
+    }
+    return 0;
+}
+/** Semver prerelease identifiers: numeric before alphanumeric, numeric numerically, else lexically; shorter first. */
+function comparePrerelease(a, b) {
+    const pa = a.split('.');
+    const pb = b.split('.');
+    const n = Math.max(pa.length, pb.length);
+    for (let i = 0; i < n; i += 1) {
+        const sa = pa[i];
+        const sb = pb[i];
+        if (sa === undefined)
+            return -1;
+        if (sb === undefined)
+            return 1;
+        const numA = /^\d+$/.test(sa);
+        const numB = /^\d+$/.test(sb);
+        if (numA && numB) {
+            if (Number(sa) !== Number(sb))
+                return Number(sa) < Number(sb) ? -1 : 1;
+            continue;
+        }
+        if (numA !== numB)
+            return numA ? -1 : 1;
+        if (sa !== sb)
+            return sa < sb ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Classify a plugin root: a git checkout when it carries `.git`; the installed plugin when it
+ * sits under a `plugins/` directory (the marketplace cache or the hand-installed copy); anything
+ * else is an explicit plugin-shaped directory (an unpacked tarball, a test fixture).
+ */
+export function classifySource(dir) {
+    if (existsSync(join(dir, '.git')))
+        return 'checkout';
+    if (dir.split(sep).includes('plugins'))
+        return 'claude-plugin-cache';
+    return 'directory';
+}
+/** A `PluginSource` for an explicit plugin root, or `null` when it is not a plugin root. */
+export function pluginSourceAt(dir) {
+    const version = pluginVersionAt(dir);
+    return version === null ? null : { path: dir, kind: classifySource(dir), plugin_version: version };
+}
+/** The marketplace cache dir the live plugin versions live under, for a config dir. */
+export function livePluginCacheDir(configDir) {
+    return join(configDir, 'plugins', 'cache', PLUGIN_NAME, PLUGIN_NAME);
+}
+/**
+ * Discover the live installed plugin: the explicit `WICKED_CREW_SKILLS_SOURCE` override, else the
+ * highest version in the marketplace cache. NOTHING else — in particular not the hand-installed
+ * `plugins/wicked-garden` copy (see the module header). `env`/`home` are injectable so tests never
+ * read the developer's real config dir. Returns `null` when nothing is installed — the caller says
+ * "install garden first" loudly.
+ */
+export function discoverLivePlugin(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? homedir();
+    const override = env[SKILLS_SOURCE_ENV];
+    if (override !== undefined && override !== '')
+        return pluginSourceAt(override);
+    const cache = livePluginCacheDir(claudeConfigDir(env, home));
+    if (!existsSync(cache))
+        return null;
+    const versions = readdirSync(cache)
+        .filter((entry) => pluginVersionAt(join(cache, entry)) !== null)
+        .sort(compareVersions);
+    const top = versions[versions.length - 1];
+    if (top === undefined)
+        return null;
+    const dir = join(cache, top);
+    return { path: dir, kind: 'claude-plugin-cache', plugin_version: pluginVersionAt(dir) ?? top };
+}
+const GIT_TIMEOUT_MS = 5_000;
+/** The checkout's HEAD sha + dirty flag; `{null,false}` for a non-checkout source. */
+export function gitStateOf(source) {
+    if (source.kind !== 'checkout')
+        return { git_sha: null, git_dirty: false };
+    try {
+        const sha = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: source.path,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const status = execFileSync('git', ['status', '--porcelain'], {
+            cwd: source.path,
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return { git_sha: sha, git_dirty: status.trim() !== '' };
+    }
+    catch (err) {
+        return {
+            git_sha: null,
+            git_dirty: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=plugin-source.js.map