pumuki 6.3.97 → 6.3.99

package/scripts/framework-menu-system-notifications-cause.ts

@@ -5,7 +5,6 @@ import {
 } from './framework-menu-system-notifications-text';
 
 const BLOCKED_CAUSE_SUMMARY_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_GATE_BLOCKED: 'El gate de evidencia de IA está bloqueado.',
   EVIDENCE_MISSING: 'Falta evidencia para validar este paso.',
   EVIDENCE_INVALID: 'La evidencia actual es inválida.',
   EVIDENCE_CHAIN_INVALID: 'La cadena de evidencia no es válida.',
@@ -19,14 +18,6 @@ const BLOCKED_CAUSE_SUMMARY_BY_CODE: Readonly<Record<string, string>> = {
   OPENSPEC_MISSING: 'OpenSpec no está instalado en este repositorio.',
   MCP_ENTERPRISE_RECEIPT_MISSING: 'Falta el recibo enterprise de MCP.',
   BACKEND_AVOID_EXPLICIT_ANY: 'Se detectó uso de "any" explícito en backend.',
-  FRONTEND_NO_CONSOLE_LOG: 'Se detectó uso de "console.log" en frontend.',
-  BACKEND_NO_CONSOLE_LOG: 'Se detectó uso de "console.log" en backend.',
-  GIT_ATOMICITY_TOO_MANY_SCOPES: 'Se han cambiado demasiados scopes en el mismo commit.',
-  SOLID_HEURISTIC: 'Se detectó una violación estructural en el cambio actual.',
-  TRACKING_CANONICAL_SOURCE_CONFLICT:
-    'Hay varias fuentes canónicas de seguimiento declaradas.',
-  TRACKING_CANONICAL_IN_PROGRESS_INVALID:
-    'El archivo canónico de seguimiento debe tener exactamente una tarea en construcción.',
 };
 
 const ENGLISH_CAUSE_HINTS = [
@@ -65,27 +56,12 @@ const toKnownSpanishCauseFromMessage = (message: string): string | null => {
   if (normalized.includes('avoid explicit any')) {
     return BLOCKED_CAUSE_SUMMARY_BY_CODE.BACKEND_AVOID_EXPLICIT_ANY;
   }
-  if (normalized.includes('console.log usage is not allowed in frontend code')) {
-    return BLOCKED_CAUSE_SUMMARY_BY_CODE.FRONTEND_NO_CONSOLE_LOG;
-  }
-  if (normalized.includes('console.log usage is not allowed in backend code')) {
-    return BLOCKED_CAUSE_SUMMARY_BY_CODE.BACKEND_NO_CONSOLE_LOG;
-  }
   if (normalized.includes('evidence is stale')) {
     return BLOCKED_CAUSE_SUMMARY_BY_CODE.EVIDENCE_STALE;
   }
-  if (normalized.includes('evidence ai gate status is blocked')) {
-    return BLOCKED_CAUSE_SUMMARY_BY_CODE.EVIDENCE_GATE_BLOCKED;
-  }
   if (normalized.includes('no upstream tracking reference')) {
     return BLOCKED_CAUSE_SUMMARY_BY_CODE.PRE_PUSH_UPSTREAM_MISSING;
   }
-  if (normalized.includes('too many scopes changed') || normalized.includes('atomicity budget exceeded')) {
-    return BLOCKED_CAUSE_SUMMARY_BY_CODE.GIT_ATOMICITY_TOO_MANY_SCOPES;
-  }
-  if (normalized.includes('heuristic violation')) {
-    return BLOCKED_CAUSE_SUMMARY_BY_CODE.SOLID_HEURISTIC;
-  }
   return null;
 };
 

package/scripts/framework-menu-system-notifications-macos-swift-source.ts

@@ -1,10 +1,6 @@
 export const SWIFT_BLOCKED_DIALOG_SOURCE = String.raw`import AppKit
 import Foundation
 
-final class KeyableFloatingPanel: NSPanel {
-  override var canBecomeKey: Bool { true }
-}
-
 struct DialogConfig {
   let title: String
   let cause: String
@@ -12,7 +8,6 @@ struct DialogConfig {
   let disableButton: String
   let muteButton: String
   let keepButton: String
-  let timeoutSeconds: Double
 }
 
 func parseArguments() -> DialogConfig {
@@ -23,74 +18,18 @@ func parseArguments() -> DialogConfig {
     }
     return args[index + 1]
   }
-  let timeoutRaw = read("--timeout-seconds", fallback: "15")
-  let timeout = Double(timeoutRaw) ?? 15
   return DialogConfig(
     title: read("--title", fallback: "Pumuki bloqueado"),
     cause: read("--cause", fallback: "Bloqueo detectado."),
     remediation: read("--remediation", fallback: "Corrige el bloqueo y vuelve a ejecutar."),
     disableButton: read("--disable-button", fallback: "Desactivar"),
     muteButton: read("--mute-button", fallback: "Silenciar 30 min"),
-    keepButton: read("--keep-button", fallback: "Mantener activas"),
-    timeoutSeconds: max(5, timeout)
+    keepButton: read("--keep-button", fallback: "Mantener activas")
   )
 }
 
-final class DialogController: NSObject, NSApplicationDelegate, NSWindowDelegate {
+final class DialogAppDelegate: NSObject, NSApplicationDelegate {
   private let config: DialogConfig
-  private var window: NSWindow?
-  private var chosenButton: String?
-
-  private func preferredWidth() -> CGFloat {
-    let longest = max(config.title.count, max(config.cause.count, config.remediation.count))
-    let estimated = CGFloat(longest) * 4.9 + 170
-    let visibleFrame = targetVisibleFrame()
-    let maxAllowed = max(360, visibleFrame.width - 40)
-    return min(max(360, estimated), min(620, maxAllowed))
-  }
-
-  private func targetVisibleFrame() -> NSRect {
-    let mouse = NSEvent.mouseLocation
-    if let screen = NSScreen.screens.first(where: { NSMouseInRect(mouse, $0.frame, false) }) {
-      return screen.visibleFrame
-    }
-    if let main = NSScreen.main {
-      return main.visibleFrame
-    }
-    if let first = NSScreen.screens.first {
-      return first.visibleFrame
-    }
-    return NSRect(x: 0, y: 0, width: 1440, height: 900)
-  }
-
-  private func pinWindowToBottomRight() {
-    guard let panel = window else {
-      return
-    }
-    let width = panel.frame.width
-    let height = panel.frame.height
-    let margin: CGFloat = 20
-    let visibleFrame = targetVisibleFrame()
-    let target = NSRect(
-      x: visibleFrame.maxX - width - margin,
-      y: visibleFrame.minY + margin,
-      width: width,
-      height: height
-    )
-    panel.setFrame(target, display: true)
-  }
-
-  private func resizeWindowToContent(root: NSStackView, contentView: NSView) {
-    guard let panel = window else {
-      return
-    }
-    contentView.layoutSubtreeIfNeeded()
-    let fitting = root.fittingSize
-    let visibleFrame = targetVisibleFrame()
-    let width = min(max(panel.frame.width, fitting.width + 30), min(620, visibleFrame.width - 40))
-    let height = min(max(140, fitting.height + 30), max(180, visibleFrame.height - 40))
-    panel.setContentSize(NSSize(width: width, height: height))
-  }
 
   init(config: DialogConfig) {
     self.config = config
@@ -98,149 +37,30 @@ final class DialogController: NSObject, NSApplicationDelegate, NSWindowDelegate
   }
 
   func applicationDidFinishLaunching(_ notification: Notification) {
-    showWindow()
-    startTimeout()
-  }
-
-  private func showWindow() {
-    let width = preferredWidth()
-    let height: CGFloat = 170
-    let margin: CGFloat = 20
-    let screenFrame = targetVisibleFrame()
-    let origin = NSPoint(
-      x: screenFrame.maxX - width - margin,
-      y: screenFrame.minY + margin
-    )
-
-    let panel = KeyableFloatingPanel(
-      contentRect: NSRect(x: origin.x, y: origin.y, width: width, height: height),
-      styleMask: [.titled, .closable, .fullSizeContentView],
-      backing: .buffered,
-      defer: false
-    )
-    panel.becomesKeyOnlyIfNeeded = false
-    panel.level = .floating
-    panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-    panel.titleVisibility = .hidden
-    panel.titlebarAppearsTransparent = true
-    panel.isMovable = true
-    panel.isReleasedWhenClosed = false
-    panel.delegate = self
-    panel.hidesOnDeactivate = false
-    panel.standardWindowButton(.zoomButton)?.isHidden = true
-    panel.standardWindowButton(.miniaturizeButton)?.isHidden = true
-
-    let root = NSStackView()
-    root.orientation = .vertical
-    root.alignment = .leading
-    root.spacing = 12
-    root.translatesAutoresizingMaskIntoConstraints = false
-
-    let titleField = NSTextField(labelWithString: config.title)
-    titleField.font = NSFont.boldSystemFont(ofSize: 15)
-    titleField.lineBreakMode = .byWordWrapping
-    titleField.maximumNumberOfLines = 0
-    titleField.preferredMaxLayoutWidth = width - 48
-    titleField.cell?.lineBreakMode = .byWordWrapping
-    titleField.cell?.usesSingleLineMode = false
-    titleField.cell?.wraps = true
-
-    let causeField = NSTextField(wrappingLabelWithString: "Causa: \(config.cause)")
-    causeField.font = NSFont.systemFont(ofSize: 12)
-    causeField.lineBreakMode = .byWordWrapping
-    causeField.maximumNumberOfLines = 0
-    causeField.preferredMaxLayoutWidth = width - 48
-    causeField.cell?.lineBreakMode = .byWordWrapping
-    causeField.cell?.usesSingleLineMode = false
-    causeField.cell?.wraps = true
-
-    let remediationField = NSTextField(wrappingLabelWithString: "Solución: \(config.remediation)")
-    remediationField.font = NSFont.systemFont(ofSize: 12)
-    remediationField.lineBreakMode = .byWordWrapping
-    remediationField.maximumNumberOfLines = 0
-    remediationField.preferredMaxLayoutWidth = width - 48
-    remediationField.cell?.lineBreakMode = .byWordWrapping
-    remediationField.cell?.usesSingleLineMode = false
-    remediationField.cell?.wraps = true
-
-    let buttons = NSStackView()
-    buttons.orientation = .horizontal
-    buttons.alignment = .centerY
-    buttons.spacing = 10
-
-    let disableButton = NSButton(title: config.disableButton, target: self, action: #selector(disablePressed))
-    disableButton.bezelStyle = .rounded
-    let muteButton = NSButton(title: config.muteButton, target: self, action: #selector(mutePressed))
-    muteButton.bezelStyle = .rounded
-    let keepButton = NSButton(title: config.keepButton, target: self, action: #selector(keepPressed))
-    keepButton.bezelStyle = .rounded
-    keepButton.keyEquivalent = "\r"
-
-    buttons.addArrangedSubview(disableButton)
-    buttons.addArrangedSubview(muteButton)
-    buttons.addArrangedSubview(keepButton)
-
-    root.addArrangedSubview(titleField)
-    root.addArrangedSubview(causeField)
-    root.addArrangedSubview(remediationField)
-    root.addArrangedSubview(buttons)
-
-    panel.contentView = NSView()
-    guard let contentView = panel.contentView else {
-      finish(with: config.keepButton)
-      return
-    }
-    contentView.addSubview(root)
-    NSLayoutConstraint.activate([
-      root.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 18),
-      root.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -18),
-      root.topAnchor.constraint(equalTo: contentView.topAnchor, constant: 18),
-      root.bottomAnchor.constraint(equalTo: contentView.bottomAnchor, constant: -18),
-    ])
-
-    self.window = panel
-    resizeWindowToContent(root: root, contentView: contentView)
-    pinWindowToBottomRight()
-    panel.makeKeyAndOrderFront(nil)
-    panel.orderFrontRegardless()
     NSApp.activate(ignoringOtherApps: true)
-    DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) { [weak self] in
-      guard let self else {
-        return
-      }
-      self.resizeWindowToContent(root: root, contentView: contentView)
-      self.pinWindowToBottomRight()
-    }
-  }
 
-  private func startTimeout() {
-    Timer.scheduledTimer(withTimeInterval: config.timeoutSeconds, repeats: false) { [weak self] _ in
-      self?.finish(with: self?.config.keepButton ?? "Mantener activas")
+    let alert = NSAlert()
+    alert.messageText = config.title
+    alert.informativeText = "Causa: \(config.cause)\n\nSolución: \(config.remediation)"
+    alert.alertStyle = .critical
+    alert.addButton(withTitle: config.keepButton)
+    alert.addButton(withTitle: config.muteButton)
+    alert.addButton(withTitle: config.disableButton)
+
+    let response = alert.runModal()
+    let choice: String
+    switch response {
+    case .alertFirstButtonReturn:
+      choice = config.keepButton
+    case .alertSecondButtonReturn:
+      choice = config.muteButton
+    case .alertThirdButtonReturn:
+      choice = config.disableButton
+    default:
+      choice = config.keepButton
     }
-  }
-
-  func windowWillClose(_ notification: Notification) {
-    finish(with: config.keepButton)
-  }
-
-  @objc private func disablePressed() {
-    finish(with: config.disableButton)
-  }
 
-  @objc private func mutePressed() {
-    finish(with: config.muteButton)
-  }
-
-  @objc private func keepPressed() {
-    finish(with: config.keepButton)
-  }
-
-  private func finish(with button: String) {
-    guard chosenButton == nil else {
-      return
-    }
-    chosenButton = button
-    FileHandle.standardOutput.write(Data("button returned:\(button)\n".utf8))
+    FileHandle.standardOutput.write(Data("button returned:\(choice)\n".utf8))
     NSApp.terminate(nil)
   }
 
@@ -252,7 +72,7 @@ final class DialogController: NSObject, NSApplicationDelegate, NSWindowDelegate
 let config = parseArguments()
 let app = NSApplication.shared
 app.setActivationPolicy(.accessory)
-let controller = DialogController(config: config)
-app.delegate = controller
+let delegate = DialogAppDelegate(config: config)
+app.delegate = delegate
 app.run()
 `;

package/scripts/framework-menu-system-notifications-macos.ts

@@ -5,6 +5,7 @@ import {
   type SystemNotificationCommandRunnerWithOutput,
   type SystemNotificationsConfig,
 } from './framework-menu-system-notifications-types';
+import { isTruthyEnvValue } from './framework-menu-system-notifications-env';
 import { resolveBlockedDialogEnabled } from './framework-menu-system-notifications-macos-dialog-enabled';
 import { emitMacOsBannerStage } from './framework-menu-system-notifications-macos-banner-stage';
 import { emitMacOsBlockedDialogStage } from './framework-menu-system-notifications-macos-blocked-stage';
@@ -19,6 +20,9 @@ const shouldSkipMacOsBannerForInteractiveBlockedDialog = (params: {
   config: SystemNotificationsConfig;
   env: NodeJS.ProcessEnv;
 }): boolean => {
+  if (!isTruthyEnvValue(params.env.PUMUKI_MACOS_GATE_BLOCKED_BANNER_DEDUPE)) {
+    return false;
+  }
   if (params.event.kind !== 'gate.blocked') {
     return false;
   }

package/scripts/framework-menu-system-notifications-payloads-blocked.ts

@@ -22,7 +22,7 @@ export const buildGateBlockedPayload = (
     resolveBlockedCauseSummary(event, causeCode),
     72
   );
-  const remediation = resolveBlockedRemediation(event, causeCode, { variant: 'banner' });
+  const remediation = resolveBlockedRemediation(event, causeCode);
   return {
     title: '🔴 Pumuki bloqueado',
     subtitle: `${projectPrefix}${event.stage} · ${causeSummary}`,

package/scripts/framework-menu-system-notifications-remediation.ts

@@ -4,30 +4,22 @@ import {
   truncateNotificationText,
 } from './framework-menu-system-notifications-text';
 
-type BlockedRemediationVariant = 'banner' | 'dialog';
-
 const BLOCKED_REMEDIATION_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_GATE_BLOCKED: 'Corrige las violaciones bloqueantes detectadas en la evidencia y vuelve a ejecutar el gate.',
-  EVIDENCE_MISSING: 'Genera la evidencia del slice actual y vuelve a validar esta fase.',
-  EVIDENCE_INVALID: 'Regenera la evidencia de esta iteración y repite la validación.',
+  EVIDENCE_MISSING: 'Genera evidencia del slice actual y vuelve a validar el gate de esta fase.',
+  EVIDENCE_INVALID: 'Regenera la evidencia de la iteración y repite la validación en el mismo stage.',
   EVIDENCE_CHAIN_INVALID: 'Regenera la evidencia para restaurar la cadena de integridad y vuelve a validar.',
-  EVIDENCE_STALE: 'Refresca la evidencia y vuelve a validar PRE_WRITE/PRE_PUSH.',
-  EVIDENCE_BRANCH_MISMATCH: 'Regenera la evidencia en esta rama y repite la validación.',
-  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera la evidencia desde este repositorio y vuelve a validar.',
-  PRE_PUSH_UPSTREAM_MISSING: 'Configura upstream con `git push --set-upstream origin <branch>` y repite PRE_PUSH.',
-  SDD_SESSION_MISSING: 'Abre la sesión SDD del change activo y repite la validación.',
-  SDD_SESSION_INVALID: 'Refresca la sesión SDD activa y vuelve a validar esta fase.',
-  OPENSPEC_MISSING: 'Instala OpenSpec en este repositorio y vuelve a validar el gate.',
-  MCP_ENTERPRISE_RECEIPT_MISSING: 'Genera el receipt enterprise de MCP y vuelve a validar.',
-  BACKEND_AVOID_EXPLICIT_ANY: 'Sustituye `any` por tipos concretos en backend y relanza el gate.',
-  GIT_ATOMICITY_TOO_MANY_SCOPES: 'Divide el cambio por scope o en commits más pequeños y vuelve a ejecutar el gate.',
-  SOLID_HEURISTIC: 'Corrige la violación detectada y vuelve a ejecutar el gate.',
+  EVIDENCE_STALE: 'Ejecuta una auditoría completa de evidencia y vuelve a validar PRE_WRITE/PRE_PUSH. Si persiste, refresca la sesión SDD y reintenta.',
+  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en esta rama y vuelve a ejecutar la validación para sincronizar branch y snapshot.',
+  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este repositorio y relanza la validación del gate.',
+  PRE_PUSH_UPSTREAM_MISSING: 'Configura upstream con `git push --set-upstream origin <branch>` y vuelve a ejecutar PRE_PUSH.',
+  SDD_SESSION_MISSING: 'Abre sesión SDD del change activo y repite la validación de la fase actual.',
+  SDD_SESSION_INVALID: 'Refresca la sesión SDD (open/refresh) y vuelve a validar en el mismo stage.',
+  OPENSPEC_MISSING: 'Instala OpenSpec en el repositorio y relanza la validación del gate.',
+  MCP_ENTERPRISE_RECEIPT_MISSING: 'Genera el receipt enterprise de MCP y vuelve a ejecutar la validación.',
+  BACKEND_AVOID_EXPLICIT_ANY: 'Reemplaza `any` por tipos concretos en backend y vuelve a lanzar el gate para confirmar el fix.',
 };
 
-const BLOCKED_REMEDIATION_MAX_LENGTH_BY_VARIANT: Readonly<Record<BlockedRemediationVariant, number>> = {
-  banner: 120,
-  dialog: 220,
-};
+const BLOCKED_REMEDIATION_MAX_LENGTH = 220;
 
 const GENERIC_BLOCKED_REMEDIATION =
   'Corrige el bloqueo indicado y vuelve a ejecutar el comando.';
@@ -95,10 +87,7 @@ const toKnownSpanishRemediationFromMessage = (message: string, causeCode: string
 
 export const resolveBlockedRemediation = (
   event: Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>,
-  causeCode: string,
-  options?: {
-    variant?: BlockedRemediationVariant;
-  }
+  causeCode: string
 ): string => {
   const variant = options?.variant ?? 'dialog';
   const maxLength = BLOCKED_REMEDIATION_MAX_LENGTH_BY_VARIANT[variant];

package/scripts/framework-menu-system-notifications-text.ts

@@ -7,13 +7,7 @@ export const truncateNotificationText = (value: string, maxLength: number): stri
   if (value.length <= maxLength) {
     return value;
   }
-  const limit = Math.max(1, maxLength - 1);
-  const trimmed = value.slice(0, limit).trimEnd();
-  const boundary = trimmed.lastIndexOf(' ');
-  const shortened = boundary >= Math.floor(limit * 0.6)
-    ? trimmed.slice(0, boundary).trimEnd()
-    : trimmed;
-  return `${shortened}…`;
+  return `${value.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
 };
 
 export const resolveProjectLabel = (params: {

package/scripts/framework-menu.ts

@@ -16,6 +16,7 @@ import {
   runWorkingTreeGateSilent,
   runRepoAndStagedPrePushGateSilent,
   runWorkingTreePrePushGateSilent,
+  runUnstagedGateSilent,
 } from './framework-menu-gate-lib';
 import { createFrameworkMenuPrompts } from './framework-menu-prompts';
 import { resolveDefaultRangeFrom } from './framework-menu-runners';
@@ -62,7 +63,9 @@ const menu = async (): Promise<void> => {
       runRepoGate: runRepoGateSilent,
       runRepoAndStagedGate: runRepoAndStagedPrePushGateSilent,
       runStagedGate: runStagedGateSilent,
+      runUnstagedGate: runUnstagedGateSilent,
       runWorkingTreeGate: runWorkingTreePrePushGateSilent,
+      runWorkingTreePreCommitGate: runWorkingTreeGateSilent,
       write: (text) => {
         output.write(text);
       },
@@ -73,7 +76,6 @@ const menu = async (): Promise<void> => {
         consumerRuntime.printMenu();
       } else {
         const currentSummary = consumerRuntime.readCurrentSummary();
-        const lastPreflight = consumerRuntime.readLastPreflight();
         if (!isMenuUiV2Enabled()) {
           output.write(
             `\n${formatAdvancedMenuClassicView(advancedActions, {
@@ -85,7 +87,6 @@ const menu = async (): Promise<void> => {
             output.write(
               `\n${formatAdvancedMenuView(advancedActions, {
                 evidenceSummary: currentSummary ?? undefined,
-                preflight: lastPreflight ?? undefined,
               })}\n`
             );
           } catch {

package/scripts/package-install-smoke-consumer-git-repo-lib.ts

@@ -39,17 +39,8 @@ export const configureRemoteAndFeatureBranch = (
     workspace.tmpRoot
   );
   runGitStep(workspace, ['remote', 'add', 'origin', workspace.bareRemote], 'git remote add origin');
+  runGitStep(workspace, ['push', '-u', 'origin', 'main'], 'git push origin main');
   runGitStep(workspace, ['checkout', '-b', 'feature/package-smoke'], 'git checkout feature branch');
-  runGitStep(
-    workspace,
-    ['push', '-u', 'origin', 'feature/package-smoke'],
-    'git push origin feature branch'
-  );
-  runGitStep(
-    workspace,
-    ['push', 'origin', 'HEAD:refs/heads/main'],
-    'git push origin main from feature branch'
-  );
   runGitStep(
     workspace,
     ['branch', '--set-upstream-to=origin/main', 'feature/package-smoke'],

package/scripts/package-install-smoke-consumer-npm-lib.ts

@@ -15,11 +15,10 @@ import packageJson from '../package.json';
 const runNpmStep = (
   workspace: SmokeWorkspace,
   args: string[],
-  context: string,
-  env?: NodeJS.ProcessEnv
+  context: string
 ): void => {
   assertSuccess(
-    runCommand({ cwd: workspace.consumerRepo, executable: 'npm', args, env }),
+    runCommand({ cwd: workspace.consumerRepo, executable: 'npm', args }),
     context
   );
 };
@@ -33,14 +32,7 @@ export const installTarballIntoConsumerRepo = (
     'node_modules/\n.ai_evidence.json\n',
     'utf8'
   );
-  runNpmStep(
-    workspace,
-    ['install', workspace.tarballPath ?? ''],
-    'npm install <tarball>',
-    {
-      PUMUKI_SKIP_POSTINSTALL: '1',
-    }
-  );
+  runNpmStep(workspace, ['install', workspace.tarballPath ?? ''], 'npm install <tarball>');
 };
 
 export const verifyInstalledPackageCanBeRequired = (
@@ -59,40 +51,10 @@ export const verifyInstalledPackageCanBeRequired = (
 export const verifyInstalledPumukiBinaryVersion = (
   workspace: SmokeWorkspace
 ): void => {
-  const hasInstalledStatusVersion = (
-    result: ReturnType<typeof runCommand>,
-  ): boolean => {
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(result.stdout);
-    } catch {
-      return false;
-    }
-
-    const packageVersion =
-      typeof parsed === 'object' && parsed !== null && 'packageVersion' in parsed
-        ? (parsed as { packageVersion?: unknown }).packageVersion
-        : null;
-    const effectiveVersion =
-      typeof parsed === 'object'
-      && parsed !== null
-      && 'version' in parsed
-      && typeof (parsed as { version?: unknown }).version === 'object'
-      && (parsed as { version: { effective?: unknown } }).version !== null
-        ? (parsed as { version: { effective?: unknown } }).version.effective
-        : null;
-
-    return packageVersion === packageJson.version || effectiveVersion === packageJson.version;
-  };
-
   const assertInstalledStatusVersion = (
     result: ReturnType<typeof runCommand>,
     context: string
   ): void => {
-    if (hasInstalledStatusVersion(result)) {
-      return;
-    }
-
     let parsed: unknown;
     try {
       parsed = JSON.parse(result.stdout);
@@ -113,9 +75,11 @@ export const verifyInstalledPumukiBinaryVersion = (
         ? (parsed as { version: { effective?: unknown } }).version.effective
         : null;
 
-    throw new Error(
-      `${context} reported unexpected version (packageVersion=${String(packageVersion)}, effectiveVersion=${String(effectiveVersion)}, expected=${packageJson.version})`
-    );
+    if (packageVersion !== packageJson.version && effectiveVersion !== packageJson.version) {
+      throw new Error(
+        `${context} reported unexpected version (packageVersion=${String(packageVersion)}, effectiveVersion=${String(effectiveVersion)}, expected=${packageJson.version})`
+      );
+    }
   };
 
   const noInstallVersionCheck = runCommand({
@@ -129,8 +93,7 @@ export const verifyInstalledPumukiBinaryVersion = (
     noInstallVersionCheck.exitCode === 0
     && !/Cannot find module|ERR_MODULE_NOT_FOUND|failed to resolve tsx runtime/.test(
       noInstallVersionCheck.combined
-    )
-    && hasInstalledStatusVersion(noInstallVersionCheck);
+    );
   if (noInstallPassed) {
     assertNoFatalOutput(noInstallVersionCheck, 'pumuki status --json smoke');
     assertInstalledStatusVersion(noInstallVersionCheck, 'pumuki status --json smoke');

package/scripts/pumuki-full-surface-smoke-lib.ts

@@ -0,0 +1,37 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type SmokeBinStrategy = 'source' | 'installed';
+
+export const resolveBinStrategy = (raw: string | undefined): SmokeBinStrategy => {
+  const normalized = (raw ?? 'source').trim().toLowerCase();
+  if (normalized === 'installed' || normalized === 'consumer') {
+    return 'installed';
+  }
+  return 'source';
+};
+
+export type SmokeLayout = {
+  pumukiPackageRoot: string;
+  smokeCwd: string;
+  binStrategy: SmokeBinStrategy;
+  binRoot: string;
+};
+
+export const resolveSmokeLayout = (params: {
+  scriptFileUrl: string;
+  env: NodeJS.ProcessEnv;
+}): SmokeLayout => {
+  const pumukiPackageRoot = join(dirname(fileURLToPath(params.scriptFileUrl)), '..');
+  const smokeCwd =
+    (params.env.PUMUKI_SMOKE_REPO_ROOT ?? pumukiPackageRoot).trim() || pumukiPackageRoot;
+  const binStrategy = resolveBinStrategy(params.env.PUMUKI_SMOKE_BIN_STRATEGY);
+  const binRoot =
+    binStrategy === 'installed'
+      ? join(smokeCwd, 'node_modules', 'pumuki')
+      : pumukiPackageRoot;
+  return { pumukiPackageRoot, smokeCwd, binStrategy, binRoot };
+};
+
+export const installedBinMarkerPath = (layout: SmokeLayout): string =>
+  join(layout.binRoot, 'bin', 'pumuki.js');