opensip-cli 0.1.6 → 0.1.7

package/dist/bootstrap/pre-action-hook.js

@@ -6,14 +6,22 @@
  * {@link executePostBailoutBootstrap} (phases 5–9). This module wires those
  * to Commander's preAction/postAction hooks.
  */
-import { currentScope, generatePrefixedId } from '@opensip-cli/core';
+import { currentScope, exitScope, generatePrefixedId } from '@opensip-cli/core';
 import { commandPath } from '../commands/command-scope-index.js';
+import { hostEnv } from '../env/host-env-specs.js';
 import { executePostBailoutBootstrap } from './execute-post-bailout-bootstrap.js';
 import { planPreActionBootstrap } from './plan-pre-action-bootstrap.js';
 export { resolveOwningTool } from './owning-tool-init.js';
 export function installPreActionHook(program, version, runtime, commandScopes) {
     program.hook('preAction', async (_thisCommand, actionCommand) => {
-        const runId = generatePrefixedId('run');
+        // B1 ("Child runId behavior"): resolve `runId` env-FIRST. A forked/spawned
+        // child re-enters this hook and inherits its parent's run via `OPENSIP_RUN_ID`
+        // (set in the child env by `correlationToEnv`); a top-level invocation, with
+        // no `OPENSIP_RUN_ID` set, mints a fresh id. This is the single inheritance
+        // seam — the spec JSON deliberately never carries `runId`, because the logger
+        // that stamps every worker line is already live before the spec is parsed.
+        const inherited = hostEnv.get('OPENSIP_RUN_ID');
+        const runId = inherited && inherited.length > 0 ? inherited : generatePrefixedId('run');
         const opts = actionCommand.opts();
         const cwd = opts.cwd ?? process.cwd();
         const cwdExplicit = actionCommand.getOptionValueSource('cwd') === 'cli';
@@ -49,5 +57,14 @@ export function disposeCurrentScope() {
     catch {
         // @swallow-ok dispose errors on shutdown; the run has already produced its outcome.
     }
+    finally {
+        // Complete the per-command lifecycle: clear the ambient ALS slot so a
+        // subsequent command in the same process (a long-lived host driving
+        // Commander sequentially) starts with a clean slot and its `enterScope`
+        // does not trip the always-on re-entrancy guard against this finished run.
+        // Production runs one command per process, so this is normally the final
+        // teardown; it is a no-op when no scope is current.
+        exitScope();
+    }
 }
 //# sourceMappingURL=pre-action-hook.js.map

package/dist/bootstrap/pre-action-hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"pre-action-hook.js","sourceRoot":"","sources":["../../src/bootstrap/pre-action-hook.ts"],"names":[],"mappings":"AAAA,qOAAqO;AACrO;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAMxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,MAAM,UAAU,oBAAoB,CAClC,OAAgB,EAChB,OAAe,EACf,OAAyB,EACzB,aAAgC;IAEhC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,EAAE;QAC9D,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,GAAG,GAAI,IAAI,CAAC,GAAc,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAClD,MAAM,WAAW,GAAG,aAAa,CAAC,oBAAoB,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;QAExE,MAAM,IAAI,GAAG,sBAAsB,CAAC;YAClC,IAAI,EAAE,IAAI;YACV,GAAG;YACH,WAAW;YACX,KAAK;YACL,WAAW,EAAE,aAAa,CAAC,IAAI,EAAE;YACjC,WAAW,EAAE,WAAW,CAAC,aAAa,CAAC;YACvC,aAAa;YACb,kBAAkB,EAAE,IAAI,CAAC,MAA4B;SACtD,CAAC,CAAC;QAEH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,2BAA2B,CAAC;YAClD,IAAI;YACJ,OAAO;YACP,OAAO;YACP,iIAAiI;YACjI,OAAO,EAAE,aAAa,CAAC,eAAe,EAAE,CAAC,KAAK,KAAK,KAAK;YACxD,MAAM,EAAE,IAAI,CAAC,MAA4B;SAC1C,CAAC,CAAC;QACH,KAAK,CAAC,WAAW,CAAC,KAAK,CACrB,MAAM,EACN,OAAO,EACP,sCAAsC,aAAa,CAAC,IAAI,EAAE,GAAG,CAC9D,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,YAAY,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACzC,CAAC,CAAC,OAAO,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oFAAoF;IACtF,CAAC;AACH,CAAC"}
+{"version":3,"file":"pre-action-hook.js","sourceRoot":"","sources":["../../src/bootstrap/pre-action-hook.ts"],"names":[],"mappings":"AAAA,qOAAqO;AACrO;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAEnD,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAMxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,MAAM,UAAU,oBAAoB,CAClC,OAAgB,EAChB,OAAe,EACf,OAAyB,EACzB,aAAgC;IAEhC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,EAAE;QAC9D,2EAA2E;QAC3E,+EAA+E;QAC/E,6EAA6E;QAC7E,4EAA4E;QAC5E,8EAA8E;QAC9E,2EAA2E;QAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAS,gBAAgB,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACxF,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,GAAG,GAAI,IAAI,CAAC,GAAc,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAClD,MAAM,WAAW,GAAG,aAAa,CAAC,oBAAoB,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;QAExE,MAAM,IAAI,GAAG,sBAAsB,CAAC;YAClC,IAAI,EAAE,IAAI;YACV,GAAG;YACH,WAAW;YACX,KAAK;YACL,WAAW,EAAE,aAAa,CAAC,IAAI,EAAE;YACjC,WAAW,EAAE,WAAW,CAAC,aAAa,CAAC;YACvC,aAAa;YACb,kBAAkB,EAAE,IAAI,CAAC,MAA4B;SACtD,CAAC,CAAC;QAEH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,2BAA2B,CAAC;YAClD,IAAI;YACJ,OAAO;YACP,OAAO;YACP,iIAAiI;YACjI,OAAO,EAAE,aAAa,CAAC,eAAe,EAAE,CAAC,KAAK,KAAK,KAAK;YACxD,MAAM,EAAE,IAAI,CAAC,MAA4B;SAC1C,CAAC,CAAC;QACH,KAAK,CAAC,WAAW,CAAC,KAAK,CACrB,MAAM,EACN,OAAO,EACP,sCAAsC,aAAa,CAAC,IAAI,EAAE,GAAG,CAC9D,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,YAAY,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACzC,CAAC,CAAC,OAAO,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oFAAoF;IACtF,CAAC;YAAS,CAAC;QACT,sEAAsE;QACtE,oEAAoE;QACpE,wEAAwE;QACxE,2EAA2E;QAC3E,yEAAyE;QACzE,oDAAoD;QACpD,SAAS,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/bootstrap/register-tools-discovery.d.ts

@@ -1,4 +1,41 @@
+/**
+ * register-tools-discovery — installed + authored tool admission and discovery.
+ *
+ * Extracted from register-tools.ts so the bundled registration path stays a
+ * focused module under the file-length soft limit.
+ */
 import { type ToolPluginManifest, type ToolProvenance, type ToolRegistry, type ToolDiscoverySource } from '@opensip-cli/core';
+import { type ToolRuntimeLoad } from './admit-tool-package.js';
+import type { ToolAdmission } from './tool-admission-types.js';
+export type AuthoredAdmission = ToolAdmission;
+/**
+ * Admit or reject a PROJECT-LOCAL authored tool under the deny-by-default trust
+ * policy. The trust decision always precedes module import; a non-allowlisted
+ * tool fails closed before any authored code can run.
+ *
+ * @throws {PluginIncompatibleError} When the sidecar manifest is missing,
+ * malformed, incompatible, or not trusted by the project-tool allowlist.
+ */
+export declare function admitProjectLocalTool(args: {
+    readonly dir: string;
+    readonly env?: NodeJS.ProcessEnv;
+}): AuthoredAdmission;
+/**
+ * Admit a USER-GLOBAL authored tool — trusted-by-default because the user placed
+ * it in their own home-dir tool host, but still fail-closed on a missing or
+ * incompatible manifest.
+ */
+export declare function admitUserGlobalTool(args: {
+    readonly dir: string;
+}): AuthoredAdmission;
+/**
+ * Emit the best-effort stderr line + structured warning for a discovered
+ * INSTALLED tool whose runtime failed to load. Each failure reason maps to its
+ * own diagnostic while preserving the installed leg's skip-not-crash posture.
+ */
+export declare function emitInstalledLoadFailure(name: string, load: Extract<ToolRuntimeLoad, {
+    ok: false;
+}>): void;
 export interface DiscoveryOptions {
     /**
      * Ordered tool-discovery sources (precedence: first wins on duplicate
@@ -47,45 +84,7 @@ export declare function discoverAndRegisterToolPackages(registry: ToolRegistry,
 /**
  * Discover + admit + register AUTHORED Tool sidecars from the two authored
  * roots, then dynamic-import each admitted runtime through the shared
- * `importToolRuntime` seam — the same admit → import → register path the
- * bundled and installed legs travel (ADR-0027; this is the leg that makes the
- * dormant {@link admitProjectLocalTool} live).
- *
- * Two roots, two trust postures:
- *   - **global** (`~/.opensip-cli/tools/`) → {@link admitUserGlobalTool},
- *     trusted-by-default.
- *   - **project** (`<project>/opensip-cli/tools/`) → {@link admitProjectLocalTool},
- *     deny-by-default (allowlist via `OPENSIP_CLI_ALLOW_PROJECT_TOOLS`).
- *
- * Global is processed FIRST so a project-authored tool cannot shadow a same-id
- * global one — matching the `~/.opensip-cli/plugins` precedence note in
- * {@link buildToolDiscoverySources} (first-writer-wins via the registry).
- * `builtInIds` are skipped so an authored tool never shadows a bundled one.
- *
- * **Trust-before-import.** For each candidate, the admit step (which EMBEDS the
- * trust decision — deny-by-default inside `admitProjectLocalTool`) runs to
- * completion BEFORE `importToolRuntime`. A non-allowlisted project tool THROWS
- * `PluginIncompatibleError` (exit 5) here, propagated out of the walk: it must
- * fail the run loudly — that is the clone-protection contract.
- *
- * **Error-posture asymmetry (deliberate).** An un-allowlisted *project* tool is
- * fail-closed by policy (clone-risk; the user must opt in). A *global* tool that
- * fails to load is also fail-closed (the user explicitly authored it into
- * `$HOME`). This differs from the *installed* npm leg, where a stray bad plugin
- * skips-with-diagnostic so it can't take fit/graph/sim down — authored tools are
- * first-party-intent, installed tools are ambient.
- *
- * @param registry The per-invocation tool registry to populate.
- * @param opts.projectAuthoredDir `resolveProjectPaths(root).authoredToolsDir`,
- *   or `undefined` when there is no resolvable project context.
- * @param opts.globalAuthoredDir `resolveUserPaths().authoredToolsDir`.
- * @param opts.env Environment carrying the project allowlist (default
- *   `process.env`); injectable for tests.
- * @param builtInIds Bundled-tool ids to skip on a name collision.
- * @param provenance Sink for admitted authored tools' provenance records.
- * @param manifests Sink for admitted authored tools' manifests (§5.3).
- * @throws {PluginIncompatibleError} for an un-allowlisted project tool, or any
- *   authored tool whose sidecar/runtime is missing/incompatible (fail-closed).
+ * `importToolRuntime` seam.
  */
 export declare function discoverAndRegisterAuthoredTools(registry: ToolRegistry, opts: {
     readonly projectAuthoredDir?: string;

package/dist/bootstrap/register-tools-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-tools-discovery.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-discovery.ts"],"names":[],"mappings":"AACA,OAAO,EASL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAW3B,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CAqBvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,GACnC,OAAO,CAAC,IAAI,CAAC,CAoDf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,EACD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,GACnC,OAAO,CAAC,IAAI,CAAC,CA0Bf"}
+{"version":3,"file":"register-tools-discovery.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-discovery.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAYL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAEzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAsC9C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,GAAG,iBAAiB,CAgBpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAErF;AAoCD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,GAC5C,IAAI,CA0BN;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CAqBvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,GACnC,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;;;GAIG;AACH,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,EACD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,GACnC,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/bootstrap/register-tools-discovery.js

@@ -1,9 +1,122 @@
 // @fitness-ignore-file performance-anti-patterns -- sequential await across discovered tool packages preserves load order for plugin-conflict detection; bounded by installed plugin count
-import { assertManifestMatchesTool, discoverAuthoredToolSidecars, discoverToolPackagesFromAnchors, logger, PluginIncompatibleError, resolveProjectContext, resolveProjectPaths, resolveUserPaths, } from '@opensip-cli/core';
-import { hostRuntimeImportPolicyFor, importToolRuntime } from './admit-tool-package.js';
-import { admitProjectLocalTool, admitUserGlobalTool, } from './authored-tool-admission.js';
-import { admitInstalledTool, emitInstalledLoadFailure } from './installed-tool-admission.js';
-import { BOOTSTRAP_MODULE } from './register-tools-shared.js';
+/**
+ * register-tools-discovery — installed + authored tool admission and discovery.
+ *
+ * Extracted from register-tools.ts so the bundled registration path stays a
+ * focused module under the file-length soft limit.
+ */
+import { admitTool, assertManifestMatchesTool, discoverAuthoredToolSidecars, discoverToolPackagesFromAnchors, logger, PluginIncompatibleError, PROJECT_LOCAL_MANIFEST_FILE, resolveProjectContext, resolveProjectPaths, resolveUserPaths, loadToolManifest, } from '@opensip-cli/core';
+import { hostRuntimeImportPolicyFor, importToolRuntime, } from './admit-tool-package.js';
+import { BOOTSTRAP_MODULE } from './constants.js';
+import { isProjectLocalToolTrusted } from './tool-trust.js';
+/**
+ * The shared admission tail for both authored sources. When `preloadedManifest`
+ * is supplied we use that snapshot so the trust decision and compatibility gate
+ * see the identical declaration.
+ *
+ * @throws {PluginIncompatibleError} When the sidecar manifest is missing,
+ * malformed, or rejected by the compatibility gate.
+ */
+function admitAuthoredTool(source, dir, preloadedManifest) {
+    const rawManifest = preloadedManifest ?? loadToolManifest(source, dir);
+    if (rawManifest === undefined) {
+        throw new PluginIncompatibleError(`${source} tool at '${dir}' has no conformant ${PROJECT_LOCAL_MANIFEST_FILE} sidecar`, { diagnostic: 'manifest missing or malformed' });
+    }
+    const result = admitTool({
+        manifest: rawManifest,
+        source,
+        dir,
+        explicitlyRequested: true,
+    });
+    if (result.decision !== 'admit') {
+        throw new PluginIncompatibleError(`${source} tool '${rawManifest.id}' is incompatible: ${result.diagnostic ?? 'compatibility gate rejected it'}`, { diagnostic: result.diagnostic });
+    }
+    return { provenance: result.provenance, manifest: result.manifest };
+}
+/**
+ * Admit or reject a PROJECT-LOCAL authored tool under the deny-by-default trust
+ * policy. The trust decision always precedes module import; a non-allowlisted
+ * tool fails closed before any authored code can run.
+ *
+ * @throws {PluginIncompatibleError} When the sidecar manifest is missing,
+ * malformed, incompatible, or not trusted by the project-tool allowlist.
+ */
+export function admitProjectLocalTool(args) {
+    const manifest = loadToolManifest('project-local', args.dir);
+    if (manifest === undefined) {
+        throw new PluginIncompatibleError(`project-local tool at '${args.dir}' has no conformant ${PROJECT_LOCAL_MANIFEST_FILE} sidecar`, { diagnostic: 'manifest missing or malformed' });
+    }
+    if (!isProjectLocalToolTrusted(manifest.id, args.env)) {
+        throw new PluginIncompatibleError(`project-local tool '${manifest.id}' is not trusted to load (deny-by-default). ` +
+            `Allowlist it via OPENSIP_CLI_ALLOW_PROJECT_TOOLS='${manifest.id}' to admit it.`, { diagnostic: 'project-local tool not allowlisted (deny-by-default)' });
+    }
+    return admitAuthoredTool('project-local', args.dir, manifest);
+}
+/**
+ * Admit a USER-GLOBAL authored tool — trusted-by-default because the user placed
+ * it in their own home-dir tool host, but still fail-closed on a missing or
+ * incompatible manifest.
+ */
+export function admitUserGlobalTool(args) {
+    return admitAuthoredTool('user-global', args.dir);
+}
+/**
+ * Run the admission gate over a discovered INSTALLED tool package before its
+ * module is imported. Installed tools are best-effort: incompatible or malformed
+ * ambient packages skip with diagnostics rather than crashing unrelated commands.
+ */
+function admitInstalledTool(pkg, builtInIds) {
+    const manifest = loadToolManifest('installed', pkg.packageDir);
+    if (manifest === undefined) {
+        process.stderr.write(`opensip: tool package ${pkg.name} has no conformant package.json#opensipTools manifest — skipping\n`);
+        logger.warn({
+            evt: 'cli.tool.manifest_invalid',
+            module: BOOTSTRAP_MODULE,
+            name: pkg.name,
+        });
+        return undefined;
+    }
+    if (builtInIds.has(manifest.id))
+        return undefined;
+    const result = admitTool({
+        manifest,
+        source: 'installed',
+        dir: pkg.packageDir,
+        packageName: pkg.name,
+        explicitlyRequested: false,
+    });
+    if (result.decision !== 'admit')
+        return undefined;
+    return { provenance: result.provenance, manifest: result.manifest };
+}
+/**
+ * Emit the best-effort stderr line + structured warning for a discovered
+ * INSTALLED tool whose runtime failed to load. Each failure reason maps to its
+ * own diagnostic while preserving the installed leg's skip-not-crash posture.
+ */
+export function emitInstalledLoadFailure(name, load) {
+    if (load.reason === 'no-entry') {
+        process.stderr.write(`opensip: tool package ${name} has no resolvable entry point — skipping\n`);
+        logger.warn({ evt: 'cli.tool.no_entry', module: BOOTSTRAP_MODULE, name });
+        return;
+    }
+    if (load.reason === 'invalid-shape') {
+        process.stderr.write(`opensip: tool package ${name} does not export a valid \`tool\` — skipping\n`);
+        logger.warn({
+            evt: 'cli.tool.invalid_shape',
+            module: BOOTSTRAP_MODULE,
+            name,
+        });
+        return;
+    }
+    process.stderr.write(`opensip: failed to load tool ${name}: ${load.detail ?? 'import failed'}\n`);
+    logger.warn({
+        evt: 'cli.tool.load_failed',
+        module: BOOTSTRAP_MODULE,
+        name,
+        error: load.detail,
+    });
+}
 /**
  * Build the ordered tool-discovery sources. Order is precedence
  * (first-occurrence-wins on duplicate name):
@@ -58,42 +171,33 @@ export function buildToolDiscoverySources(cwd, cliInstallDir) {
  * @param provenance Optional sink for admitted tools' provenance records.
  */
 export async function discoverAndRegisterToolPackages(registry, opts, builtInIds, provenance = [], manifests = []) {
-    // `builtInIds` is the set of already-registered bundled-tool *human ids* (manifest.id)
-    // to skip on a name collision (launch — passed explicitly by the composition root, which
-    // derives it from the bundled MANIFESTS it just loaded; compare against runtime
-    // metadata.name for the human key).
     const discovered = discoverToolPackagesFromAnchors(opts.sources);
+    // Stable-UUID collision guard (ADR-0048): a discovered package whose runtime
+    // `metadata.id` (the stable UUID) is already registered is the SAME tool
+    // re-discovered via a stray anchor — e.g. a second copy of `@opensip-cli/*`
+    // in a node_modules ABOVE the project root. The human-name skip alone misses
+    // it when the two copies disagree on `metadata.name` (e.g. one built before
+    // the verb-rename), which would otherwise double-register and trip the
+    // session-replay duplicate guard. UUID is identity; skip on a UUID match.
+    const registeredStableIds = new Set(registry.list().map((t) => t.metadata.id));
     for (const pkg of discovered) {
         try {
-            // Compatibility gate BEFORE import (launch). `undefined` means the
-            // gate skipped it (or it's a built-in id); an admission means import +
-            // register as before.
             const admission = admitInstalledTool(pkg, builtInIds);
             if (admission === undefined)
                 continue;
-            // Load the runtime through the SHARED dynamic-import path (launch) — the
-            // same `importToolRuntime` the bundled path uses. Resolves the entry
-            // from `packageDir` so a tool living in a host dir off the CLI's own
-            // module-resolution path still loads. An installed tool is best-effort:
-            // any load failure skips-with-diagnostic (it must not take fit/graph/sim
-            // down), in contrast to the bundled path's fail-closed.
             const load = await importToolRuntime(pkg.packageDir, hostRuntimeImportPolicyFor('installed'));
             if (!load.ok) {
                 emitInstalledLoadFailure(pkg.name, load);
                 continue;
             }
-            // builtInIds holds human ids (from bundled manifests); compare against runtime human name
             if (builtInIds.has(load.tool.metadata.name ?? load.tool.metadata.id))
                 continue;
-            // Drift guard — the SAME manifest⇔runtime identity check the bundled and
-            // authored legs run. For an installed tool a mismatch throws into the
-            // surrounding catch (skip-with-diagnostic posture), never crashing the CLI.
+            // Stable-UUID collision (see above): the same tool already registered
+            // under a possibly-different human name. Skip the re-discovered copy.
+            if (registeredStableIds.has(load.tool.metadata.id))
+                continue;
             assertManifestMatchesTool(admission.manifest, load.tool);
             registry.register(load.tool, { sourcePackage: pkg.name });
-            // Record provenance + manifest only now that the tool actually
-            // registered — `plugin list` and the per-run capability registry must
-            // never include a tool whose runtime failed to load (parity with the
-            // bundled/authored legs, which also record after registration).
             provenance.push(admission.provenance);
             manifests.push(admission.manifest);
         }
@@ -112,48 +216,9 @@ export async function discoverAndRegisterToolPackages(registry, opts, builtInIds
 /**
  * Discover + admit + register AUTHORED Tool sidecars from the two authored
  * roots, then dynamic-import each admitted runtime through the shared
- * `importToolRuntime` seam — the same admit → import → register path the
- * bundled and installed legs travel (ADR-0027; this is the leg that makes the
- * dormant {@link admitProjectLocalTool} live).
- *
- * Two roots, two trust postures:
- *   - **global** (`~/.opensip-cli/tools/`) → {@link admitUserGlobalTool},
- *     trusted-by-default.
- *   - **project** (`<project>/opensip-cli/tools/`) → {@link admitProjectLocalTool},
- *     deny-by-default (allowlist via `OPENSIP_CLI_ALLOW_PROJECT_TOOLS`).
- *
- * Global is processed FIRST so a project-authored tool cannot shadow a same-id
- * global one — matching the `~/.opensip-cli/plugins` precedence note in
- * {@link buildToolDiscoverySources} (first-writer-wins via the registry).
- * `builtInIds` are skipped so an authored tool never shadows a bundled one.
- *
- * **Trust-before-import.** For each candidate, the admit step (which EMBEDS the
- * trust decision — deny-by-default inside `admitProjectLocalTool`) runs to
- * completion BEFORE `importToolRuntime`. A non-allowlisted project tool THROWS
- * `PluginIncompatibleError` (exit 5) here, propagated out of the walk: it must
- * fail the run loudly — that is the clone-protection contract.
- *
- * **Error-posture asymmetry (deliberate).** An un-allowlisted *project* tool is
- * fail-closed by policy (clone-risk; the user must opt in). A *global* tool that
- * fails to load is also fail-closed (the user explicitly authored it into
- * `$HOME`). This differs from the *installed* npm leg, where a stray bad plugin
- * skips-with-diagnostic so it can't take fit/graph/sim down — authored tools are
- * first-party-intent, installed tools are ambient.
- *
- * @param registry The per-invocation tool registry to populate.
- * @param opts.projectAuthoredDir `resolveProjectPaths(root).authoredToolsDir`,
- *   or `undefined` when there is no resolvable project context.
- * @param opts.globalAuthoredDir `resolveUserPaths().authoredToolsDir`.
- * @param opts.env Environment carrying the project allowlist (default
- *   `process.env`); injectable for tests.
- * @param builtInIds Bundled-tool ids to skip on a name collision.
- * @param provenance Sink for admitted authored tools' provenance records.
- * @param manifests Sink for admitted authored tools' manifests (§5.3).
- * @throws {PluginIncompatibleError} for an un-allowlisted project tool, or any
- *   authored tool whose sidecar/runtime is missing/incompatible (fail-closed).
+ * `importToolRuntime` seam.
  */
 export async function discoverAndRegisterAuthoredTools(registry, opts, builtInIds, provenance = [], manifests = []) {
-    // Global FIRST (trusted-by-default), then project (deny-by-default).
     for (const candidate of discoverAuthoredToolSidecars(opts.globalAuthoredDir)) {
         await admitAndRegisterAuthored({
             registry,
@@ -166,8 +231,6 @@ export async function discoverAndRegisterAuthoredTools(registry, opts, builtInId
     }
     if (opts.projectAuthoredDir !== undefined) {
         for (const candidate of discoverAuthoredToolSidecars(opts.projectAuthoredDir)) {
-            // admitProjectLocalTool embeds the deny-by-default trust gate; a
-            // non-allowlisted tool THROWS here, BEFORE importToolRuntime below.
             await admitAndRegisterAuthored({
                 registry,
                 admission: admitProjectLocalTool({ dir: candidate.dir, env: opts.env }),
@@ -179,22 +242,10 @@ export async function discoverAndRegisterAuthoredTools(registry, opts, builtInId
         }
     }
 }
-/**
- * Shared register-step for an already-ADMITTED authored tool: skip a
- * built-in-id collision, dynamic-import the runtime (fail-closed on failure —
- * an authored tool is first-party-intent), run the manifest⇔runtime drift
- * guard, register, and record provenance + manifest. Admission (incl. the trust
- * decision) has already happened by the time this is called — so import here
- * never precedes a trust decision.
- *
- * @throws {PluginIncompatibleError} when the authored tool's runtime fails to
- *   load via the plugin path — an authored tool is first-party-intent, so a
- *   load failure is fail-closed (surfaced), never silently skipped.
- */
+/** @throws {PluginIncompatibleError} When the authored tool runtime fails to load. */
 async function admitAndRegisterAuthored(args) {
     const { registry, admission, dir, builtInIds, provenance, manifests } = args;
     const { provenance: prov, manifest } = admission;
-    // Never shadow a bundled tool (defense in depth; the registry also dedupes).
     if (builtInIds.has(prov.id))
         return;
     const load = await importToolRuntime(dir, hostRuntimeImportPolicyFor(prov.source));
@@ -202,8 +253,6 @@ async function admitAndRegisterAuthored(args) {
         const detailSuffix = load.detail ? `: ${load.detail}` : '';
         throw new PluginIncompatibleError(`${prov.source} tool '${prov.id}' failed to load via the plugin path (${load.reason}${detailSuffix})`, { diagnostic: `authored tool runtime load failed: ${load.reason}` });
     }
-    // Drift guard: the static sidecar and the runtime tool are two declarations
-    // of the same identity — catch a sidecar that fell out of sync.
     assertManifestMatchesTool(manifest, load.tool);
     registry.register(load.tool);
     provenance.push(prov);

package/dist/bootstrap/register-tools-discovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"register-tools-discovery.js","sourceRoot":"","sources":["../../src/bootstrap/register-tools-discovery.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"register-tools-discovery.js","sourceRoot":"","sources":["../../src/bootstrap/register-tools-discovery.ts"],"names":[],"mappings":"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"}

package/dist/bootstrap/register-tools-mount.d.ts

@@ -1,5 +1,5 @@
 import { type CliProgram } from '@opensip-cli/contracts';
-import { type ToolCliContext, type ToolRegistry } from '@opensip-cli/core';
+import { type Tool, type ToolCliContext, type ToolRegistry } from '@opensip-cli/core';
 /**
  * Walk the registry and mount each tool's commands onto `program`. This is
  * **step 8** of the tool lifecycle (launch, §5.4) — see
@@ -22,4 +22,21 @@ import { type ToolCliContext, type ToolRegistry } from '@opensip-cli/core';
  * @param ctx The per-invocation handler context (render/emit/scope — no program).
  */
 export declare function mountAllToolCommands(registry: ToolRegistry, program: CliProgram, ctx: ToolCliContext): void;
+/**
+ * Mount ONE tool's commands from its declared `commandSpecs` — the only command
+ * surface (public launch). Extracted so {@link mountAllToolCommands} keeps its
+ * per-tool failure isolation around a single call. A tool with no `commandSpecs`
+ * contributes nothing and is surfaced via `cli.tool.no_command_surface`.
+ *
+ * Nesting (`CommandSpec.parent`, tool-command-surface-taxonomy Task 0.4): a spec
+ * declaring `parent` is mounted as a SUBCOMMAND of the same-tool spec whose name
+ * matches `parent` (the tool's primary verb) — enabling the `<tool> <verb>`
+ * grammar (`graph export`, `fit list`). This is the SAME generic parent+leaf
+ * pattern the host already uses for `sessions`/`plugin`/`tools`
+ * (`host-command-specs.ts:mountHostCommands`): the parent's mounted Commander
+ * command (which also carries its own action) hosts the child via
+ * `mountCommandSpec(primaryCmd, child, ctx)`. No per-tool special case. Specs
+ * with no `parent` mount flat onto the root program exactly as before.
+ */
+export declare function mountOneTool(program: CliProgram, tool: Tool, ctx: ToolCliContext): void;
 //# sourceMappingURL=register-tools-mount.d.ts.map

package/dist/bootstrap/register-tools-mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-tools-mount.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAO9F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CAqBN"}
+{"version":3,"file":"register-tools-mount.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAU,KAAK,IAAI,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAY9F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CA2BN;AAqCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CA4BvF"}