@jossuealcala/madre 0.3.0 → 0.3.2

package/src/room.mjs

@@ -21,6 +21,9 @@ import { parseDirectives } from './directives.mjs';
 import { isValidModelName } from './models.mjs';
 import { MODES, SCOPES, SCOPE_LABELS, capabilitySummary, normalizeMode, resolveScopes } from './capabilities.mjs';
 import { createLease, diffSnapshots, snapshot } from './lease.mjs';
+import { stat as statFile } from 'node:fs/promises';
+import { basename as baseName, join as joinPath } from 'node:path';
+import { contentTypeFor } from './files.mjs';
 import { imageStudioFor } from './image-studio.mjs';
 import { CAPABILITIES, imageModuleState } from './capabilities.mjs';
 import { resolveReferences } from './files.mjs';
@@ -80,6 +83,7 @@ export class Room {
   #attachments = new Attachments();
   #scopeConfig = {};
   #delegation;
+  #privacy = null;
   #maxPlanSteps;
   #maxConcurrentTurns;
   #planMaxAgeMs;
@@ -96,6 +100,7 @@ export class Room {
     distill = {},
     memoryServer = null,
     mother = null,
+    privacy = null,
     historicalEvents = [],
     invokers = defaultInvokers,
     agentTimeouts = {},
@@ -114,6 +119,7 @@ export class Room {
     this.#recallShare = Math.min(0.6, Math.max(0, Number.isFinite(recallShare) ? recallShare : 0.3));
     this.#memoryServer = memoryServer;
     this.#mother = mother;
+    this.#privacy = privacy;
     this.#invokers = invokers;
     this.#agentTimeouts = agentTimeouts;
     this.#maxMessageChars = maxMessageChars;
@@ -190,8 +196,7 @@ export class Room {
     }
     const scopes = this.scopesFor(step.agent);
     const enabled = Object.fromEntries(SCOPES.map((scope) => [scope, scopes[scope].enabled && scopes[scope].wired]));
-    const lease = await createLease({ projectRoot: this.#projectRoot, leaseId: randomUUID() });
-    lease.messageId = parentMessageId;
+    const lease = await this.#projectLease({ leaseId: randomUUID(), messageId: parentMessageId });
     lease.scopes = decision.decision === 'plan' ? Object.fromEntries(SCOPES.map((scope) => [scope, true])) : enabled;
     await this.#emit('lease.granted', {
       escalated: decision.decision,
@@ -199,6 +204,7 @@ export class Room {
       messageId: parentMessageId,
       agent: step.agent,
       outDir: lease.relativeDir,
+      scratchDir: lease.scratchDir,
       scopes: SCOPES.filter((scope) => enabled[scope]),
       unavailable: SCOPES.filter((scope) => !scopes[scope].capable).map((scope) => SCOPE_LABELS[scope]),
       planId,
@@ -226,8 +232,8 @@ export class Room {
   }
   embedNow() { return this.#vectors.runNow(); }
 
-  #contextFor(priorEvents, { messageId, text }) {
-    return contextFor({ memory: this.#memory, priorEvents, messageId, text, contextMaxChars: this.#contextMaxChars, recallShare: this.#recallShare, remember: (events) => this.#remember(events) });
+  #contextFor(priorEvents, { messageId, text, omitSynthetic = false }) {
+    return contextFor({ memory: this.#memory, priorEvents, messageId, text, contextMaxChars: this.#contextMaxChars, recallShare: this.#recallShare, remember: (events) => this.#remember(events), omitSynthetic });
   }
 
   // The human tunes the archive from MU/TH/UR; changes apply to the next run.
@@ -293,6 +299,44 @@ export class Room {
     return { stats: this.memoryStats(), memories: this.#memory.memories({ limit: 500 }), links: this.#memory.memoryLinks() };
   }
 
+  /* ---------- privacy: terms that never travel through the room ---------- */
+
+  privacy() { return this.#privacy; }
+  setPrivacy(terms, marker) {
+    if (!this.#privacy) return null;
+    this.#privacy.set(terms, marker);
+    return this.#privacy;
+  }
+  privacyExposure(events = []) {
+    if (!this.#privacy?.enabled) return { events: 0, entries: 0, memories: 0 };
+    let hits = 0;
+    for (const event of events) if (this.#privacy.redactDeep(event.payload).hits) hits += 1;
+    return { events: hits, ...(this.#memory ? this.#memory.exposure() : { entries: 0, memories: 0 }) };
+  }
+
+  // The human's hand on the ledger: every private term already recorded becomes the marker,
+  // in the log, the index and the notes. Recorded like anything else the human does.
+  async purgePrivate() {
+    if (!this.#privacy?.enabled) return { events: 0, entries: 0, memories: 0 };
+    const privacy = this.#privacy;
+    const rewritten = await this.#store.rewrite((event) => {
+      const { value, hits } = privacy.redactDeep(event.payload);
+      return hits ? { ...event, payload: value } : event;
+    });
+    const memory = this.#memory ? this.#memory.purge() : { entries: 0, memories: 0 };
+    if (this.#memory) this.#vectors.schedule();
+    const result = { events: rewritten.changed, ...memory };
+    await this.#emit('privacy.purged', { ...result, terms: privacy.terms.length });
+    return result;
+  }
+
+  // The human's verdict on a reply: good, bad, or cleared. The dataset listens.
+  async rateMessage(messageId, rating) {
+    if (typeof messageId !== 'string' || !messageId.trim()) throw new Error('Which reply? Give its messageId.');
+    if (!['good', 'bad', 'none'].includes(rating)) throw new Error('A rating is good, bad or none.');
+    return this.#emit('message.rated', { messageId, rating, by: 'you' });
+  }
+
   // Forgetting is recorded in the ledger like anything else the human does to the room.
   async forgetMemory(id) {
     if (!this.#memory) return null;
@@ -508,6 +552,9 @@ export class Room {
       references: references.length ? references.map(({ excerpt, ...reference }) => reference) : undefined,
       create: create === true ? true : undefined,
     });
+    // The human may say what they like; the room only says so, because every agent will read it.
+    const exposed = this.#privacy?.hits(text2) ?? 0;
+    if (exposed && !ghost) await this.#emit('privacy.warning', { messageId, hits: exposed });
     // The human's creation lease: one directory for this message and any plan
     // it starts. Granted before the agent runs, recorded, revocable by STOPALL.
     // The lease carries the scopes enabled for the target; if the target cannot
@@ -530,10 +577,9 @@ export class Room {
           message: `@${parsed.target} will answer read-only: ${scopes.write.capable ? 'file creation is switched off for it (enable it in CONNECTIONS)' : 'its CLI cannot create files'}${unavailable.length ? `; it cannot ${unavailable.join(' or ')}` : ''}.${alternatives.length ? ` For creation ask ${alternatives.join(' or ')}.` : ''}`,
         });
       } else {
-        lease = await createLease({ projectRoot: this.#projectRoot, leaseId: randomUUID() });
-        lease.messageId = messageId;
+        lease = await this.#projectLease({ leaseId: randomUUID(), messageId });
         // CREATE authorizes the plan to use each delegate's enabled creation
-        // scopes; a standing write lease authorizes files only.
+        // scopes; a default-#2 lease authorizes files only.
         lease.scopeCeiling = { write: true, imageGen: !standing, web: true };
         lease.scopes = Object.fromEntries(SCOPES.map((scope) => [scope, enabled.includes(scope) && (!standing || scope === 'write')]));
         await this.#emit('lease.granted', {
@@ -542,6 +588,7 @@ export class Room {
           messageId,
           agent: parsed.target,
           outDir: lease.relativeDir,
+          scratchDir: lease.scratchDir,
           grantedBy: 'you',
           scopes: standing ? ['write'] : enabled,
           unavailable,
@@ -565,6 +612,25 @@ export class Room {
     await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, attachments: files, references, lease, ashCode: ashActive, mode: ghost ? 0 : control ? 3 : (lease ? 2 : 1) }));
   }
 
+  // A #2 lease: the project itself is where new files go, and MADRE keeps a scratch folder
+  // under .pulse/out/ for what has no natural place. Each turn under it takes a checkpoint
+  // and puts back whatever existed before, so CREATE only ever adds.
+  async #projectLease({ leaseId, messageId }) {
+    const scratch = await createLease({ projectRoot: this.#projectRoot, leaseId });
+    return { leaseId, messageId, outDir: this.#projectRoot, relativeDir: '.', scratchDir: scratch.relativeDir, create: true };
+  }
+
+  // Artifacts from a #2 turn: the files the checkpoint saw appear, as the room shows them.
+  async #artifactsFrom(files) {
+    const out = [];
+    for (const file of files) {
+      if (file.status !== 'A') continue;
+      const info = await statFile(joinPath(this.#projectRoot, file.path)).catch(() => null);
+      out.push({ name: baseName(file.path), path: file.path, size: info?.size ?? 0, contentType: contentTypeFor(file.path), status: 'created' });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
   // Agents that can receive a delegated step from `self`.
   delegatesFor(self) {
     return this.#agents.filter((agent) => agent.ready && agent.id !== self).map((agent) => agent.id);
@@ -626,7 +692,8 @@ export class Room {
     }
 
     const priorEvents = await this.#store.readAll();
-    const { context, recall, memories } = await this.#contextFor(priorEvents, { messageId, text });
+    // @madre never reads its own canned replies back: a small model would echo them.
+    const { context, recall, memories } = await this.#contextFor(priorEvents, { messageId, text, omitSynthetic: Boolean(agent.local) });
     let handoffId = null;
     if (context.previousAgent && context.previousAgent !== targetId) {
       handoffId = randomUUID();
@@ -669,7 +736,7 @@ export class Room {
     // The orchestrator's turn is over before its plan starts, so it is never
     // counted as in flight while the others work.
     if (outcome?.directives?.steps.length) {
-      await this.#runPlan({ orchestrator: agent.id, parentMessageId: outcome.responseMessageId, directives: outcome.directives, lease, ashCode });
+      await this.#runPlan({ orchestrator: agent.id, parentMessageId: outcome.responseMessageId, directives: outcome.directives, lease, ashCode, mode });
     }
     return outcome?.responseMessageId ?? null;
   }
@@ -684,6 +751,8 @@ export class Room {
       motherLines: this.#mother ? this.#mother.recent() : [],
       memoryServer: this.#memoryServer,
       controlHolder: this.#controlDesk.holder?.agent ?? null,
+      privacyMarker: this.#privacy?.marker ?? '[ENTIDAD-ORG]',
+      madreModel: this.#agents.find((agent) => agent.id === 'madre' && agent.ready)?.version ?? null,
     });
   }
 
@@ -698,13 +767,19 @@ export class Room {
     const turnScopes = { web: enabled.web, imageGen: enabled.imageGen };
     let lease = null;
     let controlRun = null;
-    if (mode === 3 && requester === 'you' && depth === 0) {
+    let createRun = null;
+    if (mode === 3 && (requester === 'you' || planId) && depth <= 1 && agentScopes.maxMode >= 3 && enabled.write) {
       // CONTROL: the project itself is the writable root, and a checkpoint
-      // taken now makes every change of this turn reversible.
-      const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled });
-      controlRun = seat.run;
-      lease = seat.lease;
-      await this.#emit('control.started', seat.announcement);
+      // taken now makes every change of this turn reversible. A plan step gets
+      // it when the orchestrator, itself in #3, named #3 for that step.
+      if (this.#controlDesk.holder) {
+        await this.#alert('control-busy', `@${this.#controlDesk.holder.agent} still holds CONTROL; @${agent.id} answers read-only this turn.`, `control-busy:${agent.id}`);
+      } else {
+        const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled });
+        controlRun = seat.run;
+        lease = seat.lease;
+        await this.#emit('control.started', seat.announcement);
+      }
     } else if (sharedLease) {
       lease = enabled.write ? {
         ...sharedLease,
@@ -713,8 +788,7 @@ export class Room {
     } else if (agentScopes.write.always && enabled.write && requester !== 'you' && requester !== 'mother') {
       // Standing lease for a delegate: the human opted this agent into
       // creating files on every turn, so a plan step gets its own directory.
-      lease = await createLease({ projectRoot: this.#projectRoot, leaseId: randomUUID() });
-      lease.messageId = messageId;
+      lease = await this.#projectLease({ leaseId: randomUUID(), messageId });
       lease.scopeCeiling = { write: true, imageGen: false, web: true };
       lease.scopes = { ...enabled, imageGen: false };
       await this.#emit('lease.granted', {
@@ -723,11 +797,18 @@ export class Room {
         messageId,
         agent: agent.id,
         outDir: lease.relativeDir,
+        scratchDir: lease.scratchDir,
         scopes: ['write'],
         unavailable: SCOPES.filter((scope) => !agentScopes[scope].capable).map((scope) => SCOPE_LABELS[scope]),
         planId,
       });
     }
+    if (lease?.create && !controlRun) {
+      // CREATE: photograph the project now; after the turn only what appeared stays.
+      const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled, mode: 2 });
+      createRun = seat.run;
+      lease = { ...lease, checkpoint: seat.run.checkpoint };
+    }
     turnScopes.imageGen = Boolean(lease?.scopes?.imageGen);
     // The step asks for files but nobody granted a lease: say so now, with a
     // way out, instead of letting the agent's refusal be the only signal.
@@ -746,16 +827,18 @@ export class Room {
     const native = Boolean(CAPABILITIES[agent.id]?.imageGen);
     const studio = imageModuleState();
     const imageStudio = lease?.scopes?.imageGen && enabled.imageGen && !native && studio.enabled
-      ? imageStudioFor({ enabled: true, model: studio.model, outDir: lease.outDir })
+      ? imageStudioFor({ enabled: true, model: studio.model, outDir: lease.scratchDir ? joinPath(this.#projectRoot, lease.scratchDir) : lease.outDir })
       : null;
     // The turn's effective mode: #0 for ghosts, #3 in control, #2 only while it holds a lease.
     const turnMode = mode === 0 ? 0 : controlRun ? 3 : lease ? 2 : 1;
     try {
       const invoke = this.#invokers[agent.adapter];
       if (!invoke) throw new Error(`${agent.label} does not have a supported MADRE adapter.`);
-      const before = lease && !lease.control ? await snapshot(lease.outDir) : null;
+      const before = lease && !lease.control && !lease.create ? await snapshot(lease.outDir) : null;
       const responseMessageId = randomUUID();
       const notesBefore = this.#memory ? this.#memory.maxMemoryId() : 0;
+      const others = this.delegatesFor(agent.id);
+      const mayDelegate = allowDelegation && this.#delegation && depth === 0;
       const result = await invoke({
         executable: agent.path,
         projectRoot: this.#projectRoot,
@@ -769,12 +852,22 @@ export class Room {
         scopes: turnScopes,
         imageStudio,
         memoryServer: memoryServerForTurn(this.#memoryServer, { agent: agent.id, messageId: responseMessageId, mode: turnMode }),
+        // For @madre: who asks, who it may convene, and whether a plan would run at all.
+        requester,
+        crew: others,
+        delegation: mayDelegate,
+        maxSteps: this.#maxPlanSteps,
       });
-      const artifacts = lease && !lease.control ? diffSnapshots(before, await snapshot(lease.outDir), { relativeDir: lease.relativeDir }) : [];
+      // Privacy: a private term in a reply is replaced before the ledger, the plan parser,
+      // the archivist or any other agent can see it. The reply says how many, not which.
+      const guarded = this.#privacy?.redact(result.text ?? '') ?? { text: result.text, hits: 0 };
+      if (guarded.hits) result.text = guarded.text;
+      // CREATE: what appeared stays and is shown; what existed before is put back and said.
+      const createChanges = createRun ? await this.#controlDesk.settle(createRun) : null;
+      const artifacts = createChanges ? await this.#artifactsFrom(createChanges.files) : lease && !lease.control ? diffSnapshots(before, await snapshot(lease.outDir), { relativeDir: lease.relativeDir }) : [];
       // CONTROL: what really changed in the project, forbidden zones reverted on the spot.
       const controlChanges = controlRun ? await this.#controlDesk.settle(controlRun) : null;
-      const others = this.delegatesFor(agent.id);
-      const directives = allowDelegation && this.#delegation && depth === 0
+      const directives = mayDelegate
         ? parseDirectives(result.text, { self: agent.id, available: others, maxSteps: this.#maxPlanSteps })
         : { steps: [], closing: null, ignored: [] };
       if (directives.steps.length === 0 && directives.ignored.length && depth === 0) {
@@ -798,14 +891,20 @@ export class Room {
         status: 'completed',
         planId,
         model,
+        synthetic: result.synthetic || undefined,
+        redacted: guarded.hits || undefined,
         mode: turnMode,
         leaseId: lease?.leaseId,
         artifacts: artifacts.length ? artifacts : undefined,
         delegates: directives.steps.length ? directives.steps.map((step) => step.agent) : undefined,
       });
+      if (guarded.hits) await this.#emit('privacy.redacted', { agent: agent.id, messageId, responseMessageId, hits: guarded.hits, marker: this.#privacy.marker });
       if (artifacts.length) {
         await this.#emit('artifacts.created', { leaseId: lease.leaseId, messageId, responseMessageId, agent: agent.id, outDir: lease.relativeDir, files: artifacts });
       }
+      if (createChanges && (createChanges.existingReverted.length || createChanges.forbiddenReverted.length)) {
+        await this.#emit('create.reverted', { checkpointId: createChanges.checkpointId, agent: agent.id, messageId, responseMessageId, existing: createChanges.existingReverted, forbidden: createChanges.forbiddenReverted, message: createChanges.message });
+      }
       // What the agent saved through memory_note during this turn, for the bubble's hint.
       if (this.#memory && turnMode !== 0) {
         const noted = this.#memory.notesSince(notesBefore, { agent: agent.id });
@@ -819,29 +918,37 @@ export class Room {
       await this.#emit('agent.completed', { messageId, agent: agent.id, handoffId, planId });
       return { responseMessageId, directives };
     } catch (error) {
-      await this.#emit('message.failed', { messageId, target: agent.id, planId, error: failureMessage(error) });
+      await this.#emit('message.failed', { messageId, target: agent.id, planId, error: this.#privacy ? this.#privacy.redact(failureMessage(error)).text : failureMessage(error) });
       return null;
     } finally {
       // Release CONTROL whichever way the turn ended; the checkpoint stays for UNDO.
       await this.#controlDesk.release(controlRun);
+      await this.#controlDesk.release(createRun);
     }
   }
 
-  async #runPlan({ orchestrator, parentMessageId, directives, lease = null, ashCode = false }) {
+  async #runPlan({ orchestrator, parentMessageId, directives, lease = null, ashCode = false, mode = 1 }) {
     const planId = randomUUID();
-    // The plan runs at the human's mode: #2 only while a lease exists, and a
-    // step's agent gets #2 only if its own scopes allow writing.
-    const stepMode = (agentId) => (lease && this.scopesFor(agentId).write.enabled ? 2 : 1);
+    // The plan's ceiling is the human's mode: #3 when the orchestrator held CONTROL, #2 while a
+    // lease exists, #1 otherwise. A step may ask for a mode ("@codex #2: …"); it gets the lowest
+    // of what it asked, the ceiling and its own MAX MODE. Without a number it inherits the plan.
+    const ceiling = mode >= 3 ? 3 : lease ? 2 : 1;
+    const stepMode = (step) => {
+      const scopes = this.scopesFor(step.agent);
+      const asked = normalizeMode(step.mode, lease ? 2 : 1);
+      const granted = Math.min(asked, ceiling, scopes.maxMode);
+      return granted >= 2 && !scopes.write.enabled ? 1 : granted;
+    };
     const plan = { planId, orchestrator, steps: directives.steps, closing: directives.closing, step: 0, stopped: null, startedAt: Date.now() };
     this.#plans.set(planId, plan);
     await this.#emit('plan.created', {
       planId,
       orchestrator,
       parentMessageId,
-      steps: directives.steps.map((step) => ({ ...step, mode: stepMode(step.agent) })),
+      steps: directives.steps.map((step) => ({ ...step, mode: stepMode(step) })),
       closing: directives.closing,
       ignored: directives.ignored,
-      mode: lease ? 2 : 1,
+      mode: ceiling,
       leaseId: lease?.leaseId ?? null,
     });
     try {
@@ -857,7 +964,16 @@ export class Room {
         let stepLease = lease;
         let escalation = null;
         const stepScopes = this.scopesFor(step.agent);
-        if (!lease && !stepScopes.write.always && looksLikeCreation(step.text) && stepScopes.maxMode >= 2 && stepScopes.write.enabled) {
+        const wanted = stepMode(step);
+        // Under a #3 ceiling the orchestrator's word is enough: a #2 step gets its project lease,
+        // a #3 step gets CONTROL for its turn. Under #1 a creation step still asks the human.
+        if (ceiling === 3 && !stepLease && wanted === 2) {
+          stepLease = await this.#projectLease({ leaseId: randomUUID(), messageId });
+          stepLease.scopeCeiling = { write: true, imageGen: true, web: true };
+          stepLease.scopes = Object.fromEntries(SCOPES.map((scope) => [scope, stepScopes[scope].enabled && stepScopes[scope].wired]));
+          await this.#emit('lease.granted', { delegated: true, leaseId: stepLease.leaseId, messageId, agent: step.agent, outDir: '.', scratchDir: stepLease.scratchDir, grantedBy: orchestrator, scopes: SCOPES.filter((scope) => stepLease.scopes[scope]), unavailable: [], planId });
+        }
+        if (ceiling < 3 && !lease && !stepScopes.write.always && (wanted >= 2 || looksLikeCreation(step.text)) && stepScopes.maxMode >= 2 && stepScopes.write.enabled) {
           const outcome = await this.#askForMode({ planId, plan, step, index, totalSteps: directives.steps.length + (directives.closing ? 1 : 0), orchestrator, parentMessageId, mode: 2 });
           if (outcome.scope === 'plan') lease = outcome.lease;
           if (outcome.scope) stepLease = outcome.lease; else escalation = outcome.reason;
@@ -873,12 +989,12 @@ export class Room {
           ashCode: ashCode ? { active: true, applied: abbreviated.applied, reason: abbreviated.reason, language: abbreviated.language, originalChars: abbreviated.originalChars, encodedChars: abbreviated.encodedChars } : undefined,
           status: 'delegated',
           planId,
-          mode: stepLease && stepScopes.write.enabled ? 2 : 1,
+          mode: wanted === 3 ? 3 : stepLease && stepScopes.write.enabled ? 2 : 1,
           escalation: escalation ?? undefined,
           step: index + 1,
           totalSteps: directives.steps.length + (directives.closing ? 1 : 0),
         });
-        await this.#dispatch({ messageId, targetId: step.agent, text: stepText, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease: stepLease, ashCode, mode: stepLease && stepScopes.write.enabled ? 2 : 1, escalation });
+        await this.#dispatch({ messageId, targetId: step.agent, text: stepText, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease: wanted === 3 ? null : stepLease, ashCode, mode: wanted === 3 ? 3 : stepLease && stepScopes.write.enabled ? 2 : 1, escalation });
       }
       if (!plan.stopped && directives.closing) {
         plan.step = directives.steps.length + 1;

package/src/server.mjs

@@ -15,7 +15,7 @@ import { ErrorSentinel } from './sentinel-errors.mjs';
 import { probeOllama, ollamaEmbedder, ollamaInvoker, pullModel } from './ollama.mjs';
 import { moduleById, describeModules, findModuleRoute } from './modules/index.mjs';
 import { madreAgent, madreInvoker, MADRE_AGENT_ID, MADRE_ADAPTER } from './adapters/madre.mjs';
-import { exportDataset } from './dataset.mjs';
+import { exportDataset, readiness as datasetReadiness } from './dataset.mjs';
 
 const PACKAGE = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8').catch(() => '{}'));
 let crashHandlersInstalled = false;
@@ -42,6 +42,9 @@ import { applyConfigToEnv, loadConfig } from './config.mjs';
 import { extensionById, runInstaller } from './extensions.mjs';
 import { loginPlanFor, probeAll } from './auth-probe.mjs';
 import { loadConfig as readConfig, updateConfig } from './config.mjs';
+import { Privacy, normalizeTerms, privacySettings } from './privacy.mjs';
+import { checkForUpdate, detectInstall, updateCommand, releaseUrl } from './updates.mjs';
+import { totalmem } from 'node:os';
 import { discoverModels } from './models.mjs';
 import { setImageModule } from './capabilities.mjs';
 import { resolveGeminiKey } from './image-studio.mjs';
@@ -131,7 +134,21 @@ export async function createPulseServer({
   const historicalEvents = await store.readAll();
   // The room's memory: derived from the ledger, rebuilt if missing or stale,
   // and never a reason for the room not to open.
-  const memory = await new RoomMemory(join(roomDir, 'memory.sqlite')).initialize(store)
+  // Release channel: one registry read a day, cached for every room on this machine. On by
+  // default; PULSE_UPDATE_CHECK=0 or the switch in MU/TH/UR turns it off. Never self-updates.
+  const updatesEnabled = () => (process.env.PULSE_UPDATE_CHECK !== undefined ? process.env.PULSE_UPDATE_CHECK !== '0' : updatesConfig.check !== false);
+  let updatesConfig = { ...((await readConfig(root)).updates ?? {}) };
+  const install = detectInstall({ projectRoot: canonicalProjectRoot });
+  async function versionView({ force = false } = {}) {
+    const check = await checkForUpdate({ name: PACKAGE.name, current: PACKAGE.version, cacheFile: join(root, 'updates.json'), fetchImpl: reportFetch, enabled: updatesEnabled(), force });
+    return { ...check, name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
+  }
+  // Privacy: the terms that never travel through this room, from config.json and the environment.
+  // config.json is shared by every room on this machine, so the list is re-read before each
+  // human message and whenever MU/TH/UR looks: a term named in one room guards them all.
+  const privacy = new Privacy(privacySettings(await readConfig(root)));
+  const refreshPrivacy = async () => { const { terms, marker } = privacySettings(await readConfig(root)); privacy.set(terms, marker); return privacy; };
+  const memory = await new RoomMemory(join(roomDir, 'memory.sqlite')).attachPrivacy(privacy).initialize(store)
     .catch((error) => { console.error(`MADRE memory unavailable, turns get the recent window only: ${error.message}`); return null; });
   // Meaning-aware recall through the user's own Gemini key, when there is one;
   // and the memory as MCP tools for every agent's turn.
@@ -139,6 +156,12 @@ export async function createPulseServer({
   // start and again from MODULES; wired live, no restart.
   let ollama = { running: false, host: null, models: [], embedModel: null, chatModel: null };
   const ollamaSettings = async () => ({ enabled: true, embeddings: true, archivist: true, agent: true, ...((await readConfig(root)).modules?.ollama ?? {}) });
+  // What the TRAIN card needs: where the recipe ships, the room, the model name @madre will pick up, a base that fits this machine.
+  function trainingInfo() {
+    const slug = basename(canonicalProjectRoot).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    const gb = Math.round(totalmem() / 1024 ** 3);
+    return { roomDir, recipeDir: fileURLToPath(new URL('../docs/training/', import.meta.url)), modelName: `madre-${slug}`, baseModel: gb >= 32 ? 'Qwen/Qwen2.5-3B-Instruct' : 'Qwen/Qwen2.5-1.5B-Instruct', memoryGb: gb };
+  }
   async function wireOllama({ probe: doProbe = true } = {}) {
     if (doProbe) ollama = await ollamaProbe();
     // A model trained on this room (docs/training) is named madre-<project>: @madre uses it when it exists.
@@ -188,6 +211,7 @@ export async function createPulseServer({
     store,
     agents,
     projectRoot,
+    privacy,
     softTokenBudget,
     contextMaxChars,
     recallShare: Number(process.env.PULSE_RECALL_SHARE ?? startupMemory.recallShare),
@@ -236,6 +260,8 @@ export async function createPulseServer({
       geminiRetries: Number(process.env.PULSE_GEMINI_RETRIES ?? 1),
       capabilities: room.capabilities(),
       memory: memorySettingsView(),
+      updates: { check: updatesEnabled(), envWins: process.env.PULSE_UPDATE_CHECK !== undefined },
+      privacy: { terms: privacy.terms, marker: privacy.marker, envWins: privacySettings({}, process.env).envWins },
     };
   }
   // What MU/TH/UR shows under MEMORY: the live values, who could distil, and what embeds today.
@@ -297,7 +323,9 @@ export async function createPulseServer({
         if (!agents.some((agent) => agent.id === agentId) || !scopes || typeof scopes !== 'object') continue;
         config.scopes[agentId] = { ...(current[agentId] ?? {}) };
         for (const scope of ['write', 'imageGen', 'web', 'alwaysCreate']) if (typeof scopes[scope] === 'boolean') config.scopes[agentId][scope] = scopes[scope];
-        if (Number.isInteger(Number(scopes.maxMode)) && Number(scopes.maxMode) >= 0 && Number(scopes.maxMode) <= 3) config.scopes[agentId].maxMode = Number(scopes.maxMode);
+        // MAX MODE and DEFAULT MODE are the two controls; setting them retires the older flags they replace.
+        if (Number.isInteger(Number(scopes.maxMode)) && Number(scopes.maxMode) >= 0 && Number(scopes.maxMode) <= 3) { config.scopes[agentId].maxMode = Number(scopes.maxMode); delete config.scopes[agentId].write; }
+        if (Number.isInteger(Number(scopes.defaultMode)) && Number(scopes.defaultMode) >= 1 && Number(scopes.defaultMode) <= 2) { config.scopes[agentId].defaultMode = Number(scopes.defaultMode); delete config.scopes[agentId].alwaysCreate; }
       }
       room.setScopes(config.scopes);
     }
@@ -675,6 +703,7 @@ export async function createPulseServer({
         return sendJson(response, 201, { attachment: { id: record.id, name: record.name, fileName: record.fileName, size: record.size, contentType: record.contentType, url: `/api/files?root=attachments&path=${encodeURIComponent(record.fileName)}` } });
       }
       if (request.method === 'GET' && url.pathname === '/api/settings') {
+        await refreshPrivacy();
         return sendJson(response, 200, { settings: effectiveSettings(), config: await readConfig(root), sessions, sessionsAt, loggingIn, agents: agents.map((agent) => ({ ...agent, login: loginPlanFor(agent) })) });
       }
       if (request.method === 'POST' && url.pathname === '/api/settings') {
@@ -709,13 +738,58 @@ export async function createPulseServer({
       // The dataset behind MADRE AI: exported on demand next to the ledger.
       if (url.pathname === '/api/dataset' && (request.method === 'GET' || request.method === 'POST')) {
         const dir = join(roomDir, 'dataset');
+        const notes = memory ? memory.memories({ limit: 5000 }) : [];
         if (request.method === 'GET') {
           const manifest = await readFile(join(dir, 'manifest.json'), 'utf8').then(JSON.parse).catch(() => null);
-          return sendJson(response, 200, { dataset: manifest, dir, trained: ollama.madreModel ?? null });
+          return sendJson(response, 200, { dataset: manifest, dir, trained: ollama.madreModel ?? null, readiness: datasetReadiness(await store.readAll(), notes), training: trainingInfo() });
         }
-        const result = await exportDataset({ events: await store.readAll(), notes: memory ? memory.memories({ limit: 5000 }) : [], dir, project: basename(canonicalProjectRoot), home: homedir() });
+        const events = await store.readAll();
+        const result = await exportDataset({ events, notes, dir, project: basename(canonicalProjectRoot), home: homedir(), privacy });
         await room.record('dataset.exported', { pairs: result.pairs, turns: result.turns, notes: result.notes, train: result.train, valid: result.valid, dir });
-        return sendJson(response, 200, { dataset: result, dir, trained: ollama.madreModel ?? null });
+        return sendJson(response, 200, { dataset: result, dir, trained: ollama.madreModel ?? null, readiness: datasetReadiness(events, notes), training: trainingInfo() });
+      }
+      // PRIVACY: the terms live in config.json only; the ledger records counts, never words.
+      if (request.method === 'GET' && url.pathname === '/api/privacy') {
+        await refreshPrivacy();
+        return sendJson(response, 200, { terms: privacy.terms, marker: privacy.marker, exposure: room.privacyExposure(await store.readAll()) });
+      }
+      if (request.method === 'POST' && url.pathname === '/api/privacy') {
+        const patch = await body(request).catch(() => ({}));
+        const current = (await readConfig(root)).privacy ?? {};
+        const next = { ...current };
+        if ('terms' in patch) next.terms = normalizeTerms(patch.terms);
+        if (typeof patch.marker === 'string' && patch.marker.trim()) next.marker = patch.marker.trim().slice(0, 40);
+        await updateConfig(root, { privacy: next });
+        privacy.set(next.terms ?? [], next.marker);
+        await room.record('privacy.updated', { terms: privacy.terms.length, marker: privacy.marker });
+        return sendJson(response, 200, { terms: privacy.terms, marker: privacy.marker, exposure: room.privacyExposure(await store.readAll()) });
+      }
+      if (request.method === 'POST' && url.pathname === '/api/privacy/purge') {
+        const payload = await body(request).catch(() => ({}));
+        if (!designationOk(payload.designation)) return sendJson(response, 403, { error: 'UNABLE TO COMPUTE. UNABLE TO CLARIFY.' });
+        await refreshPrivacy();
+        if (!privacy.enabled) return sendJson(response, 412, { error: 'No private terms are set. Write them first.' });
+        const result = await room.purgePrivate();
+        // The log was rewritten in place: the broadcaster's byte offset is stale, the sequences are not.
+        tailOffset = (await store.tail(0)).offset;
+        return sendJson(response, 200, { purged: result, exposure: room.privacyExposure(await store.readAll()) });
+      }
+      // The human's verdict on a reply, for the dataset: good, bad, none.
+      if (request.method === 'POST' && url.pathname === '/api/messages/rate') {
+        const payload = await body(request).catch(() => ({}));
+        try {
+          const event = await room.rateMessage(String(payload.messageId ?? ''), String(payload.rating ?? ''));
+          return sendJson(response, 200, { rated: event.payload });
+        } catch (error) { return sendJson(response, 400, { error: error.message }); }
+      }
+      // Release channel: current, latest on npm, and the command for how this copy runs.
+      if (request.method === 'GET' && url.pathname === '/api/version') {
+        return sendJson(response, 200, await versionView({ force: url.searchParams.get('force') === '1' }));
+      }
+      if (request.method === 'POST' && url.pathname === '/api/updates/settings') {
+        const patch = await body(request).catch(() => ({}));
+        if (typeof patch.check === 'boolean') { updatesConfig = { ...updatesConfig, check: patch.check }; await updateConfig(root, { updates: updatesConfig }); }
+        return sendJson(response, 200, { updates: { check: updatesEnabled(), envWins: process.env.PULSE_UPDATE_CHECK !== undefined } });
       }
       if (request.method === 'GET' && url.pathname === '/api/mother') {
         return sendJson(response, 200, { mother: room.motherStatus(), strikes: CODE000_STRIKES });
@@ -811,6 +885,7 @@ export async function createPulseServer({
         // hears "no" with a reason instead of a silent log line.
         const gate = await room.modeCheck(payload);
         if (!gate.ok) return sendJson(response, gate.status ?? 403, { error: gate.error, mode: gate.mode, maxMode: gate.maxMode });
+        await refreshPrivacy();
         void room.send(payload).catch((error) => {
           console.error(`MADRE room error: ${error.message}`);
         });

package/src/updates.mjs

@@ -0,0 +1,79 @@
+// Release channel: is there a newer MADRE on npm? One read of the public registry, at most
+// once a day, cached in ~/.pulse/updates.json. It sends the package name and nothing else,
+// the same request `npx` makes; PULSE_UPDATE_CHECK=0 or the switch in MU/TH/UR turns it off.
+// MADRE never updates itself: the room is in use and the process belongs to the human. It
+// shows the exact command for how this copy was launched.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export const REGISTRY = 'https://registry.npmjs.org';
+export const UPDATE_TTL_MS = 24 * 60 * 60 * 1000;
+
+const parse = (version) => String(version ?? '').trim().replace(/^v/, '').split(/[.+-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+
+// -1 when a < b, 0 when equal, 1 when a > b. Pre-release tags are ignored: a room compares releases.
+export function compareVersions(a, b) {
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i += 1) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+
+// How this copy runs, from the path of the script Node started: npx cache, the project's own
+// node_modules, a global install, or the source tree.
+export function detectInstall({ script = process.argv[1] ?? '', projectRoot = process.cwd() } = {}) {
+  const path = String(script).replace(/\\/g, '/');
+  if (/\/_npx\//.test(path)) return 'npx';
+  if (projectRoot && path.startsWith(`${String(projectRoot).replace(/\\/g, '/').replace(/\/$/, '')}/node_modules/`)) return 'project';
+  if (/\/node_modules\//.test(path)) return 'global';
+  return 'source';
+}
+
+export function updateCommand(install, name, version = 'latest') {
+  switch (install) {
+    case 'npx': return `npx ${name}@${version} start`;
+    case 'project': return `npm install ${name}@${version}`;
+    case 'global': return `npm install -g ${name}@${version}`;
+    default: return 'git pull';
+  }
+}
+
+export function releaseUrl(repository, version) {
+  const url = String(repository?.url ?? repository ?? '').replace(/^git\+/, '').replace(/\.git$/, '');
+  return url ? `${url}/releases/tag/v${version}` : null;
+}
+
+async function readCache(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch { return null; }
+}
+
+// The check. `enabled: false` answers from the cache only and never touches the network.
+export async function checkForUpdate({ name, current, cacheFile, fetchImpl = globalThis.fetch, now = Date.now(), ttlMs = UPDATE_TTL_MS, enabled = true, force = false, timeoutMs = 4000 } = {}) {
+  const cached = cacheFile ? await readCache(cacheFile) : null;
+  const fresh = cached && cached.name === name && Number.isFinite(cached.checkedAt) && now - cached.checkedAt < ttlMs;
+  let latest = cached?.name === name ? cached.latest ?? null : null;
+  let checkedAt = cached?.name === name ? cached.checkedAt ?? null : null;
+  let source = latest ? 'cache' : 'none';
+  let error = null;
+  if (enabled && (force || !fresh)) {
+    try {
+      const response = await fetchImpl(`${REGISTRY}/${encodeURIComponent(name).replace('%40', '@')}/latest`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
+      if (!response.ok) throw new Error(`registry HTTP ${response.status}`);
+      const doc = await response.json();
+      if (typeof doc?.version !== 'string') throw new Error('registry answered without a version');
+      latest = doc.version;
+      checkedAt = now;
+      source = 'registry';
+      if (cacheFile) {
+        await mkdir(dirname(cacheFile), { recursive: true }).catch(() => {});
+        await writeFile(cacheFile, JSON.stringify({ name, latest, checkedAt })).catch(() => {});
+      }
+    } catch (cause) {
+      error = cause.message;
+      if (!latest) source = 'error';
+    }
+  }
+  if (!enabled) source = latest ? 'cache' : 'off';
+  const available = Boolean(latest && current && compareVersions(current, latest) < 0);
+  return { enabled, current: current ?? null, latest, available, checkedAt, source, error };
+}