paseo-room 0.3.0 → 0.4.0

package/README.md

@@ -45,6 +45,7 @@ interactive stdin/stdout/stderr, and targets exactly one selected agent and role
 | `--agent <codex\|claude\|pi>` | `codex` | Which coding agent to seat. Repeat the flag to combine agents. |
 | `--apply` | off | Actually write setup/remove changes; `auth login` does not use it. |
 | `--json` | off | One machine-readable document instead of text. |
+| `--no-claude-memory-contract` | off | Omit the role contract from Claude role `CLAUDE.md` files, leaving the room plugin as the only Claude carrier. Your global memory is still carried. `setup` only. |
 | `--room-home <path>` | `~/.paseo-room` | Where role homes are written. |
 | `--codex-home <path>` | `~/.codex` | Source Codex configuration. |
 | `--claude-home <path>` | `~/.claude` | Source Claude Code configuration. |
@@ -99,7 +100,7 @@ starts, its exit code is preserved; a signal is returned using the conventional
     auth.json                       # created and owned by Codex after role login, if file-backed
     AGENTS.md, skills, plugins, hooks.json              → symlinks into ~/.codex when present (Peer: see below)
   roles/claude/<role>/
-    CLAUDE.md                     # your global memory + role instructions
+    CLAUDE.md                     # your global memory + role instructions (contract omitted with --no-claude-memory-contract)
     settings.json                 # your settings.json + PASEO_ROOM_ROLE
     .claude.json                  # seeded once from yours, then owned by Claude
     .credentials.json                # created and owned by Claude after role login, if file-backed
@@ -258,6 +259,14 @@ the plugin is absent, disabled, failed, registered from another path, or drifted
 silently missing carrier is not a guarantee. The hook runs for newly created sessions;
 recreate an existing Claude session after setup or an update.
 
+`setup --no-claude-memory-contract` leaves the plugin as the only Claude carrier: each role
+`CLAUDE.md` then holds your global memory alone, and the file is not written at all when you
+have none. Only the contract is dropped, never your own memory, and an earlier generation of it
+is removed rather than left behind. The choice is recorded in `room.json`, so `verify` compares
+against it and rejects the flag itself; `setup` without the flag restores the fallback. Keep the
+fallback unless you have a reason not to: the plugin hook is verified, but whether a *resumed*
+session re-enters it is unproven, and `CLAUDE.md` is what covers that case.
+
 Pi providers use a strict command tail:
 
 ```text

package/dist/index.js

@@ -15,7 +15,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "paseo-room",
-      version: "0.3.0",
+      version: "0.4.0",
       description: "One CLI that configures Codex, Claude Code, and Pi role homes in $HOME and registers them with your local Paseo daemon.",
       keywords: [
         "paseo",
@@ -282,6 +282,7 @@ async function staleChildren(entry) {
 }
 async function current(entry) {
   const stat2 = await lstatOrAbsent(entry.path);
+  if (entry.kind === "absent") return stat2 ? "different" : "same";
   if (!stat2) return "absent";
   if (entry.kind === "dir") return stat2.isDirectory() ? "same" : "different";
   if (entry.kind === "managed-dir") {
@@ -301,9 +302,9 @@ async function planEntries(entries) {
   for (const entry of entries) {
     const state = await current(entry);
     operations.push({
-      action: state === "same" ? "noop" : state === "absent" ? "create" : "update",
+      action: state === "same" ? "noop" : entry.kind === "absent" ? "remove" : state === "absent" ? "create" : "update",
       // A managed directory is still a directory to everything that reports operations.
-      kind: entry.kind === "managed-dir" ? "dir" : entry.kind,
+      kind: entry.kind === "managed-dir" ? "dir" : entry.kind === "absent" ? "file" : entry.kind,
       target: entry.path
     });
   }
@@ -372,6 +373,12 @@ async function applyManagedDirectory(entry) {
     await rm(child, { force: true });
   }
 }
+async function removeManagedFile(path) {
+  const stat2 = await lstatOrAbsent(path);
+  if (!stat2) return;
+  if (!stat2.isFile()) refuse(path, "a regular file this room generated", stat2);
+  await rm(path, { force: true });
+}
 async function applyEntries(entries) {
   for (const entry of entries) {
     if (await current(entry) === "same") continue;
@@ -383,6 +390,10 @@ async function applyEntries(entries) {
       await applyManagedDirectory(entry);
       continue;
     }
+    if (entry.kind === "absent") {
+      await removeManagedFile(entry.path);
+      continue;
+    }
     await mkdir(dirname(entry.path), { recursive: true, mode: DIR_MODE });
     await assertReplaceable(entry);
     await replaceAtomically(entry);
@@ -461,12 +472,14 @@ var init_roles = __esm({
 // src/room.ts
 import { join as join3 } from "path";
 import { z } from "zod";
-function renderMarker(version, agents, roles, contract) {
+function renderMarker(version, agents, roles, contract, claudeMemoryContract) {
   return JSON.stringify({
     version,
     agents: [...agents],
     roles: [...roles],
-    ...contract === void 0 ? {} : { contract }
+    ...contract === void 0 ? {} : { contract },
+    // Written only when it differs from the default, so an unchanged room's marker is unchanged.
+    ...claudeMemoryContract === false ? { claudeMemoryContract: false } : {}
   }, null, 2) + "\n";
 }
 async function readMarker(layout) {
@@ -494,7 +507,13 @@ var init_room = __esm({
        * written before contract provenance existed has no digest, and such a marker must still
        * parse rather than look like a foreign file.
        */
-      contract: z.string().min(1).optional()
+      contract: z.string().min(1).optional(),
+      /**
+       * False when this room deliberately suppressed the role contract in Claude's `CLAUDE.md`,
+       * leaving the plugin as its only Claude carrier. Optional and defaulted to true so a room
+       * written before the option existed keeps parsing and keeps its current behaviour.
+       */
+      claudeMemoryContract: z.boolean().optional()
     });
   }
 });
@@ -1098,8 +1117,10 @@ function renderRoleState(source) {
   for (const key of SEEDED_KEYS) if (key in root) state[key] = root[key];
   return JSON.stringify(state, null, 2) + "\n";
 }
-function renderRoleMemory(source, role) {
+function renderRoleMemory(source, role, contract = true) {
   const operator = source?.trim();
+  if (!contract) return operator ? `${operator}
+` : void 0;
   return operator ? `${operator}
 
 ${renderInstructions(role)}` : renderInstructions(role);
@@ -1219,7 +1240,7 @@ var init_claude = __esm({
           "CronList"
         ]
       },
-      async build(layout, roles) {
+      async build(layout, roles, options = {}) {
         const home = layout.agentHome.claude;
         const binary = await which(layout.bin.claude, layout.searchPath);
         if (!binary) {
@@ -1272,7 +1293,9 @@ var init_claude = __esm({
             if (divergence) drift.push(mcpDriftCheck(role, target, statePath, divergence));
           }
           entries.push({ kind: "dir", path: target });
-          entries.push({ kind: "file", path: join7(target, "CLAUDE.md"), content: renderRoleMemory(memorySource, role) });
+          const memoryPath = join7(target, "CLAUDE.md");
+          const memory = renderRoleMemory(memorySource, role, options.memoryContract ?? true);
+          entries.push(memory === void 0 ? { kind: "absent", path: memoryPath } : { kind: "file", path: memoryPath, content: memory });
           entries.push({ kind: "file", path: join7(target, "settings.json"), content: renderRoleSettings(settingsSource, role, target) });
           entries.push({ kind: "file", path: statePath, content: renderRoleState(stateSource), once: true });
           entries.push(...await roleResourceEntries({ role, target, home, names: SHARED, shared, executable: EXECUTABLE }));
@@ -2157,7 +2180,7 @@ function roleProfiles(agent, roles) {
     notes: ROLE_NOTES[role]
   }));
 }
-async function buildDesired(layout, agents, roles) {
+async function buildDesired(layout, agents, roles, build = {}) {
   const entries = [
     { kind: "dir", path: layout.roomHome },
     { kind: "dir", path: sharedRoom(layout) },
@@ -2169,7 +2192,7 @@ async function buildDesired(layout, agents, roles) {
   const binaries = {};
   for (const id of agents) {
     const agent = AGENTS[id];
-    const plan = await agent.build(layout, roles);
+    const plan = await agent.build(layout, roles, build);
     entries.push(...plan.entries);
     checks.push(...plan.checks);
     const credentials = plan.credentials ?? [];
@@ -2206,7 +2229,7 @@ async function buildDesired(layout, agents, roles) {
   }
   const pluginPath = agents.includes("claude") ? claudeCarrierPluginDir(layout) : void 0;
   if (pluginPath !== void 0) entries.push(...claudeCarrierEntries(layout, roles));
-  entries.push({ kind: "file", path: join11(layout.roomHome, MARKER), content: renderMarker(package_default.version, agents, roles, contractDigest()) });
+  entries.push({ kind: "file", path: join11(layout.roomHome, MARKER), content: renderMarker(package_default.version, agents, roles, contractDigest(), markerMemoryContract(agents, build.memoryContract ?? true)) });
   return { entries, providers, profiles, checks, ...pluginPath === void 0 ? {} : { pluginPath } };
 }
 function contractProvenance(previous) {
@@ -2232,6 +2255,14 @@ function thinkingDiagnostics(live, desired) {
     `Choose a lower reasoning option for those seats in Paseo if you want the room's own defaults (${ROLE_THINKING.supervisor} for Supervisor, ${ROLE_THINKING.lead} for Lead and Peer).`
   )];
 }
+function fileDriftSummary(drifted) {
+  const removals = drifted.filter((operation) => operation.action === "remove").length;
+  const count = String(drifted.length);
+  const subject = drifted.length === 1 ? "managed role file is" : "managed role files are";
+  if (removals === 0) return `${count} ${subject} missing or outdated.`;
+  if (removals === drifted.length) return `${count} ${subject} present but suppressed by this room.`;
+  return `${count} ${subject} missing or outdated, and ${String(removals)} of them are present but suppressed by this room.`;
+}
 function fileDriftDetail(targets) {
   const catalogs = targets.filter((target) => target.endsWith(`${sep2}model-catalog.json`));
   if (catalogs.length === 0) return "";
@@ -2394,9 +2425,21 @@ async function reconcilePlugin(session, desired, plan, pending, expectedPath) {
   }
   return [pluginRuntimeCheck(plugin, expectedPath)];
 }
+function markerMemoryContract(agents, memoryContract) {
+  return agents.includes("claude") ? memoryContract : void 0;
+}
+function memoryContractDiagnostic(agents, memoryContract) {
+  if (memoryContract || !agents.includes("claude")) return [];
+  return [warn(
+    "claude.memory-contract",
+    "Claude role CLAUDE.md files carry your global memory only: the role contract was not written to them, so the trusted server plugin is this room's only Claude carrier. Only a newly created agent passes through its creation hook, and whether a resumed session re-enters that hook is unproven.",
+    "Drop --no-claude-memory-contract and run setup --apply to restore the file fallback."
+  )];
+}
 async function setup(options = {}) {
   const layout = resolveLayout(options, options.env);
   const agents = options.agents ?? ["codex"];
+  const memoryContract = options.claudeMemoryContract ?? true;
   const invalid = layoutChecks(layout, agents);
   if (invalid.length > 0) return failed("setup", invalid);
   const rootSafety = await roomPathSafety(layout, [], []);
@@ -2408,7 +2451,7 @@ async function setup(options = {}) {
   const compatibilityAgents = [.../* @__PURE__ */ new Set([...agents, ...previous?.agents ?? []])];
   const daemon = await checkDaemon(layout, options.env, minimumPaseoVersion(compatibilityAgents));
   if (!daemon.daemon) return failed("setup", daemon.checks);
-  const desired = await buildDesired(layout, agents, ROLES);
+  const desired = await buildDesired(layout, agents, ROLES, { memoryContract });
   const stale = await staleFrom(layout, previous, agents, ROLES);
   const retained = stale.retainedDirectories.length === 0 ? [] : [warn(
     "room.stale-role-homes-preserved",
@@ -2423,7 +2466,7 @@ async function setup(options = {}) {
     const { operations, liveProfiles } = plan;
     const pending = operations.filter((operation) => operation.action !== "noop");
     const pluginPreconditions = desired.pluginPath === void 0 ? plan.pluginChecks : [pluginsEnabledCheck(await session.pluginsEnabled()), ...plan.pluginChecks];
-    const preApplyDiagnostics = [...checks, ...pluginPreconditions, ...contractProvenance(previous), ...thinkingDiagnostics(liveProfiles, desired.profiles)];
+    const preApplyDiagnostics = [...checks, ...pluginPreconditions, ...memoryContractDiagnostic(agents, memoryContract), ...contractProvenance(previous), ...thinkingDiagnostics(liveProfiles, desired.profiles)];
     if (hasFailure(preApplyDiagnostics) || !options.apply) {
       return {
         command: "setup",
@@ -2451,13 +2494,15 @@ async function setup(options = {}) {
       version: package_default.version,
       agents: [...agents],
       roles: [...ROLES],
-      contract: contractDigest()
+      contract: contractDigest(),
+      ...markerMemoryContract(agents, memoryContract) === false ? { claudeMemoryContract: false } : {}
     };
     const appliedChecks = [
       ...checks,
       ...pluginPreconditions,
       ...pluginChecks,
       pass("room.applied", `Room ready at ${layout.roomHome} with ${String(ids.length)} Paseo providers.`),
+      ...memoryContractDiagnostic(agents, memoryContract),
       ...contractProvenance(appliedMarker),
       ...thinkingDiagnostics(appliedProfiles, desired.profiles)
     ];
@@ -2484,7 +2529,10 @@ async function verify(options = {}) {
   if (hasFailure(pathSafety)) return failed("verify", pathSafety);
   const daemon = await checkDaemon(layout, options.env, minimumPaseoVersion(marker.agents));
   if (!daemon.daemon) return failed("verify", daemon.checks);
-  const desired = await buildDesired(layout, marker.agents, marker.roles);
+  const desired = await buildDesired(layout, marker.agents, marker.roles, {
+    // The room's own recorded choice, so verify compares against what setup wrote.
+    memoryContract: marker.claudeMemoryContract ?? true
+  });
   const checks = [...daemon.checks, ...desired.checks];
   if (hasFailure(checks)) return failed("verify", checks);
   return withSession(daemon.daemon, async (session) => {
@@ -2504,11 +2552,12 @@ async function verify(options = {}) {
     ];
     const all = [
       ...checks,
-      files === 0 ? pass("room.files", "Every managed role file matches the current definition.") : fail("room.files", `${String(files)} managed role files are missing or outdated.${fileDriftDetail(driftedFiles.map((operation) => operation.target))}`, "Run: paseo-room setup --apply"),
+      files === 0 ? pass("room.files", "Every managed role file matches the current definition.") : fail("room.files", `${fileDriftSummary(driftedFiles)}${fileDriftDetail(driftedFiles.map((operation) => operation.target))}`, "Run: paseo-room setup --apply"),
       providers === 0 ? pass("room.providers", `All ${String(Object.keys(desired.providers).length)} Paseo providers are registered as expected.`) : fail("room.providers", `${String(providers)} Paseo providers are missing or differ.`, "Run: paseo-room setup --apply"),
       profiles === 0 ? pass("room.profiles", `All ${String(desired.profiles.length)} Paseo agent profiles are registered as expected.`) : fail("room.profiles", `${String(profiles)} Paseo agent profiles are missing or differ.`, "Run: paseo-room setup --apply"),
       ...pluginChecks,
       // Diagnostics last: a warning never precedes the failure it might be mistaken for.
+      ...memoryContractDiagnostic(marker.agents, marker.claudeMemoryContract ?? true),
       ...contractProvenance(marker),
       ...thinkingDiagnostics(liveProfiles, desired.profiles)
     ];
@@ -2658,12 +2707,25 @@ async function runWizard(prompts, emit, write, options = {}, onAction) {
     options: AGENT_IDS.map((value) => ({ value, label: AGENTS[value].label }))
   });
   if (typeof agents === "symbol" || agents.length === 0) return cancelled();
-  const preview = await setup({ ...options, agents });
+  let claudeMemoryContract = true;
+  if (agents.includes("claude")) {
+    const carrier = await prompts.select({
+      message: "Claude role contract carrier: the room plugin is always used. Also write the contract into each role CLAUDE.md?",
+      options: [
+        { value: "both", label: "Yes \u2014 keep it as a fallback (recommended; resume behaviour is unproven)" },
+        { value: "plugin", label: "No \u2014 plugin only; CLAUDE.md keeps your global memory alone" }
+      ]
+    });
+    if (typeof carrier === "symbol") return cancelled();
+    claudeMemoryContract = carrier === "both";
+  }
+  const setupOptions = { ...options, agents, claudeMemoryContract };
+  const preview = await setup(setupOptions);
   const status = emit(preview);
   if (preview.outcome !== "changes-planned") return status;
   const approved = await prompts.confirm({ message: "Apply these changes? Authentication will not be validated or started." });
   if (approved !== true) return cancelled();
-  return emit(await setup({ ...options, agents, apply: true }));
+  return emit(await setup({ ...setupOptions, apply: true }));
 }
 var terminalPrompts;
 var init_wizard = __esm({
@@ -2729,7 +2791,14 @@ function optionsFrom(raw, base) {
     if (typeof value === "string" && value.trim()) paths[flag] = value.trim();
   }
   const agents = Array.isArray(raw.agent) && raw.agent.length > 0 ? raw.agent : void 0;
-  return { ...base, ...paths, ...agents ? { agents } : {}, ...raw.apply === true ? { apply: true } : {} };
+  return {
+    ...base,
+    ...paths,
+    ...agents ? { agents } : {},
+    ...raw.apply === true ? { apply: true } : {},
+    // Commander defaults a --no- flag to true, so only an explicit opt-out is carried.
+    ...raw.claudeMemoryContract === false ? { claudeMemoryContract: false } : {}
+  };
 }
 function failedFromThrown(command, error) {
   if (error instanceof PromptAssetError) {
@@ -2779,7 +2848,7 @@ async function runCli(argv, output, context = {}) {
       return emit(failedFromThrown(wizardCommand, error));
     }
   }
-  const program = new Command().name("paseo-room").description("Configure Codex/Claude/Pi role homes in $HOME and register them with your local Paseo daemon.").version(package_default.version).usage("<setup|verify|remove> [options]\n       auth login <codex|claude|pi> <supervisor|lead|peer> [options]").argument("<command>", "setup | verify | remove | auth").argument("[command-arguments...]", "auth login <agent> <role>").option("--agent <agent>", "codex, claude, or pi; repeat to combine (default: codex)", collectAgent).option("--apply", "actually make the changes (default: dry run)").option("--json", "machine-readable output").option("--room-home <path>", "where role homes are written (default: ~/.paseo-room)").option("--codex-home <path>", "source Codex config (default: ~/.codex)").option("--claude-home <path>", "source Claude Code config (default: ~/.claude)").option("--pi-home <path>", "source Pi config (default: ~/.pi/agent)").option("--codex-bin <path>", "Codex executable (default: found on PATH)").option("--claude-bin <path>", "Claude Code executable (default: found on PATH)").option("--pi-bin <path>", "Pi executable (default: found on PATH)").option("--paseo-bin <path>", "Paseo executable (default: found on PATH)").configureOutput({ writeOut: (text) => {
+  const program = new Command().name("paseo-room").description("Configure Codex/Claude/Pi role homes in $HOME and register them with your local Paseo daemon.").version(package_default.version).usage("<setup|verify|remove> [options]\n       auth login <codex|claude|pi> <supervisor|lead|peer> [options]").argument("<command>", "setup | verify | remove | auth").argument("[command-arguments...]", "auth login <agent> <role>").option("--agent <agent>", "codex, claude, or pi; repeat to combine (default: codex)", collectAgent).option("--apply", "actually make the changes (default: dry run)").option("--json", "machine-readable output").option("--no-claude-memory-contract", "omit the role contract from Claude role CLAUDE.md files, leaving the room plugin as the only Claude carrier").option("--room-home <path>", "where role homes are written (default: ~/.paseo-room)").option("--codex-home <path>", "source Codex config (default: ~/.codex)").option("--claude-home <path>", "source Claude Code config (default: ~/.claude)").option("--pi-home <path>", "source Pi config (default: ~/.pi/agent)").option("--codex-bin <path>", "Codex executable (default: found on PATH)").option("--claude-bin <path>", "Claude Code executable (default: found on PATH)").option("--pi-bin <path>", "Pi executable (default: found on PATH)").option("--paseo-bin <path>", "Paseo executable (default: found on PATH)").configureOutput({ writeOut: (text) => {
     output.stdout(text);
   }, writeErr: (text) => {
     output.stderr(text);
@@ -2800,7 +2869,16 @@ async function runCli(argv, output, context = {}) {
     return 2;
   }
   try {
+    if (raw.claudeMemoryContract === false && (command === "verify" || command === "remove")) {
+      output.stderr(`paseo-room ${command}: --no-claude-memory-contract is a setup choice recorded in the room marker; ${command} reads it from there.
+`);
+      return 2;
+    }
     if (command === "auth") {
+      if (raw.claudeMemoryContract === false) {
+        output.stderr("paseo-room auth login only authenticates a role and does not use --no-claude-memory-contract.\n");
+        return 2;
+      }
       if (raw.apply === true) {
         output.stderr("paseo-room auth login is already explicit and does not use --apply.\n");
         return 2;