@oratis/lisa 0.3.0 → 0.4.0

package/dist/integrations/registry.js

@@ -0,0 +1,38 @@
+/**
+ * Integration registry — mirrors src/channels/registry.ts.
+ *
+ * Each agent adapter calls registerIntegration() at module-load time; the
+ * hub looks them up by name. Keeps adapters decoupled and lets community
+ * adapters slot in by importing one more module.
+ */
+const FACTORIES = new Map();
+export function registerIntegration(name, factory) {
+    FACTORIES.set(name, factory);
+}
+export async function makeIntegration(name, cfg) {
+    const factory = FACTORIES.get(name);
+    if (!factory) {
+        throw new Error(`unknown integration "${name}". Known: ${Array.from(FACTORIES.keys()).join(", ") || "(none registered)"}`);
+    }
+    return await factory(cfg);
+}
+export function listAvailableIntegrations() {
+    return Array.from(FACTORIES.keys()).sort();
+}
+/** Test hook — clear the registry between unit tests. */
+export function _resetIntegrationsForTest() {
+    FACTORIES.clear();
+    builtinsRegistered = false;
+}
+// Lazy registration of built-in adapters. Each module calls
+// registerIntegration() at import time.
+let builtinsRegistered = false;
+export async function registerBuiltinIntegrations() {
+    if (builtinsRegistered)
+        return;
+    builtinsRegistered = true;
+    await import("./claude-code/observer.js");
+    await import("./codex/observer.js");
+    // Additional adapters register here as they land (opencode, aider, …).
+}
+//# sourceMappingURL=registry.js.map

package/dist/integrations/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/integrations/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE1D,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,OAA6B;IAE7B,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,GAA2B;IAE3B,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,aAC1B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAC7C,EAAE,CACH,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,yBAAyB;IACvC,SAAS,CAAC,KAAK,EAAE,CAAC;IAClB,kBAAkB,GAAG,KAAK,CAAC;AAC7B,CAAC;AAED,4DAA4D;AAC5D,wCAAwC;AACxC,IAAI,kBAAkB,GAAG,KAAK,CAAC;AAC/B,MAAM,CAAC,KAAK,UAAU,2BAA2B;IAC/C,IAAI,kBAAkB;QAAE,OAAO;IAC/B,kBAAkB,GAAG,IAAI,CAAC;IAC1B,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;IAC1C,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACpC,uEAAuE;AACzE,CAAC"}

package/dist/integrations/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Cross-agent orchestration — shared types.
+ *
+ * LISA observes many CLI agents (Claude Code, Codex, OpenCode, Aider, …),
+ * each with its own on-disk session format. These types are the normalized,
+ * agent-agnostic shape every adapter produces, so the UI, the hub, and the
+ * advisor never care which agent a session came from.
+ *
+ * See docs/ORCHESTRATOR_PLAN.md for the full design (L1 OBSERVE, L2 UNDERSTAND).
+ */
+/** Which agent produced a session. Open-ended string so community adapters
+ *  can add kinds without touching this file. */
+export type AgentKind = "claude-code" | "codex" | "opencode" | "aider" | "gemini" | "cursor" | "github-pr" | "mcp" | "lisa" | (string & {});
+/** Normalized session state across all agents. Superset of any single
+ *  agent's states; adapters map their native states onto these. */
+export type AgentSessionState = "working" | "waiting" | "error" | "idle" | "done" | "unknown";
+/**
+ * L2 — structural activity for a session. Populated by tier ≥ "activity"
+ * adapters. PRIVACY: every field here is structural metadata (tool NAMES,
+ * file PATHS, command argv[0], error strings, counts) — never a prompt, a
+ * model reply, or full command arguments. See parser privacy tests.
+ */
+export interface SessionActivity {
+    /** Number of assistant/user turns observed (rough progress indicator). */
+    turnCount: number;
+    /** Most recent tool names, newest last, e.g. ["Read","Edit","Bash"]. */
+    lastTools: string[];
+    /** File paths touched by Edit/Write-style tools (deduped, capped). */
+    filesTouched: string[];
+    /** argv[0] of the most recent shell command, e.g. "npm" — not the full command. */
+    lastCommandName?: string;
+    /** Short error summary if the last meaningful activity errored. */
+    lastError?: string;
+    /** git branch recorded by the agent, if any. */
+    gitBranch?: string;
+    /** Token usage so far (for cost-spike detection). */
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    /** Tool name awaiting a permission decision, if the session is blocked on one. */
+    pendingPermission?: string;
+}
+/**
+ * One normalized session. The merge target for every adapter's output.
+ */
+export interface AgentSession {
+    agent: AgentKind;
+    /** Stable id within this agent (uuid, rollout filename, PR number, …). */
+    sessionId: string;
+    /** Human label — usually the basename of cwd. */
+    project: string;
+    cwd?: string;
+    state: AgentSessionState;
+    /** Short machine-ish reason for the state ("end_turn", "permission", …). */
+    stateReason: string;
+    /** Last activity time, epoch ms. */
+    lastMtime: number;
+    /** L2 activity, present when the adapter runs at tier ≥ "activity". */
+    activity?: SessionActivity;
+}
+/** Visibility tier — how deeply LISA may inspect a session. See plan §3. */
+export type VisibilityTier = "off" | "metadata" | "activity" | "intent";
+/** Per-integration config from ~/.lisa/agents.json. */
+export interface AgentIntegrationConfig {
+    enabled?: boolean;
+    /** Home dir / data dir override (e.g. CODEX_HOME, OPENCODE_DATA_DIR). */
+    home?: string;
+    /** Extra roots to watch (e.g. Aider's per-project logs). */
+    watchRoots?: string[];
+    /** Per-integration visibility override; falls back to the global tier. */
+    visibility?: VisibilityTier;
+    /** Arbitrary adapter-specific options. */
+    [k: string]: unknown;
+}
+/**
+ * An adapter that watches one agent kind and emits normalized sessions.
+ * Stateful: holds file watchers / timers between start() and stop().
+ */
+export interface AgentObserver {
+    readonly agent: AgentKind;
+    /** Begin watching. `emit` is called on every new/changed session. */
+    start(emit: (session: AgentSession) => void): Promise<void>;
+    /** Current snapshot of active sessions. */
+    list(): AgentSession[];
+    /** Tear down watchers/timers. Idempotent. */
+    stop(): Promise<void>;
+}
+export type AgentObserverFactory = (cfg: AgentIntegrationConfig) => AgentObserver | Promise<AgentObserver>;
+//# sourceMappingURL=types.d.ts.map

package/dist/integrations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/integrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;gDACgD;AAChD,MAAM,MAAM,SAAS,GACjB,aAAa,GACb,OAAO,GACP,UAAU,GACV,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,KAAK,GACL,MAAM,GACN,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;mEACmE;AACnE,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,iBAAiB,CAAC;IACzB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAExE,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,0CAA0C;IAC1C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,qEAAqE;IACrE,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,2CAA2C;IAC3C,IAAI,IAAI,YAAY,EAAE,CAAC;IACvB,6CAA6C;IAC7C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,GAAG,EAAE,sBAAsB,KACxB,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC"}

package/dist/integrations/types.js

@@ -0,0 +1,12 @@
+/**
+ * Cross-agent orchestration — shared types.
+ *
+ * LISA observes many CLI agents (Claude Code, Codex, OpenCode, Aider, …),
+ * each with its own on-disk session format. These types are the normalized,
+ * agent-agnostic shape every adapter produces, so the UI, the hub, and the
+ * advisor never care which agent a session came from.
+ *
+ * See docs/ORCHESTRATOR_PLAN.md for the full design (L1 OBSERVE, L2 UNDERSTAND).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/integrations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/integrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/memory/vector.d.ts

@@ -12,7 +12,11 @@ interface Index {
     docs: Document[];
     idf: Map<string, number>;
 }
-export declare function buildIndex(): Promise<Index>;
+/** Drop the cached index (test hook / explicit invalidation). */
+export declare function clearIndexCache(): void;
+export declare function buildIndex(opts?: {
+    cache?: boolean;
+}): Promise<Index>;
 export interface SearchHit {
     sessionId: string;
     startedAt: string;

package/dist/memory/vector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../src/memory/vector.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAIlC,UAAU,QAAQ;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,UAAU,KAAK;IACb,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B;AASD,wBAAsB,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,CAkCjD;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,SAAS,EAAE,CAuBtE;AA2BD,eAAO,MAAM,qBAAqB,EAAE,OAAO,IAAI,GAAG,OAAO,EAAE,GAAG,SAAqB,CAAC"}
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../src/memory/vector.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAKlC,UAAU,QAAQ;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,UAAU,KAAK;IACb,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B;AA4CD,iEAAiE;AACjE,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,wBAAsB,UAAU,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAW/E;AAsCD,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,SAAS,EAAE,CAuBtE;AA2BD,eAAO,MAAM,qBAAqB,EAAE,OAAO,IAAI,GAAG,OAAO,EAAE,GAAG,SAAqB,CAAC"}

package/dist/memory/vector.js

@@ -1,4 +1,7 @@
+import path from "node:path";
+import fs from "node:fs/promises";
 import { listSessionsOnDisk, loadSessionMessages } from "../sessions/list.js";
+import { SESSIONS_DIR } from "../paths.js";
 import { extractTextFromContent } from "../agent.js";
 const STOPWORDS = new Set([
     "the", "a", "an", "of", "to", "in", "and", "or", "for", "is", "it",
@@ -6,7 +9,61 @@ const STOPWORDS = new Set([
     "by", "from", "but", "not", "i", "you", "we", "they", "he", "she",
     "lisa", "tool", "use", "user", "assistant",
 ]);
-export async function buildIndex() {
+// ── index cache ───────────────────────────────────────────────────────────
+// buildIndex re-reads + re-tokenizes EVERY past session, which is O(total
+// transcript bytes). memory_search was calling it fresh on every invocation,
+// so a chat that searches its memory N times in one session paid that cost N
+// times even when nothing changed. We cache the built index keyed by a cheap
+// fingerprint of the sessions directory (each .jsonl's mtime + size). The
+// fingerprint changes the instant any session is appended to or a new one
+// appears, so the cache is correct, not just fast.
+let cachedIndex = null;
+let cachedFingerprint = "";
+async function sessionsFingerprint() {
+    let files;
+    try {
+        files = await fs.readdir(SESSIONS_DIR);
+    }
+    catch {
+        // Missing dir and empty dir must fingerprint identically: buildIndex →
+        // listSessionsOnDisk → ensureDir CREATES the dir as a side effect, so a
+        // distinct "no-dir" sentinel would spuriously miss the cache on the very
+        // next call. Both collapse to the empty fingerprint.
+        return "";
+    }
+    const parts = [];
+    for (const f of files.sort()) {
+        if (!f.endsWith(".jsonl"))
+            continue;
+        try {
+            const st = await fs.stat(path.join(SESSIONS_DIR, f));
+            parts.push(`${f}:${st.mtimeMs}:${st.size}`);
+        }
+        catch {
+            // file vanished between readdir and stat — ignore
+        }
+    }
+    return parts.join("|");
+}
+/** Drop the cached index (test hook / explicit invalidation). */
+export function clearIndexCache() {
+    cachedIndex = null;
+    cachedFingerprint = "";
+}
+export async function buildIndex(opts = {}) {
+    const useCache = opts.cache !== false;
+    if (useCache) {
+        const fp = await sessionsFingerprint();
+        if (cachedIndex && fp === cachedFingerprint)
+            return cachedIndex;
+        const built = await buildIndexUncached();
+        cachedIndex = built;
+        cachedFingerprint = fp;
+        return built;
+    }
+    return buildIndexUncached();
+}
+async function buildIndexUncached() {
     const sessions = await listSessionsOnDisk();
     const docs = [];
     const docFreq = new Map();

package/dist/memory/vector.js.map

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

package/dist/soul/lock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-process advisory file lock for soul writes.
+ *
+ * The in-process commit queue (git.ts enqueueCommit) serializes writes within
+ * ONE process, but LISA runs as several processes against the same
+ * ~/.lisa/soul/: the web server, the CLI/REPL, and — crucially — the
+ * heartbeat/idle runners launched by launchd/cron on their own clock. Two of
+ * those writing concurrently can:
+ *   - lose a desire-progress append (read-modify-write race), or
+ *   - collide on .git/index.lock (one commit fails).
+ *
+ * withFileLock implements a portable advisory mutex via exclusive file
+ * creation (`open(..., "wx")` succeeds only if the file doesn't exist). It
+ * self-heals from a crashed holder via a staleness timeout + a best-effort
+ * liveness check on the recorded pid.
+ */
+export interface FileLockOpts {
+    /** Treat a held lock as abandoned after this many ms (crashed holder). */
+    staleMs?: number;
+    /** Give up acquiring after this many ms. */
+    timeoutMs?: number;
+    /** Poll interval while waiting for the lock. */
+    pollMs?: number;
+}
+/**
+ * Run `fn` while holding an exclusive lock at `lockPath`. Releases the lock
+ * (deletes the file) when `fn` settles, success or failure.
+ */
+export declare function withFileLock<T>(lockPath: string, fn: () => Promise<T>, opts?: FileLockOpts): Promise<T>;
+/** The canonical soul write-lock path. */
+export declare const SOUL_LOCK_PATH: string;
+/**
+ * Run `fn` while holding the soul write-lock. Use this around any
+ * read-modify-write of soul state (e.g. desire-progress appends) so a
+ * concurrent heartbeat/idle/chat process can't interleave and lose data.
+ */
+export declare function withSoulLock<T>(fn: () => Promise<T>, opts?: FileLockOpts): Promise<T>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/soul/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/soul/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoCD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAED,0CAA0C;AAC1C,eAAO,MAAM,cAAc,QAAqC,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAErF"}

package/dist/soul/lock.js

@@ -0,0 +1,103 @@
+/**
+ * Cross-process advisory file lock for soul writes.
+ *
+ * The in-process commit queue (git.ts enqueueCommit) serializes writes within
+ * ONE process, but LISA runs as several processes against the same
+ * ~/.lisa/soul/: the web server, the CLI/REPL, and — crucially — the
+ * heartbeat/idle runners launched by launchd/cron on their own clock. Two of
+ * those writing concurrently can:
+ *   - lose a desire-progress append (read-modify-write race), or
+ *   - collide on .git/index.lock (one commit fails).
+ *
+ * withFileLock implements a portable advisory mutex via exclusive file
+ * creation (`open(..., "wx")` succeeds only if the file doesn't exist). It
+ * self-heals from a crashed holder via a staleness timeout + a best-effort
+ * liveness check on the recorded pid.
+ */
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { ensureDir } from "../fs-utils.js";
+import { SOUL_DIR } from "./paths.js";
+const DEFAULTS = { staleMs: 30_000, timeoutMs: 10_000, pollMs: 50 };
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Is the process holding this lock gone or the lock too old to trust? */
+async function isStale(lockPath, staleMs) {
+    let body;
+    try {
+        body = JSON.parse(await fsp.readFile(lockPath, "utf8"));
+    }
+    catch {
+        // Unreadable / malformed lock file → treat as stale so we can recover.
+        return true;
+    }
+    if (typeof body.ts !== "number" || Date.now() - body.ts > staleMs)
+        return true;
+    // Best-effort liveness: signal 0 throws ESRCH if the pid is dead. Only
+    // meaningful on the same host; on a different host kill() may report the
+    // wrong answer, so we still rely primarily on the ts timeout above.
+    if (typeof body.pid === "number" && body.pid > 0) {
+        try {
+            process.kill(body.pid, 0);
+        }
+        catch (e) {
+            if (e.code === "ESRCH")
+                return true; // holder dead
+        }
+    }
+    return false;
+}
+/**
+ * Run `fn` while holding an exclusive lock at `lockPath`. Releases the lock
+ * (deletes the file) when `fn` settles, success or failure.
+ */
+export async function withFileLock(lockPath, fn, opts = {}) {
+    const { staleMs, timeoutMs, pollMs } = { ...DEFAULTS, ...opts };
+    await ensureDir(path.dirname(lockPath));
+    const deadline = Date.now() + timeoutMs;
+    // ── acquire ──
+    for (;;) {
+        try {
+            const fh = await fsp.open(lockPath, "wx");
+            try {
+                await fh.writeFile(JSON.stringify({ pid: process.pid, ts: Date.now() }));
+            }
+            finally {
+                await fh.close();
+            }
+            break; // acquired
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            // Held by someone. Steal if stale, else wait.
+            if (await isStale(lockPath, staleMs)) {
+                await fsp.rm(lockPath, { force: true }).catch(() => { });
+                continue; // retry immediately
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`timed out acquiring lock ${lockPath} after ${timeoutMs}ms`);
+            }
+            await delay(pollMs);
+        }
+    }
+    // ── critical section ──
+    try {
+        return await fn();
+    }
+    finally {
+        await fsp.rm(lockPath, { force: true }).catch(() => { });
+    }
+}
+/** The canonical soul write-lock path. */
+export const SOUL_LOCK_PATH = path.join(SOUL_DIR, ".write.lock");
+/**
+ * Run `fn` while holding the soul write-lock. Use this around any
+ * read-modify-write of soul state (e.g. desire-progress appends) so a
+ * concurrent heartbeat/idle/chat process can't interleave and lose data.
+ */
+export function withSoulLock(fn, opts) {
+    return withFileLock(SOUL_LOCK_PATH, fn, opts);
+}
+//# sourceMappingURL=lock.js.map

package/dist/soul/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/soul/lock.ts"],"names":[],"mappings":"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"}

package/dist/soul/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/soul/paths.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ,QAA+B,CAAC;AAErD,eAAO,MAAM,SAAS,QAAmC,CAAC;AAC1D,eAAO,MAAM,SAAS,QAAiC,CAAC;AACxD,eAAO,MAAM,aAAa,QAAqC,CAAC;AAChE,eAAO,MAAM,YAAY,QAAoC,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAyC,CAAC;AACxE,eAAO,MAAM,aAAa,QAAuC,CAAC;AAClE,eAAO,MAAM,SAAS,QAAwC,CAAC;AAE/D,eAAO,MAAM,eAAe,QAAgC,CAAC;AAC7D,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AACjE,eAAO,MAAM,gBAAgB,QAAiC,CAAC;AAC/D,eAAO,MAAM,gBAAgB,QAAiC,CAAC;AAC/D,eAAO,MAAM,sBAAsB,QAAuC,CAAC;AAE3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/soul/paths.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,QAAQ,QAA+B,CAAC;AAErD,eAAO,MAAM,SAAS,QAAmC,CAAC;AAC1D,eAAO,MAAM,SAAS,QAAiC,CAAC;AACxD,eAAO,MAAM,aAAa,QAAqC,CAAC;AAChE,eAAO,MAAM,YAAY,QAAoC,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAyC,CAAC;AACxE,eAAO,MAAM,aAAa,QAAuC,CAAC;AAClE,eAAO,MAAM,SAAS,QAAwC,CAAC;AAE/D,eAAO,MAAM,eAAe,QAAgC,CAAC;AAC7D,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AACjE,eAAO,MAAM,gBAAgB,QAAiC,CAAC;AAC/D,eAAO,MAAM,gBAAgB,QAAiC,CAAC;AAC/D,eAAO,MAAM,sBAAsB,QAAuC,CAAC;AAK3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AACD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/soul/paths.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { LISA_HOME } from "../paths.js";
+import { assertSafeSlug } from "./slug.js";
 export const SOUL_DIR = path.join(LISA_HOME, "soul");
 export const SOUL_SEED = path.join(SOUL_DIR, "seed.json");
 export const SOUL_NAME = path.join(SOUL_DIR, "name.md");
@@ -13,22 +14,27 @@ export const SOUL_OPINIONS_DIR = path.join(SOUL_DIR, "opinions");
 export const SOUL_DESIRES_DIR = path.join(SOUL_DIR, "desires");
 export const SOUL_JOURNAL_DIR = path.join(SOUL_DIR, "journal");
 export const SOUL_RELATIONSHIPS_DIR = path.join(SOUL_DIR, "relationships");
+// Every slug-bearing path helper runs the slug through assertSafeSlug first.
+// This is the single chokepoint for path-traversal defense: a slug like
+// "../../../etc/x" or "a/b" throws here rather than escaping the soul dir.
 export function valueFile(slug) {
-    return path.join(SOUL_VALUES_DIR, `${slug}.md`);
+    return path.join(SOUL_VALUES_DIR, `${assertSafeSlug(slug)}.md`);
 }
 export function opinionFile(slug) {
-    return path.join(SOUL_OPINIONS_DIR, `${slug}.md`);
+    return path.join(SOUL_OPINIONS_DIR, `${assertSafeSlug(slug)}.md`);
 }
 export function desireFile(slug) {
-    return path.join(SOUL_DESIRES_DIR, `${slug}.md`);
+    return path.join(SOUL_DESIRES_DIR, `${assertSafeSlug(slug)}.md`);
 }
 export function desireProgressFile(slug) {
-    return path.join(SOUL_DESIRES_DIR, `${slug}.progress.md`);
+    return path.join(SOUL_DESIRES_DIR, `${assertSafeSlug(slug)}.progress.md`);
 }
 export function journalFile(date) {
-    return path.join(SOUL_JOURNAL_DIR, `${date}.md`);
+    // Journal keys are dates (YYYY-MM-DD), which assertSafeSlug accepts (no
+    // separators/dots-leading), so this guards against a malformed date too.
+    return path.join(SOUL_JOURNAL_DIR, `${assertSafeSlug(date)}.md`);
 }
 export function relationshipFile(userKey) {
-    return path.join(SOUL_RELATIONSHIPS_DIR, `${userKey}.md`);
+    return path.join(SOUL_RELATIONSHIPS_DIR, `${assertSafeSlug(userKey)}.md`);
 }
 //# sourceMappingURL=paths.js.map

package/dist/soul/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/soul/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AAClE,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AAE/D,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AAE3E,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;AAClD,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;AACpD,CAAC;AACD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;AACnD,CAAC;AACD,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,IAAI,cAAc,CAAC,CAAC;AAC5D,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;AACnD,CAAC;AACD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,GAAG,OAAO,KAAK,CAAC,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/soul/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AAClE,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;AAE/D,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AAE3E,6EAA6E;AAC7E,wEAAwE;AACxE,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AACD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AACD,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC5E,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,wEAAwE;IACxE,yEAAyE;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AACD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC5E,CAAC"}

package/dist/soul/slug.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Slug safety for soul file paths.
+ *
+ * Soul state lives one-file-per-entry under ~/.lisa/soul/{values,opinions,
+ * desires,relationships}/<slug>.md. The slug comes from the LLM (via
+ * soul_patch / desire tools) or from reflect operations, so it is untrusted
+ * input that gets joined into a filesystem path. Without validation, a slug
+ * like "../../../etc/something" or "foo/bar" would let a write escape the
+ * soul directory (path traversal) or silently nest into subdirectories.
+ *
+ * Two functions, two jobs:
+ *   - assertSafeSlug — a HARD GATE applied in every path helper (read AND
+ *     write). Throws on anything that could traverse or escape. Deliberately
+ *     permissive about case/style so it never breaks reads of slugs written
+ *     by older versions; it only blocks genuinely dangerous shapes.
+ *   - normalizeSlug — a SOFT CLEANER applied when a NEW slug is first minted
+ *     from free-form input. Lowercases, strips to [a-z0-9-], collapses dashes,
+ *     caps length — produces a tidy, collision-resistant slug.
+ */
+export declare const MAX_SLUG_LEN = 64;
+export declare class UnsafeSlugError extends Error {
+    constructor(slug: string, reason: string);
+}
+/**
+ * Throw if `slug` could escape its soul subdirectory or corrupt the path.
+ * This is the security boundary — applied in paths.ts so no code path can
+ * construct a soul file path from a dangerous slug.
+ */
+export declare function assertSafeSlug(slug: string): string;
+/**
+ * Produce a tidy slug from free-form text. Use when minting a NEW slug.
+ * - lowercases
+ * - replaces any run of non [a-z0-9] with a single dash
+ * - trims leading/trailing dashes
+ * - caps length
+ * Returns "" only if the input had no usable characters; callers should
+ * treat "" as "generate a fallback" (e.g. a timestamp-based slug).
+ */
+export declare function normalizeSlug(raw: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/soul/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../src/soul/slug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIzC;AAWD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD"}

package/dist/soul/slug.js

@@ -0,0 +1,78 @@
+/**
+ * Slug safety for soul file paths.
+ *
+ * Soul state lives one-file-per-entry under ~/.lisa/soul/{values,opinions,
+ * desires,relationships}/<slug>.md. The slug comes from the LLM (via
+ * soul_patch / desire tools) or from reflect operations, so it is untrusted
+ * input that gets joined into a filesystem path. Without validation, a slug
+ * like "../../../etc/something" or "foo/bar" would let a write escape the
+ * soul directory (path traversal) or silently nest into subdirectories.
+ *
+ * Two functions, two jobs:
+ *   - assertSafeSlug — a HARD GATE applied in every path helper (read AND
+ *     write). Throws on anything that could traverse or escape. Deliberately
+ *     permissive about case/style so it never breaks reads of slugs written
+ *     by older versions; it only blocks genuinely dangerous shapes.
+ *   - normalizeSlug — a SOFT CLEANER applied when a NEW slug is first minted
+ *     from free-form input. Lowercases, strips to [a-z0-9-], collapses dashes,
+ *     caps length — produces a tidy, collision-resistant slug.
+ */
+export const MAX_SLUG_LEN = 64;
+export class UnsafeSlugError extends Error {
+    constructor(slug, reason) {
+        super(`unsafe soul slug ${JSON.stringify(slug)}: ${reason}`);
+        this.name = "UnsafeSlugError";
+    }
+}
+// Control characters (codepoints 0x00–0x1f): newlines, tabs, null, etc.
+// Checked via codepoint so the source stays plain-ASCII.
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) < 0x20)
+            return true;
+    }
+    return false;
+}
+/**
+ * Throw if `slug` could escape its soul subdirectory or corrupt the path.
+ * This is the security boundary — applied in paths.ts so no code path can
+ * construct a soul file path from a dangerous slug.
+ */
+export function assertSafeSlug(slug) {
+    if (typeof slug !== "string" || slug.length === 0) {
+        throw new UnsafeSlugError(String(slug), "empty");
+    }
+    if (slug.length > MAX_SLUG_LEN) {
+        throw new UnsafeSlugError(slug, `longer than ${MAX_SLUG_LEN} chars`);
+    }
+    if (hasControlChar(slug)) {
+        throw new UnsafeSlugError(slug, "contains control characters");
+    }
+    if (slug.includes("/") || slug.includes("\\")) {
+        throw new UnsafeSlugError(slug, "contains a path separator");
+    }
+    // Block "." / ".." and any leading-dot form — path-traversal primitives
+    // and dotfiles that would hide from directory listings.
+    if (slug.startsWith(".")) {
+        throw new UnsafeSlugError(slug, "starts with a dot");
+    }
+    return slug;
+}
+/**
+ * Produce a tidy slug from free-form text. Use when minting a NEW slug.
+ * - lowercases
+ * - replaces any run of non [a-z0-9] with a single dash
+ * - trims leading/trailing dashes
+ * - caps length
+ * Returns "" only if the input had no usable characters; callers should
+ * treat "" as "generate a fallback" (e.g. a timestamp-based slug).
+ */
+export function normalizeSlug(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_SLUG_LEN)
+        .replace(/-+$/g, ""); // re-trim in case slice landed mid-dash-run
+}
+//# sourceMappingURL=slug.js.map

package/dist/soul/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../../src/soul/slug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAE/B,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,wEAAwE;AACxE,yDAAyD;AACzD,SAAS,cAAc,CAAC,CAAS;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,OAAO,IAAI,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QAC/B,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,eAAe,YAAY,QAAQ,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,6BAA6B,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,2BAA2B,CAAC,CAAC;IAC/D,CAAC;IACD,wEAAwE;IACxE,wDAAwD;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,GAAG;SACP,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;SACtB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,4CAA4C;AACtE,CAAC"}

package/dist/soul/store.d.ts

@@ -13,7 +13,18 @@ export declare function readConstitution(): Promise<string>;
 export declare function writeConstitution(text: string): Promise<void>;
 export declare function readEmotions(): Promise<EmotionState>;
 export declare function writeEmotions(state: EmotionState): Promise<void>;
-export declare function decayEmotions(state: EmotionState): Promise<EmotionState>;
+/**
+ * Apply exponential decay to all emotion intensities based on elapsed time
+ * since `state.updatedAt`. Pure modulo the clock: pass `nowMs` to make it
+ * deterministic (tests / replay). Preserves the `events` trail and the
+ * per-emotion `decay` rates — only the `values` and `updatedAt` change.
+ *
+ * Called BOTH on read (display) and at the start of soul_feel (so the
+ * persisted baseline is always decay-correct before a new delta is added).
+ * Previously decay only ran on read, so soul_feel added deltas onto a stale
+ * (un-decayed) value and the stored intensity could be months out of date.
+ */
+export declare function decayEmotions(state: EmotionState, nowMs?: number): EmotionState;
 export declare function listValues(): Promise<ValueEntry[]>;
 export declare function writeValue(entry: ValueEntry): Promise<void>;
 export declare function listOpinions(): Promise<OpinionEntry[]>;