@pencil-agent/nano-pencil 1.13.0 → 1.13.4

package/dist/builtin-extensions.js

@@ -24,6 +24,8 @@ const BUNDLED_SAL_EXTENSION = join(__dirname, "extensions", "defaults", "sal", "
 const BUNDLED_GRUB_EXTENSION = join(__dirname, "extensions", "defaults", "grub", "index.js");
 const BUNDLED_SUBAGENT_EXTENSION = join(__dirname, "extensions", "defaults", "subagent", "index.js");
 const BUNDLED_TEAM_EXTENSION = join(__dirname, "extensions", "defaults", "team", "index.js");
+const BUNDLED_BTW_EXTENSION = join(__dirname, "extensions", "defaults", "btw", "index.js");
+const BUNDLED_DEBUG_EXTENSION = join(__dirname, "extensions", "defaults", "debug", "index.js");
 const BUNDLED_MCP_EXTENSION = join(__dirname, "extensions", "defaults", "mcp", "index.js");
 const BUNDLED_EXPORT_HTML_EXTENSION = join(__dirname, "extensions", "optional", "export-html", "index.js");
 /** Find package root from current module location (containing package.json with nano-pencil related name) */
@@ -209,6 +211,24 @@ export function getBuiltinExtensionPaths() {
         if (existsSync(teamTs))
             paths.push(teamTs);
     }
+    // === BTW extension (quick side question without interrupting) ===
+    if (existsSync(BUNDLED_BTW_EXTENSION)) {
+        paths.push(BUNDLED_BTW_EXTENSION);
+    }
+    else {
+        const btwTs = join(__dirname, "extensions", "defaults", "btw", "index.ts");
+        if (existsSync(btwTs))
+            paths.push(btwTs);
+    }
+    // === Debug extension (system diagnostics with three-layer analysis) ===
+    if (existsSync(BUNDLED_DEBUG_EXTENSION)) {
+        paths.push(BUNDLED_DEBUG_EXTENSION);
+    }
+    else {
+        const debugTs = join(__dirname, "extensions", "defaults", "debug", "index.ts");
+        if (existsSync(debugTs))
+            paths.push(debugTs);
+    }
     // Built-in MCP extension
     if (existsSync(BUNDLED_MCP_EXTENSION)) {
         paths.push(BUNDLED_MCP_EXTENSION);

package/dist/cli.js

@@ -6,5 +6,28 @@
  * [HERE]: Entry point; orchestrates argument parsing and mode selection
  */
 process.title = "nanopencil";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const args = process.argv.slice(2);
+// Fast path: --version, --help don't need full module loading
+if (args.includes("--version")) {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    // In dev, package.json is in project root; in bundle, it's two levels up from dist/cli.js
+    const pkgPath = __dirname.endsWith("dist") ? join(__dirname, "..", "package.json") : join(__dirname, "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+    console.log(pkg.version);
+    process.exit(0);
+}
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(`nanoPencil AI coding agent`);
+    console.log(`Usage: nanopencil [options]`);
+    console.log(`       nanopencil [command] [options]`);
+    console.log(`Options:`);
+    console.log(`  --version    Show version`);
+    console.log(`  --help, -h   Show this help`);
+    process.exit(0);
+}
 import { main } from "./main.js";
-main(process.argv.slice(2));
+main(args);

package/dist/core/config/settings-manager.d.ts

@@ -113,6 +113,8 @@ export interface Settings {
 export type SettingsScope = "global" | "project";
 export interface SettingsStorage {
     withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
+    withLockAsync(scope: SettingsScope, fn: (current: string | undefined) => Promise<string | undefined>): Promise<void>;
+    readStorageAsync(scope: SettingsScope): Promise<string | undefined>;
 }
 export interface SettingsError {
     scope: SettingsScope;
@@ -123,11 +125,15 @@ export declare class FileSettingsStorage implements SettingsStorage {
     private projectSettingsPath;
     constructor(cwd?: string, agentDir?: string);
     withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
+    withLockAsync(scope: SettingsScope, fn: (current: string | undefined) => Promise<string | undefined>): Promise<void>;
+    readStorageAsync(scope: SettingsScope): Promise<string | undefined>;
 }
 export declare class InMemorySettingsStorage implements SettingsStorage {
     private global;
     private project;
     withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
+    withLockAsync(scope: SettingsScope, fn: (current: string | undefined) => Promise<string | undefined>): Promise<void>;
+    readStorageAsync(scope: SettingsScope): Promise<string | undefined>;
 }
 export declare class SettingsManager {
     private storage;
@@ -145,12 +151,18 @@ export declare class SettingsManager {
     private constructor();
     /** Create a SettingsManager that loads from files */
     static create(cwd?: string, agentDir?: string): SettingsManager;
+    /** Create a SettingsManager that loads from files async */
+    static createAsync(cwd?: string, agentDir?: string): Promise<SettingsManager>;
     /** Create a SettingsManager from an arbitrary storage backend */
     static fromStorage(storage: SettingsStorage): SettingsManager;
+    /** Create a SettingsManager from an arbitrary storage backend async */
+    static fromStorageAsync(storage: SettingsStorage): Promise<SettingsManager>;
     /** Create an in-memory SettingsManager (no file I/O) */
     static inMemory(settings?: Partial<Settings>): SettingsManager;
     private static loadFromStorage;
+    private static loadFromStorageAsync;
     private static tryLoadFromStorage;
+    private static tryLoadFromStorageAsync;
     /** Migrate old settings format to new format */
     private static migrateSettings;
     getGlobalSettings(): Settings;
@@ -158,6 +170,7 @@ export declare class SettingsManager {
     /** Get merged effective settings (project overrides global). */
     getSettings(): Settings;
     reload(): void;
+    reloadAsync(): Promise<void>;
     /** Apply additional overrides on top of current settings */
     applyOverrides(overrides: Partial<Settings>): void;
     /** Mark a global field as modified during this session */
@@ -167,10 +180,14 @@ export declare class SettingsManager {
     private recordError;
     private clearModifiedScope;
     private enqueueWrite;
+    private enqueueWriteAsync;
     private cloneModifiedNestedFields;
     private persistScopedSettings;
+    private persistScopedSettingsAsync;
     private save;
+    private saveAsync;
     private saveProjectSettings;
+    private saveProjectSettingsAsync;
     flush(): Promise<void>;
     drainErrors(): SettingsError[];
     getLastChangelogVersion(): string | undefined;

package/dist/core/config/settings-manager.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
 import lockfile from "proper-lockfile";
 import { APP_NAME, CONFIG_DIR_NAME, getAgentDir } from "../../config.js";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
 /** Deep merge settings: project/overrides take precedence, nested objects merge recursively */
 function deepMergeSettings(base, overrides) {
     const result = { ...base };
@@ -63,6 +64,42 @@ export class FileSettingsStorage {
             }
         }
     }
+    async withLockAsync(scope, fn) {
+        const filePath = scope === "global" ? this.globalSettingsPath : this.projectSettingsPath;
+        const dir = dirname(filePath);
+        let release;
+        try {
+            const fileExists = existsSync(filePath);
+            if (fileExists) {
+                release = lockfile.lockSync(filePath, { realpath: false });
+            }
+            // Read inside the lock so we capture a consistent snapshot before writing.
+            const current = fileExists ? await readFile(filePath, "utf-8") : undefined;
+            const next = await fn(current);
+            if (next !== undefined) {
+                if (!existsSync(dir)) {
+                    await mkdir(dir, { recursive: true });
+                }
+                // Ensure we hold the lock for the write even if we only read above.
+                if (!release) {
+                    release = lockfile.lockSync(filePath, { realpath: false });
+                }
+                await writeFile(filePath, next, "utf-8");
+            }
+        }
+        finally {
+            if (release) {
+                release();
+            }
+        }
+    }
+    async readStorageAsync(scope) {
+        const filePath = scope === "global" ? this.globalSettingsPath : this.projectSettingsPath;
+        if (!existsSync(filePath)) {
+            return undefined;
+        }
+        return readFile(filePath, "utf-8");
+    }
 }
 export class InMemorySettingsStorage {
     global;
@@ -79,6 +116,21 @@ export class InMemorySettingsStorage {
             }
         }
     }
+    async withLockAsync(scope, fn) {
+        const current = scope === "global" ? this.global : this.project;
+        const next = await fn(current);
+        if (next !== undefined) {
+            if (scope === "global") {
+                this.global = next;
+            }
+            else {
+                this.project = next;
+            }
+        }
+    }
+    async readStorageAsync(scope) {
+        return scope === "global" ? this.global : this.project;
+    }
 }
 export class SettingsManager {
     storage;
@@ -107,6 +159,11 @@ export class SettingsManager {
         const storage = new FileSettingsStorage(cwd, agentDir);
         return SettingsManager.fromStorage(storage);
     }
+    /** Create a SettingsManager that loads from files async */
+    static async createAsync(cwd = process.cwd(), agentDir = getAgentDir()) {
+        const storage = new FileSettingsStorage(cwd, agentDir);
+        return SettingsManager.fromStorageAsync(storage);
+    }
     /** Create a SettingsManager from an arbitrary storage backend */
     static fromStorage(storage) {
         const globalLoad = SettingsManager.tryLoadFromStorage(storage, "global");
@@ -120,6 +177,21 @@ export class SettingsManager {
         }
         return new SettingsManager(storage, globalLoad.settings, projectLoad.settings, globalLoad.error, projectLoad.error, initialErrors);
     }
+    /** Create a SettingsManager from an arbitrary storage backend async */
+    static async fromStorageAsync(storage) {
+        const [globalLoadResult, projectLoadResult] = await Promise.all([
+            SettingsManager.tryLoadFromStorageAsync(storage, "global"),
+            SettingsManager.tryLoadFromStorageAsync(storage, "project"),
+        ]);
+        const initialErrors = [];
+        if (globalLoadResult.error) {
+            initialErrors.push({ scope: "global", error: globalLoadResult.error });
+        }
+        if (projectLoadResult.error) {
+            initialErrors.push({ scope: "project", error: projectLoadResult.error });
+        }
+        return new SettingsManager(storage, globalLoadResult.settings, projectLoadResult.settings, globalLoadResult.error, projectLoadResult.error, initialErrors);
+    }
     /** Create an in-memory SettingsManager (no file I/O) */
     static inMemory(settings = {}) {
         const storage = new InMemorySettingsStorage();
@@ -137,6 +209,14 @@ export class SettingsManager {
         const settings = JSON.parse(content);
         return SettingsManager.migrateSettings(settings);
     }
+    static async loadFromStorageAsync(storage, scope) {
+        const content = await storage.readStorageAsync(scope);
+        if (!content) {
+            return {};
+        }
+        const settings = JSON.parse(content);
+        return SettingsManager.migrateSettings(settings);
+    }
     static tryLoadFromStorage(storage, scope) {
         try {
             return { settings: SettingsManager.loadFromStorage(storage, scope), error: null };
@@ -145,6 +225,14 @@ export class SettingsManager {
             return { settings: {}, error: error };
         }
     }
+    static async tryLoadFromStorageAsync(storage, scope) {
+        try {
+            return { settings: await SettingsManager.loadFromStorageAsync(storage, scope), error: null };
+        }
+        catch (error) {
+            return { settings: {}, error: error };
+        }
+    }
     /** Migrate old settings format to new format */
     static migrateSettings(settings) {
         // Migrate queueMode -> steeringMode
@@ -210,6 +298,33 @@ export class SettingsManager {
         }
         this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
     }
+    async reloadAsync() {
+        const [globalLoadResult, projectLoadResult] = await Promise.all([
+            SettingsManager.tryLoadFromStorageAsync(this.storage, "global"),
+            SettingsManager.tryLoadFromStorageAsync(this.storage, "project"),
+        ]);
+        if (!globalLoadResult.error) {
+            this.globalSettings = globalLoadResult.settings;
+            this.globalSettingsLoadError = null;
+        }
+        else {
+            this.globalSettingsLoadError = globalLoadResult.error;
+            this.recordError("global", globalLoadResult.error);
+        }
+        this.modifiedFields.clear();
+        this.modifiedNestedFields.clear();
+        this.modifiedProjectFields.clear();
+        this.modifiedProjectNestedFields.clear();
+        if (!projectLoadResult.error) {
+            this.projectSettings = projectLoadResult.settings;
+            this.projectSettingsLoadError = null;
+        }
+        else {
+            this.projectSettingsLoadError = projectLoadResult.error;
+            this.recordError("project", projectLoadResult.error);
+        }
+        this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
+    }
     /** Apply additional overrides on top of current settings */
     applyOverrides(overrides) {
         this.settings = deepMergeSettings(this.settings, overrides);
@@ -257,6 +372,17 @@ export class SettingsManager {
             this.recordError(scope, error);
         });
     }
+    enqueueWriteAsync(scope, task) {
+        this.writeQueue = this.writeQueue
+            .then(async () => {
+            await task();
+            this.clearModifiedScope(scope);
+        })
+            .catch((error) => {
+            this.recordError(scope, error);
+        });
+        return this.writeQueue;
+    }
     cloneModifiedNestedFields(source) {
         const snapshot = new Map();
         for (const [key, value] of source.entries()) {
@@ -289,6 +415,31 @@ export class SettingsManager {
             return JSON.stringify(mergedSettings, null, 2);
         });
     }
+    async persistScopedSettingsAsync(scope, snapshotSettings, modifiedFields, modifiedNestedFields) {
+        await this.storage.withLockAsync(scope, async (current) => {
+            const currentFileSettings = current
+                ? SettingsManager.migrateSettings(JSON.parse(current))
+                : {};
+            const mergedSettings = { ...currentFileSettings };
+            for (const field of modifiedFields) {
+                const value = snapshotSettings[field];
+                if (modifiedNestedFields.has(field) && typeof value === "object" && value !== null) {
+                    const nestedModified = modifiedNestedFields.get(field);
+                    const baseNested = currentFileSettings[field] ?? {};
+                    const inMemoryNested = value;
+                    const mergedNested = { ...baseNested };
+                    for (const nestedKey of nestedModified) {
+                        mergedNested[nestedKey] = inMemoryNested[nestedKey];
+                    }
+                    mergedSettings[field] = mergedNested;
+                }
+                else {
+                    mergedSettings[field] = value;
+                }
+            }
+            return JSON.stringify(mergedSettings, null, 2);
+        });
+    }
     save() {
         this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
         if (this.globalSettingsLoadError) {
@@ -301,6 +452,18 @@ export class SettingsManager {
             this.persistScopedSettings("global", snapshotGlobalSettings, modifiedFields, modifiedNestedFields);
         });
     }
+    async saveAsync() {
+        this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
+        if (this.globalSettingsLoadError) {
+            return;
+        }
+        const snapshotGlobalSettings = structuredClone(this.globalSettings);
+        const modifiedFields = new Set(this.modifiedFields);
+        const modifiedNestedFields = this.cloneModifiedNestedFields(this.modifiedNestedFields);
+        await this.enqueueWriteAsync("global", async () => {
+            await this.persistScopedSettingsAsync("global", snapshotGlobalSettings, modifiedFields, modifiedNestedFields);
+        });
+    }
     saveProjectSettings(settings) {
         this.projectSettings = structuredClone(settings);
         this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
@@ -314,6 +477,19 @@ export class SettingsManager {
             this.persistScopedSettings("project", snapshotProjectSettings, modifiedFields, modifiedNestedFields);
         });
     }
+    async saveProjectSettingsAsync(settings) {
+        this.projectSettings = structuredClone(settings);
+        this.settings = deepMergeSettings(this.globalSettings, this.projectSettings);
+        if (this.projectSettingsLoadError) {
+            return;
+        }
+        const snapshotProjectSettings = structuredClone(this.projectSettings);
+        const modifiedFields = new Set(this.modifiedProjectFields);
+        const modifiedNestedFields = this.cloneModifiedNestedFields(this.modifiedProjectNestedFields);
+        await this.enqueueWriteAsync("project", async () => {
+            await this.persistScopedSettingsAsync("project", snapshotProjectSettings, modifiedFields, modifiedNestedFields);
+        });
+    }
     async flush() {
         await this.writeQueue;
     }

package/dist/core/extensions/loader.js

@@ -260,10 +260,17 @@ export async function loadExtensions(paths, cwd, eventBus) {
     const errors = [];
     const resolvedEventBus = eventBus ?? createEventBus();
     const runtime = createExtensionRuntime();
-    for (const extPath of paths) {
-        const { extension, error } = await loadExtension(extPath, cwd, resolvedEventBus, runtime);
+    // Parallel loading for faster startup.
+    // Note: unlike the old sequential loop, this collects all errors before surfacing
+    // them — a crashing extension no longer aborts early. This is intentional: we want
+    // all extensions to attempt loading so error reports are comprehensive, not truncated.
+    const results = await Promise.all(paths.map((extPath) => loadExtension(extPath, cwd, resolvedEventBus, runtime).then((result) => ({
+        ...result,
+        path: extPath,
+    }))));
+    for (const { extension, error, path } of results) {
         if (error) {
-            errors.push({ path: extPath, error });
+            errors.push({ path, error });
             continue;
         }
         if (extension) {

package/dist/core/mcp/mcp-client.js

@@ -174,13 +174,24 @@ export class MCPClient {
     }
     async spawnProcess(spec, env, cwd) {
         return await new Promise((resolve, reject) => {
-            const child = spawn(spec.command, spec.args, {
-                env,
-                cwd,
-                stdio: ["pipe", "pipe", "pipe"],
-                windowsHide: true,
-                shell: process.platform === "win32",
-            });
+            // On Windows, use shell mode but pass command as a single string to avoid DEP0190 warning
+            // On Unix, use non-shell mode for better security
+            const useShell = process.platform === "win32";
+            const child = useShell
+                ? spawn([spec.command, ...spec.args].map(arg => arg.includes(" ") ? `"${arg}"` : arg).join(" "), {
+                    env,
+                    cwd,
+                    stdio: ["pipe", "pipe", "pipe"],
+                    windowsHide: true,
+                    shell: true,
+                })
+                : spawn(spec.command, spec.args, {
+                    env,
+                    cwd,
+                    stdio: ["pipe", "pipe", "pipe"],
+                    windowsHide: true,
+                    shell: false,
+                });
             const onError = (err) => {
                 child.removeListener("spawn", onSpawn);
                 reject(err);

package/dist/core/messages.js

@@ -9,7 +9,7 @@ export const BRANCH_SUMMARY_PREFIX = `The following is a summary of a branch tha
 <summary>
 `;
 export const BRANCH_SUMMARY_SUFFIX = `</summary>`;
-export const CUSTOM_MESSAGE_TYPES_EXCLUDED_FROM_CONTEXT = new Set(["presence"]);
+export const CUSTOM_MESSAGE_TYPES_EXCLUDED_FROM_CONTEXT = new Set(["presence", "btw"]);
 /**
  * Convert a BashExecutionMessage to user message text for LLM context.
  */

package/dist/core/package-manager.d.ts

@@ -93,8 +93,9 @@ export declare class DefaultPackageManager implements PackageManager {
     private parseSource;
     /**
      * Check if an npm package needs to be updated.
-     * - For unpinned packages: check if registry has a newer version
      * - For pinned packages: check if installed version matches the pinned version
+     * - For unpinned packages: skip registry check at startup (returns false); registry
+     *   check is deferred to explicit /update or auto-update runs to avoid startup latency
      */
     private npmNeedsUpdate;
     private getInstalledNpmVersion;

package/dist/core/package-manager.js

@@ -129,8 +129,8 @@ function collectFiles(dir, filePattern, skipNodeModules = true, ignoreMatcher, r
             }
         }
     }
-    catch {
-        // Ignore errors
+    catch (err) {
+        console.error("[package-manager] collectFiles failed:", err);
     }
     return files;
 }
@@ -177,8 +177,8 @@ function collectSkillEntries(dir, includeRootFiles = true, ignoreMatcher, rootDi
             }
         }
     }
-    catch {
-        // Ignore errors
+    catch (err) {
+        console.error("[package-manager] collectSkillEntries failed:", err);
     }
     return entries;
 }
@@ -247,8 +247,8 @@ function collectAutoPromptEntries(dir) {
             }
         }
     }
-    catch {
-        // Ignore errors
+    catch (err) {
+        console.error("[package-manager] collectAutoPromptEntries failed:", err);
     }
     return entries;
 }
@@ -283,8 +283,8 @@ function collectAutoThemeEntries(dir) {
             }
         }
     }
-    catch {
-        // Ignore errors
+    catch (err) {
+        console.error("[package-manager] collectAutoThemeEntries failed:", err);
     }
     return entries;
 }
@@ -372,8 +372,8 @@ function collectAutoExtensionEntries(dir) {
             }
         }
     }
-    catch {
-        // Ignore errors
+    catch (err) {
+        console.error("[package-manager] collectAutoExtensionEntries failed:", err);
     }
     return entries;
 }
@@ -862,8 +862,9 @@ export class DefaultPackageManager {
     }
     /**
      * Check if an npm package needs to be updated.
-     * - For unpinned packages: check if registry has a newer version
      * - For pinned packages: check if installed version matches the pinned version
+     * - For unpinned packages: skip registry check at startup (returns false); registry
+     *   check is deferred to explicit /update or auto-update runs to avoid startup latency
      */
     async npmNeedsUpdate(source, installedPath) {
         if (isOfflineModeEnabled()) {
@@ -877,15 +878,9 @@ export class DefaultPackageManager {
             // Pinned: check if installed matches pinned (exact match for now)
             return installedVersion !== pinnedVersion;
         }
-        // Unpinned: check registry for latest version
-        try {
-            const latestVersion = await this.getLatestNpmVersion(source.name);
-            return latestVersion !== installedVersion;
-        }
-        catch {
-            // If we can't check registry, assume it's fine
-            return false;
-        }
+        // For unpinned packages on startup, skip registry check - assume installed version is fine
+        // Registry check will happen only when user explicitly runs /update or auto-update triggers
+        return false;
     }
     getInstalledNpmVersion(installedPath) {
         const packageJsonPath = join(installedPath, "package.json");
@@ -1372,8 +1367,8 @@ export class DefaultPackageManager {
                     files.push(...collectResourceFiles(p, resourceType));
                 }
             }
-            catch {
-                // Ignore errors
+            catch (err) {
+                console.error("[package-manager] collectFilesFromPaths failed:", err);
             }
         }
         return files;

package/dist/core/runtime/agent-session.js

@@ -339,7 +339,9 @@ export class AgentSession {
         if (event.type === "message_update") {
             // Streaming updates: emit to UI immediately, don't await extensions
             this._emit(event);
-            this._emitExtensionEvent(event).catch(() => { });
+            this._emitExtensionEvent(event).catch((err) => {
+                this._logger.error("[extension] message_update event error", { error: err });
+            });
         }
         else {
             // All other events: extensions run concurrently with UI notification
@@ -394,8 +396,9 @@ export class AgentSession {
                         await this._soulManager.recordInteraction(context, outcome, "turn");
                         await this._soulManager.updateExpertise(expertiseDomain, tags, outcome === "success");
                     }
-                    catch {
+                    catch (err) {
                         // Keep Soul failures non-blocking for the main session lifecycle.
+                        this._logger.warn("[soul] recordInteraction/updateExpertise failed", { error: err });
                     }
                 })();
             }
@@ -408,7 +411,9 @@ export class AgentSession {
                 type: "agent_end",
                 messages: event.messages,
             })
-                .catch(() => { });
+                .catch((err) => {
+                this._logger.error("[extension] agent_end event error", { error: err });
+            });
         }
     };
     /** Extract text content from a message */

package/dist/extensions/defaults/CLAUDE.md

@@ -17,16 +17,21 @@ security-audit/engine/interceptor.ts: Request/response interception, Interceptor
 security-audit/engine/logger.ts: Security event logging, JSON file audit trail
 security-audit/engine/detector.ts: Vulnerability detection, pattern matching for dangerous commands
 soul/index.ts: AI personality evolution extension, persistent personality across sessions
-grub/index.ts: Grub extension entry - autonomous iterative task runner extracted from legacy loop, /grub command + GRUB_MESSAGE_TYPE renderer
-grub/grub-controller.ts: GrubController - drives autonomous grub iterations, state machine for LoopTaskState
-grub/grub-parser.ts: Grub command parsing, parseGrubCommand/buildGrubHelp
-grub/grub-types.ts: Grub types, GrubStatus/GrubDecisionStatus/GrubDecision/GrubTaskState/GrubTaskSnapshot
-grub/README.md: Grub extension documentation - autonomous "keep digging until done" runner
+grub/index.ts: Grub extension entry - long-running autonomous harness, dual-phase system prompts (initializer/coding), /grub command (start/status/resume/stop) + grub renderer, session_start auto-adopt, git harness commit, pruneStale cleanup
+grub/grub-controller.ts: GrubController - state machine for /grub iterations, durable persistState on every transition, adoptResumedTask for cross-session resume, validateCompletion downgrades premature complete when feature-list still has pending entries
+grub/grub-parser.ts: Grub command parsing - parseGrubCommand/buildGrubHelp with resume subcommand, status --json, --max-iter/--max-fail flags
+grub/grub-types.ts: Grub types - GrubStatus/GrubDecisionStatus/GrubDecision/GrubPhase/GrubTaskState/GrubTaskSnapshot/ParsedGrubCommand + FeatureItem/FeatureList (version 1 schema) + PersistedGrubState envelope
+grub/grub-feature-list.ts: feature-list.json IO - readFeatureList/writeFeatureList atomic write, validateFeatureListDiff enforces passes/evidence-only mutations, createInitialFeatureList placeholder, migrateChecklistToFeatureList legacy converter, countPassing/allPassing/firstPending helpers
+grub/grub-persistence.ts: Cross-session persistence - persistState atomic JSON write to .grub/<id>/state.json, loadState shape-validated read, discoverActiveTasks scans .grub/ for running records, pruneStale removes terminal harnesses older than 30 days by default
+grub/README.md: Grub extension documentation - long-running harness contract, feature-list.json schema, completion guard, cross-session resume, legacy migration
 loop/index.ts: Loop extension entry - session-scoped recurring prompt/command scheduler with pause/resume/run-now/max-runs/quiet, /loop command + LOOP_MESSAGE_TYPE renderer
 loop/scheduler-controller.ts: SchedulerController - in-memory recurring task store with pause/resume/run-now/max-runs, MAX_SCHEDULED_TASKS=50
 loop/scheduler-parser.ts: Loop command parsing with flags/subcommands, parseSchedulerCommand/parseDurationSpec/buildSchedulerHelp, --name/--max/--quiet
 loop/scheduler-types.ts: Scheduled loop types, LoopPayloadKind/ScheduledLoopTask/LoopStartSpec/ParsedSchedulerCommand
 loop/README.md: Loop extension documentation - recurring scheduler usage and flags
+btw/index.ts: BTW extension entry - /btw command for quick side questions without interrupting main task, uses completeSimple() for lightweight response, BTW_MESSAGE_TYPE renderer
+debug/index.ts: Debug extension entry - /debug command for system diagnostics with three-layer analysis (Phenomenon/Essence/Philosophy), supports /debug env|session|model subcommands, uses completeSimple() for LLM analysis, DEBUG_MESSAGE_TYPE renderer
+debug/collectors.ts: Diagnostic data collectors for /debug command, collectSystemInfo/collectModelInfo/collectSessionInfo/collectConfigInfo/collectGitInfo/collectAgentState, sanitizeForLLM, formatDiagnosticData
 plan/index.ts: Plan Mode extension entry - registers /plan command, EnterPlanMode/ExitPlanMode tools, permission gating, workflow prompt injection
 plan/types.ts: PlanModeState, PlanModeAttachment types, PlanModeConfig, PlanApprovalRequest/Response
 plan/plan-file-manager.ts: PlanFileManager - plan file path management and I/O, slug generation, plans directory

package/dist/extensions/defaults/btw/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: btwExtension - registers /btw command and BTW message renderer
+ * [FROM]: Depends on core/extensions/types
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/defaults/btw/index.ts - quick side question without interrupting main task
+ */
+import type { ExtensionAPI } from "../../../core/extensions/types.js";
+export default function btwExtension(api: ExtensionAPI): Promise<void>;