opensip-cli 0.1.6 → 0.1.8

package/dist/bootstrap/phase-map.js

@@ -0,0 +1,108 @@
+/**
+ * Single orchestration vocabulary: maps lifecycle steps, pre-action phases, and
+ * the implementing modules. Replaces parallel taxonomies in tool-lifecycle.ts
+ * and pre-action-bootstrap-phases.ts as the one source of truth.
+ */
+import { PRE_ACTION_PHASES } from './pre-action-bootstrap-phases.js';
+import { TOOL_LIFECYCLE_STEPS } from './tool-lifecycle.js';
+/**
+ * Canonical phase map. Startup steps 1–4 live in `bootstrapCli`; step 8 in
+ * `mountAllToolCommands`; steps 5–7 and 9 in the pre-action executor.
+ */
+export const BOOTSTRAP_PHASE_MAP = [
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.discover,
+        module: 'bootstrap/index.ts',
+        symbol: 'bootstrapCli → registerFirstPartyTools / discoverAndRegisterToolPackages',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.compat,
+        module: 'bootstrap/admit-tool-package.ts',
+        symbol: 'admitToolPackage',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.trust,
+        module: 'bootstrap/register-tools-discovery.ts',
+        symbol: 'admitProjectLocalTool',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.import,
+        module: 'bootstrap/validate-tool.ts',
+        symbol: 'isValidTool + ToolRegistry.register',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.config,
+        preActionPhase: PRE_ACTION_PHASES.buildScope,
+        module: 'bootstrap/config-and-capabilities.ts',
+        symbol: 'composeAndValidateToolConfig',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.scope,
+        preActionPhase: PRE_ACTION_PHASES.buildScope,
+        module: 'bootstrap/build-per-run-scope.ts',
+        symbol: 'buildPerRunScope → resolveToolHooks().contributeScope',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.capabilities,
+        preActionPhase: PRE_ACTION_PHASES.toolPreflight,
+        module: 'bootstrap/config-and-capabilities.ts',
+        symbol: 'wireCapabilityRegistry + loadOwningToolCapabilities',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.mount,
+        module: 'bootstrap/register-tools-mount.ts',
+        symbol: 'mountAllToolCommands (composition root)',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.initialize,
+        preActionPhase: PRE_ACTION_PHASES.toolPreflight,
+        module: 'bootstrap/owning-tool-init.ts',
+        symbol: 'maybeInitializeOwningTool',
+    },
+    {
+        lifecycleStep: TOOL_LIFECYCLE_STEPS.dispatch,
+        module: 'commands/mount-command-spec.ts',
+        symbol: 'mountCommandSpec action',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.readCommandOptions,
+        module: 'bootstrap/plan-pre-action-bootstrap.ts',
+        symbol: 'planPreActionBootstrap',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.mergeCliDefaults,
+        module: 'bootstrap/plan-pre-action-bootstrap.ts',
+        symbol: 'planPreActionBootstrap → mergeCliDefaults',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.resolveProject,
+        module: 'bootstrap/plan-pre-action-bootstrap.ts',
+        symbol: 'planPreActionBootstrap → resolveProjectContext',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.bailoutWindow,
+        module: 'bootstrap/pre-action-guards.ts',
+        symbol: 'pre-action guards',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.projectSideEffects,
+        module: 'bootstrap/execute-post-bailout-bootstrap.ts',
+        symbol: 'executePostBailoutBootstrap → projectSideEffects',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.enterScope,
+        module: 'bootstrap/execute-post-bailout-bootstrap.ts',
+        symbol: 'enterScope',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.hostStartEffects,
+        module: 'bootstrap/execute-post-bailout-bootstrap.ts',
+        symbol: 'executePostBailoutBootstrap → hostStartEffects',
+    },
+    {
+        preActionPhase: PRE_ACTION_PHASES.dispose,
+        module: 'bootstrap/pre-action-hook.ts',
+        symbol: 'disposeCurrentScope',
+    },
+];
+//# sourceMappingURL=phase-map.js.map

package/dist/bootstrap/phase-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-map.js","sourceRoot":"","sources":["../../src/bootstrap/phase-map.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAU3D;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA6B;IAC3D;QACE,aAAa,EAAE,oBAAoB,CAAC,QAAQ;QAC5C,MAAM,EAAE,oBAAoB;QAC5B,MAAM,EAAE,0EAA0E;KACnF;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,MAAM;QAC1C,MAAM,EAAE,iCAAiC;QACzC,MAAM,EAAE,kBAAkB;KAC3B;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,KAAK;QACzC,MAAM,EAAE,uCAAuC;QAC/C,MAAM,EAAE,uBAAuB;KAChC;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,MAAM;QAC1C,MAAM,EAAE,4BAA4B;QACpC,MAAM,EAAE,qCAAqC;KAC9C;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,MAAM;QAC1C,cAAc,EAAE,iBAAiB,CAAC,UAAU;QAC5C,MAAM,EAAE,sCAAsC;QAC9C,MAAM,EAAE,8BAA8B;KACvC;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,KAAK;QACzC,cAAc,EAAE,iBAAiB,CAAC,UAAU;QAC5C,MAAM,EAAE,kCAAkC;QAC1C,MAAM,EAAE,uDAAuD;KAChE;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,YAAY;QAChD,cAAc,EAAE,iBAAiB,CAAC,aAAa;QAC/C,MAAM,EAAE,sCAAsC;QAC9C,MAAM,EAAE,qDAAqD;KAC9D;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,KAAK;QACzC,MAAM,EAAE,mCAAmC;QAC3C,MAAM,EAAE,yCAAyC;KAClD;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,UAAU;QAC9C,cAAc,EAAE,iBAAiB,CAAC,aAAa;QAC/C,MAAM,EAAE,+BAA+B;QACvC,MAAM,EAAE,2BAA2B;KACpC;IACD;QACE,aAAa,EAAE,oBAAoB,CAAC,QAAQ;QAC5C,MAAM,EAAE,gCAAgC;QACxC,MAAM,EAAE,yBAAyB;KAClC;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,kBAAkB;QACpD,MAAM,EAAE,wCAAwC;QAChD,MAAM,EAAE,wBAAwB;KACjC;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,gBAAgB;QAClD,MAAM,EAAE,wCAAwC;QAChD,MAAM,EAAE,2CAA2C;KACpD;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,cAAc;QAChD,MAAM,EAAE,wCAAwC;QAChD,MAAM,EAAE,gDAAgD;KACzD;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,aAAa;QAC/C,MAAM,EAAE,gCAAgC;QACxC,MAAM,EAAE,mBAAmB;KAC5B;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,kBAAkB;QACpD,MAAM,EAAE,6CAA6C;QACrD,MAAM,EAAE,kDAAkD;KAC3D;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,UAAU;QAC5C,MAAM,EAAE,6CAA6C;QACrD,MAAM,EAAE,YAAY;KACrB;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,gBAAgB;QAClD,MAAM,EAAE,6CAA6C;QACrD,MAAM,EAAE,gDAAgD;KACzD;IACD;QACE,cAAc,EAAE,iBAAiB,CAAC,OAAO;QACzC,MAAM,EAAE,8BAA8B;QACtC,MAAM,EAAE,qBAAqB;KAC9B;CACO,CAAC"}

package/dist/bootstrap/pre-action-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pre-action-hook.d.ts","sourceRoot":"","sources":["../../src/bootstrap/pre-action-hook.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,aAAa,EAAE,iBAAiB,GAC/B,IAAI,CAkCN;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAS1C"}
+{"version":3,"file":"pre-action-hook.d.ts","sourceRoot":"","sources":["../../src/bootstrap/pre-action-hook.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAWH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,aAAa,EAAE,iBAAiB,GAC/B,IAAI,CA6CN;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAiB1C"}

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

@@ -6,14 +6,27 @@
  * {@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 { setResolvedCommandLabel } from '../telemetry/command-label.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');
+        // M12: stamp the RESOLVED command name for the duration metric's label
+        // (bounded cardinality) before any bootstrap that might throw — set as early
+        // as the matched command is known.
+        setResolvedCommandLabel(actionCommand.name());
+        // 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 +62,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;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExE,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,uEAAuE;QACvE,6EAA6E;QAC7E,mCAAmC;QACnC,uBAAuB,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9C,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,43 @@
+/**
+ * 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.
+ */
+/** Stderr + structured log when an installed tool is skipped by the trust gate. */
+export declare function emitInstalledTrustDenied(toolId: string, packageName: string, packageDir: string): void;
+export declare function emitInstalledLoadFailure(name: string, load: Extract<ToolRuntimeLoad, {
+    ok: false;
+}>): void;
 export interface DiscoveryOptions {
     /**
      * Ordered tool-discovery sources (precedence: first wins on duplicate
@@ -7,6 +46,8 @@ export interface DiscoveryOptions {
      * and stays unit-testable with explicit anchors.
      */
     readonly sources: readonly ToolDiscoverySource[];
+    /** Injectable env for installed-tool trust (bootstrap-time; defaults to `process.env`). */
+    readonly env?: NodeJS.ProcessEnv;
 }
 /**
  * Build the ordered tool-discovery sources. Order is precedence
@@ -23,69 +64,11 @@ export interface DiscoveryOptions {
  * source.
  */
 export declare function buildToolDiscoverySources(cwd: string, cliInstallDir: string): ToolDiscoverySource[];
-/**
- * Discover and register third-party tool packages from npm — any
- * `package.json` declaring `opensipTools.kind === 'tool'`. Built-in
- * ids are skipped to avoid double-registration warnings. Discovery spans
- * the supplied sources (the user-global tool host dir, the project tree +
- * its `.runtime` tool host dir, and the CLI install dir — see
- * {@link buildToolDiscoverySources}).
- *
- * Each discovered package runs through the SAME `admitTool` gate the
- * bundled path uses (launch, Phase 3) BEFORE its module is imported:
- * the static `package.json#opensipTools` manifest is read with source
- * `'installed'`, the compatibility gate runs, and only an `admit` verdict
- * proceeds to import + register. An installed tool is best-effort
- * `explicitlyRequested: false`, so an incompatible one `skip`s (logged)
- * rather than failing the whole CLI — a stray incompatible plugin must not
- * take fit/graph/sim down. Admitted tools' `ToolProvenance` is pushed onto
- * the optional `provenance` collector for Phase 4's `plugin list`.
- *
- * @param provenance Optional sink for admitted tools' provenance records.
- */
 export declare function discoverAndRegisterToolPackages(registry: ToolRegistry, opts: DiscoveryOptions, builtInIds: ReadonlySet<string>, provenance?: ToolProvenance[], manifests?: ToolPluginManifest[]): Promise<void>;
 /**
  * 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,mFAAmF;AACnF,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,IAAI,CAaN;AAED,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;IACjD,2FAA2F;IAC3F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CAqBvB;AA2DD,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,CAmCf;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,135 @@
 // @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 { isInstalledToolTrusted, 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.
+ */
+/** Stderr + structured log when an installed tool is skipped by the trust gate. */
+export function emitInstalledTrustDenied(toolId, packageName, packageDir) {
+    process.stderr.write(`opensip: installed tool ${packageName} (${toolId}) is not trusted to load (deny-by-default). ` +
+        `Allowlist it via OPENSIP_CLI_ALLOW_INSTALLED_TOOLS='${toolId}' to admit it ` +
+        `(or OPENSIP_CLI_ALLOW_INSTALLED_TOOLS='*' for all). See opensip.ai/docs/opensip-cli/70-reference/10-environment-variables/\n`);
+    logger.warn({
+        evt: 'cli.tool.installed_trust_denied',
+        module: BOOTSTRAP_MODULE,
+        toolId,
+        packageName,
+        packageDir,
+    });
+}
+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):
@@ -57,45 +183,52 @@ export function buildToolDiscoverySources(cwd, cliInstallDir) {
  *
  * @param provenance Optional sink for admitted tools' provenance records.
  */
+async function registerDiscoveredInstalledPackage(pkg, args) {
+    const admission = admitInstalledTool(pkg, args.builtInIds);
+    if (admission === undefined)
+        return;
+    if (!isInstalledToolTrusted(admission.manifest.id, args.env)) {
+        emitInstalledTrustDenied(admission.manifest.id, pkg.name, pkg.packageDir);
+        return;
+    }
+    const load = await importToolRuntime(pkg.packageDir, hostRuntimeImportPolicyFor('installed'));
+    if (!load.ok) {
+        emitInstalledLoadFailure(pkg.name, load);
+        return;
+    }
+    if (args.builtInIds.has(load.tool.metadata.name ?? load.tool.metadata.id))
+        return;
+    // Stable-UUID collision (ADR-0048): skip a re-discovered copy of an already-
+    // registered tool (see discoverAndRegisterToolPackages JSDoc).
+    if (args.registeredStableIds.has(load.tool.metadata.id))
+        return;
+    assertManifestMatchesTool(admission.manifest, load.tool);
+    // @fitness-ignore-next-line detached-promises -- ToolRegistry.register(...) returns void (registry.ts:46); the detached-promise heuristic misfires on the discarded non-promise call result.
+    args.registry.register(load.tool, { sourcePackage: pkg.name });
+    args.provenance.push(admission.provenance);
+    args.manifests.push(admission.manifest);
+}
 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));
+    const env = opts.env ?? process.env;
     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.
-            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);
+            await registerDiscoveredInstalledPackage(pkg, {
+                registry,
+                builtInIds,
+                env,
+                registeredStableIds,
+                provenance,
+                manifests,
+            });
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -112,48 +245,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 +260,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 +271,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 +282,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);