@drewpayment/mink 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {

package/src/commands/bug-search.ts

@@ -1,5 +1,5 @@
-import { loadBugMemory, searchBugs } from "../core/bug-memory";
-import { bugMemoryPath } from "../core/paths";
+import { searchBugs } from "../core/bug-memory";
+import { aggregateBugMemory } from "../core/state-aggregator";
 
 export function bugSearch(cwd: string, query: string): void {
   if (!query) {
@@ -7,7 +7,7 @@ export function bugSearch(cwd: string, query: string): void {
     process.exit(1);
   }
 
-  const memory = loadBugMemory(bugMemoryPath(cwd));
+  const memory = aggregateBugMemory(cwd);
   const results = searchBugs(memory, query);
 
   if (results.length === 0) {

package/src/commands/detect-waste.ts

@@ -1,36 +1,31 @@
 import { statSync } from "fs";
 import {
-  tokenLedgerPath,
+  tokenLedgerShardPath,
   fileIndexPath,
-  actionLogPath,
   learningMemoryPath,
 } from "../core/paths";
-import { createEmptyLedger, isTokenLedger, saveLedger } from "../core/token-ledger";
+import { loadLedger, saveLedger } from "../core/token-ledger";
 import { isFileIndex, createEmptyIndex } from "../core/index-store";
-import { safeReadLog } from "../core/action-log";
+import {
+  aggregateTokenLedger,
+  aggregateActionLog,
+} from "../core/state-aggregator";
+import { loadCounters } from "../core/state-counters";
 import { safeReadJson } from "../core/fs-utils";
 import { runDetection } from "../core/waste-detection";
+import { getOrCreateDeviceId } from "../core/device";
 import type { TokenLedger } from "../types/token-ledger";
 import type { FileIndex } from "../types/file-index";
 
 export function detectWaste(cwd: string): void {
-  const ledgerPath = tokenLedgerPath(cwd);
   const idxPath = fileIndexPath(cwd);
-  const logPath = actionLogPath(cwd);
   const lmPath = learningMemoryPath(cwd);
 
-  // Load and validate ledger — distinguish empty vs corrupted
-  const rawLedger = safeReadJson(ledgerPath);
-  let ledger: TokenLedger;
-
-  if (rawLedger === null) {
-    ledger = createEmptyLedger();
-  } else if (!isTokenLedger(rawLedger)) {
-    console.warn("[mink] Warning: corrupt token ledger, skipping waste detection");
-    return;
-  } else {
-    ledger = rawLedger;
-  }
+  // Aggregated ledger (across all device shards + legacy). Aggregator returns
+  // an empty ledger when no sources exist, so the empty-vs-corrupt distinction
+  // collapses into "treat missing as empty" — corrupt files inside a shard are
+  // already logged by loadLedger.
+  const ledger: TokenLedger = aggregateTokenLedger(cwd);
 
   // Load file index
   const rawIndex = safeReadJson(idxPath);
@@ -41,8 +36,8 @@ export function detectWaste(cwd: string): void {
     fileIndex = createEmptyIndex();
   }
 
-  // Load action log content
-  const actionLogContent = safeReadLog(logPath);
+  // Aggregated action log content (across all device shards + legacy)
+  const actionLogContent = aggregateActionLog(cwd);
 
   // Get learning memory mtime
   let learningMemoryMtimeMs: number | null = null;
@@ -52,18 +47,32 @@ export function detectWaste(cwd: string): void {
     // File missing — will be flagged as stale
   }
 
-  // Run detection
+  // Pull hit/miss telemetry from the per-device counter file, falling back to
+  // the legacy header counters when unmigrated. We feed runDetection a synthetic
+  // header so it works without knowing about the split.
+  const counters = loadCounters(cwd);
+  const headerForDetection = {
+    ...fileIndex.header,
+    lifetimeHits: counters.fileIndexHits || fileIndex.header.lifetimeHits,
+    lifetimeMisses: counters.fileIndexMisses || fileIndex.header.lifetimeMisses,
+  };
+
+  // Run detection on the aggregated cross-device view
   const flags = runDetection(
     ledger,
     fileIndex.entries,
-    fileIndex.header,
+    headerForDetection,
     actionLogContent,
     learningMemoryMtimeMs
   );
 
-  // Store flags in ledger (replaces previous)
-  ledger.wasteFlags = flags;
-  saveLedger(ledgerPath, ledger);
+  // Persist flags in THIS device's shard ledger so it's the only writer for
+  // that file. The aggregator unions wasteFlags across shards on read, so
+  // every device's view stays current without merge conflicts.
+  const shardLedgerPath = tokenLedgerShardPath(cwd, getOrCreateDeviceId());
+  const shardLedger = loadLedger(shardLedgerPath);
+  shardLedger.wasteFlags = flags;
+  saveLedger(shardLedgerPath, shardLedger);
 
   // Output summary
   if (flags.length === 0) {

package/src/commands/post-read.ts

@@ -1,11 +1,12 @@
 import { relative } from "path";
 import { readStdinJson } from "../core/stdin";
-import { sessionPath, fileIndexPath, actionLogPath } from "../core/paths";
+import { sessionPath, fileIndexPath, actionLogShardPath } from "../core/paths";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState, recordRead } from "../core/session";
 import { isFileIndex, lookupEntry } from "../core/index-store";
 import { estimateTokens, isBinaryFile } from "../core/token-estimate";
 import { createActionLogWriter } from "../core/action-log";
+import { getOrCreateDeviceId } from "../core/device";
 import type { SessionState } from "../types/session";
 import type { FileIndex } from "../types/file-index";
 import type { PostToolUseInput } from "../types/hook-input";
@@ -100,9 +101,11 @@ export async function postRead(cwd: string): Promise<void> {
     // Record the read in session state
     recordRead(state, filePath, result.estimatedTokens, result.indexHit);
 
-    // Append read entry to action log
+    // Append read entry to this device's action log shard
     try {
-      const logWriter = createActionLogWriter(actionLogPath(cwd));
+      const logWriter = createActionLogWriter(
+        actionLogShardPath(cwd, getOrCreateDeviceId())
+      );
       logWriter.appendReadEntry(
         new Date().toISOString(),
         filePath,

package/src/commands/post-write.ts

@@ -1,7 +1,8 @@
 import { relative } from "path";
 import { readFileSync } from "fs";
 import { readStdinJson } from "../core/stdin";
-import { sessionPath, fileIndexPath, actionLogPath } from "../core/paths";
+import { sessionPath, fileIndexPath, actionLogShardPath } from "../core/paths";
+import { getOrCreateDeviceId } from "../core/device";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState, recordWrite } from "../core/session";
 import {
@@ -129,9 +130,11 @@ export async function postWrite(cwd: string): Promise<void> {
       upsertEntry(index, result.indexEntry);
     }
 
-    // 2. Action log entry
+    // 2. Action log entry — write to this device's shard
     try {
-      const logWriter = createActionLogWriter(actionLogPath(cwd));
+      const logWriter = createActionLogWriter(
+        actionLogShardPath(cwd, getOrCreateDeviceId())
+      );
       logWriter.appendWriteEntry(
         new Date().toISOString(),
         filePath,

package/src/commands/pre-read.ts

@@ -3,12 +3,11 @@ import { readStdinJson } from "../core/stdin";
 import { sessionPath, fileIndexPath } from "../core/paths";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState } from "../core/session";
+import { isFileIndex, lookupEntry } from "../core/index-store";
 import {
-  isFileIndex,
-  lookupEntry,
-  recordHit,
-  recordMiss,
-} from "../core/index-store";
+  incrementFileIndexHit,
+  incrementFileIndexMiss,
+} from "../core/state-counters";
 import type { SessionState } from "../types/session";
 import type { FileIndex, FileIndexEntry } from "../types/file-index";
 import type { PreToolUseInput } from "../types/hook-input";
@@ -40,17 +39,17 @@ export function analyzePreRead(
     state.counters.repeatedReadWarnings++;
   }
 
-  // File index lookup
+  // File index lookup. Hit/miss telemetry is persisted by the caller via
+  // increment{Hit,Miss}, not by mutating the shared index — keeping the
+  // file-index.json content-addressed by filePath so a JSON union merge driver
+  // can resolve cross-device updates without conflict.
   if (index) {
     entry = lookupEntry(index, filePath);
     if (entry) {
       indexHit = true;
-      recordHit(index);
       warnings.push(
         `[mink] ${filePath} — ${entry.description} (~${entry.estimatedTokens} tokens)`
       );
-    } else {
-      recordMiss(index);
     }
   }
 
@@ -99,7 +98,12 @@ export async function preRead(cwd: string): Promise<void> {
     // Persist state changes
     atomicWriteJson(sessionPath(cwd), state);
     if (index) {
-      atomicWriteJson(fileIndexPath(cwd), index);
+      try {
+        if (result.indexHit) incrementFileIndexHit(cwd);
+        else incrementFileIndexMiss(cwd);
+      } catch {
+        // Counter file is best-effort telemetry — never block the read hook
+      }
     }
   } catch {
     // Never crash — exit silently

package/src/commands/pre-write.ts

@@ -5,6 +5,10 @@ import { sessionPath, learningMemoryPath, bugMemoryPath } from "../core/paths";
 import { safeReadJson, atomicWriteJson } from "../core/fs-utils";
 import { createSessionState, isSessionState } from "../core/session";
 import { parseLearningMemory, getEntries } from "../core/learning-memory";
+import {
+  aggregateLearningMemory,
+  aggregateBugMemory,
+} from "../core/state-aggregator";
 import { extractPatterns, matchPatterns } from "../core/pattern-engine";
 import {
   loadBugMemory,
@@ -88,20 +92,19 @@ export async function preWrite(cwd: string): Promise<void> {
     const filePath = relative(cwd, absolutePath);
     const writeContent = extractWriteContent(input);
 
-    // Load learning memory Do-Not-Repeat entries
+    // Load learning memory Do-Not-Repeat entries (canonical + sidecars)
     let doNotRepeatEntries: string[] = [];
     try {
-      const markdown = readFileSync(learningMemoryPath(cwd), "utf-8");
-      const mem = parseLearningMemory(markdown);
+      const mem = aggregateLearningMemory(cwd);
       doNotRepeatEntries = getEntries(mem, "Do-Not-Repeat");
     } catch {
       // Learning memory not found or corrupt — skip enforcement
     }
 
-    // Load bug memory for this file
+    // Load bug memory for this file (aggregated across shards)
     let bugMemory: BugMemory | undefined;
     try {
-      bugMemory = loadBugMemory(bugMemoryPath(cwd));
+      bugMemory = aggregateBugMemory(cwd);
     } catch {
       // Bug memory not found or corrupt — skip lookup
     }

package/src/commands/reflect.ts

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync } from "fs";
-import { parseLearningMemory, serializeLearningMemory } from "../core/learning-memory";
+import { existsSync } from "fs";
+import { dirname } from "path";
+import { serializeLearningMemory, totalEntryCount } from "../core/learning-memory";
+import { aggregateLearningMemoryAt } from "../core/state-aggregator";
 import { reflectMemory } from "../core/reflection";
 import { atomicWriteText, safeReadJson } from "../core/fs-utils";
 import type { ReflectionResult } from "../types/learning-memory";
@@ -8,18 +10,21 @@ import type { ProjectConfig } from "../types/file-index";
 const DEFAULT_TOKEN_BUDGET = 2000;
 
 export function reflect(
-  projectDir: string,
+  _cwd: string,
   memoryPath: string,
   configPath: string
 ): ReflectionResult | null {
-  if (!existsSync(memoryPath)) {
+  // Aggregate canonical + every device's sidecar that sits next to memoryPath.
+  // Using dirname(memoryPath) keeps callers in control of where the project
+  // state lives — production passes projectDir(cwd)/learning-memory.md, tests
+  // pass arbitrary temp directories.
+  const projDir = dirname(memoryPath);
+  const mem = aggregateLearningMemoryAt(projDir);
+  if (totalEntryCount(mem) === 0 && !existsSync(memoryPath)) {
     console.log("[mink] no learning memory found");
     return null;
   }
 
-  const markdown = readFileSync(memoryPath, "utf-8");
-  const mem = parseLearningMemory(markdown);
-
   const config = safeReadJson(configPath) as ProjectConfig | null;
   const tokenBudget = config?.learningMemoryTokenBudget ?? DEFAULT_TOKEN_BUDGET;
 

package/src/commands/session-start.ts

@@ -1,8 +1,9 @@
 import { mkdirSync } from "fs";
 import { createSessionState } from "../core/session";
-import { projectDir, sessionPath, actionLogPath } from "../core/paths";
+import { projectDir, sessionPath, actionLogShardPath } from "../core/paths";
 import { atomicWriteJson } from "../core/fs-utils";
 import { createActionLogWriter } from "../core/action-log";
+import { getOrCreateDeviceId } from "../core/device";
 import { isWikiEnabled, isVaultInitialized, isInsideVault } from "../core/vault";
 import { loadVaultIndex } from "../core/note-index";
 
@@ -23,6 +24,17 @@ export function sessionStart(cwd: string): void {
     // Never crash hooks
   }
 
+  // One-shot migration to sync layout v2. Idempotent re-run is a no-op.
+  try {
+    const { readSyncVersion, MINK_SYNC_VERSION } = require("../core/sync");
+    if (readSyncVersion() < MINK_SYNC_VERSION) {
+      const { migrateSyncLayout } = require("./sync-migrate");
+      migrateSyncLayout();
+    }
+  } catch {
+    // Migration is best-effort; never block session-start
+  }
+
   // Sync pull before session begins (if enabled)
   try {
     const { isSyncInitialized, syncPull } = require("../core/sync");
@@ -39,9 +51,11 @@ export function sessionStart(cwd: string): void {
   const state = createSessionState();
   atomicWriteJson(sessionPath(cwd), state);
 
-  // Append session header to action log
+  // Append session header to this device's action log shard
   try {
-    const logWriter = createActionLogWriter(actionLogPath(cwd));
+    const logWriter = createActionLogWriter(
+      actionLogShardPath(cwd, getOrCreateDeviceId())
+    );
     logWriter.appendSessionHeader(state.startTimestamp);
   } catch {
     // Never crash hooks
@@ -55,6 +69,23 @@ export function sessionStart(cwd: string): void {
         (e) => e.category === "inbox"
       ).length;
 
+      // Regenerate the master index when missing — it's gitignored under sync
+      // v2 so freshly-cloned devices need it materialised before Obsidian can
+      // see the vault. updateMasterIndex is idempotent + cheap.
+      try {
+        const { join } = require("path");
+        const { existsSync } = require("fs");
+        const { resolveVaultPath } = require("../core/vault");
+        const { updateMasterIndex } = require("../core/note-linker");
+        const vaultPath = resolveVaultPath();
+        const masterIndexPath = join(vaultPath, "_index.md");
+        if (!existsSync(masterIndexPath)) {
+          updateMasterIndex(vaultPath);
+        }
+      } catch {
+        // Never crash hooks on regeneration failure
+      }
+
       if (inboxCount > 0) {
         console.error(
           `[mink] vault: ${inboxCount} notes in inbox need categorization`

package/src/commands/session-stop.ts

@@ -4,8 +4,10 @@ import { safeReadJson, atomicWriteJson, atomicWriteText } from "../core/fs-utils
 import { isSessionState, buildSummary } from "../core/session";
 import { reflect } from "./reflect";
 import { createLedgerFinalizer } from "../core/token-ledger";
-import { loadBugMemory, hasBugForFileInSession } from "../core/bug-memory";
+import { hasBugForFileInSession } from "../core/bug-memory";
+import { aggregateBugMemoryAt } from "../core/state-aggregator";
 import { createActionLogWriter, consolidateLog } from "../core/action-log";
+import { getOrCreateDeviceId } from "../core/device";
 import {
   isWikiEnabled,
   isVaultInitialized,
@@ -55,7 +57,8 @@ export function sessionStop(
   state.stopCount++;
 
   const projDir = dirname(sessionFile);
-  const effectiveFinalizer = finalizer ?? createLedgerFinalizer(projDir);
+  const deviceId = getOrCreateDeviceId();
+  const effectiveFinalizer = finalizer ?? createLedgerFinalizer(projDir, deviceId);
 
   if (hasActivity(state)) {
     const summary = buildSummary(state);
@@ -66,9 +69,11 @@ export function sessionStop(
       effectiveFinalizer.updateSession(summary);
     }
 
-    // Append session end to action log and run consolidation
+    // Append session end to action log and run consolidation. Both writes
+    // target THIS device's shard so concurrent sessions on other devices
+    // never collide on the action log file.
     try {
-      const logPath = join(projDir, "action-log.md");
+      const logPath = join(projDir, "state", deviceId, "action-log.md");
       const logWriter = createActionLogWriter(logPath);
       logWriter.appendSessionEnd(summary);
 
@@ -84,8 +89,7 @@ export function sessionStop(
 
   // Check for files edited 3+ times without a corresponding bug entry
   const editCounts = getEditCounts(state);
-  const bugMemoryFile = join(projDir, "bug-memory.json");
-  const bugMemory = loadBugMemory(bugMemoryFile);
+  const bugMemory = aggregateBugMemoryAt(projDir);
 
   for (const [filePath, count] of Object.entries(editCounts)) {
     if (count >= 3) {

package/src/commands/status.ts

@@ -13,6 +13,12 @@ import { isFileIndex } from "../core/index-store";
 import { loadLedger } from "../core/token-ledger";
 import { parseLearningMemory, totalEntryCount } from "../core/learning-memory";
 import { loadBugMemory } from "../core/bug-memory";
+import {
+  aggregateTokenLedger,
+  aggregateBugMemory,
+  aggregateLearningMemory,
+} from "../core/state-aggregator";
+import { loadCounters } from "../core/state-counters";
 import { getDaemonStatus } from "../core/daemon";
 
 interface FileCheck {
@@ -72,12 +78,17 @@ export function status(cwd: string): void {
     const raw = safeReadJson(fileIndexPath(cwd));
     if (raw && isFileIndex(raw)) {
       const h = raw.header;
-      const total = h.lifetimeHits + h.lifetimeMisses;
-      const ratio = total > 0 ? ((h.lifetimeHits / total) * 100).toFixed(1) : "N/A";
+      // Hit/miss counters live in the per-device counter file, fall back to
+      // legacy header counters for unmigrated repos.
+      const counters = loadCounters(cwd);
+      const hits = counters.fileIndexHits || h.lifetimeHits;
+      const misses = counters.fileIndexMisses || h.lifetimeMisses;
+      const total = hits + misses;
+      const ratio = total > 0 ? ((hits / total) * 100).toFixed(1) : "N/A";
       console.log("  File index:");
       console.log(`    Files: ${h.totalFiles}`);
       console.log(`    Last scan: ${h.lastScanTimestamp || "never"}`);
-      console.log(`    Hit/miss ratio: ${ratio}${total > 0 ? "%" : ""} (${h.lifetimeHits} hits, ${h.lifetimeMisses} misses)`);
+      console.log(`    Hit/miss ratio: ${ratio}${total > 0 ? "%" : ""} (${hits} hits, ${misses} misses)`);
     } else {
       console.log("  File index: not available");
     }
@@ -86,9 +97,9 @@ export function status(cwd: string): void {
   }
   console.log();
 
-  // Section 3: Token ledger
+  // Section 3: Token ledger (aggregated across all device shards + legacy)
   try {
-    const ledger = loadLedger(tokenLedgerPath(cwd));
+    const ledger = aggregateTokenLedger(cwd);
     const lt = ledger.lifetime;
     console.log("  Token ledger:");
     console.log(`    Sessions: ${lt.totalSessions}`);
@@ -100,32 +111,33 @@ export function status(cwd: string): void {
   }
   console.log();
 
-  // Section 4: Learning memory
+  // Section 4: Learning memory (canonical + sidecars)
   try {
-    const memPath = learningMemoryPath(cwd);
-    if (existsSync(memPath)) {
-      const content = readFileSync(memPath, "utf-8");
-      const mem = parseLearningMemory(content);
-      const total = totalEntryCount(mem);
-      const mtime = statSync(memPath).mtime;
+    const mem = aggregateLearningMemory(cwd);
+    const total = totalEntryCount(mem);
+    if (total === 0 && mem.projectName === "unknown") {
+      console.log("  Learning memory: not initialized");
+    } else {
       console.log("  Learning memory:");
       console.log(`    User Preferences: ${mem.sections["User Preferences"].length}`);
       console.log(`    Key Learnings: ${mem.sections["Key Learnings"].length}`);
       console.log(`    Do-Not-Repeat: ${mem.sections["Do-Not-Repeat"].length}`);
       console.log(`    Decision Log: ${mem.sections["Decision Log"].length}`);
       console.log(`    Total entries: ${total}`);
-      console.log(`    Last modified: ${mtime.toISOString()}`);
-    } else {
-      console.log("  Learning memory: not initialized");
+      const memPath = learningMemoryPath(cwd);
+      if (existsSync(memPath)) {
+        const mtime = statSync(memPath).mtime;
+        console.log(`    Canonical last modified: ${mtime.toISOString()}`);
+      }
     }
   } catch {
     console.log("  Learning memory: error reading");
   }
   console.log();
 
-  // Section 5: Bug log
+  // Section 5: Bug log (aggregated across shards)
   try {
-    const bugs = loadBugMemory(bugMemoryPath(cwd));
+    const bugs = aggregateBugMemory(cwd);
     console.log(`  Bug log: ${bugs.entries.length} entries`);
   } catch {
     console.log("  Bug log: error reading");