@bastani/atomic 0.8.19 → 0.8.20-0

package/dist/builtin/workflows/src/tui/session-confirm.ts

@@ -154,12 +154,12 @@ export function renderKillConfirm(opts: KillConfirmRenderOpts): string[] {
   lines.push(renderTextRow(
     inner,
     theme,
-    `      ${muted}Aborts the active stage and discards partial work.${RESET}`,
+    `      ${muted}Aborts in-flight work and marks the run killed.${RESET}`,
   ));
   lines.push(renderTextRow(
     inner,
     theme,
-    `      ${muted}Removes the run from live history/status.${RESET}`,
+    `      ${muted}Retains it in history/status for inspection.${RESET}`,
   ));
   lines.push(renderBlankRow(inner, theme));
 
@@ -219,7 +219,6 @@ export interface WorkflowKilledNoticeRenderOpts {
   theme: GraphTheme;
   run: RunSnapshot;
   previousStatus: RunStatus;
-  wasInFlight: boolean;
 }
 
 const KILLED_TITLE = "Workflow killed";
@@ -252,7 +251,7 @@ function renderKilledTextRow(
 export function renderWorkflowKilledNotice(
   opts: WorkflowKilledNoticeRenderOpts,
 ): string[] {
-  const { width, theme, run, previousStatus, wasInFlight } = opts;
+  const { width, theme, run, previousStatus } = opts;
   const inner = Math.max(4, width - 2);
   const idShort = run.id.slice(0, 8);
   const stageCount = run.stages.length;
@@ -285,14 +284,14 @@ export function renderWorkflowKilledNotice(
   ));
   lines.push(renderBlankRow(inner, theme));
 
-  const action = wasInFlight
+  const action = runningStages > 0
     ? "Active stage work was aborted."
-    : "The completed run was removed.";
+    : "Run was marked killed; no stages were actively running.";
   lines.push(renderKilledTextRow(inner, theme, `      ${success}✓${RESET}${panelBg} ${muted}${action}${RESET}`));
   lines.push(renderKilledTextRow(
     inner,
     theme,
-    `      ${success}✓${RESET}${panelBg} ${muted}Run removed from live history and status.${RESET}`,
+    `      ${success}✓${RESET}${panelBg} ${muted}Run retained for read-only inspection.${RESET}`,
   ));
   lines.push(renderBlankRow(inner, theme));
   lines.push(renderKilledFooter(width, theme));

package/dist/builtin/workflows/src/tui/session-picker.ts

@@ -38,30 +38,31 @@ export interface SessionPickerState {
   query: string;
   /** 0-based index into the filtered/visible list. */
   selectedIndex: number;
-  /** Toggle for "include long-ended runs". Default false. */
+  /** Toggle for terminal run visibility. Default true so retained terminal runs stay inspectable. */
   includeAll: boolean;
   /** True when the filter input has focus (typing routes to query). */
   filterFocused: boolean;
 }
 
 export function createSessionPickerState(): SessionPickerState {
-  return { query: "", selectedIndex: 0, includeAll: false, filterFocused: false };
+  return { query: "", selectedIndex: 0, includeAll: true, filterFocused: false };
 }
 
 /** A run plus a derived bucket — keeps the renderer monomorphic. */
 export interface PickerRow {
   readonly run: RunSnapshot;
-  readonly bucket: "active" | "recent";
+  readonly bucket: "active" | "terminal";
 }
 
 const RECENT_WINDOW_MS = 60 * 60 * 1000;
 
 /**
- * Slice runs into picker rows. Active = `endedAt === undefined`. Recent =
- * ended within the last hour. With `includeAll`, the hour cutoff is dropped.
+ * Slice runs into picker rows. Active = `endedAt === undefined`. Terminal =
+ * retained terminal runs. With `includeAll` false, terminal rows are limited
+ * to the legacy recent-ended one-hour window.
  *
  * Sort: active first (newest start last in the list = bottom-of-pane),
- * then recent newest-end first.
+ * then terminal newest-end first.
  */
 export function selectRunsForPicker(
   runs: readonly RunSnapshot[],
@@ -76,20 +77,23 @@ export function selectRunsForPicker(
   };
 
   const active: PickerRow[] = [];
-  const recent: PickerRow[] = [];
+  const terminal: PickerRow[] = [];
   for (const r of runs) {
     if (!matches(r)) continue;
-    if (r.endedAt === undefined) {
+
+    const endedAt = r.endedAt;
+    if (endedAt === undefined) {
       active.push({ run: r, bucket: "active" });
       continue;
     }
-    if (includeAll || now - (r.endedAt ?? 0) <= RECENT_WINDOW_MS) {
-      recent.push({ run: r, bucket: "recent" });
+
+    if (includeAll || now - endedAt <= RECENT_WINDOW_MS) {
+      terminal.push({ run: r, bucket: "terminal" });
     }
   }
   active.sort((a, b) => a.run.startedAt - b.run.startedAt);
-  recent.sort((a, b) => (b.run.endedAt ?? 0) - (a.run.endedAt ?? 0));
-  return [...active, ...recent];
+  terminal.sort((a, b) => (b.run.endedAt ?? 0) - (a.run.endedAt ?? 0));
+  return [...active, ...terminal];
 }
 
 // ---------------------------------------------------------------------------
@@ -308,7 +312,7 @@ export function renderSessionPicker(opts: SessionPickerRenderOpts): string[] {
   for (let i = 0; i < visible.length; i++) {
     const row = visible[i]!;
     if (row.bucket !== prevBucket) {
-      lines.push(renderSectionRow(row.bucket === "active" ? "ACTIVE" : "RECENT", inner, theme));
+      lines.push(renderSectionRow(row.bucket === "active" ? "ACTIVE" : "TERMINAL", inner, theme));
       prevBucket = row.bucket;
     }
     const absIndex = Math.max(0, start) + i;
@@ -398,7 +402,7 @@ export function handleSessionPickerInput(
   // `x` = kill. Avoids collision with vim's `k` = up.
   if (matchesKey(data, "x") || matchesKey(data, Key.shift("x"))) {
     const row = rows[state.selectedIndex];
-    if (!row) return { kind: "noop" };
+    if (!row || row.run.endedAt !== undefined) return { kind: "noop" };
     return { kind: "kill", runId: row.run.id };
   }
 

package/dist/builtin/workflows/src/tui/status-list.ts

@@ -336,8 +336,8 @@ function shortId(id: string): string {
 }
 
 function emptyStateLine(theme?: GraphTheme): string {
-  if (!theme) return "  no in-flight runs";
-  return `  ${hexToAnsi(theme.dim)}no in-flight runs${RESET}`;
+  if (!theme) return "  no workflow runs in current session";
+  return `  ${hexToAnsi(theme.dim)}no workflow runs in current session${RESET}`;
 }
 
 function statusIconForRun(run: RunSnapshot): string {

package/dist/builtin/workflows/src/tui/store-widget-installer.ts

@@ -1,26 +1,43 @@
 /**
- * Widget installer — wires the orchestrator's above-editor widget to the
- * workflow store, mirroring the eager `setWidget + requestRender` pattern
- * from nicobailon/pi-subagents src/tui/render.ts `renderWidget`.
+ * Widget installer — wires the orchestrator's below-editor widget to the
+ * workflow store using a single long-lived component that is updated in
+ * place (issue #1109).
+ *
+ * Placement note (belowEditor, not aboveEditor): the widget renders a live
+ * elapsed clock that re-renders every second. pi-tui full-clears the screen +
+ * scrollback whenever a changed line is above the viewport fold. An
+ * aboveEditor widget gets pushed above the fold once the bottom region grows
+ * tall, so each clock tick repainted the whole screen (the resize flicker in
+ * #1109). belowEditor keeps the widget among the last rendered lines (always
+ * within the bottom viewport), so the clock tick is a clean differential
+ * redraw. See the `setWidget` call site for the full rationale.
  *
  * Pattern:
- *   1. Every store mutation re-calls `ui.setWidget(WIDGET_KEY, factory)`
- *      with a *fresh* factory. Pi disposes the previous component,
- *      mounts the new one, and redraws. There is no long-lived component
- *      that subscribes to the store internally — that pattern leaves the
- *      widget visually stale after `up-arrow` history recall and similar
- *      editor events that force a re-render without a setWidget call.
- *   2. After `setWidget` we call `ui.requestRender()` to flush the new
- *      content immediately; pi-subagents does the same in its
- *      `rerenderWidget` helper.
- *   3. The widget contents are static per snapshot (no spinner), but the
+ *   1. The widget mounts once (`ui.setWidget(WIDGET_KEY, factory)`) on the
+ *      hidden→visible transition and unmounts once
+ *      (`ui.setWidget(WIDGET_KEY, undefined)`) on visible→hidden. Pi treats
+ *      every `setWidget` call as a full replacement — it disposes the
+ *      previous component, constructs a fresh one, rebuilds the widget
+ *      container, and redraws — so re-issuing `setWidget` on each store
+ *      mutation or clock tick produces a visible flicker. We therefore call
+ *      it only on real mount/unmount transitions.
+ *   2. For every other refresh — store mutations that change content and
+ *      the one-shot clock-refresh timer alike — we call `ui.requestRender()`
+ *      only. Pi re-invokes the *same* mounted component's `render(width)`
+ *      with no dispose/remount, so the elapsed-time label keeps ticking
+ *      smoothly without flicker.
+ *   3. The long-lived component reads the *latest* store snapshot through a
+ *      live getter (`() => currentSnap`) at render time, so it is never
+ *      visually stale — including after `up-arrow` history recall and other
+ *      editor events that force a host re-render without a `setWidget` call.
+ *   4. The mount / unmount / update / none decision is extracted into the
+ *      pure, unit-testable `decideWidgetAction`, keeping this module a thin
+ *      orchestration layer over a pure policy (SRP).
+ *   5. The widget contents are static per snapshot (no spinner), but the
  *      rendered lines include wall-clock labels (`3s`, `complete · 4s ago`)
  *      and recent-ended visibility. We therefore keep one lightweight
  *      one-shot refresh timer while the widget is visible, matching other
  *      live Atomic widgets without reintroducing a high-frequency spinner.
- *   4. The factory builds a pi-tui `Container` of `Text` children styled
- *      via pi's runtime `Theme` (theme.fg, theme.bold). This is what
- *      makes the widget visually distinct from chat content.
  */
 
 import type { Store } from "../shared/store.js";
@@ -80,16 +97,57 @@ function isStale(err: unknown): boolean {
   return err instanceof Error && err.message.includes(STALE_CONTEXT);
 }
 
+/** The four ways a refresh can reach (or skip) the terminal. */
+export type WidgetAction = "mount" | "unmount" | "update" | "none";
+
+export interface WidgetRenderState {
+  /** Whether the widget is currently mounted (factory installed via setWidget). */
+  readonly mounted: boolean;
+  /** Plain preview lines last rendered while mounted (empty when not mounted). */
+  readonly lines: readonly string[];
+}
+
+function linesEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
 /**
- * Build the widget factory closure. Pi invokes the factory with
- * `(this.ui, theme)` — we use the supplied theme to apply pi's terminal
- * palette to every span.
+ * Pure decision: given the previous mount state + previously rendered lines
+ * and the next preview lines, decide how a refresh should reach the terminal.
+ *  - hidden  → visible             => "mount"   (setWidget(factory))
+ *  - visible → hidden              => "unmount" (setWidget(undefined))
+ *  - visible → visible, changed    => "update"  (requestRender only — no remount)
+ *  - visible → visible, identical  => "none"    (skip the redundant repaint)
+ *  - hidden  → hidden              => "none"
+ *
+ * No UI/terminal dependency, so it is unit-testable without a real terminal.
  */
-function widgetFactory(snap: StoreSnapshot): WidgetFactory {
+export function decideWidgetAction(
+  prev: WidgetRenderState,
+  nextLines: readonly string[],
+): WidgetAction {
+  const nextVisible = nextLines.length > 0;
+  if (!prev.mounted) return nextVisible ? "mount" : "none";
+  if (!nextVisible) return "unmount";
+  return linesEqual(prev.lines, nextLines) ? "none" : "update";
+}
+
+/**
+ * Build the long-lived widget factory closure. Pi invokes the factory once
+ * with `(this.ui, theme)` at mount; the returned component is reused across
+ * renders. It closes over a *live* snapshot getter rather than a captured
+ * snapshot, so each `requestRender()` recomputes lines from the latest
+ * snapshot (and a fresh `Date.now()`) with no dispose/remount.
+ */
+function widgetFactory(getSnap: () => StoreSnapshot): WidgetFactory {
   return (_tui, theme) => {
     return {
       render: (width: number) =>
-        buildThemedWidgetLines(snap, theme as PiTheme | undefined, width),
+        buildThemedWidgetLines(getSnap(), theme as PiTheme | undefined, width),
     };
   };
 }
@@ -104,6 +162,12 @@ export function installStoreWidget(
 
   let disposed = false;
   let refreshTimer: TimerHandle | undefined;
+  // In-place widget state: whether the long-lived component is mounted, the
+  // latest snapshot it should render, and the last plain preview lines used
+  // to detect no-op refreshes.
+  let mounted = false;
+  let currentSnap: StoreSnapshot;
+  let lastLines: readonly string[] = [];
 
   const clearRefreshTimer = (): void => {
     if (refreshTimer === undefined) return;
@@ -125,16 +189,47 @@ export function installStoreWidget(
     if (disposed) return;
     clearRefreshTimer();
     try {
-      const snap = storeInstance.snapshot();
-      const previewLines = buildThemedWidgetLines(snap, undefined);
-      if (previewLines.length === 0) {
-        ui.setWidget?.(WIDGET_KEY, undefined);
-        ui.requestRender?.();
-        return;
+      currentSnap = storeInstance.snapshot();
+      const nextLines = buildThemedWidgetLines(currentSnap, undefined);
+      const action = decideWidgetAction({ mounted, lines: lastLines }, nextLines);
+
+      switch (action) {
+        case "mount":
+          // Mount the single long-lived component. It reads `currentSnap`
+          // through the getter on every subsequent render, so we never need
+          // to re-issue setWidget to refresh content.
+          ui.setWidget?.(WIDGET_KEY, widgetFactory(() => currentSnap), {
+            // belowEditor (not aboveEditor): the widget renders a live elapsed
+            // clock that re-renders every second. pi-tui's differential
+            // renderer does a full screen+scrollback clear whenever a *changed*
+            // line sits ABOVE the viewport fold (tui.js `firstChanged <
+            // prevViewportTop -> fullRender(true)`). An aboveEditor widget is
+            // pushed above the fold when the bottom region (usage meter,
+            // multi-line editor, below-editor widgets, footer) grows tall,
+            // so each clock tick then repainted the whole screen — the resize
+            // flicker in #1109. belowEditor keeps the widget among the last
+            // rendered lines (always within the bottom viewport), so its
+            // per-second tick is a clean in-place differential redraw.
+            placement: "belowEditor",
+          });
+          ui.requestRender?.();
+          mounted = true;
+          break;
+        case "unmount":
+          ui.setWidget?.(WIDGET_KEY, undefined);
+          ui.requestRender?.();
+          mounted = false;
+          break;
+        case "update":
+          // In place — NO setWidget, NO dispose/remount (the #1109 flicker fix).
+          ui.requestRender?.();
+          break;
+        case "none":
+          break;
       }
-      ui.setWidget?.(WIDGET_KEY, widgetFactory(snap), { placement: "aboveEditor" });
-      ui.requestRender?.();
-      scheduleRefresh(snap);
+
+      lastLines = nextLines;
+      scheduleRefresh(currentSnap);
     } catch (err) {
       if (isStale(err)) return;
       throw err;

package/dist/config.d.ts

@@ -78,6 +78,7 @@ export declare const ENV_SHARE_VIEWER_URL: string;
 export declare const ENV_CLEAR_ON_SHRINK: string;
 export declare const ENV_HARDWARE_CURSOR: string;
 export declare const ENV_TIMING: string;
+export declare const WORKFLOW_STAGE_SUBAGENT_GUARD_ENV: string;
 export declare function getEnvNames(name: string): string[];
 export declare function getEnvValue(name: string): string | undefined;
 export declare function hasEnvValue(name: string): boolean;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["import { accessSync, constants, existsSync, readFileSync, realpathSync } from \"fs\";\nimport { homedir } from \"os\";\nimport { basename, dirname, join, resolve, sep, win32 } from \"path\";\nimport { fileURLToPath } from \"url\";\nimport { spawnProcessSync } from \"./utils/child-process.ts\";\nimport { normalizePath } from \"./utils/paths.ts\";\n\n// =============================================================================\n// Package Detection\n// =============================================================================\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\n/**\n * Detect if we're running as a Bun compiled binary.\n * Bun binaries have import.meta.url containing \"$bunfs\", \"~BUN\", or \"%7EBUN\" (Bun's virtual filesystem path)\n */\nexport const isBunBinary =\n\timport.meta.url.includes(\"$bunfs\") || import.meta.url.includes(\"~BUN\") || import.meta.url.includes(\"%7EBUN\");\n\n/** Detect if Bun is the runtime (compiled binary or bun run) */\nexport const isBunRuntime = !!process.versions.bun;\n\n// =============================================================================\n// Install Method Detection\n// =============================================================================\n\nexport type InstallMethod = \"bun-binary\" | \"npm\" | \"pnpm\" | \"yarn\" | \"bun\" | \"unknown\";\n\ninterface SelfUpdateCommandStep {\n\tcommand: string;\n\targs: string[];\n\tdisplay: string;\n}\n\nexport interface SelfUpdateCommand extends SelfUpdateCommandStep {\n\tsteps?: SelfUpdateCommandStep[];\n}\n\nfunction makeSelfUpdateCommand(\n\tinstallStep: SelfUpdateCommandStep,\n\tuninstallStep?: SelfUpdateCommandStep,\n): SelfUpdateCommand {\n\tif (!uninstallStep) return installStep;\n\treturn {\n\t\t...installStep,\n\t\tdisplay: `${uninstallStep.display} && ${installStep.display}`,\n\t\tsteps: [uninstallStep, installStep],\n\t};\n}\n\nfunction makeSelfUpdateCommandStep(command: string, args: string[]): SelfUpdateCommandStep {\n\treturn {\n\t\tcommand,\n\t\targs,\n\t\tdisplay: [command, ...args].map((arg) => (/\\s/.test(arg) ? `\"${arg}\"` : arg)).join(\" \"),\n\t};\n}\n\nexport function detectInstallMethod(): InstallMethod {\n\tif (isBunBinary) {\n\t\treturn \"bun-binary\";\n\t}\n\n\tconst resolvedPath = `${__dirname}\\0${process.execPath || \"\"}`.toLowerCase().replace(/\\\\/g, \"/\");\n\n\tif (resolvedPath.includes(\"/pnpm/\") || resolvedPath.includes(\"/.pnpm/\")) {\n\t\treturn \"pnpm\";\n\t}\n\tif (resolvedPath.includes(\"/yarn/\") || resolvedPath.includes(\"/.yarn/\")) {\n\t\treturn \"yarn\";\n\t}\n\tif (isBunRuntime || resolvedPath.includes(\"/install/global/node_modules/\")) {\n\t\treturn \"bun\";\n\t}\n\tif (resolvedPath.includes(\"/npm/\") || resolvedPath.includes(\"/node_modules/\")) {\n\t\treturn \"npm\";\n\t}\n\n\treturn \"unknown\";\n}\n\nfunction getInferredNpmInstall(): { root: string; prefix: string } | undefined {\n\tconst packageDir = getPackageDir();\n\tconst path = process.platform === \"win32\" || packageDir.includes(\"\\\\\") ? win32 : { basename, dirname };\n\tconst parent = path.dirname(packageDir);\n\tlet root: string | undefined;\n\tif (path.basename(parent).startsWith(\"@\") && path.basename(path.dirname(parent)) === \"node_modules\") {\n\t\troot = path.dirname(parent);\n\t} else if (path.basename(parent) === \"node_modules\") {\n\t\troot = parent;\n\t}\n\tif (!root) return undefined;\n\tconst rootParent = path.dirname(root);\n\tif (path.basename(rootParent) === \"lib\") return { root, prefix: path.dirname(rootParent) };\n\t// Windows global npm prefixes use `<prefix>\\\\node_modules`, which is\n\t// indistinguishable from local project installs by path shape alone. Do not\n\t// infer unsupported Windows custom prefixes without `npm root -g` evidence.\n\treturn undefined;\n}\n\nfunction getSelfUpdateCommandForMethod(\n\tmethod: InstallMethod,\n\tinstalledPackageName: string,\n\tupdatePackageName = installedPackageName,\n\tnpmCommand?: string[],\n): SelfUpdateCommand | undefined {\n\tswitch (method) {\n\t\tcase \"bun-binary\":\n\t\t\treturn undefined;\n\t\tcase \"pnpm\":\n\t\t\treturn makeSelfUpdateCommand(\n\t\t\t\tmakeSelfUpdateCommandStep(\"pnpm\", [\"install\", \"-g\", \"--ignore-scripts\", updatePackageName]),\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(\"pnpm\", [\"remove\", \"-g\", installedPackageName]),\n\t\t\t);\n\t\tcase \"yarn\":\n\t\t\treturn makeSelfUpdateCommand(\n\t\t\t\tmakeSelfUpdateCommandStep(\"yarn\", [\"global\", \"add\", \"--ignore-scripts\", updatePackageName]),\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(\"yarn\", [\"global\", \"remove\", installedPackageName]),\n\t\t\t);\n\t\tcase \"bun\":\n\t\t\treturn makeSelfUpdateCommand(\n\t\t\t\tmakeSelfUpdateCommandStep(\"bun\", [\"install\", \"-g\", \"--ignore-scripts\", updatePackageName]),\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(\"bun\", [\"uninstall\", \"-g\", installedPackageName]),\n\t\t\t);\n\t\tcase \"npm\": {\n\t\t\tconst [command = \"npm\", ...npmArgs] = npmCommand ?? [];\n\t\t\tconst inferred = npmCommand?.length ? undefined : getInferredNpmInstall();\n\t\t\tconst prefixArgs = [...npmArgs, ...(inferred ? [\"--prefix\", inferred.prefix] : [])];\n\t\t\tconst installStep = makeSelfUpdateCommandStep(command, [\n\t\t\t\t...prefixArgs,\n\t\t\t\t\"install\",\n\t\t\t\t\"-g\",\n\t\t\t\t\"--ignore-scripts\",\n\t\t\t\tupdatePackageName,\n\t\t\t]);\n\t\t\tconst uninstallStep =\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(command, [...prefixArgs, \"uninstall\", \"-g\", installedPackageName]);\n\t\t\treturn makeSelfUpdateCommand(installStep, uninstallStep);\n\t\t}\n\t\tcase \"unknown\":\n\t\t\treturn undefined;\n\t}\n}\n\nfunction readCommandOutput(\n\tcommand: string,\n\targs: string[],\n\toptions: { requireSuccess?: boolean } = {},\n): string | undefined {\n\tconst result = spawnProcessSync(command, args, {\n\t\tencoding: \"utf-8\",\n\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t});\n\tif (result.status === 0) return result.stdout.trim() || undefined;\n\tif (options.requireSuccess) {\n\t\tconst reason = result.error?.message || result.stderr.trim() || `exit code ${result.status ?? \"unknown\"}`;\n\t\tthrow new Error(`Failed to run ${[command, ...args].join(\" \")}: ${reason}`);\n\t}\n\treturn undefined;\n}\n\nfunction getGlobalPackageRoots(method: InstallMethod, _packageName: string, npmCommand?: string[]): string[] {\n\tswitch (method) {\n\t\tcase \"npm\": {\n\t\t\tconst configured = !!npmCommand?.length;\n\t\t\tconst [command = \"npm\", ...npmArgs] = npmCommand ?? [];\n\t\t\tif (configured && command === \"bun\") {\n\t\t\t\tconst bunBin = readCommandOutput(command, [...npmArgs, \"pm\", \"bin\", \"-g\"], {\n\t\t\t\t\trequireSuccess: true,\n\t\t\t\t});\n\t\t\t\tconst roots = [join(homedir(), \".bun\", \"install\", \"global\", \"node_modules\")];\n\t\t\t\tif (bunBin) {\n\t\t\t\t\troots.push(join(dirname(bunBin), \"install\", \"global\", \"node_modules\"));\n\t\t\t\t}\n\t\t\t\treturn roots;\n\t\t\t}\n\t\t\tconst root = readCommandOutput(command, [...npmArgs, \"root\", \"-g\"], {\n\t\t\t\trequireSuccess: configured,\n\t\t\t});\n\t\t\tconst inferred = configured ? undefined : getInferredNpmInstall();\n\t\t\treturn [root, inferred?.root].filter((x): x is string => !!x);\n\t\t}\n\t\tcase \"pnpm\": {\n\t\t\tconst root = readCommandOutput(\"pnpm\", [\"root\", \"-g\"]);\n\t\t\treturn root ? [root, dirname(root)] : [];\n\t\t}\n\t\tcase \"yarn\": {\n\t\t\tconst dir = readCommandOutput(\"yarn\", [\"global\", \"dir\"]);\n\t\t\treturn dir ? [dir, join(dir, \"node_modules\")] : [];\n\t\t}\n\t\tcase \"bun\": {\n\t\t\tconst bunBin = readCommandOutput(\"bun\", [\"pm\", \"bin\", \"-g\"]);\n\t\t\tconst roots = [join(homedir(), \".bun\", \"install\", \"global\", \"node_modules\")];\n\t\t\tif (bunBin) {\n\t\t\t\troots.push(join(dirname(bunBin), \"install\", \"global\", \"node_modules\"));\n\t\t\t}\n\t\t\treturn roots;\n\t\t}\n\t\tcase \"bun-binary\":\n\t\tcase \"unknown\":\n\t\t\treturn [];\n\t}\n}\n\nfunction normalizeExistingPathForComparison(path: string, resolveSymlinks: boolean): string | undefined {\n\tconst resolvedPath = resolve(path);\n\tif (!existsSync(resolvedPath)) {\n\t\treturn undefined;\n\t}\n\tlet normalizedPath = resolvedPath;\n\tif (resolveSymlinks) {\n\t\ttry {\n\t\t\tnormalizedPath = realpathSync(resolvedPath);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\tif (process.platform === \"win32\") {\n\t\tnormalizedPath = normalizedPath.toLowerCase();\n\t}\n\treturn normalizedPath;\n}\n\nfunction getPathComparisonCandidates(path: string): string[] {\n\treturn Array.from(\n\t\tnew Set(\n\t\t\t[normalizeExistingPathForComparison(path, false), normalizeExistingPathForComparison(path, true)].filter(\n\t\t\t\t(candidate): candidate is string => !!candidate,\n\t\t\t),\n\t\t),\n\t);\n}\n\nfunction getEntrypointPackageDir(): string | undefined {\n\tconst entrypoint = process.argv[1];\n\tif (!entrypoint) return undefined;\n\tlet dir = dirname(entrypoint);\n\twhile (dir !== dirname(dir)) {\n\t\tif (existsSync(join(dir, \"package.json\"))) {\n\t\t\treturn dir;\n\t\t}\n\t\tdir = dirname(dir);\n\t}\n\treturn undefined;\n}\n\nfunction isSelfUpdatePathWritable(): boolean {\n\tconst packageDir = getPackageDir();\n\ttry {\n\t\taccessSync(packageDir, constants.W_OK);\n\t\taccessSync(dirname(packageDir), constants.W_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction isManagedByGlobalPackageManager(method: InstallMethod, packageName: string, npmCommand?: string[]): boolean {\n\tconst packageDirs = [getPackageDir(), getEntrypointPackageDir()].filter((dir): dir is string => !!dir);\n\tconst packageDirCandidates = packageDirs.flatMap((dir) => getPathComparisonCandidates(dir));\n\treturn getGlobalPackageRoots(method, packageName, npmCommand).some((root) => {\n\t\treturn getPathComparisonCandidates(root).some((normalizedRoot) => {\n\t\t\tconst rootPrefix = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;\n\t\t\treturn packageDirCandidates.some((packageDir) => packageDir.startsWith(rootPrefix));\n\t\t});\n\t});\n}\n\nexport function getSelfUpdateCommand(\n\tpackageName: string,\n\tnpmCommand?: string[],\n\tupdatePackageName = packageName,\n): SelfUpdateCommand | undefined {\n\tconst method = detectInstallMethod();\n\tconst command = getSelfUpdateCommandForMethod(method, packageName, updatePackageName, npmCommand);\n\tif (!command || !isManagedByGlobalPackageManager(method, packageName, npmCommand) || !isSelfUpdatePathWritable()) {\n\t\treturn undefined;\n\t}\n\treturn command;\n}\n\nexport function getSelfUpdateUnavailableInstruction(\n\tpackageName: string,\n\tnpmCommand?: string[],\n\tupdatePackageName = packageName,\n): string {\n\tconst method = detectInstallMethod();\n\tif (method === \"bun-binary\") {\n\t\treturn `Download from: https://github.com/earendil-works/pi-mono/releases/latest`;\n\t}\n\tconst command = getSelfUpdateCommandForMethod(method, packageName, updatePackageName, npmCommand);\n\tif (command) {\n\t\tif (isManagedByGlobalPackageManager(method, packageName, npmCommand) && !isSelfUpdatePathWritable()) {\n\t\t\treturn `This installation is managed by a global ${method} install, but the install path is not writable. Update it yourself with: ${command.display}`;\n\t\t}\n\t\treturn `This installation is not managed by a global ${method} install. Update it with the package manager, wrapper, or source checkout that provides it.`;\n\t}\n\treturn `Update ${updatePackageName} using the package manager, wrapper, or source checkout that provides this installation.`;\n}\n\nexport function getUpdateInstruction(packageName: string): string {\n\tconst method = detectInstallMethod();\n\tconst command = getSelfUpdateCommandForMethod(method, packageName);\n\tif (command) {\n\t\treturn `Run: ${command.display}`;\n\t}\n\treturn getSelfUpdateUnavailableInstruction(packageName);\n}\n\n// =============================================================================\n// Package Asset Paths (shipped with executable)\n// =============================================================================\n\n/**\n * Get the base directory for resolving package assets (themes, package.json, README.md, CHANGELOG.md).\n * - For Bun binary: returns the directory containing the executable\n * - For Node.js (dist/): returns __dirname (the dist/ directory)\n * - For tsx (src/): returns parent directory (the package root)\n */\nexport function getPackageDir(): string {\n\t// Allow override via environment variable (useful for Nix/Guix where store paths tokenize poorly).\n\t// This runs before package.json app config is read, so the env var name is hardcoded.\n\tconst envDir = process.env.ATOMIC_PACKAGE_DIR ?? process.env.PI_PACKAGE_DIR;\n\tif (envDir) {\n\t\treturn normalizePath(envDir);\n\t}\n\n\tif (isBunBinary) {\n\t\t// Bun binary: process.execPath points to the compiled executable\n\t\treturn dirname(process.execPath);\n\t}\n\t// Node.js: walk up from __dirname until we find package.json\n\tlet dir = __dirname;\n\twhile (dir !== dirname(dir)) {\n\t\tif (existsSync(join(dir, \"package.json\"))) {\n\t\t\treturn dir;\n\t\t}\n\t\tdir = dirname(dir);\n\t}\n\t// Fallback (shouldn't happen)\n\treturn __dirname;\n}\n\n/**\n * Get path to built-in themes directory (shipped with package)\n * - For Bun binary: theme/ next to executable\n * - For Node.js (dist/): dist/modes/interactive/theme/\n * - For tsx (src/): src/modes/interactive/theme/\n */\nexport function getThemesDir(): string {\n\tif (isBunBinary) {\n\t\treturn join(getPackageDir(), \"theme\");\n\t}\n\t// Theme is in modes/interactive/theme/ relative to src/ or dist/\n\tconst packageDir = getPackageDir();\n\tconst srcOrDist = existsSync(join(packageDir, \"src\")) ? \"src\" : \"dist\";\n\treturn join(packageDir, srcOrDist, \"modes\", \"interactive\", \"theme\");\n}\n\n/**\n * Get path to HTML export template directory (shipped with package)\n * - For Bun binary: export-html/ next to executable\n * - For Node.js (dist/): dist/core/export-html/\n * - For tsx (src/): src/core/export-html/\n */\nexport function getExportTemplateDir(): string {\n\tif (isBunBinary) {\n\t\treturn join(getPackageDir(), \"export-html\");\n\t}\n\tconst packageDir = getPackageDir();\n\tconst srcOrDist = existsSync(join(packageDir, \"src\")) ? \"src\" : \"dist\";\n\treturn join(packageDir, srcOrDist, \"core\", \"export-html\");\n}\n\n/** Get path to package.json */\nexport function getPackageJsonPath(): string {\n\treturn join(getPackageDir(), \"package.json\");\n}\n\n/** Get path to README.md */\nexport function getReadmePath(): string {\n\treturn resolve(join(getPackageDir(), \"README.md\"));\n}\n\n/** Get path to docs directory */\nexport function getDocsPath(): string {\n\treturn resolve(join(getPackageDir(), \"docs\"));\n}\n\n/** Get path to examples directory */\nexport function getExamplesPath(): string {\n\treturn resolve(join(getPackageDir(), \"examples\"));\n}\n\n/** Get path to CHANGELOG.md */\nexport function getChangelogPath(): string {\n\treturn resolve(join(getPackageDir(), \"CHANGELOG.md\"));\n}\n\n/**\n * Get path to built-in interactive assets directory.\n * - For Bun binary: assets/ next to executable\n * - For Node.js (dist/): dist/modes/interactive/assets/\n * - For tsx (src/): src/modes/interactive/assets/\n */\nexport function getInteractiveAssetsDir(): string {\n\tif (isBunBinary) {\n\t\treturn join(getPackageDir(), \"assets\");\n\t}\n\tconst packageDir = getPackageDir();\n\tconst srcOrDist = existsSync(join(packageDir, \"src\")) ? \"src\" : \"dist\";\n\treturn join(packageDir, srcOrDist, \"modes\", \"interactive\", \"assets\");\n}\n\n/** Get path to a bundled interactive asset */\nexport function getBundledInteractiveAssetPath(name: string): string {\n\treturn join(getInteractiveAssetsDir(), name);\n}\n\n// =============================================================================\n// App Config (from package.json <appName>Config, with piConfig as a legacy shim)\n// =============================================================================\n\ninterface AppConfig {\n\tname?: string;\n\tconfigDir?: string;\n\tchangelogUrl?: string;\n}\n\ninterface PackageJson extends Record<string, unknown> {\n\tname?: string;\n\tversion?: string;\n\tpiConfig?: AppConfig;\n}\n\nconst pkg = JSON.parse(readFileSync(getPackageJsonPath(), \"utf-8\")) as PackageJson;\n\nfunction appNameFromPackageName(packageName: string | undefined): string | undefined {\n\tconst localName = packageName?.split(\"/\").pop()?.trim();\n\treturn localName && localName.length > 0 ? localName : undefined;\n}\n\nfunction readAppConfig(packageJson: PackageJson, appName: string | undefined): AppConfig | undefined {\n\tif (appName) {\n\t\tconst appConfig = packageJson[`${appName}Config`];\n\t\tif (appConfig && typeof appConfig === \"object\" && !Array.isArray(appConfig)) {\n\t\t\treturn appConfig as AppConfig;\n\t\t}\n\t}\n\treturn packageJson.piConfig;\n}\n\nexport const PACKAGE_NAME: string = pkg.name || \"@bastani/atomic\";\nconst packageAppName = appNameFromPackageName(PACKAGE_NAME);\nconst appConfig = readAppConfig(pkg, packageAppName);\nexport const APP_NAME: string = appConfig?.name || packageAppName || \"pi\";\nexport const APP_TITLE: string = appConfig?.name !== undefined || APP_NAME !== \"pi\" ? APP_NAME : \"π\";\nexport const CONFIG_DIR_NAME: string = appConfig?.configDir || (APP_NAME === \"pi\" ? \".pi\" : `.${APP_NAME}`);\nexport const LEGACY_CONFIG_DIR_NAME = \".pi\";\nexport const CONFIG_DIR_NAMES: readonly string[] =\n\tCONFIG_DIR_NAME === LEGACY_CONFIG_DIR_NAME ? [CONFIG_DIR_NAME] : [CONFIG_DIR_NAME, LEGACY_CONFIG_DIR_NAME];\nexport const VERSION: string = pkg.version || \"0.0.0\";\nexport const CHANGELOG_URL: string | undefined = appConfig?.changelogUrl?.trim() || undefined;\n\nconst ENV_PREFIX = APP_NAME.toUpperCase();\nexport const LEGACY_ENV_PREFIX = \"PI\";\n\n// e.g., ATOMIC_CODING_AGENT_DIR (with PI_CODING_AGENT_DIR as a compatibility alias)\nexport const ENV_AGENT_DIR = `${ENV_PREFIX}_CODING_AGENT_DIR`;\nexport const ENV_SESSION_DIR = `${ENV_PREFIX}_CODING_AGENT_SESSION_DIR`;\nexport const ENV_PACKAGE_DIR = `${ENV_PREFIX}_PACKAGE_DIR`;\nexport const ENV_OFFLINE = `${ENV_PREFIX}_OFFLINE`;\nexport const ENV_SKIP_VERSION_CHECK = `${ENV_PREFIX}_SKIP_VERSION_CHECK`;\nexport const ENV_STARTUP_BENCHMARK = `${ENV_PREFIX}_STARTUP_BENCHMARK`;\nexport const ENV_TELEMETRY = `${ENV_PREFIX}_TELEMETRY`;\nexport const ENV_SHARE_VIEWER_URL = `${ENV_PREFIX}_SHARE_VIEWER_URL`;\nexport const ENV_CLEAR_ON_SHRINK = `${ENV_PREFIX}_CLEAR_ON_SHRINK`;\nexport const ENV_HARDWARE_CURSOR = `${ENV_PREFIX}_HARDWARE_CURSOR`;\nexport const ENV_TIMING = `${ENV_PREFIX}_TIMING`;\n\nexport function getEnvNames(name: string): string[] {\n\tif (ENV_PREFIX === LEGACY_ENV_PREFIX || !name.startsWith(`${ENV_PREFIX}_`)) return [name];\n\treturn [name, `${LEGACY_ENV_PREFIX}_${name.slice(ENV_PREFIX.length + 1)}`];\n}\n\nexport function getEnvValue(name: string): string | undefined {\n\tfor (const candidate of getEnvNames(name)) {\n\t\tconst value = process.env[candidate];\n\t\tif (value !== undefined) return value;\n\t}\n\treturn undefined;\n}\n\nexport function hasEnvValue(name: string): boolean {\n\treturn getEnvValue(name) !== undefined;\n}\n\nexport function setEnvValue(name: string, value: string): void {\n\tprocess.env[name] = value;\n}\n\nexport function expandTildePath(path: string): string {\n\treturn normalizePath(path);\n}\n\nconst DEFAULT_SHARE_VIEWER_URL = \"https://pi.dev/session/\";\n\n/** Get the share viewer URL for a gist ID */\nexport function getShareViewerUrl(gistId: string): string {\n\tconst baseUrl = getEnvValue(ENV_SHARE_VIEWER_URL) || DEFAULT_SHARE_VIEWER_URL;\n\treturn `${baseUrl}#${gistId}`;\n}\n\n// =============================================================================\n// User Config Paths (~/.atomic/agent/*)\n// =============================================================================\n\n/** Get the agent config directory (e.g., ~/.atomic/agent/) */\nexport function getAgentDir(): string {\n\tconst envDir = getEnvValue(ENV_AGENT_DIR);\n\tif (envDir) {\n\t\treturn expandTildePath(envDir);\n\t}\n\treturn join(homedir(), CONFIG_DIR_NAME, \"agent\");\n}\n\n/** Get the legacy pi agent config directory (e.g., ~/.pi/agent/) */\nexport function getLegacyAgentDir(): string {\n\treturn join(homedir(), LEGACY_CONFIG_DIR_NAME, \"agent\");\n}\n\n/** Get agent config directories in precedence order (primary first, then legacy). */\nexport function getAgentDirs(): string[] {\n\tconst primary = getAgentDir();\n\tif (hasEnvValue(ENV_AGENT_DIR) || CONFIG_DIR_NAME === LEGACY_CONFIG_DIR_NAME) {\n\t\treturn [primary];\n\t}\n\tconst legacy = getLegacyAgentDir();\n\treturn legacy === primary ? [primary] : [primary, legacy];\n}\n\n/** Get user config root directories in precedence order (primary first, then legacy). */\nexport function getUserConfigDirs(): string[] {\n\treturn CONFIG_DIR_NAMES.map((name) => join(homedir(), name));\n}\n\n/** Get project config directories in precedence order (primary first, then legacy). */\nexport function getProjectConfigDirs(cwd: string): string[] {\n\treturn CONFIG_DIR_NAMES.map((name) => join(cwd, name));\n}\n\n/** Get a path inside every user config root directory. */\nexport function getUserConfigPaths(...segments: string[]): string[] {\n\treturn getUserConfigDirs().map((dir) => join(dir, ...segments));\n}\n\n/** Get a path inside every agent config directory. */\nexport function getAgentConfigPaths(...segments: string[]): string[] {\n\treturn getAgentDirs().map((dir) => join(dir, ...segments));\n}\n\n/** Get a path inside every project config directory. */\nexport function getProjectConfigPaths(cwd: string, ...segments: string[]): string[] {\n\treturn getProjectConfigDirs(cwd).map((dir) => join(dir, ...segments));\n}\n\n/** Get path to user's custom themes directory */\nexport function getCustomThemesDir(): string {\n\treturn join(getAgentDir(), \"themes\");\n}\n\n/** Get path to models.json */\nexport function getModelsPath(): string {\n\treturn join(getAgentDir(), \"models.json\");\n}\n\n/** Get path to auth.json */\nexport function getAuthPath(): string {\n\treturn join(getAgentDir(), \"auth.json\");\n}\n\n/** Get path to settings.json */\nexport function getSettingsPath(): string {\n\treturn join(getAgentDir(), \"settings.json\");\n}\n\n/** Get path to tools directory */\nexport function getToolsDir(): string {\n\treturn join(getAgentDir(), \"tools\");\n}\n\n/** Get path to managed binaries directory (fd, rg) */\nexport function getBinDir(): string {\n\treturn join(getAgentDir(), \"bin\");\n}\n\n/** Get path to prompt templates directory */\nexport function getPromptsDir(): string {\n\treturn join(getAgentDir(), \"prompts\");\n}\n\n/** Get path to sessions directory */\nexport function getSessionsDir(): string {\n\treturn join(getAgentDir(), \"sessions\");\n}\n\n/** Get path to debug log file */\nexport function getDebugLogPath(): string {\n\treturn join(getAgentDir(), `${APP_NAME}-debug.log`);\n}\n"]}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["import { accessSync, constants, existsSync, readFileSync, realpathSync } from \"fs\";\nimport { homedir } from \"os\";\nimport { basename, dirname, join, resolve, sep, win32 } from \"path\";\nimport { fileURLToPath } from \"url\";\nimport { spawnProcessSync } from \"./utils/child-process.ts\";\nimport { normalizePath } from \"./utils/paths.ts\";\n\n// =============================================================================\n// Package Detection\n// =============================================================================\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\n/**\n * Detect if we're running as a Bun compiled binary.\n * Bun binaries have import.meta.url containing \"$bunfs\", \"~BUN\", or \"%7EBUN\" (Bun's virtual filesystem path)\n */\nexport const isBunBinary =\n\timport.meta.url.includes(\"$bunfs\") || import.meta.url.includes(\"~BUN\") || import.meta.url.includes(\"%7EBUN\");\n\n/** Detect if Bun is the runtime (compiled binary or bun run) */\nexport const isBunRuntime = !!process.versions.bun;\n\n// =============================================================================\n// Install Method Detection\n// =============================================================================\n\nexport type InstallMethod = \"bun-binary\" | \"npm\" | \"pnpm\" | \"yarn\" | \"bun\" | \"unknown\";\n\ninterface SelfUpdateCommandStep {\n\tcommand: string;\n\targs: string[];\n\tdisplay: string;\n}\n\nexport interface SelfUpdateCommand extends SelfUpdateCommandStep {\n\tsteps?: SelfUpdateCommandStep[];\n}\n\nfunction makeSelfUpdateCommand(\n\tinstallStep: SelfUpdateCommandStep,\n\tuninstallStep?: SelfUpdateCommandStep,\n): SelfUpdateCommand {\n\tif (!uninstallStep) return installStep;\n\treturn {\n\t\t...installStep,\n\t\tdisplay: `${uninstallStep.display} && ${installStep.display}`,\n\t\tsteps: [uninstallStep, installStep],\n\t};\n}\n\nfunction makeSelfUpdateCommandStep(command: string, args: string[]): SelfUpdateCommandStep {\n\treturn {\n\t\tcommand,\n\t\targs,\n\t\tdisplay: [command, ...args].map((arg) => (/\\s/.test(arg) ? `\"${arg}\"` : arg)).join(\" \"),\n\t};\n}\n\nexport function detectInstallMethod(): InstallMethod {\n\tif (isBunBinary) {\n\t\treturn \"bun-binary\";\n\t}\n\n\tconst resolvedPath = `${__dirname}\\0${process.execPath || \"\"}`.toLowerCase().replace(/\\\\/g, \"/\");\n\n\tif (resolvedPath.includes(\"/pnpm/\") || resolvedPath.includes(\"/.pnpm/\")) {\n\t\treturn \"pnpm\";\n\t}\n\tif (resolvedPath.includes(\"/yarn/\") || resolvedPath.includes(\"/.yarn/\")) {\n\t\treturn \"yarn\";\n\t}\n\tif (isBunRuntime || resolvedPath.includes(\"/install/global/node_modules/\")) {\n\t\treturn \"bun\";\n\t}\n\tif (resolvedPath.includes(\"/npm/\") || resolvedPath.includes(\"/node_modules/\")) {\n\t\treturn \"npm\";\n\t}\n\n\treturn \"unknown\";\n}\n\nfunction getInferredNpmInstall(): { root: string; prefix: string } | undefined {\n\tconst packageDir = getPackageDir();\n\tconst path = process.platform === \"win32\" || packageDir.includes(\"\\\\\") ? win32 : { basename, dirname };\n\tconst parent = path.dirname(packageDir);\n\tlet root: string | undefined;\n\tif (path.basename(parent).startsWith(\"@\") && path.basename(path.dirname(parent)) === \"node_modules\") {\n\t\troot = path.dirname(parent);\n\t} else if (path.basename(parent) === \"node_modules\") {\n\t\troot = parent;\n\t}\n\tif (!root) return undefined;\n\tconst rootParent = path.dirname(root);\n\tif (path.basename(rootParent) === \"lib\") return { root, prefix: path.dirname(rootParent) };\n\t// Windows global npm prefixes use `<prefix>\\\\node_modules`, which is\n\t// indistinguishable from local project installs by path shape alone. Do not\n\t// infer unsupported Windows custom prefixes without `npm root -g` evidence.\n\treturn undefined;\n}\n\nfunction getSelfUpdateCommandForMethod(\n\tmethod: InstallMethod,\n\tinstalledPackageName: string,\n\tupdatePackageName = installedPackageName,\n\tnpmCommand?: string[],\n): SelfUpdateCommand | undefined {\n\tswitch (method) {\n\t\tcase \"bun-binary\":\n\t\t\treturn undefined;\n\t\tcase \"pnpm\":\n\t\t\treturn makeSelfUpdateCommand(\n\t\t\t\tmakeSelfUpdateCommandStep(\"pnpm\", [\"install\", \"-g\", \"--ignore-scripts\", updatePackageName]),\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(\"pnpm\", [\"remove\", \"-g\", installedPackageName]),\n\t\t\t);\n\t\tcase \"yarn\":\n\t\t\treturn makeSelfUpdateCommand(\n\t\t\t\tmakeSelfUpdateCommandStep(\"yarn\", [\"global\", \"add\", \"--ignore-scripts\", updatePackageName]),\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(\"yarn\", [\"global\", \"remove\", installedPackageName]),\n\t\t\t);\n\t\tcase \"bun\":\n\t\t\treturn makeSelfUpdateCommand(\n\t\t\t\tmakeSelfUpdateCommandStep(\"bun\", [\"install\", \"-g\", \"--ignore-scripts\", updatePackageName]),\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(\"bun\", [\"uninstall\", \"-g\", installedPackageName]),\n\t\t\t);\n\t\tcase \"npm\": {\n\t\t\tconst [command = \"npm\", ...npmArgs] = npmCommand ?? [];\n\t\t\tconst inferred = npmCommand?.length ? undefined : getInferredNpmInstall();\n\t\t\tconst prefixArgs = [...npmArgs, ...(inferred ? [\"--prefix\", inferred.prefix] : [])];\n\t\t\tconst installStep = makeSelfUpdateCommandStep(command, [\n\t\t\t\t...prefixArgs,\n\t\t\t\t\"install\",\n\t\t\t\t\"-g\",\n\t\t\t\t\"--ignore-scripts\",\n\t\t\t\tupdatePackageName,\n\t\t\t]);\n\t\t\tconst uninstallStep =\n\t\t\t\tupdatePackageName === installedPackageName\n\t\t\t\t\t? undefined\n\t\t\t\t\t: makeSelfUpdateCommandStep(command, [...prefixArgs, \"uninstall\", \"-g\", installedPackageName]);\n\t\t\treturn makeSelfUpdateCommand(installStep, uninstallStep);\n\t\t}\n\t\tcase \"unknown\":\n\t\t\treturn undefined;\n\t}\n}\n\nfunction readCommandOutput(\n\tcommand: string,\n\targs: string[],\n\toptions: { requireSuccess?: boolean } = {},\n): string | undefined {\n\tconst result = spawnProcessSync(command, args, {\n\t\tencoding: \"utf-8\",\n\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t});\n\tif (result.status === 0) return result.stdout.trim() || undefined;\n\tif (options.requireSuccess) {\n\t\tconst reason = result.error?.message || result.stderr.trim() || `exit code ${result.status ?? \"unknown\"}`;\n\t\tthrow new Error(`Failed to run ${[command, ...args].join(\" \")}: ${reason}`);\n\t}\n\treturn undefined;\n}\n\nfunction getGlobalPackageRoots(method: InstallMethod, _packageName: string, npmCommand?: string[]): string[] {\n\tswitch (method) {\n\t\tcase \"npm\": {\n\t\t\tconst configured = !!npmCommand?.length;\n\t\t\tconst [command = \"npm\", ...npmArgs] = npmCommand ?? [];\n\t\t\tif (configured && command === \"bun\") {\n\t\t\t\tconst bunBin = readCommandOutput(command, [...npmArgs, \"pm\", \"bin\", \"-g\"], {\n\t\t\t\t\trequireSuccess: true,\n\t\t\t\t});\n\t\t\t\tconst roots = [join(homedir(), \".bun\", \"install\", \"global\", \"node_modules\")];\n\t\t\t\tif (bunBin) {\n\t\t\t\t\troots.push(join(dirname(bunBin), \"install\", \"global\", \"node_modules\"));\n\t\t\t\t}\n\t\t\t\treturn roots;\n\t\t\t}\n\t\t\tconst root = readCommandOutput(command, [...npmArgs, \"root\", \"-g\"], {\n\t\t\t\trequireSuccess: configured,\n\t\t\t});\n\t\t\tconst inferred = configured ? undefined : getInferredNpmInstall();\n\t\t\treturn [root, inferred?.root].filter((x): x is string => !!x);\n\t\t}\n\t\tcase \"pnpm\": {\n\t\t\tconst root = readCommandOutput(\"pnpm\", [\"root\", \"-g\"]);\n\t\t\treturn root ? [root, dirname(root)] : [];\n\t\t}\n\t\tcase \"yarn\": {\n\t\t\tconst dir = readCommandOutput(\"yarn\", [\"global\", \"dir\"]);\n\t\t\treturn dir ? [dir, join(dir, \"node_modules\")] : [];\n\t\t}\n\t\tcase \"bun\": {\n\t\t\tconst bunBin = readCommandOutput(\"bun\", [\"pm\", \"bin\", \"-g\"]);\n\t\t\tconst roots = [join(homedir(), \".bun\", \"install\", \"global\", \"node_modules\")];\n\t\t\tif (bunBin) {\n\t\t\t\troots.push(join(dirname(bunBin), \"install\", \"global\", \"node_modules\"));\n\t\t\t}\n\t\t\treturn roots;\n\t\t}\n\t\tcase \"bun-binary\":\n\t\tcase \"unknown\":\n\t\t\treturn [];\n\t}\n}\n\nfunction normalizeExistingPathForComparison(path: string, resolveSymlinks: boolean): string | undefined {\n\tconst resolvedPath = resolve(path);\n\tif (!existsSync(resolvedPath)) {\n\t\treturn undefined;\n\t}\n\tlet normalizedPath = resolvedPath;\n\tif (resolveSymlinks) {\n\t\ttry {\n\t\t\tnormalizedPath = realpathSync(resolvedPath);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\tif (process.platform === \"win32\") {\n\t\tnormalizedPath = normalizedPath.toLowerCase();\n\t}\n\treturn normalizedPath;\n}\n\nfunction getPathComparisonCandidates(path: string): string[] {\n\treturn Array.from(\n\t\tnew Set(\n\t\t\t[normalizeExistingPathForComparison(path, false), normalizeExistingPathForComparison(path, true)].filter(\n\t\t\t\t(candidate): candidate is string => !!candidate,\n\t\t\t),\n\t\t),\n\t);\n}\n\nfunction getEntrypointPackageDir(): string | undefined {\n\tconst entrypoint = process.argv[1];\n\tif (!entrypoint) return undefined;\n\tlet dir = dirname(entrypoint);\n\twhile (dir !== dirname(dir)) {\n\t\tif (existsSync(join(dir, \"package.json\"))) {\n\t\t\treturn dir;\n\t\t}\n\t\tdir = dirname(dir);\n\t}\n\treturn undefined;\n}\n\nfunction isSelfUpdatePathWritable(): boolean {\n\tconst packageDir = getPackageDir();\n\ttry {\n\t\taccessSync(packageDir, constants.W_OK);\n\t\taccessSync(dirname(packageDir), constants.W_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction isManagedByGlobalPackageManager(method: InstallMethod, packageName: string, npmCommand?: string[]): boolean {\n\tconst packageDirs = [getPackageDir(), getEntrypointPackageDir()].filter((dir): dir is string => !!dir);\n\tconst packageDirCandidates = packageDirs.flatMap((dir) => getPathComparisonCandidates(dir));\n\treturn getGlobalPackageRoots(method, packageName, npmCommand).some((root) => {\n\t\treturn getPathComparisonCandidates(root).some((normalizedRoot) => {\n\t\t\tconst rootPrefix = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;\n\t\t\treturn packageDirCandidates.some((packageDir) => packageDir.startsWith(rootPrefix));\n\t\t});\n\t});\n}\n\nexport function getSelfUpdateCommand(\n\tpackageName: string,\n\tnpmCommand?: string[],\n\tupdatePackageName = packageName,\n): SelfUpdateCommand | undefined {\n\tconst method = detectInstallMethod();\n\tconst command = getSelfUpdateCommandForMethod(method, packageName, updatePackageName, npmCommand);\n\tif (!command || !isManagedByGlobalPackageManager(method, packageName, npmCommand) || !isSelfUpdatePathWritable()) {\n\t\treturn undefined;\n\t}\n\treturn command;\n}\n\nexport function getSelfUpdateUnavailableInstruction(\n\tpackageName: string,\n\tnpmCommand?: string[],\n\tupdatePackageName = packageName,\n): string {\n\tconst method = detectInstallMethod();\n\tif (method === \"bun-binary\") {\n\t\treturn `Download from: https://github.com/earendil-works/pi-mono/releases/latest`;\n\t}\n\tconst command = getSelfUpdateCommandForMethod(method, packageName, updatePackageName, npmCommand);\n\tif (command) {\n\t\tif (isManagedByGlobalPackageManager(method, packageName, npmCommand) && !isSelfUpdatePathWritable()) {\n\t\t\treturn `This installation is managed by a global ${method} install, but the install path is not writable. Update it yourself with: ${command.display}`;\n\t\t}\n\t\treturn `This installation is not managed by a global ${method} install. Update it with the package manager, wrapper, or source checkout that provides it.`;\n\t}\n\treturn `Update ${updatePackageName} using the package manager, wrapper, or source checkout that provides this installation.`;\n}\n\nexport function getUpdateInstruction(packageName: string): string {\n\tconst method = detectInstallMethod();\n\tconst command = getSelfUpdateCommandForMethod(method, packageName);\n\tif (command) {\n\t\treturn `Run: ${command.display}`;\n\t}\n\treturn getSelfUpdateUnavailableInstruction(packageName);\n}\n\n// =============================================================================\n// Package Asset Paths (shipped with executable)\n// =============================================================================\n\n/**\n * Get the base directory for resolving package assets (themes, package.json, README.md, CHANGELOG.md).\n * - For Bun binary: returns the directory containing the executable\n * - For Node.js (dist/): returns __dirname (the dist/ directory)\n * - For tsx (src/): returns parent directory (the package root)\n */\nexport function getPackageDir(): string {\n\t// Allow override via environment variable (useful for Nix/Guix where store paths tokenize poorly).\n\t// This runs before package.json app config is read, so the env var name is hardcoded.\n\tconst envDir = process.env.ATOMIC_PACKAGE_DIR ?? process.env.PI_PACKAGE_DIR;\n\tif (envDir) {\n\t\treturn normalizePath(envDir);\n\t}\n\n\tif (isBunBinary) {\n\t\t// Bun binary: process.execPath points to the compiled executable\n\t\treturn dirname(process.execPath);\n\t}\n\t// Node.js: walk up from __dirname until we find package.json\n\tlet dir = __dirname;\n\twhile (dir !== dirname(dir)) {\n\t\tif (existsSync(join(dir, \"package.json\"))) {\n\t\t\treturn dir;\n\t\t}\n\t\tdir = dirname(dir);\n\t}\n\t// Fallback (shouldn't happen)\n\treturn __dirname;\n}\n\n/**\n * Get path to built-in themes directory (shipped with package)\n * - For Bun binary: theme/ next to executable\n * - For Node.js (dist/): dist/modes/interactive/theme/\n * - For tsx (src/): src/modes/interactive/theme/\n */\nexport function getThemesDir(): string {\n\tif (isBunBinary) {\n\t\treturn join(getPackageDir(), \"theme\");\n\t}\n\t// Theme is in modes/interactive/theme/ relative to src/ or dist/\n\tconst packageDir = getPackageDir();\n\tconst srcOrDist = existsSync(join(packageDir, \"src\")) ? \"src\" : \"dist\";\n\treturn join(packageDir, srcOrDist, \"modes\", \"interactive\", \"theme\");\n}\n\n/**\n * Get path to HTML export template directory (shipped with package)\n * - For Bun binary: export-html/ next to executable\n * - For Node.js (dist/): dist/core/export-html/\n * - For tsx (src/): src/core/export-html/\n */\nexport function getExportTemplateDir(): string {\n\tif (isBunBinary) {\n\t\treturn join(getPackageDir(), \"export-html\");\n\t}\n\tconst packageDir = getPackageDir();\n\tconst srcOrDist = existsSync(join(packageDir, \"src\")) ? \"src\" : \"dist\";\n\treturn join(packageDir, srcOrDist, \"core\", \"export-html\");\n}\n\n/** Get path to package.json */\nexport function getPackageJsonPath(): string {\n\treturn join(getPackageDir(), \"package.json\");\n}\n\n/** Get path to README.md */\nexport function getReadmePath(): string {\n\treturn resolve(join(getPackageDir(), \"README.md\"));\n}\n\n/** Get path to docs directory */\nexport function getDocsPath(): string {\n\treturn resolve(join(getPackageDir(), \"docs\"));\n}\n\n/** Get path to examples directory */\nexport function getExamplesPath(): string {\n\treturn resolve(join(getPackageDir(), \"examples\"));\n}\n\n/** Get path to CHANGELOG.md */\nexport function getChangelogPath(): string {\n\treturn resolve(join(getPackageDir(), \"CHANGELOG.md\"));\n}\n\n/**\n * Get path to built-in interactive assets directory.\n * - For Bun binary: assets/ next to executable\n * - For Node.js (dist/): dist/modes/interactive/assets/\n * - For tsx (src/): src/modes/interactive/assets/\n */\nexport function getInteractiveAssetsDir(): string {\n\tif (isBunBinary) {\n\t\treturn join(getPackageDir(), \"assets\");\n\t}\n\tconst packageDir = getPackageDir();\n\tconst srcOrDist = existsSync(join(packageDir, \"src\")) ? \"src\" : \"dist\";\n\treturn join(packageDir, srcOrDist, \"modes\", \"interactive\", \"assets\");\n}\n\n/** Get path to a bundled interactive asset */\nexport function getBundledInteractiveAssetPath(name: string): string {\n\treturn join(getInteractiveAssetsDir(), name);\n}\n\n// =============================================================================\n// App Config (from package.json <appName>Config, with piConfig as a legacy shim)\n// =============================================================================\n\ninterface AppConfig {\n\tname?: string;\n\tconfigDir?: string;\n\tchangelogUrl?: string;\n}\n\ninterface PackageJson extends Record<string, unknown> {\n\tname?: string;\n\tversion?: string;\n\tpiConfig?: AppConfig;\n}\n\nconst pkg = JSON.parse(readFileSync(getPackageJsonPath(), \"utf-8\")) as PackageJson;\n\nfunction appNameFromPackageName(packageName: string | undefined): string | undefined {\n\tconst localName = packageName?.split(\"/\").pop()?.trim();\n\treturn localName && localName.length > 0 ? localName : undefined;\n}\n\nfunction readAppConfig(packageJson: PackageJson, appName: string | undefined): AppConfig | undefined {\n\tif (appName) {\n\t\tconst appConfig = packageJson[`${appName}Config`];\n\t\tif (appConfig && typeof appConfig === \"object\" && !Array.isArray(appConfig)) {\n\t\t\treturn appConfig as AppConfig;\n\t\t}\n\t}\n\treturn packageJson.piConfig;\n}\n\nexport const PACKAGE_NAME: string = pkg.name || \"@bastani/atomic\";\nconst packageAppName = appNameFromPackageName(PACKAGE_NAME);\nconst appConfig = readAppConfig(pkg, packageAppName);\nexport const APP_NAME: string = appConfig?.name || packageAppName || \"pi\";\nexport const APP_TITLE: string = appConfig?.name !== undefined || APP_NAME !== \"pi\" ? APP_NAME : \"π\";\nexport const CONFIG_DIR_NAME: string = appConfig?.configDir || (APP_NAME === \"pi\" ? \".pi\" : `.${APP_NAME}`);\nexport const LEGACY_CONFIG_DIR_NAME = \".pi\";\nexport const CONFIG_DIR_NAMES: readonly string[] =\n\tCONFIG_DIR_NAME === LEGACY_CONFIG_DIR_NAME ? [CONFIG_DIR_NAME] : [CONFIG_DIR_NAME, LEGACY_CONFIG_DIR_NAME];\nexport const VERSION: string = pkg.version || \"0.0.0\";\nexport const CHANGELOG_URL: string | undefined = appConfig?.changelogUrl?.trim() || undefined;\n\nconst ENV_PREFIX = APP_NAME.toUpperCase();\nexport const LEGACY_ENV_PREFIX = \"PI\";\n\n// e.g., ATOMIC_CODING_AGENT_DIR (with PI_CODING_AGENT_DIR as a compatibility alias)\nexport const ENV_AGENT_DIR = `${ENV_PREFIX}_CODING_AGENT_DIR`;\nexport const ENV_SESSION_DIR = `${ENV_PREFIX}_CODING_AGENT_SESSION_DIR`;\nexport const ENV_PACKAGE_DIR = `${ENV_PREFIX}_PACKAGE_DIR`;\nexport const ENV_OFFLINE = `${ENV_PREFIX}_OFFLINE`;\nexport const ENV_SKIP_VERSION_CHECK = `${ENV_PREFIX}_SKIP_VERSION_CHECK`;\nexport const ENV_STARTUP_BENCHMARK = `${ENV_PREFIX}_STARTUP_BENCHMARK`;\nexport const ENV_TELEMETRY = `${ENV_PREFIX}_TELEMETRY`;\nexport const ENV_SHARE_VIEWER_URL = `${ENV_PREFIX}_SHARE_VIEWER_URL`;\nexport const ENV_CLEAR_ON_SHRINK = `${ENV_PREFIX}_CLEAR_ON_SHRINK`;\nexport const ENV_HARDWARE_CURSOR = `${ENV_PREFIX}_HARDWARE_CURSOR`;\nexport const ENV_TIMING = `${ENV_PREFIX}_TIMING`;\nexport const WORKFLOW_STAGE_SUBAGENT_GUARD_ENV = `${ENV_PREFIX}_WORKFLOW_STAGE_SUBAGENT_GUARD`;\n\nexport function getEnvNames(name: string): string[] {\n\tif (ENV_PREFIX === LEGACY_ENV_PREFIX || !name.startsWith(`${ENV_PREFIX}_`)) return [name];\n\treturn [name, `${LEGACY_ENV_PREFIX}_${name.slice(ENV_PREFIX.length + 1)}`];\n}\n\nexport function getEnvValue(name: string): string | undefined {\n\tfor (const candidate of getEnvNames(name)) {\n\t\tconst value = process.env[candidate];\n\t\tif (value !== undefined) return value;\n\t}\n\treturn undefined;\n}\n\nexport function hasEnvValue(name: string): boolean {\n\treturn getEnvValue(name) !== undefined;\n}\n\nexport function setEnvValue(name: string, value: string): void {\n\tprocess.env[name] = value;\n}\n\nexport function expandTildePath(path: string): string {\n\treturn normalizePath(path);\n}\n\nconst DEFAULT_SHARE_VIEWER_URL = \"https://pi.dev/session/\";\n\n/** Get the share viewer URL for a gist ID */\nexport function getShareViewerUrl(gistId: string): string {\n\tconst baseUrl = getEnvValue(ENV_SHARE_VIEWER_URL) || DEFAULT_SHARE_VIEWER_URL;\n\treturn `${baseUrl}#${gistId}`;\n}\n\n// =============================================================================\n// User Config Paths (~/.atomic/agent/*)\n// =============================================================================\n\n/** Get the agent config directory (e.g., ~/.atomic/agent/) */\nexport function getAgentDir(): string {\n\tconst envDir = getEnvValue(ENV_AGENT_DIR);\n\tif (envDir) {\n\t\treturn expandTildePath(envDir);\n\t}\n\treturn join(homedir(), CONFIG_DIR_NAME, \"agent\");\n}\n\n/** Get the legacy pi agent config directory (e.g., ~/.pi/agent/) */\nexport function getLegacyAgentDir(): string {\n\treturn join(homedir(), LEGACY_CONFIG_DIR_NAME, \"agent\");\n}\n\n/** Get agent config directories in precedence order (primary first, then legacy). */\nexport function getAgentDirs(): string[] {\n\tconst primary = getAgentDir();\n\tif (hasEnvValue(ENV_AGENT_DIR) || CONFIG_DIR_NAME === LEGACY_CONFIG_DIR_NAME) {\n\t\treturn [primary];\n\t}\n\tconst legacy = getLegacyAgentDir();\n\treturn legacy === primary ? [primary] : [primary, legacy];\n}\n\n/** Get user config root directories in precedence order (primary first, then legacy). */\nexport function getUserConfigDirs(): string[] {\n\treturn CONFIG_DIR_NAMES.map((name) => join(homedir(), name));\n}\n\n/** Get project config directories in precedence order (primary first, then legacy). */\nexport function getProjectConfigDirs(cwd: string): string[] {\n\treturn CONFIG_DIR_NAMES.map((name) => join(cwd, name));\n}\n\n/** Get a path inside every user config root directory. */\nexport function getUserConfigPaths(...segments: string[]): string[] {\n\treturn getUserConfigDirs().map((dir) => join(dir, ...segments));\n}\n\n/** Get a path inside every agent config directory. */\nexport function getAgentConfigPaths(...segments: string[]): string[] {\n\treturn getAgentDirs().map((dir) => join(dir, ...segments));\n}\n\n/** Get a path inside every project config directory. */\nexport function getProjectConfigPaths(cwd: string, ...segments: string[]): string[] {\n\treturn getProjectConfigDirs(cwd).map((dir) => join(dir, ...segments));\n}\n\n/** Get path to user's custom themes directory */\nexport function getCustomThemesDir(): string {\n\treturn join(getAgentDir(), \"themes\");\n}\n\n/** Get path to models.json */\nexport function getModelsPath(): string {\n\treturn join(getAgentDir(), \"models.json\");\n}\n\n/** Get path to auth.json */\nexport function getAuthPath(): string {\n\treturn join(getAgentDir(), \"auth.json\");\n}\n\n/** Get path to settings.json */\nexport function getSettingsPath(): string {\n\treturn join(getAgentDir(), \"settings.json\");\n}\n\n/** Get path to tools directory */\nexport function getToolsDir(): string {\n\treturn join(getAgentDir(), \"tools\");\n}\n\n/** Get path to managed binaries directory (fd, rg) */\nexport function getBinDir(): string {\n\treturn join(getAgentDir(), \"bin\");\n}\n\n/** Get path to prompt templates directory */\nexport function getPromptsDir(): string {\n\treturn join(getAgentDir(), \"prompts\");\n}\n\n/** Get path to sessions directory */\nexport function getSessionsDir(): string {\n\treturn join(getAgentDir(), \"sessions\");\n}\n\n/** Get path to debug log file */\nexport function getDebugLogPath(): string {\n\treturn join(getAgentDir(), `${APP_NAME}-debug.log`);\n}\n"]}

package/dist/config.js

@@ -385,6 +385,7 @@ export const ENV_SHARE_VIEWER_URL = `${ENV_PREFIX}_SHARE_VIEWER_URL`;
 export const ENV_CLEAR_ON_SHRINK = `${ENV_PREFIX}_CLEAR_ON_SHRINK`;
 export const ENV_HARDWARE_CURSOR = `${ENV_PREFIX}_HARDWARE_CURSOR`;
 export const ENV_TIMING = `${ENV_PREFIX}_TIMING`;
+export const WORKFLOW_STAGE_SUBAGENT_GUARD_ENV = `${ENV_PREFIX}_WORKFLOW_STAGE_SUBAGENT_GUARD`;
 export function getEnvNames(name) {
     if (ENV_PREFIX === LEGACY_ENV_PREFIX || !name.startsWith(`${ENV_PREFIX}_`))
         return [name];