@shrkcrft/cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/commands/cache-align.command.d.ts

@@ -0,0 +1,12 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk align` — replace volatile tokens (UUIDs/JWTs/timestamps/hashes) with
+ * stable placeholders so a provider KV-cache prefix stays steady across turns.
+ * Aligned text → stdout; the reversible map is written to `--map <path>` (or
+ * `.sharkcraft/cache-align/align.json`). Pass an existing `--map` to carry
+ * ordinals forward. `shrk unalign` restores.
+ */
+export declare const alignCommand: ICommandHandler;
+/** `shrk unalign` — the restore half: turn placeholders back into originals. */
+export declare const unalignCommand: ICommandHandler;
+//# sourceMappingURL=cache-align.command.d.ts.map

package/dist/commands/cache-align.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-align.command.d.ts","sourceRoot":"","sources":["../../src/commands/cache-align.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,eA4B1B,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,cAAc,EAAE,eAuB5B,CAAC"}

package/dist/commands/cache-align.command.js

@@ -0,0 +1,78 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { alignVolatileTokens, restoreVolatileTokens, } from '@shrkcrft/compress';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+function readInput(args) {
+    const positional = args.positional[0];
+    const useStdin = flagBool(args, 'stdin') || positional === undefined || positional === '-';
+    return useStdin ? readFileSync(0, 'utf8') : readFileSync(positional, 'utf8');
+}
+function loadMap(path) {
+    if (!path || !existsSync(path))
+        return undefined;
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof parsed === 'object' && parsed !== null && Array.isArray(parsed.bindings)) {
+        return parsed;
+    }
+    return undefined;
+}
+/**
+ * `shrk align` — replace volatile tokens (UUIDs/JWTs/timestamps/hashes) with
+ * stable placeholders so a provider KV-cache prefix stays steady across turns.
+ * Aligned text → stdout; the reversible map is written to `--map <path>` (or
+ * `.sharkcraft/cache-align/align.json`). Pass an existing `--map` to carry
+ * ordinals forward. `shrk unalign` restores.
+ */
+export const alignCommand = {
+    name: 'align',
+    description: 'Replace volatile tokens with stable placeholders for KV-cache prefix stability; reversible via `shrk unalign`.',
+    usage: 'shrk [--cwd <dir>] align [<file>|-] [--stdin] [--map <path>] [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        let content;
+        try {
+            content = readInput(args);
+        }
+        catch (e) {
+            process.stderr.write(`align: cannot read input — ${e.message}\n`);
+            return 1;
+        }
+        const mapPath = flagString(args, 'map') ?? nodePath.join(cwd, '.sharkcraft', 'cache-align', 'align.json');
+        const result = alignVolatileTokens(content, loadMap(mapPath));
+        mkdirSync(nodePath.dirname(mapPath), { recursive: true });
+        writeFileSync(mapPath, JSON.stringify(result.map, null, 2), 'utf8');
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ aligned: result.aligned, map: result.map, replaced: result.replaced }) + '\n');
+            return 0;
+        }
+        process.stdout.write(result.aligned + '\n');
+        process.stderr.write(`aligned: ${result.replaced} token(s) replaced · map → ${mapPath}\n`);
+        return 0;
+    },
+};
+/** `shrk unalign` — the restore half: turn placeholders back into originals. */
+export const unalignCommand = {
+    name: 'unalign',
+    description: 'Restore the original volatile tokens in aligned text using its `--map`.',
+    usage: 'shrk [--cwd <dir>] unalign [<file>|-] [--stdin] --map <path>',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const mapPath = flagString(args, 'map') ?? nodePath.join(cwd, '.sharkcraft', 'cache-align', 'align.json');
+        const map = loadMap(mapPath);
+        if (!map) {
+            process.stderr.write(`unalign: no alignment map at "${mapPath}" (pass --map <path>).\n`);
+            return 1;
+        }
+        let content;
+        try {
+            content = readInput(args);
+        }
+        catch (e) {
+            process.stderr.write(`unalign: cannot read input — ${e.message}\n`);
+            return 1;
+        }
+        process.stdout.write(restoreVolatileTokens(content, map) + '\n');
+        return 0;
+    },
+};

package/dist/commands/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}

package/dist/commands/command-catalog.js

@@ -1495,6 +1495,48 @@ export const COMMAND_CATALOG = Object.freeze([
         intendedAudience: [CommandAudience.Human, CommandAudience.Ci],
         taskRole: CommandTaskRole.Inspect,
     }),
+    entry({
+        command: 'compress',
+        description: 'Deterministically compress a blob (file or stdin) to cut tokens — JSON→table, logs/search/diffs→signal. Reversible via `shrk expand`.',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSessionOnly,
+        writesFiles: true,
+        mcpAvailable: true,
+        surface: CommandSurface.Common,
+        intendedAudience: [CommandAudience.Agent, CommandAudience.Human],
+        taskRole: CommandTaskRole.Context,
+    }),
+    entry({
+        command: 'expand',
+        description: 'Retrieve the full original a `shrk compress` run cached, by its `<<ccr:KEY>>` key.',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        surface: CommandSurface.Common,
+        intendedAudience: [CommandAudience.Agent, CommandAudience.Human],
+        taskRole: CommandTaskRole.Context,
+    }),
+    entry({
+        command: 'align',
+        description: 'Replace volatile tokens (UUIDs/JWTs/timestamps/hashes) with stable placeholders for KV-cache prefix stability; reversible via `shrk unalign`.',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSessionOnly,
+        writesFiles: true,
+        mcpAvailable: true,
+        surface: CommandSurface.Advanced,
+        intendedAudience: [CommandAudience.Agent, CommandAudience.Human],
+        taskRole: CommandTaskRole.Context,
+    }),
+    entry({
+        command: 'unalign',
+        description: 'Restore the original volatile tokens in aligned text using its `--map`.',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        mcpAvailable: true,
+        surface: CommandSurface.Advanced,
+        intendedAudience: [CommandAudience.Agent, CommandAudience.Human],
+        taskRole: CommandTaskRole.Context,
+    }),
     // ── Backend feature expansion ─────────────────────────────────────────
     entry({
         command: 'bundle create',

package/dist/commands/compress.command.d.ts

@@ -0,0 +1,15 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk compress` — deterministically compress a blob (file or stdin) before
+ * it re-enters an agent prompt. Same information, fewer tokens. Lossy passes
+ * cache the original under `.sharkcraft/ccr/` so `shrk expand <key>` can get
+ * it back. The compressed text goes to stdout (pipeable); the savings summary
+ * goes to stderr unless `--json` is set.
+ */
+export declare const compressCommand: ICommandHandler;
+/**
+ * `shrk expand` — the retrieve half of CCR. Print the full original that
+ * `shrk compress` cached for a `<<ccr:KEY>>` key.
+ */
+export declare const expandCommand: ICommandHandler;
+//# sourceMappingURL=compress.command.d.ts.map

package/dist/commands/compress.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,eAkE7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA0B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { compressContent, EContentType, FileCcrStore, } from '@shrkcrft/compress';
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+const CONTENT_TYPES = new Set(Object.values(EContentType));
+function ccrDir(cwd) {
+    return nodePath.join(cwd, '.sharkcraft', 'ccr');
+}
+function readInput(args) {
+    const positional = args.positional[0];
+    const useStdin = flagBool(args, 'stdin') || positional === undefined || positional === '-';
+    if (useStdin)
+        return readFileSync(0, 'utf8');
+    return readFileSync(positional, 'utf8');
+}
+/**
+ * `shrk compress` — deterministically compress a blob (file or stdin) before
+ * it re-enters an agent prompt. Same information, fewer tokens. Lossy passes
+ * cache the original under `.sharkcraft/ccr/` so `shrk expand <key>` can get
+ * it back. The compressed text goes to stdout (pipeable); the savings summary
+ * goes to stderr unless `--json` is set.
+ */
+export const compressCommand = {
+    name: 'compress',
+    description: 'Compress a blob (file or stdin) deterministically to cut tokens — JSON→table, logs/search/diffs→signal. Reversible via `shrk expand`.',
+    usage: 'shrk [--cwd <dir>] compress [<file>|-] [--stdin] [--type <content-type>] [--query <text>] [--max <n>] [--no-cache] [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        let content;
+        try {
+            content = readInput(args);
+        }
+        catch (e) {
+            process.stderr.write(`compress: cannot read input — ${e.message}\n`);
+            return 1;
+        }
+        if (content.length === 0) {
+            process.stderr.write('compress: empty input.\n');
+            return 1;
+        }
+        const opts = {};
+        if (!flagBool(args, 'no-cache'))
+            opts.store = new FileCcrStore(ccrDir(cwd));
+        const query = flagString(args, 'query');
+        if (query)
+            opts.query = query;
+        const max = flagNumber(args, 'max');
+        if (max !== undefined && max > 0)
+            opts.maxItems = Math.floor(max);
+        const type = flagString(args, 'type');
+        if (type && CONTENT_TYPES.has(type))
+            opts.contentType = type;
+        const result = compressContent(content, opts);
+        const pct = Math.round(result.savings.ratio * 100);
+        // A lossy result with no cached original (i.e. --no-cache) can't be undone
+        // by `shrk expand`. Warn so the dropped detail isn't lost silently.
+        if (result.lossy && !result.ccrKey) {
+            process.stderr.write('warning: compressed lossily but the original was NOT cached (--no-cache) — ' +
+                'detail is unrecoverable; omit --no-cache to keep it retrievable via `shrk expand`.\n');
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                contentType: result.contentType,
+                strategy: result.strategy,
+                lossy: result.lossy,
+                tokensBefore: result.savings.before,
+                tokensAfter: result.savings.after,
+                tokensSaved: result.savings.saved,
+                savedRatio: result.savings.ratio,
+                ccrKey: result.ccrKey ?? null,
+                note: result.note,
+                compressed: result.compressed,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(result.compressed + '\n');
+        const cached = result.ccrKey ? ` · original cached as ${result.ccrKey} (shrk expand ${result.ccrKey})` : '';
+        process.stderr.write(`${result.strategy}: ${result.savings.before} → ${result.savings.after} tokens (−${pct}%)${cached}\n`);
+        return 0;
+    },
+};
+/**
+ * `shrk expand` — the retrieve half of CCR. Print the full original that
+ * `shrk compress` cached for a `<<ccr:KEY>>` key.
+ */
+export const expandCommand = {
+    name: 'expand',
+    description: 'Retrieve the full original a `shrk compress` run cached, by its `<<ccr:KEY>>` key.',
+    usage: 'shrk [--cwd <dir>] expand <key> [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const key = (args.positional[0] ?? '').trim();
+        if (key.length === 0) {
+            process.stderr.write('expand: a CCR key is required (e.g. `shrk expand a1b2c3d4e5f60718`).\n');
+            return 1;
+        }
+        const store = new FileCcrStore(ccrDir(cwd));
+        const entry = store.get(key);
+        if (!entry) {
+            process.stderr.write(`expand: no cached original for key "${key}" under ${ccrDir(cwd)}.\n`);
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ key: entry.key, bytes: entry.bytes, content: entry.content }) + '\n');
+            return 0;
+        }
+        process.stdout.write(entry.content + '\n');
+        return 0;
+    },
+};

package/dist/commands/context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,cAAc,EAAE,eAiI5B,CAAC"}
+{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eAyI5B,CAAC"}

package/dist/commands/context.command.js

@@ -6,10 +6,33 @@ import * as nodePath from 'node:path';
 import { buildUniversalSearch, explainTaskRouting, recommendCommands, renderOverviewText, buildProjectOverview, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+/**
+ * Minimal JSON shape for agent / skill consumption — the context-side mirror
+ * of `shrk task --compact`. Drops the heavy `body` and `request` echo and
+ * carries the section map + structured action hints (so the agent reads
+ * forbiddenActions / verificationCommands / preferredFlow directly instead of
+ * regexing the markdown body). The schema marker is distinct so consumers can
+ * tell the shapes apart at a glance.
+ */
+function minimalContext(task, result, commands) {
+    return {
+        schema: 'sharkcraft.context/v1-compact',
+        task,
+        tokens: { used: result.totalTokens, max: result.maxTokens },
+        sections: result.sections.map((s) => ({
+            title: s.title,
+            tokens: s.tokens,
+            ...(s.truncated ? { truncated: true } : {}),
+        })),
+        omittedSections: result.omittedSections,
+        actionHints: result.actionHints,
+        topCommands: (commands?.recommendations ?? []).slice(0, 5).map((r) => r.command),
+    };
+}
 export const contextCommand = {
     name: 'context',
     description: 'Build relevant AI-ready context for a task (token-budgeted). Subcommands: build / refresh / status.',
-    usage: 'shrk context [build|refresh|status] --task "<task>" [--max-tokens 3000] [--framework x] [--area y] [--json]',
+    usage: 'shrk context [build|refresh|status] --task "<task>" [--max-tokens 3000] [--framework x] [--area y] [--json] [--compact] [--full]',
     async run(args) {
         // Dispatch subcommands (build / refresh / status) based on first positional.
         const sub = args.positional[0];
@@ -79,6 +102,14 @@ export const contextCommand = {
             // ignore — fall back to legacy context only.
         }
         if (flagBool(args, 'json') || flagBool(args, 'machine-json')) {
+            // `--compact` emits a minimal, structured agent shape (no long body /
+            // request echo) — the context-side mirror of `shrk task --compact`.
+            // Carries the load-bearing action hints as structured data so the agent
+            // never has to parse the markdown body. Full shape stays the default.
+            if (flagBool(args, 'compact')) {
+                process.stdout.write(asJson(minimalContext(task, result, commandRecommendations)) + '\n');
+                return 0;
+            }
             process.stdout.write(asJson({
                 ...result,
                 commands: commandRecommendations,

package/dist/commands/smart-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyDhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA+JjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAiMF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC"}
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyDhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA6LjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC"}

package/dist/commands/smart-context.command.js

@@ -1,7 +1,8 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { AiMessageRole, buildPromptMessages, EnhancementPipeline, EnhancementStageKind, OllamaProvider, buildDefaultEnhancementStages, selectAiProvider, } from '@shrkcrft/ai';
+import * as os from 'node:os';
+import { AiMessageRole, buildPromptMessages, EnhancementPipeline, EnhancementStageKind, OllamaProvider, buildDefaultEnhancementStages, buildFastEnhancementStages, selectAiProvider, } from '@shrkcrft/ai';
 import { buildContext } from '@shrkcrft/context';
 import { EdgeKind, GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
 import { buildProjectOverview, buildTaskPacket, inspectSharkcraft, renderOverviewText, } from '@shrkcrft/inspector';
@@ -42,13 +43,28 @@ const SMART_CONTEXT_DIR = nodePath.join('.sharkcraft', 'smart-context');
 export const smartContextCommand = {
     name: 'smart-context',
     description: 'Build deterministic context and ask an AI provider to synthesise an enriched brief (default), structured plan (--plan), or two-stage development plan (--ai-plan).',
-    usage: 'shrk smart-context "<task>" [--plan] [--ai-plan] [--save] [--provider auto|ollama|llamacpp] [--enhance|--no-enhance] [--enhance-passes N] [--instructions <path>] [--no-instructions] [--model <id>] [--max-tokens N] [--stage1-max-tokens N] [--seed-tokens N] [--expansion-tokens N] [--expansion-limit N] [--log-prompt] [--save-conversation[=<path>]] [--dry-run] [--debug] [--json]',
+    usage: 'shrk smart-context "<task>" [--plus] [--budget <seconds>] [--plan] [--ai-plan] [--save] [--provider auto|ollama|llamacpp] [--enhance|--no-enhance] [--enhance-passes N] [--instructions <path>] [--no-instructions] [--model <id>] [--max-tokens N] [--stage1-max-tokens N] [--seed-tokens N] [--expansion-tokens N] [--expansion-limit N] [--log-prompt] [--save-conversation[=<path>]] [--dry-run] [--debug] [--json]',
     async run(args) {
         const task = args.positional.join(' ').trim();
         if (!task) {
             process.stderr.write('Usage: shrk smart-context "<task>" [--plan] [--ai-plan] [--save]\n');
             return 2;
         }
+        // Isolate the LLM / native-runtime work in a child process. On macOS the
+        // node-llama-cpp (ggml/Metal) and ONNX static destructors abort during
+        // `exit()` — surfacing a GGML backtrace + `libc++abi … mutex lock failed`
+        // (and a shell `abort`) AFTER a perfectly good result. There is no JS hook
+        // in this Node build to skip libc++ finalizers, so instead the child
+        // self-contains that noise (fd 2 → log on exit) and hands its real exit
+        // code back through a sentinel file; the parent never loads a native
+        // runtime, so it exits cleanly with the correct code. Dry-run does no
+        // native work, so it stays in-process. Gated on SHRK_CLI so a unit test
+        // calling `run()` in-process never spawns a subprocess.
+        if (process.env.SHRK_CLI === '1' &&
+            process.env.SHRK_SMART_CONTEXT_WORKER !== '1' &&
+            !flagBool(args, 'dry-run')) {
+            return runSmartContextInChild();
+        }
         const cwd = resolveCwd(args);
         const opts = readCommonOptions(args);
         const inspection = await inspectSharkcraft({ cwd });
@@ -125,6 +141,15 @@ export const smartContextCommand = {
                     process.stderr.write(`[smart-context] conversation saved → ${path}\n`);
                 }
             }
+            const enh = enhanced.value.enhancement;
+            if (!opts.json && !enh.deterministicFallback) {
+                if (enh.budgetExhausted) {
+                    process.stderr.write(`[smart-context] budget reached before all ${enh.plannedPasses} passes finished — output is the best so far. Try a smaller --model or raise --budget.\n`);
+                }
+                if (!enh.plus) {
+                    process.stderr.write(`[smart-context] fast ${enh.plannedPasses}-pass enhancement. Pass --plus for the full draft→critique→refine→polish (denser, slower).\n`);
+                }
+            }
             const envelope = buildEnvelope({
                 task,
                 seed,
@@ -1040,6 +1065,63 @@ function isEmbeddingsCleanupNoise(line) {
  * already set the kernel-visible exit code before the abort. We
  * surface that code verbatim.
  */
+/**
+ * Run a smart-context brief/plan in an isolated child and return its real exit
+ * code. stdio is inherited so progress + result flow straight to the user's
+ * terminal; the child redirects fd 2 to a log file before its native teardown
+ * abort, so no backtrace reaches the console. The child writes its true exit
+ * code to a sentinel file (read back here) because the SIGABRT during teardown
+ * would otherwise clobber it with 134. The parent loads no native runtime, so
+ * it exits cleanly — no `zsh: abort`, correct code.
+ */
+function runSmartContextInChild() {
+    return new Promise((resolve) => {
+        const exitFile = nodePath.join(os.tmpdir(), `shrk-sc-exit-${process.pid}-${Date.now()}.code`);
+        const child = spawn(process.execPath, process.argv.slice(1), {
+            env: {
+                ...process.env,
+                SHRK_SMART_CONTEXT_WORKER: '1',
+                SHRK_WORKER_EXITCODE_FILE: exitFile,
+            },
+            stdio: 'inherit',
+        });
+        child.on('error', (err) => {
+            process.stderr.write(`Failed to spawn smart-context worker: ${err.message}\n`);
+            resolve(1);
+        });
+        child.on('close', (code, signal) => {
+            // Prefer the sentinel — the worker writes its true exit code before the
+            // native teardown can abort the process.
+            let real = null;
+            try {
+                if (existsSync(exitFile)) {
+                    const raw = readFileSync(exitFile, 'utf8').trim();
+                    if (raw.length > 0 && Number.isFinite(Number(raw)))
+                        real = Number(raw);
+                    try {
+                        unlinkSync(exitFile);
+                    }
+                    catch {
+                        // best-effort cleanup
+                    }
+                }
+            }
+            catch {
+                // fall through to the signal/code-based result below
+            }
+            if (real !== null) {
+                resolve(real);
+                return;
+            }
+            // No sentinel (worker crashed mid-run, not during teardown) → surface a
+            // failure rather than masking it. SIGABRT with no sentinel ⇒ non-zero.
+            if (typeof code === 'number')
+                resolve(code);
+            else
+                resolve(signal ? 1 : 0);
+        });
+    });
+}
 function runEmbeddingsBuildInChild() {
     return new Promise((resolve) => {
         const child = spawn(process.execPath, process.argv.slice(1), {
@@ -1269,6 +1351,10 @@ function readCommonOptions(args) {
         stream: flagBool(args, 'stream'),
         enhance: resolveEnhanceFlag(args),
         enhancePasses: flagNumber(args, 'enhance-passes') ?? readEnhancePassesEnv(),
+        plus: flagBool(args, 'plus'),
+        ...(flagNumber(args, 'budget') !== undefined
+            ? { budgetMs: Math.max(1, flagNumber(args, 'budget')) * 1000 }
+            : {}),
         logPrompt: flagBool(args, 'log-prompt'),
         saveConversation: flagBool(args, 'save-conversation') || flagString(args, 'save-conversation') !== undefined,
         ...(flagString(args, 'save-conversation')
@@ -2514,13 +2600,29 @@ function truncateLine(text, max) {
  * system body verbatim across stages so the model never loses
  * grounding; only the user turn changes per stage.
  */
+/**
+ * Wall-clock ceilings for the enhancement pipeline. These are anti-hang
+ * guards, not target runtimes — the speed win comes from running fewer passes
+ * by default and from picking a smaller `--model`. A slow model that overruns
+ * degrades to the best output so far (or the deterministic seed). Override per
+ * invocation with `--budget <seconds>`.
+ */
+const PER_STAGE_TIMEOUT_MS = 90_000;
+const FAST_ENHANCE_BUDGET_MS = 150_000;
+const PLUS_ENHANCE_BUDGET_MS = 360_000;
 async function runEnhancementPipeline(input) {
     const provider = input.provider;
     const systemMsg = input.messages.find((m) => m.role === AiMessageRole.System);
     const userMsg = input.messages.find((m) => m.role === AiMessageRole.User);
     const originalContext = systemMsg?.content ?? '';
     const taskBody = userMsg?.content ?? input.seed.task;
-    const pipeline = new EnhancementPipeline(buildDefaultEnhancementStages());
+    // Default is the fast 2-pass draft→polish; `--plus` opts into the full
+    // draft→critique→refine→polish for denser output. Both are wall-clock
+    // bounded so a slow local model degrades gracefully instead of hanging.
+    const plus = input.options.plus;
+    const stages = plus ? buildDefaultEnhancementStages() : buildFastEnhancementStages();
+    const budgetMs = input.options.budgetMs ?? (plus ? PLUS_ENHANCE_BUDGET_MS : FAST_ENHANCE_BUDGET_MS);
+    const pipeline = new EnhancementPipeline(stages);
     const stageInputs = [];
     const stageResponses = [];
     // Tee per-stage prompts/responses so we can rebuild the conversation
@@ -2540,6 +2642,8 @@ async function runEnhancementPipeline(input) {
     const piRun = await pipeline.run({ task: taskBody, originalContext }, recordingProvider, {
         ...(input.options.enhancePasses ? { maxPasses: input.options.enhancePasses } : {}),
         maxTokensPerStage: input.options.maxTokens,
+        budgetMs,
+        perStageTimeoutMs: PER_STAGE_TIMEOUT_MS,
         ...(input.options.model ? { model: input.options.model } : {}),
         onStage: (e) => {
             if (!input.options.json) {
@@ -2607,6 +2711,9 @@ async function runEnhancementPipeline(input) {
                 })),
                 totalUsage: piRun.value.totalUsage,
                 deterministicFallback: piRun.value.deterministicFallback,
+                budgetExhausted: piRun.value.budgetExhausted,
+                plannedPasses: stages.length,
+                plus,
             },
             turns,
         },

package/dist/dashboard/dashboard-api-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-api-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/dashboard-api-server.ts"],"names":[],"mappings":"AA4DA,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AA2BD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqC1F;AA2jBD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"dashboard-api-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/dashboard-api-server.ts"],"names":[],"mappings":"AAuIA,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AA2BD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqC1F;AA0lBD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

package/dist/dashboard/dashboard-api-server.js

@@ -15,10 +15,71 @@ import * as http from 'node:http';
 import * as fs from 'node:fs';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildDashboardAdoption, buildDashboardArchitecture, buildDashboardBoundaries, buildDashboardCapabilities, buildDashboardCommands, buildDashboardCoverage, buildDashboardDoctor, buildDashboardDrift, buildDashboardGraph, buildDashboardGraphNode, buildDashboardGraphPath, buildDashboardHealth, buildDashboardMcpSummary, buildDashboardOnboarding, buildDashboardOverview, buildDashboardPacks, buildDashboardPipelines, buildDashboardPresets, buildDashboardQuality, buildDashboardReports, buildDashboardReview, buildDashboardSafety, buildDashboardScaffolds, buildDashboardSchemas, buildDashboardSessionDetail, buildDashboardSessions, buildDashboardStats, inspectSharkcraft, renderDevSessionHtml, scanDevSession, } from '@shrkcrft/inspector';
+import { buildDashboardAdoption, buildDashboardArchitecture, buildDashboardBoundaries, buildDashboardCapabilities, buildDashboardCommands, buildDashboardCoverage, buildDashboardDoctor, buildDashboardDrift, buildDashboardGraph, buildDashboardGraphNode, buildDashboardGraphPath, buildDashboardHealth, buildDashboardKnowledgeList, buildDashboardKnowledgeEntry, buildDashboardKnowledgeGraph, buildDashboardKnowledgeSimilar, buildDashboardMcpSummary, buildDashboardOnboarding, buildDashboardOverview, buildDashboardPacks, buildDashboardPipelines, buildDashboardPresets, buildDashboardQuality, buildDashboardReports, buildDashboardReview, buildDashboardSafety, buildDashboardScaffolds, buildDashboardSchemas, buildDashboardSessionDetail, buildDashboardSessions, buildDashboardStats, inspectSharkcraft, renderDevSessionHtml, scanDevSession, } from '@shrkcrft/inspector';
+import { EContentType, compactArrayToColumnar, estimateTokens } from '@shrkcrft/compress';
 import { COMMAND_CATALOG } from "../commands/command-catalog.js";
 import { buildDashboardCodeIntelligence, buildDashboardMigrations, buildDashboardQualityGates, buildDashboardRoutes, } from "./code-intelligence-data.js";
+import { buildKnowledgeAsk } from "./knowledge-ask.js";
 const SCHEMA_ID = 'sharkcraft.dashboard-api/v1';
+/**
+ * Compute the deterministic compression layer's per-surface token savings for
+ * the dashboard. Measured on the live workspace (no timestamps → stable).
+ *
+ * `realTokens`, when supplied, is an exact BPE tokenizer (cl100k_base); the
+ * panel then reports exact counts and flags `tokensAreEstimated: false`. With
+ * no tokenizer (the default in a published install, where the dev-only
+ * `gpt-tokenizer` is absent) it falls back to the engine's estimator — whose
+ * *percentages* are sound but whose *absolutes* are rough — and flags
+ * `tokensAreEstimated: true` so the UI never presents an estimate as exact.
+ */
+function buildDashboardCompression(inspection, realTokens) {
+    const graph = buildDashboardKnowledgeGraph(inspection);
+    // Both encodings are JSON, so when estimating, score them with the JSON
+    // divisor — the same ratio the engine uses — for the closest absolute counts.
+    const count = (text) => realTokens ? realTokens(text) : estimateTokens(text, EContentType.Json);
+    const surfaces = [];
+    const add = (surface, strategy, beforeText, afterText) => {
+        const before = count(beforeText);
+        // Net-loss guard: columnar/legend overhead can exceed the raw encoding on
+        // tiny arrays. The engine ships whichever is smaller, so report what the
+        // agent actually pays — never a negative saving.
+        const after = Math.min(count(afterText), before);
+        surfaces.push({ surface, strategy, before, after, savedPct: before > 0 ? Math.round((1 - after / before) * 100) : 0 });
+    };
+    const nodes = [...graph.nodes];
+    const edges = [...graph.edges];
+    add('knowledge graph', 'columnar table', JSON.stringify({ nodes, edges }), JSON.stringify({ nodes: compactArrayToColumnar(nodes) ?? nodes, edges: compactArrayToColumnar(edges) ?? edges }));
+    add('knowledge nodes', 'columnar table', JSON.stringify(nodes), JSON.stringify(compactArrayToColumnar(nodes) ?? nodes));
+    const totalsBefore = surfaces.reduce((s, x) => s + x.before, 0);
+    const totalsAfter = surfaces.reduce((s, x) => s + x.after, 0);
+    return {
+        surfaces,
+        totals: {
+            before: totalsBefore,
+            after: totalsAfter,
+            savedPct: totalsBefore > 0 ? Math.round((1 - totalsAfter / totalsBefore) * 100) : 0,
+        },
+        tokensAreEstimated: !realTokens,
+    };
+}
+/**
+ * Best-effort load of the optional dev tokenizer for exact dashboard counts.
+ * Guarded dynamic import: `gpt-tokenizer` is not a runtime dependency of the
+ * CLI, so this resolves to `undefined` in any install that did not ship it, and
+ * the dashboard transparently falls back to the estimator.
+ */
+async function loadDashboardTokenizer() {
+    try {
+        const mod = (await import('gpt-tokenizer'));
+        if (typeof mod.encode !== 'function')
+            return undefined;
+        const encode = mod.encode;
+        return (text) => (text ? encode(text).length : 0);
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function startDashboardApiServer(opts) {
     const host = opts.host ?? '127.0.0.1';
     const port = opts.port ?? 0;
@@ -324,8 +385,10 @@ async function handle(req, res, ctx) {
         path.startsWith('/api/pipelines') ||
         path.startsWith('/api/architecture') ||
         path.startsWith('/api/graph') ||
+        path.startsWith('/api/knowledge') ||
         path.startsWith('/api/onboarding') ||
         path.startsWith('/api/review') ||
+        path.startsWith('/api/compression') ||
         path.startsWith('/api/scaffolds');
     const inspection = needsInspection
         ? await inspectSharkcraft({ cwd: projectRoot })
@@ -345,6 +408,10 @@ async function handle(req, res, ctx) {
     if (path === '/api/packs') {
         return respond(res, buildEnvelope(projectRoot, buildDashboardPacks(inspection)));
     }
+    if (path === '/api/compression') {
+        const realTokens = await loadDashboardTokenizer();
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCompression(inspection, realTokens)));
+    }
     if (path === '/api/presets') {
         return respond(res, buildEnvelope(projectRoot, buildDashboardPresets(inspection)));
     }
@@ -377,6 +444,32 @@ async function handle(req, res, ctx) {
             return respondError(res, 400, 'bad-request', 'from and to query params required');
         return respond(res, buildEnvelope(projectRoot, buildDashboardGraphPath(inspection, from, to)));
     }
+    // Knowledge explorer. Specific sub-paths (ask / graph / entry) are matched
+    // before the bare list route. The ask route synthesizes a grounded answer
+    // with the local LLM — still a read: it never writes, and is wall-clock
+    // bounded so it cannot hang the server.
+    if (path === '/api/knowledge/ask') {
+        const q = url.searchParams.get('q');
+        if (!q || !q.trim())
+            return respondError(res, 400, 'bad-request', 'q query param required');
+        return respond(res, buildEnvelope(projectRoot, await buildKnowledgeAsk(inspection, q)));
+    }
+    if (path === '/api/knowledge/graph') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeGraph(inspection)));
+    }
+    const knowledgeSimilarMatch = path.match(/^\/api\/knowledge\/similar\/(.+)$/);
+    if (knowledgeSimilarMatch) {
+        const id = decodeURIComponent(knowledgeSimilarMatch[1]);
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeSimilar(inspection, id)));
+    }
+    const knowledgeEntryMatch = path.match(/^\/api\/knowledge\/entry\/(.+)$/);
+    if (knowledgeEntryMatch) {
+        const id = decodeURIComponent(knowledgeEntryMatch[1]);
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeEntry(inspection, id)));
+    }
+    if (path === '/api/knowledge') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeList(inspection)));
+    }
     if (path === '/api/onboarding') {
         return respond(res, buildEnvelope(projectRoot, buildDashboardOnboarding(inspection)));
     }

package/dist/dashboard/knowledge-ask.d.ts

@@ -0,0 +1,4 @@
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IDashboardKnowledgeAskResponse } from '@shrkcrft/dashboard-api';
+export declare function buildKnowledgeAsk(inspection: ISharkcraftInspection, question: string): Promise<IDashboardKnowledgeAskResponse>;
+//# sourceMappingURL=knowledge-ask.d.ts.map

package/dist/dashboard/knowledge-ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-ask.d.ts","sourceRoot":"","sources":["../../src/dashboard/knowledge-ask.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,8BAA8B,EAE/B,MAAM,yBAAyB,CAAC;AAwCjC,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,8BAA8B,CAAC,CA0EzC"}

package/dist/dashboard/knowledge-ask.js

@@ -0,0 +1,112 @@
+/**
+ * Read-only "ask a question over the knowledge base" for the dashboard.
+ *
+ * Deterministic retrieval (searchKnowledge) is the source of truth and ALWAYS
+ * populates `sources`. The local LLM only synthesizes a prose `answer` grounded
+ * in those entries. When no LLM is reachable, or it times out / errors, the
+ * response degrades gracefully to the retrieved entries — the GET handler never
+ * hangs and never writes anything.
+ */
+import { ERROR_CODES } from '@shrkcrft/core';
+import { AiMessageRole, selectAiProvider } from '@shrkcrft/ai';
+import { searchKnowledge } from '@shrkcrft/knowledge';
+/** Hard wall-clock bound so a slow local model can't hang a dashboard GET. */
+const ASK_TIMEOUT_MS = 15_000;
+/** How many entries to retrieve and feed as grounding. */
+const RETRIEVE_LIMIT = 8;
+/** Per-entry grounding budget (chars) — keeps the prompt small for local models. */
+const ENTRY_CHARS = 1100;
+const SYSTEM_PROMPT = [
+    'You are the SharkCraft knowledge assistant for a single repository.',
+    'Answer the question USING ONLY the knowledge entries provided below as context.',
+    'Every entry is delimited and prefixed with its id in [brackets].',
+    'Cite the entries you used by writing their id in [brackets] inline.',
+    'If the answer is not present in the provided entries, say so plainly — do not invent.',
+    'Be concise: a few short paragraphs or bullets. No preamble, no sign-off.',
+].join('\n');
+function roundScore(n) {
+    return Math.round(n * 100) / 100;
+}
+function buildMessages(question, grounding) {
+    return [
+        { role: AiMessageRole.System, content: SYSTEM_PROMPT },
+        {
+            role: AiMessageRole.User,
+            content: [
+                '# Knowledge entries',
+                grounding,
+                '',
+                '# Question',
+                question.trim(),
+                '',
+                'Answer now, citing entry ids in [brackets].',
+            ].join('\n'),
+        },
+    ];
+}
+export async function buildKnowledgeAsk(inspection, question) {
+    const startedAt = Date.now();
+    const trimmed = question.trim();
+    // 1. Deterministic retrieval — always available, the engine's ground truth.
+    const results = searchKnowledge(inspection.knowledgeEntries, {
+        query: trimmed,
+        limit: RETRIEVE_LIMIT,
+    });
+    const sources = results.map((r) => ({
+        id: r.entry.id,
+        title: r.entry.title,
+        type: String(r.entry.type),
+        score: roundScore(r.score),
+    }));
+    const degrade = (note, provider) => ({
+        question: trimmed,
+        llmAvailable: false,
+        ...(provider ? { provider } : {}),
+        answer: null,
+        degraded: true,
+        note,
+        sources,
+        citedEntryIds: [],
+        durationMs: Date.now() - startedAt,
+    });
+    // 2. Provider selection — local-only, may be absent.
+    const selection = selectAiProvider(process.env.AI_PROVIDER);
+    if (!selection.provider) {
+        return degrade('No local LLM is reachable, so this is the deterministic top-matches view. Start an Ollama daemon or set LLAMACPP_MODEL_PATH to enable synthesized answers.');
+    }
+    if (results.length === 0) {
+        return degrade('No knowledge entries matched the question.', selection.provider.id);
+    }
+    // 3. Grounded prompt from the retrieved entries.
+    const grounding = results
+        .map((r) => {
+        const body = (r.entry.summary ?? r.entry.content).slice(0, ENTRY_CHARS);
+        return `### [${r.entry.id}] ${r.entry.title}\n${body}`;
+    })
+        .join('\n\n');
+    // 4. Bounded LLM call; any failure degrades to retrieval-only.
+    const res = await selection.provider.send({
+        messages: buildMessages(trimmed, grounding),
+        maxTokens: 1024,
+        temperature: 0.2,
+        timeoutMs: ASK_TIMEOUT_MS,
+    });
+    if (!res.ok) {
+        const note = res.error.code === ERROR_CODES.TIMEOUT
+            ? 'The local LLM timed out — showing the deterministic top matches instead.'
+            : `The local LLM could not answer (${res.error.message}) — showing the deterministic top matches instead.`;
+        return degrade(note, selection.provider.id);
+    }
+    const answer = res.value.content.trim();
+    const citedEntryIds = sources.map((s) => s.id).filter((id) => answer.includes(id));
+    return {
+        question: trimmed,
+        llmAvailable: true,
+        provider: selection.provider.id,
+        answer,
+        degraded: false,
+        sources,
+        citedEntryIds,
+        durationMs: Date.now() - startedAt,
+    };
+}

package/dist/index.d.ts

@@ -17,6 +17,9 @@ export { packsListCommand, packsGetCommand, packsInspectCommand, packsDoctorComm
 export { pipelinesListCommand, pipelinesGetCommand, pipelinesContextCommand, pipelinesPlanCommand, pipelinesScriptCommand, pipelinesNextCommand, } from './commands/pipelines.command.js';
 export { schemasListCommand, schemasGetCommand, schemasWriteCommand, } from './commands/schemas.command.js';
 export { versionCommand } from './commands/version.command.js';
+export { compressCommand, expandCommand } from './commands/compress.command.js';
+export { alignCommand, unalignCommand } from './commands/cache-align.command.js';
 export { makeHelpCommand } from './commands/help.command.js';
 export { buildRegistry, runCli } from './main.js';
+export { buildWatchPlan, maybeRunInWatchMode, runWatchLoop, } from './output/watch-loop.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -17,5 +17,8 @@ export { packsListCommand, packsGetCommand, packsInspectCommand, packsDoctorComm
 export { pipelinesListCommand, pipelinesGetCommand, pipelinesContextCommand, pipelinesPlanCommand, pipelinesScriptCommand, pipelinesNextCommand, } from "./commands/pipelines.command.js";
 export { schemasListCommand, schemasGetCommand, schemasWriteCommand, } from "./commands/schemas.command.js";
 export { versionCommand } from "./commands/version.command.js";
+export { compressCommand, expandCommand } from "./commands/compress.command.js";
+export { alignCommand, unalignCommand } from "./commands/cache-align.command.js";
 export { makeHelpCommand } from "./commands/help.command.js";
 export { buildRegistry, runCli } from "./main.js";
+export { buildWatchPlan, maybeRunInWatchMode, runWatchLoop, } from "./output/watch-loop.js";

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAoX/B,wBAAgB,aAAa,IAAI,eAAe,CAuX/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAkGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAsX/B,wBAAgB,aAAa,IAAI,eAAe,CA2X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAkGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}

package/dist/main.js

@@ -34,6 +34,8 @@ import { gateCommand } from "./commands/gate.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
 import { statsCommand } from "./commands/stats.command.js";
+import { compressCommand, expandCommand } from "./commands/compress.command.js";
+import { alignCommand, unalignCommand } from "./commands/cache-align.command.js";
 import { reviewCommand } from "./commands/review.command.js";
 import { onboardCommand } from "./commands/onboard.command.js";
 import { contradictionsCommand, generatedCommand, ingestCommand, } from "./commands/ingest.command.js";
@@ -196,6 +198,10 @@ export function buildRegistry() {
     registry.register(migrateCommand);
     registry.register(coverageCommand);
     registry.register(statsCommand);
+    registry.register(compressCommand);
+    registry.register(expandCommand);
+    registry.register(alignCommand);
+    registry.register(unalignCommand);
     registry.register(reviewCommand);
     registry.register(onboardCommand);
     registry.register(ingestCommand);
@@ -816,6 +822,39 @@ function printDidYouMean(attempted) {
     if (footer)
         process.stderr.write(renderErrorFooter(footer));
 }
+/**
+ * Point fd 2 (stderr) at a log file so native-runtime teardown noise written
+ * during process exit lands in a file instead of the user's terminal. Returns
+ * silently on any failure (the worst case is the pre-existing noisy stderr).
+ *
+ * The log path can be overridden with `SHRK_NATIVE_TEARDOWN_LOG`; default is
+ * `<tmpdir>/shrk-native-teardown.log`. We append, with a timestamped header,
+ * so the trace is recoverable for debugging without ever touching the console.
+ */
+async function redirectStderrToTeardownLog() {
+    try {
+        const fs = await import('node:fs');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const logPath = process.env.SHRK_NATIVE_TEARDOWN_LOG?.trim() ||
+            path.join(os.tmpdir(), 'shrk-native-teardown.log');
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        // Close fd 2; the next open() reclaims the lowest free descriptor (2),
+        // so all subsequent stderr — including native C++ writes during
+        // `__cxa_finalize` — flows to the log file.
+        fs.closeSync(2);
+        const fd = fs.openSync(logPath, 'a');
+        if (fd !== 2) {
+            // Couldn't reclaim fd 2 — leave things as they are rather than risk
+            // writing the result to the wrong descriptor.
+            return;
+        }
+        fs.writeSync(2, `\n--- shrk native-runtime teardown @ ${new Date().toISOString()} ---\n`);
+    }
+    catch {
+        // Best-effort containment; never let log redirection break the exit.
+    }
+}
 // Entry point when invoked directly.
 //
 // Bun exposes `import.meta.main`; Node does not. When Node runs the
@@ -830,6 +869,10 @@ if (isMain ||
     entryPath.endsWith('shrk') ||
     entryPath.endsWith('shrk.js') ||
     entryPath.endsWith('shrk.cmd')) {
+    // Marks a real CLI invocation (vs. a command handler imported directly by a
+    // test). Commands that re-exec themselves in an isolated child gate on this
+    // so unit tests calling `run()` in-process never spawn a subprocess.
+    process.env.SHRK_CLI = '1';
     loadDotenv(process.cwd());
     const argv = process.argv.slice(2);
     const cleanShutdown = async (code) => {
@@ -839,10 +882,16 @@ if (isMain ||
         // work completed — the user sees their result then `zsh: abort`.
         // Dynamic imports keep these off the hot path for commands that
         // never touched them.
+        // Track whether any native runtime (ONNX via embeddings, Metal/ggml via
+        // node-llama-cpp) was actually loaded this run. If so, its static
+        // destructors can still abort with a backtrace during `exit()` below —
+        // and there is no JS hook in this Node version to skip libc++ finalizers.
+        // We contain that by redirecting fd 2 to a log file just before exit.
+        let nativeRuntimeLoaded = false;
         try {
             const mod = (await import('@shrkcrft/embeddings'));
             if (typeof mod.disposeSemanticIndexPipeline === 'function') {
-                await mod.disposeSemanticIndexPipeline();
+                nativeRuntimeLoaded = (await mod.disposeSemanticIndexPipeline()) || nativeRuntimeLoaded;
             }
         }
         catch {
@@ -851,7 +900,7 @@ if (isMain ||
         try {
             const mod = (await import('@shrkcrft/ai'));
             if (typeof mod.disposeLlamaCppRuntime === 'function') {
-                await mod.disposeLlamaCppRuntime();
+                nativeRuntimeLoaded = (await mod.disposeLlamaCppRuntime()) || nativeRuntimeLoaded;
             }
         }
         catch {
@@ -869,6 +918,29 @@ if (isMain ||
         catch {
             // ignore flush failures
         }
+        // When running as an isolated worker (e.g. the smart-context child), hand
+        // the real exit code back to the parent via a sentinel file. The native
+        // teardown abort below would otherwise clobber it with SIGABRT (134).
+        const exitCodeFile = process.env.SHRK_WORKER_EXITCODE_FILE;
+        if (exitCodeFile) {
+            try {
+                const fs = await import('node:fs');
+                fs.writeFileSync(exitCodeFile, String(code), 'utf8');
+            }
+            catch {
+                // best-effort; parent falls back to the child's signal/code.
+            }
+        }
+        // Contain native-runtime teardown noise. The ggml/ONNX destructors write a
+        // backtrace + `libc++abi: terminating … mutex lock failed` straight to fd 2
+        // during `exit()`, AFTER our real output is already on screen. That bypasses
+        // any JS stream wrapper, so the only reliable way to keep it off the user's
+        // terminal is to point fd 2 at a log file first: close(2) frees the lowest
+        // fd, and the next open() reclaims it. Gated on `nativeRuntimeLoaded` so
+        // ordinary commands keep their stderr untouched.
+        if (nativeRuntimeLoaded) {
+            await redirectStderrToTeardownLog();
+        }
         // Prefer a low-level exit over `process.exit` on Node. Without
         // this, libc++ static destructors run during `process.exit`, and
         // native bindings still resident in memory abort with libc++abi

package/dist/output/format-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format-output.d.ts","sourceRoot":"","sources":["../../src/output/format-output.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAG3F;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,CAWlE;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB"}
+{"version":3,"file":"format-output.d.ts","sourceRoot":"","sources":["../../src/output/format-output.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAG3F;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAO7C;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,CAWlE;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB"}

package/dist/output/format-output.js

@@ -9,7 +9,12 @@ export function kv(key, value) {
     return `  ${key.padEnd(18)} ${v}`;
 }
 export function asJson(value) {
-    return JSON.stringify(value, null, 2);
+    // Minified by default: `--json` output is for machine / agent consumption, so
+    // we emit the smallest valid JSON (mirrors the MCP wire's default). The shape
+    // is unchanged — only whitespace is removed — so `JSON.parse` consumers are
+    // unaffected. Set SHRK_JSON_PRETTY=1 for human-readable 2-space indentation.
+    const pretty = process.env.SHRK_JSON_PRETTY === '1' || process.env.SHRK_JSON_PRETTY === 'true';
+    return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
 }
 export function table(rows) {
     if (rows.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,37 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.14",
-    "@shrkcrft/config": "^0.1.0-alpha.14",
-    "@shrkcrft/workspace": "^0.1.0-alpha.14",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.14",
-    "@shrkcrft/context": "^0.1.0-alpha.14",
-    "@shrkcrft/rules": "^0.1.0-alpha.14",
-    "@shrkcrft/paths": "^0.1.0-alpha.14",
-    "@shrkcrft/templates": "^0.1.0-alpha.14",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.14",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.14",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.14",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.14",
-    "@shrkcrft/presets": "^0.1.0-alpha.14",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.14",
-    "@shrkcrft/graph": "^0.1.0-alpha.14",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.14",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.14",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.14",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.14",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.14",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.14",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.14",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.14",
-    "@shrkcrft/migrate": "^0.1.0-alpha.14",
-    "@shrkcrft/generator": "^0.1.0-alpha.14",
-    "@shrkcrft/importer": "^0.1.0-alpha.14",
-    "@shrkcrft/inspector": "^0.1.0-alpha.14",
-    "@shrkcrft/ai": "^0.1.0-alpha.14",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.14",
-    "@shrkcrft/shared": "^0.1.0-alpha.14",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.14",
+    "@shrkcrft/core": "^0.1.0-alpha.16",
+    "@shrkcrft/compress": "^0.1.0-alpha.16",
+    "@shrkcrft/config": "^0.1.0-alpha.16",
+    "@shrkcrft/workspace": "^0.1.0-alpha.16",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.16",
+    "@shrkcrft/context": "^0.1.0-alpha.16",
+    "@shrkcrft/rules": "^0.1.0-alpha.16",
+    "@shrkcrft/paths": "^0.1.0-alpha.16",
+    "@shrkcrft/templates": "^0.1.0-alpha.16",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.16",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.16",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.16",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.16",
+    "@shrkcrft/presets": "^0.1.0-alpha.16",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.16",
+    "@shrkcrft/graph": "^0.1.0-alpha.16",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.16",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.16",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.16",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.16",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.16",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.16",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.16",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.16",
+    "@shrkcrft/migrate": "^0.1.0-alpha.16",
+    "@shrkcrft/generator": "^0.1.0-alpha.16",
+    "@shrkcrft/importer": "^0.1.0-alpha.16",
+    "@shrkcrft/inspector": "^0.1.0-alpha.16",
+    "@shrkcrft/ai": "^0.1.0-alpha.16",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.16",
+    "@shrkcrft/shared": "^0.1.0-alpha.16",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.16",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {