@bastani/atomic 0.9.19-alpha.1 → 0.9.19-alpha.3

package/dist/modes/rpc/task-ui-bridge.js

@@ -0,0 +1,146 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getOwnerTaskStore, watchOwnerTaskStoreBinding } from "../../core/tasks/owner-store.js";
+import { TaskInspector } from "../interactive/components/task-inspector.js";
+import { isActiveBackgroundTask, renderTaskFooter } from "../interactive/components/task-list.js";
+import { isPhysicalCtrlC } from "../interactive/interactive-key-identity.js";
+const widgetVisibility = new WeakMap();
+/** Render against the engine's owner. Native capabilities never cross the UI bridge. */
+export function bindEngineTaskWidget(session, ui) {
+    const key = "atomic.background-tasks";
+    let unsubscribe = () => { };
+    let disposed = false;
+    let mounted = false;
+    let visible = true;
+    const connect = () => {
+        unsubscribe();
+        if (mounted)
+            ui.setWidget(key, undefined);
+        mounted = false;
+        const store = getOwnerTaskStore(session);
+        const update = () => {
+            if (disposed)
+                return;
+            if (!visible || !store?.backgroundTasks.some(isActiveBackgroundTask)) {
+                if (mounted)
+                    ui.setWidget(key, undefined);
+                mounted = false;
+                return;
+            }
+            if (!mounted) {
+                mounted = true;
+                ui.setWidget(key, () => ({
+                    invalidate() { },
+                    render(width) {
+                        return renderTaskFooter(store?.backgroundTasks ?? [], width);
+                    },
+                }), { placement: "belowEditor" });
+            }
+            ui.requestRender();
+        };
+        unsubscribe = store?.subscribe(update) ?? (() => { });
+        update();
+    };
+    const unwatch = watchOwnerTaskStoreBinding(session, connect);
+    const unwatchWidget = ui.onWidgetRelease?.(key, () => {
+        mounted = false;
+    });
+    widgetVisibility.set(session, (value) => {
+        visible = value;
+        connect();
+    });
+    connect();
+    return () => {
+        disposed = true;
+        widgetVisibility.delete(session);
+        unwatch();
+        unwatchWidget?.();
+        unsubscribe();
+        if (mounted)
+            ui.setWidget(key, undefined);
+    };
+}
+export async function showEngineTaskInspector(session, ui, taskId) {
+    session.getAgentTaskHost();
+    const store = getOwnerTaskStore(session);
+    if (!store)
+        throw new Error("Task owner is unavailable");
+    try {
+        widgetVisibility.get(session)?.(false);
+        await showTaskInspector(ui, store, taskId);
+    }
+    finally {
+        widgetVisibility.get(session)?.(true);
+    }
+}
+/** Main CLI mount, shared by the local host and its isolated engine. */
+export async function showTaskInspector(ui, store, taskId) {
+    let requestRender = () => { };
+    let finishView = () => { };
+    let closed = false;
+    let fullscreen = false;
+    const inspector = new TaskInspector(store, () => {
+        if (inspector.fullscreen !== fullscreen)
+            finishView();
+        else
+            requestRender();
+    }, () => {
+        closed = true;
+        finishView();
+    });
+    inspector.open(taskId);
+    try {
+        while (!closed) {
+            fullscreen = inspector.fullscreen;
+            await ui.custom((tui, _theme, _keys, done) => {
+                requestRender = () => tui.requestRender();
+                finishView = () => done();
+                return {
+                    invalidate: () => inspector.invalidate(),
+                    render: (width) => {
+                        const height = Math.max(1, tui.terminal.rows);
+                        if (!fullscreen)
+                            return inspector.renderPicker(width, height);
+                        const lines = inspector.renderViewport(width, height);
+                        // Fullscreen detail pages cover all parent chat and prompt cells.
+                        return Array.from({ length: height }, (_, row) => {
+                            const line = truncateToWidth(lines[row] ?? "", width);
+                            return line + " ".repeat(Math.max(0, width - visibleWidth(line)));
+                        });
+                    },
+                    handleInput: (data) => {
+                        if (isPhysicalCtrlC(data)) {
+                            closed = true;
+                            done();
+                        }
+                        else
+                            inspector.handleInput(data);
+                        return true;
+                    },
+                };
+            }, {
+                overlay: fullscreen,
+                purpose: "navigation",
+                handlesCtrlC: true,
+                deferInlineCustomUiFocus: true,
+                handlesInternalUiAction: true,
+                ...(fullscreen
+                    ? {
+                        overlayOptions: {
+                            anchor: "center",
+                            width: "100%",
+                            maxHeight: "100%",
+                            margin: 0,
+                        },
+                    }
+                    : {}),
+            });
+            // Host dismissal without a navigation transition must not reopen the view.
+            if (inspector.fullscreen === fullscreen)
+                closed = true;
+        }
+    }
+    finally {
+        inspector?.dispose();
+    }
+}
+//# sourceMappingURL=task-ui-bridge.js.map

package/dist/modes/rpc/task-ui-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-ui-bridge.js","sourceRoot":"","sources":["../../../src/modes/rpc/task-ui-bridge.ts"],"names":[],"mappings":"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","sourcesContent":["import { truncateToWidth, visibleWidth } from \"@earendil-works/pi-tui\";\nimport type { AgentSession } from \"../../core/agent-session.js\";\nimport type { ExtensionUIContext } from \"../../core/extensions/index.js\";\nimport type { TaskId } from \"../../core/tasks/contracts.js\";\nimport { getOwnerTaskStore, type OwnerTaskStore, watchOwnerTaskStoreBinding } from \"../../core/tasks/owner-store.js\";\nimport { TaskInspector } from \"../interactive/components/task-inspector.js\";\nimport { isActiveBackgroundTask, renderTaskFooter } from \"../interactive/components/task-list.js\";\nimport { isPhysicalCtrlC } from \"../interactive/interactive-key-identity.ts\";\n\nconst widgetVisibility = new WeakMap<AgentSession, (visible: boolean) => void>();\n\n/** Render against the engine's owner. Native capabilities never cross the UI bridge. */\nexport function bindEngineTaskWidget(session: AgentSession, ui: ExtensionUIContext): () => void {\n\tconst key = \"atomic.background-tasks\";\n\tlet unsubscribe = () => {};\n\tlet disposed = false;\n\tlet mounted = false;\n\tlet visible = true;\n\tconst connect = () => {\n\t\tunsubscribe();\n\t\tif (mounted) ui.setWidget(key, undefined);\n\t\tmounted = false;\n\t\tconst store = getOwnerTaskStore(session);\n\t\tconst update = () => {\n\t\t\tif (disposed) return;\n\t\t\tif (!visible || !store?.backgroundTasks.some(isActiveBackgroundTask)) {\n\t\t\t\tif (mounted) ui.setWidget(key, undefined);\n\t\t\t\tmounted = false;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (!mounted) {\n\t\t\t\tmounted = true;\n\t\t\t\tui.setWidget(\n\t\t\t\t\tkey,\n\t\t\t\t\t() => ({\n\t\t\t\t\t\tinvalidate() {},\n\t\t\t\t\t\trender(width: number) {\n\t\t\t\t\t\t\treturn renderTaskFooter(store?.backgroundTasks ?? [], width);\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t\t{ placement: \"belowEditor\" },\n\t\t\t\t);\n\t\t\t}\n\t\t\tui.requestRender();\n\t\t};\n\t\tunsubscribe = store?.subscribe(update) ?? (() => {});\n\t\tupdate();\n\t};\n\tconst unwatch = watchOwnerTaskStoreBinding(session, connect);\n\tconst unwatchWidget = ui.onWidgetRelease?.(key, () => {\n\t\tmounted = false;\n\t});\n\twidgetVisibility.set(session, (value) => {\n\t\tvisible = value;\n\t\tconnect();\n\t});\n\tconnect();\n\treturn () => {\n\t\tdisposed = true;\n\t\twidgetVisibility.delete(session);\n\t\tunwatch();\n\t\tunwatchWidget?.();\n\t\tunsubscribe();\n\t\tif (mounted) ui.setWidget(key, undefined);\n\t};\n}\n\nexport async function showEngineTaskInspector(\n\tsession: AgentSession,\n\tui: Pick<ExtensionUIContext, \"custom\">,\n\ttaskId?: string,\n): Promise<void> {\n\tsession.getAgentTaskHost();\n\tconst store = getOwnerTaskStore(session);\n\tif (!store) throw new Error(\"Task owner is unavailable\");\n\ttry {\n\t\twidgetVisibility.get(session)?.(false);\n\t\tawait showTaskInspector(ui, store, taskId);\n\t} finally {\n\t\twidgetVisibility.get(session)?.(true);\n\t}\n}\n\n/** Main CLI mount, shared by the local host and its isolated engine. */\nexport async function showTaskInspector(\n\tui: Pick<ExtensionUIContext, \"custom\">,\n\tstore: OwnerTaskStore,\n\ttaskId?: string,\n): Promise<void> {\n\tlet requestRender = () => {};\n\tlet finishView = () => {};\n\tlet closed = false;\n\tlet fullscreen = false;\n\tconst inspector = new TaskInspector(\n\t\tstore,\n\t\t() => {\n\t\t\tif (inspector.fullscreen !== fullscreen) finishView();\n\t\t\telse requestRender();\n\t\t},\n\t\t() => {\n\t\t\tclosed = true;\n\t\t\tfinishView();\n\t\t},\n\t);\n\tinspector.open(taskId as TaskId | undefined);\n\ttry {\n\t\twhile (!closed) {\n\t\t\tfullscreen = inspector.fullscreen;\n\t\t\tawait ui.custom<void>(\n\t\t\t\t(tui, _theme, _keys, done) => {\n\t\t\t\t\trequestRender = () => tui.requestRender();\n\t\t\t\t\tfinishView = () => done();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tinvalidate: () => inspector.invalidate(),\n\t\t\t\t\t\trender: (width: number) => {\n\t\t\t\t\t\t\tconst height = Math.max(1, tui.terminal.rows);\n\t\t\t\t\t\t\tif (!fullscreen) return inspector.renderPicker(width, height);\n\t\t\t\t\t\t\tconst lines = inspector.renderViewport(width, height);\n\t\t\t\t\t\t\t// Fullscreen detail pages cover all parent chat and prompt cells.\n\t\t\t\t\t\t\treturn Array.from({ length: height }, (_, row) => {\n\t\t\t\t\t\t\t\tconst line = truncateToWidth(lines[row] ?? \"\", width);\n\t\t\t\t\t\t\t\treturn line + \" \".repeat(Math.max(0, width - visibleWidth(line)));\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t},\n\t\t\t\t\t\thandleInput: (data: string) => {\n\t\t\t\t\t\t\tif (isPhysicalCtrlC(data)) {\n\t\t\t\t\t\t\t\tclosed = true;\n\t\t\t\t\t\t\t\tdone();\n\t\t\t\t\t\t\t} else inspector.handleInput(data);\n\t\t\t\t\t\t\treturn true;\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\toverlay: fullscreen,\n\t\t\t\t\tpurpose: \"navigation\",\n\t\t\t\t\thandlesCtrlC: true,\n\t\t\t\t\tdeferInlineCustomUiFocus: true,\n\t\t\t\t\thandlesInternalUiAction: true,\n\t\t\t\t\t...(fullscreen\n\t\t\t\t\t\t? {\n\t\t\t\t\t\t\t\toverlayOptions: {\n\t\t\t\t\t\t\t\t\tanchor: \"center\" as const,\n\t\t\t\t\t\t\t\t\twidth: \"100%\" as const,\n\t\t\t\t\t\t\t\t\tmaxHeight: \"100%\" as const,\n\t\t\t\t\t\t\t\t\tmargin: 0,\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t: {}),\n\t\t\t\t},\n\t\t\t);\n\t\t\t// Host dismissal without a navigation transition must not reopen the view.\n\t\t\tif (inspector.fullscreen === fullscreen) closed = true;\n\t\t}\n\t} finally {\n\t\tinspector?.dispose();\n\t}\n}\n"]}

package/dist/self-update-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"self-update-plan.js","sourceRoot":"","sources":["../src/self-update-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EACN,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GAErB,MAAM,0BAA0B,CAAC;AAUlC,MAAM,UAAU,mBAAmB,CAAC,OAAwB,EAAE,KAAK,GAAG,KAAK;IAC1E,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,YAAY,CAAC;IACxD,OAAO;QACN,WAAW;QACX,WAAW,EAAE,GAAG,WAAW,IAAI,OAAO,CAAC,OAAO,EAAE;QAChD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,KAAK,IAAI,WAAW,KAAK,YAAY,IAAI,qBAAqB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC;QACnG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAAc;IACzD,IAAI,OAAoC,CAAC;IACzC,IAAI,CAAC;QACJ,OAAO,GAAG,MAAM,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,aAAa,uBAAuB,CAAC,KAAK,CAAC,EAAE,EAAE;YACpG,KAAK,EAAE,KAAK;SACZ,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,WAAW,CAAC,CAAC;IACjF,OAAO,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE;IACtF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,CAAC;QACJ,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC;aACpD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;aAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;aAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,OAAO,CAAC;IAChB,CAAC;AACF,CAAC","sourcesContent":["import { Markdown } from \"@earendil-works/pi-tui\";\nimport { APP_NAME, PACKAGE_NAME, VERSION } from \"./config.js\";\nimport { getMarkdownTheme } from \"./modes/interactive/theme/theme.ts\";\nimport {\n\tformatVersionCheckError,\n\tgetLatestPiRelease,\n\tisNewerPackageVersion,\n\ttype LatestPiRelease,\n} from \"./utils/version-check.ts\";\n\nexport interface SelfUpdatePlan {\n\tpackageName: string;\n\tinstallSpec: string;\n\tversion: string;\n\tshouldRun: boolean;\n\tnote?: string;\n}\n\nexport function buildSelfUpdatePlan(release: LatestPiRelease, force = false): SelfUpdatePlan {\n\tconst packageName = release.packageName ?? PACKAGE_NAME;\n\treturn {\n\t\tpackageName,\n\t\tinstallSpec: `${packageName}@${release.version}`,\n\t\tversion: release.version,\n\t\tshouldRun: force || packageName !== PACKAGE_NAME || isNewerPackageVersion(release.version, VERSION),\n\t\t...(release.note ? { note: release.note } : {}),\n\t};\n}\n\nexport async function resolveSelfUpdatePlan(force: boolean): Promise<SelfUpdatePlan> {\n\tlet release: LatestPiRelease | undefined;\n\ttry {\n\t\trelease = await getLatestPiRelease({ retry: true });\n\t} catch (error) {\n\t\tthrow new Error(`Could not determine latest ${APP_NAME} version: ${formatVersionCheckError(error)}`, {\n\t\t\tcause: error,\n\t\t});\n\t}\n\tif (!release) throw new Error(`Could not determine latest ${APP_NAME} version.`);\n\treturn buildSelfUpdatePlan(release, force);\n}\n\nexport function renderSelfUpdateNote(note: string, width = process.stdout.columns ?? 80): string | undefined {\n\tconst trimmed = note.trim();\n\tif (!trimmed) return undefined;\n\ttry {\n\t\treturn new Markdown(trimmed, 0, 0, getMarkdownTheme())\n\t\t\t.render(Math.max(20, width))\n\t\t\t.map((line) => line.trimEnd())\n\t\t\t.join(\"\\n\");\n\t} catch {\n\t\treturn trimmed;\n\t}\n}\n"]}
+{"version":3,"file":"self-update-plan.js","sourceRoot":"","sources":["../src/self-update-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EACN,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GAErB,MAAM,0BAA0B,CAAC;AAUlC,MAAM,UAAU,mBAAmB,CAAC,OAAwB,EAAE,KAAK,GAAG,KAAK;IAC1E,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,YAAY,CAAC;IACxD,OAAO;QACN,WAAW;QACX,WAAW,EAAE,GAAG,WAAW,IAAI,OAAO,CAAC,OAAO,EAAE;QAChD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,KAAK,IAAI,WAAW,KAAK,YAAY,IAAI,qBAAqB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC;QACnG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAAc;IACzD,IAAI,OAAoC,CAAC;IACzC,IAAI,CAAC;QACJ,OAAO,GAAG,MAAM,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,aAAa,uBAAuB,CAAC,KAAK,CAAC,EAAE,EAAE;YACpG,KAAK,EAAE,KAAK;SACZ,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,WAAW,CAAC,CAAC;IACjF,OAAO,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE;IACtF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,CAAC;QACJ,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC;aACpD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;aAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;aAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,OAAO,CAAC;IAChB,CAAC;AACF,CAAC","sourcesContent":["import { Markdown } from \"@earendil-works/pi-tui\";\nimport { APP_NAME, PACKAGE_NAME, VERSION } from \"./config.js\";\nimport { getMarkdownTheme } from \"./modes/interactive/theme/theme.js\";\nimport {\n\tformatVersionCheckError,\n\tgetLatestPiRelease,\n\tisNewerPackageVersion,\n\ttype LatestPiRelease,\n} from \"./utils/version-check.ts\";\n\nexport interface SelfUpdatePlan {\n\tpackageName: string;\n\tinstallSpec: string;\n\tversion: string;\n\tshouldRun: boolean;\n\tnote?: string;\n}\n\nexport function buildSelfUpdatePlan(release: LatestPiRelease, force = false): SelfUpdatePlan {\n\tconst packageName = release.packageName ?? PACKAGE_NAME;\n\treturn {\n\t\tpackageName,\n\t\tinstallSpec: `${packageName}@${release.version}`,\n\t\tversion: release.version,\n\t\tshouldRun: force || packageName !== PACKAGE_NAME || isNewerPackageVersion(release.version, VERSION),\n\t\t...(release.note ? { note: release.note } : {}),\n\t};\n}\n\nexport async function resolveSelfUpdatePlan(force: boolean): Promise<SelfUpdatePlan> {\n\tlet release: LatestPiRelease | undefined;\n\ttry {\n\t\trelease = await getLatestPiRelease({ retry: true });\n\t} catch (error) {\n\t\tthrow new Error(`Could not determine latest ${APP_NAME} version: ${formatVersionCheckError(error)}`, {\n\t\t\tcause: error,\n\t\t});\n\t}\n\tif (!release) throw new Error(`Could not determine latest ${APP_NAME} version.`);\n\treturn buildSelfUpdatePlan(release, force);\n}\n\nexport function renderSelfUpdateNote(note: string, width = process.stdout.columns ?? 80): string | undefined {\n\tconst trimmed = note.trim();\n\tif (!trimmed) return undefined;\n\ttry {\n\t\treturn new Markdown(trimmed, 0, 0, getMarkdownTheme())\n\t\t\t.render(Math.max(20, width))\n\t\t\t.map((line) => line.trimEnd())\n\t\t\t.join(\"\\n\");\n\t} catch {\n\t\treturn trimmed;\n\t}\n}\n"]}

package/docs/background-tasks.md

@@ -0,0 +1,205 @@
+---
+title: "Background tasks"
+description: "Run subagents and shell tasks while continuing your conversation"
+---
+
+# Background tasks
+
+Background subagents keep working after the launch call returns. You can continue chatting without restarting them or keeping a task list open.
+
+In main chat and live workflow-stage chat, a compact indicator appears **below the prompt box and MCP status**, and above the workflow `BACKGROUND` widget when present:
+
+```text
+Tasks  2 local agents running · 1 queued · /tasks
+```
+
+It summarizes only active background agents and shells, including queued work, stopping tasks, and tasks needing attention. Completed, failed, and stopped tasks leave the footer immediately; when no background work is active, the indicator disappears. Results and failure details remain in completion cards and `/tasks`, so an old failure cannot keep the live indicator red. Running tasks do not expire merely because they are quiet.
+
+Run `/tasks` to open a compact inline picker in the editor slot, like `/workflow connect`, with the conversation still visible above it. Detail, transcript, input, and cancellation-confirmation pages use the full screen. Escape returns to the picker with the selected task preserved, then to chat. The command also appears in workflow-stage slash suggestions, including when skill commands are disabled. Foreground-only commands do not appear. Work that ran in the background stays available after completion or a later foreground wait. Updates never open the list automatically. Closing the inspector does not stop the tasks.
+
+Main and workflow-stage pickers use the same layout for empty and populated lists. Below the picker, the footer keeps that chat's resolved model and reasoning level, current folder and Git branch, and MCP status, including while its foreground turn streams. Each picker lists only its owner's tasks.
+
+Opening `/tasks` is navigation, not an approval request. It does not mark the agent blocked in Herdr or produce a "Main chat needs input" notice. A genuine main-chat question waiting behind the workflow graph still shows that notice until answered or the graph is hidden or closed. The inspector stays open until you close it, even when its tasks finish; task history is not deleted when the compact indicator disappears.
+
+## Choose how long to wait
+
+The agent can choose foreground-first or background observation for each authorized shell or subagent call. Choosing a mode does not require a separate user confirmation and does not relax tool permissions or task ownership.
+
+| Call | Observation behavior |
+| --- | --- |
+| `bash` or `powershell` without `wait` | Waits for the owner's command observation budget, normally 10 seconds, then automatically returns if still running. |
+| `subagent` without `wait` | Returns after admission; the child runs in the background by default. |
+| Any of these tools with `wait: { kind: "background" }` | Explicitly returns after admission without waiting for execution to finish. |
+| Any of these tools with `wait: { kind: "foreground" }` | Waits for the owner's observation budget, normally 10 seconds for shells and 30 seconds for agents. |
+| Any of these tools with `wait: { kind: "foreground", budgetMs: 1000 }` | Waits up to one second, then automatically yields if the original task is still running. |
+
+If the task finishes during observation, the call returns its terminal result instead. Automatic backgrounding is **observation expiry**, not a slow-task failure, a restart, or a second execution. Use foreground-first observation for a dependency and background observation for independent work. If a dependency yields, wait for its actual completion before using the result.
+
+Shell `budgetMs` accepts finite non-negative milliseconds; zero means no observation delay. It is only valid for foreground observation. A trusted SDK host can override the usual budgets or select `tasks.wait.kind: "until-settled"`; omitted foreground budgets then wait until settlement. Explicit per-call budgets still take precedence.
+
+Native observation timers run independently of JavaScript. A zero-budget wait can already be backgrounded by the time a caller reads the next task snapshot, even before JavaScript awaits the result. Synchronous wait registration does not guarantee a visible foreground interval. The elapsed result still identifies the same wait and task; execution continues.
+
+## Background subagents
+
+Ask Atomic to delegate a bounded task:
+
+```text
+Have a codebase-analyzer trace the authentication flow in the background.
+Keep working with me here while it runs.
+```
+
+For tool callers, owner-bound launches default to background observation. Explicit examples:
+
+```ts
+subagent({
+  agent: "codebase-analyzer",
+  task: "Trace the authentication flow. Do not edit files.",
+  wait: { kind: "background" },
+})
+
+subagent({
+  tasks: [
+    { agent: "codebase-analyzer", task: "Trace request authentication." },
+    { agent: "codebase-pattern-finder", task: "Find authorization test patterns." },
+  ],
+  concurrency: 2,
+  wait: { kind: "background" },
+})
+```
+
+Parallel tasks have independent identities. Accepted work beyond the concurrency limit stays queued. Use `/agents` to browse available definitions before choosing an agent.
+
+Intercom communication does not cancel a parallel batch. A blocking ask or supervisor decision waits only in the requesting child and resumes that same execution after the matching reply. Sends and progress updates remain nonblocking. Foreground observations may yield so the parent can reply; execution concurrency, queued siblings, and task identities are preserved. Stop a selected task explicitly, or close its owner to cancel all owned work.
+
+A launch result says **Launched in background**. This records what happened at launch; it is not a permanently live status label. The below-prompt indicator and `/tasks` show the current state.
+
+### Waiting is not restarting
+
+To wait briefly before continuing:
+
+```ts
+subagent({
+  agent: "codebase-analyzer",
+  task: "Trace the authentication flow.",
+  wait: { kind: "foreground", budgetMs: 30000 },
+})
+```
+
+If that observation budget expires, the same child continues in the background. It is not an execution timeout. Observe the task ID returned by the original call:
+
+```ts
+subagent({ action: "wait", id: taskId, budgetMs: 1000 })
+subagent({ action: "status", id: taskId })
+```
+
+Do not launch a duplicate just to retrieve its result. Use the task ID returned at launch. IDs are scoped to the session or workflow stage that owns them.
+
+Foreground subagent launches and explicit `action: "wait"` calls also yield when user steering or an Intercom ask/send is admitted to the waiting parent, in main chat or a live workflow stage. The message stays in the normal delivery queue so the parent can handle it and reply. This releases only observation: children keep running under the same task IDs, and other owners' waits are unaffected.
+
+### Completion messages
+
+Completion creates a shaded notification card in the owning chat without depending on a model reply. It uses the chat theme's card background and padding, with a colored outcome, the agent or shell name, and an available result preview:
+
+```text
+✓ Subagent codebase-analyzer completed: Trace the authentication flow.
+  Authentication starts in …
+/tasks to inspect
+```
+
+The parent model also receives the result context. The internal receipt stays in structured message details, rather than becoming raw JSON in chat. The same persisted completion identity handles delivery retries without relaunching the child. Workflow completions remain in their owning stage chat, not the main conversation.
+
+Stopping a subagent through `/tasks` (`x`, then `y`) also delivers a **stopped** card and stop context to the parent model. The notice arrives after termination is confirmed, not while the task is merely **Stopping**, and does not require a final response from the child. Cancelling queued work notifies without starting it. Repeated stop requests or late child results do not duplicate the notice or overwrite the recorded outcome; a task that finished before cancellation keeps its actual result. Closing the owning session or workflow stage still suppresses late notices.
+
+Restored completions may have only an outcome and task identity if the original live task or transcript is unavailable. Atomic does not invent missing output. Excerpts are bounded; inspect retained history for more detail.
+
+Long titles and previews are truncated or wrapped within the card width. Its background covers the ellipsis, expand hint, and trailing padding on every row.
+
+## Inspect tasks
+
+| View | Controls |
+| --- | --- |
+| Task list | Up/Down selects; Enter opens detail; Escape returns to chat. |
+| Task detail | Up/Down selects an action; Enter activates it; PageUp/PageDown scrolls the body. |
+| Transcript | Up/Down scrolls; PageUp/PageDown moves one viewport; PageUp at the top loads earlier history; Home/End jumps within loaded history. |
+| Go back | Left or Escape returns from transcript to detail, then from detail to the list. |
+| Stop | `x` requests cancellation; confirm with `y`, or keep running with `n` or Escape. |
+| Shell input | Select Input when offered; Enter sends the text plus a newline; Escape leaves input mode. |
+
+Configured task bindings take precedence over the default Left, page, and `x` shortcuts. Input mode receives ordinary typing, including `x`, without stopping the task. The footer shows the applicable controls.
+
+The list groups **Agents** and **Shells**, with counts and status symbols. Detail views pin identity, state, available metrics, and the selected action while their body scrolls. Missing metrics are omitted rather than displayed as zero. Recorded zero values remain visible.
+
+Agent rows and completion cards show the resolved model and reasoning setting, for example `openai-codex/gpt-6-astra · thinking medium`. These settings update on fallback and remain after completion. Foreground results retain the same metadata. Missing settings are not inferred from token counts; early launch receipts may not yet have a resolved model.
+
+Agent details include recent retained tool activity, the prompt, a latest-response preview, and error or attention information. Transcript inspection uses a dedicated scrolling view with a pinned title, line position, and controls, rather than nesting full chat components inside a detail box. It renders retained messages and tool results without hidden reasoning or inline images. Earlier pages do not jump back to the latest page when background activity arrives.
+
+An open live transcript updates directly from the child's session events, including streaming assistant text and partial/final tool results. Shell output refreshes on task state updates, including updates received during an earlier output read. You do not need to leave and reopen the transcript. Reading earlier retained pages keeps your position while the live tail continues updating.
+
+Shell details show the command, available exit information, and a bounded output tail. The preview shows up to ten wrapped lines from the retained 8 KiB tail. Output gaps and omitted earlier content are labelled. An empty output stream says **No output available**. Shell transcript inspection exposes the retained tail, not an invented agent conversation or an unlimited log viewer.
+
+### States
+
+| State | Meaning |
+| --- | --- |
+| Queued | Admitted, waiting for execution capacity. |
+| Running | Execution is live, including when the parent has stopped waiting. |
+| Input needed | An owned prompt needs attention. Open question is offered when a host route is available. |
+| Stopping | Cancellation was requested; termination has not yet settled. |
+| Completed | Execution finished successfully. |
+| Failed | Execution ended with an error. Details retain the error message. |
+| Stopped | Execution was cancelled. Completed work is not undone. |
+
+Completed, failed, and stopped tasks retain inspection but do not offer execution controls. **Foreground wait** observes a running task; it does not transfer ownership or create a second execution.
+
+## Background shells
+
+Top-level model `bash` calls on POSIX and native Windows, and `powershell` calls on native Windows, use the session's task owner. A long command can outlive its foreground observation budget and return a task ID while continuing to run. Its status then appears below the prompt and under **Shells** in `/tasks`. An explicit execution timeout still ends the command; it is separate from observation yielding.
+
+```ts
+// Background immediately, keeping the command owned and its output retained.
+bash({ command: "npm run build", wait: { kind: "background" }, timeout: 600 })
+
+// Foreground-first, automatically yielding after one second if still running.
+bash({ command: "npm test", wait: { kind: "foreground", budgetMs: 1000 }, timeout: 600 })
+
+// Keep the default automatic observation budget.
+bash({ command: "npm run check" })
+```
+
+The shell execution timeout is separate: `timeout` is seconds and defaults to 300, with a maximum of 3600. It continues counting after backgrounding. Choose a timeout appropriate for the command; reducing `budgetMs` does not shorten or extend it. Use the returned task ID to inspect or stop the existing task through `/tasks`. Background completion notifies the parent automatically, so there is no need to launch the command again to collect its result.
+
+Shell completions use the same shaded card as subagents, with a retained output preview and available exit code. Nonzero shell exits are shown as failures even though the process itself reached a terminal state. Cancellation shows Stopped. The card and below-prompt count update in the owning main or workflow-stage chat.
+
+Native Windows owned shells use supervised pipes or ConPTY, with Job Object containment before execution resumes and confirmed cleanup. If containment cannot be established, launch is refused rather than falling back to unsupervised execution. The legacy Windows WSL `bash.exe` stdin transport remains unsupported for owned launch because Windows jobs cannot supervise Linux guest processes. Running Atomic inside WSL uses the normal POSIX/Bash path.
+
+Bash calls inside subagent sessions retain their existing execution paths. Without a supported task owner, explicit background requests are refused before execution; foreground calls wait for completion rather than automatically yielding. Custom operations adapters receive `wait` but must implement it themselves. External-terminal processes are not adopted into `/tasks`. A child's own tool use appears in that subagent's activity and transcript.
+
+## Lifetime and scope
+
+Background means independent of the current observation, not independent of its owner. **Pausing main chat** aborts the foreground turn only; its background agents and shells keep running. Detaching a workflow pane, ending a model turn, or closing `/tasks` also leaves owned background work alone.
+
+**Pausing a workflow stage** blocks new task launches immediately and cancels that stage generation's active and admitted queued agents and commands. Queued agents are cancelled before active cancellations free execution slots. Command setup already in flight may briefly start a shell during the pause transition; pause waits for those admissions, cancels the resulting shells, and confirms resource cleanup before completing. A successful pause leaves no owned active or queued executions. Cancellation or cleanup failures are reported instead of confirming pause. Main-chat tasks, sibling stages, and future stage generations are unaffected by a stage-scoped pause.
+
+Pause does not close the stage's message generation: queued user and Intercom messages remain held for resume. Resume permits fresh launches but never resurrects cancelled executions; retained task results remain inspectable. Closing a session or stage generation still cancels its remaining owned work. Explicit `/tasks` stop and declared execution timeouts remain separate controls.
+
+On native Windows, Suspend opens a PowerShell subshell rather than freezing Atomic. Exit the subshell to restore the same session; owned background tasks continue while it is open.
+
+Task inspection is owner-scoped. It is not a machine-wide process list. Switching sessions does not copy the previous session's task rows into the new one. Missing retained history is reported explicitly.
+
+Git branch watchers for alternate folders are shared by their chat footers and released when the last viewer closes or changes folders. Main chat and other open stage chats keep their live branch updates; closing `/tasks` alone leaves its chat footer active.
+
+## Task state and completion delivery
+
+Foreground and background describe observation, not different executions. Each admitted task keeps its identity and owning session as callers start or stop waiting. The native `wasBackground` field remains set after a designated wait yields, including after a later foreground wait or settlement.
+
+Execution outcome and resource cleanup are separate states. A terminal result does not by itself prove that resources were reaped. Cleanup failures remain explicit. Supervised shells retain output while running, and finish output draining as part of cleanup.
+
+Native integrations can use `TaskSupervisor.taskSettlement(task)` from `@bastani/atomic-natives` to retrieve an authentic terminal receipt without creating a new wait. This supports recovery when a bounded event journal no longer contains the completion event. Session-history completion intents and acknowledgements reuse the same identity when notification delivery is retried.
+
+UI previews are bounded and are not a substitute for retained output. Gaps and truncation are labelled; unavailable history is reported rather than reconstructed from activity counters.
+
+## Related documentation
+
+- [Subagents](/subagents) covers definitions, models, context, and delegation boundaries.
+- [Keybindings](/keybindings) covers task-action remapping.
+- [Workflows](/workflows) covers durable stage lifecycles.

package/docs/compaction.md

@@ -117,6 +117,8 @@ Configure defaults in `~/.atomic/agent/settings.json` or `.atomic/settings.json`
 
 Exactly the configured recent-message tail is outside the compactable region; Atomic does not force the final logical turn to remain outside it. After successful automatic compaction, input queued before compaction started resumes automatically once the active run becomes idle; pressing Escape is not required to release it. Pressing Escape while compaction is active cancels it like other session operations. In isolated interactive mode, cancellation and host UI response frames use an independent RPC control lane, so they can reach the engine while the ordinary `compact` request is still pending instead of waiting behind it. Atomic writes a backup snapshot immediately before appending a compaction boundary.
 
+Automatic continuations belong to the original prompt, including repeated output-cap continuations. The prompt and `agent_settled` lifecycle finish only after the entire chain drains, so status integrations such as [Herdr](/herdr) stay working through quiet response waits and continuation gaps.
+
 Manual compaction is single-flight. A manual request made while another manual compaction is still in flight joins that run and receives its result instead of starting a second model call, so it emits no extra `compaction_start`/`compaction_end` pair and appends no extra boundary; `abortCompaction()` (Escape) still cancels the single owning run for every waiter. A manual request made while automatic compaction is active takes ownership: it cancels unfinished automatic work, abandons any pending automatic continuation, waits for the active turn and automatic state to settle, then runs the requested manual compaction. If the automatic boundary committed first, the manual request runs after it rather than reusing that result or writing concurrently. In the interactive TUI, `/compact` uses this takeover only for automatic compaction; a second manual compaction or branch summary is still refused. Ordinary text typed during compaction remains queued and flushes after its non-mid-turn completion, including cancellation or failure.
 
 The post-tool check stays inside the active Pi loop: it runs the rung ladder once for that completed tool turn, returns the rebuilt context to the loop, and never calls or schedules `agent.continue()`. If the caller installed `prepareNextTurn` or `prepareNextTurnWithContext`, Atomic invokes it after compaction with that rebuilt context and sends the caller's complete replacement context through the normal context transform to the next provider request. A `shouldStopAfterTurn` result of `true` takes precedence over queued steering and follow-up messages, including messages queued while the callback is running: Atomic leaves that work pending until a later explicit prompt or continuation instead of starting another provider request. Normal context reconstruction preserves provider tool-call/result protocol validity. Below-threshold tool turns follow the unchanged request path. Because the same active run resumes without emitting another `agent_start`, the interactive TUI replaces the compaction loader with its working spinner and keeps terminal progress active as soon as successful mid-turn compaction ends; streaming feedback therefore resumes immediately without waiting for another user interaction.

package/docs/development.md

@@ -8,15 +8,10 @@ See [AGENTS.md](https://github.com/bastani-inc/atomic/blob/main/AGENTS.md) for a
 git clone https://github.com/bastani-inc/atomic
 cd atomic
 npm ci --ignore-scripts
-npm run typecheck
+npm run build
 ```
 
-This monorepo runs a hybrid toolchain matching upstream pi: npm installs, builds, checks, and runs the vitest suites, while Bun compiles the release binaries and runs `scripts/*.ts`. Avoid yarn and pnpm. Run package scripts from the monorepo root or a package directory, for example:
-
-```bash
-npm run test:unit
-npm run build --workspace=@bastani/atomic
-```
+Use npm for installs, builds, checks, and Vitest suites. Bun compiles standalone binaries and runs repository TypeScript scripts. Do not use yarn, pnpm, or `bun install`.
 
 Atomic keeps the caller's current working directory when launched from development wrappers.
 
@@ -33,7 +28,7 @@ Configure via `package.json`:
 }
 ```
 
-Change `name`, `configDir`, and the `bin` field for your fork. The app-specific `<appName>Config` key is preferred; legacy `piConfig` remains a backwards-compatible shim. Atomic sets these to `atomic`, `.atomic`, and the `atomic` executable. Affects CLI banner, config paths, and environment variable names.
+Change `name`, `configDir`, and the `bin` field for your fork. These control the CLI banner, config paths, and environment variable names. Legacy `piConfig` remains a compatibility fallback.
 
 ## Path Resolution
 
@@ -53,86 +48,42 @@ Never use `__dirname` directly for package assets.
 - Rendered TUI lines with ANSI codes
 - Last messages sent to the LLM
 
-## Startup timing probes
-
-Use `scripts/perf/windows-startup/benchmark.ts` for Windows startup claims. It launches the ordinary bare `atomic` command through a real 120x40 ConPTY, feeds ordered output into `@xterm/headless`, and timestamps each receive with `process.hrtime.bigint()`. Complete first paint requires the final `Atomic v<version>` identity, the focused `❯ ` editor, and two identical settled frames at least one 80 ms animation interval apart. `dispatchMs` runs from the Enter write to the first byte observed by a raw TCP loopback provider. The headline `spawnToDispatchMs` is exactly `startupCompleteMs + dispatchMs`; `launchToProviderFirstByteMs` separately retains the contiguous launch-to-provider interval that also contains nonce typing and editor-echo wait. The provider request must contain the nonce and the normal tool schemas, and every accepted sample must pass `/workflow list` after the timed response. See [the benchmark README](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md) for artifact preparation, cache profiles, raw records, and summary commands.
-
-Do not use `time-to-first-frame` as settled-paint evidence, and do not substitute `launchToProviderFirstByteMs` for the contract sum. The first-frame mark records the host's first requested identity frame after the header is mounted; it does not prove terminal receipt, animation settlement, engine resource readiness, or provider readiness. `ATOMIC_STARTUP_BENCHMARK=1`, `--no-extensions`, and `--no-tools` are attribution controls only. They do not run the accepted full CLI path with bundled workflows, normal extensions, tools, and provider dispatch.
-
-The process-local lifecycle timing seams use monotonic nanoseconds and remain disabled until an internal diagnostic adapter installs a synchronous sink. With no sink, they do not read the clock, write output, or schedule work. External ConPTY and TCP marks remain authoritative. Startup now has several deliberate partial orders rather than one cross-process sequence:
-
-```text
-interactive host: process-entry → interactive-engine-spawn → engine-ready
-                  → tui-start → header-mounted → initialize engine-bound state
-                  → chat-output-release → interactive-input-handler-ready
-
-isolated child:   process-entry → engine-ready → engine-bound
-                  → engine-resources-ready
-
-external screen:  first-terminal-write → startup-coherent → startup-complete
-
-first turn:       interactive-first-submit → before-provider-request
-```
-
-The header and editor are mounted before the host waits for `engine-bound`; the child can therefore report binding while the host is applying its theme or requesting that frame. `engine-bound` means RPC control plus the mandatory minimal session are available. `engine-resources-ready` is a separate, generation-scoped child message sent only after a staged optional snapshot containing bundled extensions, tools, providers, skills, prompts, and themes commits. User prompts, extension commands, model/resource commands, session replacement, and tool-dispatching RPC calls wait for that gate. After a readiness failure, `/reload` bypasses the rejected gate to start a fresh transactional attempt; successful retry replaces the gate before later work proceeds. Escape cancels a first submission that is still waiting, so that continuation cannot dispatch later. `session_start` messages are queued against the candidate snapshot and released only after publication. Mandatory Intercom remains in the minimal runtime. A failed transactional candidate leaves host-managed settings, providers, tools, resources, event subscriptions, and system-prompt state unchanged, restores an unadmitted prompt draft exactly, and reports the generation failure once. Extension-owned objects stored with `sessionScopedExtensionState` are deliberately shared across reloads and are not cloned or rolled back.
-
-`engine-resources-ready` is recorded in the isolated engine process; host marks are recorded in the interactive process. The two process clocks are monotonic but must not be subtracted without an external synchronization protocol. `startup-coherent` and `startup-complete` describe internal render composition, not terminal receipt. The external VT predicates decide the reported first-paint marks.
-
-For package-manager installs under Node 22, Atomic enables Node's persistent module compile cache in both the host and isolated child and flushes the host cache before spawning the child. Explicit `NODE_COMPILE_CACHE` and `NODE_DISABLE_COMPILE_CACHE` settings pass through unchanged. This preserves Node's coverage opt-out and avoids forcing a new cache directory or a first-run-only precompile step. SEA, V8 snapshots, and package-install precompilation were not adopted because Atomic's dynamic ESM, native modules, workers, and first-run requirements do not provide a safe portable boundary.
-
-Compiled releases syntax-minify the shared CJS `app.js` sidecar without identifier minification and compile launchers with bytecode on all eight supported targets, including Windows x64 and ARM64. `bun run scripts/probe-windows-bytecode.ts` pins Bun 1.4.0, cross-compiles `bun-windows-x64-baseline` and `bun-windows-arm64` launchers, and verifies their PE machine types. Atomic observed a Bun 1.3.14 Windows startup crash in `llint_entry`, but Bun 1.4.0 already contains the embedded-bytecode alignment fix ([#26299](https://github.com/oven-sh/bun/pull/26299)) and integrity fallback ([#31961](https://github.com/oven-sh/bun/pull/31961)); the separate Bun 1.4.0 Windows report ([#40302](https://github.com/oven-sh/bun/issues/40302)) concerns a general standalone/JIT segfault and has not been shown to be bytecode-specific. Cross-compilation is not runtime validation: release candidates still require full-archive target-machine coverage of the TUI, workflows, tools, extensions, workers, and native add-ons, with Windows ARM64 validated on ARM64 hardware.
-
-Set `ATOMIC_TIMING=1` only for the older human-readable phase diagnostics. Normal interactive launches print that initial timing group before `interactiveMode.run()` starts the TUI loop, so later marks are not printed during ordinary sessions.
+For startup measurements, see the [Windows startup benchmark](https://github.com/bastani-inc/atomic/blob/main/scripts/perf/windows-startup/README.md). Internal timing marks do not prove terminal first paint.
 
 ## Testing
 
 ```bash
-npm run typecheck                 # Type-check the monorepo
-npm run test:unit                 # Run unit tests
-npm run test:integration          # Run integration tests
-npm run test:all                  # Run all tests
-npm run test:scripts              # Run the repository script tests under node --test
-# Run the package Vitest suite (Node-hosted)
+npm run check                    # Typechecks and published-shrinkwrap validation
+npm run test:unit                # Root unit tests
+npm run test:integration         # Root integration tests
+npm run test:all                 # All root test projects
+npm run test:scripts             # Repository script tests under Node
 npm run test --workspace=@bastani/atomic -- test/specific.test.ts
 ```
 
-Root Vitest projects install a fresh in-memory durable backend before every test.
-Durability initialization imports the backend and its process owner rather than
-preloading the DBOS factory or the Atomic host. A test that needs host prototype
-installers must import those real modules explicitly rather than depend on a
-side effect of shared setup. Test-local backend overrides still use the factory's
-injection seam, and the next test receives a fresh backend without resetting
-unrelated initialization or warning state. Keep the global artifact/native setups,
-default isolation, worker sizing and timeout budgets unchanged when measuring
-test cost. See the [CI measurements](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#current-critical-path-measured-september-5-2026)
-for local gains and the remaining hosted Linux/Windows validation.
-
-CI runs the complete root unit and integration suites in independent Linux and
-Windows jobs. Each builds its own native and package prerequisites; both required
-result gates wait for every work job and reject failures, cancellations and skips.
-This trades duplicated setup for earlier integration feedback without changing
-test isolation, coverage or retries.
+CI runs root unit and integration suites on Linux and Windows. See [CI documentation](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md) for job details and release procedures.
 
-## Deterministic installs
+### Installed package smoke test
 
-`@bastani/atomic` ships `packages/coding-agent/npm-shrinkwrap.json` so package-manager installs resolve the same dependency tree every time. Contributors working from a source checkout can validate that the checked-in shrinkwrap is up to date with:
+After building, run:
 
 ```bash
-bun run scripts/generate-coding-agent-shrinkwrap.mjs --check
+ATOMIC_REQUIRE_INSTALLED_NODE_SMOKE=1 npx vitest --run --project integration test/integration/installed-package-node-extensions.test.ts
 ```
 
-## Release security boundary
+This checks Node startup and builtin extension loading outside the checkout.
 
-Atomic's release bases remain at the `0.0.0` placeholder. `scripts/cut-release.ts` stamps the real version only on a detached tagged release commit. Tag creation runs an inert signal workflow; a separate `workflow_run` publisher loaded from protected `main` validates the exact upstream repository, source workflow/event/run, tag/SHA, immutable release-base trailers, and deterministic release tree. The privileged trigger checks out only protected workflow code: it treats the tag tree as data, exports it only after deterministic verification, and makes every read-only build verify the protected job's source checksum instead of checking out tag-selected code. Same-run artifact transport failures receive at most one retry after partial-download cleanup and still fail explicitly on the second error; verified source archives are streamed to tar over stdin for portable Windows drive-letter handling. Preparation restores the digest-verified source after documentation validation before producing artifacts. Release-source jobs configure no dependency cache, npm publication has OIDC without repository write, and GitHub Release creation has repository write without OIDC. Never move or recreate a failed release tag or dispatch the privileged publisher. See the repository's [CI/CD pipeline](https://github.com/bastani-inc/atomic/blob/main/docs/ci.md#release-pipeline) for trusted-publisher configuration.
+Atomic ships an npm shrinkwrap. After dependency changes, regenerate it with `npm run shrinkwrap:coding-agent` and validate with `npm run check`.
 
 ## Project Structure
 
-```
+```text
 packages/
-  coding-agent/ # Atomic CLI, agent loop, providers, TUI, and core runtime
-  workflows/    # First-party workflow extension bundled into Atomic
-  subagents/    # Built-in subagent orchestration and reusable agents
-  mcp/          # Built-in MCP adapter extension
-  web-access/   # Built-in web search and content extraction tools
-  intercom/     # Built-in cross-session coordination channel
+  ai/           # Atomic's LLM provider fork
+  coding-agent/ # CLI, interactive mode, and core runtime
+  workflows/    # Workflow execution
+  subagents/    # Subagent orchestration
+  mcp/          # MCP adapter
+  web-access/   # Web search and content extraction
+  intercom/     # Cross-session coordination
 ```

package/docs/docs.json

@@ -20,11 +20,13 @@
           "providers",
           "environment-variables",
           "llama-cpp",
+          "herdr",
           "containerization",
           "security",
           "settings",
           "keybindings",
           "sessions",
+          "background-tasks",
           "compaction"
         ]
       },

package/docs/environment-variables.md

@@ -13,7 +13,7 @@ Atomic accepts environment variables for configuration, provider credentials, an
 | `ATOMIC_SKIP_VERSION_CHECK` | `PI_SKIP_VERSION_CHECK` | Skip automatic startup version checks; explicit self-update still checks |
 | `ATOMIC_TELEMETRY` | `PI_TELEMETRY` | Enable/disable install/update telemetry |
 | `ATOMIC_REDUCED_MOTION` | `PI_REDUCED_MOTION` | Use static reduced-motion presentation |
-| `ATOMIC_EXPERIMENTAL` | `PI_EXPERIMENTAL` | Set to `1` to enable experimental features: built-in tool definitions request strict JSON-schema constrained sampling (`prefer`), and the footer shows an `xp` badge |
+| `ATOMIC_EXPERIMENTAL` | `PI_EXPERIMENTAL` | Set to `1` to enable experimental features and preferred strict JSON-schema constrained sampling for additional built-in tools; `read`, `edit`, `write`, `bash`, and PowerShell already prefer strict sampling by default. The footer shows an `xp` badge |
 
 `PI_CACHE_RETENTION=long` is a provider/upstream prompt-cache option and intentionally has no Atomic-prefixed alias. `VISUAL` and `EDITOR` select the Ctrl+G external editor when `externalEditor` is unset.