@twinsearth/w2m-dsh-plugin 1.3.1 → 1.4.0

package/src/relay/state.mjs

@@ -25,6 +25,14 @@ import { planJoin } from '../chatops/fleet-join.mjs';
 import { validateTaskDependencies } from './task-deps.mjs';
 import { buildMembers, isMemberRole, setMemberRole as applyMemberRole } from './fleet-members.mjs';
 import { canonicalSignedPayload, publicKeyFromBase64 } from '../util/envelope-signature.mjs';
+import { createProjectRoom } from './project-room.mjs';
+import { createProjectLocks } from './project-locks.mjs';
+import { createProjectReviews } from './project-reviews.mjs';
+import { createProjectNotifications } from './project-notifications.mjs';
+import { createBlobSessions } from './blob-sessions.mjs';
+import { createProjectRefs } from './project-refs.mjs';
+import { createMetrics } from './reliability-metrics.mjs';
+import { argvHash as grantArgvHash } from '../maintenance/grant.mjs';
 
 export const PROTOCOL_VERSION = 1;
 
@@ -37,6 +45,11 @@ export const PROTOCOL_VERSION = 1;
 export const ERROR_STATUS = Object.freeze({
   UNAUTHORIZED: 401,
   BAD_REQUEST: 400,
+  // v1.3.12-beta.1: dispatch refuses a grant written for another task or argv. Caller errors (400), not authorization verdicts.
+  GRANT_TASK_MISMATCH: 400,
+  GRANT_ARGV_MISMATCH: 400,
+  GRANT_EXPIRED: 400,
+  GRANT_REVOKED: 403,
   NOT_FOUND: 404,
   PAIRING_INVALID: 400,
   PAIRING_EXPIRED: 400,
@@ -509,6 +522,71 @@ export class RabbitState {
     /** @type {{seq:number,event:object,target:string|null}[]} ring buffer, last N events */
     this.buffer = [];
     this.devices = new Map();      // machine_id -> device
+    // v1.3.10-beta.2: operator signing keys seen with a dispatch; agents pin the first one they receive.
+    this.operatorKeys = new Map();
+    // v1.3.10-beta.13: shared project objects (M4). Tasks name a project; readers get snapshot + events.
+    this.metrics = createMetrics();
+    // v1.3.14-beta.4: project-scoped live push. A client that follows one project subscribes here instead of filtering the
+    // global stream, so two clients see the same project events in the same order (the room owns the sequence).
+    this.projectSubscribers = new Set();
+    // v1.3.14-beta.1 (collaboration model): shared objects every client reads the same way -- a project board and an artifact
+    // index. Before this a client could only list ALL tasks, so two clients "in the same project" built different boards.
+    this.artifacts = new Map();
+    // v1.3.14-beta.2: the remaining shared objects -- decisions and a project memory document. Both are append/versioned and
+    // read by every member, so "what we agreed" is the same object for every client rather than a chat history.
+    this.decisions = new Map();
+    this.projectMemory = new Map();
+    // v1.3.13-beta.4: branch heads and merge outcomes live with the project room so one stream answers "where is the branch".
+    this.refs = createProjectRefs({
+      now: () => this.nowMs(),
+      onEvent: (event) => { try { this.projects.appendEvent({ projectId: event.payload.project_id, type: event.type, actor: { kind: 'operator', id: 'relay' }, payload: event.payload }); } catch { /* history */ } },
+    });
+    // Every project-room event is counted once, here: the room's own events and the lock/review/notification events projected
+    // into it both pass through this callback, so the counter cannot double-count a projection.
+    // v1.3.14-beta.3: which project events are worth a notification, and whether they need an action from a member.
+    const NOTIFIED = Object.freeze({
+      'decision.recorded': { kind: 'decision.recorded', subject: 'a decision was recorded', requiresAction: false },
+      'artifact.registered': { kind: 'artifact.registered', subject: 'an artifact was registered', requiresAction: false },
+      'memory.updated': { kind: 'memory.updated', subject: 'project memory was updated', requiresAction: false },
+      'merge.conflict': { kind: 'merge.conflict', subject: 'a merge conflicted', requiresAction: true },
+      'merge.merged': { kind: 'merge.merged', subject: 'a patch was merged', requiresAction: false },
+      'ref.advanced': { kind: 'ref.updated', subject: 'a branch was advanced', requiresAction: false },
+    });
+    const metricsEvent = (event) => {
+      try { this.metrics.inc('wm_project_events_total', { type: event.type }); } catch { /* metrics never break the room */ }
+      for (const listener of this.projectSubscribers) { try { listener(event); } catch { /* a subscriber never breaks the room */ } }
+      const notified = NOTIFIED[event.type];
+      if (notified !== undefined) {
+        try {
+          this.notifications.notify({ projectId: event.project_id, kind: notified.kind, target: { kind: 'broadcast' }, subject: notified.subject, refs: event.payload ?? {}, requiresAction: notified.requiresAction });
+        } catch { /* a notification is never worth failing the event for */ }
+      }
+    };
+    this.projects = createProjectRoom({ now: () => this.nowMs(), onEvent: metricsEvent });
+    this.defaultProjectId = 'default';
+    // M5 primitives share the project room's event stream: a lock, review or notification is a project event with the
+    // module's own sequence attached, so one reader can reconstruct "what happened" from a single cursor.
+    const roomEvent = (event) => {
+      try {
+        this.projects.appendEvent({ projectId: event.payload.project_id, type: event.type, actor: { kind: 'operator', id: 'relay' }, payload: { ...event.payload, module_seq: event.seq } });
+      } catch { /* an event about a project that is gone is history, not an error */ }
+    };
+    this.locks = createProjectLocks({ now: () => this.nowMs(), onEvent: roomEvent });
+    this.reviews = createProjectReviews({ now: () => this.nowMs(), onEvent: roomEvent });
+    this.notifications = createProjectNotifications({ now: () => this.nowMs(), onEvent: roomEvent });
+    // v1.3.10-beta.20: a committed chunk session becomes a fleet blob with the same verified bytes. A store failure does not
+    // undo the commit (the session is gone), but it is reported through the route so a caller never believes a blob exists.
+    // v1.3.12-beta.2: revoked grants. The operator can stop one authorisation from being used; the dispatch preflight
+    // refuses a task carrying a revoked grant, and the ledger keeps the revocation with its reason.
+    this.revokedGrants = new Map();
+    this.blobSessions = createBlobSessions({
+      now: () => this.nowMs(),
+      onCommit: (blob) => {
+        const device = this.devices.get(blob.machineId);
+        if (device === undefined) return;
+        this.putFleetBlob(device, blob.bytes);
+      },
+    });
     /** v1.2.5: operator-assigned roles, kept apart from device records so a re-pair cannot change authority. */
     this.roles = new Map();        // machine_id -> 'owner'|'worker'|'observer'
     /** v1.2.5: read watermarks per session, per machine. */
@@ -705,6 +783,10 @@ export class RabbitState {
 
   /** @returns {boolean} true when a new task was created. */
   _applyLedgerEntry(entry) {
+    if (entry?.type === 'operator.key.registered' && entry.key && typeof entry.key.key_id === 'string') {
+      this.operatorKeys.set(entry.key.key_id, { ...entry.key });
+      return false;
+    }
     if (!entry || typeof entry.type !== 'string') return false;
     switch (entry.type) {
       case 'task.created': {
@@ -738,7 +820,8 @@ export class RabbitState {
           // v1.2.7: a revived task keeps its graph edges and assignment, or the scheduler silently becomes a different scheduler.
           depends_on: Array.isArray(t.depends_on) ? t.depends_on : [],
           assignee: typeof t.assignee === 'string' && t.assignee !== '' ? t.assignee : null,
-          reduce_of: typeof t.reduce_of === 'string' ? t.reduce_of : null,
+          project_id: typeof t.project_id === 'string' ? t.project_id : null,
+        reduce_of: typeof t.reduce_of === 'string' ? t.reduce_of : null,
           reduce_inputs: Array.isArray(t.reduce_inputs) ? t.reduce_inputs : [],
           leases: new Map(),
           cancelled: false,
@@ -1730,6 +1813,85 @@ export class RabbitState {
      * v1.2.10: validate the reduce artifact list up front. A malformed list would otherwise become an offer the machine
      * cannot execute, and the failure would surface as a generic refusal on the executor instead of at dispatch.
      */
+    /**
+     * v1.3.10-beta.2: a maintenance request is opaque to the relay (the root runner is the authority) but its shape and
+     * size are checked here so a malformed request is refused at dispatch instead of on a machine it was never meant for.
+     */
+    const rawMaintenance = input.maintenance ?? null;
+    let normalizedMaintenance = null;
+    if (rawMaintenance !== null) {
+      if (typeof rawMaintenance !== 'object' || Array.isArray(rawMaintenance) || Buffer.byteLength(JSON.stringify(rawMaintenance), 'utf8') > 64 * 1024) {
+        throw new ProtocolError('BAD_REQUEST', 'maintenance must be an object of at most 64 KiB', {});
+      }
+      if (typeof rawMaintenance.request_id !== 'string' || rawMaintenance.request_id === '') {
+        throw new ProtocolError('BAD_REQUEST', 'maintenance.request_id is required', {});
+      }
+      normalizedMaintenance = rawMaintenance;
+    }
+    /**
+     * v1.3.10-beta.3: a task-level grant travels with the dispatch. The relay checks its shape and time window so a bad
+     * grant is refused at dispatch, but the agent is the verifier — the relay never decides authorisation on its own.
+     */
+    /**
+     * v1.3.13-beta.1 (task model): a task may explain WHICH copy of the project it runs on. The relay validates the
+     * descriptor and carries it, exactly as it carries argv: the machine that owns the copy decides whether it can honour
+     * it (and the agent currently refuses a workspace task with WORKSPACE_UNSUPPORTED until the execution slice lands).
+     */
+    const rawWorkspace = input.workspace ?? null;
+    let normalizedWorkspace = null;
+    if (rawWorkspace !== null) {
+      if (typeof rawWorkspace !== 'object' || Array.isArray(rawWorkspace) || Buffer.byteLength(JSON.stringify(rawWorkspace), 'utf8') > 4 * 1024) {
+        throw new ProtocolError('BAD_REQUEST', 'workspace must be an object of at most 4 KiB', {});
+      }
+      if (rawWorkspace.kind !== 'worktree') throw new ProtocolError('BAD_REQUEST', "workspace.kind must be 'worktree'", { kind: rawWorkspace.kind });
+      if (typeof rawWorkspace.base_commit !== 'string' || !/^[0-9a-f]{7,64}$/.test(rawWorkspace.base_commit)) {
+        throw new ProtocolError('BAD_REQUEST', 'workspace.base_commit must be a hex commit id', { base_commit: rawWorkspace.base_commit });
+      }
+      const produce = rawWorkspace.produce ?? 'patch';
+      if (!['patch', 'commit', 'none'].includes(produce)) throw new ProtocolError('BAD_REQUEST', "workspace.produce must be patch, commit or none", { produce });
+      normalizedWorkspace = { kind: 'worktree', base_commit: rawWorkspace.base_commit, produce };
+    }
+    const rawGrant = input.grant ?? null;
+    let normalizedGrant = null;
+    if (rawGrant !== null) {
+      if (typeof rawGrant !== 'object' || Array.isArray(rawGrant) || Buffer.byteLength(JSON.stringify(rawGrant), 'utf8') > 8 * 1024) {
+        throw new ProtocolError('BAD_REQUEST', 'grant must be an object of at most 8 KiB', {});
+      }
+      if (typeof rawGrant.grant_id !== 'string' || rawGrant.grant_id === '' || !/^[0-9a-f]{64}$/.test(String(rawGrant.argv_hash ?? ''))) {
+        throw new ProtocolError('BAD_REQUEST', 'grant needs grant_id and a 64-hex argv_hash', {});
+      }
+      // v1.3.12-beta.1: dispatch-side preflight of the execution-authorization model. The agent verifies the signature and
+      // the use ledger; the relay refuses a grant that is plainly for another task or another argv, by name, before any
+      // machine sees the task. This is a caller-bug check, not a second authorisation decision.
+      if (typeof rawGrant.task_id === 'string' && rawGrant.task_id !== '' && rawGrant.task_id !== taskId) {
+        throw new ProtocolError('GRANT_TASK_MISMATCH', 'the grant names another task_id', { grant_task_id: rawGrant.task_id, task_id: taskId });
+      }
+      if (grantArgvHash(commandArgv) !== String(rawGrant.argv_hash)) {
+        throw new ProtocolError('GRANT_ARGV_MISMATCH', 'the grant argv_hash does not match command_argv', { argv_hash: String(rawGrant.argv_hash), computed: grantArgvHash(commandArgv) });
+      }
+      if (rawGrant.expires_at !== undefined) {
+        const expiresAt = Date.parse(String(rawGrant.expires_at));
+        if (Number.isNaN(expiresAt)) throw new ProtocolError('BAD_REQUEST', 'grant.expires_at is not a timestamp', { expires_at: rawGrant.expires_at });
+        if (expiresAt <= this.nowMs()) throw new ProtocolError('GRANT_EXPIRED', 'the grant has already expired', { expires_at: rawGrant.expires_at });
+      }
+      if (this.revokedGrants.has(String(rawGrant.grant_id))) {
+        throw new ProtocolError('GRANT_REVOKED', 'the grant was revoked by the operator', { grant_id: String(rawGrant.grant_id) });
+      }
+      normalizedGrant = rawGrant;
+    }
+    const rawOperatorKey = input.operator_key ?? null;
+    let normalizedOperatorKey = null;
+    if (rawOperatorKey !== null) {
+      if (typeof rawOperatorKey !== 'object' || Array.isArray(rawOperatorKey)) throw new ProtocolError('BAD_REQUEST', 'operator_key must be an object', {});
+      if (typeof rawOperatorKey.key_id !== 'string' || typeof rawOperatorKey.public_key_pem !== 'string') {
+        throw new ProtocolError('BAD_REQUEST', 'operator_key needs key_id and public_key_pem', {});
+      }
+      normalizedOperatorKey = { key_id: rawOperatorKey.key_id, public_key_pem: rawOperatorKey.public_key_pem, created_at: rawOperatorKey.created_at ?? new Date(this.nowMs()).toISOString() };
+      if (this.operatorKeys.has(normalizedOperatorKey.key_id) === false) {
+        this.operatorKeys.set(normalizedOperatorKey.key_id, normalizedOperatorKey);
+        this._ledger({ type: 'operator.key.registered', key: normalizedOperatorKey });
+      }
+    }
     const rawReduceInputs = input.reduce_inputs === undefined || input.reduce_inputs === null ? [] : input.reduce_inputs;
     if (!Array.isArray(rawReduceInputs) || rawReduceInputs.length > 16) {
       throw new ProtocolError('BAD_REQUEST', 'reduce_inputs must be an array of at most 16 artifacts', { count: Array.isArray(rawReduceInputs) ? rawReduceInputs.length : null });
@@ -1782,7 +1944,15 @@ export class RabbitState {
        * v1.2.10: a reduce task names the map task it reduces and the artifacts it consumes. The artifact LIST travels with
        * the task (never inferred by the reducer), because "which shards this reduce covers" is the completeness contract.
        */
+      project_id: this.ensureProject(input.project_id ?? null),
       reduce_of: typeof input.reduce_of === 'string' && input.reduce_of !== '' ? input.reduce_of : null,
+      workspace: normalizedWorkspace,
+      grant: normalizedGrant,
+      grant_summary: normalizedGrant === null ? null : { grant_id: normalizedGrant.grant_id, argv_hash: normalizedGrant.argv_hash, key_id: normalizedGrant.signature?.key_id ?? null },
+      /** v1.3.10-beta.2: a signed maintenance request travels with the task; the relay carries it, the root runner verifies it. */
+      maintenance: normalizedMaintenance,
+      operator_key: normalizedOperatorKey,
+      maintenance_summary: normalizedMaintenance === null ? null : { request_id: normalizedMaintenance.request_id ?? null, action: normalizedMaintenance.action ?? null },
       reduce_inputs: normalizedReduceInputs,
       leases: new Map(),
       cancelled: false,
@@ -2043,6 +2213,8 @@ export class RabbitState {
       type: 'task.created',
       task: {
         task_id: task.task_id,
+        workspace: task.workspace ?? null,
+        project_id: task.project_id,
         mode: task.mode,
         command_argv: task.command_argv,
         cwd_rel: task.cwd_rel,
@@ -2067,6 +2239,8 @@ export class RabbitState {
             depends_on: Array.isArray(task.depends_on) ? task.depends_on : [],
             assignee: task.assignee ?? null,
             reduce_of: task.reduce_of ?? null,
+            maintenance_summary: task.maintenance_summary ?? null,
+            grant_summary: task.grant_summary ?? null,
             reduce_inputs: Array.isArray(task.reduce_inputs) ? task.reduce_inputs : [],
         origin_machine_id: task.origin_machine_id ?? null,
         p2p: task.p2p ?? null,
@@ -2074,6 +2248,11 @@ export class RabbitState {
       leases: [...task.leases.values()].map((l) => ({ ...l })),
     });
 
+    // v1.3.10-beta.13: a task belongs to a project, and the project room records the link as an event both clients see.
+    try {
+      this.projects.appendEvent({ projectId: task.project_id, type: 'task.linked', actor: { kind: 'operator', id: 'relay' }, payload: { task_id: taskId, mode: task.mode } });
+    } catch { /* the ledger already carries the task; the room event is additive */ }
+
     const refusedOnly = [...task.leases.values()].every((l) => l.state === 'refused');
     if (refusedOnly) {
       // §6.3 Step 0 territory: a task nobody may execute is still a valid, reportable task.
@@ -2181,6 +2360,10 @@ export class RabbitState {
       p2p: task.p2p ?? null,
       // v1.2.10: present only on a reduce task, so a normal offer stays byte-identical.
       ...(task.reduce_of !== null ? { reduce_of: task.reduce_of, reduce_inputs: task.reduce_inputs } : {}),
+      // v1.3.10-beta.2: the signed request and its operator key travel together; the agent pins the key on first sight.
+      ...(task.maintenance !== null && task.maintenance !== undefined ? { maintenance: task.maintenance, operator_key: task.operator_key } : {}),
+      ...(task.workspace !== null && task.workspace !== undefined ? { workspace: task.workspace } : {}),
+      ...(task.grant !== null && task.grant !== undefined ? { grant: task.grant } : {}),
       cwd_rel: task.cwd_rel,
       // Omitted when false, so a single-command offer for every existing caller stays byte-identical -- the
       // same reason `stages` above is conditional.
@@ -2201,6 +2384,27 @@ export class RabbitState {
     return event;
   }
 
+  /**
+   * Resolve the project a task belongs to. The implicit default project is created lazily, so existing callers keep working
+   * without naming one; an explicit unknown project is a refusal, not a new project.
+   */
+  ensureProject(projectId) {
+    const wanted = typeof projectId === 'string' && projectId !== '' ? projectId : this.defaultProjectId;
+    try {
+      this.projects.snapshot({ projectId: wanted });
+      return wanted;
+    } catch (error) {
+      if (error?.code !== 'PROJECT_NOT_FOUND') throw error;
+      if (wanted !== this.defaultProjectId) throw new ProtocolError('BAD_REQUEST', 'unknown project_id', { project_id: wanted });
+      this.projects.createProject({ projectId: this.defaultProjectId, name: 'default', createdBy: { kind: 'operator', id: 'relay', name: 'relay' } });
+      return wanted;
+    }
+  }
+
+  /** Snapshot helpers the project routes use; kept on state so the relay has one owner of the room. */
+  projectSnapshot(projectId) { return this.projects.snapshot({ projectId: this.ensureProject(projectId) }); }
+  projectEvents(projectId, options = {}) { return this.projects.events({ projectId: this.ensureProject(projectId), ...options }); }
+
   getTask(taskId) { return this.tasks.get(taskId) ?? null; }
 
   requireTask(taskId) {
@@ -2320,6 +2524,103 @@ export class RabbitState {
     return released;
   }
 
+  /** Stop one issued grant from being used. Idempotent: revoking twice is the same authorisation state. */
+  revokeGrant({ grantId, reason = null, actor = { kind: "operator", id: "operator" } }) {
+    if (typeof grantId !== "string" || grantId === "") throw new ProtocolError("BAD_REQUEST", "grant_id is required");
+    const existing = this.revokedGrants.get(grantId);
+    if (existing !== undefined) return { ok: true, already_revoked: true, revocation: { ...existing } };
+    const revocation = { grant_id: grantId, reason: typeof reason === "string" && reason !== "" ? reason : null, revoked_at: this.nowIso(), revoked_by: actor };
+    this.revokedGrants.set(grantId, revocation);
+    this._ledger({ type: "grant.revoked", grant_id: grantId, reason: revocation.reason, revoked_by: actor });
+    return { ok: true, already_revoked: false, revocation: { ...revocation } };
+  }
+
+  /** Audit view: every task that carried a grant, plus every revocation. Operator credential only. */
+  grantedTasks() {
+    const tasks = [];
+    for (const task of this.tasks.values()) {
+      if (task.grant_summary === null || task.grant_summary === undefined) continue;
+      tasks.push({ task_id: task.task_id, grant_id: task.grant_summary.grant_id, argv_hash: task.grant_summary.argv_hash, key_id: task.grant_summary.key_id, mode: task.mode, created_at: rfc3339(task.created_at_ms) });
+    }
+    return { tasks, revoked: [...this.revokedGrants.values()].map((entry) => ({ ...entry })) };
+  }
+
+  /** Register a content-addressed artifact against a project (idempotent by sha256). */
+  registerArtifact({ projectId, sha256, bytes, kind = "artifact", sourceTaskId = null, actor = null }) {
+    if (!/^[0-9a-f]{64}$/.test(String(sha256))) throw new ProtocolError("BAD_REQUEST", "artifact sha256 must be 64 hex", {});
+    const wanted = this.ensureProject(projectId);
+    const existing = this.artifacts.get(sha256);
+    if (existing !== undefined && existing.project_id === wanted) return { ok: true, artifact: { ...existing }, already: true };
+    const artifact = { project_id: wanted, sha256: String(sha256), bytes: Number.isInteger(bytes) && bytes >= 0 ? bytes : null, kind: String(kind), source_task_id: sourceTaskId, created_at: this.nowIso(), actor };
+    this.artifacts.set(sha256, artifact);
+    try { this.projects.appendEvent({ projectId: wanted, type: "artifact.registered", actor: actor ?? { kind: "operator", id: "relay" }, payload: { sha256: artifact.sha256, bytes: artifact.bytes, kind: artifact.kind, source_task_id: sourceTaskId } }); } catch { /* history */ }
+    return { ok: true, artifact: { ...artifact }, already: false };
+  }
+
+  listArtifacts({ projectId }) {
+    const wanted = this.ensureProject(projectId);
+    return [...this.artifacts.values()].filter((artifact) => artifact.project_id === wanted).sort((a, b) => (a.created_at < b.created_at ? 1 : -1)).map((artifact) => ({ ...artifact }));
+  }
+
+  /** The project board: every task attributed to this project, with the scheduler's own status. */
+  projectBoard({ projectId }) {
+    const wanted = this.ensureProject(projectId);
+    const tasks = [...this.tasks.values()].filter((task) => task.project_id === wanted).map((task) => {
+      const summary = this.taskSummary(task);
+      return { task_id: summary.task_id, status: summary.status, mode: summary.mode, created_at: summary.created_at, leases: summary.leases, lease_states: summary.lease_states, result_count: [...this.results.values()].filter((record) => record?.envelope?.task_id === task.task_id).length };
+    });
+    const counts = {};
+    for (const task of tasks) counts[task.status] = (counts[task.status] ?? 0) + 1;
+    return { project_id: wanted, tasks, counts, generated_at: this.nowIso() };
+  }
+
+  /** Append a decision to a project. Decisions are records; there is no edit or delete. */
+  addDecision({ projectId, title, text = null, actor = null, refs = {}, kind = "decision" }) {
+    const wanted = this.ensureProject(projectId);
+    if (typeof title !== "string" || title.trim() === "") throw new ProtocolError("BAD_REQUEST", "decision title is required", {});
+    const list = this.decisions.get(wanted) ?? [];
+    const index = list.length + 1;
+    const decision = {
+      decision_id: wanted + "-d" + String(index).padStart(4, "0"),
+      project_id: wanted, title: title.trim().slice(0, 200), text: typeof text === "string" ? text.slice(0, 4000) : null,
+      kind: String(kind), refs: refs !== null && typeof refs === "object" ? { ...refs } : {},
+      actor, created_at: this.nowIso(),
+    };
+    list.push(decision);
+    this.decisions.set(wanted, list);
+    try { this.projects.appendEvent({ projectId: wanted, type: "decision.recorded", actor: actor ?? { kind: "operator", id: "relay" }, payload: { decision_id: decision.decision_id, title: decision.title, kind: decision.kind } }); } catch { /* history */ }
+    return { ok: true, decision: { ...decision } };
+  }
+
+  listDecisions({ projectId }) {
+    const wanted = this.ensureProject(projectId);
+    return (this.decisions.get(wanted) ?? []).map((decision) => ({ ...decision, refs: { ...decision.refs } }));
+  }
+
+  /** A small versioned document per project (64 KiB cap): shared context that is not a log. */
+  setProjectMemory({ projectId, text, actor = null }) {
+    const wanted = this.ensureProject(projectId);
+    if (typeof text !== "string") throw new ProtocolError("BAD_REQUEST", "memory text must be a string", {});
+    if (Buffer.byteLength(text, "utf8") > 64 * 1024) throw new ProtocolError("PROJECT_MEMORY_TOO_LARGE", "project memory is limited to 64 KiB", { bytes: Buffer.byteLength(text, "utf8") });
+    const previous = this.projectMemory.get(wanted);
+    const doc = { project_id: wanted, text, version: (previous?.version ?? 0) + 1, updated_at: this.nowIso(), actor };
+    this.projectMemory.set(wanted, doc);
+    try { this.projects.appendEvent({ projectId: wanted, type: "memory.updated", actor: actor ?? { kind: "operator", id: "relay" }, payload: { version: doc.version, bytes: Buffer.byteLength(text, "utf8") } }); } catch { /* history */ }
+    return { ok: true, document: { ...doc } };
+  }
+
+  getProjectMemory({ projectId }) {
+    const wanted = this.ensureProject(projectId);
+    const doc = this.projectMemory.get(wanted);
+    return doc === undefined ? { project_id: wanted, text: "", version: 0, updated_at: null, actor: null } : { ...doc };
+  }
+
+  /** Subscribe to every project event. Returns an unsubscribe function. */
+  onProjectEvent(listener) {
+    this.projectSubscribers.add(listener);
+    return () => { this.projectSubscribers.delete(listener); };
+  }
+
   taskSummary(task) {
     return {
       task_id: task.task_id,
@@ -2337,8 +2638,14 @@ export class RabbitState {
        * Before this, GET /v1/tasks carried no status at all, so a board classified a waiting task as "ready" (its dependencies
        * map empty) and a released task as "waiting" forever. The board must read the scheduler's own words or it is decoration.
        */
+      project_id: task.project_id ?? null,
       reduce_of: task.reduce_of ?? null,
       reduce_inputs: Array.isArray(task.reduce_inputs) ? task.reduce_inputs : [],
+      maintenance_request_id: task.maintenance_summary?.request_id ?? null,
+      workspace: task.workspace === null || task.workspace === undefined ? null : { ...task.workspace },
+    grant_id: task.grant_summary?.grant_id ?? null,
+    argv_hash: task.grant_summary?.argv_hash ?? null,
+    grant_key_id: task.grant_summary?.key_id ?? null,
       status: (() => {
         if (task.cancelled === true) return 'cancelled';
         const leases = [...task.leases.values()];