@a13xu/lucid 1.16.1 → 1.19.0

package/build/tools/backup.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const BackupFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    reason?: string | undefined;
+}, {
+    path: string;
+    reason?: string | undefined;
+}>;
+export declare function handleBackupFile(stmts: Statements, args: z.infer<typeof BackupFileSchema>): string;
+export declare const RestoreFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    backup_id: z.ZodOptional<z.ZodNumber>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    version?: number | undefined;
+    backup_id?: number | undefined;
+    dry_run?: boolean | undefined;
+}, {
+    path: string;
+    version?: number | undefined;
+    backup_id?: number | undefined;
+    dry_run?: boolean | undefined;
+}>;
+export declare function handleRestoreFile(stmts: Statements, args: z.infer<typeof RestoreFileSchema>): string;
+export declare const CheckTruncateRiskSchema: z.ZodObject<{
+    path: z.ZodString;
+    new_content: z.ZodOptional<z.ZodString>;
+    new_size: z.ZodOptional<z.ZodNumber>;
+    record: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    new_content?: string | undefined;
+    new_size?: number | undefined;
+    record?: boolean | undefined;
+}, {
+    path: string;
+    new_content?: string | undefined;
+    new_size?: number | undefined;
+    record?: boolean | undefined;
+}>;
+export declare function handleCheckTruncateRisk(stmts: Statements, args: z.infer<typeof CheckTruncateRiskSchema>): string;

package/build/tools/backup.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { resolve } from "path";
+import { writeFileSync } from "fs";
+import { decompress } from "../store/content.js";
+import { assessTruncate, backupFile, recordTruncateEvent, TUNABLES, } from "../guardian/truncate-guard.js";
+// ---------------------------------------------------------------------------
+// backup_file
+// ---------------------------------------------------------------------------
+export const BackupFileSchema = z.object({
+    path: z.string().min(1).describe("File to snapshot"),
+    reason: z.string().optional().describe("Why this snapshot was taken (logged)"),
+});
+export function handleBackupFile(stmts, args) {
+    const result = backupFile(stmts, args.path, args.reason ?? "manual");
+    const absPath = resolve(args.path);
+    const total = stmts.countBackups.get(absPath)?.count ?? 0;
+    if (!result.saved)
+        return `⏭️  ${result.reason} (${absPath})`;
+    return [
+        `📸 Backup created: ${absPath}`,
+        `   size: ${result.size}B  hash: ${result.hash?.slice(0, 12)}…`,
+        `   versions retained: ${Math.min(total, TUNABLES.BACKUP_RETENTION)}/${TUNABLES.BACKUP_RETENTION}`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// restore_file
+// ---------------------------------------------------------------------------
+export const RestoreFileSchema = z.object({
+    path: z.string().min(1).describe("File to restore"),
+    version: z.number().int().positive().optional()
+        .describe("1 = latest backup, 2 = previous, etc. Default: 1"),
+    backup_id: z.number().int().positive().optional()
+        .describe("Specific backup row id (overrides version)"),
+    dry_run: z.boolean().optional().describe("Show what would be restored without writing"),
+});
+export function handleRestoreFile(stmts, args) {
+    const absPath = resolve(args.path);
+    if (args.backup_id !== undefined) {
+        const row = stmts.getBackupById.get(args.backup_id);
+        if (!row)
+            return `❌ Backup id=${args.backup_id} not found`;
+        if (row.filepath !== absPath) {
+            return `❌ Backup id=${args.backup_id} belongs to ${row.filepath}, not ${absPath}`;
+        }
+        return doRestore(absPath, row.content, row.created_at, row.original_size, args.dry_run === true);
+    }
+    const all = stmts.getBackupsByPath.all(absPath);
+    if (all.length === 0)
+        return `❌ No backups found for: ${absPath}`;
+    const idx = (args.version ?? 1) - 1;
+    if (idx < 0 || idx >= all.length) {
+        return `❌ Version ${args.version} out of range (have ${all.length} backups for this file)`;
+    }
+    const row = all[idx];
+    return doRestore(absPath, row.content, row.created_at, row.original_size, args.dry_run === true);
+}
+function doRestore(absPath, blob, createdAt, originalSize, dryRun) {
+    const content = decompress(blob);
+    const ts = new Date(createdAt * 1000).toISOString();
+    if (dryRun) {
+        return [
+            `🔍 DRY RUN — would restore ${absPath}`,
+            `   from snapshot at ${ts}`,
+            `   size: ${originalSize}B  (${content.split("\n").length} lines)`,
+        ].join("\n");
+    }
+    writeFileSync(absPath, content, "utf-8");
+    return [
+        `♻️  Restored: ${absPath}`,
+        `   from snapshot at ${ts}`,
+        `   size: ${originalSize}B`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// check_truncate_risk
+// ---------------------------------------------------------------------------
+export const CheckTruncateRiskSchema = z.object({
+    path: z.string().min(1).describe("File path the write would target"),
+    new_content: z.string().optional()
+        .describe("Proposed new content. Omit to query cascade-lock status only."),
+    new_size: z.number().int().nonnegative().optional()
+        .describe("Proposed new size in bytes (alternative to new_content)"),
+    record: z.boolean().optional()
+        .describe("If true, log this as a truncate event (used by hook). Default: false"),
+});
+export function handleCheckTruncateRisk(stmts, args) {
+    const probeContent = args.new_content
+        ?? (args.new_size !== undefined ? " ".repeat(args.new_size) : null);
+    const verdict = assessTruncate(args.path, probeContent, stmts);
+    if (args.record === true && verdict.blocked) {
+        recordTruncateEvent(stmts, args.path, verdict.prevSize, verdict.newSize, true);
+    }
+    if (!verdict.blocked) {
+        return [
+            `✅ Safe write: ${resolve(args.path)}`,
+            `   prev: ${verdict.prevSize}B → new: ${verdict.newSize >= 0 ? verdict.newSize + "B" : "?"} ` +
+                `(keeps ${Math.round(verdict.shrinkRatio * 100)}%)`,
+        ].join("\n");
+    }
+    return [
+        `🛑 BLOCK [${verdict.rule}]: ${resolve(args.path)}`,
+        `   ${verdict.reason}`,
+        verdict.cascade
+            ? `   cascade_count=${verdict.cascadeCount} within ${TUNABLES.CASCADE_WINDOW_SECONDS}s`
+            : `   prev=${verdict.prevSize}B  new=${verdict.newSize}B  ratio=${verdict.shrinkRatio.toFixed(2)}`,
+    ].join("\n");
+}

package/build/tools/delegate-local.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const DelegateLocalSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    system: z.ZodOptional<z.ZodString>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    model?: string | undefined;
+    system?: string | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+}, {
+    prompt: string;
+    model?: string | undefined;
+    system?: string | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+}>;
+export declare function handleDelegateLocal(args: z.infer<typeof DelegateLocalSchema>): Promise<string>;
+export declare const LocalLlmStatusSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare function handleLocalLlmStatus(): Promise<string>;

package/build/tools/delegate-local.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { loadLocalConfig } from "../local-llm/config.js";
+import { generate, ping, LocalLlmError } from "../local-llm/client.js";
+import { describeRuntime } from "../local-llm/runtimes.js";
+// ---------------------------------------------------------------------------
+// delegate_local — direct passthrough to the configured local LLM
+// ---------------------------------------------------------------------------
+export const DelegateLocalSchema = z.object({
+    prompt: z.string().min(1).describe("User prompt for the local model."),
+    system: z.string().optional().describe("Optional system prompt (Python coding role, conventions, …)."),
+    max_tokens: z.number().int().positive().max(8192).optional().describe("Cap on completion tokens. Default 2048."),
+    temperature: z.number().min(0).max(2).optional().describe("Sampling temperature. Default 0.2 (deterministic)."),
+    model: z.string().optional().describe("Override the configured default model."),
+});
+export async function handleDelegateLocal(args) {
+    const cfg = loadLocalConfig();
+    if (!cfg) {
+        return [
+            `❌ Local LLM not configured.`,
+            `   Run in your terminal:  lucid local init`,
+            `   Then restart Claude Code so the new config is picked up.`,
+        ].join("\n");
+    }
+    if (!cfg.enabled) {
+        return `❌ Local LLM is disabled in ${cfg.endpoint} config. Run \`lucid local init\` to re-enable.`;
+    }
+    const effective = args.model ? { ...cfg, model: args.model } : cfg;
+    try {
+        const res = await generate(effective, {
+            prompt: args.prompt,
+            system: args.system,
+            max_tokens: args.max_tokens,
+            temperature: args.temperature,
+        });
+        const tokens = res.prompt_tokens !== undefined && res.completion_tokens !== undefined
+            ? `prompt=${res.prompt_tokens}, completion=${res.completion_tokens}`
+            : "tokens=?";
+        return [
+            `🤖 ${effective.model} via ${describeRuntime(effective.runtime)} (${res.latency_ms}ms, ${tokens})`,
+            ``,
+            res.text.trim(),
+        ].join("\n");
+    }
+    catch (e) {
+        if (e instanceof LocalLlmError) {
+            return `❌ ${e.message}`;
+        }
+        return `❌ Unexpected error: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+// ---------------------------------------------------------------------------
+// local_llm_status — informational
+// ---------------------------------------------------------------------------
+export const LocalLlmStatusSchema = z.object({});
+export async function handleLocalLlmStatus() {
+    const cfg = loadLocalConfig();
+    if (!cfg) {
+        return [
+            `Local LLM: not configured.`,
+            ``,
+            `To set it up, run in your terminal:  lucid local init`,
+            `It walks you through runtime detection (Ollama / LM Studio / llama.cpp /`,
+            `remote endpoint), model selection, and a reachability test.`,
+        ].join("\n");
+    }
+    const reach = await ping(cfg);
+    return [
+        `Local LLM: ${cfg.enabled ? "enabled" : "disabled"}`,
+        `  runtime:   ${describeRuntime(cfg.runtime)}`,
+        `  endpoint:  ${cfg.endpoint}`,
+        `  model:     ${cfg.model}`,
+        `  reachable: ${reach.ok ? `✓ ${reach.latency_ms}ms` : `✗ ${reach.detail ?? "?"}`}`,
+        `  saved at:  ${cfg.configured_at}`,
+    ].join("\n");
+}

package/build/tools/init.js

@@ -5,6 +5,8 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { fileURLToPath } from "url";
 import { indexProject } from "../indexer/project.js";
 import { saveAdminConfig, loadAdminConfig, isAdminConfigured, sendTestAlert, } from "../security/alerts.js";
+import { isConfigured as isLocalLlmConfigured, loadLocalConfig } from "../local-llm/config.js";
+import { describeRuntime } from "../local-llm/runtimes.js";
 export const InitProjectSchema = z.object({
     directory: z.string().optional(),
     // ── Admin alert configuration (asked once at project init) ──────────────
@@ -31,6 +33,9 @@ export const InitProjectSchema = z.object({
 });
 const LUCID_MARKER = "Lucid: call sync_file";
 const LUCID_UPDATE_MARKER = "lucid-update-check";
+const LUCID_GUARD_MARKER = "lucid-guard-pre-edit";
+const LUCID_SESSION_TICK_MARKER = "lucid-session-tick";
+const LUCID_SESSION_COMPACT_MARKER = "lucid-session-compact";
 const LUCID_HOOK = {
     matcher: "Write|Edit|NotebookEdit",
     hooks: [
@@ -40,6 +45,38 @@ const LUCID_HOOK = {
         },
     ],
 };
+// PreToolUse hook: snapshot file + block destructive truncates BEFORE write.
+// Reads Claude Code's PreToolUse JSON from stdin; exit 2 hard-blocks the tool.
+// Marker token included so we can idempotently detect prior installs.
+const LUCID_PRE_EDIT_HOOK = {
+    matcher: "Write|Edit|MultiEdit|NotebookEdit",
+    hooks: [
+        {
+            type: "command",
+            command: `lucid guard pre-edit 2>&1 # ${LUCID_GUARD_MARKER}`,
+        },
+    ],
+};
+// UserPromptSubmit hook: track session length → emit /compact and /clear hints.
+// stdout from this hook is injected into Claude's context for the upcoming turn.
+const LUCID_SESSION_TICK_HOOK = {
+    hooks: [
+        {
+            type: "command",
+            command: `lucid session tick # ${LUCID_SESSION_TICK_MARKER}`,
+        },
+    ],
+};
+// PreCompact hook: reset per-session counters when /compact runs so the next
+// hint cycle starts from a clean baseline.
+const LUCID_PRE_COMPACT_HOOK = {
+    hooks: [
+        {
+            type: "command",
+            command: `lucid session compact # ${LUCID_SESSION_COMPACT_MARKER}`,
+        },
+    ],
+};
 // SessionStart hook: checks npm registry and notifies if update is available.
 // Uses only Node.js built-in https module — no external dependencies required.
 const LUCID_UPDATE_HOOK = {
@@ -84,6 +121,36 @@ function installHooks(dir) {
         hooks["PostToolUse"] = [...postToolUse, LUCID_HOOK];
         changed = true;
     }
+    // ── PreToolUse: backup + truncate guard ──────────────────────────────────
+    const preToolUse = hooks["PreToolUse"] ?? [];
+    const guardAlreadyInstalled = preToolUse.some((h) => {
+        const cmd = h.command ?? h.hooks?.[0]?.command ?? "";
+        return cmd.includes(LUCID_GUARD_MARKER);
+    });
+    if (!guardAlreadyInstalled) {
+        hooks["PreToolUse"] = [...preToolUse, LUCID_PRE_EDIT_HOOK];
+        changed = true;
+    }
+    // ── UserPromptSubmit: session-cost hints (/compact, /clear) ──────────────
+    const userPromptSubmit = hooks["UserPromptSubmit"] ?? [];
+    const sessionTickInstalled = userPromptSubmit.some((h) => {
+        const cmd = h.command ?? h.hooks?.[0]?.command ?? "";
+        return cmd.includes(LUCID_SESSION_TICK_MARKER);
+    });
+    if (!sessionTickInstalled) {
+        hooks["UserPromptSubmit"] = [...userPromptSubmit, LUCID_SESSION_TICK_HOOK];
+        changed = true;
+    }
+    // ── PreCompact: reset counters when /compact fires ────────────────────────
+    const preCompact = hooks["PreCompact"] ?? [];
+    const preCompactInstalled = preCompact.some((h) => {
+        const cmd = h.command ?? h.hooks?.[0]?.command ?? "";
+        return cmd.includes(LUCID_SESSION_COMPACT_MARKER);
+    });
+    if (!preCompactInstalled) {
+        hooks["PreCompact"] = [...preCompact, LUCID_PRE_COMPACT_HOOK];
+        changed = true;
+    }
     // ── SessionStart: version check ───────────────────────────────────────────
     const sessionStart = hooks["SessionStart"] ?? [];
     const updateAlreadyInstalled = sessionStart.some((h) => {
@@ -116,6 +183,42 @@ sync_file(path="<path of the file you just wrote/edited>")
 
 This keeps the Lucid knowledge graph up to date with the latest code.
 If multiple files changed (refactor, git pull), call sync_project() instead.
+
+## 🛡️  Lucid — Backup & Truncate Guard (automatic)
+
+A PreToolUse hook (\`lucid guard pre-edit\`) runs before every Write/Edit/MultiEdit:
+1. **Snapshot** the file into the versioned backup store (last 10 versions kept).
+2. **Block** destructive truncates: empty/whitespace overwrite, >70% shrink, or
+   ≥2 truncate attempts within 60s (cascade lock — common in autonomous loops).
+
+Tools available when you need them:
+- \`backup_file(path)\` — manual snapshot before risky refactors.
+- \`restore_file(path, version=1, dry_run=true)\` — preview/restore from backup.
+- \`check_truncate_risk(path, new_content)\` — assess a planned write.
+
+If a guard blocks legitimately (e.g. you really do want to empty a file), set
+\`LUCID_TRUNCATE_OVERRIDE=1\` for that one invocation, or run
+\`lucid guard clear\` to release a cascade lock. Do **not** disable the hook.
+
+## 💸  Lucid — Session-cost hints (/compact, /clear)
+
+Two hooks track session length to keep per-turn cost predictable:
+
+- **UserPromptSubmit** runs \`lucid session tick\` and may inject one or more of:
+  - \`/compact\` hint at **15 prompts**, re-emitted every **10** afterwards.
+  - \`/clear\` hint at **30 prompts** (one-shot — preferable when switching tasks).
+  - Cache-cold hint when idle gap exceeds **5 min** (prompt cache TTL).
+- **PreCompact** runs \`lucid session compact\` to reset the per-session counter
+  so the next hint cycle starts from a clean baseline.
+
+When you see a hint, surface it to the user and act on it — the cost model is
+per-turn linear with transcript length even when the cache is warm. Tools:
+- \`session_status\` — inspect prompt counts and pending hints.
+- \`lucid session reset\` — manually reset a single session counter (CLI).
+
+Tunable via env: \`LUCID_COMPACT_HINT_AT\`, \`LUCID_COMPACT_HINT_EVERY\`,
+\`LUCID_CLEAR_HINT_AT\`, \`LUCID_CACHE_STALE_SECONDS\`,
+\`LUCID_SESSION_HINTS_DISABLED=1\` to silence completely.
 <!-- /LUCID_SYNC -->
 `;
 function injectClaudeMdInstruction(dir) {
@@ -150,8 +253,11 @@ export async function handleInitProject(stmts, input) {
     const hookResult = installHooks(dir);
     if (hookResult.installed) {
         lines.push(`🔗 Claude Code hooks installed (.claude/settings.json)`);
-        lines.push(`   PostToolUse: reminder to call sync_file() after every Write/Edit`);
-        lines.push(`   SessionStart: auto-check for Lucid updates on session start`);
+        lines.push(`   PreToolUse:       backup + truncate guard before every Write/Edit/MultiEdit`);
+        lines.push(`   PostToolUse:      reminder to call sync_file() after every Write/Edit`);
+        lines.push(`   UserPromptSubmit: session-cost hints (/compact at 15, /clear at 30, cache-cold)`);
+        lines.push(`   PreCompact:       reset session counters when /compact fires`);
+        lines.push(`   SessionStart:     auto-check for Lucid updates on session start`);
     }
     else {
         lines.push(`🔗 Hooks: ${hookResult.reason}`);
@@ -256,6 +362,22 @@ export async function handleInitProject(stmts, input) {
             lines.push(`   Webhook HMAC signing: set LUCID_WEBHOOK_SECRET env var.`);
         }
     }
+    // ── Local LLM nudge ───────────────────────────────────────────────────────
+    lines.push(``);
+    lines.push(`🤖 Local LLM (delegate_local)`);
+    if (isLocalLlmConfigured()) {
+        const cfg = loadLocalConfig();
+        lines.push(`   Configured: ${cfg.model} via ${describeRuntime(cfg.runtime)} @ ${cfg.endpoint}`);
+    }
+    else {
+        lines.push(`   Not configured. To enable delegation of small specialized tasks to a local`);
+        lines.push(`   coder LLM (Ollama / LM Studio / llama.cpp / remote endpoint), run in your terminal:`);
+        lines.push(``);
+        lines.push(`     lucid local init`);
+        lines.push(``);
+        lines.push(`   It walks you through runtime detection, model selection, and a reachability test.`);
+        lines.push(`   Config is saved globally to ~/.lucid/local.json (one setup → all projects).`);
+    }
     lines.push(``);
     lines.push(`From now on, call sync_file(path) after every file you write or edit.`);
     lines.push(`Use recall() to query accumulated project knowledge.`);

package/build/tools/plan.js

@@ -16,10 +16,10 @@ export const PlanListSchema = z.object({
     status: z.enum(["active", "completed", "abandoned", "all"]).optional().default("active"),
 });
 export const PlanGetSchema = z.object({
-    plan_id: z.number().int().positive(),
+    plan_id: z.coerce.number().int().positive(),
 });
 export const PlanUpdateTaskSchema = z.object({
-    task_id: z.number().int().positive(),
+    task_id: z.coerce.number().int().positive(),
     status: z.enum(["pending", "in_progress", "done", "blocked"]),
     note: z.string().optional(),
 });

package/build/tools/session.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const SessionStatusSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    session_id?: string | undefined;
+    limit?: number | undefined;
+}, {
+    session_id?: string | undefined;
+    limit?: number | undefined;
+}>;
+export declare function handleSessionStatus(stmts: Statements, args: z.infer<typeof SessionStatusSchema>): string;

package/build/tools/session.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { SESSION_TUNABLES } from "../guardian/session-tracker.js";
+// ---------------------------------------------------------------------------
+// session_status — show current session-cost state and hint thresholds
+// ---------------------------------------------------------------------------
+export const SessionStatusSchema = z.object({
+    session_id: z.string().optional()
+        .describe("Specific session id. Defaults to the most recently active session."),
+    limit: z.number().int().positive().max(50).optional()
+        .describe("How many recent sessions to list when session_id is omitted (default 5)."),
+});
+export function handleSessionStatus(stmts, args) {
+    const limit = args.limit ?? 5;
+    if (args.session_id) {
+        const row = stmts.getCliSession.get(args.session_id);
+        if (!row)
+            return `No session found with id=${args.session_id}`;
+        return formatSession(row, true);
+    }
+    const recent = stmts.recentCliSessions.all(limit);
+    if (recent.length === 0) {
+        return [
+            `No Claude Code sessions tracked yet.`,
+            ``,
+            `Hints fire at:`,
+            `  /compact at ${SESSION_TUNABLES.COMPACT_HINT_AT} prompts (re-emitted every ${SESSION_TUNABLES.COMPACT_HINT_EVERY})`,
+            `  /clear   at ${SESSION_TUNABLES.CLEAR_HINT_AT} prompts (one-shot)`,
+            `  cache-cold after ${SESSION_TUNABLES.CACHE_STALE_SECONDS}s idle`,
+        ].join("\n");
+    }
+    const lines = [
+        `📊 Recent Claude Code sessions (top ${recent.length}):`,
+        ``,
+    ];
+    for (const r of recent)
+        lines.push(formatSession(r, false));
+    lines.push(``);
+    lines.push(`Thresholds: /compact@${SESSION_TUNABLES.COMPACT_HINT_AT} (+${SESSION_TUNABLES.COMPACT_HINT_EVERY}), ` +
+        `/clear@${SESSION_TUNABLES.CLEAR_HINT_AT}, cache-cold>${SESSION_TUNABLES.CACHE_STALE_SECONDS}s`);
+    return lines.join("\n");
+}
+function formatSession(r, full) {
+    const idle = Math.floor(Date.now() / 1000) - r.last_activity_at;
+    const idleStr = idle < 60 ? `${idle}s` : idle < 3600 ? `${Math.round(idle / 60)}m` : `${Math.round(idle / 3600)}h`;
+    const status = r.prompt_count >= SESSION_TUNABLES.CLEAR_HINT_AT ? "🔴" :
+        r.prompt_count >= SESSION_TUNABLES.COMPACT_HINT_AT ? "🟠" : "🟢";
+    const head = `${status} ${r.session_id.slice(0, 8)}…  ${r.prompt_count} prompts  idle=${idleStr}  compacts=${r.compact_count}`;
+    if (!full)
+        return "  " + head;
+    return [
+        head,
+        `   started:    ${new Date(r.started_at * 1000).toISOString()}`,
+        `   last activ: ${new Date(r.last_activity_at * 1000).toISOString()}`,
+        r.last_compact_event_at
+            ? `   last compact: ${new Date(r.last_compact_event_at * 1000).toISOString()}`
+            : `   last compact: —`,
+        r.cwd ? `   cwd: ${r.cwd}` : ``,
+    ].filter(Boolean).join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a13xu/lucid",
-  "version": "1.16.1",
+  "version": "1.19.0",
   "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "compress-prompts": "node scripts/compress-prompts.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -53,6 +54,7 @@
     "better-sqlite3": "^12.0.0",
     "chokidar": "^4.0.3",
     "express": "^5.2.1",
+    "sharp": "^0.34.5",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/skills/lucid-audit/SKILL.md

@@ -2,6 +2,17 @@
 name: lucid-audit
 description: MANDATORY before marking any task done — runs Logic Guardian + Code Quality checks. HARD-GATE blocks completion without validation.
 argument-hint: "[file path or 'all changed files']"
+allowed-tools:
+  - mcp__lucid__suggest_model
+  - mcp__lucid__validate_file
+  - mcp__lucid__check_drift
+  - mcp__lucid__get_checklist
+  - mcp__lucid__check_code_quality
+  - mcp__lucid__coding_rules
+  - mcp__lucid__get_recent
+  - mcp__lucid__sync_file
+  - Read
+  - Glob
 ---
 
 <HARD-GATE>

package/skills/lucid-context/SKILL.md

@@ -2,6 +2,15 @@
 name: lucid-context
 description: Use BEFORE starting any coding task — retrieves relevant context via smart_context (code + knowledge graph). HARD-GATE: do not read files manually before calling smart_context.
 argument-hint: "[what you are working on]"
+allowed-tools:
+  - mcp__lucid__suggest_model
+  - mcp__lucid__smart_context
+  - mcp__lucid__get_context
+  - mcp__lucid__get_recent
+  - mcp__lucid__recall
+  - mcp__lucid__grep_code
+  - mcp__lucid__reward
+  - mcp__lucid__penalize
 ---
 
 <HARD-GATE>

package/skills/lucid-plan/SKILL.md

@@ -2,6 +2,15 @@
 name: lucid-plan
 description: MANDATORY before writing code for any non-trivial feature — creates a persisted plan with tasks. HARD-GATE: no coding without a plan.
 argument-hint: "[feature or task description]"
+allowed-tools:
+  - mcp__lucid__suggest_model
+  - mcp__lucid__plan_create
+  - mcp__lucid__plan_list
+  - mcp__lucid__plan_get
+  - mcp__lucid__plan_update_task
+  - mcp__lucid__smart_context
+  - mcp__lucid__recall
+  - mcp__lucid__remember
 ---
 
 <HARD-GATE>

package/skills/lucid-security/SKILL.md

@@ -2,6 +2,15 @@
 name: lucid-security
 description: Run before merging any code that handles user input, auth, or external data — security scan + drift check for injection, XSS, and credential exposure.
 argument-hint: "[file path or directory]"
+allowed-tools:
+  - mcp__lucid__suggest_model
+  - mcp__lucid__security_scan
+  - mcp__lucid__check_drift
+  - mcp__lucid__validate_file
+  - mcp__lucid__get_recent
+  - mcp__lucid__grep_code
+  - Read
+  - Glob
 ---
 
 <HARD-GATE>

package/skills/lucid-start/SKILL.md

@@ -2,6 +2,15 @@
 name: lucid-start
 description: MANDATORY at every session start and before any coding task — loads project context via Lucid before Claude reads any file or writes any code
 argument-hint: "[optional: what you are about to work on]"
+allowed-tools:
+  - mcp__lucid__suggest_model
+  - mcp__lucid__init_project
+  - mcp__lucid__sync_file
+  - mcp__lucid__sync_project
+  - mcp__lucid__memory_stats
+  - mcp__lucid__recall
+  - mcp__lucid__get_recent
+  - mcp__lucid__smart_context
 ---
 
 <HARD-GATE>

package/skills/lucid-webdev/SKILL.md

@@ -2,6 +2,20 @@
 name: lucid-webdev
 description: Use for web development tasks — generates components, pages, audits, API clients, and performance hints via Lucid's 10 web dev tools.
 argument-hint: "[what you are building: component/page/api/audit]"
+allowed-tools:
+  - mcp__lucid__suggest_model
+  - mcp__lucid__generate_component
+  - mcp__lucid__scaffold_page
+  - mcp__lucid__seo_meta
+  - mcp__lucid__accessibility_audit
+  - mcp__lucid__api_client
+  - mcp__lucid__test_generator
+  - mcp__lucid__responsive_layout
+  - mcp__lucid__security_scan
+  - mcp__lucid__design_tokens
+  - mcp__lucid__perf_hints
+  - Write
+  - Edit
 ---
 
 <HARD-GATE>