bitfab-cli 0.2.387 → 0.2.388

package/dist/index.js

@@ -24962,7 +24962,7 @@ var semver3 = __toESM(require_semver2(), 1);
 
 // ../bitfab-plugin-lib/dist/bakedSdkVersions.js
 var BAKED_SDK_VERSIONS = {
-  typescript: "0.61.0",
+  typescript: "0.61.1",
   python: "0.61.0",
   ruby: "0.61.0",
   go: "0.61.0"
@@ -31536,7 +31536,7 @@ If the block prints \`ERROR: Bitfab plugin not installed\`, the user hasn't inst
 {{/plugin-dir-lookup}}
 **SDK reference:** https://docs.bitfab.ai is the source of truth for SDK install, initialization, API surface, and replay. Every docs path below ends in \`.md\`: that suffix returns the page as plain markdown (no HTML chrome), so fetch the URLs exactly as written. Fetch in this order before writing any code, do not improvise from memory:
 - **Canonical API surface (preferred for agents):** the dense reference pages at \`/reference/typescript.md\`, \`/reference/python.md\`, \`/reference/ruby.md\`, \`/reference/go.md\`. These list every public export, signature, type, default, and error semantic, no tutorials, no prose. Read these first.
-- **Default to opt-out tracing.** For TypeScript, install and wire the matching \`@bitfab/transform\` build adapter, then use \`withTrace\`/\`trace\` for the workflow root and \`withNode\`/\`node\` only where a discovered call needs naming, typing, capture, finalization, or replay-mocking policy. For Python 3.12+, use \`@client.trace\` and \`@client.node\` the same way. Opt-in \`withSpan\`/\`span\` remains supported, but setup chooses it only when opt-out is technically impossible: Ruby, Go, Python before 3.12, a TypeScript build path for which the documented transform adapters truly cannot be wired, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework handlers, processors, and their generated spans are compatible descendants of an opt-out root and are never by themselves a reason to choose spans. Keep the framework integration and use \`withNode\`/\`node\` for first-party calls that need explicit policy. Existing manual spans in the selected call stack are also not a reason to fall back. Convert that whole call stack to one opt-out surface. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; a helper shared with an opt-in caller requires a disjoint trace boundary or explicit refactor confirmation. Remove redundant span wrappers and replace policy-bearing spans with nodes. Preserve their names, types, capture controls, finalizers, and replay-mocking behavior. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it would require a non-additive rewrite. Never put \`withSpan\` beneath \`withTrace\`. The SDK raises \`MixedTracingError\`. Name all three primitives when fetching a reference page so the fetched guidance cannot collapse back to spans alone.
+- **Default to opt-out tracing.** For TypeScript, wire the matching \`@bitfab/sdk/transform\` build adapter included with the SDK, then use \`withTrace\`/\`trace\` for the workflow root and \`withNode\`/\`node\` only where a discovered call needs naming, typing, capture, finalization, or replay-mocking policy. For Python 3.12+, use \`@client.trace\` and \`@client.node\` the same way. Opt-in \`withSpan\`/\`span\` remains supported, but setup chooses it only when opt-out is technically impossible: Ruby, Go, Python before 3.12, a TypeScript build path for which the documented transform adapters truly cannot be wired, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework handlers, processors, and their generated spans are compatible descendants of an opt-out root and are never by themselves a reason to choose spans. Keep the framework integration and use \`withNode\`/\`node\` for first-party calls that need explicit policy. Existing manual spans in the selected call stack are also not a reason to fall back. Convert that whole call stack to one opt-out surface. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; a helper shared with an opt-in caller requires a disjoint trace boundary or explicit refactor confirmation. Remove redundant span wrappers and replace policy-bearing spans with nodes. Preserve their names, types, capture controls, finalizers, and replay-mocking behavior. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it would require a non-additive rewrite. Never put \`withSpan\` beneath \`withTrace\`. The SDK raises \`MixedTracingError\`. Name all three primitives when fetching a reference page so the fetched guidance cannot collapse back to spans alone.
 - **Cross-SDK shared semantics:** \`/reference/overview.md\` (invariants), \`/reference/span-types.md\` (the \`SpanType\` enum), \`/reference/http.md\` (wire protocol).
 - **Framework integrations (fetch when a framework is detected in step 1 of Instrument):** {{frameworkDocsPaths}}. Each page documents the SDK's native handler/processor/wrapper for that framework, which is usually preferable to hand-wrapping every node/agent call with \`withSpan\`/\`@span\`.
 - **Tutorials / walkthroughs / replay registry module template:** the language-specific documentation pages (\`/typescript-sdk.md\`, \`/python-sdk.md\`, \`/ruby-sdk.md\`, \`/go-sdk.md\`). Use these for the copy-pasteable replay registry module and the replay output contract. During Instrument, fetch the Replay section before Instrument's write-instrumentation step so the replay registry module can be written alongside the instrumentation in the same cycle without re-fetching.
@@ -31798,7 +31798,7 @@ Bitfab provides opt-out tracing and safe replay during development. For TypeScri
 - \`withNode(...)\` / \`node(...)\` to configure a discovered call
 - \`replay(...)\` to run recorded scenarios against current code
 
-Default to opt-out tracing. A trace root records its serializable inputs and output plus every first-party call beneath it. Most descendants need no wrapper. Add a node only when a call needs a name, type, capture override, finalizer, or replay-mocking policy. TypeScript requires the matching \`@bitfab/transform\` build adapter; setup installs and configures it. Python requires 3.12+. Opt-in spans remain supported; setup uses them as the fallback for Ruby, Go, unsupported runtimes, and live streaming roots that opt-out tracing cannot finalize without changing behavior. Keep one tracing surface per call stack. Never mix \`withSpan\` beneath \`withTrace\`; the SDK rejects mixed tracing surfaces.
+Default to opt-out tracing. A trace root records its serializable inputs and output plus every first-party call beneath it. Most descendants need no wrapper. Add a node only when a call needs a name, type, capture override, finalizer, or replay-mocking policy. TypeScript requires the matching \`@bitfab/sdk/transform\` build adapter included with the SDK; setup configures it. Python requires 3.12+. Opt-in spans remain supported; setup uses them as the fallback for Ruby, Go, unsupported runtimes, and live streaming roots that opt-out tracing cannot finalize without changing behavior. Keep one tracing surface per call stack. Never mix \`withSpan\` beneath \`withTrace\`; the SDK rejects mixed tracing surfaces.
 
 \`replay\` calls into your trace root and can modify each captured descendant in one of five ways:
 
@@ -32059,7 +32059,7 @@ Confirm the change to the user.`,
 
 **Install the SDK now.** Detect the project's package manager from its manifest (\`pyproject.toml\` \u2192 \`uv\`/\`poetry\`; \`package.json\` \u2192 \`pnpm\`/\`npm\`/\`yarn\`/\`bun\`; \`Gemfile\` \u2192 \`bundle\`; \`go.mod\` \u2192 \`go get\`; \`requirements.txt\` \u2192 edit file + \`pip install -r\`) and run its canonical add command, do NOT stop to ask about version pinning, dependency groups, package publishing, or whether a supported transform adapter should be added. The user's request to instrument authorizes the dependencies and build wiring required by the selected approach. Prefer \`uv add\`/\`poetry add\` over bare \`pip install\` (bare \`pip install\` doesn't persist to pyproject.toml). In monorepos, scope to the correct workspace (e.g. \`pnpm add --filter <pkg>\`, or cd into the app directory first), running from the repo root will install into the wrong package. Install the SDK as a runtime dependency whenever instrumented code ships or executes from the package, including published libraries and CLIs. Use a development dependency only when the instrumented code is excluded from the published/runtime artifact. Then set the \`BITFAB_API_KEY\` environment variable.
 
-**Install opt-out capture support at the same time.** For TypeScript, add \`@bitfab/transform\` as a development dependency in the same application workspace and wire its adapter into the actual server build before instrumenting. Inspect the build tool and use the matching documented adapter. For Next.js, wrap the existing config with \`@bitfab/transform/next\` while preserving existing wrappers such as Sentry; do not replace or bypass them. For tsup, add the \`@bitfab/transform/esbuild\` plugin to the existing tsup esbuild options. For direct Node or \`tsx\`, update the real start command to register \`@bitfab/transform/register\`. The package also ships documented adapters for Vite, Rollup, webpack, Rspack, Rsbuild, Rolldown, Bun, SWC, Babel, Nest, and the TypeScript compiler. Verify the transformed build path covers the production entrypoint. Do not call a build unsupported until you have checked these adapters and the language guide. For Python, verify the runtime is 3.12+ before choosing \`trace\`/\`node\`. Fall back to opt-in spans only when the language/runtime or build path truly cannot support subtree capture, or when the selected root returns a live stream that opt-out tracing cannot finalize without changing behavior. A published package, a framework-generated span model, or the need to add a supported transform adapter is not a fallback reason. State the concrete technical blocker to the user and keep the whole selected call stack on one tracing surface.
+**Install opt-out capture support at the same time.** For TypeScript, the SDK already includes every transform adapter; do not install a second transform package. Wire the matching \`@bitfab/sdk/transform\` adapter into the actual server build before instrumenting. Inspect the build tool and use the matching documented adapter. For Next.js, wrap the existing config with \`@bitfab/sdk/transform/next\` while preserving existing wrappers such as Sentry; do not replace or bypass them. For tsup, add the \`@bitfab/sdk/transform/esbuild\` plugin to the existing tsup esbuild options. For direct Node or \`tsx\`, update the real start command to register \`@bitfab/sdk/transform/register\`. The package also ships documented adapters for Vite, Rollup, webpack, Rspack, Rsbuild, Rolldown, Bun, SWC, Babel, Nest, and the TypeScript compiler. Verify the transformed build path covers the production entrypoint. Do not call a build unsupported until you have checked these adapters and the language guide. For Python, verify the runtime is 3.12+ before choosing \`trace\`/\`node\`. Fall back to opt-in spans only when the language/runtime or build path truly cannot support subtree capture, or when the selected root returns a live stream that opt-out tracing cannot finalize without changing behavior. A published package, a framework-generated span model, or the need to add a supported transform adapter is not a fallback reason. State the concrete technical blocker to the user and keep the whole selected call stack on one tracing surface.
 
 **Keep organization-specific keys isolated.** Inspect how the selected application already names and loads Bitfab keys before changing its client initialization. A TypeScript client whose configured \`apiKey\` is missing or resolves empty falls back to \`BITFAB_API_KEY\`. If this client intentionally uses a dedicated key for another organization or environment, also set \`captureEnabled\` from the presence of that dedicated key. Never rely on an empty dedicated key to disable tracing because the fallback can send traces to the organization bound to \`BITFAB_API_KEY\`. Do not replace an existing general-purpose \`BITFAB_API_KEY\` when the application deliberately keeps these destinations separate.
 
@@ -32194,7 +32194,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
 
 **Delegate 11b to a subagent only when 11a is itself a large mechanical fan-out** (>10 files) whose generation genuinely overlaps the registry work. The subagent must follow the same registry-only contract.
 
-**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must install and configure \`@bitfab/transform\` in the application build, then put \`withTrace\`/\`trace\` on the existing workflow root. Python 3.12+ uses \`trace\` on the root. Let first-party descendants be discovered automatically and use \`withNode\`/\`node\` for external reads, unsafe side effects, model calls, naming, typing, capture overrides, finalization, and replay mocking. Do not add \`withSpan\` inside an opt-out trace. Existing \`withSpan\` usage is not a reason to extend the opt-in pattern. When a manual span already runs inside the selected call stack, migrate the call stack instead of abandoning opt-out. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; if an opt-in caller remains, use a disjoint trace boundary or stop for refactor confirmation. Remove redundant span wrappers. Replace spans that carry policy with nodes and preserve that policy. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it requires a non-additive rewrite. This tracing-surface migration is instrumentation work, not an application refactor. Stop for refactor confirmation only if preserving application behavior requires changing the underlying function or its callers. Spans remain supported, but during setup choose them only when opt-out is technically impossible: Ruby, Go, unsupported Python runtimes, a TypeScript build path unsupported by every documented transform adapter, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework integrations and their generated spans remain nested beneath the opt-out root; they do not justify a span root. Adding a supported transform adapter, including the esbuild adapter used by tsup, is required setup work rather than a fallback reason. Report the concrete technical blocker and keep the selected call stack on one tracing surface.
+**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must configure the bundled \`@bitfab/sdk/transform\` adapter in the application build, then put \`withTrace\`/\`trace\` on the existing workflow root. Python 3.12+ uses \`trace\` on the root. Let first-party descendants be discovered automatically and use \`withNode\`/\`node\` for external reads, unsafe side effects, model calls, naming, typing, capture overrides, finalization, and replay mocking. Do not add \`withSpan\` inside an opt-out trace. Existing \`withSpan\` usage is not a reason to extend the opt-in pattern. When a manual span already runs inside the selected call stack, migrate the call stack instead of abandoning opt-out. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; if an opt-in caller remains, use a disjoint trace boundary or stop for refactor confirmation. Remove redundant span wrappers. Replace spans that carry policy with nodes and preserve that policy. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it requires a non-additive rewrite. This tracing-surface migration is instrumentation work, not an application refactor. Stop for refactor confirmation only if preserving application behavior requires changing the underlying function or its callers. Spans remain supported, but during setup choose them only when opt-out is technically impossible: Ruby, Go, unsupported Python runtimes, a TypeScript build path unsupported by every documented transform adapter, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework integrations and their generated spans remain nested beneath the opt-out root; they do not justify a span root. Adding a supported transform adapter, including the esbuild adapter used by tsup, is required setup work rather than a fallback reason. Report the concrete technical blocker and keep the selected call stack on one tracing surface.
 
 - **11a. Instrumentation edits**: follow the SDK reference exactly, purely additive. Never change behavior, arguments, return values, error handling, variable names, types, control flow, or code structure. **Wrapping means wrapping, not silently rewriting.** Attach the opt-out trace to the existing root and configure only the discovered nodes that need policy. Rewriting, re-implementing, inlining, or hand-reconstructing a framework/SDK call to seat a root is sometimes genuinely necessary, but it is a refactor, not additive instrumentation: never do it silently as part of the write step. Any such rewrite must preserve behavior exactly (labeled *visibility* or *structural* in the refactor plan); a rewrite that would change behavior is never allowed, fall back to an additive root or move the boundary inward instead. Try the additive root first, when the natural root is opaque or stream-returning, reach for the framework handler/middleware or the \`finalize\` option wrapped around the *unchanged* call. If none of those fit and a rewrite really is required, STOP, present the refactor plan to the user in plain terms and get an explicit yes before touching the code (the "Refactor confirmation" rules below say what the plan must contain), then proceed once they approve. **Likewise, if the additive wrap doesn't typecheck, STOP and surface it rather than dropping or loosening an argument, weakening validation, or otherwise quietly changing runtime behavior to make it compile** (the same "no type-checker escape hatches, don't paper over it" rule the replay step enforces): a compile error on a purely-additive wrap means the wrap isn't additive, so either find the additive form or present it to the user as a refactor and get approval first. Batch repetitive edits into one message (many Edit calls); for large mechanical fan-outs (>10 files of the same wrapper pattern), validate the pattern on one file, then delegate the rest to a subagent. **For each external read or unsafe side effect that replay must mock, configure the discovered node with replay mocking** (TypeScript \`withNode({ type, mockOnReplay: true }, fn)\` / \`@client.node(...)\`; Python \`@client.node(type=..., mock_on_replay=True)\`). Under opt-in fallback, put the equivalent option on the span. This lets replay's \`mock: "marked"\` strategy serve its recorded output without mixing tracing surfaces.
 
@@ -32212,7 +32212,7 @@ Recommend one to start with. **Ask the user to pick exactly ONE workflow to inst
   - **Side-effect check**: if importing the instrumented function triggers module-level side effects (booting listeners/ports/prod connections), do not work around it silently; flag it to the user (a subagent returns that fact in its report so the main agent can flag it).
   - **Result**: confirm the registry module path and the exact \`bitfab-replay --registry ...\` command. Surface signature mismatches or import side effects.{{/codex}}{{#codex}}**Write instrumentation AND the replay registry module for this trace function in the same cycle.** Skip the registry for Go-only projects.
 
-**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must install and configure \`@bitfab/transform\` in the application build, then put \`withTrace\`/\`trace\` on the existing workflow root. Python 3.12+ uses \`trace\` on the root. Let first-party descendants be discovered automatically and use \`withNode\`/\`node\` for external reads, unsafe side effects, model calls, naming, typing, capture overrides, finalization, and replay mocking. Do not add \`withSpan\` inside an opt-out trace. Existing \`withSpan\` usage is not a reason to extend the opt-in pattern. When a manual span already runs inside the selected call stack, migrate the call stack instead of abandoning opt-out. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; if an opt-in caller remains, use a disjoint trace boundary or stop for refactor confirmation. Remove redundant span wrappers. Replace spans that carry policy with nodes and preserve that policy. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it requires a non-additive rewrite. This tracing-surface migration is instrumentation work, not an application refactor. Stop for refactor confirmation only if preserving application behavior requires changing the underlying function or its callers. Spans remain supported, but during setup choose them only when opt-out is technically impossible: Ruby, Go, unsupported Python runtimes, a TypeScript build path unsupported by every documented transform adapter, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework integrations and their generated spans remain nested beneath the opt-out root; they do not justify a span root. Adding a supported transform adapter, including the esbuild adapter used by tsup, is required setup work rather than a fallback reason. Report the concrete technical blocker and keep the selected call stack on one tracing surface.
+**Default instrumentation policy:** use opt-out tracing whenever the selected TypeScript or Python workflow supports it. TypeScript setup must configure the bundled \`@bitfab/sdk/transform\` adapter in the application build, then put \`withTrace\`/\`trace\` on the existing workflow root. Python 3.12+ uses \`trace\` on the root. Let first-party descendants be discovered automatically and use \`withNode\`/\`node\` for external reads, unsafe side effects, model calls, naming, typing, capture overrides, finalization, and replay mocking. Do not add \`withSpan\` inside an opt-out trace. Existing \`withSpan\` usage is not a reason to extend the opt-in pattern. When a manual span already runs inside the selected call stack, migrate the call stack instead of abandoning opt-out. Before converting a span-bearing helper in place, inspect every production caller and confirm each caller belongs to the same opt-out surface; if an opt-in caller remains, use a disjoint trace boundary or stop for refactor confirmation. Remove redundant span wrappers. Replace spans that carry policy with nodes and preserve that policy. TypeScript \`withNode\` requires a named function, so preserve an existing name or use an additive named function form; stop for refactor confirmation if naming it requires a non-additive rewrite. This tracing-surface migration is instrumentation work, not an application refactor. Stop for refactor confirmation only if preserving application behavior requires changing the underlying function or its callers. Spans remain supported, but during setup choose them only when opt-out is technically impossible: Ruby, Go, unsupported Python runtimes, a TypeScript build path unsupported by every documented transform adapter, or a live streaming root whose output opt-out tracing cannot finalize without changing behavior. Framework integrations and their generated spans remain nested beneath the opt-out root; they do not justify a span root. Adding a supported transform adapter, including the esbuild adapter used by tsup, is required setup work rather than a fallback reason. Report the concrete technical blocker and keep the selected call stack on one tracing surface.
 
 - **11a. Instrumentation edits**: follow the SDK reference exactly, purely additive. Never change behavior, arguments, return values, error handling, variable names, types, control flow, or code structure. **Wrapping means wrapping, not silently rewriting.** Attach the opt-out trace to the existing root and configure only the discovered nodes that need policy. Rewriting, re-implementing, inlining, or hand-reconstructing a framework/SDK call to seat a root is sometimes genuinely necessary, but it is a refactor, not additive instrumentation: never do it silently as part of the write step. Any such rewrite must preserve behavior exactly (labeled *visibility* or *structural* in the refactor plan); a rewrite that would change behavior is never allowed, fall back to an additive root or move the boundary inward instead. Try the additive root first, when the natural root is opaque or stream-returning, reach for the framework handler/middleware or the \`finalize\` option wrapped around the *unchanged* call. If none of those fit and a rewrite really is required, STOP, present the refactor plan to the user in plain terms and get an explicit yes before touching the code (the "Refactor confirmation" rules below say what the plan must contain), then proceed once they approve. **Likewise, if the additive wrap doesn't typecheck, STOP and surface it rather than dropping or loosening an argument, weakening validation, or otherwise quietly changing runtime behavior to make it compile** (the same "no type-checker escape hatches, don't paper over it" rule the replay step enforces): a compile error on a purely-additive wrap means the wrap isn't additive, so either find the additive form or present it to the user as a refactor and get approval first. Batch repetitive edits in parallel (one message, many Edit calls); for large mechanical fan-outs (>10 files of the same wrapper pattern), validate the pattern on one file, then do the remaining files. **For each external read or unsafe side effect that replay must mock, configure the discovered node with replay mocking** (TypeScript \`withNode({ type, mockOnReplay: true }, fn)\` / \`@client.node(...)\`; Python \`@client.node(type=..., mock_on_replay=True)\`). Under opt-in fallback, put the equivalent option on the span. This lets replay's \`mock: "marked"\` strategy serve its recorded output without mixing tracing surfaces.
 
@@ -32457,7 +32457,7 @@ Mark each key as \u2705 traces arriving (with most recent timestamp), \u26A0\uFE
    - **Bare trace-processor keys** ({{traceProcessorNames}} over plain \`run()\`): the processor captures the run but its root span records an empty input, so a processor-only key without the run wrapper {{traceProcessorRootWrappers}} or an application root is NOT replayable. Flag it \u26A0\uFE0F root not replayable and recommend adding a \`withTrace\`/\`trace\` root that takes the run input in supported subtree runtimes, or routing through the run wrapper. Recommend a manual \`withSpan\`/\`@span\` root only when opt-out is technically unavailable. When an application root exists, check its signature like any decorated key (next bullet).
    - **Decorated/wrapped keys**: read the root function signature and confirm it's replayable per Instrument's trace-boundary serializability requirement (serializable inputs). Flag any key whose root takes unserializable inputs (live SDK/DB clients, HTTP \`Request\`/\`Response\`, stream writers, sockets, opaque request contexts) as \u26A0\uFE0F root not replayable, reasoning from the signature, not the function name. This is independent of the replay-registry coverage in sub-step 3 above: a non-replayable root is \u26A0\uFE0F whether or not a registry exists for it (a key can be \u274C no replay registry module AND \u26A0\uFE0F root not replayable at once), so never roll a non-replayable root up into \u2705 just because it has no registry entry.
 
-5. **Subtree capture wiring**: an opt-out \`trace\`/\`withTrace\` root records the root and nothing beneath it unless the runtime support is actually there, which looks like healthy tracing until someone opens a trace and finds one node. Only check this when step {{step:inspect/gather-functions}} found an opt-out root; a repo whose roots are all \`withSpan\`/\`span\` needs none of it. **TypeScript** needs two things, both required: (a) \`@bitfab/transform\` in that workspace's manifest, and (b) an adapter wired into the build that produces the server entrypoint. Grep the build configuration and start scripts for \`@bitfab/transform/\`: \`next.config.*\`, \`vite.config.*\`, \`webpack.config.*\`, \`rspack.config.*\`, \`rsbuild.config.*\`, \`rollup.config.*\`, \`tsup.config.*\`, \`babel.config.*\`, Nest's \`webpackConfigPath\` target, or \`--import @bitfab/transform/register\` on the real start command. Mark \u2705 package present and adapter wired, \u26A0\uFE0F package installed but no adapter in the real build path, or \u274C package missing. **Python** needs 3.12+ instead; read the project's declared version and flag anything below it. The application's own log corroborates a \u274C or \u26A0\uFE0F finding: both SDKs log one \`[bitfab]\` warning when an opt-out root runs without its runtime support.
+5. **Subtree capture wiring**: an opt-out \`trace\`/\`withTrace\` root records the root and nothing beneath it unless the runtime support is actually there, which looks like healthy tracing until someone opens a trace and finds one node. Only check this when step {{step:inspect/gather-functions}} found an opt-out root; a repo whose roots are all \`withSpan\`/\`span\` needs none of it. **TypeScript** needs two things, both required: (a) \`@bitfab/sdk\` in that workspace's manifest, and (b) an adapter wired into the build that produces the server entrypoint. Grep the build configuration and start scripts for either the current \`@bitfab/sdk/transform/\` prefix or the still-supported \`@bitfab/transform/\` compatibility prefix: \`next.config.*\`, \`vite.config.*\`, \`webpack.config.*\`, \`rspack.config.*\`, \`rsbuild.config.*\`, \`rollup.config.*\`, \`tsup.config.*\`, \`babel.config.*\`, Nest's \`webpackConfigPath\` target, or the corresponding \`--import .../register\` on the real start command. Treat either adapter prefix as wired; do not add an SDK adapter alongside an existing compatibility adapter. Mark \u2705 package present and adapter wired, \u26A0\uFE0F package installed but no adapter in the real build path, or \u274C package missing. **Python** needs 3.12+ instead; read the project's declared version and flag anything below it. The application's own log corroborates a \u274C or \u26A0\uFE0F finding: both SDKs log one \`[bitfab]\` warning when an opt-out root runs without its runtime support.
 
 Hold these results for the report. (If nothing is instrumented, no trace function keys AND no trace-processor registrations, skip both the **replay** and the **replayability** checks, they are per-workflow, so there's nothing to evaluate; report both as \`n/a (nothing instrumented)\`, never \u2705. Still run the **plugin** and **SDK** checks: the SDK may be installed and stale, or on the legacy \`bitfab\` package needing the \`@bitfab/sdk\` rename, independent of whether any trace functions exist in this repo yet.)`,
           next: "inspect/report"
@@ -32473,13 +32473,13 @@ Hold these results for the report. (If nothing is instrumented, no trace functio
 - **Instrumented here**: the list of keys with \u2705 / \u26A0\uFE0F / \u2753 markers from step {{step:inspect/check-traces}}.
 - **Replay**: \u2705 covers all keys / \u26A0\uFE0F missing keys / \u274C none (from the replay-registry check in step {{step:inspect/check-freshness}}).
 - **Replayable**: \u2705 all roots replayable / \u26A0\uFE0F \`<key>\` root not replayable / \`n/a (nothing instrumented)\` (from the per-root replayability check in step {{step:inspect/check-freshness}}; flagged whether or not a replay registry module exists for the key; never \u2705 when nothing is instrumented).
-- **Subtree capture**: \u2705 wired / \u26A0\uFE0F \`@bitfab/transform\` installed but no adapter in the real build path / \u274C \`@bitfab/transform\` missing / \u274C Python below 3.12 / \`n/a (no opt-out roots)\` (from the subtree-capture check in step {{step:inspect/check-freshness}}).
+- **Subtree capture**: \u2705 wired / \u26A0\uFE0F \`@bitfab/sdk\` installed but no transform adapter in the real build path / \u274C \`@bitfab/sdk\` missing / \u274C Python below 3.12 / \`n/a (no opt-out roots)\` (from the subtree-capture check in step {{step:inspect/check-freshness}}).
 
 Then, for anything not healthy, name the most likely cause and the fix:
 - **Plugin or SDK out of date, or on the legacy \`bitfab\` package**: apply via the fix prompt below (upgrades the version and/or switches \`bitfab\` \u2192 \`@bitfab/sdk\`; same effect as \`{{cmd}}update\`).
 - **Replay missing or incomplete**: refresh via \`{{cmd}}setup replay\` (non-interactive; creates or extends registry entries to cover every key).
 - **Root not replayable**, two failure modes, with the fix matched to each: **(a) the root takes unserializable inputs** (live SDK/DB clients, HTTP req/res, streams, opaque contexts), with or without a replay registry module: move the trace boundary inward to a serializable-input function or refactor to introduce one; **(b) a bare trace-processor-only key** ({{traceProcessorNames}}) whose root is the processor's empty-input span: add a \`withTrace\`/\`trace\` root that wraps the run and takes its input in a supported subtree runtime, or route the run through the run wrapper ({{traceProcessorRootWrappers}}). Use a manual \`withSpan\`/\`@span\` root only when opt-out is technically unavailable. Either way, re-instrument via \`{{cmd}}setup modify\` (or \`{{cmd}}setup instrument\` for a fresh boundary). This is a code change, recommended here, not applied blanket.
-- **Opt-out roots without subtree capture**: every trace is the root alone, so tracing looks healthy and the traces are useless for per-step diagnosis, replay mocking, and prompt iteration. For TypeScript, install \`@bitfab/transform\` in that workspace and wire the matching adapter into the build behind the server entrypoint, preserving existing config wrappers such as Sentry. For Python, this is a runtime upgrade to 3.12+; report it rather than attempting it.
+- **Opt-out roots without subtree capture**: every trace is the root alone, so tracing looks healthy and the traces are useless for per-step diagnosis, replay mocking, and prompt iteration. For TypeScript, use the installed SDK and wire the matching adapter into the build behind the server entrypoint, preserving existing config wrappers such as Sentry. For Python, this is a runtime upgrade to 3.12+; report it rather than attempting it.
 - **Instrumented but no traces**: the app hasn't run with tracing enabled, or \`BITFAB_API_KEY\` isn't set in the run environment. Run the app with the key loaded.
 - **Key set but traces aren't visible in the browser**: the API key is bound to a different Clerk org/tenant than the browser session. A key resolves \`API key \u2192 organization_id \u2192 clerk_organization_id \u2192 Clerk tenant\` at creation time; browser visibility requires both to be the same tenant.
 - **Nothing instrumented**: run \`{{cmd}}setup instrument\`.
@@ -32532,7 +32532,7 @@ Then continue to the fix prompt. Inspect does not open Bitfab.`,
 - **SDK out of date** (\`updateAvailable: true\`, \`renameFrom\` null), name the workspace and the \`current \u2192 latest\` jump, then {{askVerb}} to upgrade; if yes, run the package manager's upgrade from that workspace directory (the same commands \`{{cmd}}update\` uses): npm / pnpm / yarn / bun \`add @bitfab/sdk@latest\`; uv / poetry / pip \`bitfab-py@latest\`; \`bundle update bitfab\`; \`go get github.com/Project-White-Rabbit/bitfab-go@latest && go mod tidy\`. Read the manifest afterward to confirm the new version. Each workspace is its own decision.
 - **On the legacy \`bitfab\` package** (\`renameFrom\` non-null), this rewrites import sites, so **preview before touching code**: list every \`from "bitfab"\` / \`require("bitfab")\` site you would change, then {{askVerb}} to proceed. If yes, remove the old package and add the new one in one step (e.g. \`pnpm remove bitfab && pnpm add @bitfab/sdk@latest\`, or the npm / yarn / bun equivalent) and rewrite those imports to \`@bitfab/sdk\`. Do this even when \`current\` already equals \`latest\`, the rename is the fix. (TypeScript-only; Python / Ruby / Go package names don't change.)
 - **Replay missing or incomplete**: {{askVerb}} to refresh; if yes, run \`{{cmd}}setup replay\` to create or extend the scripts so every trace function key is covered (it is non-interactive).
-- **Subtree capture not wired** (TypeScript), this edits a build file, so **preview before touching code**: name the workspace, the adapter you would use, and the exact config file or start script you would change, then {{askVerb}} to proceed. If yes, add \`@bitfab/transform\` as a development dependency in that workspace and wire the matching adapter: \`@bitfab/transform/next\` wrapping the existing \`next.config\`, the \`/vite\`, \`/rollup\`, \`/rolldown\`, \`/esbuild\`, \`/bun\`, \`/webpack\`, \`/rspack\`, \`/rsbuild\`, \`/babel\`, \`/nest\`, or \`/typescript\` entry in the existing build config, or \`--import @bitfab/transform/register\` on the real start command. Preserve every existing wrapper; never replace or bypass one. Python below 3.12 is a runtime upgrade, report it and do not attempt it.
+- **Subtree capture not wired** (TypeScript), this edits a build file, so **preview before touching code**: name the workspace, the adapter you would use, and the exact config file or start script you would change, then {{askVerb}} to proceed. If yes, use the installed SDK and wire the matching \`@bitfab/sdk/transform\` adapter: \`@bitfab/sdk/transform/next\` wrapping the existing \`next.config\`, the \`/vite\`, \`/rollup\`, \`/rolldown\`, \`/esbuild\`, \`/bun\`, \`/webpack\`, \`/rspack\`, \`/rsbuild\`, \`/babel\`, \`/nest\`, or \`/typescript\` entry in the existing build config, or \`--import @bitfab/sdk/transform/register\` on the real start command. Preserve every existing wrapper; never replace or bypass one. Python below 3.12 is a runtime upgrade, report it and do not attempt it.
 
 For unusual monorepos or private registries, defer to \`{{cmd}}update\`. Report what was applied and what the user declined. Do not open Bitfab.`,
           next: "cleanup/finish"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab-cli",
-  "version": "0.2.387",
+  "version": "0.2.388",
   "description": "Install and configure the Bitfab plugin in Claude Code, Codex, or Cursor, or the Bitfab skill pack in Amp (Alpha).",
   "type": "module",
   "main": "dist/index.js",