@systemdox/mcp-server 0.1.56 → 0.1.58

package/dist/setup-team.js

@@ -352,15 +352,41 @@ function readFrontmatter(text) {
   const m = BLOCK_RE.exec(text);
   if (!m) return void 0;
   const front = { shareFalse: false };
-  for (const line of m[1].split(/\r?\n/)) {
-    const kv = /^([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
+  const lines = m[1].split(/\r?\n/);
+  if (lines.some((l) => /^[ \t]*\t/.test(l) && l.trim())) return front;
+  let topType;
+  let topShare;
+  let nestedType;
+  let nestedShare;
+  let inMetadata = false;
+  let nestedIndent;
+  for (const line of lines) {
+    if (!line.trim() || /^[ \t]*#/.test(line)) continue;
+    const indent = /^ */.exec(line)[0].length;
+    if (indent === 0) {
+      inMetadata = /^metadata[ \t]*:[ \t]*(#.*)?$/.test(line);
+      nestedIndent = void 0;
+    }
+    const kv = /^ *([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
     if (!kv) continue;
     const raw = kv[2].replace(/[ \t]+#.*$/, "");
     const quoted = /^(["'])(.*)\1$/.exec(raw);
     const value = quoted ? quoted[2] : raw;
-    if (kv[1] === "type") front.type = value.trim().toLowerCase();
-    if (kv[1] === "share") front.shareFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
-  }
+    const isFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
+    if (indent === 0) {
+      if (kv[1] === "type") topType = value.trim().toLowerCase();
+      if (kv[1] === "share") topShare = isFalse;
+      continue;
+    }
+    if (!inMetadata) continue;
+    nestedIndent ??= indent;
+    if (indent !== nestedIndent) continue;
+    if (kv[1] === "type") nestedType = value.trim().toLowerCase();
+    if (kv[1] === "share") nestedShare = isFalse;
+  }
+  const type = topType ?? nestedType;
+  if (type !== void 0) front.type = type;
+  front.shareFalse = (topShare ?? nestedShare) === true;
   return front;
 }
 function isShareable(path, text) {
@@ -686,20 +712,52 @@ async function removeFolder(path) {
 
 // src/sync-memory.ts
 import { existsSync } from "fs";
-import { mkdir as mkdir2, readdir, readFile as readFile2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { appendFile, mkdir as mkdir2, open, readdir, readFile as readFile2, rename as rename2, rm as rm2, stat, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname2, join as join2, resolve } from "path";
+var HOOK_LOG_MAX_BYTES = 1024 * 1024;
 var SYNC_MEMORY_COMMAND = "npx -y @systemdox/mcp-server sync-memory";
 var SyncFailed = class extends Error {
 };
+var SyncStopped = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+  }
+  reason;
+};
+function failureReason(e) {
+  if (e instanceof SyncStopped) return e.reason;
+  const { status, code } = refusal(e);
+  if (status !== void 0) return code ? `SystemDox refused it, ${code}` : "SystemDox refused it";
+  const err = e;
+  const net = err?.cause?.code ?? err?.code ?? "";
+  if (e instanceof TypeError || /^(ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|UND_ERR)/.test(net)) {
+    return "SystemDox could not be reached";
+  }
+  return "it could not finish";
+}
+async function writeWhole(path, text) {
+  await mkdir2(dirname2(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile2(tmp, text, "utf8");
+    await rename2(tmp, path);
+  } catch (e) {
+    await rm2(tmp, { force: true });
+    throw e;
+  }
+}
 function refusal(e) {
   if (!(e instanceof Error)) return {};
   const { status, code } = e;
   return { status: typeof status === "number" ? status : void 0, code: typeof code === "string" ? code : void 0 };
 }
 var toPath = (root, rel) => join2(root, ...rel.split("/"));
+var LEFT_TEMP_RE = /\.\d+\.[a-z0-9]+\.tmp$/;
 async function readFolder(root) {
   const files = {};
   const names = /* @__PURE__ */ new Set();
+  const temps = [];
   async function walk(dir, prefix) {
     for (const e of await readdir(dir, { withFileTypes: true })) {
       if (e.name.startsWith(".")) continue;
@@ -707,12 +765,13 @@ async function readFolder(root) {
       if (e.isDirectory()) await walk(join2(dir, e.name), rel);
       else if (e.isFile()) {
         names.add(rel.toLowerCase());
+        if (LEFT_TEMP_RE.test(e.name)) temps.push(rel);
         if (e.name.endsWith(".md")) files[rel] = await readFile2(join2(dir, e.name), "utf8");
       }
     }
   }
   if (existsSync(root)) await walk(root, "");
-  return { files, names };
+  return { files, names, temps };
 }
 async function pullTeam(client, ws, project) {
   try {
@@ -761,7 +820,11 @@ var Report = class {
   deletedHere = /* @__PURE__ */ new Set();
   deletedFromTeam = /* @__PURE__ */ new Set();
   conflicts = [];
+  /** The conflict copies written this run, by name. */
+  copies = /* @__PURE__ */ new Set();
   skipped = /* @__PURE__ */ new Map();
+  /** Skipped files a sync in the member's terminal can send: held for a value, or for the vault. */
+  waiting = /* @__PURE__ */ new Set();
   people = [];
   toAnswer = /* @__PURE__ */ new Map();
   add(plan) {
@@ -769,12 +832,32 @@ var Report = class {
     plan.pushed.forEach((p) => this.pushed.add(p));
     plan.deletedHere.forEach((p) => this.deletedHere.add(p));
     plan.deletedFromTeam.forEach((p) => this.deletedFromTeam.add(p));
-    for (const c of plan.conflicts) this.conflicts.push(`${c.path}: the team's text; yours is beside it as ${c.copy}`);
+    for (const c of plan.conflicts) {
+      this.conflicts.push(`${c.path}: the team's text; yours is beside it as ${c.copy}`);
+      this.copies.add(c.copy);
+    }
     for (const line of plan.indexTeamLines) this.conflicts.push(`${INDEX_FILE}: your line was kept; the team's was: ${line}`);
   }
   skip(path, reason) {
     if (!this.skipped.has(path)) this.skipped.set(path, reason);
   }
+  /** Skipped, and waiting for the member at a terminal. */
+  wait(path, reason) {
+    this.skip(path, reason);
+    this.waiting.add(path);
+  }
+  summary(outcome, version, reason) {
+    return {
+      outcome,
+      ...reason ? { reason } : {},
+      version,
+      pulled: this.pulled.size,
+      pushed: this.pushed.size,
+      deleted: this.deletedHere.size + this.deletedFromTeam.size,
+      conflictCopies: [...this.copies].sort(),
+      waiting: [...this.waiting].sort()
+    };
+  }
   lines(summary, dryRun) {
     const out = [summary];
     const section = (title, items) => {
@@ -877,7 +960,7 @@ async function people(opts, ws, files, report, hint) {
           for (const path of g.files) {
             if (leftOut.has(path)) continue;
             current[path] = addShareFalse(current[path]);
-            await writeFile2(toPath(opts.dir, path), current[path], "utf8");
+            await writeWhole(toPath(opts.dir, path), current[path]);
             leftOut.add(path);
           }
           report.people.push({ kind: g.kind, answer: "left out (share: false)", files: g.files.length });
@@ -980,7 +1063,7 @@ async function people(opts, ws, files, report, hint) {
     const yes = /^y(es)?$/i.test((await ask(`Rewrite ${paths.length} file${paths.length === 1 ? "" : "s"} as shown? [y/N] `)).trim());
     if (yes) {
       for (const path of paths) {
-        await writeFile2(toPath(opts.dir, path), rewritten[path], "utf8");
+        await writeWhole(toPath(opts.dir, path), rewritten[path]);
         current[path] = rewritten[path];
       }
     }
@@ -995,11 +1078,11 @@ async function people(opts, ws, files, report, hint) {
     held.add(path);
     const keys = pending.filter((f) => f.kind !== HOME_PATH).map((f) => groupKey(f.kind, f.normalised));
     if (keys.some((k) => vaultDown.has(k))) {
-      report.skip(path, "the vault did not answer (SYD-K019) for a value in it; it syncs once the value is filed");
+      report.wait(path, "the vault did not answer (SYD-K019) for a value in it; it syncs once the value is filed");
     } else if (keys.some((k) => !answers.has(k))) {
-      report.skip(path, `it holds a value nobody has answered for: run \`${hint}\` in a terminal`);
+      report.wait(path, `it holds a value nobody has answered for: run \`${hint}\` in a terminal`);
     } else {
-      report.skip(path, `it holds a value to rewrite as its identifier or ~: run \`${hint}\` in a terminal`);
+      report.wait(path, `it holds a value to rewrite as its identifier or ~: run \`${hint}\` in a terminal`);
     }
   }
   for (const g of groups) {
@@ -1010,12 +1093,11 @@ async function people(opts, ws, files, report, hint) {
   }
   return { files: current, held, leftOut };
 }
+async function removeLeftTemps(dir, temps) {
+  for (const rel of temps) await rm2(toPath(dir, rel), { force: true });
+}
 async function applyPlan(dir, plan) {
-  for (const [path, text] of Object.entries(plan.writes)) {
-    const full = toPath(dir, path);
-    await mkdir2(dirname2(full), { recursive: true });
-    await writeFile2(full, text, "utf8");
-  }
+  for (const [path, text] of Object.entries(plan.writes)) await writeWhole(toPath(dir, path), text);
   for (const path of plan.deletes) await rm2(toPath(dir, path), { force: true });
 }
 var sameManifest = (a, b) => Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([p, h]) => b[p] === h);
@@ -1060,8 +1142,19 @@ async function syncMemory(opts) {
   const { client, out } = opts;
   const now = opts.now?.() ?? /* @__PURE__ */ new Date();
   try {
+    const checkDeadline = () => {
+      if (opts.deadline !== void 0 && Date.now() > opts.deadline) {
+        throw new SyncStopped("took too long", "Stopped: the sync's time ran out before anything more was written or sent.");
+      }
+    };
     const own = await client.getOwnTeamSetup();
     const ws = own.workspace;
+    if (opts.workspace && ws !== opts.workspace) {
+      throw new SyncStopped(
+        "the key is for another workspace",
+        `The key is for ${ws}, not ${opts.workspace}: nothing was synced. Set SYSTEMDOX_API_KEY to a key of ${opts.workspace}, or unset it.`
+      );
+    }
     const project = opts.project ?? (own.memory.length === 1 ? own.memory[0].project : void 0);
     if (!project) {
       throw new SyncFailed(
@@ -1075,6 +1168,12 @@ async function syncMemory(opts) {
     const date = localDate(now);
     const stored = (await readState(ws)).memory?.[project];
     let team = await pullTeam(client, ws, project);
+    if (opts.unattended && stored && !team.exists) {
+      throw new SyncStopped(
+        "the team memory could not be read",
+        `${ws}/${project} could not be read from SystemDox: nothing was changed. Run sync-memory in your terminal to see why.`
+      );
+    }
     let base = stored ? { version: stored.version, manifest: stored.manifest, exists: true } : { version: 0, manifest: {}, exists: false };
     const folder = await readFolder(dir);
     const shared = {};
@@ -1087,14 +1186,16 @@ async function syncMemory(opts) {
       } else shared[path] = text;
     }
     const importWrites = {};
-    if (opts.importDir) {
-      const other = await readFolder(resolve(opts.importDir));
-      const taken = new Set(folder.names);
+    const current = { ...folder.files };
+    const taken = new Set(folder.names);
+    for (const importDir of opts.importDirs ?? []) {
+      const other = await readFolder(resolve(importDir));
       for (const [path, text] of Object.entries(other.files).sort(([a], [b]) => a.localeCompare(b))) {
         if (!isShareable(path, text) || !isFilePath(path)) continue;
-        const here = folder.files[path];
+        const here = current[path];
         if (here === void 0) {
           shared[path] = text;
+          current[path] = text;
           importWrites[path] = text;
           taken.add(path.toLowerCase());
         } else if (here !== text) {
@@ -1102,16 +1203,14 @@ async function syncMemory(opts) {
           taken.add(copy.toLowerCase());
           importWrites[copy] = text;
           report.conflicts.push(`${path}: this folder's text; the imported one is beside it as ${copy}`);
+          report.copies.add(copy);
         }
       }
-      folder.names = taken;
-      if (!opts.dryRun) {
-        for (const [path, text] of Object.entries(importWrites)) {
-          const full = toPath(dir, path);
-          await mkdir2(dirname2(full), { recursive: true });
-          await writeFile2(full, text, "utf8");
-        }
-      }
+    }
+    folder.names = taken;
+    if (!opts.dryRun) {
+      checkDeadline();
+      for (const [path, text] of Object.entries(importWrites)) await writeWhole(toPath(dir, path), text);
     }
     const found = await people(run3, ws, shared, report, hint);
     for (const path of found.leftOut) {
@@ -1136,12 +1235,16 @@ async function syncMemory(opts) {
         );
         return 0;
       }
+      checkDeadline();
+      if (attempt === 1) await removeLeftTemps(dir, folder.temps);
       await applyPlan(dir, plan);
       let version = team.version;
       if (!sameManifest(plan.manifest, team.manifest)) {
+        checkDeadline();
         await upload(client, ws, project, plan, team.manifest, report);
       }
       if (!sameManifest(plan.manifest, team.manifest)) {
+        checkDeadline();
         try {
           version = (await client.pushMemoryVersion(ws, project, { baseVersion: team.version, manifest: plan.manifest })).version;
         } catch (e) {
@@ -1153,6 +1256,7 @@ async function syncMemory(opts) {
                 false
               )
             );
+            opts.summary?.(report.summary("moved-on", team.version, "moved on twice"));
             return 2;
           }
           base = team;
@@ -1177,33 +1281,45 @@ async function syncMemory(opts) {
           false
         )
       );
+      opts.summary?.(report.summary("synced", version));
       return 0;
     }
   } catch (e) {
     out(e.message);
+    opts.summary?.({
+      outcome: "failed",
+      reason: failureReason(e),
+      version: 0,
+      pulled: 0,
+      pushed: 0,
+      deleted: 0,
+      conflictCopies: [],
+      waiting: []
+    });
     return 1;
   }
 }
 
 // src/setup-team.ts
-var SETUP_USAGE = "Usage: systemdox-mcp-server setup [--project <name>] [--dir <checkout>] [--yes] [--overwrite]";
+var SETUP_USAGE = "Usage: systemdox-mcp-server setup [--project <name>] [--dir <checkout>] [--import <folder>]... [--yes] [--overwrite]";
 var HEADERS_HELPER = "npx -y @systemdox/mcp-server marketplace-auth";
 var SetupFailed = class extends Error {
 };
 function parseSetupArgs(argv) {
-  const args = { yes: false, overwrite: false };
+  const args = { yes: false, overwrite: false, importDirs: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--yes") args.yes = true;
     else if (a === "--overwrite") args.overwrite = true;
-    else if (a === "--project" || a === "--dir") {
+    else if (a === "--project" || a === "--dir" || a === "--import") {
       const value = argv[++i];
       if (!value || value.startsWith("--")) throw new Error(`${a} needs a value
 ${SETUP_USAGE}`);
       if (a === "--project") {
         if (!isWorkspace(value)) throw new Error(`${value} is not a project name (lower case letters, digits and -)`);
         args.project = value;
-      } else args.dir = value;
+      } else if (a === "--dir") args.dir = value;
+      else args.importDirs.push(value);
     } else throw new Error(`Unexpected argument ${a}
 ${SETUP_USAGE}`);
   }
@@ -1223,6 +1339,60 @@ async function claudeCodeVersion() {
     return void 0;
   }
 }
+async function gitTopFolder(dir) {
+  try {
+    const { stdout } = await run2("git", ["-C", dir, "rev-parse", "--show-toplevel"], { timeout: 1e4, windowsHide: true });
+    const top = stdout.trim();
+    return top ? resolve2(top) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function claudeMemoryFolder(path) {
+  return join3(homeDir(), ".claude", "projects", path.replace(/[^A-Za-z0-9]/g, "-"), "memory");
+}
+async function countMemoryFiles(folder) {
+  let count = 0;
+  async function walk(dir, prefix) {
+    let entries2;
+    try {
+      entries2 = await readdir2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries2) {
+      if (e.name.startsWith(".")) continue;
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) await walk(join3(dir, e.name), rel);
+      else if (e.isFile() && e.name.endsWith(".md")) {
+        try {
+          if (isShareable(rel, await readFile3(join3(dir, e.name), "utf8"))) count++;
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(folder, "");
+  return count;
+}
+async function memoryImports(checkout, teamFolder, named, gitTop = gitTopFolder) {
+  const candidates = [resolve2(checkout)];
+  const top = await gitTop(checkout);
+  if (top && !candidates.includes(top)) candidates.push(top);
+  const out = [];
+  for (const path of candidates) {
+    const folder = claudeMemoryFolder(path);
+    if (resolve2(folder) === resolve2(teamFolder)) continue;
+    const files = await countMemoryFiles(folder);
+    if (files) out.push({ folder, files, named: false });
+  }
+  for (const dir of named) {
+    const folder = resolve2(dir);
+    if (out.some((i) => i.folder === folder)) continue;
+    out.push({ folder, files: await countMemoryFiles(folder), named: true });
+  }
+  return out;
+}
 function parseVersion(text) {
   const m = text?.match(/(\d+)\.(\d+)\.(\d+)/);
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : void 0;
@@ -1264,9 +1434,9 @@ function skipValue(t, i) {
   while (i < t.length && !/[\s,}\]]/.test(t[i])) i++;
   return i;
 }
-function objectMembers(t, open) {
+function objectMembers(t, open2) {
   const members = [];
-  let i = skipSpace(t, open + 1);
+  let i = skipSpace(t, open2 + 1);
   if (t[i] === "}") return { members, close: i };
   for (; ; ) {
     i = skipSpace(t, i);
@@ -1293,13 +1463,13 @@ function setJsonMember(text, keys, value) {
   const eol = text.includes("\r\n") ? "\r\n" : "\n";
   const render = (v, indent) => compact ? JSON.stringify(v) : JSON.stringify(v, null, unit).split("\n").join(eol + indent);
   const nest = (from) => keys.slice(from).reduceRight((acc, k) => ({ [k]: acc }), value);
-  let open = skipSpace(text, 0);
+  let open2 = skipSpace(text, 0);
   for (let k = 0; k < keys.length; k++) {
-    const { members, close } = objectMembers(text, open);
+    const { members, close } = objectMembers(text, open2);
     const found = members.filter((m) => m.key === keys[k]).at(-1);
     if (found) {
       if (k < keys.length - 1 && text[found.valueStart] === "{") {
-        open = found.valueStart;
+        open2 = found.valueStart;
         continue;
       }
       return text.slice(0, found.valueStart) + render(nest(k + 1), lineIndent(text, found.keyStart)) + text.slice(found.valueEnd);
@@ -1308,16 +1478,16 @@ function setJsonMember(text, keys, value) {
     if (compact) {
       const member = `${name}:${render(nest(k + 1), "")}`;
       if (members.length) return text.slice(0, members.at(-1).valueEnd) + "," + member + text.slice(members.at(-1).valueEnd);
-      return text.slice(0, open + 1) + member + text.slice(close);
+      return text.slice(0, open2 + 1) + member + text.slice(close);
     }
     if (members.length) {
       const last = members.at(-1);
       const indent2 = lineIndent(text, last.keyStart);
       return text.slice(0, last.valueEnd) + `,${eol}${indent2}${name}: ${render(nest(k + 1), indent2)}` + text.slice(last.valueEnd);
     }
-    const outer = lineIndent(text, open);
+    const outer = lineIndent(text, open2);
     const indent = outer + unit;
-    return text.slice(0, open + 1) + `${eol}${indent}${name}: ${render(nest(k + 1), indent)}${eol}${outer}` + text.slice(close);
+    return text.slice(0, open2 + 1) + `${eol}${indent}${name}: ${render(nest(k + 1), indent)}${eol}${outer}` + text.slice(close);
   }
   return text;
 }
@@ -1363,9 +1533,9 @@ function importBlock(workspace, eol = "\n") {
 function withImportBlock(text, workspace) {
   const eol = text.includes("\r\n") ? "\r\n" : "\n";
   const block = importBlock(workspace, eol);
-  const open = `<!-- systemdox:${workspace} -->`;
+  const open2 = `<!-- systemdox:${workspace} -->`;
   const close = `<!-- /systemdox:${workspace} -->`;
-  const start = text.indexOf(open);
+  const start = text.indexOf(open2);
   const end = start >= 0 ? text.indexOf(close, start) : -1;
   if (start >= 0 && end >= 0) return text.slice(0, start) + block + text.slice(end + close.length);
   if (!text) return block + eol;
@@ -1489,6 +1659,15 @@ async function runTeamSetup(opts) {
       }
       items.push(item(`autoMemoryDirectory in ${localSettings}`, [memoryFolder]));
     }
+    const imports = project && memoryFolder && !state.memory?.[project] ? await memoryImports(checkout, memoryFolder, opts.importDirs ?? [], opts.gitTop) : [];
+    for (const i of imports) {
+      items.push(
+        item(
+          `${i.named ? "the folder --import names" : "the memories Claude Code kept for this checkout"}, imported into ${project} on its first sync`,
+          [`${i.folder}: ${i.files} file${i.files === 1 ? "" : "s"} to share`]
+        )
+      );
+    }
     const pending = items.filter((i) => !accepted.has(i.sha256));
     if (pending.length) {
       if (!canAsk) {
@@ -1558,6 +1737,7 @@ async function runTeamSetup(opts) {
       const code = await syncMemory({
         project,
         dryRun: false,
+        importDirs: imports.map((i) => i.folder),
         client,
         out: (...lines) => lines.forEach((l) => out(l)),
         ask: opts.terminal ? opts.ask : void 0,
@@ -1602,7 +1782,11 @@ export {
   HEADERS_HELPER,
   SETUP_USAGE,
   claudeCodeVersion,
+  claudeMemoryFolder,
+  countMemoryFiles,
+  gitTopFolder,
   importBlock,
+  memoryImports,
   parseSetupArgs,
   runTeamSetup,
   runTeamSetupCommand,

package/dist/sync-memory.d.ts

@@ -1,8 +1,9 @@
 /**
  * `systemdox-mcp-server sync-memory [--project <name>] [--dir <folder>]
- * [--import <folder>] [--dry-run]`, and the core of the local MCP tool
- * `sync_memory` (ADR-217 §2.3 with Amendment 2,
- * specs/changes/team-setup/contract.md "sync-memory and the MCP tool
+ * [--import <folder>]... [--dry-run]`, the core of the local MCP tool
+ * `sync_memory`, and `sync-memory --hook <workspace>`, the run the team plugin
+ * makes at the start and the end of a session (ADR-217 §2.3 with Amendments 2
+ * and 3, specs/changes/team-setup/contract.md "sync-memory and the MCP tool
  * sync_memory").
  *
  * 1. Pull: the team's latest version (`getMemory`), the base (state.json; with
@@ -17,18 +18,43 @@
  *    state.json takes the new base only after the push succeeds.
  *
  * Exit codes: 0 synced; 1 usage, no key, or the API refused; 2 the push was
- * refused twice on a stale base.
+ * refused twice on a stale base. `--hook` always exits 0: it syncs only the
+ * projects this computer synced before, asks nothing, prints one line per
+ * project (and a line for conflict copies and one for waiting files), appends
+ * the full report to the workspace's sync-memory.log, holds sync.lock, keeps
+ * to a 20-second budget and never holds a session up.
  */
 import { SystemDoxApiClient } from "./lib/api-client.js";
 import { type CommandIo } from "./lib/team-setup-files.js";
-export declare const SYNC_MEMORY_USAGE = "Usage: systemdox-mcp-server sync-memory [--project <name>] [--dir <folder>] [--import <folder>] [--dry-run]";
+export declare const SYNC_MEMORY_USAGE: string;
+/** The hook run's budget, lock staleness and log size (contract.md "--hook"). */
+export declare const HOOK_BUDGET_MS = 20000;
+export declare const HOOK_LOCK_STALE_MS = 60000;
+export declare const HOOK_LOG_MAX_BYTES: number;
 export declare const SYNC_MEMORY_COMMAND = "npx -y @systemdox/mcp-server sync-memory";
 export type SyncClient = Pick<SystemDoxApiClient, "getOwnTeamSetup" | "getMemory" | "readBlobs" | "findMissingBlobs" | "uploadBlobs" | "pushMemoryVersion" | "lookupValues" | "answerValues" | "fileMemoryPeople">;
 export interface SyncMemoryArgs {
     project?: string;
     dir?: string;
-    importDir?: string;
+    /** Folders to import on this sync, in order (`--import`, repeatable). */
+    importDirs?: string[];
     dryRun: boolean;
+    /** `--hook <workspace>`: the run the team plugin makes. */
+    hook?: string;
+}
+/** What a sync came to, for the hook run's one line (never a value). */
+export interface SyncSummary {
+    outcome: "synced" | "moved-on" | "failed";
+    /** For `failed`: why, in a few words. */
+    reason?: string;
+    version: number;
+    pulled: number;
+    pushed: number;
+    deleted: number;
+    /** The `.local-<date>.md` copies this run wrote. */
+    conflictCopies: string[];
+    /** The files skipped this run (waiting for the member, or refused). */
+    waiting: string[];
 }
 export interface SyncMemoryOptions extends SyncMemoryArgs {
     client: SyncClient;
@@ -38,6 +64,14 @@ export interface SyncMemoryOptions extends SyncMemoryArgs {
      * nothing is asked and nothing is rewritten. */
     ask?: (question: string) => Promise<string>;
     now?: () => Date;
+    /** Told what the sync came to, once, at its end. */
+    summary?: (summary: SyncSummary) => void;
+    /** The workspace the run is for (`--hook <workspace>`): a key for another one syncs nothing. */
+    workspace?: string;
+    /** Epoch ms: past it, nothing more is written or sent (the hook's budget). */
+    deadline?: number;
+    /** A hook run: a project the team no longer serves is left as it is. */
+    unattended?: boolean;
 }
 export declare function parseSyncMemoryArgs(argv: string[]): SyncMemoryArgs;
 /**
@@ -45,9 +79,27 @@ export declare function parseSyncMemoryArgs(argv: string[]): SyncMemoryArgs;
  * report goes to `opts.out`.
  */
 export declare function syncMemory(opts: SyncMemoryOptions): Promise<number>;
-/** The command: parse, find the key, sync. */
-export declare function runSyncMemory(argv: string[], io: CommandIo & {
+/** The lines the hook prints for one project (contract.md "--hook"): never a value. */
+export declare function hookLines(ws: string, project: string, folder: string, s: SyncSummary): string[];
+export interface HookIo extends CommandIo {
     client?: SyncClient;
-    ask?: (question: string) => Promise<string>;
     now?: () => Date;
+    /** The budget and the lock's staleness, for tests. */
+    budgetMs?: number;
+    lockStaleMs?: number;
+    /** Epoch ms the budget counts from: the process start for the CLI (npx and
+     * loading count against Claude Code's 30 seconds too), now otherwise. */
+    startedAt?: number;
+}
+/**
+ * `sync-memory --hook <workspace>`: the run the team plugin makes at the start
+ * and the end of a session. Every project this computer has synced before, in
+ * its default folder; never a first sync; one line per project on stdout (plus
+ * a line for conflict copies and one for waiting files), the full report in
+ * the log; one run at a time per workspace; a budget; exit 0 whatever happens.
+ */
+export declare function runHookSync(workspace: string, io: HookIo, env?: NodeJS.ProcessEnv): Promise<number>;
+/** The command: parse, find the key, sync. */
+export declare function runSyncMemory(argv: string[], io: HookIo & {
+    ask?: (question: string) => Promise<string>;
 }, env?: NodeJS.ProcessEnv): Promise<number>;