sticky-note-cli 2.9.2 → 3.0.0

package/bin/cli.js

@@ -25,6 +25,7 @@ const VERSION = require("../package.json").version;
 
 const HOOK_FILES = [
   "sticky-utils.js",
+  "data-branch.js",          // git plumbing module for sticky-note/data branch
   "session-start.js",
   "session-end.js",
   "inject-context.js",
@@ -115,6 +116,14 @@ function findStaleHookPaths(settings) {
         ) {
           stale.push(cmd);
         }
+        // Old relative-path format: node ".claude/hooks/foo.js"
+        // This fails when Claude Code launches from a subdirectory of the
+        // project root, because the path resolves relative to the launch cwd,
+        // not relative to where .claude/settings.json lives. The fix is to
+        // use `npx sticky-note run-hook foo` which walks up to find the hooks.
+        if (/node\s+["']\.claude[\\/]hooks[\\/][^"']+\.js["']/.test(cmd)) {
+          stale.push(cmd);
+        }
       }
     }
   }
@@ -975,15 +984,9 @@ async function cmdInit() {
     print("  [OK] .git/hooks/post-rewrite (attribution survives rebase)");
   }
 
-  // Install pre-commit hook (auto-stage .sticky-note/ files)
-  if (installPreCommitHook()) {
-    print("  [OK] .git/hooks/pre-commit (auto-stage .sticky-note/ files)");
-  }
-
-  // Install post-commit hook (auto-commit leftover .sticky-note/ changes)
-  if (installPostCommitHook()) {
-    print("  [OK] .git/hooks/post-commit (auto-sync .sticky-note/ after commit)");
-  }
+  // Data branch sync handles persistence — no pre/post-commit hooks needed
+  print("  [OK] Skipping git pre/post-commit hooks (data branch sync handles this now)");
+  print("       Run `npx sticky-note migrate` to migrate existing .sticky-note/ data.");
 
   // Create environment directory structure
   const envDir = path.join(stickyNoteDir, "environment");
@@ -1123,11 +1126,35 @@ function cmdUpdate() {
   if (installGitHook("post-rewrite")) {
     print("  [OK] .git/hooks/post-rewrite (attribution survives rebase)");
   }
-  if (installPreCommitHook()) {
-    print("  [OK] .git/hooks/pre-commit (auto-stage .sticky-note/ files)");
-  }
-  if (installPostCommitHook()) {
-    print("  [OK] .git/hooks/post-commit (auto-sync .sticky-note/ after commit)");
+
+  // Remove sticky-note pre-commit and post-commit git hooks (replaced by data branch)
+  const gitDir2 = path.join(process.cwd(), ".git");
+  if (fs.existsSync(gitDir2)) {
+    const gitHooksDir2 = path.join(gitDir2, "hooks");
+    for (const hookName of ["pre-commit", "post-commit"]) {
+      const hookPath2 = path.join(gitHooksDir2, hookName);
+      if (!fs.existsSync(hookPath2)) continue;
+      const content2 = fs.readFileSync(hookPath2, "utf-8");
+      if (!content2.includes(STICKY_PRE_COMMIT_MARKER) && !content2.includes(STICKY_POST_COMMIT_MARKER)) continue;
+      let updated2 = content2;
+      const preStart2 = updated2.indexOf(STICKY_PRE_COMMIT_MARKER);
+      const preEnd2 = updated2.indexOf(STICKY_PRE_COMMIT_END);
+      if (preStart2 !== -1 && preEnd2 !== -1) {
+        updated2 = updated2.slice(0, preStart2) + updated2.slice(preEnd2 + STICKY_PRE_COMMIT_END.length);
+      }
+      const postStart2 = updated2.indexOf(STICKY_POST_COMMIT_MARKER);
+      const postEnd2 = updated2.indexOf(STICKY_POST_COMMIT_END);
+      if (postStart2 !== -1 && postEnd2 !== -1) {
+        updated2 = updated2.slice(0, postStart2) + updated2.slice(postEnd2 + STICKY_POST_COMMIT_END.length);
+      }
+      if (updated2.replace(/^#!.*\n/, "").trim() === "") {
+        fs.unlinkSync(hookPath2);
+        print("  [OK] Removed .git/hooks/" + hookName + " (no longer needed)");
+      } else {
+        fs.writeFileSync(hookPath2, updated2, "utf-8");
+        print("  [OK] Removed sticky-note blocks from .git/hooks/" + hookName);
+      }
+    }
   }
 
   // Update hook_version in config
@@ -3350,6 +3377,308 @@ async function cmdEnvAddPlugin() {
   print("");
 }
 
+// ──────────────────────────────────────────────
+// run-hook: locate and execute a hook from any directory
+// ──────────────────────────────────────────────
+
+function cmdRunHook() {
+  const { spawnSync } = require("child_process");
+  const hookName = process.argv[3]; // e.g. "session-start"
+
+  if (!hookName) {
+    process.stderr.write(
+      "[sticky-note] run-hook: missing hook name\n" +
+      "  Usage: npx sticky-note run-hook <name>\n" +
+      "  Names: session-start, session-end, inject-context, pre-tool-use,\n" +
+      "         track-work, on-stop, on-error\n"
+    );
+    // Emit empty output so Claude Code doesn't choke on missing stdout JSON
+    process.stdout.write(JSON.stringify({ output: "" }) + "\n");
+    process.exit(0);
+  }
+
+  // Walk up from cwd to find .claude/hooks/<name>.js
+  const hookFile = hookName.endsWith(".js") ? hookName : `${hookName}.js`;
+  let dir = process.cwd();
+  let hookPath = null;
+  for (let i = 0; i < 20; i++) {
+    const candidate = path.join(dir, ".claude", "hooks", hookFile);
+    if (fs.existsSync(candidate)) {
+      hookPath = candidate;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+
+  if (!hookPath) {
+    // Hook not installed — exit silently (non-fatal)
+    process.stdout.write(JSON.stringify({ output: "" }) + "\n");
+    process.exit(0);
+  }
+
+  // Spawn the hook with stdin/stdout/stderr inherited so Claude Code's pipe
+  // flows through to the hook process unchanged.
+  const result = spawnSync(process.execPath, [hookPath], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(result.status != null ? result.status : 0);
+}
+
+// ──────────────────────────────────────────────
+// MIGRATE command
+// ──────────────────────────────────────────────
+
+/**
+ * One-time migration from .sticky-note/ (feature-branch storage) to
+ * .git/sticky-note/ (data-branch storage).
+ *
+ * Idempotent — safe to run multiple times.
+ */
+async function cmdMigrate() {
+  printBanner();
+
+  if (!isGitRepo()) {
+    print("  [ERR] Not a git repository.");
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const oldDir = path.join(cwd, ".sticky-note");
+
+  // Locate .git directory using plumbing (works from subdirectories)
+  let gitDir;
+  try {
+    gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      cwd,
+    }).trim();
+  } catch (err) {
+    print("  [ERR] Could not locate .git directory: " + err.message);
+    process.exit(1);
+  }
+
+  const newDir = path.join(gitDir, "sticky-note");
+  print("  📂 Source: " + oldDir);
+  print("  📂 Target: " + newDir);
+  print("");
+
+  // Step 1: Copy files from .sticky-note/ to .git/sticky-note/
+  mkdirSafe(newDir);
+  mkdirSafe(path.join(newDir, "audit"));
+  mkdirSafe(path.join(newDir, "presence"));
+
+  let copiedFiles = 0;
+  const srcMemory = path.join(oldDir, "sticky-note.json");
+  const dstMemory = path.join(newDir, "sticky-note.json");
+  if (fs.existsSync(srcMemory)) {
+    fs.copyFileSync(srcMemory, dstMemory);
+    copiedFiles++;
+    print("  [OK] Copied sticky-note.json");
+  } else if (!fs.existsSync(dstMemory)) {
+    // No existing data — create empty memory
+    fs.writeFileSync(
+      dstMemory,
+      JSON.stringify({ version: "2", project: "", threads: [] }, null, 2) + "\n"
+    );
+    print("  [OK] Created empty sticky-note.json (no .sticky-note/ found)");
+  }
+
+  const oldAuditDir = path.join(oldDir, "audit");
+  if (fs.existsSync(oldAuditDir)) {
+    for (const file of fs.readdirSync(oldAuditDir)) {
+      if (file.endsWith(".jsonl")) {
+        const dst = path.join(newDir, "audit", file);
+        if (!fs.existsSync(dst)) {
+          fs.copyFileSync(path.join(oldAuditDir, file), dst);
+          copiedFiles++;
+        }
+      }
+    }
+  }
+
+  const oldPresenceDir = path.join(oldDir, "presence");
+  if (fs.existsSync(oldPresenceDir)) {
+    for (const file of fs.readdirSync(oldPresenceDir)) {
+      if (file.endsWith(".json")) {
+        const dst = path.join(newDir, "presence", file);
+        if (!fs.existsSync(dst)) {
+          fs.copyFileSync(path.join(oldPresenceDir, file), dst);
+          copiedFiles++;
+        }
+      }
+    }
+  }
+  if (copiedFiles > 0) print("  [OK] Copied " + copiedFiles + " file(s) to .git/sticky-note/");
+
+  // Step 2: Commit files to sticky-note/data branch using plumbing
+  print("");
+  print("  📌 Committing to sticky-note/data branch...");
+  try {
+    // Inline the plumbing here (data-branch.js lives in hooks, not in CLI path)
+    _commitFilesToDataBranch(newDir);
+    print("  [OK] sticky-note/data branch created/updated");
+  } catch (err) {
+    print("  [WARN] Could not commit to data branch: " + err.message);
+  }
+
+  // Step 3: Add .sticky-note/ to .gitignore
+  print("");
+  const gitignorePath = path.join(cwd, ".gitignore");
+  const MARKER = "# sticky-note: data branch migration";
+  const IGNORE_LINE = ".sticky-note/";
+  let gitignoreUpdated = false;
+  if (fs.existsSync(gitignorePath)) {
+    const existing = fs.readFileSync(gitignorePath, "utf-8");
+    const gitignoreLines = existing.split(/\r?\n/).map(l => l.trim());
+    if (!gitignoreLines.includes(IGNORE_LINE)) {
+      fs.appendFileSync(gitignorePath, "\n" + MARKER + "\n" + IGNORE_LINE + "\n");
+      gitignoreUpdated = true;
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, MARKER + "\n" + IGNORE_LINE + "\n");
+    gitignoreUpdated = true;
+  }
+  if (gitignoreUpdated) {
+    print("  [OK] Added .sticky-note/ to .gitignore");
+  } else {
+    print("  [OK] .gitignore already contains .sticky-note/");
+  }
+
+  // Step 4: Remove sticky-note pre-commit and post-commit hooks
+  print("");
+  const gitHooksDir = path.join(gitDir, "hooks");
+  for (const hookName of ["pre-commit", "post-commit"]) {
+    const hookPath = path.join(gitHooksDir, hookName);
+    if (!fs.existsSync(hookPath)) continue;
+    const content = fs.readFileSync(hookPath, "utf-8");
+    if (content.includes(STICKY_PRE_COMMIT_MARKER) || content.includes(STICKY_POST_COMMIT_MARKER)) {
+      // Remove sticky-note blocks
+      let updated = content;
+      // Remove pre-commit block
+      const preStart = updated.indexOf(STICKY_PRE_COMMIT_MARKER);
+      const preEnd = updated.indexOf(STICKY_PRE_COMMIT_END);
+      if (preStart !== -1 && preEnd !== -1) {
+        updated = updated.slice(0, preStart) + updated.slice(preEnd + STICKY_PRE_COMMIT_END.length);
+      }
+      // Remove post-commit block
+      const postStart = updated.indexOf(STICKY_POST_COMMIT_MARKER);
+      const postEnd = updated.indexOf(STICKY_POST_COMMIT_END);
+      if (postStart !== -1 && postEnd !== -1) {
+        updated = updated.slice(0, postStart) + updated.slice(postEnd + STICKY_POST_COMMIT_END.length);
+      }
+      // If only the shebang remains, delete the file
+      if (updated.replace(/^#!.*\n/, "").trim() === "") {
+        fs.unlinkSync(hookPath);
+        print("  [OK] Removed .git/hooks/" + hookName + " (was sticky-note only)");
+      } else {
+        fs.writeFileSync(hookPath, updated, "utf-8");
+        print("  [OK] Removed sticky-note blocks from .git/hooks/" + hookName);
+      }
+    }
+  }
+
+  // Step 5: Push data branch if remote exists
+  print("");
+  try {
+    const remote = execFileSync("git", ["remote"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      cwd,
+    }).trim().split("\n")[0];
+    if (remote) {
+      print("  🔄 Pushing sticky-note/data to " + remote + "...");
+      execFileSync("git", ["push", remote, "refs/heads/sticky-note/data:refs/heads/sticky-note/data"], {
+        timeout: 30000, stdio: ["pipe", "pipe", "pipe"],
+        cwd,
+      });
+      print("  [OK] Pushed sticky-note/data");
+    } else {
+      print("  ⏭️  No remote configured — skipping push");
+    }
+  } catch (err) {
+    print("  [WARN] Push failed: " + err.message);
+    print("  [INFO] Your data is safe locally. Run `npx sticky-note migrate` again to retry.");
+  }
+
+  print("");
+  print("  ✅ Migration complete!");
+  print("");
+  print("  Next steps:");
+  print("  1. Commit the .gitignore change:  git add .gitignore && git commit -m 'chore: gitignore sticky-note data dir'");
+  print("  2. Each teammate runs:             npx sticky-note init");
+  print("");
+}
+
+/**
+ * Inline git plumbing to commit files from a local dir to sticky-note/data.
+ * Extracted from data-branch.js for use in CLI context (no hooks dir on PATH).
+ */
+function _commitFilesToDataBranch(srcDir) {
+  const os = require("os");
+  const crypto = require("crypto");
+  const branchRef = "refs/heads/sticky-note/data";
+  const tmpIndex = path.join(
+    os.tmpdir(),
+    "sticky-idx-" + process.pid + "-" + crypto.randomBytes(4).toString("hex")
+  );
+
+  try {
+    let parentSha = null;
+    try {
+      parentSha = execFileSync("git", ["rev-parse", "--verify", branchRef], {
+        encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (_) {}
+
+    const indexEnv = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+    if (parentSha) {
+      execFileSync("git", ["read-tree", parentSha], {
+        timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv,
+      });
+    }
+
+    // Walk srcDir and commit all files
+    function walkAndAdd(dir, prefix) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        const relPath = prefix ? prefix + "/" + entry.name : entry.name;
+        if (entry.isDirectory()) {
+          walkAndAdd(full, relPath);
+        } else if (entry.isFile() && !entry.name.startsWith(".sticky-")) {
+          const content = fs.readFileSync(full);
+          const blobSha = execFileSync("git", ["hash-object", "-w", "--stdin"], {
+            input: content, encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+          }).trim();
+          execFileSync(
+            "git",
+            ["update-index", "--add", "--cacheinfo", "100644," + blobSha + "," + relPath],
+            { timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv }
+          );
+        }
+      }
+    }
+    walkAndAdd(srcDir, "");
+
+    const treeSha = execFileSync("git", ["write-tree"], {
+      encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv,
+    }).trim();
+
+    const commitArgs = ["commit-tree", treeSha, "-m", "chore(sticky-note): migrate to data branch"];
+    if (parentSha) commitArgs.push("-p", parentSha);
+    const commitSha = execFileSync("git", commitArgs, {
+      encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    execFileSync("git", ["update-ref", branchRef, commitSha], {
+      timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+    });
+  } finally {
+    try { fs.unlinkSync(tmpIndex); } catch (_) {}
+  }
+}
+
 // ──────────────────────────────────────────────
 // Main
 // ──────────────────────────────────────────────
@@ -3419,6 +3748,15 @@ async function main() {
     case "mcp-server":
       cmdMcpServer();
       break;
+    case "run-hook":
+      cmdRunHook();
+      break;
+    case "migrate":
+      cmdMigrate().catch((err) => {
+        console.error(err);
+        process.exit(1);
+      });
+      break;
     case "--version":
     case "-v":
       print(`sticky-note v${VERSION}`);
@@ -3449,6 +3787,7 @@ async function main() {
     print("    bootstrap          Provision MCP servers with secrets from manifest");
     print("    env                Environment management (status, add-server, add-plugin)");
     print("    mcp-server         Launch the sticky-note MCP server (stdio JSON-RPC)");
+    print("    run-hook <name>    Run a hook from any subdirectory (finds .claude/hooks/ up the tree)");
       print("");
       print("  Options:");
       print("    --version  Show version");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sticky-note-cli",
-  "version": "2.9.2",
+  "version": "3.0.0",
   "description": "Human-to-human handoff for AI coding assistants. Git-backed shared memory for Claude Code and Copilot CLI.",
   "license": "MIT",
   "bin": {

package/templates/gitignore-additions.txt

@@ -1,3 +1,6 @@
+# Sticky Note - data moved to sticky-note/data branch (.git/sticky-note/ cache)
+.sticky-note/
+
 # Sticky Note - local overrides
 .claude/settings.local.json
 

package/templates/hooks/data-branch.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * data-branch.js — Git plumbing for the sticky-note/data orphan branch.
+ *
+ * Reads/writes files via git plumbing (hash-object, update-index, write-tree,
+ * commit-tree, update-ref). No working-tree checkout is ever performed.
+ * All operations are synchronous; callers receive result objects on failure.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
+
+const DATA_BRANCH = "sticky-note/data";
+const DATA_REF = "refs/heads/" + DATA_BRANCH;
+
+const GIT_OPTS = { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] };
+
+// ── Git helpers ───────────────────────────────────────────
+
+function getDefaultRemote() {
+  try {
+    const out = execFileSync("git", ["remote"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return out.split(/\r?\n/)[0] || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Returns file content from a git ref as a string, or null if not found. */
+function readFileFromBranch(ref, filePath) {
+  try {
+    return execFileSync("git", ["show", ref + ":" + filePath], GIT_OPTS);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Commit { relativePath: content } to a branch using git plumbing.
+ * Does not touch the working tree or the main index. Returns the new commit SHA.
+ */
+function commitFilesToBranch(branchName, fileMap) {
+  const branchRef = "refs/heads/" + branchName;
+  const tmpIndex = path.join(
+    os.tmpdir(),
+    "sticky-idx-" + process.pid + "-" + crypto.randomBytes(4).toString("hex")
+  );
+
+  try {
+    let parentSha = null;
+    try {
+      parentSha = execFileSync("git", ["rev-parse", "--verify", branchRef], {
+        encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (_) {
+      // Branch doesn't exist yet — first commit creates it as orphan
+    }
+
+    const indexEnv = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+
+    if (parentSha) {
+      execFileSync("git", ["read-tree", parentSha], {
+        timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+        env: indexEnv,
+      });
+    }
+
+    for (const [filePath, content] of Object.entries(fileMap)) {
+      const blobSha = execFileSync("git", ["hash-object", "-w", "--stdin"], {
+        input: content,
+        encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+
+      execFileSync(
+        "git",
+        ["update-index", "--add", "--cacheinfo", "100644," + blobSha + "," + filePath],
+        { timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv }
+      );
+    }
+
+    const treeSha = execFileSync("git", ["write-tree"], {
+      encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+      env: indexEnv,
+    }).trim();
+
+    const commitArgs = ["commit-tree", treeSha, "-m", "chore(sticky-note): sync thread data"];
+    if (parentSha) {
+      commitArgs.push("-p", parentSha);
+    }
+
+    const commitSha = execFileSync("git", commitArgs, GIT_OPTS).trim();
+
+    execFileSync("git", ["update-ref", branchRef, commitSha], {
+      timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    return commitSha;
+  } finally {
+    try { fs.unlinkSync(tmpIndex); } catch (_) {}
+  }
+}
+
+// ── Fetch ─────────────────────────────────────────────────
+
+/**
+ * Fetch the remote data branch into a local remote-tracking ref.
+ * Returns { ok, sha, error, remoteRef }.
+ */
+function fetchDataBranch(remote, branchName) {
+  branchName = branchName || DATA_BRANCH;
+  remote = remote || getDefaultRemote();
+  if (!remote) return { ok: false, sha: null, error: "no remote configured", remoteRef: null };
+
+  const remoteRef = "refs/remotes/" + remote + "/" + branchName;
+  try {
+    execFileSync(
+      "git",
+      ["fetch", remote, branchName + ":" + remoteRef],
+      { timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
+    );
+    let sha = null;
+    try {
+      sha = execFileSync("git", ["rev-parse", "--verify", remoteRef], {
+        encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (_) {}
+    return { ok: true, sha, error: null, remoteRef };
+  } catch (err) {
+    return { ok: false, sha: null, error: err.message, remoteRef };
+  }
+}
+
+// ── Push with retry ────────────────────────────────────────
+
+/**
+ * Push the local data branch to the remote, retrying on rejection.
+ * On non-fast-forward rejection, fetches and merges before retrying.
+ * Returns { ok, error }.
+ */
+function pushDataBranch(remote, branchName, maxRetries, localMemPath, loadJsonFn, saveJsonFn) {
+  branchName = branchName || DATA_BRANCH;
+  remote = remote || getDefaultRemote();
+  maxRetries = maxRetries || 3;
+  if (!remote) return { ok: false, error: "no remote configured" };
+
+  const pushSpec = DATA_REF + ":" + DATA_REF;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      execFileSync("git", ["push", remote, pushSpec], {
+        timeout: 30000, stdio: ["pipe", "pipe", "pipe"],
+      });
+      return { ok: true, error: null };
+    } catch (err) {
+      if (attempt === maxRetries) {
+        return { ok: false, error: err.message };
+      }
+
+      // Fetch, merge, and re-commit so the next push attempt advances the ref
+      try {
+        const fetchResult = fetchDataBranch(remote, branchName);
+        if (fetchResult.ok && fetchResult.remoteRef && localMemPath) {
+          const remoteContent = readFileFromBranch(fetchResult.remoteRef, "sticky-note.json");
+          if (remoteContent) {
+            mergeAndSaveFromRemote(localMemPath, remoteContent, loadJsonFn, saveJsonFn);
+            const mergedContent = fs.readFileSync(localMemPath, "utf-8");
+            commitFilesToBranch(branchName, { "sticky-note.json": mergedContent });
+          }
+        }
+      } catch (_) {}
+
+      // Brief exponential backoff (busy-wait — synchronous context)
+      const end = Date.now() + Math.pow(2, attempt) * 300;
+      while (Date.now() < end) {}
+    }
+  }
+  return { ok: false, error: "max retries exceeded" };
+}
+
+// ── Thread merge ──────────────────────────────────────────
+
+function _mostRecentTimestamp(thread) {
+  return thread.last_activity_at || thread.updated_at || thread.created_at || "";
+}
+
+/**
+ * Merge two thread arrays, preferring the more-recently-active copy
+ * when both contain the same thread ID.
+ */
+function mergeThreadArrays(localThreads, remoteThreads) {
+  const merged = new Map();
+
+  for (const t of (localThreads || [])) {
+    if (t && t.id) merged.set(t.id, t);
+  }
+
+  for (const t of (remoteThreads || [])) {
+    if (!t || !t.id) continue;
+    const existing = merged.get(t.id);
+    if (!existing || _mostRecentTimestamp(t) > _mostRecentTimestamp(existing)) {
+      merged.set(t.id, t);
+    }
+  }
+
+  return Array.from(merged.values());
+}
+
+const EMPTY_MEMORY = { version: "2", project: "", threads: [] };
+
+/**
+ * Merge remote sticky-note.json content into the local memory file.
+ * Uses loadJsonFn/saveJsonFn when provided, otherwise reads/writes directly.
+ */
+function mergeAndSaveFromRemote(localMemPath, remoteContent, loadJsonFn, saveJsonFn) {
+  let remoteMemory;
+  try {
+    remoteMemory = JSON.parse(remoteContent);
+  } catch (_) {
+    return; // corrupt remote — skip
+  }
+
+  const localMemory = loadJsonFn
+    ? loadJsonFn(localMemPath, { ...EMPTY_MEMORY })
+    : { ...EMPTY_MEMORY };
+
+  const localThreads = Array.isArray(localMemory.threads) ? localMemory.threads.filter(Boolean) : [];
+  const remoteThreads = Array.isArray(remoteMemory.threads) ? remoteMemory.threads.filter(Boolean) : [];
+  localMemory.threads = mergeThreadArrays(localThreads, remoteThreads);
+
+  if (saveJsonFn) {
+    saveJsonFn(localMemPath, localMemory);
+  } else {
+    fs.mkdirSync(path.dirname(localMemPath), { recursive: true });
+    fs.writeFileSync(localMemPath, JSON.stringify(localMemory, null, 2) + "\n", "utf-8");
+  }
+}
+
+// ── Exports ───────────────────────────────────────────────
+
+module.exports = {
+  DATA_BRANCH,
+  DATA_REF,
+  getDefaultRemote,
+  readFileFromBranch,
+  commitFilesToBranch,
+  fetchDataBranch,
+  pushDataBranch,
+  mergeThreadArrays,
+  mergeAndSaveFromRemote,
+};

package/templates/hooks/session-end.js

@@ -29,9 +29,14 @@ try {
   _safeExit();
 }
 
+let dataBranch = null;
+try { dataBranch = require("./data-branch.js"); } catch (_) {}
+
 const {
   getMemoryPath,
   getConfigPath,
+  getAuditDir,
+  getPresenceDir,
   getUserPresencePath,
   getAllAuditPaths,
   loadJson,
@@ -724,6 +729,53 @@ function clearPresence(user) {
   }
 }
 
+// ── Data-branch commit/push ───────────────────────────────
+
+/** Collect files from a directory matching an extension into fileMap. */
+function _collectDirFiles(dir, ext, prefix, fileMap) {
+  if (!dir || !fs.existsSync(dir)) return;
+  for (const file of fs.readdirSync(dir)) {
+    if (file.endsWith(ext)) {
+      fileMap[prefix + file] = fs.readFileSync(path.join(dir, file), "utf-8");
+    }
+  }
+}
+
+function commitAndPushDataBranch() {
+  if (!dataBranch) return;
+  try {
+    const fileMap = {};
+    const memPath = getMemoryPath();
+    if (fs.existsSync(memPath)) {
+      fileMap["sticky-note.json"] = fs.readFileSync(memPath, "utf-8");
+    }
+
+    _collectDirFiles(getAuditDir(), ".jsonl", "audit/", fileMap);
+    _collectDirFiles(getPresenceDir(), ".json", "presence/", fileMap);
+
+    if (Object.keys(fileMap).length === 0) return;
+
+    dataBranch.commitFilesToBranch(dataBranch.DATA_BRANCH, fileMap);
+
+    const remote = dataBranch.getDefaultRemote();
+    if (remote) {
+      const pushResult = dataBranch.pushDataBranch(
+        remote, dataBranch.DATA_BRANCH, 3, getMemoryPath(), loadJson, saveJson
+      );
+      if (!pushResult.ok) {
+        process.stderr.write(
+          "[STICKY-NOTE] warning: failed to push data branch — " + pushResult.error + "\n" +
+          "[STICKY-NOTE] your data is safe locally in .git/sticky-note/\n"
+        );
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      "[STICKY-NOTE] warning: data branch sync failed — " + err.message + "\n"
+    );
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────
 
 function main() {
@@ -946,6 +998,9 @@ function main() {
     }
   }
 
+  // Commit current data to sticky-note/data branch and push
+  commitAndPushDataBranch();
+
   const fileCount = filesTouched.length;
   const commitCount = commitShas.length;
   const statusLabel = isCopilotCli ? "updated" : "closed";

package/templates/hooks/session-start.js

@@ -105,6 +105,10 @@ try {
 // session-start to run.
 try { utils.selfHealHookPaths && utils.selfHealHookPaths(); } catch (_) { /* non-fatal */ }
 
+// Non-fatal: data-branch sync is disabled if the module is missing.
+let dataBranch = null;
+try { dataBranch = require("./data-branch.js"); } catch (_) {}
+
 const {
   getMemoryPath,
   getConfigPath,
@@ -879,6 +883,47 @@ function ensureEnvironmentProvisioned() {
   if (debug) process.stderr.write("[sticky-note] environment provisioning complete\n");
 }
 
+// ── Data branch fetch-and-merge ───────────────────────────
+
+/**
+ * Fetches the remote sticky-note/data branch and merges into local memory.
+ * Also reads from the LOCAL data branch (fresh clones, offline, tests).
+ * Non-blocking — the session continues with local data on any failure.
+ */
+function fetchAndMergeDataBranch() {
+  if (!dataBranch) return;
+
+  const memPath = getMemoryPath();
+  const mergeFrom = (ref) => {
+    const content = dataBranch.readFileFromBranch(ref, "sticky-note.json");
+    if (content) {
+      dataBranch.mergeAndSaveFromRemote(memPath, content, loadJson, saveJson);
+    }
+  };
+
+  try {
+    const remote = dataBranch.getDefaultRemote();
+
+    if (remote) {
+      const fetchResult = dataBranch.fetchDataBranch(remote);
+      if (!fetchResult.ok) {
+        process.stderr.write(
+          "[STICKY-NOTE] offline — using local thread cache (" +
+            (fetchResult.error || "fetch failed") + ")\n"
+        );
+      } else if (fetchResult.remoteRef) {
+        mergeFrom(fetchResult.remoteRef);
+      }
+    }
+
+    mergeFrom(dataBranch.DATA_REF);
+  } catch (err) {
+    process.stderr.write(
+      "[STICKY-NOTE] offline — using local thread cache (" + err.message + ")\n"
+    );
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────
 
 function main() {
@@ -892,6 +937,9 @@ function main() {
     hookInput = {};
   }
 
+  // Fetch remote data branch and merge into local cache — before reading memory
+  fetchAndMergeDataBranch();
+
   let sessionId = getSessionId(hookInput);
   const aiTool = detectTool(hookInput);
   const isCopilotCli = aiTool === "copilot-cli" || process.argv.includes("--copilot-cli") || !!process.env.COPILOT_CLI;

package/templates/hooks/sticky-utils.js

@@ -38,8 +38,16 @@ const FILE_PATH_PATTERN = /[\w./\\-]+\.\w{1,10}/g;
 // ── Path helpers ──────────────────────────────────────────
 
 function _stickyDir() {
-  const scriptDir = path.dirname(path.resolve(__filename));
-  return path.join(scriptDir, "..", "..", ".sticky-note");
+  try {
+    const gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return path.resolve(gitDir, "sticky-note");
+  } catch (_) {
+    // Fallback for non-git environments (e.g., unit tests without git init)
+    const scriptDir = path.dirname(path.resolve(__filename));
+    return path.join(scriptDir, "..", "..", ".sticky-note");
+  }
 }
 
 // ── Error logging ─────────────────────────────────────────
@@ -81,9 +89,11 @@ function reportHookError(hookName, error, hint) {
 // the first time any hook (e.g. session-start, inject-context) successfully
 // loads, so the next session starts clean.
 //
-// The rewritten command always uses the relative form `node ".claude/hooks/<basename>"`,
-// matching what `templates/settings.json` ships today. We extract `<basename>`
-// from the existing command so we never invent hook scripts that don't exist.
+// The rewritten command uses `npx sticky-note run-hook <basename>` which walks
+// up the directory tree to find `.claude/hooks/<basename>.js`, so it works even
+// when Claude Code is launched from a subdirectory of the project root.
+// We extract `<basename>` from the existing command so we never invent hook
+// scripts that don't exist.
 //
 // Returns the list of (hookEvent, oldCommand, newCommand) tuples that were
 // rewritten, or [] if nothing was stale.
@@ -100,12 +110,15 @@ function selfHealHookPaths(settingsPath) {
     try { settings = JSON.parse(raw); } catch (_) { return result; }
     if (!settings || !settings.hooks) return result;
 
-    // Match the same shapes findStaleHookPaths() in bin/cli.js looks for:
-    // any absolute path inside the command string, or a $(git rev-parse ...)
-    // shell expansion that won't work on Windows / under Claude Code.
-    const STALE = /["'][A-Za-z]:[\\/]|["']\/(?:Users|home|root|tmp)\/|\$\(git rev-parse/;
+    // Two stale patterns:
+    // 1. Absolute paths (written by older sticky-note-cli or copied from another machine)
+    // 2. Old relative form `node ".claude/hooks/foo.js"` — fails when Claude Code
+    //    launches from a subdirectory, because the path resolves relative to the
+    //    launch cwd, not the directory containing .claude/settings.json.
+    const STALE_ABSOLUTE = /["'][A-Za-z]:[\\/]|["']\/(?:Users|home|root|tmp)\/|\$\(git rev-parse/;
+    const STALE_RELATIVE = /^node\s+["']\.claude[\\/]hooks[\\/][^"']+\.js["']\s*$/;
     // Match the script basename in either quoted or bare form.
-    const BASENAME = /([A-Za-z0-9_.-]+\.(?:js|sh|cjs|mjs))(?:["'`\s]|$)/;
+    const BASENAME = /([A-Za-z0-9_.-]+)\.(?:js|sh|cjs|mjs)(?:["'`\s]|$)/;
 
     let changed = false;
     for (const [event, entries] of Object.entries(settings.hooks)) {
@@ -113,11 +126,13 @@ function selfHealHookPaths(settingsPath) {
       for (const entry of entries) {
         for (const h of (entry && entry.hooks) || []) {
           const cmd = h && h.command;
-          if (typeof cmd !== "string" || !STALE.test(cmd)) continue;
+          if (typeof cmd !== "string") continue;
+          const isStale = STALE_ABSOLUTE.test(cmd) || STALE_RELATIVE.test(cmd);
+          if (!isStale) continue;
           const m = cmd.match(BASENAME);
           if (!m) continue;
           const basename = m[1];
-          const newCmd = `node ".claude/hooks/${basename}"`;
+          const newCmd = `npx sticky-note run-hook ${basename}`;
           result.push({ event, oldCommand: cmd, newCommand: newCmd });
           h.command = newCmd;
           changed = true;
@@ -130,10 +145,10 @@ function selfHealHookPaths(settingsPath) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
     try {
       const summary =
-        `[STICKY-NOTE] ⚠️  Detected ${result.length} stale absolute hook path(s) in ` +
+        `[STICKY-NOTE] ⚠️  Detected ${result.length} stale hook path(s) in ` +
         `${path.relative(process.cwd(), settingsPath) || settingsPath} — rewrote to ` +
-        `relative paths so hooks work on this machine. Commit the change to share ` +
-        `the fix with your team.`;
+        `"npx sticky-note run-hook <name>" so hooks work from any subdirectory. ` +
+        `Commit the change to share the fix with your team.`;
       process.stderr.write(summary + "\n");
       for (const { event, oldCommand, newCommand } of result.slice(0, 5)) {
         process.stderr.write(`[STICKY-NOTE]   ${event}: ${oldCommand} → ${newCommand}\n`);
@@ -1108,5 +1123,10 @@ module.exports = {
   rotateBackup,
   acquireLock,
   releaseLock,
+  // Cloud sync stubs (feature not yet implemented — on-stop.js uses these)
+  useCloud: () => false,
+  cloudReadThreads: async () => null,
+  cloudWriteThread: async () => {},
+  cloudAppendAudit: async () => {},
 };
 // tier1 test

package/templates/hooks.json

@@ -1,47 +1,47 @@
-{
-  "version": 1,
-  "hooks": {
-    "sessionStart": [
-      {
-        "type": "command",
-        "bash": "COPILOT_CLI=1 node \".claude/hooks/session-start.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/session-start.js\" --copilot-cli"
-      }
-    ],
-    "sessionEnd": [
-      {
-        "type": "command",
-        "bash": "COPILOT_CLI=1 node \".claude/hooks/session-end.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/session-end.js\" --copilot-cli"
-      }
-    ],
-    "userPromptSubmitted": [
-      {
-        "type": "command",
-        "bash": "COPILOT_CLI=1 node \".claude/hooks/inject-context.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/inject-context.js\" --copilot-cli"
-      }
-    ],
-    "preToolUse": [
-      {
-        "type": "command",
-        "bash": "COPILOT_CLI=1 node \".claude/hooks/pre-tool-use.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/pre-tool-use.js\" --copilot-cli"
-      }
-    ],
-    "postToolUse": [
-      {
-        "type": "command",
-        "bash": "COPILOT_CLI=1 node \".claude/hooks/track-work.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/track-work.js\" --copilot-cli"
-      }
-    ],
-    "errorOccurred": [
-      {
-        "type": "command",
-        "bash": "COPILOT_CLI=1 node \".claude/hooks/on-error.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/on-error.js\" --copilot-cli"
-      }
-    ]
-  }
-}
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/session-start.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/session-start.js\" --copilot-cli"
+      }
+    ],
+    "sessionEnd": [
+      {
+        "type": "command",
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/session-end.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/session-end.js\" --copilot-cli"
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/inject-context.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/inject-context.js\" --copilot-cli"
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/pre-tool-use.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/pre-tool-use.js\" --copilot-cli"
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/track-work.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/track-work.js\" --copilot-cli"
+      }
+    ],
+    "errorOccurred": [
+      {
+        "type": "command",
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/on-error.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/on-error.js\" --copilot-cli"
+      }
+    ]
+  }
+}

package/templates/settings.json

@@ -1,81 +1,81 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/session-start.js\""
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/session-end.js\""
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/inject-context.js\""
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/pre-tool-use.js\""
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/track-work.js\""
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/on-stop.js\""
-          }
-        ]
-      }
-    ],
-    "PostToolUseFailure": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \".claude/hooks/on-error.js\""
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook session-start"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook session-end"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook inject-context"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook pre-tool-use"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook track-work"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook on-stop"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx sticky-note run-hook on-error"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/sticky-note.json

@@ -1,5 +1,5 @@
-{
-  "version": "2",
-  "project": "",
-  "threads": []
-}
+{
+  "version": "2",
+  "project": "",
+  "threads": []
+}