arcroom 0.0.1-beta

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,46 @@
+# arcroom
+
+One shared memory for every coding agent on your team. When Claude Code, Codex, Cursor or OpenCode finishes a piece of work, the next agent, on any teammate's laptop, is handed the steps instead of redoing it. ArcRoom also blocks an agent's third identical tool call in a row and keeps a run going while your done-checks fail.
+
+## Quickstart
+
+Sign up at [arcroomai.com](https://www.arcroomai.com), then get a key: **Settings → API keys** (shown once). Then, in the project you work on:
+
+```
+npx arcroom init        # paste the key when asked (or set ARCROOM_API_KEY)
+npx arcroom whoami      # checks the key and the connection
+```
+
+Same memory for another agent in the same project:
+
+```
+npx arcroom init --agent codex     # or cursor, opencode (experimental)
+```
+
+`init` copies the plugin to `~/.arcroom/runtime` and adds its hooks and MCP server to the agent's settings. Nothing else needs to run.
+
+## What leaves your laptop
+
+Prompts (system reminders removed, secrets redacted, first 1,000 characters), file paths, search patterns, shell commands (first 1,000 characters), URLs and web queries, done-check results, git hashes of the files a turn touched, token counts, and what an agent saves on purpose with ArcRoom's tools. **Never file contents, tool output or edit diffs.** Secret files (`.env`, keys) are skipped.
+
+Every upload waits first in `~/.arcroom/spool.jsonl`, so you can read it before it goes. `arcroom off` stops ArcRoom for one repo on this laptop; `arcroom on` starts it again.
+
+## If the API is down
+
+Hooks never block a session. Memory lookup gives up after 3 seconds, the prompt goes through without it ("memory offline"), and lookups pause for a minute.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `arcroom init [--agent claude\|codex\|cursor\|opencode] [--project <id>]` | set up this machine and project |
+| `arcroom whoami` | who the key belongs to |
+| `arcroom doctor` | checks the key, the API, the hooks in this folder and the uploader, and prints the fix for each problem |
+| `arcroom off` / `arcroom on` | stop or restart ArcRoom for this repo |
+| `arcroom checks` / `arcroom checks approve <code>` | read and approve the done-checks in `.arcroom.json` |
+| `arcroom wrong [memo id] [reason]` | report a memory that was wrong |
+| `arcroom decide "<choice>" --why ...` | record a team decision |
+| `arcroom rule [--tag t] [--max-hits n] [--idle-days d]` | team rules for when memory expires |
+| `arcroom code [status\|sync\|on\|off]` | the code map |
+
+Docs: https://www.arcroomai.com/docs

package/dist/agents.js

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { sessionFile } from './loop.js';
+// Other coding agents on the same hook handler. The hook speaks Claude Code's payloads; this file translates.
+//   codex     same events, payloads and outputs as Claude Code; only its tool names differ (shell, apply_patch)
+//   cursor    camelCase events, conversation_id, workspace_roots; can't add context to a prompt, so recall is held
+//             back and handed over on the next tool call (postToolUse accepts additional_context)
+//   opencode  a plugin file (opencodePlugin) calls the hook with Claude Code payloads; tools are lowercase; recall is
+//             found on chat.message and added through experimental.chat.system.transform (an experimental OpenCode hook)
+// Sources (Oct 2026): cursor.com/docs/agent/hooks, learn.chatgpt.com/docs/hooks, opencode.ai/docs/plugins
+export const AGENTS = ['claude', 'codex', 'cursor', 'opencode'];
+const CURSOR_EVENTS = {
+    sessionStart: 'SessionStart',
+    beforeSubmitPrompt: 'UserPromptSubmit',
+    preToolUse: 'PreToolUse',
+    postToolUse: 'PostToolUse',
+    stop: 'Stop',
+    sessionEnd: 'SessionEnd',
+};
+export const CURSOR_HOOKS = Object.keys(CURSOR_EVENTS);
+/** Every file an apply_patch touches ("*** Update File: src/a.ts"). */
+export const patchFiles = (patch) => [...patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)].map((m) => m[1].trim());
+/**
+ * Any agent's tool call in Claude Code's terms (Read / Edit / Bash / Grep / Glob), so traces become the same steps.
+ * Returns the tool, its input, and any further files (a patch can touch several).
+ */
+export function normalizeTool(name, input) {
+    const n = String(name ?? '');
+    const i = input ?? {};
+    const file = i.file_path ?? i.filePath ?? i.target_file ?? i.path;
+    const command = Array.isArray(i.command) ? i.command.join(' ') : (i.command ?? i.cmd);
+    const patch = typeof i === 'string' ? i : (i.input ?? i.patch);
+    if (/apply_patch/i.test(n) && typeof patch === 'string') {
+        const [first, ...more] = patchFiles(patch);
+        return { tool: 'Edit', input: { file_path: first }, more };
+    }
+    if (/^(bash|shell|exec_command|run_terminal_cmd|terminal)$/i.test(n) && command)
+        return { tool: 'Bash', input: { command }, more: [] };
+    if (/^(read|read_file|view)$/i.test(n) && file)
+        return { tool: 'Read', input: { file_path: file }, more: [] };
+    if (/^(edit|write|multiedit|edit_file|write_file|search_replace|create_file)$/i.test(n) && file)
+        return { tool: /write|create/i.test(n) ? 'Write' : 'Edit', input: { file_path: file }, more: [] };
+    if (/^(grep|codebase_search|grep_search)$/i.test(n))
+        return { tool: 'Grep', input: { pattern: i.pattern ?? i.query, path: i.path }, more: [] };
+    if (/^(glob|list|list_dir|file_search)$/i.test(n))
+        return { tool: 'Glob', input: { pattern: i.pattern ?? i.query ?? i.path }, more: [] };
+    return { tool: n, input: i, more: [] };
+}
+/** One agent's hook payload as the Claude Code payload the hook handles (+ more_files for multi-file patches). */
+export function fromAgent(raw, agent) {
+    if (agent === 'claude')
+        return raw;
+    const r = { ...raw };
+    if (agent === 'cursor') {
+        r.hook_event_name = CURSOR_EVENTS[raw.hook_event_name] ?? raw.hook_event_name;
+        r.session_id = raw.session_id ?? raw.conversation_id;
+        r.cwd = raw.cwd ?? raw.workspace_roots?.[0];
+        r.tool_response = raw.tool_response ?? raw.tool_output;
+    }
+    if (r.tool_name !== undefined) {
+        const t = normalizeTool(r.tool_name, r.tool_input);
+        r.tool_name = t.tool;
+        r.tool_input = t.input;
+        if (t.more.length)
+            r.more_files = t.more;
+    }
+    return r;
+}
+/** The hook's Claude Code output in the agent's own terms. */
+export function toAgent(agent, event, out, session) {
+    if (agent !== 'cursor')
+        return out;
+    const context = out.hookSpecificOutput?.additionalContext;
+    const pending = sessionFile(session, '.pending-context');
+    switch (event) {
+        case 'SessionStart':
+            return context ? { additional_context: context } : {};
+        case 'UserPromptSubmit':
+            // Cursor can't add context here: keep it for the first tool call of this turn
+            if (context)
+                writeFileSync(pending, context);
+            return { continue: true };
+        case 'PostToolUse': {
+            if (!existsSync(pending))
+                return {};
+            const held = readFileSync(pending, 'utf8');
+            rmSync(pending, { force: true });
+            return { additional_context: held };
+        }
+        case 'PreToolUse': {
+            const deny = out.hookSpecificOutput?.permissionDecision === 'deny';
+            const reason = out.hookSpecificOutput?.permissionDecisionReason;
+            return deny ? { permission: 'deny', agent_message: reason, user_message: reason } : {};
+        }
+        case 'Stop':
+            if (out.decision === 'block')
+                return { followup_message: out.reason };
+            // Cursor shows the person nothing from a Stop hook: the note (e.g. done-checks not approved) waits for the next
+            // tool call, where the agent is asked to pass it on (N21)
+            if (out.systemMessage)
+                writeFileSync(pending, `ArcRoom note for the user (tell them): ${out.systemMessage}`);
+            return {};
+        default:
+            return {};
+    }
+}
+/** The OpenCode plugin: calls the ArcRoom hook with Claude Code payloads for each OpenCode event. */
+export function opencodePlugin(entry, project, node = process.execPath) {
+    const args = JSON.stringify([entry, 'hook', '--agent', 'opencode', ...(project ? ['--project', project] : [])]);
+    return `// ArcRoom for OpenCode (written by \`arcroom init --agent opencode\`; experimental).
+// Traces prompts and tool calls, hands over team memory for each prompt, blocks repeated calls, keeps the agent on
+// failing done-checks, and adds the last run's note.
+import { spawnSync } from 'node:child_process';
+
+const run = (payload) => {
+  const r = spawnSync(${JSON.stringify(node)}, ${args}, { input: JSON.stringify(payload), encoding: 'utf8' });
+  try { return JSON.parse(r.stdout || '{}'); } catch { return {}; }
+};
+
+export const ArcRoom = async ({ client, directory }) => {
+  const base = (id) => ({ session_id: id ?? 'opencode', cwd: directory });
+  const say = async (id, text) => {
+    if (id && text) await client.session.prompt({ path: { id }, body: { noReply: true, parts: [{ type: 'text', text }] } }).catch(() => {});
+  };
+  // recall for the prompt being answered: found when the message arrives, added to the system prompt for that turn
+  const pending = new Map();
+  return {
+    'chat.message': async (input, output) => {
+      const prompt = (output.parts ?? []).filter((p) => p.type === 'text' && !p.synthetic).map((p) => p.text).join('\\n');
+      if (!prompt) return;
+      const context = run({ ...base(input.sessionID), hook_event_name: 'UserPromptSubmit', prompt }).hookSpecificOutput?.additionalContext;
+      if (context) pending.set(input.sessionID, context);
+      else pending.delete(input.sessionID);
+    },
+    'experimental.chat.system.transform': async (input, output) => {
+      const context = input.sessionID && pending.get(input.sessionID);
+      if (context) output.system.push(context);
+    },
+    'tool.execute.before': async (input, output) => {
+      const out = run({ ...base(input.sessionID), hook_event_name: 'PreToolUse', tool_name: input.tool, tool_input: output.args, tool_use_id: input.callID });
+      if (out.hookSpecificOutput?.permissionDecision === 'deny') throw new Error(out.hookSpecificOutput.permissionDecisionReason);
+    },
+    'tool.execute.after': async (input, output) => {
+      run({ ...base(input.sessionID), hook_event_name: 'PostToolUse', tool_name: input.tool, tool_input: output.args, tool_response: output.output, tool_use_id: input.callID });
+    },
+    event: async ({ event }) => {
+      const id = event.properties?.sessionID ?? event.properties?.info?.id;
+      if (event.type === 'session.created') await say(id, run({ ...base(id), hook_event_name: 'SessionStart' }).hookSpecificOutput?.additionalContext);
+      if (event.type === 'session.idle') {
+        pending.delete(id); // the turn is over: the next prompt gets its own recall
+        const out = run({ ...base(id), hook_event_name: 'Stop' });
+        if (out.decision === 'block' && id) await client.session.prompt({ path: { id }, body: { parts: [{ type: 'text', text: out.reason }] } }).catch(() => {});
+      }
+      if (event.type === 'session.deleted') run({ ...base(id), hook_event_name: 'SessionEnd' });
+    },
+  };
+};
+`;
+}

package/dist/blind.js

@@ -0,0 +1,216 @@
+import { git as runGit } from './git.js';
+import { createCipheriv, createDecipheriv, createHmac, hkdfSync, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { ARCROOM_HOME } from './home.js';
+import { projectOf } from './session.js';
+const mac = (key, s) => createHmac('sha256', key).update(s).digest('hex');
+/** The three working keys and the fingerprint, all derived from the 32-byte team key. */
+export function keysFrom(root) {
+    const sub = (info) => Buffer.from(hkdfSync('sha256', root, Buffer.alloc(0), info, 32));
+    return { root, fp: mac(root, 'arcroom fingerprint').slice(0, 16), path: sub('arcroom paths'), hash: sub('arcroom hashes'), enc: sub('arcroom notes') };
+}
+export const newKeys = () => keysFrom(randomBytes(32));
+/** src/billing → k_7f3a…; the repo root stays "." (it says nothing). */
+export const scramblePath = (k, rel) => (rel === '' || rel === '.' ? '.' : `k_${mac(k.path, rel).slice(0, 24)}`);
+/** A git hash → c_…; the trailing * (uncommitted edits) is kept so "dirty" stays visible. */
+export const scrambleHash = (k, h) => (h.endsWith('*') ? `c_${mac(k.hash, h.slice(0, -1)).slice(0, 24)}*` : `c_${mac(k.hash, h).slice(0, 24)}`);
+/** A branch (b_) or repo (r_) name. */
+export const scrambleName = (k, kind, name) => `${kind}_${mac(k.path, `${kind}:${name}`).slice(0, 20)}`;
+export function encrypt(k, text) {
+    const iv = randomBytes(12);
+    const c = createCipheriv('aes-256-gcm', k.enc, iv);
+    const body = Buffer.concat([c.update(text, 'utf8'), c.final()]);
+    return `enc:v1:${Buffer.concat([iv, c.getAuthTag(), body]).toString('base64')}`;
+}
+/** The text, or undefined when it was sealed with another key. Plain text passes through. */
+export function decrypt(k, sealed) {
+    if (!sealed.startsWith('enc:v1:'))
+        return sealed;
+    try {
+        const b = Buffer.from(sealed.slice(7), 'base64');
+        const d = createDecipheriv('aes-256-gcm', k.enc, b.subarray(0, 12));
+        d.setAuthTag(b.subarray(12, 28));
+        return Buffer.concat([d.update(b.subarray(28)), d.final()]).toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The key as a code to pass to a teammate, or to keep as the recovery code. */
+export const keyCode = (k) => `arck1_${k.root.toString('base64url')}`;
+export function fromCode(code) {
+    const m = /^arck1_([A-Za-z0-9_-]{43})$/.exec(code.trim());
+    if (!m)
+        throw new Error('that is not an ArcRoom key code (it starts with arck1_)');
+    return keysFrom(Buffer.from(m[1], 'base64url'));
+}
+const keyFile = (fp) => join(ARCROOM_HOME, 'keys', `${fp}.key`);
+export function saveKey(k) {
+    mkdirSync(join(ARCROOM_HOME, 'keys'), { recursive: true });
+    writeFileSync(keyFile(k.fp), keyCode(k), { mode: 0o600 });
+    return keyFile(k.fp);
+}
+export function loadKey(fp) {
+    try {
+        const k = fromCode(readFileSync(keyFile(fp), 'utf8'));
+        return k.fp === fp ? k : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const git = (cwd, args) => {
+    const r = runGit(args, { cwd, timeout: 3000, maxBuffer: 64 * 1024 * 1024 });
+    return r.status === 0 ? r.stdout : undefined;
+};
+export const gitRoot = (cwd) => git(cwd, ['rev-parse', '--show-toplevel'])?.trim();
+/** The repo's Code wing setup: its mode from .arcroom.json, and in Blind mode the key when this laptop has it. */
+export function codeSetup(cwd) {
+    const root = cwd ? gitRoot(cwd) : undefined;
+    if (!root)
+        return undefined;
+    const cfg = readSetup(root);
+    const mode = cfg.code === 'blind' || cfg.code === 'off' ? cfg.code : 'standard';
+    // N12: a repo seen in Blind mode on this laptop stays Blind even if a commit takes it out of .arcroom.json;
+    // only the person here lowers it (arcroom code on|off)
+    const known = blindRepos()[root];
+    if (mode !== 'blind' && known)
+        return { root, mode: 'blind', fp: known, keys: loadKey(known) };
+    if (mode === 'blind' && typeof cfg.key === 'string' && known !== cfg.key)
+        rememberBlind(root, cfg.key);
+    return mode === 'blind' ? { root, mode, fp: cfg.key, keys: typeof cfg.key === 'string' ? loadKey(cfg.key) : undefined } : { root, mode };
+}
+/** Repos this laptop has seen in Blind mode: git root -> key fingerprint. */
+const BLIND_REPOS = join(ARCROOM_HOME, 'blind-repos.json');
+const blindRepos = () => {
+    try {
+        return JSON.parse(readFileSync(BLIND_REPOS, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+const saveBlindRepos = (repos) => {
+    mkdirSync(ARCROOM_HOME, { recursive: true, mode: 0o700 });
+    writeFileSync(BLIND_REPOS, JSON.stringify(repos, null, 2) + '\n', { mode: 0o600 });
+};
+const rememberBlind = (root, fp) => saveBlindRepos({ ...blindRepos(), [root]: fp });
+/** The person chose another mode for this repo (arcroom code on|off): it is no longer kept Blind. */
+export function forgetBlind(root) {
+    const { [root]: _gone, ...rest } = blindRepos();
+    saveBlindRepos(rest);
+}
+export function readSetup(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, '.arcroom.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeSetup(root, patch) {
+    const next = { ...readSetup(root), ...patch };
+    for (const [k, v] of Object.entries(next))
+        if (v === undefined)
+            delete next[k];
+    writeFileSync(join(root, '.arcroom.json'), JSON.stringify(next, null, 2) + '\n');
+}
+/** The repo id as the Room knows it: the git remote, scrambled in Blind mode. */
+export const repoKey = (s) => (s.mode === 'blind' && s.keys ? scrambleName(s.keys, 'r', projectOf(s.root)) : projectOf(s.root));
+export const branchKey = (s, branch) => (s.mode === 'blind' && s.keys ? scrambleName(s.keys, 'b', branch) : branch);
+export const nodeKey = (s, rel) => (s.mode === 'blind' && s.keys ? scramblePath(s.keys, rel) : rel || '.');
+export const hashKey = (s, h) => (s.mode === 'blind' && s.keys ? scrambleHash(s.keys, h) : h);
+/** A path (absolute, or relative to `from`) as a repo path: "src/billing/tax.ts", or undefined outside the repo. */
+export function repoPath(root, p, from = root) {
+    const rel = relative(root, isAbsolute(p) ? p : join(from, p)).replaceAll('\\', '/');
+    return rel.startsWith('..') || isAbsolute(rel) ? undefined : rel || '.';
+}
+/** Every scrambled id in this checkout → its path (files git knows about and their folders). */
+export function pathMap(s) {
+    const map = new Map();
+    if (s.mode !== 'blind' || !s.keys)
+        return map;
+    const files = (git(s.root, ['ls-files', '--cached', '--others', '--exclude-standard']) ?? '').split('\n').filter(Boolean);
+    for (const f of files) {
+        map.set(scramblePath(s.keys, f), f);
+        for (let d = f.lastIndexOf('/'); d > 0; d = f.lastIndexOf('/', d - 1))
+            map.set(scramblePath(s.keys, f.slice(0, d)), f.slice(0, d));
+    }
+    return map;
+}
+/** Text with every k_… id this checkout knows turned back into its path. */
+export const unscramble = (text, map) => (map.size ? text.replace(/k_[0-9a-f]{24}/g, (m) => map.get(m) ?? m) : text);
+/** Paths inside a shell command: the repo folder becomes ".", files and folders that exist are scrambled. */
+export function scrambleCommand(cmd, s, cwd) {
+    const rootFwd = s.root.replaceAll('\\', '/');
+    let out = cmd.split(s.root).join('.').split(rootFwd).join('.');
+    out = out.replace(/[\w@.\-/\\]+/g, (tok) => {
+        if (tok.length < 2 || !/[/\\.]/.test(tok) || /^\.+$/.test(tok))
+            return tok;
+        const rel = repoPath(s.root, tok, cwd);
+        if (!rel || rel === '.' || !existsSync(join(s.root, rel)))
+            return tok;
+        return scramblePath(s.keys, rel);
+    });
+    return out;
+}
+const CONTENT = ['content', 'old_string', 'new_string', 'edits', 'new_source'];
+/**
+ * One event as it may leave a Blind laptop: paths scrambled, file contents and tool output dropped, the folder the
+ * agent runs in replaced by ".". Without the key nothing path-like is sent at all.
+ */
+export function blindEvent(e, s) {
+    const k = s.keys;
+    const cwd = typeof e.cwd === 'string' ? e.cwd : s.root;
+    const path = (p) => {
+        if (typeof p !== 'string')
+            return p;
+        const rel = repoPath(s.root, p, cwd);
+        return !k ? 'hidden' : rel ? scramblePath(k, rel) : 'outside';
+    };
+    const d = { ...(e.data ?? {}) };
+    switch (e.type) {
+        case 'run.start':
+            d.project = k ? scrambleName(k, 'r', projectOf(s.root)) : undefined;
+            d.cwd = '.';
+            if (typeof d.branch === 'string')
+                d.branch = k ? scrambleName(k, 'b', d.branch) : undefined;
+            delete d.transcript;
+            break;
+        case 'tool.start': {
+            const i = { ...(typeof d.input === 'object' && d.input ? d.input : {}) };
+            for (const f of ['file_path', 'notebook_path', 'path'])
+                if (i[f] !== undefined)
+                    i[f] = path(i[f]);
+            if (typeof i.command === 'string')
+                i.command = k ? scrambleCommand(i.command, s, cwd) : 'hidden';
+            for (const f of CONTENT)
+                delete i[f];
+            d.input = i;
+            break;
+        }
+        case 'tool.end':
+            delete d.output; // file contents and command output never leave a Blind laptop
+            break;
+        case 'turn.end':
+            if (d.files && typeof d.files === 'object')
+                d.files = k
+                    ? Object.fromEntries(Object.entries(d.files).flatMap(([p, h]) => {
+                        const rel = repoPath(s.root, p, cwd);
+                        return rel ? [[scramblePath(k, rel), scrambleHash(k, String(h))]] : [];
+                    }))
+                    : undefined;
+            break;
+        case 'context':
+            delete d.text; // what ArcRoom handed over, already unscrambled on this laptop
+            break;
+        default:
+            if (String(e.type).startsWith('other.'))
+                return { ...e, cwd: undefined, data: {} };
+    }
+    for (const [key, v] of Object.entries(d))
+        if (v === undefined)
+            delete d[key];
+    return { ...e, cwd: undefined, data: d };
+}