@hiveku-apps/sync 0.3.3 → 0.3.6

package/src/codex.mjs

@@ -17,8 +17,11 @@
  *                            the OLYMPUS_API_KEY env var). git-ignored.
  *   skill/command knowledge → .agents/skills/<name>/SKILL.md (repo-scoped; Codex
  *                            prompts are global-only + deprecated)
- *   permissions            → NO per-repo equivalent (Codex ignores approval/
- *                            sandbox keys in repo config) — stated in AGENTS.md.
+ *   permissions            → the hiveku server's per-tool approvals: a FIXED
+ *                            list of high-risk tools asks first
+ *                            (CODEX_PROMPT_TOOLS below), every other tool runs
+ *                            without asking. The safe-work rules are stated
+ *                            as instructions in AGENTS.md, for every tool.
  *
  * This complements the published Hiveku Codex plugin
  * (github.com/locus2012/hiveku-codex-plugin): the plugin ships the generic
@@ -29,27 +32,94 @@
  */
 
 import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 
+import { formatKey, readTomlDeclarations } from './toml.mjs';
 import { loadDotenv, safeSlug } from './util.mjs';
 
+/**
+ * The FIXED list of high-risk Hiveku tools that Codex asks about before
+ * running. It is the Hiveku Codex plugin's own prompt list, copied name for
+ * name (codex-prompt-tools.json says which release; 246 names at plugin
+ * 0.1.16). It includes hiveku_batch, because Codex asks by the name of the tool
+ * it calls and a batch carries other tools.
+ *
+ * It is a list of names, not a category. Every tool not on it runs without
+ * asking under the "approve" default, and that includes many deletes and sends
+ * (at MCP d4a73ba6d, for example crm_delete_contact, content_delete,
+ * assets_delete, survey_send and accounting_invoice_send). That is why
+ * AGENTS.md keeps the safe-work rules as instructions for every tool.
+ *
+ * A listed tool does not always ask either. Codex checks the run mode before
+ * it reads a tool's approval_mode (codex-mcp mcp_permission_prompt_is_auto_approved):
+ *   - approval policy "never" (what `codex exec` sets) with a read-only or
+ *     workspace-write sandbox: nobody can answer, so a listed call is
+ *     cancelled and the rest run;
+ *   - approval policy "never" with no sandbox or full disk write
+ *     (--dangerously-bypass-approvals-and-sandbox, i.e. --yolo, or
+ *     danger-full-access in `codex exec`): every prompt is skipped, these
+ *     included, and every Hiveku tool runs unattended.
+ *
+ * Why this folder has to write it: the folder's .codex/config.toml defines
+ * [mcp_servers.hiveku]. Codex 0.131 then drops the plugin's server of the same
+ * name (core/src/config/mod.rs: configured servers win, plugin servers are
+ * only `or_insert`ed) and takes each tool's approval mode from the config
+ * layers alone (core/src/mcp_tool_call.rs custom_mcp_tool_approval_mode:
+ * tools.<tool>.approval_mode, else default_tools_approval_mode; the plugin is
+ * read only when no config layer names the server). With only
+ * default_tools_approval_mode = "approve" here, every Hiveku tool ran without
+ * a prompt, with or without the plugin installed.
+ *
+ * Adding another prompt list (the unmerged Versions Wave 2 branch has
+ * RESTORE_TOOLS, for example): put its names into this one Set, so each tool
+ * still gets exactly one table. A second block of tables would define some
+ * tables twice (four of Wave 2's five names are already here), and that makes
+ * the whole config.toml invalid TOML.
+ *
+ * The user's own table wins: a listed tool that already has its own
+ * [mcp_servers.hiveku.tools.<tool>] table outside the managed block gets no
+ * table from us (userToolTables below), and writeCodexScaffold writes nothing
+ * when the block would still declare a table the file declares (blockConflict).
+ */
+export const CODEX_PROMPT_TOOLS = [
+  ...new Set(JSON.parse(readFileSync(new URL('./codex-prompt-tools.json', import.meta.url), 'utf8')).tools),
+];
+
+/** A TOML bare key when the name allows it, a quoted key otherwise. */
+function tomlKey(name) {
+  return /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
+}
+
 const AGENTS_BEGIN = '<!-- hiveku:begin -->';
 const AGENTS_END = '<!-- hiveku:end -->';
 const TOML_BEGIN = '# hiveku:begin (managed by hiveku-sync — do not edit inside)';
 const TOML_END = '# hiveku:end';
 const SKILL_STAMP = '<!-- generated-by: hiveku-sync (mirrored from account knowledge) -->';
 
-/** Replace (or append) the marked region inside existing content. */
-function upsertMarkedRegion(existing, begin, end, region) {
+/**
+ * Replace (or append) the marked region inside existing content. Also says
+ * where: `start` is the region's offset in `text`, and `replaced` the old
+ * region it replaced (null when it was appended).
+ */
+function placeMarkedRegion(existing, begin, end, region) {
   const b = existing.indexOf(begin);
   const e = existing.indexOf(end);
   if (b !== -1 && e !== -1 && e > b) {
-    return existing.slice(0, b) + region + existing.slice(e + end.length);
+    return {
+      text: existing.slice(0, b) + region + existing.slice(e + end.length),
+      start: b,
+      replaced: existing.slice(b, e + end.length),
+    };
   }
   const sep = existing.length && !existing.endsWith('\n\n') ? (existing.endsWith('\n') ? '\n' : '\n\n') : '';
-  return existing + sep + region + '\n';
+  return { text: existing + sep + region + '\n', start: existing.length + sep.length, replaced: null };
+}
+
+/** Replace (or append) the marked region inside existing content. */
+function upsertMarkedRegion(existing, begin, end, region) {
+  return placeMarkedRegion(existing, begin, end, region).text;
 }
 
 /** AGENTS.md — lean on purpose (Codex caps the instruction chain at ~32KiB). */
@@ -68,6 +138,11 @@ invoked by name) and this file.
 
 Non-negotiables (also in CLAUDE.md, restated because they are load-bearing):
 - **Verify identity before ANY write:** \`get_account_info\` must return THIS account.
+- **Context and memory.** Call \`account_context_get({ domain })\` first, before any copy, plan or analysis.
+  The account memory is read-only to you: owners edit it on the Hiveku dashboard, the local copy is
+  \`hiveku-data/account/ACCOUNT_MEMORY.md\` (never edit or upload it); suggest one line with \`account_memory_append\`.
+  Department memory is ONE document per department: read it (\`memory_list({ domain })\`), merge, then send the
+  whole document with \`memory_update({ memory_id, content })\`. Never create-then-overwrite on a 409.
 - **You are NOT the only writer.** Others push to these same projects while you work. Check what is
   current BEFORE you start (\`project_version_log\`) and AGAIN before you push (\`project_files_status\`
   — \`changed\` = they edited it, \`only_remote\` = they added files you lack). Before any tree-replace
@@ -82,34 +157,168 @@ Non-negotiables (also in CLAUDE.md, restated because they are load-bearing):
   attributed to the authenticated user (\`crm_list_users\`).
 - **Every completed task ends with an "Owner update"** — 2–4 calm, plain-language sentences a busy owner
   can skim: benefit first, no alarm vocabulary, accurate.
+- **Hiveku itself in your way?** A Hiveku tool still failing after one sensible retry → \`hiveku_report_issue\`;
+  a capability no tool offers (search \`hiveku_docs_search\` first) → \`hiveku_request_feature\`. No secrets or personal data.
+- **Tell the user only if it changes what they get:** one or two calm sentences — flagged to the Hiveku team (give the
+  ref), the team is quick to fix these, you'll let them know when it's sorted. No error codes, blame or promised times.
 - Video generation is paid + capped — \`marketing_generate_video\` with \`dry_run: true\` first.
 
 Discover tools with \`hiveku_docs_search\` / \`hiveku_docs_get\` and \`hiveku_playbooks_list\` /
-\`hiveku_playbook_get\`. Codex ignores repo-level approval/sandbox config, so the rules above are
-instructions, not enforced permissions — follow them.
+\`hiveku_playbook_get\`. Codex asks the user first only for a fixed list of ${CODEX_PROMPT_TOOLS.length} high-risk Hiveku
+tools (hiveku-sync's \`codex-prompt-tools.json\`, the Hiveku Codex plugin's list, written as per-tool
+prompts in \`.codex/config.toml\`). Every other Hiveku tool, including many deletes and sends, runs
+without asking, and some Codex modes (\`--yolo\`, \`danger-full-access\`) skip even those prompts. So
+never count on a prompt: the rules above are instructions, not enforced permissions — follow them for
+every tool.
 ${AGENTS_END}`;
 }
 
+/**
+ * The listed tools whose table the user's own settings already declare
+ * outside the managed block, in list order. Writing ours as well would
+ * declare that table twice, which TOML does not allow, so theirs wins.
+ *
+ * A tool's table is declared by a [mcp_servers.hiveku.tools.<tool>] or
+ * [[...]] header, however it is spelled (quoted parts, spaces), or by a key
+ * that sets it from a table above it: `<tool> = { ... }` or
+ * `<tool>.approval_mode = ...` under [mcp_servers.hiveku.tools]. A header one
+ * level deeper ([...tools.<tool>.x]) does not declare it, so it does not count.
+ * The file is read as Codex reads it (TOML 1.1 syntax, a byte-order mark at
+ * the start); a line that cannot be read is skipped.
+ *
+ * `withoutApprovalMode`: those whose own table sets no approval_mode, so
+ * Codex uses the server default ("approve") for them.
+ */
+function userToolTables(existing) {
+  const text = existing.replace(/\r\n/g, '\n');
+  const begin = text.indexOf(TOML_BEGIN);
+  const end = text.indexOf(TOML_END);
+  const blockEnd = begin !== -1 && end > begin ? end + TOML_END.length : -1;
+  const found = new Map(); // tool -> { declared, setsMode, notATable }
+  for (const statement of readTomlDeclarations(text).statements) {
+    if (blockEnd !== -1 && statement.pos >= begin && statement.pos < blockEnd) continue; // ours
+    const keyval = statement.type === 'keyval';
+    const key = keyval ? [...statement.header, ...statement.key] : statement.key;
+    if (key.length < 4 || key[0] !== 'mcp_servers' || key[1] !== 'hiveku' || key[2] !== 'tools') continue;
+    const entry = found.get(key[3]) ?? { declared: false, setsMode: false, notATable: false };
+    if (keyval ? statement.header.length < 4 : key.length === 4) entry.declared = true;
+    if (key[4] === 'approval_mode') entry.setsMode = true;
+    if (keyval && key.length === 4) {
+      if (statement.value !== 'table') entry.notATable = true;
+      else if (statement.tableKeys.includes('approval_mode')) entry.setsMode = true;
+    }
+    if (statement.type === 'arrayTable' && key.length === 4) entry.notATable = true;
+    found.set(key[3], entry);
+  }
+  const tools = CODEX_PROMPT_TOOLS.filter((tool) => found.get(tool)?.declared);
+  const withoutApprovalMode = tools.filter((tool) => !found.get(tool).setsMode && !found.get(tool).notATable);
+  return { tools, withoutApprovalMode };
+}
+
+/**
+ * Where the update would declare a table or key twice with one of the two in
+ * hiveku-sync's own block: the one way writing the block can break a file.
+ * Returns the first such place as { ours, line }, `ours` being the block's
+ * statement and `line` the other declaration's line in `existing` (the file
+ * as it is now), or null. A problem in the rest of the file is the user's own
+ * and not a reason to stop: the block is written as before.
+ *
+ * `placed` is placeMarkedRegion's result for `region` in `existing`.
+ */
+function blockConflict(existing, placed, region) {
+  const normalize = (text) => text.replace(/\r\n/g, '\n');
+  const start = normalize(placed.text.slice(0, placed.start)).length;
+  const end = start + region.length;
+  const inBlock = (statement) => statement !== null && statement.pos >= start && statement.pos < end;
+  // Text before the block is as it was; text after it moved by the old block's length less the new one's.
+  const before = normalize(existing);
+  const oldLength = placed.replaced === null ? 0 : normalize(placed.replaced).length;
+  const lineNow = (pos) => before.slice(0, pos < start ? pos : pos - end + start + oldLength).split('\n').length;
+  for (const { statement, prior } of readTomlDeclarations(normalize(placed.text)).conflicts) {
+    if (!inBlock(statement) && !inBlock(prior)) continue;
+    const theirs = inBlock(statement) ? prior : statement;
+    return { ours: inBlock(statement) ? statement : prior, line: theirs && !inBlock(theirs) ? lineNow(theirs.pos) : null };
+  }
+  return null;
+}
+
+/**
+ * The error for an update blockConflict refused. It names the block's own
+ * table or key (hiveku-sync's names) and only the line number of the user's,
+ * so nothing the user typed is repeated (a pasted secret, say).
+ */
+function refusalMessage(tomlPath, existing, { ours, line }) {
+  const name =
+    ours.type === 'keyval' ? `the key ${formatKey([...ours.header, ...ours.key])}` : `the table [${formatKey(ours.key)}]`;
+  const where = line ? `line ${line} of it` : 'a line of it';
+  const lines = [
+    `${tomlPath} was not updated: ${where} conflicts with ${name} in the hiveku-sync block, and a TOML file may declare each table and key only once. Nothing in the folder was changed.`,
+  ];
+  const begin = existing.indexOf(TOML_BEGIN);
+  if (begin !== -1 && existing.indexOf(TOML_BEGIN, begin + 1) !== -1) {
+    lines.push('The file has more than one "# hiveku:begin" line, so hiveku-sync could not tell which block is its own. Keep one block, then run `hiveku-sync codex` again.');
+  } else if (begin !== -1 && !(existing.indexOf(TOML_END) > begin)) {
+    lines.push('hiveku-sync could not find its own block to replace: the "# hiveku:begin" line has no "# hiveku:end" line after it. Put "# hiveku:end" back at the end of the block, then run `hiveku-sync codex` again.');
+  } else {
+    lines.push(`Remove or change ${line ? `line ${line}` : 'that line'}, then run \`hiveku-sync codex\` again.`);
+  }
+  return lines.join(' ');
+}
+
+/** A TOML basic string holding `value`: quotes, backslashes and control characters other than tab escaped. */
+function tomlString(value) {
+  const escaped = value.replace(/["\\\x00-\x08\x0a-\x1f\x7f]/g, (ch) =>
+    ch === '"' || ch === '\\' ? `\\${ch}` : `\\u${ch.charCodeAt(0).toString(16).toUpperCase().padStart(4, '0')}`,
+  );
+  return `"${escaped}"`;
+}
+
 /** The [mcp_servers.*] region for <folder>/.codex/config.toml. */
-function codexTomlRegion({ baseUrl, profile, apiKey }) {
+function codexTomlRegion({ baseUrl, profile, apiKey, userTables = [] }) {
   const base = baseUrl.replace(/\/+$/, '');
   const url = profile === 'full' ? `${base}/mcp` : `${base}/mcp?profile=${encodeURIComponent(profile)}`;
   // Prefer an inlined key (self-contained, no env setup needed; the file is
   // git-ignored). Fall back to the OLYMPUS_API_KEY env var when we can't
   // resolve a real key at scaffold time (e.g. `init` before the user pastes it).
+  //
+  // http_headers is Codex's map of static HTTP headers for a streamable HTTP
+  // MCP server (Codex config reference, "mcp_servers.<id>.http_headers"; the
+  // docs' example is `http_headers = { "X-Figma-Region" = "us-east-1" }`, next
+  // to bearer_token_env_var). TOML allows the key once per table, so the
+  // client label rides in the same inline table as an inlined key.
+  // X-Hiveku-Client: codex is what the MCP server's memory log shows as
+  // "via Codex"; it is a label, never authentication. The key and the URL come
+  // from .env, so they are escaped: a quote in either would otherwise end the
+  // string early and leave the block itself unreadable.
   const auth = apiKey
-    ? `http_headers = { "Authorization" = "Bearer ${apiKey}" }`
-    : `bearer_token_env_var = "OLYMPUS_API_KEY"`;
+    ? `http_headers = { "Authorization" = ${tomlString(`Bearer ${apiKey}`)}, "X-Hiveku-Client" = "codex" }`
+    : `bearer_token_env_var = "OLYMPUS_API_KEY"\nhttp_headers = { "X-Hiveku-Client" = "codex" }`;
   // default_tools_approval_mode = "approve": this folder exists so the agent
-  // can operate the account — per-call approval prompts would also auto-cancel
-  // every tool call in headless `codex exec` (CI/cron), this lane's core use.
-  // (Enum is approve|prompt; the docs' "auto" is not accepted by codex 0.131.)
+  // can operate the account — per-call approval prompts would also cancel
+  // every tool call in headless `codex exec` (CI/cron, this lane's core use)
+  // under a read-only or workspace-write sandbox.
+  // The per-tool tables after it override that default for CODEX_PROMPT_TOOLS
+  // (a tool's own approval_mode wins over the server default), so those ask
+  // first, exactly as they do under the Hiveku Codex plugin, in the modes where
+  // Codex asks at all (see CODEX_PROMPT_TOOLS). Each tool gets ONE table: a
+  // table defined twice makes the whole file invalid TOML, so merge any other
+  // prompt list into CODEX_PROMPT_TOOLS instead of adding tables here, and
+  // leave out the tools whose table the user declares outside this block
+  // (userTables): their own setting wins.
+  const skip = new Set(userTables);
+  const promptTables = CODEX_PROMPT_TOOLS.filter((tool) => !skip.has(tool))
+    .map((tool) => `[mcp_servers.hiveku.tools.${tomlKey(tool)}]\napproval_mode = "prompt"`)
+    .join('\n');
   return `${TOML_BEGIN}
 [mcp_servers.hiveku]
-url = "${url}"
+url = ${tomlString(url)}
 ${auth}
 default_tools_approval_mode = "approve"
 
+# Ask first: a fixed list of high-risk tools (the Hiveku Codex plugin's list).
+# Every other hiveku tool runs without asking.
+${promptTables}
+
 [mcp_servers.playwright]
 command = "npx"
 args = ["-y", "@playwright/mcp@latest"]
@@ -194,6 +403,10 @@ export async function mirrorKnowledgeToSkills(folder) {
  * .codex/config.toml (git-ignored) + mirror the account's knowledge to skills.
  * Resolves OLYMPUS_API_KEY from the folder's .env / process env to inline the
  * MCP auth when possible.
+ *
+ * Throws, with nothing in the folder written, when the hiveku-sync block would
+ * declare a table or key that the rest of config.toml also declares (see
+ * blockConflict). The updated file is checked in memory, before any write.
  */
 export async function writeCodexScaffold({ folder, slug, baseUrl, profile }) {
   // The FOLDER's .env wins over a process-level export: folder = tenant
@@ -205,6 +418,24 @@ export async function writeCodexScaffold({ folder, slug, baseUrl, profile }) {
     dotenv.OLYMPUS_API_KEY && dotenv.OLYMPUS_API_KEY !== 'olp_replace_me' ? dotenv.OLYMPUS_API_KEY : '';
   const apiKey = dotenvKey || (existsSync(join(folder, '.env')) ? '' : process.env.OLYMPUS_API_KEY || '');
 
+  // .codex/config.toml (marker-managed region; rest of user's config untouched).
+  // First, and checked in memory before anything is written, so that a refused
+  // update leaves the whole folder as it was (no .codex/ folder created either).
+  const tomlPath = join(folder, '.codex', 'config.toml');
+  let toml = '';
+  try {
+    toml = await readFile(tomlPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const userTables = userToolTables(toml);
+  const region = codexTomlRegion({ baseUrl, profile, apiKey, userTables: userTables.tools });
+  const placed = placeMarkedRegion(toml, TOML_BEGIN, TOML_END, region);
+  const conflict = blockConflict(toml, placed, region);
+  if (conflict) throw new Error(refusalMessage(tomlPath, toml, conflict));
+  await mkdir(dirname(tomlPath), { recursive: true });
+  await writeFile(tomlPath, placed.text, 'utf8');
+
   // AGENTS.md (marker-managed)
   const agentsPath = join(folder, 'AGENTS.md');
   let agents = '';
@@ -215,17 +446,6 @@ export async function writeCodexScaffold({ folder, slug, baseUrl, profile }) {
   }
   await writeFile(agentsPath, upsertMarkedRegion(agents, AGENTS_BEGIN, AGENTS_END, agentsMdRegion({ slug })), 'utf8');
 
-  // .codex/config.toml (marker-managed region; rest of user's config untouched)
-  const tomlPath = join(folder, '.codex', 'config.toml');
-  let toml = '';
-  try {
-    toml = await readFile(tomlPath, 'utf8');
-  } catch {
-    /* new */
-  }
-  await mkdir(dirname(tomlPath), { recursive: true });
-  await writeFile(tomlPath, upsertMarkedRegion(toml, TOML_BEGIN, TOML_END, codexTomlRegion({ baseUrl, profile, apiKey })), 'utf8');
-
   // Gitignore EVERY credential-bearing file this lane depends on — not just the
   // one we write. The retrofit reads .env for OLYMPUS_API_KEY to inline it, so a
   // folder that had no .gitignore would otherwise end up with one that ignores
@@ -236,7 +456,14 @@ export async function writeCodexScaffold({ folder, slug, baseUrl, profile }) {
   await appendGitignoreLines(folder, ['.codex/config.toml', '.env', '.env.local', '.hiveku/']);
 
   const skills = await mirrorKnowledgeToSkills(folder);
-  return { inlinedKey: !!apiKey, skillsMirrored: skills };
+  // userToolTables: listed tools left to the user's own table (the CLI names
+  // them); userTablesWithoutApprovalMode: those whose table sets no approval_mode.
+  return {
+    inlinedKey: !!apiKey,
+    skillsMirrored: skills,
+    userToolTables: userTables.tools,
+    userTablesWithoutApprovalMode: userTables.withoutApprovalMode,
+  };
 }
 
 /**

package/src/init.mjs

@@ -64,6 +64,9 @@ exposes the **${profile}** profile of Olympus tools.
 - \`rules/\` — synced agent rules
 - \`skills/\` — synced agent skills
 - \`commands/\`, \`agents/\`, \`identity/\` — other memory types
+- \`hiveku-data/account/ACCOUNT_MEMORY.md\` — the account memory (the business
+  facts every department agent reads), **read-only**: owners and admins edit it on
+  the Hiveku dashboard under Account memory, and nothing uploads this file
 - \`projects/<slug>/\` — coder project source pulled via \`hiveku-sync pull-project\`
 - \`.hiveku/manifest.json\` — memory last-sync record
 - \`.hiveku/projects.json\` — project ID ↔ folder mapping
@@ -81,6 +84,16 @@ changes (new skill, updated rule, etc.), call the corresponding MCP tool:
   commands, agents, identity entries
 - \`memory_delete\` — to remove an entry
 
+\`memory_update\` replaces the whole entry. Each department's memory is ONE
+document, so read the current one with \`memory_list({ domain })\`, merge your
+change into its full text, and send the whole document. Use \`memory_create\`
+only when none exists; a 409 means one does, so read and merge, never overwrite.
+
+The account memory is the exception: no tool sets it. Read it with
+\`account_memory_get\`, suggest one line with \`account_memory_append\` (an owner
+keeps or removes it), and tell the user that owners and admins edit it on the
+Hiveku dashboard under Account memory.
+
 Then run \`hiveku-sync pull\` to refresh the local copies.
 
 ## Coder projects (pull / status / push)
@@ -112,6 +125,14 @@ You can also ask Claude in this workspace to:
 Claude has the \`project_files_list\`, \`project_file_get\`, \`project_files_status\`,
 and \`project_commit\` MCP tools available under the **${profile}** profile.
 
+## When Hiveku itself gets in your way
+
+- A Hiveku tool still failing after one sensible retry → \`hiveku_report_issue\`; a capability
+  no tool offers (search \`hiveku_docs_search\` first) → \`hiveku_request_feature\`. No secrets or personal data.
+- Tell the user only if it changes what they get: one or two calm sentences — flagged to the Hiveku
+  team (give the ref), the team is quick to fix these, you'll let them know when it's sorted. No
+  error codes, blame or promised times.
+
 ## Tenant scope
 
 The API key in \`.env\` is **pinned to one Hiveku account**. You cannot switch

package/src/projects.mjs

@@ -19,6 +19,7 @@ import {
   writeFileAtomic,
   readJson,
 } from './util.mjs';
+import { isAccountMemoryPath } from './account-memory.mjs';
 // NOTE: push.mjs imports helpers from this module; the cycle is safe because
 // both sides reference the imports only inside functions (never at module eval).
 import { computePushPlan } from './push.mjs';
@@ -118,6 +119,12 @@ async function listAllRemoteFiles(client, projectId) {
   return all;
 }
 
+/**
+ * Every local file push, commit and status consider. The pulled account memory
+ * (hiveku-data/account/) is left out wherever it sits: it is a read-only copy
+ * that owners edit on the dashboard, and nothing may upload it, not even when
+ * an account folder and a project folder are the same folder.
+ */
 export async function walkLocalFiles(rootDir) {
   const out = [];
   async function recurse(dir) {
@@ -131,6 +138,7 @@ export async function walkLocalFiles(rootDir) {
       if (entry.name.startsWith('.')) continue;
       if (IGNORE_DIRS.has(entry.name)) continue;
       const full = join(dir, entry.name);
+      if (isAccountMemoryPath(relative(rootDir, full).split(sep).join('/'))) continue;
       if (entry.isDirectory()) {
         await recurse(full);
       } else if (entry.isFile()) {

package/src/pull.mjs

@@ -2,6 +2,11 @@
  * `hiveku-sync pull` — fetches memory/rules/skills via the MCP memory_list tool
  * and writes them as local .md files under the current folder.
  *
+ * The account memory (domains `account` and `account-suggestions`) is not a
+ * knowledge entry: it is classified explicitly, never written under memory/,
+ * and pulled once from account_memory_get into a read-only
+ * hiveku-data/account/ACCOUNT_MEMORY.md (see account-memory.mjs).
+ *
  * Safety: refuses to overwrite when the .env API key no longer matches the
  * manifest's recorded key preview (prevents pulling Account A's data into a
  * folder previously synced for Account B — the 2026-05-11 cross-tenant bug
@@ -22,6 +27,15 @@ import {
   TYPE_TO_FOLDER,
   SUPPORTED_TYPES,
 } from './util.mjs';
+import {
+  ACCOUNT_MEMORY_FILE,
+  classifyMemoryEntry,
+  ACCOUNT_MEMORY_TOOL,
+  normalizeAccountMemory,
+  renderAccountMemoryFile,
+  resolveAccountId,
+  writeReadOnly,
+} from './account-memory.mjs';
 
 const MANIFEST_PATH = '.hiveku/manifest.json';
 
@@ -58,7 +72,19 @@ function renderEntry(entry, type) {
   return `${frontmatter}${body}`;
 }
 
-export async function runPull({ baseDir = process.cwd(), profile } = {}) {
+/**
+ * Write hiveku-data/account/ACCOUNT_MEMORY.md from account_memory_get, read-only.
+ * Returns { file, version, suggestions, accountId }, or throws (the caller
+ * records the error and keeps the previous copy).
+ */
+export async function pullAccountMemory({ client, baseDir, fetchedAt = new Date().toISOString() }) {
+  const memory = normalizeAccountMemory(await client.callToolJson(ACCOUNT_MEMORY_TOOL, {}));
+  const accountId = await resolveAccountId(client);
+  await writeReadOnly(join(baseDir, ACCOUNT_MEMORY_FILE), renderAccountMemoryFile({ memory, accountId, fetchedAt }));
+  return { file: ACCOUNT_MEMORY_FILE, version: memory.version, suggestions: memory.suggestions.length, accountId };
+}
+
+export async function runPull({ baseDir = process.cwd(), profile, client: injectedClient } = {}) {
   const envPath = join(baseDir, '.env');
   const dotenv = await loadDotenv(envPath);
   const apiKey = readEnv(process.env, dotenv, 'OLYMPUS_API_KEY');
@@ -88,10 +114,10 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
     );
   }
 
-  const client = new HivekuMcpClient({ baseUrl, apiKey, profile: activeProfile });
-  await client.initialize();
+  const client = injectedClient || new HivekuMcpClient({ baseUrl, apiKey, profile: activeProfile });
+  if (!injectedClient) await client.initialize();
 
-  const summary = { total: 0, by_type: {}, errors: [] };
+  const summary = { total: 0, by_type: {}, errors: [], account_memory: null, account_rows_skipped: 0 };
   const writtenFiles = new Set();
 
   for (const type of SUPPORTED_TYPES) {
@@ -103,10 +129,19 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
       summary.errors.push({ type, message: err.message });
       continue;
     }
-    summary.by_type[type] = entries.length;
-    summary.total += entries.length;
-
+    // The two account-memory domains are not knowledge entries: an older
+    // server still lists them, and they would land as memory/account.md and
+    // memory/account-suggestions.md (raw JSON Lines) looking editable. They
+    // are written once, read-only, from account_memory_get below.
+    const knowledge = [];
     for (const entry of entries) {
+      if (classifyMemoryEntry(entry, folder).kind === 'knowledge') knowledge.push(entry);
+      else summary.account_rows_skipped += 1;
+    }
+    summary.by_type[type] = knowledge.length;
+    summary.total += knowledge.length;
+
+    for (const entry of knowledge) {
       const filename = entryFilename(entry);
       const fullPath = join(baseDir, folder, filename);
       await writeFileAtomic(fullPath, renderEntry(entry, type));
@@ -114,6 +149,17 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
     }
   }
 
+  // The account memory: one read-only file, never uploaded by anything here.
+  // A failure keeps the previous copy (and its manifest line), so it is not
+  // reported as removed upstream.
+  try {
+    summary.account_memory = await pullAccountMemory({ client, baseDir });
+    writtenFiles.add(ACCOUNT_MEMORY_FILE);
+  } catch (err) {
+    summary.errors.push({ type: 'account memory', message: err.message });
+    if ((manifest?.files ?? []).includes(ACCOUNT_MEMORY_FILE)) writtenFiles.add(ACCOUNT_MEMORY_FILE);
+  }
+
   // v1: don't delete stale files; just record them in the manifest so the
   // user can prune manually if they want. Avoids losing local edits.
   const previouslySeen = new Set(manifest?.files ?? []);
@@ -129,6 +175,8 @@ export async function runPull({ baseDir = process.cwd(), profile } = {}) {
         last_sync_at: new Date().toISOString(),
         counts: summary.by_type,
         files: [...writtenFiles].sort(),
+        // Pulled for reading only: edited on the dashboard, never uploaded.
+        read_only: [ACCOUNT_MEMORY_FILE],
         removed_remotely_since_last_sync: removedRemotely,
       },
       null,